Read sensor measurements into a GeoPressureR tag object. Optionally correct timestamps
for clock offset and drift, then crop to the recording period of interest.
Usage
tag_create(
id,
manufacturer = NULL,
crop_start = NULL,
crop_end = NULL,
directory = glue::glue("./data/raw-tag/{id}"),
pressure_file = NULL,
light_file = NULL,
acceleration_file = NULL,
temperature_external_file = NULL,
temperature_internal_file = NULL,
magnetic_file = NULL,
assert_pressure = TRUE,
quiet = FALSE,
time_shift = 0,
time_drift = 0,
time_reference = NULL,
mag_axis = c("right", "forward", "down")
)Arguments
- id
Unique tag identifier.
- manufacturer
Data format:
NULL(automatic),"soi","migratetech","bas","lund","prestag", or"tabular".- crop_start
Inclusive start of the corrected recording period, as POSIXct or character in UTC.
NULLkeeps all earlier data.- crop_end
Exclusive end of the corrected recording period, as POSIXct or character in UTC.
NULLkeeps all later data.- directory
Directory containing the original sensor files.
- pressure_file
Pressure input; tabular values must be in hPa. See Sensor files and Tabular input for input formats.
- light_file
Optional light input.
- acceleration_file
Optional acceleration input.
- temperature_external_file
Optional external or air-temperature input.
- temperature_internal_file
Optional internal or body-temperature input.
- magnetic_file
Optional magnetic and acceleration input with axis columns.
- assert_pressure
Logical; require pressure data in the returned tag.
- quiet
Logical; hide progress messages and sampling-interval warnings.
- time_shift
Constant correction in hours. A numeric value for all sensors or a named list for individual sensors (
pressure,light,acceleration,temperature_external,temperature_internal,magnetic). Default is zero.- time_drift
Linear correction in hours per year (365.25 days). A numeric value for all sensors or a named list for individual sensors. Default is zero;
-12 / 60subtracts 12 minutes per year. Convert hours per 30-day month by multiplying by365.25 / 30.- time_reference
Original recorded timestamp at which drift correction is zero, as POSIXct or character in UTC.
NULLuses the earliest measurement across all sensors. Supply a timestamp if the clock was synchronised at another time. Onlytime_shiftis added at the reference.- mag_axis
SOI only. Direction of the raw x, y and z magnetometer and accelerometer axes in the bird's forward-right-down frame, as three values among
"forward","backward","right","left","down"and"up", with one per axis. The defaultc("right", "forward", "down")is the standard mounting (raw y forward, raw x to the right). Usec("left", "backward", "down")for a tag mounted reversed, or e.g.c("forward", "left", "down")for a tag rotated by 90°. Stored intag$param$tag_create$mag_axis.
Value
A GeoPressureR tag containing param (see param_create()) and the available sensor
tables. Each sensor table has a UTC POSIXct date column and the following measurement columns:
pressure:valuein hPa.light:value, in units of the manufacturer (raw counts for SOI, lux for Migratetech).temperature_external,temperature_internal:valuein °C.acceleration:value(activity) and optionallymean_acceleration_z. See SOI sensor data for their definition on SOI tags.magnetic:magnetic_x,magnetic_y,magnetic_zin Gauss, andacceleration_x,acceleration_y,acceleration_zin g, in the forward-right-down frame.
Workflow
Data are read -> corrected -> cropped. Keep the original files and specify clock
corrections in tag_create(). All sensor timestamps are rounded to the nearest millisecond
after correction and before cropping, including when no correction is supplied. A warning
identifies sensors where rounding makes distinct timestamps identical; all measurements are kept.
Pressure is required by default; use assert_pressure = FALSE
for tags without pressure data.
Sensor files
By default, files are read from ./data/raw-tag/{id} and the manufacturer is detected from
the directory where possible. Set manufacturer explicitly when needed, including for PresTag.
Sensor file arguments accept a file path or the end of a filename, where * matches any
characters and case is ignored, such as "*.pressure". Supported formats are:
SOI (
"soi"): pressure*.pressure, light*.glf, acceleration*.acceleration, external temperature*.temperatureor*.airtemperature, internal temperature*.bodytemperature, and magnetic data*.magnetic.Migratetech (
"migratetech"): pressure and acceleration*.deg, light*.lux.BAS (
"bas"): light*.ligonly; useassert_pressure = FALSE.Lund CAnMove (
"lund"): pressure*_press.xlsx, light and acceleration both fromacceleration_file(*_acc.xlsx).PresTag (
"prestag"): pressure*.txt.
Manufacturer readers detect available sensor files when their arguments are NULL.
For SOI, use NA to skip a sensor.
SOI sensor data
SOI files are text exports of the SOI GeoLocator decoder: six header lines followed by
dd.mm.yyyy HH:MM rows in UTC. Each sensor is sampled every BaseLoggingInterval ×
<sensor>LoggingInterval minutes, as configured with BirdTagManager and recorded in the
*.settings file (read into tag$param$tag_create$settings, with the normalised model and
firmware); a sensor interval of 0 means the sensor
was off. The tag only stores a value when it changes, and the decoder repeats it until the next
change. Rows that the decoder could not reconstruct are written as -2 in all columns; they are
set to NA, except in temperature_external, where they cannot be told apart from a −2 °C
measurement.
pressure(*.pressure): hPa, with 1 hPa resolution (about 8 m of altitude).light(*.glf): raw sensor counts stored as a floating-point code (2^exponent × mantissa, up to about 4.2 × 10^6), not lux.acceleration(*.acceleration):valueis the activity, the sum of absolute differences of successive z-axis acceleration over 32 measurements at 10 Hz (0–127, unitless);mean_acceleration_zis the mean z-axis acceleration of the same measurements (−64 to 63, raw counts), a proxy for body pitch.temperature_external(*.temperatureor*.AirTemperature): air temperature in °C from the pressure sensor, with 1 °C resolution between −15 and 48 °C.temperature_internal(*.BodyTemperature, hardware v2.4 and later): temperature in °C inside the tag, with about 1 °C resolution.magnetic(*.magnetic): single 3-axis magnetometer and accelerometer measurements, converted to Gauss and g according to the hardware version in*.settings(LSM303D up to v2.3, LSM303AGR from v2.4) and rotated to the forward-right-down frame according tomag_axis, by default with raw y forward and raw x to the right. For a tag mounted reversed, usemag_axis = c("left", "backward", "down")(a warning is shown when the tag rests tilted backwards). Without*.settings, magnetic data are not read.
The decoder does not correct clock drift. *.settings records the tag clock
(StopTimeRTC) and the computer clock (StopTimeReference) at download, and their difference
is stored in tag$param$tag_create$settings$clock_drift in minutes: positive when the tag clock
is ahead. To correct a linear drift, use time_drift (e.g. -clock_drift / 60 divided by the deployment
duration in years) with time_reference set to StarttimeRTC, when the clock was set.
Tabular input
With manufacturer = "tabular", each sensor argument accepts a data.frame, tibble, or CSV path.
Tables need a UTC POSIXct date column and a value column; pressure values must be in hPa.
Magnetic tables instead use the axis columns listed under Value below.
CSV files use datetime instead of date, with UTC timestamps such as
"2025-01-01T00:00:00"; fractional seconds are supported. CSV files named pressure.csv,
light.csv, etc. can be detected automatically from directory. Omit optional tabular sensors
with NULL. An in-memory pressure_file also selects tabular input automatically.
Clock correction
time_shiftadds a constant offset in hours.time_driftadds a linear correction in hours per year (365.25 days).time_referenceis the original recorded time at which drift correction is zero. By default, it is the earliest measurement across all sensors, before shifts or cropping.
Positive corrections add time; negative corrections subtract time. Each correction accepts
one value for all sensors or a named list, such as list(pressure = -12 / 60, light = 0).
Sensors omitted from a list receive zero; entries for absent sensors are ignored. All sensors
share the reference, regardless of recording duration. Drift uses the original timestamps,
before adding the shift, and extends linearly before an explicit reference.
Correction settings and the reference used for drift are recorded in tag$param$tag_create.
When changing corrections, rerun the analysis from the original data and regenerate labels
that rely on exact timestamps, including TRAINSET labels.
Cropping
Cropping uses corrected UTC timestamps: crop_start is inclusive and crop_end is exclusive.
Leave either boundary as NULL to keep all data on that side.
See also
Other tag:
print.tag(),
read_stap(),
tag_set_map(),
tag_stap_daily()
Examples
withr::with_dir(system.file("extdata", package = "GeoPressureR"), {
# Read available sensors.
tag <- tag_create("18LX", quiet = TRUE)
# Crop to the period of interest.
tag <- tag_create("18LX",
crop_start = "2017-08-01", crop_end = "2017-08-05", quiet = TRUE
)
# Select files explicitly when several match the same pattern.
tag <- tag_create("CB621",
pressure_file = "CB621_BAR.deg", light_file = "CB621.lux", quiet = TRUE
)
# Correct selected sensors using a shared recorded reference.
tag <- tag_create("18LX",
time_shift = list(light = 2), time_drift = list(pressure = -12 / 60),
time_reference = "2017-06-20", quiet = TRUE
)
})
# Read an in-memory table and apply the same correction to all sensors.
pressure <- data.frame(
date = as.POSIXct("2025-01-01", tz = "UTC") + (0:48) * 1800,
value = rep(1000, 49)
)
tag <- tag_create("example", pressure_file = pressure,
time_shift = 2, time_drift = -12 / 60, quiet = TRUE
)
