Stats Package Core

Entries on this page:

Distributions

Abstract classes for probability distributions e.g., Multivariate Bernoulli. These are also the base for sampling proposals..

class DistributionConfigs(*, debug=False, verbose=False, output_dir='./_PYOED_RESULTS_', name=None, random_seed=None)

Bases: PyOEDConfigs

Configurations class for the Distribution abstract base class. This class inherits functionality from PyOEDConfigs and only adds new class-level variables which can be updated as needed.

See PyOEDConfigs for more details on the functionality of this class along with a few additional fields. Otherwise DistributionConfigs provides the following fields.

Parameters:

• verbose (bool) – a boolean flag to control verbosity of the object.

• debug (bool) – a boolean flag that enables adding extra functionality in a debug mode

• output_dir (str | Path) – the base directory where the output files will be saved.

• name (str | None) – name of the distribution

• random_seed (int | None) – random seed used for pseudo random number generation

name: str | None

random_seed: int | None

__init__(*, debug=False, verbose=False, output_dir='./_PYOED_RESULTS_', name=None, random_seed=None)

class Distribution(configs=None)

Bases: PyOEDObject, RandomNumberGenerationMixin

Base class for probability distributions (and sampling proposals).

Note

Each class derived from Distribution should have its own __init__ method in which the constructor just calls super().__init__(configs=configs) and then add any additional initialization as needed. The validation self.validate_configurations() is carried out at the initialization time by the base class Distribution.

Parameters:

configs (dict | DistributionConfigs | None) – (optional) configurations for the model

__init__(configs=None)

Initialize the random number generator

validate_configurations(configs, raise_for_invalid=True)

Each distribution SHOULD implement it’s own function that validates its own configurations. If the validation is self contained (validates all configuations), then that’s it. However, one can just validate the configurations of of the immediate class and call super to validate configurations associated with the parent class.

If one does not wish to do any validation (we strongly advise against that), simply add the signature of this function to the model class.

Note

The purpose of this method is to make sure that the settings in the configurations object self._CONFIGURATIONS are of the right type/values and are conformable with each other. This function is called upon instantiation of the object, and each time a configuration value is updated. Thus, this function need to be inexpensive and should not do heavy computations.

Parameters:

configs (dict | DistributionConfigs) – configurations to validate. If a DistributionConfigs object is passed, validation is performed on the entire set of configurations. However, if a dictionary is passed, validation is performed only on the configurations corresponding to the keys in the dictionary.

update_configurations(**kwargs)

Take any set of keyword arguments, and lookup each in the configurations, and update as nessesary/possible/valid

Raises:

TypeError – if any of the passed keys in kwargs is invalid/unrecognized

Remarks:

• Generally, we don’t want actual implementations in abstract classes, however, this one is provided as good guidance. Derived classes can rewrite it and/or provide additional updates.

uniform_random_sample(sample_size=1)

Generate sample(s) from the created distribution with parameter setup to yield equal probabilities of all points in the distribution support. This is usefule for generating uninformative (completely blind) random samples from a given distribution. For example, a Bernoulli distribution can provide samples where the probability of sucess is set to 0.5.

abstractmethod sample(sample_size=1)

Generate sample(s) from the created distribution.

Parameters:

sample_size (int) – number of sample points to draw.

Returns:

a list of sample points from the underlying distribution, where each entry is a single sample point.

Return type:

list

abstract property size

Return the dimension/size of the underlying probability space.

Return type:

int

parameter_manager(parameter)

Creat an return a context manager that enables updating the parameter to the passed value, execute needed code and then reset the parameter to the original value.

Assuming obj is this object, and val is the parameter value one wants to run the method obj.run_code(), the following code can be used

with obj.parameter_manager(val) as mngr:
    mngr.run_code()

Returns:

a reference to self that enables calling any function under self and then automatically, the parameter is reset.

Sampling

Base classes for sampling algorithms; e.g., MCMC samplers.

class ProposalConfigs(*, debug=False, verbose=False, output_dir='./_PYOED_RESULTS_', name=None, random_seed=None)

Bases: DistributionConfigs

Configurations for the Proposal class. These do not add any additional keys to the base configurations of

Parameters:

• verbose (bool) – a boolean flag to control verbosity of the object.

