SamplingPlanner#

class SamplingPlanner(**kwargs)[source]#

Bases: object

A class for generating sampling plans. These sampling plans will be executed by do_mpc.sampling.Sampler to generate data.

The class can be created with optional keyword arguments which are passed to set_param().

Configuration and sampling plan generation:

  1. Set variables which should be sampled with set_sampling_var().

  2. (Optional) Set further options of the SamplingPlanner with set_param()

  3. Generate the sampling plan with gen_sampling_plan().

  4. And / or: Add specific sampling case with add_sampling_case().

  5. Export the plan with all sampling cases with export()

Methods#

add_sampling_case#

add_sampling_case(self, **kwargs)#

Manually add sampling case with user-defined values. Create a sampling case by choosing values for the previously introduced sampling variables (with set_sampling_var()).

Method takes arbitrary (keyword, argument) pairs, where the keywords must refer to previously introduced sampling variables. add_sampling_case() will automatically augment the sampling case with values for variables that are not passed as arguments. This only works if these variables were created with the argument fun_var_pdf.

Example:

sp = do_mpc.sampling.SamplingPlanner()

# Plan with two variables alpha and beta:
sp.set_sampling_var('alpha', np.random.randn)
sp.set_sampling_var('beta', lambda: np.random.randint(0,5))

# Create two new sampling cases, missing variable is auto-generated:
sp.add_sampling_case(alpha=1)
sp.add_sampling_case(beta= 0)
Returns:

list – Returns the newly created sampling plan.

export#

export(self, sampling_plan_name)#

Export SamplingPlan in pickle format. Pass sampling_plan_name without any path. File extension can be added (but will be stripped automatically). Change the path with data_dir.

Parameters:

sampling_plan_name (str) – Name of the exported sampling plan file.

Raises:

assertion – sampling_plan_name must be string.

Return type:

None

gen_sampling_plan#

gen_sampling_plan(self, n_samples)#

Generate the sampling plan. The generated plan contains n_samples samples based on the defined variables and the corresponding evaluation functions.

Parameters:

n_samples (int) – The number of generated samples

Raises:

assertion – n_samples must be int

Returns:

list – Returns the newly created sampling plan.

product#

product(self, **kwargs)#

Cartesian product of input variables. This method is inspired by itertools.product.

Must pass a list for each sampling_var that should be considered. Not all sampling_vars must be referenced. Sampling vars that are excluded, will generate a value according to their assigned fun_var_pdf (see set_sampling_var()).

Parameters:

kwargs (dict) – Keyword arguments of the form var_name=var_values.

Returns:

list – Returns the newly created sampling plan.

set_param#

set_param(self, **kwargs)#

Set the parameters of the SamplingPlanner class. Parameters must be passed as pairs of valid keywords and respective argument. For example:

sp.set_param(overwrite = True)

It is also possible and convenient to pass a dictionary with multiple parameters simultaneously as shown in the following example:

setup_dict = {
    'overwrite': True,
    'save_format': pickle,
}
sp.set_param(**setup_dict)

This makes use of thy python “unpack” operator. See more details here.

Note

set_param() can be called multiple times. Previously passed arguments are overwritten by successive calls.

The following parameters are available:

Parameters:

  • overwrite (bool) – Overwrites existing samplingplan under the same name, if set to True.

  • id_precision (str) – Padding for IDs of created samples. Defaults to 3. This means sample 20 will be denoted as 020.

Return type:

None

set_sampling_var#

set_sampling_var(self, name, fun_var_pdf=None)#

Introduce new sampling variables to the SamplingPlanner. Define variable name. Optionally add a function to generate values for the sampled variable (e.g. following some distribution). The parameter fun_var_pdf defaults to None.

Note

If no value-generating function is passed (for any of the introduced variables), all sampling cases must be created manually with add_sampling_case().

Note

Value generating function fun_var_pdf must not require inputs.

Example:

sp = do_mpc.sampling.SamplingPlanner()

# Plan with two variables alpha and beta:
sp.set_sampling_var('alpha', np.random.randn)
sp.set_sampling_var('beta', lambda: np.random.randint(0,5))

In the example we have passed a BuiltinFunction for the introduced variable alpha. We use the function that created values from the random normal distribution with zero mean and unity covariance. For the variable beta we created a new lambda function that draws random integers from 0 to 5.

Parameters:

  • name (str) – Name of the sampled variable

  • fun_var_pdf (Callable[[], Union[float, int]]) – Declare the value-generating function of the sampled variable

Raises:

  • assertion – name must be string

  • assertion – fun_var_pdf must be Function or BuiltinFunction

Return type:

None

Attributes#

data_dir#

SamplingPlanner.data_dir#

Set the save directory for the samplingplan. If the directory does not exist yet, it is created. If the directory is nested all (non-existing) parent folders are also created.

Example:

sp = do_mpc.sampling.SamplingPlanner()
sp.data_dir = './samples/experiment_1/'

This will set the directory to the indicated path. If the path does not exist, all folders are created.