behavr: An S3 class, based on data.table, to store ethomics data
In rethomics/behavr: Canonical Data Structure for Behavioural Data

Description Usage Arguments Details References See Also Examples

View source: R/behavr.R

In modern behavioural biology, it is common to record long time series of several variables (such as position, angle, fluorescence and many others) on multiple individuals. In addition to large multivariate time series, each individual is associated with a set of metavariables (i.e. sex, genotype, treatment and lifespan ), which, together, form the metadata. Metavariables are crucial in so far as they generally "contain" the biological question. During analysis, it is therefore important to be able to access, alter and compute interactions between both variables and metavariables. behavr is a class that facilitates manipulation and storage of metadata and data in the same object. It is designed to be both memory-efficient and user-friendly. For instance, it abstracts joins between data and metavariables.

behavr(x, metadata)

setbehavr(x, metadata)

is.behavr(x)

`x`	data.table containing all measurements
`metadata`	data.table containing the metadata

A behavr table is a data.table. Therefore, it can be used by any function that would work on a data.frame or a data.table. Most of the operation such as variable creation, subsetting and joins are inherited from the data.table [] operator, following the convention DT[i,j,by] (see data table package for detail). These operations are applied on the data. Metadata can be accessed using meta=TRUE: DT[i,j,by, meta=TRUE], which allows extraction of subsets, creation of metavariables, etc.

Both x and metadata should have a column set as key with the same name (typically named id). behavr() copies x, whilst setbehavr() uses reference. metadata is always copied.

The relevant rethomic tutorial section – about metavariables and variables in this context

data.table – on which behavr is based
xmv – to join metavariables
rejoin – to join all metadata
bind_behavr_list – to merge several behavr tables

# We generate some metadata and data
set.seed(1)
met <- data.table::data.table(id = 1:5,
                              condition = letters[1:5],
                              sex = c("M", "M", "M", "F", "F"),
                              key = "id")
data <- met[  ,
              list(t = 1L:100L,
                  x = rnorm(100),
                  y = rnorm(100),
                  eating = runif(100) > .5 ),
              by = "id"]
# we store them together in a behavr object d
# d is a copy of the data
d <- behavr(data, met)
print(d)
summary(d)

# we can also convert data to a behavr table without copy:
setbehavr(data, met)
print(data)
summary(data)

### Operations are just like in data.table
# row subsetting:
d[t < 10]
# column subsetting:
d[, .(id, t, x)]
# making new columns inline:
d[, x2 := 1 - x]
### Using `meta = TRUE` applies the operation on the metadata
# making new metavariables:
d[, treatment := interaction(condition,sex), meta = TRUE]
d[meta = TRUE]