• debug (bool) – a boolean flag that enables adding extra functionality in a debug mode

• output_dir (str | Path) – the base directory where the output files will be saved.

• name (str | None) – name of the distribution

• random_seed (int | None) – random seed used for pseudo random number generation

__init__(*, debug=False, verbose=False, output_dir='./_PYOED_RESULTS_', name=None, random_seed=None)

class Proposal(configs=None)

Bases: Distribution

Base class for Proposal (algorithms to propose samples which can be accepted or rejected by the MH step in MCMC). An example is a Gaussian proposal. Derived from Distribution, hence, one should be able to use it as a distribution.

Parameters:

configs (dict | ProposalConfigs | None) – an object that holds the proposal configurations.

__init__(configs=None)

Initialize the random number generator

validate_configurations(configs, raise_for_invalid=True)

Each distribution SHOULD implement it’s own function that validates its own configurations. If the validation is self contained (validates all configuations), then that’s it. However, one can just validate the configurations of of the immediate class and call super to validate configurations associated with the parent class.

If one does not wish to do any validation (we strongly advise against that), simply add the signature of this function to the model class.

Note

The purpose of this method is to make sure that the settings in the configurations object self._CONFIGURATIONS are of the right type/values and are conformable with each other. This function is called upon instantiation of the object, and each time a configuration value is updated. Thus, this function need to be inexpensive and should not do heavy computations.

Parameters:

configs (dict | ProposalConfigs) – configurations to validate. If a DistributionConfigs object is passed, validation is performed on the entire set of configurations. However, if a dictionary is passed, validation is performed only on the configurations corresponding to the keys in the dictionary.

class SamplerConfigs(*, debug=False, verbose=False, output_dir='./_PYOED_RESULTS_', random_seed=None)

Bases: PyOEDConfigs

Base configurations for the Sampler class.

Parameters:

• verbose (bool) – a boolean flag to control verbosity of the object.

• debug (bool) – a boolean flag that enables adding extra functionality in a debug mode

• output_dir (str | Path) – the base directory where the output files will be saved.

• random_seed (None | int) – random seed used when the object is initiated to keep track of random samples. This is useful for reproductivity. If None, random seed follows numpy.random.seed rules.

random_seed: None | int

__init__(*, debug=False, verbose=False, output_dir='./_PYOED_RESULTS_', random_seed=None)

class Sampler(configs=None)

Bases: PyOEDObject, RandomNumberGenerationMixin

Base class for Samplers (algorithms to generate samples from a predefined distribution). An example is an inverse CDF sampler, MCMC sampler, etc.

Parameters:

configs (dict | SamplerConfigs | None) – an object that holds the proposal configurations.

__init__(configs=None)

Initialize the random number generator

validate_configurations(configs, raise_for_invalid=True)

Each Sampler may implement it’s own function that validates its own configurations. If the validation is self contained (validates all configuations), then that’s it. However, one can just validate the configurations of of the immediate class and call super to validate configurations associated with the parent class.

If one does not wish to do any validation on local configurations, return super().validate_configurations(configs, raise_for_invalid) under this method. If one does not want to do any validation at all, simply omit this method.

Note

The purpose of this method is to make sure that the settings in the configurations object are of the right type/values and are conformable with each other. This function is called upon instantiation of the object, and each time a configuration value is updated. Thus, this function ought to be inexpensive and should not do heavy computations.

Parameters:

configs (dict | SamplerConfigs) – configurations to validate.

Raises:

• PyOEDConfigsValidationError – if the configurations are invalid and raise_for_invalid is set to True.

• AttributeError – if any (or a group) of the configurations does not exist in the model configurations PyOEDConfigs.

update_configurations(**kwargs)

Take any set of keyword arguments, and lookup each in the configurations, and update as nessesary/possible/valid

Raises:

TypeError is raised if any of the passed keys in kwargs is invalid/unrecognized

Remarks:

Generally, we don’t want actual implementations in abstract classes, however, this one is provided as good guidance. Derived classes can rewrite it.

abstractmethod sample(sample_size)

Generate samples from the created sampler.

Parameters:

sample_size (int) – number of sample points to draw.

Returns:

a list of sample points from the underlying distribution, where each entry is a single sample point.

Return type:

list

abstract property size: int

Return the dimension/size of the underlying probability space.

Return type:

int