Setting

Handle the display of settings, the unique description of a parametrization of the system probed by the experiment of the dcode module.

class doce.setting.Setting(plan, setting_array=None, positional=True)

stores a setting, where each member is a factor and the value of the member is a modality.

Stores a setting, where each member is a factor and the value of the member is a modality.

Examples

>>> import doce

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

>>> for setting in p:
...   print(setting)
f1=a+f2=1
f1=a+f2=2
f1=b+f2=1
f1=b+f2=2

Methods

identifier([style, sort, factor_separator, ...])	return a one-liner str or a list of str that describes a setting or a Plan object.
perform(function, experiment, log_file_name, ...)	run the function given as parameter for the setting.
remove_factor(factor)	returns a copy of the setting where the specified factor is removed.
replace(factor[, value, positional, relative])	returns a new doce.Plan object with one factor with modified modality.

identifier(style='long', sort=True, factor_separator='+', modality_separator='=', singleton=True, default=False, hide=None)

return a one-liner str or a list of str that describes a setting or a Plan object.

Return a one-liner str or a list of str that describes

a setting or a Plan object with a high degree of flexibility.

Parameters:

style: str (optional)

‘long’: (default) ‘list’: a list of string alternating factor and the corresponding modality ‘hash’: a hashed version

sort: bool (optional)

if True, sorts the factors by name (default).

If False, use the order of definition.

singleton: bool (optional)

if True, consider factors with only one modality.

if False, consider factors with only one modality (default).

default: bool (optional)

if True, also consider couple of factor/modality where the modality is explicitly set to be a default value for this factor using doce.Plan.default().

if False, do not show them (default).

hide: list of str

list the factors that should not be considered.

factor_separator: str

factor_separator used to concatenate the factors, default is ‘|’.

factor_separator: str

factor_separator used to concatenate the factor and modality value, default is ‘=’.

See also

doce.Plan.default

doce.util.compress_name

Examples

>>> import doce

>>> p = doce.Plan()
>>> p.one = ['a', 'b']
>>> p.two = [0,1]
>>> p.three = ['none', 'c']
>>> p.four = 'd'

>>> print(p)
  0  one: ['a' 'b']
  1  two: [0 1]
  2  three: ['none' 'c']
  3  four: ['d']

>>> for setting in p.select([0, 1, 1]):
...   # default display
...   print(setting.identifier())
four=d+one=a+three=c+two=1
>>> # list style
>>> print(setting.identifier('list'))
['four=d', 'one=a', 'three=c', 'two=1']
>>> # hashed version of the default display
>>> print(setting.identifier('hash'))
4474b298d3b23000e739e888042dab2b
>>> # do not apply sorting of the factor
>>> print(setting.identifier(sort=False))
one=a+two=1+three=c+four=d
>>> # specify a factor_separator
>>> print(setting.identifier(factor_separator=' '))
four=d one=a three=c two=1
>>> # do not show some factors
>>> print(setting.identifier(hide=['one', 'three']))
four=d+two=1
>>> # do not show factors with only one modality
>>> print(setting.identifier(singleton=False))
one=a+three=c+two=1
>>> delattr(p, 'four')
>>> for setting in p.select([0, 0, 0]):
...   print(setting.identifier())
one=a+three=none+two=0

>>> # set the default value of factor one to a
>>> p.default('one', 'a')
>>> for setting in p.select([0, 1, 1]):
...   print(setting.identifier())
three=c+two=1
>>> # do not hide the default value in the description
>>> print(setting.identifier(default=True))
one=a+three=c+two=1

>>> p.optional_parameter = ['value_one', 'value_two']
>>> for setting in p.select([0, 1, 1, 0]):
...   print(setting.identifier())
optional_parameter=value_one+three=c+two=1
>>> delattr(p, 'optional_parameter')

>>> p.optional_parameter = ['value_one', 'value_two']
>>> for setting in p.select([0, 1, 1, 0]):
...   print(setting.identifier())
optional_parameter=value_one+three=c+two=1

perform(function, experiment, log_file_name, *parameters)

run the function given as parameter for the setting.

Helper function for the method do().

See also

doce.Plan.do

remove_factor(factor)

returns a copy of the setting where the specified factor is removed.

Parameters:

factor: str

the name of the factor.

replace(factor, value=None, positional=0, relative=0)

returns a new doce.Plan object with one factor with modified modality.

Returns a new doce.Plan object with one factor with modified modality. The value of the requested new modality can requested by 3 exclusive means: its value, its position in the modality array, or its relative position in the array with respect to the position of the current modality.

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.

modality: literal or None (optional)

the value of the modality.

positional: int (optional)

if 0, this parameter is not considered (default).

If >0, interpreted as the index in the modality array (default).

relative: int (optional)

if 0, this parameter is not considered (default).

Otherwise, interpreted as an index, relative to the current modality.

Examples

>>> import doce

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

>>> for setting in p.select([1, 1]):
...   # the inital setting
...   print(setting)
one=b+two=2
>>> # the same setting but with the factor 'two' set to modality 1
>>> print(setting.replace('two', value=1))
one=b+two=1
>>> # the same setting but with the first factor set to modality
>>> print(setting.replace(1, value=1))
one=b+two=1
>>> # the same setting but with the factor 'two' set to modality index 0
one=b+two=1
>>> print(setting.replace('two', positional=0))
one=b+two=1
>>> # the same setting but with the factor 'two' set to
>>> # modality of relative index -1 with respect to
>>> # the modality index of the current setting
>>> print(setting.replace('two', relative=-1))
one=b+two=1