Package microsim.statistics.regression

Class RegressionUtils

java.lang.Object
microsim.statistics.regression.RegressionUtils
public class RegressionUtils extends Object

  • Constructor Summary

    Constructors
    Constructor
    Description
    RegressionUtils()
     

  • Method Summary

    Modifier and Type
    Method
    Description
    static @NonNull MultiKeyCoefficientMap
    bootstrap(@NonNull MultiKeyCoefficientMap map)
    Method to bootstrap regression covariates.
    static @NonNull MultiKeyCoefficientMap
    bootstrap(@NonNull MultiKeyCoefficientMap coefficients, @NonNull MultiKeyCoefficientMap covarianceMatrix)
    Method to bootstrap regression covariates.
    static <T> @NonNull Map<T,MultiKeyCoefficientMap>
    bootstrapMultinomialRegression(@NonNull Map<T,MultiKeyCoefficientMap> eventRegressionCoefficientMap, @NonNull MultiKeyCoefficientMap covarianceMatrix, @NonNull Class<T> enumType)
    Method to bootstrap multinomial regression covariates.
    static boolean
    event(double prob)
    rnd defaults to SimulationEngine.getRnd().
    static boolean
    event(double prob, @NonNull Random rnd)
    Checks if a randomly generated value belongs to the semi-open [0, prob) interval.
    static <T> T
    event(@NonNull Class<T> eventClass, double @NonNull [] prob)
    rnd defaults to SimulationEngine.getRnd(), events are passed as eventClass.getEnumConstants().
    static <T> T
    event(@NonNull Class<T> eventClass, double @NonNull [] weight, boolean checkWeightSum)
    rnd defaults to SimulationEngine.getRnd(), events are passed as eventClass.getEnumConstants().
    static <T> T
    event(@NonNull AbstractList<T> events, @NonNull Random rnd)
    This allows events with types that implement the list interface.
    static <T> T
    event(@NonNull Map<T,Double> map)
    rnd defaults to SimulationEngine.getRnd().
    static <T> T
    event(@NonNull Map<T,Double> map, boolean checkWeightSum)
    rnd defaults to SimulationEngine.getRnd().
    static <T> T
    event(@NonNull Map<T,Double> map, @NonNull Random rnd)
    checkWeightSum defaults to {true}.
    static <T> T
    event(@NonNull Map<T,Double> map, @NonNull Random rnd, boolean checkWeightSum)
    Transforms a map into two arrays to boost code performance and passes them further.
    static <T> T
    event(T @NonNull [] events, double @NonNull [] prob)
    rnd defaults to SimulationEngine.getRnd().
    static <T> T
    event(T @NonNull [] events, double @NonNull [] weight, boolean checkWeightSum)
    rnd defaults to SimulationEngine.getRnd().
    static <T> T
    event(T @NonNull [] events, double @NonNull [] prob, @NonNull Random rnd)
    checkWeightSum defaults to true.
    static <T> T
    event(T @NonNull [] events, double @NonNull [] weights, @NonNull Random rnd, boolean checkWeightSum)
    Returns an event determined randomly from a set of events and weights.
    static <T> T
    event(T @NonNull [] events, @NonNull Random rnd)
    For sampling an event where all events in the sample space have equal probability.
    static double
    eventPiecewiseConstant(double @NonNull [] events, double @NonNull [] weights, @NonNull Random rnd, boolean checkWeightSum)
    Performs a linear interpolation on the (numerical) event domain of a piecewise constant probability distribution.
    static double
    eventPiecewiseConstant(double @NonNull [] events, double @NonNull [] prob, Random rnd)
    checkSumWeights defaults to true.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Constructor Details

    • RegressionUtils

      public RegressionUtils()

  • Method Details

    • event

      @NonNull public static <T> T event(@NonNull @NonNull Class<T> eventClass, double @NonNull [] prob)
      rnd defaults to SimulationEngine.getRnd(), events are passed as eventClass.getEnumConstants().
      See Also:

    • event

      @NonNull public static <T> T event(@NonNull @NonNull Class<T> eventClass, double @NonNull [] weight, boolean checkWeightSum)
      rnd defaults to SimulationEngine.getRnd(), events are passed as eventClass.getEnumConstants().
      See Also:

    • event

      @NonNull public static <T> T event(T @NonNull [] events, double @NonNull [] prob)
      rnd defaults to SimulationEngine.getRnd().
      See Also:

    • event

      @NonNull public static <T> T event(T @NonNull [] events, double @NonNull [] weight, boolean checkWeightSum)
      rnd defaults to SimulationEngine.getRnd().
      See Also:

    • event

      @NonNull public static <T> T event(@NonNull @NonNull Map<T,Double> map)
      rnd defaults to SimulationEngine.getRnd().
      See Also:

    • event

      @NonNull public static <T> T event(@NonNull @NonNull Map<T,Double> map, boolean checkWeightSum)
      rnd defaults to SimulationEngine.getRnd().
      See Also:

    • event

      @NonNull public static <T> T event(T @NonNull [] events, double @NonNull [] prob, @NonNull @NonNull Random rnd)
      checkWeightSum defaults to true.
      See Also:

    • event

      @NonNull public static <T> T event(T @NonNull [] events, double @NonNull [] weights, @NonNull @NonNull Random rnd, boolean checkWeightSum)
      Returns an event determined randomly from a set of events and weights. Note that these weights do not necessarily have to sum to 1, as the method can convert the weights into probabilities by calculating their relative proportions. If the user desires that an exception is thrown if the weights do not sum to 1, please set checkProbSum to true.
      Parameters:
      events - An array of events of type T.
      weights - An array of doubles from which the probabilities are calculated (by dividing the weights by the sum of weights).
      rnd - A random number generator.
      checkWeightSum - A boolean toggle, which if true means that the method will throw an exception if the weights do not add to 1. If false, the method will calculate the probabilities associated to the weights and use these in the random sampling of the event.
      Returns:
      a randomly chosen event.

    • event

      public static boolean event(double prob)
      rnd defaults to SimulationEngine.getRnd().
      See Also:

    • event

      public static boolean event(double prob, @NonNull @NonNull Random rnd)
      Checks if a randomly generated value belongs to the semi-open [0, prob) interval.
      Parameters:
      prob - A probability value that must be in [0, 1] range.
      rnd - A random number generator.
      Returns:
      a boolean that shows if a random boolean is in the [0, prob) interval.

    • event

      @NonNull public static <T> T event(@NonNull @NonNull Map<T,Double> map, @NonNull @NonNull Random rnd)
      checkWeightSum defaults to {true}.
      See Also:

    • event

      @NonNull public static <T> T event(@NonNull @NonNull Map<T,Double> map, @NonNull @NonNull Random rnd, boolean checkWeightSum)
      Transforms a map into two arrays to boost code performance and passes them further.
      See Also:

    • event

      @NonNull public static <T> T event(T @NonNull [] events, @NonNull @NonNull Random rnd)
      For sampling an event where all events in the sample space have equal probability. The probability for each event = 1 / size of sample space.
      Parameters:
      events - The possible events in the sample space.
      rnd - A random generator.
      Returns:
      the event chosen.

    • event

      @NonNull public static <T> T event(@NonNull @NonNull AbstractList<T> events, @NonNull @NonNull Random rnd)
      This allows events with types that implement the list interface.
      See Also:

    • eventPiecewiseConstant

      public static double eventPiecewiseConstant(double @NonNull [] events, double @NonNull [] prob, Random rnd)
      checkSumWeights defaults to true.
      See Also:

    • eventPiecewiseConstant

      public static double eventPiecewiseConstant(double @NonNull [] events, double @NonNull [] weights, @NonNull @NonNull Random rnd, boolean checkWeightSum)
      Performs a linear interpolation on the (numerical) event domain of a piecewise constant probability distribution. The effective expression is derived from (toss - (x - prob[i-1])) / (x - (x - prob[i-1])), where x is the cumulative probability at the start of events[i] and (x - prob[i-1]) is the cumulative probability at the start of events[i-1].
      Parameters:
      events - The discrete set of cuts characterising the domain of a piecewise constant probability distribution.
      weights - The discrete set of probabilities characterising a piecewise constant probability distribution.
      rnd - The random number generator.
      checkWeightSum - If true, will check weights elements sum to 1, otherwise they will be normalised (by dividing each element by the sum of the elements).
      Returns:
      The value of the event drawn from a compact domain

    • bootstrap

      @NonNull public static @NonNull MultiKeyCoefficientMap bootstrap(@NonNull @NonNull MultiKeyCoefficientMap map)
      Method to bootstrap regression covariates. This method creates a new set of regression estimates by sampling from a multivariate normal distribution with expected values (means) equal to the 'coefficients' parameter and a covariance matrix as specified.
      Parameters:
      map - A MultiKeyCoefficientMap that contains both regression coefficients and a corresponding covariance matrix. This map is required to only have one key entry in the MultiKeyCoefficientMap map's MultiKey with a heading 'REGRESSOR'. The map must also contain a value column with the heading 'COEFFICIENT' and an additional value column for each regressor (covariate), in order to represent the (square, symmetric, positive semi-definite) covariance matrix.
      Returns:
      a MultiKeyCoefficientMap containing a new set of bootstrapped regression coefficients.

    • bootstrap

      @NonNull public static @NonNull MultiKeyCoefficientMap bootstrap(@NonNull @NonNull MultiKeyCoefficientMap coefficients, @NonNull @NonNull MultiKeyCoefficientMap covarianceMatrix)
      Method to bootstrap regression covariates. This method creates a new set of regression estimates by sampling from a multivariate normal distribution with expected values (means) equal to the 'coefficients' parameter and a covariance matrix as specified.
      Parameters:
      coefficients - A MultiKeyCoefficientMap that contains a set of regression coefficients. The 'coefficients' map is required to only have one key entry in each of the MultiKeyCoefficientMap map's MultiKeys, with the entries being the name of the regression covariates. There must be only one values column containing the regression coefficients for each covariate (regressor).
      covarianceMatrix - A MultiKeyCoefficientMap that provides the covariance matrix of a regression's coefficients. The covarianceMatrix map is required to only have one key entry in each of the MultiKeyCoefficientMap map's MultiKeys, with each entry corresponding to the name of a regression covariate. The values must contain a name key corresponding to each of the covariates, though the ordering of the values (columns) need not match the MultiKey (row) ordering.
      Returns:
      a MultiKeyCoefficientMap of new regression coefficients that is bootstrapped from the input estimates map.

    • bootstrapMultinomialRegression

      @NonNull public static <T> @NonNull Map<T,MultiKeyCoefficientMap> bootstrapMultinomialRegression(@NonNull @NonNull Map<T,MultiKeyCoefficientMap> eventRegressionCoefficientMap, @NonNull @NonNull MultiKeyCoefficientMap covarianceMatrix, @NonNull @NonNull Class<T> enumType)
      Method to bootstrap multinomial regression covariates. This method creates a new map of sets of regression coefficients by sampling from a multivariate normal distribution with expected values (means) equal to the regression coefficients contained in the 'coefficientOutcomeMap' and a covariance matrix as specified.
      Type Parameters:
      T - The event (outcome) of a multinomial regression.
      Parameters:
      eventRegressionCoefficientMap - A map whose keys are the possible events (outcomes) of type T of the multinomial regression, and whose values are MultiKeyCoefficientMaps each containing a set of regression coefficients corresponding to its event (the key). Each MultiKeyCoefficientMap of regression coefficients is used as expected value of a multivariate normal distribution, which is sampled in order to produce a new set of regression coefficients. The MultiKeyCoefficientMaps are required to only have one key entry, with the entries being the name of the regression covariates. There must be only one values column in the MultiKeyCoefficientMaps, containing the regression coefficients for each covariate.
      covarianceMatrix - A MultiKeyCoefficientMap that provides the covariance matrix of a regression's coefficients. The covarianceMatrix map is required to only have one key entry in each of the MultiKeyCoefficientMap map's MultiKeys, with each entry corresponding to a string with the structure [event name]_[covariate name]. So, for example, if the set of events of T are LowEducation and HighEducation, and the regression covariates declared in coefficientOutcomeMap are 'age' and 'gender', then the following MultiKey entries must exist: "LowEducation_age", "LowEducation_gender", "HighEducation_age", "HighEducation_gender", such that the name of the event is a prefix, the character "_" is the 'regular expression' and the name of the regression covariate is the suffix. This prefix/suffix ordering must be preserved in order to avoid confusion between the name of events and covariates, however the order in which the MultiKeys are specified does not matter. The values of the MultiKeyCoefficientMap must contain a name key that corresponds to each MultiKey key entry (to ensure labelling of rows and columns match), though the ordering of the values (columns) need not match the MultiKey (row) ordering.
      Returns:
      a Map whose keys are the possible events (outcomes) of type T of the multinomial regression and whose values are MultiKeyCoefficientMap with new regression coefficients (one set of coefficients for each event).