read_experiment {Rtrack}

Read experiment data.

Description

Reads a spreadsheet containing a description of all the files required for an experiment to allow batch execution.

Usage

read_experiment(
  filename,
  format = NA,
  interpolate = FALSE,
  project.dir = NA,
  data.dir = project.dir,
  author.note = "",
  threads = 1,
  verbose = FALSE
)

Arguments

filename

A spreadsheet file containing a description of the experiment or a trackxf file containing an exported experiment.

format

An experiment description for reading raw data can be provided as an Excel spreadsheet ("excel") or as a comma-delimited ("csv") or tab-delimited ("tab", "tsv", "txt" or "text") text file. The value "trackxf" indicates that the file is an archived experiment in the trackxf format (as generated by export_data). Default (NA) is to guess the format from the file extension.

interpolate

This is passed to the read_path function and specifies whether missing data points will be interpolated when reading raw swim path data. Default is FALSE.

project.dir

A directory path specifying where the files needed for processing the experiment are stored. Default (NA) means the project files are in the same directory as the experiment description (specified by filename). Ignored if format = "trackxf".

data.dir

A directory path specifying where the raw data are stored. All paths specified in the experiment description spreadsheet are interpreted as being relative to the data.dir directory. Default is the same directory as project.dir. Ignored if format = "trackxf".

author.note

Optional text describing the experiment. This might be useful if the data is to be published or otherwise shared. Appropriate information might be author names and a link to a publication or website.

threads

The number of CPU threads/processes to run in parallel. The default is 1, which will use just one single thread. A value of 0 will try to use the maximum number of available cores (using multi-threading if available). Using all of the available threads/logical cores may not be sensible though, depending on your hardware. Note that for some Linux machines with multi-threading capabilities, the number of threads detected might be the same as the number of physical CPU cores. Negative values will start the default number of threads minus the given number.

verbose

Should feedback be printed to the console. This is only useful for debugging and takes a little longer to run. Default is FALSE.

Details

Information about a full experiment can be assembled into a spreadsheet ( currently Excel and CSV formats are supported) and used to process large numbers of files in one batch. The project directory (project.dir) is where the arena description files are found. This will typically be the same place as the experiment description file (and is set to be this by default). This does not need to be the same as the current working directory. An optional data directory (data.dir) can also be specified separately allowing the storage-intensive raw data to be kept in a different location (for example on a remote server). Together, these options allow for flexibility in managing your raw data storage. Individual tracks are associated with their raw data file, experimental group metadata, an arena and any other parameters that the strategy-calling methods require. Required columns are "_TrackID", "_TargetID", "_Day", "_Trial", "_Arena" "_TrackFile" and "_TrackFileFormat" (note the leading underscore "_"). Any additional columns (without a leading underscore) will be interpreted as user-defined factors or other metadata and will be passed on to the final analysis objects and thus be available for statistical analysis.

For details on how interpolation is performed (if interpolate is set to TRUE), see the documentation for read_path.

For larger experiments, it might be helpful to run the experiment processing on multiple CPU cores in parallel. To do this, simply specify the number of processes ("threads") to use.

Value

An rtrack_experiment object containing a complete description of the experiment.

See Also

read_path, read_arena, identify_track_format to identify the format of your raw track files, and check_experiment.

Examples

require(Rtrack)
experiment.description = system.file("extdata", "Minimal_experiment.xlsx",
  package = "Rtrack")
experiment = read_experiment(experiment.description)