### Navigation

- index
- modules |
- next |
- previous |
- versuchung 0.1-0 documentation »

# Quick Introduction

As a quick start a simple experiment with input and output parameters is show:

    #!/usr/bin/python

    from versuchung.experiment import Experiment
    from versuchung.types import String
    from versuchung.files import File

    class SimpleExperiment(Experiment):
        inputs = {"input_key": String("default key"),
                  "input_value": String("default value")}
        outputs = {"output_file": File("output")}

        def run(self):
            # Combine the input parameters
            content = self.inputs.input_key.value \
                + ": " + self.inputs.input_value.value

            # write the result to the output file
            self.outputs.output_file.value = content + "\n"

    if __name__ == "__main__":
        import sys
        experiment = SimpleExperiment()
        dirname = experiment(sys.argv)

        print dirname

This experiment is put in a single python script file. It is a complete experiment and a runnable python script with a command line parser to override the default experiment input parameters.

Every experiment inherits from the `Experiment` class to gain the basic structure for parameter handling and running the experiment. After that the member variable `inputs` defines a `dict` of the input parameters. In this case two such input parameters are defined `"input_key"` and `"input_value"`, which are both of type `String` and have a specified default value. This default value is used if no argument is given on the command line. The attribute `outputs` defines the output parameter `"output_file"` which is of type `File` with the filename `"output"`. So in the experiment output there will be a file called output.

The `run()` method is the heart of every experiment. It is called when all input parameters are gathered and the experiment environment is set up. In this `SimpleExperiment` the input parameters are simply concatenated and written to the output file. This `SimpleExperiment` can be instantiated without arguments. The resulting object is called with the command line parameters to enable a command line interface.

Calling `python experiment.py --help` gives:

    Usage: experiment.py <options>

    Options:
      -h, --help            show this help message and exit
      -d BASE_DIR, --base-dir=BASE_DIR
                            Directory which is used for storing the experiment
                            data
      -l, --list            list all experiment results
      -v, --verbose         increase verbosity (specify multiple times for more)
      --input_key=INPUT_KEY
                            (default: default key)
      --input_value=INPUT_VALUE
                            (default: default value)

As you can see the two input parameters can be overwritten on the command line. The experiment can be executed by `python experiment.py` and print on the console:

    SimpleExperiment-aeb298601cdc582b1b0d8260195f6cfd

This is the versioned experiment result set. The hash at the end is calculated from the metadata of the experiment (e.g. input parameter values and the experiment version). In the current directory there was a directory created with this name where the results are located. To examine the experiment results and their metadata `python experiment.py -l` can be called:

    +SimpleExperiment-aeb298601cdc582b1b0d8260195f6cfd
    | {'date': '2012-01-14 09:46:13.445703',
    |  'experiment-name': 'SimpleExperiment',
    |  'experiment-version': 1,
    |  'input_key': 'default key',
    |  'input_value': 'default value'}

As you can see there is one result set in the current directory. All key parameters for the experiment are stored within the `metadata` file in the result directory. The `output` file in this result directory contains:

    default key: default value

### Navigation

- index
- modules |
- next |
- previous |
- versuchung 0.1-0 documentation »