Plan

Handle storage and processing of the plan of the doce module.

class doce.plan.Plan(name, **factors)

stores the different factors of the doce experiment.

This class stores the different factors of the doce experiments. For each factor, the set of different modalities can be expressed as a list or a numpy array.

To browse the setting set defined by the Plan object, one must iterate over the Plan object.

Examples

>>> import doce

>>> p = doce.Plan('')
>>> p.factor1=[1, 3]
>>> p.factor2=[2, 4]

>>> print(p)
  0  factor1: [1 3]
  1  factor2: [2 4]

>>> for setting in p:
...   print(setting)
factor1=1+factor2=2
factor1=1+factor2=4
factor1=3+factor2=2
factor1=3+factor2=4

Methods

as_panda_frame()	returns a panda frame that describes the Plan object.
clean_data_sink(path[, reverse, force, ...])	clean a data sink by considering the settings set.
clean_h5(path[, reverse, force, keep, ...])	clean a h5 data sink by considering the settings set.
default(factor, modality)	set the default modality for the specified factor.
factors()	returns the names of the factors.
nb_modalities(factor)	returns the number of modalities for a given factor.
perform(function, experiment, *parameters[, ...])	iterate over the setting set and run the function given as parameter.
select([selector, volatile, prune])	set the selector.

check
check_length
constant_factors
copy
expand_selector
get_name
merge
order_factor

as_panda_frame()

returns a panda frame that describes the Plan object.

Returns a panda frame describing the Plan object.

For ease of definition of a selector to select some settings, the columns and the rows of the panda frame are numbered.

Examples

>>> import doce

>>> p = doce.Plan('')
>>> p.one = ['a', 'b']
>>> p.two = list(range(10))

>>> print(p)
  0  one: ['a' 'b']
  1  two: [0 1 2 3 4 5 6 7 8 9]
>>> print(p.as_panda_frame())
  Factors  0  1  2  3  4  5  6  7  8  9
0    one  a  b
1    two  0  1  2  3  4  5  6  7  8  9

clean_data_sink(path, reverse=False, force=False, keep=False, wildcard='*', setting_encoding=None, archive_path='', verbose=0)

clean a data sink by considering the settings set.

This method is more conveniently used by

considering the method :meth:`doce.experiment._experiment.clean_data_sink, please see its documentation for usage.

clean_h5(path, reverse=False, force=True, keep=False, setting_encoding=None, archive_path='', verbose=0)

clean a h5 data sink by considering the settings set.

This method is more conveniently used by considering

the method :meth:`doce.experiment._experiment.clean_data_sink, please see its documentation for usage.

default(factor, modality)

set the default modality for the specified factor.

Set the default modality for the specified factor.

Parameters:

factor: str

the name of the factor

modality: int or str

the modality value

See also

doce.Plan.id

Examples

>>> import doce

p = doce.Plan(‘’)

p.f1 = [‘a’, ‘b’] p.f2 = [1, 2, 3]

print(f) for setting in p.select():

print(setting.identifier())

p.default(‘f2’, 2)

for setting in p:

print(setting.identifier())

p.f2 = [0, 1, 2, 3] print(f)

p.default(‘f2’, 2)

for setting in p:

print(setting.identifier())

factors()

returns the names of the factors.

Returns the names of the factors as a list of strings.

Examples

>>> import doce

>>> p = doce.Plan('')
>>> p.f1=['a', 'b']
>>> p.f2=[1, 2]
>>> p.f3=[0, 1]

>>> print(p.factors())
['f1', 'f2', 'f3']

nb_modalities(factor)

returns the number of modalities for a given factor.

Returns the number of modalities

for a given factor as an integer value.

Parameters:

factor: int or str

if int, considered as the index inside an array of the factors sorted by order of definition.

If str, the name of the factor.

Examples

>>> import doce

>>> p = doce.Plan('')
>>> p.one = ['a', 'b']
>>> p.two = list(range(10))

>>> print(p.nb_modalities('one'))
2
>>> print(p.nb_modalities(1))
10

perform(function, experiment, *parameters, nb_jobs=1, progress='d', log_file_name='', mail_interval=0)

iterate over the setting set and run the function given as parameter.

This function is wrapped by doce.experiment.Experiment.do(), which should be more convenient to use. Please refer to this method for usage.

Parameters:

functionfunction(Plan, Experiment, *parameters)

