Aeromagnetic Compensation

The following are key functions related to aeromagnetic compensation.

Tolles-Lawson

MagNav.create_TL_A — Function

create_TL_A(Bx, By, Bz;
            Bt       = sqrt.(Bx.^2+By.^2+Bz.^2),
            terms    = [:permanent,:induced,:eddy],
            Bt_scale = 50000,
            return_B = false)

Create Tolles-Lawson A matrix using vector magnetometer measurements. Optionally returns the magnitude and derivatives of total field.

Arguments:

Bx,By,Bz: vector magnetometer measurements [nT]
Bt: (optional) magnitude of vector magnetometer measurements or scalar magnetometer measurements for modified Tolles-Lawson [nT]
terms: (optional) Tolles-Lawson terms to use {:permanent,:induced,:eddy,:bias}
Bt_scale: (optional) scaling factor for induced and eddy current terms [nT]
return_B: (optional) if true, also return Bt & B_dot

Returns:

A: Tolles-Lawson A matrix
Bt: if return_B = true, magnitude of total field measurements [nT]
B_dot: if return_B = true, finite differences of total field vector [nT]

create_TL_A(flux::MagV, ind=trues(length(flux.x));
            Bt       = sqrt.(flux.x.^2+flux.y.^2+flux.z.^2)[ind],
            terms    = [:permanent,:induced,:eddy],
            Bt_scale = 50000,
            return_B = false)

Create Tolles-Lawson A matrix using vector magnetometer measurements. Optionally returns the magnitude and derivatives of total field.

Arguments:

flux: MagV vector magnetometer measurement struct
ind: (optional) selected data indices
Bt: (optional) magnitude of vector magnetometer measurements or scalar magnetometer measurements for modified Tolles-Lawson [nT]
terms: (optional) Tolles-Lawson terms to use {:permanent,:induced,:eddy,:bias}
Bt_scale: (optional) scaling factor for induced and eddy current terms [nT]
return_B: (optional) if true, also return Bt & B_dot

Returns:

A: Tolles-Lawson A matrix
Bt: if return_B = true, magnitude of total field measurements [nT]
B_dot: if return_B = true, finite differences of total field vector [nT]

MagNav.create_TL_coef — Function

create_TL_coef(Bx, By, Bz, B;
               Bt         = sqrt.(Bx.^2+By.^2+Bz.^2),
               λ          = 0,
               terms      = [:permanent,:induced,:eddy],
               pass1      = 0.1,
               pass2      = 0.9,
               fs         = 10.0,
               pole::Int  = 4,
               trim::Int  = 20,
               Bt_scale   = 50000,
               return_var = false)

Create Tolles-Lawson coefficients using vector and scalar magnetometer measurements and a bandpass, low-pass or high-pass filter.

Arguments:

Bx,By,Bz: vector magnetometer measurements [nT]
B: scalar magnetometer measurements [nT]
Bt: (optional) magnitude of vector magnetometer measurements or scalar magnetometer measurements for modified Tolles-Lawson [nT]
λ: (optional) ridge parameter
terms: (optional) Tolles-Lawson terms to use {:permanent,:induced,:eddy,:bias}
pass1: (optional) first passband frequency [Hz]
pass2: (optional) second passband frequency [Hz]
fs: (optional) sampling frequency [Hz]
pole: (optional) number of poles for Butterworth filter
trim: (optional) number of elements to trim after filtering
Bt_scale: (optional) scaling factor for induced and eddy current terms [nT]
return_var: (optional) if true, also return B_var

Returns:

coef: Tolles-Lawson coefficients
B_var: if return_var = true, fit error variance

create_TL_coef(flux::MagV, B, ind=trues(length(flux.x));
               Bt         = sqrt.(flux.x.^2+flux.y.^2+flux.z.^2)[ind],
               λ          = 0,
               terms      = [:permanent,:induced,:eddy],
               pass1      = 0.1,
               pass2      = 0.9,
               fs         = 10.0,
               pole::Int  = 4,
               trim::Int  = 20,
               Bt_scale   = 50000,
               return_var = false)

Create Tolles-Lawson coefficients using vector and scalar magnetometer measurements and a bandpass, low-pass or high-pass filter.

