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.
Commands¶
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.
run¶
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¶
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¶
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.
See pandas.DataFrame.to_csv
for details on these options.
Note
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.