operates on a given setting within the experiment environnment with optional parameters.

experiment:

an Experiment object

*parametersany type (optional)

parameters to be given to the function.

nb_jobsint > 0 (optional)

number of jobs.

If nb_jobs = 1, the setting set is browsed sequentially in a depth first traversal of the settings tree (default).

If nb_jobs > 1, the settings set is browsed randomly, and settings are distributed over the different processes.

progressstr (optional)

display progress of scheduling the setting set.

If str has an m, show the selector of the current setting. If str has an d, show a textual description of the current setting (default).

log_file_namestr (optional)

path to a file where potential errors will be logged.

If empty, the execution is stopped on the first faulty setting (default).

If not empty, the execution is not stopped on a faulty setting, and the error is logged in the log_file_name file.

See also

doce.experiment.Experiment.perform

select(selector=None, volatile=False, prune=True)

set the selector.

This method sets the internal selector to the selector given as parameter.

Once set, iteration over the setting set is limited to the settings that can be reached according to the definition of the selector.

Parameters:

selector: list of list of int or list of int or list of dict

a :term:`selector

volatile: bool

if True, the selector is disabled after a complete iteration over the setting set.

If False, the selector is saved for further iterations.

Examples

>>> import doce

>>> p = doce.Plan()
>>> p.f1=['a', 'b', 'c']
>>> p.f2=[1, 2, 3]

>>> # doce allows two ways of defining the selector. The first one is dict based:
>>> for setting in p.select([{'f1':'b', 'f2':[1, 2]}, {'f1':'c', 'f2':[3]}]):
...  print(setting)
f1=b+f2=1
f1=b+f2=2
f1=c+f2=3

>>> # The second one is list based. In this example, we select the settings with
>>> # the second modality of the first factor, and with the first modality of the second factor
>>> for setting in p.select([1, 0]):
...  print(setting)
f1=b+f2=1
>>> # select the settings with all the modalities of the first factor,
>>> # and the second modality of the second factor
>>> for setting in p.select([-1, 1]):
...  print(setting)
f1=a+f2=2
f1=b+f2=2
f1=c+f2=2
>>> # the selection of all the modalities of the remaining factors can be conveniently expressed
>>> for setting in p.select([1]):
...  print(setting)
f1=b+f2=1
f1=b+f2=2
f1=b+f2=3
>>> # select the settings using 2 selector, where the first selects the settings
>>> # with the first modalityof the first factor and with the second modality
>>> # of the second factor, and the second selector selects the settings
>>> # with the second modality of the first factor,
>>> # and with the third modality of the second factor
>>> for setting in p.select([[0, 1], [1, 2]]):
...  print(setting)
f1=a+f2=2
f1=b+f2=3
>>> # the latter expression may be interpreted as the selection of the settings with
>>> # the first and second modalities of the first factor and with second and
>>> # third modality of the second factor. In that case, one needs to add a -1
>>> # at the end of the selector (even if by doing so the length of the selector
>>> # is larger than the number of factors)
>>> for setting in p.select([[0, 1], [1, 2], -1]):
...  print(setting)
f1=a+f2=2
f1=a+f2=3
f1=b+f2=2
f1=b+f2=3
>>> # if volatile is set to False (default) when the selector is set
>>> # and the setting set iterated, the setting set stays ready for another iteration.
>>> for setting in p.select([0, 1]):
...  pass
>>> for setting in p:
...  print(setting)
f1=a+f2=2
>>> # if volatile is set to True when the selector is set and the setting set iterated,
>>> # the setting set is reinitialized at the second iteration.
>>> for setting in p.select([0, 1], volatile=True):
...  pass
>>> for setting in p:
...  print(setting)
f1=a+f2=1
f1=a+f2=2
f1=a+f2=3
f1=b+f2=1
f1=b+f2=2
f1=b+f2=3
f1=c+f2=1
f1=c+f2=2
f1=c+f2=3
>>> # if volatile was set to False (default) when the selector was first set
>>> # and the setting set iterated, the complete set of settings can be reached
>>> # by calling selector with no parameters.
>>> for setting in p.select([0, 1]):
...  pass
>>> for setting in p.select():
...  print(setting)
f1=a+f2=1
f1=a+f2=2
f1=a+f2=3
f1=b+f2=1
f1=b+f2=2
f1=b+f2=3
f1=c+f2=1
f1=c+f2=2
f1=c+f2=3