Arguments:

flux: MagV vector magnetometer measurement struct
B: scalar magnetometer measurements [nT]
ind: (optional) selected data indices
Bt: (optional) magnitude of vector magnetometer measurements or scalar magnetometer measurements for modified Tolles-Lawson [nT]
λ: (optional) ridge parameter
terms: (optional) Tolles-Lawson terms to use {:permanent,:induced,:eddy,:bias}
pass1: (optional) first passband frequency [Hz]
pass2: (optional) second passband frequency [Hz]
fs: (optional) sampling frequency [Hz]
pole: (optional) number of poles for Butterworth filter
trim: (optional) number of elements to trim after filtering
Bt_scale: (optional) scaling factor for induced and eddy current terms [nT]
return_var: (optional) if true, also return B_var

Returns:

coef: Tolles-Lawson coefficients
B_var: if return_var = true, fit error variance

Model Training/Fitting

MagNav.comp_train — Function

comp_train(comp_params::CompParams, xyz::XYZ, ind,
           mapS::Union{MapS,MapSd,MapS3D} = mapS_null;
           xyz_test::XYZ         = xyz,
           ind_test              = BitVector(),
           σ_curriculum          = 1.0,
           l_window::Int         = 5,
           window_type::Symbol   = :sliding,
           tf_layer_type::Symbol = :postlayer,
           tf_norm_type::Symbol  = :batch,
           dropout_prob          = 0.2,
           N_tf_head::Int        = 8,
           tf_gain               = 1.0,
           silent::Bool          = false)

Train an aeromagnetic compensation model.

Arguments:

comp_params: CompParams aeromagnetic compensation parameters struct, either:
- NNCompParams: neural network-based aeromagnetic compensation parameters struct
- LinCompParams: linear aeromagnetic compensation parameters struct
xyz: XYZ flight data struct
ind: selected data indices
mapS: (optional) MapS, MapSd, or MapS3D scalar magnetic anomaly map struct, only used for y_type = :b, :c
xyz_test: (optional) XYZ held-out test data struct
ind_test: (optional) indices for test data struct
σ_curriculum: (optional) standard deviation threshold, only used for model_type = :m3sc, :m3vc
l_window: (optional) temporal window length, only used for model_type = :m3w, :m3tf
window_type: (optional) type of windowing, :sliding for overlapping or :contiguous for non-overlapping, only used for model_type = :m3w, :m3tf
tf_layer_type: (optional) transformer normalization layer before or after skip connection {:prelayer,:postlayer}, only used for model_type = :m3tf
tf_norm_type: (optional) normalization for transformer encoder {:batch,:layer,:none}, only used for model_type = :m3tf
dropout_prob: (optional) dropout rate, only used for model_type = :m3w, :m3tf
N_tf_head: (optional) number of attention heads, only used for model_type = :m3tf
tf_gain: (optional) weight initialization parameter, only used for model_type = :m3tf
silent: (optional) if true, no print outs

Returns:

comp_params: CompParams aeromagnetic compensation parameters struct
y: length N target vector
y_hat: length N prediction vector
err: length N compensation error
features: length Nf feature vector (including components of TL A, etc.)

comp_train(comp_params::CompParams, xyz_vec::Vector, ind_vec::Vector,
           mapS::Union{MapS,MapSd,MapS3D} = mapS_null;
           xyz_test::XYZ         = xyz_vec[1],
           ind_test              = BitVector(),
           σ_curriculum          = 1.0,
           l_window::Int         = 5,
           window_type::Symbol   = :sliding,
           tf_layer_type::Symbol = :postlayer,
           tf_norm_type::Symbol  = :batch,
           dropout_prob          = 0.2,
           N_tf_head::Int        = 8,
           tf_gain               = 1.0,
           silent::Bool          = false)

Train an aeromagnetic compensation model.

Arguments:

