Retrieve information about an experiment

Description

This function is used to obtain experimental information – such as time and date of the experiment, acquisition device, and version of the software – embedded in a result file (.db) generated by the ethoscope platform.

Usage

experiment_info(FILE)

Arguments

Value

a list containing fields for metadata entries

See Also

• load_ethoscope – to load the actual data

• list_result_files – to list available files

Link ethoscope metadata to the matching result files

Description

These functions augment metadata so it can be subsequently loaded (with load_ethoscope).

Usage

link_ethoscope_metadata_remote(
  x,
  remote_dir,
  result_dir,
  index_file = "index.txt",
  overwrite_local = FALSE,
  verbose = TRUE
)

link_ethoscope_metadata(x, result_dir = NULL, index_file = NULL)

Arguments

Details

These function will augment metadata from two different types of inputs (x):

1. A data.frame (recomended) In this case, the function will try to match requested data with data available on result_dir. The provided data.table::data.table has typically one row per requested individual and the columns (not necessarily in this order):

   • machine_name – the name of the machine in which the individual was (e.g. "ETHOSCOPE_001")

   • date – the start date of the experiment formatted as "YYYY-MM-DD"

   • region_id – the ROI in which the animal was. When not provided, all regions are queried.

   • time – the start time of the experiment formatted as "HH:MM:SS". When not provided, and multiple experiment for the same machine exist, only the last one is loaded.

   • ⁠???⁠ – any number of arbitrary columns* to associate conditions/treatments/genotypes/... to the previous columns.

2. The name of a CSV file that contains a table as described in 1.

3. A vector of .db files to be read.

Value

a data.table::data.table with the same rows as x, and extra columns for further data loading

References

• metadata tutorial – how to work with metadata

See Also

• load_ethoscope – to load the actual data

• list_result_files – to list available file

Examples

# Metadata with no region_id -> all regions will be loaded with the same metadata
dir <- paste0(scopr_example_dir(), "/ethoscope_results/")
data(no_region_id_metadata)
metadata <- link_ethoscope_metadata(no_region_id_metadata, dir)
print(metadata)

# Metadata with region_id ->  only stated regions will be loaded with specific metadata
data(region_id_metadata)
metadata <- link_ethoscope_metadata(region_id_metadata, dir)
print(metadata)

## Not run: 
# If your files are stored on a remote server,
# this will download to a local directory only the needed files
REMOTE <- "ftp://a/remote/server/"
LOCAL_DIR <- "/where/I/store/the/data/"
metadata <- link_ethoscope_metadata_remote(region_id_metadata,
                                           REMOTE,
                                           LOCAL_DIR)


## End(Not run)

List all available result files

Description

This function discovers all ethoscope result files and put them in a data.table::data.table. This is useful to figure out when and which experiments were performed.

Usage

list_result_files(result_dir, index_file = NULL)

Arguments

Value

a data.table::data.table. Each row is a single experimental file, and columns describe details such as its path, start date and time, and the name and id of the ethoscope used.

See Also

• load_ethoscope – to load the actual data

• experiment_info – to show the metadata of a specific experiment

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

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::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::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

Simple toy metadata defining three experiments, with one condition (test) per experiment. Implicitly, 20 individuals are in each experiment It serves as a simple example.

Description

Simple toy metadata defining three experiments, with one condition (test) per experiment. Implicitly, 20 individuals are in each experiment It serves as a simple example.

Usage

no_region_id_metadata

Format

An object of class data.frame with 3 rows and 4 columns.

Author(s)

Quentin Geissmann

Simple toy metadata experimental conditions for 15 individuals in three experiments. the condition (test) is linked to the experiments, and another condition (treatment) is per individual. It serves as a simple example. #'

Description

Simple toy metadata experimental conditions for 15 individuals in three experiments. the condition (test) is linked to the experiments, and another condition (treatment) is per individual. It serves as a simple example. #'

Usage

region_id_metadata

Format

An object of class data.frame with 15 rows and 6 columns.

Author(s)

Quentin Geissmann

Get path to scopr example

Description

scopr comes with a sample DAM2 files in its inst/extdata directory. scopr_example allow make them easy to access.

Usage

scopr_example(path = NULL)

scopr_example_dir()

Arguments

Examples

# list all files
scopr_example()