load_ethoscope: Load data from ethoscope result files

In scopr: Read Ethoscope Data

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,
  ...
)

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.

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.

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

scopr documentation built on Aug. 15, 2022, 5:05 p.m.