samplers

This module contains various classes that can be used for specifying different types of samplers. These different samplers implement basic sampling techniques including Full Factorial sampling, Latin Hypercube sampling, and Monte Carlo sampling.

class ema_workbench.em_framework.samplers.AbstractSampler

Abstract base class from which different samplers can be derived.

In the simplest cases, only the sample method needs to be overwritten. generate_designs` is the only method called by the ensemble class. The other methods are used internally to generate the designs.

generate_designs(parameters, nr_samples)

external interface to sampler. Returns the computational experiments over the specified parameters, for the given number of samples for each parameter.

Parameters:
  • parameters (list) – a list of parameters for which to generate the experimental designs
  • nr_samples (int) – the number of samples to draw for each parameter
Returns:

  • generator – a generator object that yields the designs resulting from combining the parameters
  • int – the number of experimental designs

generate_samples(parameters, size)

The main method of :class: ~sampler.Sampler and its children. This will call the sample method for each of the parameters and return the resulting designs.

Parameters:
  • parameters (collection) – a collection of Parameterparamertainty and Categoricalparamertainty instances.
  • size (int) – the number of samples to generate.
Returns:

dict with the paramertainty.name as key, and the sample as value

Return type:

dict

sample(distribution, params, size)

method for sampling a number of samples from a particular distribution. The various samplers differ with respect to their implementation of this method.

Parameters:
  • distribution ({'uniform', 'integer'}) – the distribution to sample from
  • params (tuple) – the parameters specifying the distribution
  • size (int) – the number of samples to generate
Returns:

the samples for the distribution and specified parameters

Return type:

numpy array

class ema_workbench.em_framework.samplers.LHSSampler

generates a Latin Hypercube sample for each of the parameters

sample(distribution, params, size)

generate a Latin Hypercube Sample.

Parameters:
  • distribution (scipy distribution) – the distribution to sample from
  • params (tuple) – the parameters specifying the distribution
  • size (int) – the number of samples to generate
Returns:

with the paramertainty.name as key, and the sample as value

Return type:

dict

class ema_workbench.em_framework.samplers.MonteCarloSampler

generates a Monte Carlo sample for each of the parameters.

sample(distribution, params, size)

generate a Monte Carlo Sample.

Parameters:
  • distribution (scipy distribution) – the distribution to sample from
  • params (2-tuple of floats) – the parameters specifying the distribution
  • size (int) – the number of samples to generate
Returns:

with the paramertainty.name as key, and the sample as value

Return type:

dict

class ema_workbench.em_framework.samplers.FullFactorialSampler

generates a full factorial sample.

If the parameter is non categorical, the resolution is set the number of samples. If the parameter is categorical, the specified value for samples will be ignored and each category will be used instead.

determine_nr_of_designs(sampled_parameters)

Helper function for determining the number of experiments that will be generated given the sampled parameters.

Parameters:sampled_parameters (list) – a list of sampled parameters, as the values return by generate_samples
Returns:the total number of experimental design
Return type:int
generate_designs(parameters, nr_samples)

This method provides an alternative implementation to the default implementation provided by Sampler. This version returns a full factorial design across the parameters.

Parameters:
  • parameters (list) – a list of parameters for which to generate the experimental designs
  • nr_samples (int) – the number of intervals to use on each Parameter. Categorical parameters always return all their categories
Returns:

  • generator – a generator object that yields the designs resulting from combining the parameters
  • int – the number of experimental designs

generate_samples(parameters, size)

The main method of :class: ~sampler.Sampler and its children. This will call the sample method for each of the parameters and return the resulting samples

Parameters:
  • parameters (collection) – a collection of Parameter instances
  • size (int) – the number of samples to generate.
Returns:

with the paramertainty.name as key, and the sample as value

Return type:

dict

class ema_workbench.em_framework.samplers.PartialFactorialSampler(sampling='LHS')

generates a partial factorial design over the parameters. Any parameter where factorial is true will be included in a factorial design, while the remainder will be sampled using LHS or MC sampling.

Parameters:sampling ({PartialFactorialSampler.LHS, PartialFactorialSampler.MC}, optional) – the desired sampling for the non factorial parameters.
Raises:ValueError – if sampling is not either LHS or MC
generate_designs(parameters, nr_samples)

external interface to sampler. Returns the computational experiments over the specified parameters, for the given number of samples for each parameter.

Parameters:
  • parameters (list) – a list of parameters for which to generate the experimental designs
  • nr_samples (int) – the number of samples to draw for each parameter
Returns:

  • generator – a generator object that yields the designs resulting from combining the parameters
  • int – the number of experimental designs

ema_workbench.em_framework.samplers.sample_levers(models, n_samples, union=True, sampler=<ema_workbench.em_framework.samplers.LHSSampler object>)

generate policies by sampling over the levers

Parameters:
  • models (a collection of AbstractModel instances) –
  • n_samples (int) –
  • union (bool, optional) – in case of multiple models, sample over the union of levers, or over the intersection of the levers
  • sampler (Sampler instance, optional) –
Returns:

Return type:

generator yielding Policy instances

ema_workbench.em_framework.samplers.sample_uncertainties(models, n_samples, union=True, sampler=<ema_workbench.em_framework.samplers.LHSSampler object>)

generate scenarios by sampling over the uncertainties

Parameters:
  • models (a collection of AbstractModel instances) –
  • n_samples (int) –
  • union (bool, optional) – in case of multiple models, sample over the union of uncertainties, or over the intersection of the uncertainties
  • sampler (Sampler instance, optional) –
Returns:

  • generator – yielding Scenario instances
  • collection – the collection of parameters over which to sample
  • n_samples – the number of scenarios (!= n_samples in case off FF sampling)

ema_workbench.em_framework.samplers.determine_parameters(models, attribute, union=True)

determine the parameters over which to sample

Parameters:
  • models (a collection of AbstractModel instances) –
  • attribute ({'uncertainties', 'levers'}) –
  • union (bool, optional) – in case of multiple models, sample over the union of levers, or over the intersection of the levers
  • sampler (Sampler instance, optional) –
Returns:

Return type:

collection of Parameter instances