
Calibrate Magnetic and Acceleration Data for 3-Axis Sensors
Source:R/geomag_calib.R
geomag_calib.RdCalibrates 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
GeoPressureRtag object containing magnetic and acceleration data.- calib_data
Logical, character, data frame, or
NULL. IfTRUE, uses calibration data from themagCalib/subfolder of the tag directory. IfFALSE, 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/zand optionallyis_staticandstap_id). IfNULL, 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 whenrm_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 datamagnetic_x,magnetic_y,magnetic_z: Raw magnetic datais_static: Logical static-sample classificationpitch,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 datamagnetic_xcp,magnetic_ycp,magnetic_zcp: Calibrated magnetic data projected in the same level frame (z up:magnetic_zcpis 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 intag$mag_calib, and the fitted parameters and argument values are stored intag$param$geomag_calib(see Diagnostics).
Details
Workflow and argument use
Classify static samples.
tag_static()addsis_staticto the magnetic data usingstatic_thr_hardandstatic_thr_outlier. Only static samples are used for the calibration fit, because their acceleration is the gravity direction.Select calibration data.
calib_dataselects a dedicated calibration dataset, a supplied data frame, or the field data intag$magnetic. With field data andstap_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.Filter calibration samples. When
rm_outlier = TRUE, samples whose raw magnetic norm differs from the median raw norm by more thancalib_thr_extremeare removed (spikes). Rows with incomplete magnetic axes are removed regardless ofrm_outlier.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 withoutstap_id), the field intensity and the inclination measured against the acceleration are constant (see Calibration model). The fitted transformation is applied to every row oftag$magnetic.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.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