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:
Set variables which should be sampled with
set_sampling_var()
.(Optional) Set further options of the SamplingPlanner with
set_param()
Generate the sampling plan with
gen_sampling_plan()
.And / or: Add specific sampling case with
add_sampling_case()
.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 argumentfun_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 withdata_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 allsampling_vars
must be referenced. Sampling vars that are excluded, will generate a value according to their assignedfun_var_pdf
(seeset_sampling_var()
).- Parameters
kwargs (
dict
) – Keyword arguments of the formvar_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 parameterfun_var_pdf
defaults toNone
.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 variablealpha
. We use the function that created values from the random normal distribution with zero mean and unity covariance. For the variablebeta
we created a new lambda function that draws random integers from 0 to 5.- Parameters
name (
str
) – Name of the sampled variablefun_var_pdf (
Optional
[Callable
[[],Union
[float
,int
]]]) – Declare the value-generating function of the sampled variable
- Raises
assertion –
name
must be stringassertion –
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.