comp_params: CompParams aeromagnetic compensation parameters struct, either:
- NNCompParams: neural network-based aeromagnetic compensation parameters struct
- LinCompParams: linear aeromagnetic compensation parameters struct
xyz_vec: vector of XYZ flight data structs
ind_vec: vector of selected data indices
mapS: (optional) MapS, MapSd, or MapS3D scalar magnetic anomaly map struct, only used for y_type = :b, :c
xyz_test: (optional) XYZ held-out test data struct
ind_test: (optional) indices for test data struct
σ_curriculum: (optional) standard deviation threshold, only used for model_type = :m3sc, :m3vc
l_window: (optional) temporal window length, only used for model_type = :m3w, :m3tf
window_type: (optional) type of windowing, :sliding for overlapping or :contiguous for non-overlapping, only used for model_type = :m3w, :m3tf
tf_layer_type: (optional) transformer normalization layer before or after skip connection {:prelayer,:postlayer}, only used for model_type = :m3tf
tf_norm_type: (optional) normalization for transformer encoder {:batch,:layer,:none}, only used for model_type = :m3tf
dropout_prob: (optional) dropout rate, only used for model_type = :m3w, :m3tf
N_tf_head: (optional) number of attention heads, only used for model_type = :m3tf
tf_gain: (optional) weight initialization parameter, only used for model_type = :m3tf
silent: (optional) if true, no print outs

Returns:

comp_params: CompParams aeromagnetic compensation parameters struct
y: length N target vector
y_hat: length N prediction vector
err: length N compensation error
features: length Nf feature vector (including components of TL A, etc.)

comp_train(comp_params::CompParams, lines,
           df_line::DataFrame, df_flight::DataFrame, df_map::DataFrame;
           σ_curriculum          = 1.0,
           l_window::Int         = 5,
           window_type::Symbol   = :sliding,
           tf_layer_type::Symbol = :postlayer,
           tf_norm_type::Symbol  = :batch,
           dropout_prob          = 0.2,
           N_tf_head::Int        = 8,
           tf_gain               = 1.0,
           silent::Bool          = false)

Train an aeromagnetic compensation model.

Arguments:

comp_params: CompParams aeromagnetic compensation parameters struct, either:
- NNCompParams: neural network-based aeromagnetic compensation parameters struct
- LinCompParams: linear aeromagnetic compensation parameters struct
lines: selected line number(s)
df_line: lookup table (DataFrame) of lines

Field	Type	Description
`flight`	`Symbol`	flight name (e.g., `:Flt1001`)
`line`	`Real`	line number, i.e., segments within `flight`
`t_start`	`Real`	start time of `line` to use [s]
`t_end`	`Real`	end time of `line` to use [s]
`full_line`	`Bool`	(optional) if true, `t_start` to `t_end` is full line
`map_name`	`Symbol`	(optional) name of magnetic anomaly map relevant to `line`
`map_type`	`Symbol`	(optional) type of magnetic anomaly map for `map_name` {`drape`,`HAE`}
`line_alt`	`Real`	(optional) nominal altitude of `line` [m]

df_flight: lookup table (DataFrame) of flight data HDF5 files

Field	Type	Description
`flight`	`Symbol`	flight name (e.g., `:Flt1001`)
`xyz_type`	`Symbol`	subtype of `XYZ` to use for flight data {`:XYZ0`,`:XYZ1`,`:XYZ20`,`:XYZ21`}
`xyz_set`	`Real`	flight dataset number (used to prevent inproper mixing of datasets, such as different magnetometer locations)
`xyz_h5`	`String`	path/name of flight data HDF5 file (`.h5` extension optional)

df_map: lookup table (DataFrame) of map data HDF5 files

Field	Type	Description
`map_name`	`Symbol`	name of magnetic anomaly map
`map_h5`	`String`	path/name of map data HDF5 file (`.h5` extension optional)
`map_type`	`Symbol`	(optional) type of magnetic anomaly map {`drape`,`HAE`}
`map_alt`	`Real`	(optional) map altitude, -1 for drape map [m]

