Skip to contents

Calibrates 3-axis magnetic sensor data, performs tilt compensation, and computes magnetic field intensity, inclination, and heading.

Usage

geomag_calib(
  tag,
  calib_data = NULL,
  calib_method = c("ellipse", "sphere"),
  rm_outlier = TRUE,
  static_thr_hard = 0.1,
  static_thr_outlier = 3,
  quiet = FALSE,
  calib_thr_extreme = 1
)

Arguments

tag

A GeoPressureR tag object containing magnetic and acceleration data.

calib_data

Logical, character, data frame, or NULL. If TRUE, uses calibration data from the magCalib/ subfolder of the tag directory. If FALSE, calibrates using field-data calibration. If a character path, uses calibration data from the specified directory. If a data frame, uses it directly as the calibration dataset (date, magnetic_x/y/z, acceleration_x/y/z and optionally is_static and stap_id). If NULL, auto-detects calibration folder.

calib_method

Character. "ellipse" (default) corrects hard- and soft-iron effects, "sphere" only the hard-iron offset.

rm_outlier

Logical. If TRUE, applies the magnetic calibration-data filters described in Workflow and argument use.

static_thr_hard

Numeric. Hard threshold around 1 g used when classifying static samples. Passed to tag_static().

static_thr_outlier

Numeric. MAD threshold used to remove outliers among candidate static samples. Passed to tag_static().

quiet

Logical. If TRUE, suppresses progress messages.

calib_thr_extreme

Numeric. Maximum absolute difference (G) between the raw magnetic norm (sqrt(x^2 + y^2 + z^2)) and its median, used when rm_outlier = TRUE.

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: Logical static-sample classification

  • pitch, roll: Orientation angles (radian)

  • acceleration_xp, acceleration_yp, acceleration_zp: Acceleration projected in the level frame of the bird (x and y horizontal, z vertical and pointing up: about +1 g at rest)

  • magnetic_xc, magnetic_yc, magnetic_zc: Calibrated magnetic data

  • magnetic_xcp, magnetic_ycp, magnetic_zcp: Calibrated magnetic data projected in the same level frame (z up: magnetic_zcp is negative where the inclination is positive)

  • H: Magnetic heading / yaw (degrees). Computed from the calibrated magnetic axes after tilt compensation. 0 = North, 90 = East, 180 = South, 270 = West. Range [0, 360).

  • F: Magnetic field intensity (Gauss)

  • I: Inclination (radian) The calibration dataset used is stored in tag$mag_calib, and the fitted parameters and argument values are stored in tag$param$geomag_calib (see Diagnostics).

Details

Workflow and argument use

  1. Classify static samples. tag_static() adds is_static to the magnetic data using static_thr_hard and static_thr_outlier. Only static samples are used for the calibration fit, because their acceleration is the gravity direction.

  2. Select calibration data. calib_data selects a dedicated calibration dataset, a supplied data frame, or the field data in tag$magnetic. With field data and stap_id, the samples of flights with at least 12 samples (e.g. 1 h at 5 min) are added with the flight-mean acceleration as gravity direction: birds that rest in a single orientation (e.g. owls) only rotate in flight. Static samples are then thinned to three times the flight samples.

  3. Filter calibration samples. When rm_outlier = TRUE, samples whose raw magnetic norm differs from the median raw norm by more than calib_thr_extreme are removed (spikes). Rows with incomplete magnetic axes are removed regardless of rm_outlier.

  4. Fit the calibration model. The hard-iron offset (and the soft-iron shape for calib_method = "ellipse") is fitted so that, within each stationary period (or day without stap_id), the field intensity and the inclination measured against the acceleration are constant (see Calibration model). The fitted transformation is applied to every row of tag$magnetic.

  5. Perform tilt compensation. Pitch and roll are computed from the acceleration, then the acceleration and calibrated magnetic vectors are rotated into the Earth frame. Flight samples (non-integer stap_id) use the mean acceleration of their flight, which removes most of the wingbeat-induced tilt error of single snapshots.

  6. Compute and store outputs. Field intensity, inclination, heading, calibration data, and fitted parameters are stored in the returned tag.

Calibration model

The notation follows Appendix A of Nussbaumer et al. (2026) (doi:10.1111/2041-210x.70355 ). The raw magnetic vector \(\mathbf{B}_i\) of sample \(i\) is corrected for a hard-iron offset \(\mathbf{o}\) and a soft-iron ellipsoid of rotation \(\mathbf{R}\) and radii \(\mathbf{A} = \mathrm{diag}(a_1, a_2, a_3)\): $$\mathbf{M}_i = \mathbf{R}^\top \mathbf{A}^{-1} \mathbf{R} (\mathbf{B}_i - \mathbf{o}), \qquad a_1 a_2 a_3 = 1.$$ "ellipse" fits \(\mathbf{o}\), \(\mathbf{R}\) and the shape of \(\mathbf{A}\) (8 parameters); "sphere" fits \(\mathbf{o}\) only (\(\mathbf{R} = \mathbf{A} = \mathbf{I}\)). The product of the radii is 1, so the sensor scale is kept.

