ggetho {ggetho}

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 ggplot 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 4 animals
metadata <- data.table(id = sprintf("toy_experiment|%02d", 1:4),
                   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
## Not run: 
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()`

## End(Not run)