events_v1: Fetch events data for SNB version _v1

In mpio-be/SNB2: Smart Nest-box Data Management

Fetch events data for SNB version _v1

Description

This function fetches individual in and out events based on a time threshold and transponder readings. If two transponder readings occur close in time, the rows in between are removed, because it is unclear to which individual this data belongs, and the information about the direction of the movement is marked as "unclear". Directions are assigned based on the light barriers and the data is grouped together accordingly.

Usage

events_v1(
  x,
  setTZ = "Etc/GMT-2",
  group_ins_and_outs = TRUE,
  FUN = "translate_validity_v1",
  time_threshold = 2,
  max_distance = 16 * 60 * 60,
  silent = FALSE
)

Arguments

x	a data.table, the "raw" data, as provided for instance by the function dbq()
group_ins_and_outs	logical. Should INs and OUTs be grouped together? Defaults to TRUE.
FUN	the name of a function. How should detailed directions based on light barriers be transferred into readable directions? Defaults to the function translate_validity_v1.
time_threshold	Time in seconds. If the time difference between two consecutive lines is larger or equal to time_threshold, the rows will be treated as independent pieces of activity. Defaults to 2.
max_distance	Maximum time in secondswithin which INs and OUTs will be grouped together. Example: Set relatively small when considering provisioning data, large when looking at overnight sleep.
silent	logical. Should the stats about the data quality be printed? Defaults to TRUE.

Details

Each subfunction performs a specific task. The tasks can be described as follows:

1. fetch_ins_outs_v1: Separate different pieces of activity and assign the corresponding transponder. Consecutive rows are assigned to different pieces of activity, if the time difference between consecutive lines is smaller than time_threshold seconds, and if the transponder number changes.

2. assign_direction_v1: Remove any event that has only activity at one light barrier and no transponder connected to it (for example FRONT or BACK without transponder). Then, fetch time difference between conscutive pieces of activity and assign a transponder to them, if possible. Assign which light barrier is triggered first (=position of the bird at the beginning of the activity: o means "outside", i means "inside"; "O/I" therefore means that the event started on the outside and ended on the inside and therefore is an "IN") and which light barrier is triggered last (=position of the bird at the end of the activity). If more than one transponder is connected to one event, split the event, remove any lines between the different transponders, and set the respective beginning and end directions to "unclear".

3. concat_events_v1: Combine activities that belong together based on the transponder reading, and on the light barrier information using the following rulse:

   • If activity starts with the bird being outside, never combine with the previous event.

   • If activity ends with the bird being outside, never combine with the previous event.

   • If the start position of the bird is unclear, only combine if the previous activity ended with an "inside". Mark the start position with a lower-case.

   • If the end position of the bird is unclear, only combine if the next activity starts with an "inside". Mark the start position with a lower-case. Remove redundant information.

4. translate_validity_v1: Function that assigns easy-to-interpret directions (e.g. "IN-OUT") to the detailed but confusing directions given by the light barriers (e.g. "o/I|I/O"). The default function uses the following rules (in the specified order):

   1. assign IN-OUT to all lines (note that some of this will be over-written by the next rules!)

   2. make everything where only a single activity is recorded (e.g. concat_events_v2 did not combine 2 or more events!) as FRONT unless...

   3. unless it is I/O (=OUT) or O/I (=IN)

Value

a data.table where individual ins and outs are grouped together that is homologous to the one returned by the function events_v2. For details about the output see events_v2. Note that the column "path" that links to the raw data is here called "id" for reasons of backwards-compatibility.

Note

There is a wrapper function which can be used to fetch data across the two databases and across boxes: eva

Author(s)

LS

See Also

eva

Examples

#Note that although the raw data differ stubstantially, the functions events_v1 and events_v2 
#can be used similarly.
#The help is therefore kept short here, see ?events_v2 for further examples.
con = dbcon() #or other connection to database
x_raw = dbq(con, paste0("SELECT * FROM SNBatWESTERHOLZ.b033 
WHERE datetime_ >= '2016-05-01 00:00:00' AND datetime_ <= '2016-05-31 12:00:00'"))
x_raw[, box := 33]
x = events_v1(x_raw, group_ins_and_outs = TRUE, FUN = "translate_validity_v1", 
         time_threshold = 2, max_distance = 16*60*60, silent = FALSE)
plot(x)

#fetch the individual pieces of activity
x = events_v1(x_raw, group_ins_and_outs = FALSE, FUN = "translate_validity_v1", 
         time_threshold = 2, max_distance = 16*60*60, silent = FALSE)

mpio-be/SNB2 documentation built on Sept. 17, 2024, 4:27 p.m.