ggetho: Prepare a ggplot object to represent behavioural data

In rethomics/ggetho: Visualisation of High-Throughput Behavioural (i.e. Ethomics) Data

Prepare a ggplot object to represent behavioural data

Description

This function summarises a variable of interest (y or z axis) in order to subsequently represent it over time (x axis) (using layers provided either by ggplot2 or ggetho).

Usage

ggetho(data, mapping, summary_FUN = mean,
  summary_time_window = mins(30), time_wrap = NULL, time_offset = 0,
  multiplot = NULL, multiplot_period = hours(24), ...)

Arguments

data	behavr::behavr table containing the data and metadata
mapping	default list of aesthetic mappings to use for plot
summary_FUN	method (function) used to summarise variable over time (typically, the mean)
summary_time_window	width (in seconds) of the time window to compute a summary on
time_wrap	time (in seconds) used to wrap the data (see details)
time_offset	time offset (i.e. phase, in seconds) when using time_wrap
multiplot	integer, greater than two, or NULL, the default (see details)
multiplot_period	the duration of the period when mutiplotting (see details)
...	additional arguments to be passed to ggplot2::ggplot()

Details

time_wrap is typically used to express time relatively to the start of the the day. In other words, it can help be used to pull all days together in one representative day. In this case, time_wrap = hours(24). Instead of representing data from the start of the day, it can be done from any offset, using time_offset. For instance, time_offset = hours(12) puts the circadian reference (ZT0) in the middle of the plot.

Multiplotting is a generalisation of double-plotting, triple-plotting... This type or representation is useful to understand periodic behaviours. When multiplot is not NULL, data is repeated as many time as its value, along the x axis. The y axis is then the period (typically the day) onset. It is possible to set duration of the period, which is typically 24 h to arbitrary values using the multiplot_period argument.

Value

An initial plot object that can be further edited.

References

• The relevant rethomic tutorial section

See Also

• stat_pop_etho to show population trend by aggregating individuals over time

• stat_tile_etho to show variable of interest as colour intensity

• stat_ld_annotations to show light and dark phases on the plot

Examples

# We start by making a dataset with 20 animals
metadata <- data.table(id = sprintf("toy_experiment|%02d", 1:20),
                   condition = c("A", "B"))
dt <- toy_activity_data(metadata, 3)
# We build a plot object with **nothing inside** (just the axis)
# we want to show proportion of time sleeping  on the y axis:
pl <- ggetho(dt, aes(y = asleep))
pl
# Sometimes, the variable of interest in not on the y axis, but on z axis (colour scale).
# When we do not provide a y axis,
# ggetho will make an ID fo each animal and display them on separate rows
pl <- ggetho(dt, aes(z = asleep))
pl
# this one is the same type, but it groups the animals by condition
pl <- ggetho(dt, aes(z = asleep, y = condition))
pl
# sorting with paste
pl <- ggetho(dt, aes(z = asleep,y = paste(condition, id)))
pl

# we want to summarise (wrap) data along a circadian day:
pl <- ggetho(dt, aes(y = asleep), time_wrap = hours(24))
pl

# double-plotted actogram:
pl <- ggetho(dt,
              aes(z = moving),
              multiplot = 2,
              multiplot_period = hours(24))
pl
# then use `+ stat_tile_etho()` , or `+ stat_bar_tile_etho()`

rethomics/ggetho documentation built on Nov. 20, 2022, 11:18 a.m.