Package microsim.statistics.regression

Class RegressionUtils

java.lang.Object

microsim.statistics.regression.RegressionUtils

public class RegressionUtils
extends java.lang.Object

Constructor Summary

Constructors

Constructor	Description
RegressionUtils()

Method Summary

Modifier and Type	Method	Description
static <T> java.util.Map<T,MultiKeyCoefficientMap>	boostrapMultinomialRegression(java.util.Map<T,MultiKeyCoefficientMap> eventRegressionCoefficientMap, MultiKeyCoefficientMap covarianceMatrix, java.lang.Class<T> enumType)	Deprecated. As of release 4.0.7 because of typo in method name, replaced by #bootstrapMultinomialRegression(Map eventRegressionCoefficientMap, MultiKeyCoefficientMap covarianceMatrix, Class enumType)
static MultiKeyCoefficientMap	bootstrap(MultiKeyCoefficientMap map)	Method to bootstrap regression covariates.
static MultiKeyCoefficientMap	bootstrap(MultiKeyCoefficientMap coefficients, MultiKeyCoefficientMap covarianceMatrix)	Method to bootstrap regression covariates.
static <T> java.util.Map<T,MultiKeyCoefficientMap>	bootstrapMultinomialRegression(java.util.Map<T,MultiKeyCoefficientMap> eventRegressionCoefficientMap, MultiKeyCoefficientMap covarianceMatrix, java.lang.Class<T> enumType)	Method to bootstrap multinomial regression covariates.
static boolean	event(double prob)
static boolean	event(double prob, java.util.Random rnd)
static <T> T	event(java.lang.Class<T> eventClass, double[] prob)
static <T> T	event(java.lang.Class<T> eventClass, double[] weight, boolean checkWeightSum)
static <T> T	event(java.util.AbstractList<T> events, java.util.Random rnd)	For sampling an event where all events in the sample space have equal probability.
static <T> T	event(java.util.Map<T,java.lang.Double> map)
static <T> T	event(java.util.Map<T,java.lang.Double> map, boolean checkWeightSum)
static <T> T	event(java.util.Map<T,java.lang.Double> map, java.util.Random rnd)	Although this method is easy to use with Maps with events as the keys and probabilities as the values, it will be very slow to call it in a loop, as the events[] and prob[] need to be extracted each time this method is called.
static <T> T	event(java.util.Map<T,java.lang.Double> map, java.util.Random rnd, boolean checkWeightSum)	Useful for sampling without replacement whenever the checkWeightSum flag is set to false, as new probabilities are calculated each time this method is called.
static <T> T	event(T[] events, double[] prob)	You must provide a vector of events (any type of object) and relative weights which sum must be equal to 1.0.
static <T> T	event(T[] events, double[] weight, boolean checkWeightSum)
static <T> T	event(T[] events, double[] prob, java.util.Random rnd)
static <T> T	event(T[] events, double[] weights, java.util.Random rnd, boolean checkWeightSum)	Returns an event determined randomly from a set of events and weights.
static <T> T	event(T[] events, java.util.Random rnd)	For sampling an event where all events in the sample space have equal probability.
static double	eventPiecewiseConstant(double[] events, double[] prob, java.util.Random rnd)	Performs a linear interpolation on the (numerical) event domain of a piecewise constant probability distribution
static double	eventPiecewiseConstant(double[] events, double[] weights, java.util.Random rnd, boolean checkSumWeights)	Performs a linear interpolation on the (numerical) event domain of a piecewise constant probability distribution

Methods inherited from class java.lang.Object

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

Constructor Detail

RegressionUtils

public RegressionUtils()

Method Detail

event

public static <T> T event(java.lang.Class<T> eventClass,
                          double[] prob)

event

public static <T> T event(java.lang.Class<T> eventClass,
                          double[] weight,
                          boolean checkWeightSum)

event

public static <T> T event(T[] events,
                          double[] prob)

You must provide a vector of events (any type of object) and relative weights which sum must be equal to 1.0. The function toss a random double number and search in witch probability range the sampled number is within to select the corresponding event.

Parameters:

events -

prob -

Returns:

event