σ_curriculum: (optional) standard deviation threshold, only used for model_type = :m3sc, :m3vc
l_window: (optional) temporal window length, only used for model_type = :m3w, :m3tf
window_type: (optional) type of windowing, :sliding for overlapping or :contiguous for non-overlapping, only used for model_type = :m3w, :m3tf
tf_layer_type: (optional) transformer normalization layer before or after skip connection {:prelayer,:postlayer}, only used for model_type = :m3tf
tf_norm_type: (optional) normalization for transformer encoder {:batch,:layer,:none}, only used for model_type = :m3tf
dropout_prob: (optional) dropout rate, only used for model_type = :m3w, :m3tf
N_tf_head: (optional) number of attention heads, only used for model_type = :m3tf
tf_gain: (optional) weight initialization parameter, only used for model_type = :m3tf
silent: (optional) if true, no print outs

Returns:

comp_params: CompParams aeromagnetic compensation parameters struct
y: length N target vector
y_hat: length N prediction vector
err: length N mean-corrected (per line) compensation error
features: length Nf feature vector (including components of TL A, etc.)

Model Testing

MagNav.comp_test — Function

comp_test(comp_params::CompParams, xyz::XYZ, ind,
          mapS::Union{MapS,MapSd,MapS3D} = mapS_null;
          l_window::Int = 5,
          silent::Bool  = false)

Evaluate performance of an aeromagnetic compensation model.

Arguments:

comp_params: CompParams aeromagnetic compensation parameters struct, either:
- NNCompParams: neural network-based aeromagnetic compensation parameters struct
- LinCompParams: linear aeromagnetic compensation parameters struct
xyz: XYZ flight data struct
ind: selected data indices
mapS: (optional) MapS, MapSd, or MapS3D scalar magnetic anomaly map struct, only used for y_type = :b, :c
l_window: (optional) temporal window length, only used for model_type = :m3w, :m3tf
silent: (optional) if true, no print outs

Returns:

y: length N target vector
y_hat: length N prediction vector
err: length N compensation error
features: length Nf feature vector (including components of TL A, etc.)

comp_test(comp_params::CompParams, lines,
          df_line::DataFrame, df_flight::DataFrame, df_map::DataFrame;
          l_window::Int = 5,
          silent::Bool  = false)

Evaluate performance of an aeromagnetic compensation model.

Arguments:

comp_params: CompParams aeromagnetic compensation parameters struct, either:
- NNCompParams: neural network-based aeromagnetic compensation parameters struct
- LinCompParams: linear aeromagnetic compensation parameters struct
lines: selected line number(s)
df_line: lookup table (DataFrame) of lines

Field	Type	Description
`flight`	`Symbol`	flight name (e.g., `:Flt1001`)
`line`	`Real`	line number, i.e., segments within `flight`
`t_start`	`Real`	start time of `line` to use [s]
`t_end`	`Real`	end time of `line` to use [s]
`full_line`	`Bool`	(optional) if true, `t_start` to `t_end` is full line
`map_name`	`Symbol`	(optional) name of magnetic anomaly map relevant to `line`
`map_type`	`Symbol`	(optional) type of magnetic anomaly map for `map_name` {`drape`,`HAE`}
`line_alt`	`Real`	(optional) nominal altitude of `line` [m]

df_flight: lookup table (DataFrame) of flight data HDF5 files

Field	Type	Description
`flight`	`Symbol`	flight name (e.g., `:Flt1001`)
`xyz_type`	`Symbol`	subtype of `XYZ` to use for flight data {`:XYZ0`,`:XYZ1`,`:XYZ20`,`:XYZ21`}
`xyz_set`	`Real`	flight dataset number (used to prevent inproper mixing of datasets, such as different magnetometer locations)
`xyz_h5`	`String`	path/name of flight data HDF5 file (`.h5` extension optional)

df_map: lookup table (DataFrame) of map data HDF5 files

Field	Type	Description
`map_name`	`Symbol`	name of magnetic anomaly map
`map_h5`	`String`	path/name of map data HDF5 file (`.h5` extension optional)
`map_type`	`Symbol`	(optional) type of magnetic anomaly map {`drape`,`HAE`}
`map_alt`	`Real`	(optional) map altitude, -1 for drape map [m]

l_window: (optional) temporal window length, only used for model_type = :m3w, :m3tf
silent: (optional) if true, no print outs

Returns:

y: length N target vector
y_hat: length N prediction vector
err: length N mean-corrected (per line) compensation error
features: length Nf feature vector (including components of TL A, etc.)