Experiment([skip=0],[columns=[symbols...]],[debug=false],
           [moment_resolution=0.0015],[data_dir="data"],
           [width=1024],[height=768],[warn_on_trials_only=true],[extensions=[]])

Prepares a new experiment to be run.

Keyword Arguments

• skip the number of offsets to skip. Allows restarting of an experiment somewhere in the middle. When an experiment is terminated, the most recent offset is reported. The offset is also recorded in each row of the resulting data file (also reported on exit).

• columns the names (as symbols) of columns that will be recorded during the experiment (using record). These can be set to fixed values (using :name => value), or be filled in during a call to record (:name). The column :value is always included here, even if not specified, since there are number of events recorded automatically which make use of this column.

• debug if true, experiment will show in a windowed view

• moment_resolution the desired precision that moments should be presented at. Warnings will be printed for moments that lack this precision.

• data_dir the directory where data files should be stored (can be set to nothing to prevent a file from being created)

• width and height specified the screen resolution during the experiment

• extensions an array of Weber.Extension objects, which extend the behavior of an experiment.

• warn_on_trials_only when true, latency warnings are only displayed when the trial count is greater than 0. Thus, practice and breaks that occur before the first trial do not raise latency warnings.

addcolumn(column::Symbol)

Adds a column to be recorded in the data file.

This function must be called during setup. It cannot be called once the experiment has begun. Repeatedly adding the same column only adds the column once. After adding a column you can include that column as a keyword argument to record. You need not write to the column for every record. If left out, the column will be empty in the resulting row of the data file.

setup(fn,experiment)

Setup the experiment, adding breaks, practice, and trials.

Setup creates the context necessary to generate elements of an experiment. All calls to addtrial, addbreak and addpractice must be called inside of fn. This function must be called before run.

run(experiment;await_input=true)

Runs an experiment. You must call setup first.

By default, on windows, this function waits for user input before returning. This prevents a console from closing at the end of an experiment, preventing the user from viewing important messages. The exception is if run is called form within Juno: await_input should never be set to true in this case.

randomize_by(itr)

Randomize by a given iterable object, usually a string (e.g. the subject id.)

If the same iterable is given, calls to random functions (e.g. rand, randn and shuffle) will result in the same output.

@read_args(description,[keyword args...])

Reads experimental parameters from the user.

With no additional keyword arguments this requests the subject id, and an optional skip parameter (defaults to 0) from the user, and then returns them both in a tuple. The skip can be used to restart an experiment by passing it as the skip keyword argument to the Experiment constructor.

You can specify additional keyword arguments to request additional values from the user. Arguments that are a type will yield a request for textual input, and will verify that that input can be parsed as the given type. Arguments whose values are a list of symbols yield a request that the user select one of the specified values.

Arguments are requested from the user either as command-line arguments, or, if no command-line arguments were specified, interactively. Interactive arguments work both in the terminal or in Juno. This macro also generates useful help text that will be displayed to the user when they give a single command-line "-h" argument. This help text will include the desecription string.

Example

subject_id,skip,condition,block = @read_args("A simple experiment",
  condition=[:red,:green,:blue],block=Int)

@read_debug_args(description,[keyword args...])

Same as @read_args, but better suited to debugging errors in your program when running the experiment in Juno.

Specifically, this verison will never spawn a new process to run the experiment. This means that you can safely step through the code using debugging tools. In this case, you will also likely want to set debug=true when defining your Experiment object.

create_new_project(name,dir=".")

Creates a set of files to help you get started on a new experiment.

This creates a file called run_[name].jl, and a README.md and setup.jl file for your experiment. The readme provides useful information for running the experiment that is common across all experiments. The run file provides some guidelines to get you started creating an experiment and the setup file is a script that can be used to install Weber and any additional dependencies for the project, for anyone who wants to download and run your experiment.

Weber.trial()

Returns the current trial of the experiment.

Weber.offset()

Returns the current offset. The offset represents a well defined time in the experiment. The offset is typically incremented once for every call to addpractice addtrial and addbreak, unless you use @addtrials. You can use the offset to restart the experiment from a well defined location.

Weber.tick()

With microsecond precision, this returns the number of elapsed seconds from the start of the experiment to the start of the most recent moment.

If there is no experiment running, this returns the time since epoch with microsecond precision.

Weber.metadata() = Dict{Symbol,Any}()

Returns metadata for this experiment. You can store global state, specific to this experiment, in this dictionary.