public static <T> T event(T[] events,
                          double[] weight,
                          boolean checkWeightSum)

event

public static <T> T event(java.util.Map<T,java.lang.Double> map)

event

public static <T> T event(java.util.Map<T,java.lang.Double> map,
                          boolean checkWeightSum)

event

public static <T> T event(T[] events,
                          double[] prob,
                          java.util.Random rnd)

event

public static <T> T event(T[] events,
                          double[] weights,
                          java.util.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 - - Random number generator

checkWeightSum - - 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:

- the randomly chosen event

event

public static boolean event(double prob)

event

public static boolean event(double prob,
                            java.util.Random rnd)

event

public static <T> T event(java.util.Map<T,java.lang.Double> map,
                          java.util.Random rnd)

Although this method is easy to use with Maps with events as the keys and probabilities as the values, it will be very slow to call it in a loop, as the events[] and prob[] need to be extracted each time this method is called. Better to use the other method (event(T[], Double[]) and do the extracting of the map outside of the loop! If you want to do sampling without replacement, then you should use the event(Map map, Random rnd, boolean checkWeightSum) method instead, setting checkWeightSum to false

Parameters:

map -

rnd -

Returns:

the event chosen

event

public static <T> T event(java.util.Map<T,java.lang.Double> map,
                          java.util.Random rnd,
                          boolean checkWeightSum)

Useful for sampling without replacement whenever the checkWeightSum flag is set to false, as new probabilities are calculated each time this method is called. If checkWeightSum flag is set to true, which signifies that the map's values are weights that sum to 1, this method will be comparatively slower to call in a loop compared to other available methods, as the events[] and prob[] need to be extracted each time this method is called. Better to use the other method (event(T[], Double[]) and do the extracting of the map outside of the loop!

Parameters:

map - - contains events as keys and weights as values. These weights will be normalised to derive probabilities.

rnd -

Returns:

the event chosen

event

public static <T> T event(T[] events,
                          java.util.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 -

Returns:

the event chosen

event

public static <T> T event(java.util.AbstractList<T> events,
                          java.util.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. This allows events with types that implement the list interface.

Parameters:

events - - the possible events in the sample space

rnd -

Returns:

the event chosen

eventPiecewiseConstant

public static double eventPiecewiseConstant(double[] events,
                                            double[] prob,
                                            java.util.Random rnd)

Performs a linear interpolation on the (numerical) event domain of a piecewise constant probability distribution

Parameters:

events - : The discrete set of cuts characterising the domain of a piecewise constant probability distribution

prob - : The discrete set of probabilities characterising a piecewise constant probability distribution

rnd - : The random number generator

Returns:

: The value of the event drawn from a compact domain

eventPiecewiseConstant

public static double eventPiecewiseConstant(double[] events,
                                            double[] weights,
                                            java.util.Random rnd,
                                            boolean checkSumWeights)

Performs a linear interpolation on the (numerical) event domain of a piecewise constant probability distribution

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

checkSumWeights - : 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

public static MultiKeyCoefficientMap bootstrap(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. map is required to only have one key entry in the MultiKeyCoefficientMap map's MultiKey with a heading 'REGRESSOR'. 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

public static MultiKeyCoefficientMap bootstrap(MultiKeyCoefficientMap coefficients,
                                               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

public static <T> java.util.Map<T,MultiKeyCoefficientMap> bootstrapMultinomialRegression(java.util.Map<T,MultiKeyCoefficientMap> eventRegressionCoefficientMap,
                                                                                               MultiKeyCoefficientMap covarianceMatrix,
                                                                                               java.lang.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 sring 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).

boostrapMultinomialRegression

@Deprecated
public static <T> java.util.Map<T,MultiKeyCoefficientMap> boostrapMultinomialRegression(java.util.Map<T,MultiKeyCoefficientMap> eventRegressionCoefficientMap,
                                                                                              MultiKeyCoefficientMap covarianceMatrix,
                                                                                              java.lang.Class<T> enumType)

Deprecated.

As of release 4.0.7 because of typo in method name, replaced by #bootstrapMultinomialRegression(Map eventRegressionCoefficientMap, MultiKeyCoefficientMap covarianceMatrix, Class enumType)