Skip to contents

Calibrate Magnetic and Acceleration Data for 3-Axis Sensors

Source: R/geomag_calib.R
geomag_calib.Rd

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 = NULL,
  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 magCalib/ subfolder. 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. 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, 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. Upper threshold on the raw magnetic vector norm (sqrt(x^2 + y^2 + z^2)) 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: Projected acceleration in NED frame

  • magnetic_xc, magnetic_yc, magnetic_zc: Calibrated magnetic data

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

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

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. These arguments only control the static classification; is_static is not used to select observations for the calibration fit.

  2. Select calibration data. calib_data selects a dedicated calibration dataset, a supplied data frame, or the field data in tag$magnetic.

  3. Filter calibration samples. When rm_outlier = TRUE, calib_thr_extreme first removes observations with a large raw magnetic vector norm. A preliminary sphere fit is then used to retain centered norms between 0.25 and 0.65 and to remove MAD outliers, within stationary periods when stap_id is available. This MAD filter is independent of static_thr_outlier. Rows with incomplete magnetic axes are removed regardless of rm_outlier.

  4. Choose and fit the calibration model. calib_method selects the sphere, ellipsoid, or stationary-period model. If it is NULL, "ellipse_stap" is selected when the calibration data contain stap_id and tag$stap contains known latitudes; otherwise, "ellipse" is used. The fitted transformation is applied to every row of tag$magnetic, not only static samples.

  5. Perform tilt compensation. Pitch and roll are computed from acceleration, then the acceleration and calibrated magnetic vectors are rotated into the Earth frame.

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

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)
})
#> ℹ Using raw magnetic data for calibration 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 is_static magnetic_xc magnetic_yc
#> 1    0.115905762      0.2175903       1      TRUE  0.29552062  0.18547623
#> 2   -0.013183594      1.9647217       1     FALSE -0.01051949 -0.27627041
#> 3   -0.115295410      1.1094971       1     FALSE -0.15331763  0.09683036
#> 4   -0.112731934      0.7674561       1     FALSE  0.10926414  0.23048965
#> 5   -0.008361816      1.0251465       1     FALSE  0.26252971 -0.11046512
#> 6   -0.004760742      0.1928101       1      TRUE  0.24452869 -0.10581544
#>   magnetic_zc     pitch         roll acceleration_xp acceleration_yp
#> 1 -0.06559619 1.3327149  0.489447620   -1.447749e-16   -5.339696e-18
#> 2 -0.32140008 0.2178549 -0.006710058   -2.069471e-17   -1.628209e-18
#> 3 -0.38749907 0.3264234 -0.103545172    1.502298e-17    2.942592e-18
#> 4 -0.27609632 0.8849994 -0.145847404   -1.600553e-17   -4.933120e-18
#> 5 -0.14845232 0.7357053 -0.008156523   -1.457710e-16    8.385626e-19
#> 6 -0.18655343 1.3859400 -0.024686342   -2.950453e-16    2.117582e-22
#>   acceleration_zp magnetic_xcp magnetic_ycp magnetic_zcp         F         I
#> 1        1.045356   0.09817334   0.19453926   -0.2802734 0.3550165 0.9099384
#> 2        2.012331  -0.07933465  -0.27842079   -0.3097126 0.4239505 0.8191117
#> 3        1.177657  -0.27201992   0.05625973   -0.3253889 0.4278293 0.8641717
#> 4        1.224860  -0.16813456   0.18791724   -0.2787673 0.3758900 0.8354809
#> 5        1.382842   0.09560850  -0.11167229   -0.2855710 0.3211892 1.0953867
#> 6        1.049311  -0.13580609  -0.11038805   -0.2741615 0.3252589 1.0026549
#>           H
#> 1 296.77759
#> 2 105.90464
#> 3 191.68528
#> 4 228.18016
#> 5  49.43143
#> 6 140.89455