Defining a Experiment

As every experiment must inherit from the versuchung.experiment.Experiment class their attributes and methods are absolutly basic to versuchung.

class versuchung.experiment.Experiment(default_experiment_instance=None, title=None, inputs=None, outputs=None)

Can be used as: input parameter

__call__(args=[], **kwargs)

A experiment can also executed by calling it, execute will be called.

>>> experiment(sys.argv)

__init__(default_experiment_instance=None, title=None, inputs=None, outputs=None)

The constructor of an experiment just fills in the necessary attributes but has no sideeffects on the outside world.

Parameters:default_experiment_instance (str.) – If used as input parameter, this is the default result set used. For example "SimpleExperiment-aeb298601cdc582b1b0d8260195f6cfd"

execute(args=[], **kwargs)

Calling this method will execute the experiment

Parameters:args (list.) – The command line arguments, normally sys.argv Kwargs:The keyword arguments can be used to overwrite the default values of the experiment, without assembling a command line.

The normal mode of operation is to give sys.argv as argument:

>>> experiment.execute(sys.argv)

But with keyword arguments the following two expression result in the same result set:

>>> experiment.execute(["--input_parameter", "foo"])
>>> experiment.execute(input_parameter="foo")

filter_metadata(metadata)

This method is invocated on the dict which is stored in $result_dir/metadata before the result_hash is calculated. This helps to take influence on the input parameters which alter the experiment hash. So use it with care.

Note

Can be implemented by the user.

i = None

Shorthand for inputs

inputs = {}

In the input dictionary all input parameters are defined. They may and will influence the metadata and the metadata hash. Only objects which are marked as input parameters may be used here. The key in this dict is used as name attribute and propagated to the parameters. From these input parameters the command line interface is created.

This dict can not only be used as a dictionary but also a object with the dot-notation (this behaviour is known and widely used in javascript). And there is i as a shorthand.

>>> self.inputs["string_parameter"]
<versuchung.types.String object at 0xb73fabec>
>>> self.inputs.string_parameter
<versuchung.types.String object at 0xb73fabec>
>>> self.i.string_parameter
<versuchung.types.String object at 0xb73fabec>

metadata

Return the metadata as python dict. This works for experiments, which are running at the moment, and for already finished experiments by reading the /metadata file.

name = None

The name of the object. This is in execution mode (Experiment instance is the executed experiment) the result set name (str). When the experiment is used as input parameter it is the key-value in the inputs dictionary.

o = None

Shorthand for outputs

outputs = {}

Similar to the inputs attribute, in the output dictionary all experiment results are defined. Only objects that are explicitly marked as output parameters can be used here.

When a experiment is used as an input parameter. The results of the old experiment can be accessed through this attribute. Of course at all points the short hands for inputs and outputs can be used. As well as the javascript style access to dictionary members.

>>> self.inputs["experiment"].outputs["out_file"]
<versuchung.types.File object at 0xb736220c>
>>> self.i.experiment.o.out_file
<versuchung.types.File object at 0xb736220c>

run()

This method is the heart of every experiment and must be implemented by the user. It is called when the experiment is executed. Before all input parameters are parsed, the output directory is set up. Afterwards all temporary data is removed and the output parameters are deinitialized.

Warning

Must be implemented by the user.

title = None

Title of the experiment, this is normally the classname

version = 1

Version of the experiment, defaults to 1. The version is included in the metadata and used for the metadata hash.