Read one or more NEDAP or FIRE exports (CSV, TXT or Excel), map their
columns to the standard fields with a station format, and combine them
into one standard table for prep_visits().
read_station(
files,
station = NULL,
format = NULL,
pattern = "\\.(csv|txt|xlsx|xls)$",
sheet = 1,
verbose = 1,
...
)Character vector of file paths, or a single folder. For a
folder, all files matching pattern are read.
"nedap", "fire" or NULL (default). With NULL, the
station type is detected by trying the built-in formats on the column
names. Required when format is given.
NULL (default) for the built-in format of station, or a
station format: the path of a tab-separated format file, or a data
frame with columns field, column and optionally unit (see
station_format()).
Regular expression for file names when files is a
folder. Default: CSV, TXT, XLSX and XLS files (case-insensitive).
Sheet name or number for Excel files. Default 1.
0 (silent), 1 (summary, default) or 2 (details per file).
Further arguments passed to data.table::fread() (CSV and
TXT files).
A data.table with the standard fields of the station type
(see station_format()) plus source_file (file name without
folder):
responder (character, transponder number as recorded),
location (character), breed (character, if mapped);
entry_time, exit_time: POSIXct, clock time stored as UTC;
duration: seconds; feed_intake, trough_in, trough_out,
topup: g; weight: kg.
Fields the station type does not have, or optional fields missing in
the export, are NA. Columns of the export that are not mapped are
dropped. Attribute "station" holds the station type and
"station_format" the format used.
CSV and TXT files are read with data.table::fread(), which detects the
separator (comma, tab, semicolon). Excel files need the readxl package.
The column mapped to responder is always read as text, so leading
zeros are kept.
Columns are matched by name first (exact, then ignoring case and surrounding spaces). A number in the format is a column position, used when the export has no usable header. Positions are fragile: if the export software adds a column, every later field shifts without an error. Use names where possible.
Every file must contain all required fields of the station type. A
missing optional field (topup, breed) is filled with NA.
station_format() for the fields and the format file;
prep_visits() for the next step.
# Write the example data to two CSV files, then read them back
folder <- file.path(tempdir(), "fire_export")
dir.create(folder, showWarnings = FALSE)
data.table::fwrite(fire[fire$Location == 101, ], file.path(folder, "fire_101.csv"))
data.table::fwrite(fire[fire$Location == 102, ], file.path(folder, "fire_102.csv"))
raw <- read_station(folder)
#>
#> ── Reading 2 files ─────────────────────────────────────────────────────────────
#> ℹ Detected station type "fire"
#> ✔ Read 9794 rows from 2 files (FIRE)
head(raw)
#> responder location entry_time exit_time duration
#> <char> <char> <POSc> <POSc> <num>
#> 1: 35877 101 2023-12-19 14:15:39 2023-12-19 14:18:02 NA
#> 2: 35873 101 2023-12-19 14:18:03 2023-12-19 14:23:05 NA
#> 3: 35878 101 2023-12-19 14:23:15 2023-12-19 14:28:45 NA
#> 4: 35855 101 2023-12-19 14:29:05 2023-12-19 14:34:29 NA
#> 5: 35877 101 2023-12-19 14:34:30 2023-12-19 14:34:37 NA
#> 6: 35853 101 2023-12-19 14:34:38 2023-12-19 14:36:26 NA
#> feed_intake weight trough_in trough_out topup source_file
#> <num> <num> <num> <num> <num> <char>
#> 1: 46 67.6 678 632 286 fire_101.csv
#> 2: 248 60.8 632 384 0 fire_101.csv
#> 3: 201 70.8 670 469 286 fire_101.csv
#> 4: 121 51.2 755 634 286 fire_101.csv
#> 5: 0 0.0 634 634 0 fire_101.csv
#> 6: 0 88.6 634 634 0 fire_101.csv
attr(raw, "station")
#> [1] "fire"
# The built-in format, written as a template for other exports
station_format("fire", file = file.path(folder, "fire_format.txt"))
#> ✔ Station format written to /tmp/Rtmp93iRXT/fire_export/fire_format.txt
unlink(folder, recursive = TRUE)