Within a group \(g\) (stationary period, or day without stap_id) the Earth's field is fixed. The intensity \(F_i = \|\mathbf{M}_i\|\) and the inclination, measured against the unit acceleration \(\hat{\mathbf{a}}_i\) (gravity on static samples), $$\sin I_i = -\frac{\mathbf{M}_i \cdot \hat{\mathbf{a}}_i}{\|\mathbf{M}_i\|},$$ are therefore the same for every sample of the group, whatever the posture of the bird. The group values \(F_g\) and \(\sin I_g\) are not free parameters: they are the group means, or the WMM values (height 0, mean date of the period) at stationary periods of known location (tag$stap$known_lat). The fit minimises $$J(\mathbf{o}, \mathbf{R}, \mathbf{A}) = \sum_i \left[ h(r_i^F) + h(r_i^I) \right] + P_F + P_A,$$ with the residuals \(r_i^F = (F_i - F_{g_i}) / 0.45\) G and \(r_i^I = \sin I_i - \sin I_{g_i}\), and the pseudo-Huber loss \(h(r) = \delta^2 (\sqrt{1 + (r/\delta)^2} - 1)\), \(\delta = 0.02\). The loss is quadratic for small residuals and linear for large ones, which limits the weight of spikes and non-static samples. The penalty \(P_F\) keeps \(F_g\) of the groups of unknown location within 0.18-0.75 G, and \(P_A\) ("ellipse" only) pulls the ellipsoid towards a sphere when the data do not constrain its shape. \(J\) is minimised with BFGS (stats::optim()) from three starting offsets (an algebraic sphere fit, and the mean raw field shifted up or down along gravity), on at most 20,000 evenly thinned samples.

Give at least one stationary period with a known location (e.g. the equipment site, with GeoPressureR::tag_set_map()): without it, the intensity is not anchored, can be biased, and geomag_calib() warns.

Diagnostics

tag$param$geomag_calib contains offset (\(\mathbf{o}\)), rotM (\(\mathbf{R}^\top\)), radius_shape (\(a_1, a_2, a_3\)), radius_amplitude (\(F_g\), indexed by stap_id) and optim, a list with:

  • n_obs, n_group, n_known: samples, groups and groups of known location in the fit.

  • rmse_F: RMS of \(r_i^F\) (relative to 0.45 G).

  • rmse_I: RMS of the inclination residual \(I_i - I_{g_i}\), in degrees.

  • fit_rmse: RMS of \(F_i / F_{g_i} - 1\).

  • convergence, value: stats::optim() convergence code (0 = converged) and final \(J\).

Check that n_known is at least 1 and convergence is 0. A large rmse_I points to non-static samples, a poor static classification, or a tag whose orientation changed during the deployment. On a benchmark of 77 tags from 13 species (5-min to 6-hourly logging), the median static inclination error at stationary periods of unknown location was 2.1 degrees (2.3 degrees for the previous default ellipse_stap, which failed on 5 tags).

Examples

library(GeoPressureR)
#> Registered S3 method overwritten by 'GeoPressureR':
#>   method    from   
#>   print.tag pkgdown
withr::with_dir(system.file("extdata", package = "GeoMagR"), {
  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)
})
#>                  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 is_static magnetic_xc magnetic_yc
#> 1   -0.115905762      0.2175903       1      TRUE -0.41759985 -0.14551367
#> 2    0.013183594      1.9647217       1     FALSE -0.10491370  0.25590610
#> 3    0.115295410      1.1094971       1     FALSE  0.06258616 -0.07525642
#> 4    0.112731934      0.7674561       1     FALSE -0.22093142 -0.18668458
#> 5    0.008361816      1.0251465       1     FALSE -0.39511857  0.11528836
#> 6    0.004760742      0.1928101       1      TRUE -0.37728113  0.11141106
#>   magnetic_zc      pitch         roll acceleration_xp acceleration_yp
#> 1  -0.1340378 -1.3327149 -0.489447620    1.110223e-16    0.000000e+00
#> 2  -0.3827993 -0.2178549  0.006710058   -5.551115e-17    1.734723e-18
#> 3  -0.4319543 -0.3264234  0.103545172   -5.551115e-17    0.000000e+00
#> 4  -0.3342130 -0.8849994  0.145847404   -1.110223e-16    0.000000e+00
#> 5  -0.2224450 -0.7357053  0.008156523    2.220446e-16    0.000000e+00
#> 6  -0.2598634 -1.3859400  0.024686342    2.775558e-16    0.000000e+00
#>   acceleration_zp magnetic_xcp magnetic_ycp magnetic_zcp         F        I
#> 1        1.045356  -0.05000420  -0.19144563   -0.4175861 0.4620931 1.128296
#> 2        2.012331  -0.02007029   0.25846892   -0.3947418 0.4722606 0.989690
#> 3        1.177657   0.19954301  -0.03020645   -0.3942527 0.4429052 1.097677
#> 4        1.224860   0.13698968  -0.13613110   -0.3975705 0.4419956 1.118600
#> 5        1.382842  -0.14427506   0.11709888   -0.4293768 0.4678588 1.162374
#> 6        1.049311   0.18330871   0.11779154   -0.4180975 0.4714684 1.090371
#>            H
#> 1 104.638207
#> 2 265.559853
#> 3   8.607974
#> 4  44.819885
#> 5 219.064040
#> 6 327.275784