scopr (version 0.3.4)

load_ethoscope: Load data from ethoscope result files

Description

This function is used to import behavioural data generated by the ethoscope platform. That is it loads multiple .db files into a single R behavr::behavr table.

Usage

load_ethoscope(
  metadata,
  min_time = 0,
  max_time = Inf,
  reference_hour = NULL,
  verbose = TRUE,
  columns = NULL,
  cache = NULL,
  ncores = 1,
  FUN = NULL,
  map_arg = NULL,
  ...
)

Value

A behavr table. In addition to the metadata, it contains the data, with the columns:

• id -- autogenerated unique identifier, one per animal

• t -- time (s)

• Several variables recorded by ethoscopes (position, angle, width/height and others), or computed by FUN. Distance units (e.g. xy position, height/width) are expressed as a fraction of the width of the ROI they originate from.

Arguments

metadata

data.table::data.table used to load data (see detail)

min_time, max_time

load only data between min_time and max_time (in seconds). This time is relative to the start of the experiment.

reference_hour

hour, in the day, to use as ZT0 reference. When unspecified, time will be relative to the start of the experiment.

verbose

whether to print progress (a logical)

columns

optional vector of columns to be selected from the db file. Time (t) is always implicitly selected. When NULL and if FUN is set, columns can be retrieved automatically (from the attributes of FUN).

cache

the name of a local directory to cache results for faster subsequent data loading.

ncores

number of cores to use for optional parallel processing (experimental).

FUN

function (optional) to transform the data from each individual immediately after is has been loaded.

map_arg

a list to map FUN arguments to metavariables values. See details

...

extra arguments to be passed to FUN

Details

the linked metadata should be generated using link_ethoscope_metadata. map_arg is a list of the form list(fun_arg = "metavariable"). When provided, FUN will set specific arguments (fun_arg) to the value of a (quoted) metavariable.

References

• behavr tutorial -- how to work with the obtained behavr table

See Also

• behavr::behavr -- to understand the output format

• experiment_info -- to show information about a file/experiment

• list_result_files -- to list available files

Examples

dir <- paste0(scopr_example_dir(), "/ethoscope_results/")
data(region_id_metadata)
metadata <- link_ethoscope_metadata(region_id_metadata, dir)
print(metadata)

# Default data loading
dt <- load_ethoscope(metadata)
dt

# We use reference hour to set zt0 to 09:00 GMT
dt <- load_ethoscope(metadata, reference_hour=9)
dt

# Only load x and y positions
dt <- load_ethoscope(metadata, columns=c("x", "y"), reference_hour=9)
dt
# apply function whilst loading the data
dt <- load_ethoscope(metadata, reference_hour=9, FUN=head)
dt