Command-line interface

You’ve generated your experiment, now what? A major feature of experimentator is that it automatically turns your experiment into a command-line program, via the command exp. The general format for running experimentator commands is:

exp COMMAND <exp-file> OPTIONS

The available commands are run, resume, and export. Additionally, exp --help (or -h) will show the usage information, and exp --version will print experimentator’s version number.


Here is the abridged usage message:

  exp run [options] <exp-file> (--next=<level>  [--not-finished] | (<level> <n>)... [--from=<n>])
  exp resume [options] <exp-file> (<level> | (<level> <n>)...)
  exp export <exp-file> <data-file> [ --no-index-label --delim=<sep> --skip=<columns> --float=<format> --nan=<rep>]
  exp -h | --help
  exp --version

Don’t fear, an in-depth explanation follows.


The central command is run. There are a few ways to call it.

run –next

To run the first section at <level> that hasn’t been started:

exp run <exp-file> --next <level>

For example, to run the next participant from example.exp:

exp run example.exp --next participant

To run the next participant that hasn’t been finished (as opposed to the next that hasn’t started, the default):

exp run example.exp --next participant --not-finished

run <level> <n>

To run a specific section:

exp run <exp-file> (<level> <n>)...

The elipsis means that the previous element (the pair <level> <n>) can be repeated any number of times. For example, to run the second session of the third participant:

exp run example.exp participant 3 session 2

run –from

In either version of run, you can add the --from <n> option to start at a specific section. For example, to run the second session of the third participant, starting at the second block:

exp run example.exp participant 3 session 2 --from 2

<n> can also be a comma-separated list of integers. To start at the fourth trial of the second block:

exp run example.exp participant 3 session 2 --from 2,4

--from=<n> works the same as the from_section parameter to run_experiment_section; see documentation for that method for details.

run options

Here is the full set of options for the run command:

-d, --debug Set logging level to DEBUG.
-o <options> Pass <options> to the experiment and save it as string in Experiment.session_data[‘options’].
--demo Don’t save data.
--not-finished Run the first <level> that hasn’t finished (rather than first that hasn’t started).
--skip-parents Don’t enter context of parent levels.
--from=<n> Start running at child number <n> of the specified section. <n> can also be a comma-separated list of ints; see run_experiment_section for details (specifically, –from=<n> works like the parameter from_section).


resume is similar to run. There is nothing resume can do that run cannot, but resume makes resuming interrupted session easier. There are two ways to call it.

If you only pass a level, experimentator will try to resume the first section at that level that has been started but not finished. The syntax is:

exp resume <exp-file> <level>

For example, to resume the first block that has been started but not finished:

exp resume example.expblock

One can also use specific section numbers with resume:

exp resume <exp-file> (<level> <n>)...

The specified section must have been started but not finished. For example:

exp resume example.expparticipant 3 session 2

The difference between the above example and using run is that with resume, experimentator will automatically start at the appropriate place; with run, experimentator will start at the beginning of the section (unless an explicit starting point is passed with --from).

resume takes the same options as run.


export generates a text file with the experiment’s data. Its basic syntax is:

exp export <exp-file> <data-file>

This one should be straightforward, but here is an example anyway:

exp export example.expexample.csv

Its associated options:

 Don’t put column labels on index columns (e.g. participant, trial), for easier importing into R.
--delim=<sep> Field delimiter [default: ,].
 Comma-separated list of columns to skip.
 Format string for floating point numbers.
--nan=<rep> Missing data representation.

See pandas.DataFrame.to_csv for details on these options.


If your experiment has any complex data structures (e.g., a timeseries for every trial), it is not recommended to use the export command, as this will create an unparseable mess. Instead, access your data programmatically through the Experiment.dataframe attribute.