Package 'scopr'

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

FILE	the name of the input file

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

x	object such as a data.frame, or the name of a file (see detail)
remote_dir	the url of the result directory on the data server
result_dir	the directory where all data are saved
index_file	the name of an index_file, in result_dir (useful for loading remote data).
overwrite_local	whether to download all files. The default, FALSE, is to only fetch files if they are newer on the remote.
verbose	whether to print progress (a logical)

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

result_dir	the root directory where all data are saved, or the path to a remote directory.
index_file	the name of an index_file, in result_dir (needed for loading remote data).

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

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.
...	extra arguments to be passed to FUN

Details

the linked metadata should be generated using link_ethoscope_metadata.

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

---

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

path	Name of file. If NULL, the example files will be listed.

Examples

# list all files
scopr_example()

---