read_path {Rtrack}

Read path coordinates from raw data formats.

Description

You will normally not need to call this directly. Use read_experiment instead.

Usage

read_path(
  filename,
  arena,
  id = NULL,
  track.format = "none",
  track.index = NULL,
  interpolate = FALSE,
  time.bounds = c(NA, NA)
)

Arguments

filename

A raw data file containing path coordinates. See details for supported formats.

arena

The arena object associated with this track. This is required to calibrate the track coordinates to the coordinate space of the arena.

id

An optional name for the experiment. Default is to generate this from the filename provided.

track.format

The format of the raw file.

track.index

Only for formats where multiple tracks are stored in one file (ignored otherwise). This parameter indicates which section of the file corresponds to the track to be read. The exact usage depends on the format being read.

interpolate

Should missing data points be interpolated. Default is FALSE. Interpolation is performed at evenly-spaced intervals after removing outliers.

time.bounds

A vector of length 2 specifying the bounds on the measurement times (see Details).

Details

Raw data from several sources, including many commonly-used tracking platforms, can be read in directly. To get a list of the supported formats, use the command Rtrack::identify_track_format(). The "raw.tab" format is a simple tab-delimited text file containing three columns "Time", "X" and "Y". The timestamp values in "Time" should be in seconds from the start of the trial recording and coordinates should be in real-world units (e.g. cm, in).

If interpolate is set to TRUE, then the raw data will be cleaned to remove outlier points and ensure that time points are evenly spaced. See the online documentation for details on the method used for each experiment type.

The raw path recordings can be truncated if necessary by specifying the time.bounds parameter. This is a vector of length 2 containing the earliest and latest time points that should be retained for analysis (any points outside these bounds will be discarded). A value of NA indicates that the path should not be truncated at that end (default is c(NA, NA) meaning that the path will extend to the start and end of the recorded values). The units used must match the time units in the track files. This option should not normally need to be set, but may be useful if data acquisition begins before, or ends after, the actual experimental trial (e.g. if recording was running during entry and exit from the arena).

Value

An rtrack_path object containing the extracted swim path. This is a list comprised of the components raw.t (timestamp), raw.x (x coordinates), raw.y (y coordinates),t, x and y (normalised, cleaned and possibly interpolated coordinates).

See Also

read_arena, identify_track_format to identify the format code for your raw data, and also read_experiment for processing many tracks at once.

Examples

require(Rtrack)
track_file <- system.file("extdata", "Track_1.tab", package = "Rtrack")
arena_description <- system.file("extdata", "Arena.txt", package = "Rtrack")
arena <- read_arena(arena_description)
path <- read_path(track_file, arena, track.format = "raw.tab")