read_dam_file: Reads data from a single DAM2 single beam or a DAM5 multibeam file

Description

This function retrieves activity data in a DAMS text file. It allows selection of a date range and channels (i.e. regions).

Usage

read_dam_file(
  path,
  region_id = 1:32,
  start_datetime = -Inf,
  stop_datetime = +Inf,
  tz = "UTC",
  date_format = "%d %b %y"
)

Value

A behavr table. The metadata contains an autogenerated id per animal. The data has the columns:

id -- autogenerated unique identifier, one per animal
t -- time
activity -- number of beam crosses

Arguments

path: location of the file to read (character)
region_id: vector of unique regions to read
start_datetime, stop_datetime: the start and the end of an the experiment (see details)
tz: the timezone (see OlsonNames for a list)
date_format: the format of the dates in the DAM file (see details)

Details

start_datetime and stop_datetime are formatted as "YYYY-MM-DD HH:MM:SS". start_datetime is used as the reference time (ZT0). Therefore, if you are interested in circadian analysis and D -> L transitions are at 10:00:00, you probably want to set start_datetime = "YYYY-MM-DD 10:00:00".

According to the acquisition system, the date format can be inconsistently formatted between DAM Systems. Specify the format using strptime syntax. For instance:

"%d %b %y" -- the default, to parse "15 Nov 2019"
"%d-%m-%y" -- to parse "15-11-2019"
"%Y-%m-%d" -- the default to parse "2019-11-15"

Examples

Run this code

path <- damr_example("M064.txt")
dt <- read_dam_file(path, region_id = c(1:3), start_datetime = "2017-06-30 15:00:00")
print(dt)