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
The general format for running experimentator commands is:
exp COMMAND <exp-file> OPTIONS
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
There are a few ways to call it.
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
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
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
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
see documentation for that method for details.
Here is the full set of options for the
-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
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
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
experimentator will automatically start at the appropriate place;
run, experimentator will start at the beginning of the section
(unless an explicit starting point is passed with
resume takes the same
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:
--no-index-label Don’t put column labels on index columns (e.g. participant, trial), for easier importing into R. --delim=<sep> Field delimiter [default: ,]. --skip=<columns> Comma-separated list of columns to skip. --float=<format> Format string for floating point numbers. --nan=<rep> Missing data representation.
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