Skip to contents

Calibrate Magnetic and Acceleration Data for 3-Axis Sensors

Source: R/geomag_calib.R
geomag_calib.Rd

Performs tilt compensation and magnetic calibration for 3-axis sensor data, with support for in situ and in vitro calibration routines, outlier removal, and computation of orientation and field parameters. This function is designed for use with GeoPressureR tag objects and can utilize calibration datasets if available.

Workflow

  1. Determine static/movement states: Classify each data point as static or moving by evaluating acceleration signals.

  2. Magnetic Data Calibration:

    • Select calibration data source (raw or from calibration dataset).

    • Optionally remove extreme or outlier values.

    • Fit and apply a calibration model (sphere/ellipse or their stap variants).

  3. Tilt Compensation:

    • Compute pitch and roll from acceleration.

    • Project gravity and calibrated magnetic data into the horizontal plane of the Earth frame.

  4. Orientation and Field Parameters:

    • Calculate heading, field intensity, and inclination.

    • Store calibration metadata and processed data in the tag object.

Usage

geomag_calib(
  tag,
  calib_data = NULL,
  calib_method = NULL,
  rm_outlier = TRUE,
  quiet = FALSE
)

Arguments

tag

A GeoPressureR tag object containing magnetic and acceleration data.

calib_data

Logical, character, or NULL. If TRUE, uses calibration data from magCalib/ subfolder. If FALSE, calibrates using in situ data. If a character path, uses calibration data from the specified directory. If NULL, auto-detects calibration folder.

calib_method

Character. Calibration method, one of "sphere", "ellipse", "near-sphere", "sphere_stap", or "ellipse_stap". If NULL, chosen automatically.

rm_outlier

Logical. If TRUE, removes outliers from calibration data (recommended).

quiet

Logical. If TRUE, suppresses progress messages.

Value

Modified GeoPressureR tag object. The $magnetic data frame contains:

  • date: Timestamp (POSIXct or numeric)

  • acceleration_x, acceleration_y, acceleration_z: Raw acceleration data

  • magnetic_x, magnetic_y, magnetic_z: Raw magnetic data

  • is_static: Scaled MAD of acceleration (0 = static, >1 = movement)

  • pitch, roll: Orientation angles (radian)

  • acceleration_xp, acceleration_yp, acceleration_zp: Gravity projected in NED frame

  • is_outlier: Logical, marks outliers in magnetic data

  • magnetic_xc, magnetic_yc, magnetic_zc: Calibrated magnetic data

  • magnetic_xcp, magnetic_ycp, magnetic_zcp: Calibrated magnetic data projected in NED frame

  • H: Heading (radian, North=0)

  • F: Magnetic field intensity (Gauss)

  • I: Inclination (radian) Also returns (invisibly) the calibration dataset used (tag$mag_calib) and calibration parameters (tag$param$geomag_calib).

Details

This function is part of the GeoMag package and is intended for use with animal-attached tags that record magnetic and acceleration data. It supports several calibration workflows and robust outlier detection.

Examples

library(GeoPressureR)
withr::with_dir(system.file("extdata", package = "GeoMag"), {
  tag <- tag_create("14DM", quiet = TRUE)
  tag <- tag_label(tag, quiet = TRUE)
  tag <- geomag_calib(tag, quiet = TRUE)
  tag$param$geomag_calib
  head(tag$magnetic)
})
#> ℹ Using raw magnetic data for calibrationd data
#>                  date magnetic_x magnetic_y magnetic_z acceleration_x
#> 1 2015-07-15 00:00:00    0.30368    0.12848   -0.14048     -1.0158691
#> 2 2015-07-15 04:00:00   -0.02016   -0.26800   -0.37840     -0.4349365
#> 3 2015-07-15 08:00:00   -0.19648    0.05904   -0.42176     -0.3776245
#> 4 2015-07-15 12:00:00    0.09968    0.16864   -0.33072     -0.9479370
#> 5 2015-07-15 16:00:00    0.28208   -0.12928   -0.22688     -0.9280396
#> 6 2015-07-15 20:00:00    0.26384   -0.12560   -0.26272     -1.0314331
#>   acceleration_y acceleration_z stap_id act is_static magnetic_xc magnetic_yc
#> 1    0.115905762      0.2175903       1   0      TRUE  0.39674525  0.14658447
#> 2   -0.013183594      1.9647217       1  16     FALSE  0.09063291 -0.25724728
#> 3   -0.115295410      1.1094971       1   5     FALSE -0.07521795  0.07863007
#> 4   -0.112731934      0.7674561       1   6     FALSE  0.20274948  0.18974057
#> 5   -0.008361816      1.0251465       1   4     FALSE  0.37535353 -0.11683502
#> 6   -0.004760742      0.1928101       1   0      TRUE  0.35765925 -0.11271694
#>   magnetic_zc     pitch         roll acceleration_xp acceleration_yp
#> 1  -0.1299802 1.3327149  0.489447620   -1.387779e-16    0.000000e+00
#> 2  -0.3812061 0.2178549 -0.006710058    0.000000e+00   -1.734723e-18
#> 3  -0.4327244 0.3264234 -0.103545172    0.000000e+00    0.000000e+00
#> 4  -0.3330282 0.8849994 -0.145847404    0.000000e+00    0.000000e+00
#> 5  -0.2184198 0.7357053 -0.008156523   -1.110223e-16    0.000000e+00
#> 6  -0.2562643 1.3859400 -0.024686342   -3.053113e-16    0.000000e+00
#>   acceleration_zp magnetic_xcp magnetic_ycp magnetic_zcp          H         F
#> 1        1.045356  0.049055307   0.19048308   -0.3963564 -1.3187423 0.4424801
#> 2        2.012331  0.006473343  -0.25979938   -0.3900909  1.5458848 0.4687308
#> 3        1.177657 -0.211865235   0.03348242   -0.3912581 -2.9848525 0.4461960
#> 4        1.224860 -0.147940672   0.13932683   -0.3830381 -2.3861709 0.4336088
#> 5        1.382842  0.132331817  -0.11861266   -0.4131189  0.7307824 0.4497198
#> 6        1.049311 -0.183346905  -0.11900818   -0.3981427  2.5658592 0.4541989
#>           I
#> 1 1.1101402
#> 2 0.9831143
#> 3 1.0693225
#> 4 1.0830101
#> 5 1.1645586
#> 6 1.0687138