This vignette contains executable examples for the intended use of the R
package triact. Most of the functionalities are presented with
default parameters. We recommend that you also read the help pages to
learn more about the many parameters that can be used to customize the
behavior of the methods in triact. Furthermore, background and
rationale of the implemented analyses are described in detail in the
following publication:
Simmler M., Brouwers S. P., 2023. triact package for R: Analyzing the lying behavior of cows from accelerometer data, under review
Since triact is typically used with accelerometer data with
sampling frequency of ≥1 Hz, it is advisable to set R’s global option
digits.secs to >=1 in order to enable the printing of
fractional seconds.
options(digits.secs = 1)
Via the global option triact_table the type of tables
returned by triact can be specified. Options are
"data.frame" (the default), "tibble", and
"data.table".
options(triact_table = "data.frame")
All functionalities of the triact R package are documented
on the help page of the Triact R6 class.
?Triact
The triact R package includes two raw data files from triaxial
accelerometers (MSR145, MSR Electronics, Switzerland) attached to the
left hind leg of dairy cows. The sampling frequency was 5 Hz. Each file
represents one day of recording of one cow.
input_dir <- system.file("extdata", package = "triact")
files <- list.files(input_dir)
print(files)## [1] "cow01_5hz.csv" "cow02_5hz.csv"
Inspecting one of the files reveals a file header and the
semicolon-separated data starting after the line with
"*Data“. This is an example of what files imported by
triact might look like. However, triact can handle any
kind of delimiter-separated text files, with or without an arbitrary
file header (which is ignored during import).
cat(paste(readLines(file.path(input_dir, files[1]), n = 30), collapse = "\n"))## *CREATOR
## msr_cutter.exe;[V6.06.02]
## msr2csv.exe;[V6.06.02]
##
## *STARTTIME
## 2021-06-29;06:00:00;
##
## *MODUL
## NAME;MSR314553;MSR314553;MSR314553
## *NAME
## NAME;6A;6A;6A
##
## ID;[C26113 V5.66];[C26113 V5.66];[C26113 V5.66]
##
## *CHANNEL
## TIME;ACC x;ACC y;ACC z
##
## *UNIT
## ;G;G;G
##
## *LIMITS
## ALARM;;;
## RECRD;;;
## LIMIT1;;;
## LIMIT2;;;
##
## *DATA
## 2021-06-29 06:00:00.055;-0.048;1.032;-0.063
## 2021-06-29 06:00:00.258;-0.048;1.000;-0.063
## 2021-06-29 06:00:00.461;-0.048;1.000;-0.063
The typical triact workflow starts by creating a new object
of the Triact class.
my_triact <- Triact$new()
Acceleration data is then imported into the Triact
object (here named ‘my_triact’). The $load_files() method
can be used to import any raw data files, which are delimiter-separated
text files. If you are starting with a new file format you may want to
select one or a few (small) files to find out how to specify the
method’s argument to enable correct import from the file(s). Once this
is done, you move on to process all your files. Examine your file format
in a plain text editor or in R (as above).
my_triact$load_files(input = input_dir,
id_substring = c(1, 5),
timeFwdUpRight_cols = c(1, -2, 3, -4),
time_format = "%Y-%m-%d %H:%M:%OS",
tz = "Europe/Zurich",
skip = "DATA",
sep = ";",
header = FALSE,
dec = ".")
The parameters as used above in the call of
$load_files() have the following effects:
With id_substring = c(1, 5) we specify which part of
the filenames represents the unique identifier of the cows, by
indicating the start and end character positions c(start, end). The
example files are named “cow01_5hz.csv” and “cow02_5hz.csv”. The
substring from the first to the fifth character can here serve as unique
identifier, therefore c(1, 5). Alternatively, we could have
used a perl-like regular expression that matches the substring
("^\\w{5}", see ?regex).
With timeFwdUpRight_cols = c(1, -2, 3, -4) we map
the columns as found in the files to the time, and the
forward, up, and right accelerations as
understood by triact. Fig. 1a shows the accelerometer used to
collect the example data with the axis directions as defined by the
manufacturer (XYZ). Fig. 1b shows the directions as used in
triact. To collect the example data, the accelerometer was
mounted to the outside of the left hind leg with the Y axis pointing in
Up direction, X in opposite direction of forward
(directed backwards), and Z in opposite direction of right
(directed left). In timeFwdUpRight_cols = c(1, -2, 3, -4),
the first number indicates in which column in the file the timestamp
(data-time) is located, here in the first column. The second number
indicates which column in the file maps to forward
acceleration, here the second column, but with negative mathematical
sign as X was pointing in the opposite direction of forward
(hence -2). The third number indicates which column in the file maps to
the up axis, here the third (the Y data). The last number
indicates which column in the file maps to the right
acceleration, here the fourth, but with opposite mathematical sign as Z
was pointing in the opposite direction of right (hence
-4).
With time_format = "%Y-%m-%d %H:%M:%OS" we specify
the format of the timestamps as found in the files. The syntax is
described in ?strptime.
With tz = "Europe/Zurich" we specify the time zone
of the timestamps in the files. This is usually irrelevant if you do not
work across time zones as your system’s time zone is used as
default.
With skip = "DATA" we specify the line in the files
to start reading data, here using a (sub)string of that line (see file
inspection above). Alternatively we could have used an integer
indicating the number of lines to skip before reading data.
With sep = ";" we specify the separator character
that separates columns in the files.
With header = FALSE we specify whether the first
column of the data (after considering skip) contains column
names.
Finally, with dec = "." we specify the decimal
separator.