Skip to contents

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. NULL keeps all earlier data.

crop_end

Exclusive end of the corrected recording period, as POSIXct or character in UTC. NULL keeps 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 / 60 subtracts 12 minutes per year. Convert hours per 30-day month by multiplying by 365.25 / 30.

time_reference

Original recorded timestamp at which drift correction is zero, as POSIXct or character in UTC. NULL uses the earliest measurement across all sensors. Supply a timestamp if the clock was synchronised at another time. Only time_shift is 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 default c("right", "forward", "down") is the standard mounting (raw y forward, raw x to the right). Use c("left", "backward", "down") for a tag mounted reversed, or e.g. c("forward", "left", "down") for a tag rotated by 90°. Stored in tag$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: value in hPa.

  • light: value, in units of the manufacturer (raw counts for SOI, lux for Migratetech).

  • temperature_external, temperature_internal: value in °C.

  • acceleration: value (activity) and optionally mean_acceleration_z. See SOI sensor data for their definition on SOI tags.

  • magnetic: magnetic_x, magnetic_y, magnetic_z in Gauss, and acceleration_x, acceleration_y, acceleration_z in 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 *.temperature or *.airtemperature, internal temperature *.bodytemperature, and magnetic data *.magnetic.

  • Migratetech ("migratetech"): pressure and acceleration *.deg, light *.lux.

  • BAS ("bas"): light *.lig only; use assert_pressure = FALSE.

  • Lund CAnMove ("lund"): pressure *_press.xlsx, light and acceleration both from acceleration_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): value is the activity, the sum of absolute differences of successive z-axis acceleration over 32 measurements at 10 Hz (0–127, unitless); mean_acceleration_z is the mean z-axis acceleration of the same measurements (−64 to 63, raw counts), a proxy for body pitch.

  • temperature_external (*.temperature or *.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 to mag_axis, by default with raw y forward and raw x to the right. For a tag mounted reversed, use mag_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_shift adds a constant offset in hours.

  • time_drift adds a linear correction in hours per year (365.25 days).

  • time_reference is 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.

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
)