The user will normally not need to call this directly. Use
read_path( filename, arena, id = NULL, track.format = "none", track.index = NULL, interpolate = FALSE, time.bounds = c(NA, NA) )
A raw data file containing path coordinates. See details for supported formats.
An optional name for the experiment. Default is to generate this from the filename provided.
The format of the raw file.
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.
Should missing data points be interpolated. Default is
A vector of length 2 specifying the bounds on the measurement times (see Details).
rtrack_path object containing the extracted swim path. This is a list
comprised of the components
raw.x (x coordinates),
raw.y (y coordinates),
y (normalised, cleaned and
possibly interpolated coordinates).
Raw data from several sources can be read in directly. The formats currently supported are 'ethovision.xt.excel' (for swim paths exported from the latest Ethovision software), 'ethovision.3.csv' (for data exported from the older Ethovision version 3) and 'raw.csv'. The 'raw.csv' format is a simple comma-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).
interpolate is set to
TRUE, then the raw data will be cleaned to
remove outlier points and ensure that time points are evenly spaced. The following
procedures are used: 1. any points with missing coordinate data are removed; 2. any
points lying outside the arena are removed: 3. any points with excessive inter-point
distances (outliers) are removed by first removing points that are more than 1 SD from
the mean distance, then recalculating the mean and SD and repeating this step - this is
typically sufficient to remove noise from video tracking (such as reflections from a
water maze pool); 4. new time intervals are calculated from the first non-missing data
point to the last using the sampling rate of the raw data; 5. interpolation of x and y
values is performed at the new time points using the 'constant' interpolation method
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).