API: Functions

TL_mat2vec(TL_coef_p, TL_coef_i, TL_coef_e, terms; Bt_scale = 50000f0)

Extract the vector form of Tolles-Lawson coefficients from the matrix form.

Arguments:

• TL_coef_p: length-3 vector of permanent field coefficients
• TL_coef_i: 3 x 3 symmetric matrix of induced field coefficients, denormalized
• TL_coef_e: 3 x 3 matrix of eddy current coefficients, denormalized
• terms: Tolles-Lawson terms used {:permanent,:induced,:eddy}
• Bt_scale: (optional) scaling factor for induced & eddy current terms [nT]

Returns:

• TL_coef: Tolles-Lawson coefficients

TL_vec2mat(TL_coef::Vector, terms; Bt_scale = 50000f0)

Extract the matrix form of Tolles-Lawson coefficients from the vector form.

Arguments:

• TL_coef: Tolles-Lawson coefficients (must include :permanent & :induced)
• terms: Tolles-Lawson terms used {:permanent,:induced,:eddy}
• Bt_scale: (optional) scaling factor for induced & eddy current terms [nT]

Returns:

• TL_coef_p: length-3 vector of permanent field coefficients
• TL_coef_i: 3 x 3 symmetric matrix of induced field coefficients, denormalized
• TL_coef_e: 3 x 3 matrix of eddy current coefficients, denormalized

bpf_data!(x::AbstractVecOrMat; bpf=get_bpf())

Bandpass (or low-pass or high-pass) filter vector or columns of matrix.

Arguments:

• x: data vector or matrix
• bpf: (optional) filter object

Returns:

• nothing: x is mutated with filtered data

bpf_data(x::AbstractMatrix; bpf=get_bpf())

Bandpass (or low-pass or high-pass) filter columns of matrix.

Arguments:

• x: data matrix (e.g., Tolles-Lawson A matrix)
• bpf: (optional) filter object

Returns:

• x_f: data matrix, filtered

bpf_data(x::AbstractVector; bpf=get_bpf())

Bandpass (or low-pass or high-pass) filter vector.

Arguments:

• x: data vector (e.g., magnetometer measurements)
• bpf: (optional) filter object

Returns:

• x_f: data vector, filtered

chunk_data(x, y, l_window::Int)

Break data into non-overlapping sequences (vectors).

Arguments:

• x: N x Nf data matrix (Nf is number of features)
• y: length-N target vector
• l_window: temporal window length

Returns:

• x_seqs: sequence (vector) of Nf x l_window data matrices
• y_seqs: sequence (vector) of length-l_window target vectors

comp_m2bc_test(comp_params::NNCompParams, lines,
               df_line::DataFrame, df_flight::DataFrame, df_map::DataFrame;
               silent::Bool = false)

Evaluate performance of neural network-based aeromagnetic compensation, model 2b or 2c with additional outputs for explainability.

Arguments:

• comp_params: NNCompParams neural network-based aeromagnetic compensation parameters struct
• lines: selected line number(s)
• df_line: lookup table (DataFrame) of lines

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

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

• silent: (optional) if true, no print outs

Returns:

• y_nn: length-N neural network compensation portion
• y_TL: length-N Tolles-Lawson compensation portion
• 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.)

comp_m3_test(comp_params::NNCompParams, lines,
             df_line::DataFrame, df_flight::DataFrame, df_map::DataFrame;
             temp_params::TempParams = TempParams(),
             silent::Bool            = false)

Evaluate performance of neural network-based aeromagnetic compensation, model 3 with additional outputs for explainability.

Arguments:

• comp_params: NNCompParams neural network-based aeromagnetic compensation parameters struct
• lines: selected line number(s)
• df_line: lookup table (DataFrame) of lines

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

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

• temp_params: (optional) TempParams temporary temporal parameters struct
• silent: (optional) if true, no print outs

Returns:

• TL_perm: 3 x N matrix of TL permanent vector field
• TL_induced: 3 x N matrix of TL induced vector field
• TL_eddy: 3 x N matrix of TL eddy current vector field
• TL_aircraft: 3 x N matrix of TL aircraft vector field
• B_unit: 3 x N matrix of normalized vector magnetometer measurements
• B_vec: 3 x N matrix of vector magnetometer measurements
• y_nn: 3 x N matrix of vector neural network correction (for scalar models, in direction of Bt)
• vec_aircraft: 3 x N matrix of predicted aircraft vector field
• 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.)

comp_test(comp_params::CompParams, xyz::XYZ, ind,
          mapS::Union{MapS,MapSd,MapS3D} = mapS_null;
          temp_params::TempParams        = TempParams(),
          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
• temp_params: (optional) TempParams temporary temporal parameters struct
• 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;
          temp_params::TempParams = TempParams(),
          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

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

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

• temp_params: (optional) TempParams temporary temporal parameters struct
• 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.)

comp_train(comp_params::CompParams, xyz_vec::Vector, ind_vec::Vector,
           mapS::Union{MapS,MapSd,MapS3D} = mapS_null;
           temp_params::TempParams        = TempParams(),
           xyz_test::XYZ                  = xyz_vec[1],
           ind_test                       = BitVector(),
           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
• temp_params: (optional) TempParams temporary temporal parameters struct
• xyz_test: (optional) XYZ held-out test data struct
• ind_test: (optional) indices for test data struct
• 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::XYZ, ind,
           mapS::Union{MapS,MapSd,MapS3D} = mapS_null;
           temp_params::TempParams        = TempParams(),
           xyz_test::XYZ                  = xyz,
           ind_test                       = BitVector(),
           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
• temp_params: (optional) TempParams temporary temporal parameters struct
• xyz_test: (optional) XYZ held-out test data struct
• ind_test: (optional) indices for test data struct
• 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;
           temp_params::TempParams = TempParams(),
           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

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

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

• temp_params: (optional) TempParams temporary temporal parameters struct
• 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.)

comp_train_test(comp_params::CompParams,
                xyz_train::XYZ, xyz_test::XYZ, ind_train, ind_test,
                mapS_train::Union{MapS,MapSd,MapS3D} = mapS_null,
                mapS_test::Union{MapS,MapSd,MapS3D}  = mapS_null;
                temp_params::TempParams = TempParams(),
                silent::Bool            = false)

Train & 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_train: XYZ flight data struct for training
• xyz_test: XYZ flight data struct for testing
• ind_train: selected data indices for training
• ind_test: selected data indices for testing
• mapS_train: (optional) MapS, MapSd, or MapS3D scalar magnetic anomaly map struct for training, only used for y_type = :b, :c
• mapS_test: (optional) MapS, MapSd, or MapS3D scalar magnetic anomaly map struct for testing, only used for y_type = :b, :c
• temp_params: (optional) TempParams temporary temporal parameters struct
• silent: (optional) if true, no print outs

Returns:

• comp_params: CompParams aeromagnetic compensation parameters struct
• y_train: length-N_train training target vector
• y_train_hat: length-N_train training prediction vector
• err_train: length-N_train training compensation error
• y_test: length-N_test testing target vector
• y_test_hat: length-N_test testing prediction vector
• err_test: length-N_test testing compensation error
• features: length-Nf feature vector (including components of TL A, etc.)

comp_train_test(comp_params::CompParams, lines_train, lines_test,
                df_line::DataFrame, df_flight::DataFrame, df_map::DataFrame;
                temp_params::TempParams = TempParams(),
                silent::Bool            = false)

Train & 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_train: selected line number(s) for training
• lines_test: selected line number(s) for testing
• df_line: lookup table (DataFrame) of lines

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

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

• temp_params: (optional) TempParams temporary temporal parameters struct
• silent: (optional) if true, no print outs

Returns:

• comp_params: CompParams aeromagnetic compensation parameters struct
• y_train: length-N_train training target vector
• y_train_hat: length-N_train training prediction vector
• err_train: length-N_train mean-corrected (per line) training compensation error
• y_test: length-N_test testing target vector
• y_test_hat: length-N_test testing prediction vector
• err_test: length-N_test mean-corrected (per line) testing compensation error
• features: length-Nf feature vector (including components of TL A, etc.)

compare_fields(s1, s2; silent::Bool = false)

Compare data for each data field in 2 structs of the same type.

Arguments:

• s1: struct 1
• s2: struct 2
• silent: (optional) if true, no summary print out

Returns:

• N_dif: if silent = false, number of different fields

corrupt_mag(mag_c, Bx, By, Bz;
            dt           = 0.1,
            cor_sigma    = 1.0,
            cor_tau      = 600.0,
            cor_var      = 1.0^2,
            cor_drift    = 0.001,
            cor_perm_mag = 5.0,
            cor_ind_mag  = 5.0,
            cor_eddy_mag = 0.5)

Corrupt compensated (clean) magnetometer measurements with random, FOGM, drift, and Tolles-Lawson noise to create uncompensated (corrupted) scalar magnetometer measurements. FOGM is a First-order Gauss-Markov stochastic process.

Arguments:

• mag_c: compensated (clean) scalar magnetometer measurements [nT]
• Bx,By,Bz: vector magnetometer measurements [nT]
• dt: (optional) measurement time step [s]
• cor_sigma: (optional) corruption FOGM catch-all bias [nT]
• cor_tau: (optional) corruption FOGM catch-all time constant [s]
• cor_var: (optional) corruption measurement (white) noise variance [nT^2]
• cor_drift: (optional) corruption measurement linear drift [nT/s]
• cor_perm_mag: (optional) corruption permanent field TL coef std dev
• cor_ind_mag: (optional) corruption induced field TL coef std dev
• cor_eddy_mag: (optional) corruption eddy current TL coef std dev

Returns:

• mag_uc: uncompensated (corrupted) scalar magnetometer measurements [nT]
• TL_coef: Tolles-Lawson coefficients (partially) used to create mag_uc
• cor_fogm: corruption FOGM portion [nT]

corrupt_mag(mag_c, flux;
            dt           = 0.1,
            cor_sigma    = 1.0,
            cor_tau      = 600.0,
            cor_var      = 1.0^2,
            cor_drift    = 0.001,
            cor_perm_mag = 5.0,
            cor_ind_mag  = 5.0,
            cor_eddy_mag = 0.5)

Corrupt compensated (clean) magnetometer measurements with random, FOGM, drift, and Tolles-Lawson noise to create uncompensated (corrupted) scalar magnetometer measurements. FOGM is a First-order Gauss-Markov stochastic process.

Arguments:

• mag_c: compensated (clean) scalar magnetometer measurements [nT]
• flux: MagV vector magnetometer measurement struct
• dt: (optional) measurement time step [s]
• cor_sigma: (optional) corruption FOGM catch-all bias [nT]
• cor_tau: (optional) corruption FOGM catch-all time constant [s]
• cor_var: (optional) corruption measurement (white) noise variance [nT^2]
• cor_drift: (optional) corruption measurement linear drift [nT/s]
• cor_perm_mag: (optional) corruption permanent field TL coef std dev
• cor_ind_mag: (optional) corruption induced field TL coef std dev
• cor_eddy_mag: (optional) corruption eddy current TL coef std dev

Returns:

• mag_uc: uncompensated (corrupted) scalar magnetometer measurements [nT]
• TL_coef: Tolles-Lawson coefficients (partially) used to create mag_uc
• cor_fogm: corruption FOGM portion [nT]

create_P0(lat1 = deg2rad(45);
          init_pos_sigma   = 3.0,
          init_alt_sigma   = 0.001,
          init_vel_sigma   = 0.01,
          init_att_sigma   = deg2rad(0.01),
          ha_sigma         = 0.001,
          a_hat_sigma      = 0.01,
          acc_sigma        = 0.000245,
          gyro_sigma       = 0.00000000727,
          fogm_sigma       = 3.0,
          vec_sigma        = 1000.0,
          vec_states::Bool = false,
          fogm_state::Bool = true,
          P0_TL            = [])

Create initial covariance matrix P0.

Arguments:

• lat1: initial approximate latitude [rad]
• init_pos_sigma: (optional) initial position uncertainty [m]
• init_alt_sigma: (optional) initial altitude uncertainty [m]
• init_vel_sigma: (optional) initial velocity uncertainty [m/s]
• init_att_sigma: (optional) initial attitude uncertainty [rad]
• ha_sigma: (optional) barometer aiding altitude bias [m]
• a_hat_sigma: (optional) barometer aiding vertical accel bias [m/s^2]
• acc_sigma: (optional) accelerometer bias [m/s^2]
• gyro_sigma: (optional) gyroscope bias [rad/s]
• fogm_sigma: (optional) FOGM catch-all bias [nT]
• vec_sigma: (optional) vector magnetometer noise std dev
• vec_states: (optional) if true, include vector magnetometer states
• fogm_state: (optional) if true, include FOGM catch-all bias state
• P0_TL: (optional) initial Tolles-Lawson covariance matrix

Returns:

• P0: initial covariance matrix

create_Qd(dt = 0.1;
          VRW_sigma        = 0.000238,
          ARW_sigma        = 0.000000581,
          baro_sigma       = 1.0,
          acc_sigma        = 0.000245,
          gyro_sigma       = 0.00000000727,
          fogm_sigma       = 3.0,
          vec_sigma        = 1000.0,
          TL_sigma         = [],
          baro_tau         = 3600.0,
          acc_tau          = 3600.0,
          gyro_tau         = 3600.0,
          fogm_tau         = 600.0,
          vec_states::Bool = false,
          fogm_state::Bool = true)

Create the discrete time process/system noise matrix Qd.

Arguments:

• dt: measurement time step [s]
• VRW_sigma: (optional) velocity random walk [m/s^2 /sqrt(Hz)]
• ARW_sigma: (optional) angular random walk [rad/s /sqrt(Hz)]
• baro_sigma: (optional) barometer bias [m]
• acc_sigma: (optional) accelerometer bias [m/s^2]
• gyro_sigma: (optional) gyroscope bias [rad/s]
• fogm_sigma: (optional) FOGM catch-all bias [nT]
• vec_sigma: (optional) vector magnetometer noise std dev
• TL_sigma: (optional) Tolles-Lawson coefficients estimate std dev
• baro_tau: (optional) barometer time constant [s]
• acc_tau: (optional) accelerometer time constant [s]
• gyro_tau: (optional) gyroscope time constant [s]
• fogm_tau: (optional) FOGM catch-all time constant [s]
• vec_states: (optional) if true, include vector magnetometer states
• fogm_state: (optional) if true, include FOGM catch-all bias state

Returns:

• Qd: discrete time process/system noise matrix

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 & 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 & 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(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 & 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 & 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_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 & scalar magnetometer measurements with 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 & 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(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 & scalar magnetometer measurements with 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 & 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_XYZ0(mapS::Union{MapS,MapSd,MapS3D} = get_map(namad);
            alt            = 1000,
            dt             = 0.1,
            t              = 300,
            v              = 68,
            ll1::Tuple     = (),
            ll2::Tuple     = (),
            N_waves::Int   = 1,
            attempts::Int  = 10,
            info::String   = "Simulated data",
            flight         = 1,
            line           = 1,
            year           = 2023,
            doy            = 154,
            mapV::MapV     = get_map(emm720),
            cor_sigma      = 1.0,
            cor_tau        = 600.0,
            cor_var        = 1.0^2,
            cor_drift      = 0.001,
            cor_perm_mag   = 5.0,
            cor_ind_mag    = 5.0,
            cor_eddy_mag   = 0.5,
            init_pos_sigma = 3.0,
            init_alt_sigma = 0.001,
            init_vel_sigma = 0.01,
            init_att_sigma = deg2rad(0.01),
            VRW_sigma      = 0.000238,
            ARW_sigma      = 0.000000581,
            baro_sigma     = 1.0,
            ha_sigma       = 0.001,
            a_hat_sigma    = 0.01,
            acc_sigma      = 0.000245,
            gyro_sigma     = 0.00000000727,
            fogm_sigma     = 1.0,
            baro_tau       = 3600.0,
            acc_tau        = 3600.0,
            gyro_tau       = 3600.0,
            fogm_tau       = 600.0,
            save_h5::Bool  = false,
            xyz_h5::String = "xyz_data.h5",
            silent::Bool   = false)

Create basic flight data. Assumes constant altitude (2D flight). No required arguments, though many are available to create custom data.

Trajectory Arguments:

• mapS: (optional) MapS, MapSd, or MapS3D scalar magnetic anomaly map struct
• alt: (optional) altitude [m]
• dt: (optional) measurement time step [s]
• t: (optional) total flight time, ignored if ll2 is set [s]
• v: (optional) approximate aircraft velocity [m/s]
• ll1: (optional) initial (lat,lon) point [deg]
• ll2: (optional) final (lat,lon) point [deg]
• N_waves: (optional) number of sine waves along path
• attempts: (optional) maximum attempts at creating flight path on mapS
• info: (optional) flight data information
• flight: (optional) flight number
• line: (optional) line number, i.e., segment within flight
• year: (optional) year
• doy: (optional) day of year
• mapV: (optional) MapV vector magnetic anomaly map struct
• save_h5: (optional) if true, save xyz to xyz_h5
• xyz_h5: (optional) path/name of flight data HDF5 file to save (.h5 extension optional)

Compensated Measurement Corruption Arguments:

• cor_var: (optional) corruption measurement (white) noise variance [nT^2]
• fogm_sigma: (optional) FOGM catch-all bias [nT]
• fogm_tau: (optional) FOGM catch-all time constant [s]

Uncompensated Measurement Corruption Arguments:

• cor_sigma: (optional) corruption FOGM catch-all bias [nT]
• cor_tau: (optional) corruption FOGM catch-all time constant [s]
• cor_var: (optional) corruption measurement (white) noise variance [nT^2]
• cor_drift: (optional) corruption measurement linear drift [nT/s]
• cor_perm_mag: (optional) corruption permanent field TL coef std dev
• cor_ind_mag: (optional) corruption induced field TL coef std dev
• cor_eddy_mag: (optional) corruption eddy current TL coef std dev

INS Arguments:

• init_pos_sigma: (optional) initial position uncertainty [m]
• init_alt_sigma: (optional) initial altitude uncertainty [m]
• init_vel_sigma: (optional) initial velocity uncertainty [m/s]
• init_att_sigma: (optional) initial attitude uncertainty [rad]
• VRW_sigma: (optional) velocity random walk [m/s^2 /sqrt(Hz)]
• ARW_sigma: (optional) angular random walk [rad/s /sqrt(Hz)]
• baro_sigma: (optional) barometer bias [m]
• ha_sigma: (optional) barometer aiding altitude bias [m]
• a_hat_sigma: (optional) barometer aiding vertical accel bias [m/s^2]
• acc_sigma: (optional) accelerometer bias [m/s^2]
• gyro_sigma: (optional) gyroscope bias [rad/s]
• baro_tau: (optional) barometer time constant [s]
• acc_tau: (optional) accelerometer time constant [s]
• gyro_tau: (optional) gyroscope time constant [s]

General Arguments:

• silent: (optional) if true, no print outs

Returns:

• xyz: XYZ0 flight data struct

create_flux(path::Path, mapV::MapV = get_map(emm720);
            meas_var     = 1.0^2,
            fogm_sigma   = 1.0,
            fogm_tau     = 600.0,
            silent::Bool = false)

Create compensated (clean) vector magnetometer measurements from a vector magnetic anomaly map.

Arguments:

• path: Path struct, i.e., Traj trajectory struct, INS inertial navigation system struct, or FILTout filter extracted output struct
• mapV: (optional) MapV vector magnetic anomaly map struct
• meas_var: (optional) measurement (white) noise variance [nT^2]
• fogm_sigma: (optional) FOGM catch-all bias [nT]
• fogm_tau: (optional) FOGM catch-all time constant [s]
• silent: (optional) if true, no print outs

Returns:

• flux: MagV vector magnetometer measurement struct

create_flux(lat, lon, mapV::MapV = get_map(emm720);
            Cnb          = repeat(I(3),1,1,length(lat)),
            alt          = 1000,
            dt           = 0.1,
            meas_var     = 1.0^2,
            fogm_sigma   = 1.0,
            fogm_tau     = 600.0,
            silent::Bool = false)

Create compensated (clean) vector magnetometer measurements from a vector magnetic anomaly map.

Arguments:

• lat: latitude [rad]
• lon: longitude [rad]
• mapV: (optional) MapV vector magnetic anomaly map struct
• Cnb: (optional) direction cosine matrix (body to navigation) [-]
• alt: (optional) altitude [m]
• dt: (optional) measurement time step [s]
• meas_var: (optional) measurement (white) noise variance [nT^2]
• fogm_sigma: (optional) FOGM catch-all bias [nT]
• fogm_tau: (optional) FOGM catch-all time constant [s]
• silent: (optional) if true, no print outs

Returns:

• flux: MagV vector magnetometer measurement struct

create_informed_xyz(xyz::XYZ, ind, mapS::Union{MapS,MapSd,MapS3D},
                    use_mag::Symbol, use_vec::Symbol, TL_coef::Vector;
                    terms::Vector{Symbol} = [:permanent,:induced,:eddy],
                    disp_min = 100,
                    disp_max = 500,
                    Bt_disp  = 50,
                    Bt_scale = 50000)

Create knowledge-informed data from existing data. Given map information, an XYZ structure with magnetometer readings, and a fitted Tolles-Lawson model, this function creates a consistent, displaced XYZ structure representing what the use_mag and mag_1_c would have collected had the entire flight been laterally shifted by (disp_min,disp_max), assuming that the linear aircraft model is reasonably accurate. It makes use of a Taylor expansion of the map information to update the expected changes due to the alternative map location and due to the imputed aircraft field. The aircraft "noise" is then carried over into use_mag in the new XYZ data.

Arguments:

• xyz: XYZ flight data struct
• ind: selected data indices
• mapS: MapS, MapSd, or MapS3D scalar magnetic anomaly map struct
• use_mag: uncompensated scalar magnetometer to use for y target vector {:mag_1_uc, etc.}
• use_vec: vector magnetometer (fluxgate) to use for Tolles-Lawson A matrix {:flux_a, etc.}
• TL_coef: Tolles-Lawson coefficients
• terms: (optional) Tolles-Lawson terms to use {:permanent,:induced,:eddy}
• disp_min: (optional) minimum trajectory displacement [m]
• disp_max: (optional) maximum trajectory displacement [m]
• Bt_disp: (optional) target total magnetic field magnitude displacement offset [nT]
• Bt_scale: (optional) scaling factor for induced & eddy current terms [nT]

Returns:

• xyz_disp: XYZ flight data struct with displaced trajectory & modified magnetometer readings

create_ins(traj::Traj;
           init_pos_sigma = 3.0,
           init_alt_sigma = 0.001,
           init_vel_sigma = 0.01,
           init_att_sigma = deg2rad(0.01),
           VRW_sigma      = 0.000238,
           ARW_sigma      = 0.000000581,
           baro_sigma     = 1.0,
           ha_sigma       = 0.001,
           a_hat_sigma    = 0.01,
           acc_sigma      = 0.000245,
           gyro_sigma     = 0.00000000727,
           baro_tau       = 3600.0,
           acc_tau        = 3600.0,
           gyro_tau       = 3600.0,
           save_h5::Bool  = false,
           ins_h5::String = "ins_data.h5")

Creates an INS trajectory about a true trajectory. Propagates a 17-state Pinson error model to create INS errors.

Arguments:

• traj: Traj trajectory struct
• init_pos_sigma: (optional) initial position uncertainty [m]
• init_alt_sigma: (optional) initial altitude uncertainty [m]
• init_vel_sigma: (optional) initial velocity uncertainty [m/s]
• init_att_sigma: (optional) initial attitude uncertainty [rad]
• VRW_sigma: (optional) velocity random walk [m/s^2 /sqrt(Hz)]
• ARW_sigma: (optional) angular random walk [rad/s /sqrt(Hz)]
• baro_sigma: (optional) barometer bias [m]
• ha_sigma: (optional) barometer aiding altitude bias [m]
• a_hat_sigma: (optional) barometer aiding vertical accel bias [m/s^2]
• acc_sigma: (optional) accelerometer bias [m/s^2]
• gyro_sigma: (optional) gyroscope bias [rad/s]
• baro_tau: (optional) barometer time constant [s]
• acc_tau: (optional) accelerometer time constant [s]
• gyro_tau: (optional) gyroscope time constant [s]
• save_h5: (optional) if true, save ins to ins_h5
• ins_h5: (optional) path/name of INS data HDF5 file to save (.h5 extension optional)

Returns:

• ins: INS inertial navigation system struct

create_mag_c(path::Path, mapS::Union{MapS,MapSd,MapS3D} = get_map(namad);
             meas_var     = 1.0^2,
             fogm_sigma   = 1.0,
             fogm_tau     = 600.0,
             silent::Bool = false)

Create compensated (clean) scalar magnetometer measurements from a scalar magnetic anomaly map.

Arguments:

• path: Path struct, i.e., Traj trajectory struct, INS inertial navigation system struct, or FILTout filter extracted output struct
• mapS: (optional) MapS, MapSd, or MapS3D scalar magnetic anomaly map struct
• meas_var: (optional) measurement (white) noise variance [nT^2]
• fogm_sigma: (optional) FOGM catch-all bias [nT]
• fogm_tau: (optional) FOGM catch-all time constant [s]
• silent: (optional) if true, no print outs

Returns:

• mag_c: compensated (clean) scalar magnetometer measurements [nT]

create_mag_c(lat, lon, mapS::Union{MapS,MapSd,MapS3D} = get_map(namad);
             alt          = 1000,
             dt           = 0.1,
             meas_var     = 1.0^2,
             fogm_sigma   = 1.0,
             fogm_tau     = 600.0,
             silent::Bool = false)

Create compensated (clean) scalar magnetometer measurements from a scalar magnetic anomaly map.

Arguments:

• lat: latitude [rad]
• lon: longitude [rad]
• mapS: (optional) MapS, MapSd, or MapS3D scalar magnetic anomaly map struct
• alt: (optional) altitude [m]
• dt: (optional) measurement time step [s]
• meas_var: (optional) measurement (white) noise variance [nT^2]
• fogm_sigma: (optional) FOGM catch-all bias [nT]
• fogm_tau: (optional) FOGM catch-all time constant [s]
• silent: (optional) if true, no print outs

Returns:

• mag_c: compensated (clean) scalar magnetometer measurements [nT]

create_model(dt = 0.1, lat1 = deg2rad(45);
             init_pos_sigma   = 3.0,
             init_alt_sigma   = 0.001,
             init_vel_sigma   = 0.01,
             init_att_sigma   = deg2rad(0.01),
             meas_var         = 3.0^2,
             VRW_sigma        = 0.000238,
             ARW_sigma        = 0.000000581,
             baro_sigma       = 1.0,
             ha_sigma         = 0.001,
             a_hat_sigma      = 0.01,
             acc_sigma        = 0.000245,
             gyro_sigma       = 0.00000000727,
             fogm_sigma       = 3.0,
             vec_sigma        = 1000.0,
             TL_sigma         = [],
             baro_tau         = 3600.0,
             acc_tau          = 3600.0,
             gyro_tau         = 3600.0,
             fogm_tau         = 600.0,
             vec_states::Bool = false,
             fogm_state::Bool = true,
             P0_TL            = [])

Create a magnetic navigation filter model for use in an EKF or a MPF.

Arguments:

• dt: measurement time step [s]
• lat1: initial approximate latitude [rad]
• init_pos_sigma: (optional) initial position uncertainty [m]
• init_alt_sigma: (optional) initial altitude uncertainty [m]
• init_vel_sigma: (optional) initial velocity uncertainty [m/s]
• init_att_sigma: (optional) initial attitude uncertainty [rad]
• meas_var: (optional) measurement (white) noise variance [nT^2]
• VRW_sigma: (optional) velocity random walk [m/s^2 /sqrt(Hz)]
• ARW_sigma: (optional) angular random walk [rad/s /sqrt(Hz)]
• baro_sigma: (optional) barometer bias [m]
• ha_sigma: (optional) barometer aiding altitude bias [m]
• a_hat_sigma: (optional) barometer aiding vertical accel bias [m/s^2]
• acc_sigma: (optional) accelerometer bias [m/s^2]
• gyro_sigma: (optional) gyroscope bias [rad/s]
• fogm_sigma: (optional) FOGM catch-all bias [nT]
• vec_sigma: (optional) vector magnetometer noise std dev
• TL_sigma: (optional) Tolles-Lawson coefficients estimate std dev
• baro_tau: (optional) barometer time constant [s]
• acc_tau: (optional) accelerometer time constant [s]
• gyro_tau: (optional) gyroscope time constant [s]
• fogm_tau: (optional) FOGM catch-all time constant [s]
• vec_states: (optional) if true, include vector magnetometer states
• fogm_state: (optional) if true, include FOGM catch-all bias state
• P0_TL: (optional) initial Tolles-Lawson covariance matrix

Returns:

• P0: initial covariance matrix
• Qd: discrete time process/system noise matrix
• R: measurement (white) noise variance

create_traj(mapS::Union{MapS,MapSd,MapS3D} = get_map(namad);
            alt             = 1000,
            dt              = 0.1,
            t               = 300,
            v               = 68,
            ll1::Tuple      = (),
            ll2::Tuple      = (),
            N_waves::Int    = 1,
            attempts::Int   = 10,
            save_h5::Bool   = false,
            traj_h5::String = "traj_data.h5")

Create Traj trajectory struct with a straight or sinusoidal flight path at constant altitude (2D flight).

Arguments:

• mapS: (optional) MapS, MapSd, or MapS3D scalar magnetic anomaly map struct
• alt: (optional) altitude [m]
• dt: (optional) measurement time step [s]
• t: (optional) total flight time, ignored if ll2 is set [s]
• v: (optional) approximate aircraft velocity [m/s]
• ll1: (optional) initial (lat,lon) point [deg]
• ll2: (optional) final (lat,lon) point [deg]
• N_waves: (optional) number of sine waves along path
• attempts: (optional) maximum attempts at creating flight path on mapS
• save_h5: (optional) if true, save traj to traj_h5
• traj_h5: (optional) path/name of trajectory data HDF5 file to save (.h5 extension optional)

Returns:

• traj: Traj trajectory struct

crlb(lat, lon, alt, vn, ve, vd, fn, fe, fd, Cnb, dt, itp_mapS;
     P0         = create_P0(),
     Qd         = create_Qd(),
     R          = 1.0,
     baro_tau   = 3600.0,
     acc_tau    = 3600.0,
     gyro_tau   = 3600.0,
     fogm_tau   = 600.0,
     date       = get_years(2020,185),
     core::Bool = false)

Cramér–Rao lower bound (CRLB) computed with classic Kalman Filter. Equations evaluated about true trajectory.

Arguments:

• lat: latitude [rad]
• lon: longitude [rad]
• alt: altitude [m]
• vn: north velocity [m/s]
• ve: east velocity [m/s]
• vd: down velocity [m/s]
• fn: north specific force [m/s^2]
• fe: east specific force [m/s^2]
• fd: down specific force [m/s^2]
• Cnb: direction cosine matrix (body to navigation) [-]
• dt: measurement time step [s]
• itp_mapS: scalar map interpolation function (f(lat,lon) or f(lat,lon,alt))
• P0: (optional) initial covariance matrix
• Qd: (optional) discrete time process/system noise matrix
• R: (optional) measurement (white) noise variance
• baro_tau: (optional) barometer time constant [s]
• acc_tau: (optional) accelerometer time constant [s]
• gyro_tau: (optional) gyroscope time constant [s]
• fogm_tau: (optional) FOGM catch-all time constant [s]
• date: (optional) measurement date (decimal year) for IGRF [yr]
• core: (optional) if true, include core magnetic field in measurement

Returns:

• P: non-linear covariance matrix

crlb(traj::Traj, itp_mapS;
     P0         = create_P0(),
     Qd         = create_Qd(),
     R          = 1.0,
     baro_tau   = 3600.0,
     acc_tau    = 3600.0,
     gyro_tau   = 3600.0,
     fogm_tau   = 600.0,
     date       = get_years(2020,185),
     core::Bool = false)

Cramér–Rao lower bound (CRLB) computed with classic Kalman Filter. Equations evaluated about true trajectory.

Arguments:

• traj: Traj trajectory struct
• itp_mapS: scalar map interpolation function (f(lat,lon) or f(lat,lon,alt))
• P0: (optional) initial covariance matrix
• Qd: (optional) discrete time process/system noise matrix
• R: (optional) measurement (white) noise variance
• baro_tau: (optional) barometer time constant [s]
• acc_tau: (optional) accelerometer time constant [s]
• gyro_tau: (optional) gyroscope time constant [s]
• fogm_tau: (optional) FOGM catch-all time constant [s]
• date: (optional) measurement date (decimal year) for IGRF [yr]
• core: (optional) if true, include core magnetic field in measurement

Returns:

• P: non-linear covariance matrix

dcm2euler(dcm, order::Symbol = :body2nav)

Converts a DCM (direction cosine matrix) to yaw, pitch, and roll Euler angles. Yaw is synonymous with azimuth and heading here. There are 2 use cases:

1. With order = :body2nav, the provided DCM is assumed to rotate from the

body frame in the standard -roll, -pitch, -yaw sequence to the navigation frame. For example, if v1 is a 3x1 vector in the body frame [nose, right wing, down], then that vector rotated into the navigation frame [north, east, down] would be v2 = dcm * v1.

1. With order = :nav2body, the provided DCM is assumed to rotate from the

navigation frame in the standard yaw, pitch, roll sequence to the body frame. For example, if v1 is a 3x1 vector in the navigation frame [north, east, down], then that vector rotated into the body frame [nose, right wing, down] would be v2 = dcm * v1.

Reference: Titterton & Weston, Strapdown Inertial Navigation Technology, 2004, Section 3.6 (pg. 36-41 & 537).

Arguments:

• dcm: 3 x 3 x N direction cosine matrix [-]
• order: (optional) rotation order {:body2nav,:nav2body}

Returns:

• roll: length-N roll angle [rad], right-handed rotation about x-axis
• pitch: length-N pitch angle [rad], right-handed rotation about y-axis
• yaw: length-N yaw angle [rad], right-handed rotation about z-axis

de2dlon(de, lat)

Convert east-west position (easting) difference to longitude difference.

Arguments:

• de: east-west position (easting) difference [m]
• lat: nominal latitude [rad]

Returns:

• dlon: longitude difference [rad]

denorm_sets(train_bias, train_scale, train, test)

Denormalize (or destandardize) features (columns) of training & testing data.

Arguments:

• train_bias: 1 x Nf training data biases (means, mins, or zeros)
• train_scale: 1 x Nf training data scaling factors (std devs, maxs-mins, or ones)
• train: N_train x Nf training data, normalized
• test: N_test x Nf testing data, normalized

Returns:

• train: N_train x Nf training data, denormalized
• test: N_test x Nf testing data, denormalized

denorm_sets(train_bias, train_scale, train, val, test)

Denormalize (or destandardize) features (columns) of training, validation, & testing data.

Arguments:

• train_bias: 1 x Nf training data biases (means, mins, or zeros)
• train_scale: 1 x Nf training data scaling factors (std devs, maxs-mins, or ones)
• train: N_train x Nf training data, normalized
• val: N_val x Nf validation data, normalized
• test: N_test x Nf testing data, normalized

Returns:

• train: N_train x Nf training data, denormalized
• val: N_val x Nf validation data, denormalized
• test: N_test x Nf testing data, denormalized

denorm_sets(train_bias, train_scale, train)

Denormalize (or destandardize) features (columns) of training data.

Arguments:

• train_bias: 1 x Nf training data biases (means, mins, or zeros)
• train_scale: 1 x Nf training data scaling factors (std devs, maxs-mins, or ones)
• train: N_train x Nf training data, normalized

Returns:

• train: N_train x Nf training data, denormalized

detrend(y, x = [eachindex(y);]; λ = 0, mean_only::Bool = false)

Detrend signal (remove mean and optionally slope).

Arguments:

• y: length-N observed data vector
• x: (optional) N x Nf input data matrix (Nf is number of features)
• λ: (optional) ridge parameter
• mean_only: (optional) if true, only remove mean (not slope)

Returns:

• y: length-N observed data vector, detrended

dlat2dn(dlat, lat)

Convert latitude difference to north-south position (northing) difference.

Arguments:

• dlat: latitude difference [rad]
• lat: nominal latitude [rad]

Returns:

• dn: north-south position (northing) difference [m]

dlon2de(dlon, lat)

Convert longitude difference to east-west position (easting) difference.

Arguments:

• dlon: longitude difference [rad]
• lat: nominal latitude [rad]

Returns:

• de: east-west position (easting) difference [m]

dn2dlat(dn, lat)

Convert north-south position (northing) difference to latitude difference.

Arguments:

• dn: north-south position (northing) difference [m]
• lat: nominal latitude [rad]

Returns:

• dlat: latitude difference [rad]

downward_L(map_map::Matrix, dx, dy, dz, α::Vector;
           map_mask::BitMatrix = map_params(map_map)[2],
           expand::Bool        = true)

Downward continuation using a sequence of regularization parameters to create a characteristic L-curve. The optimal regularization parameter is at a local minimum on the L-curve, which is a local maximum of curvature. The global maximum of curvature may or may not be the optimal regularization parameter.

Arguments:

• map_map: ny x nx 2D gridded map data
• dx: x-direction map step size [m]
• dy: y-direction map step size [m]
• dz: z-direction upward/downward continuation distance [m]
• α: (geometric) sequence of regularization parameters
• map_mask: (optional) ny x nx mask for valid (not filled-in) map data
• expand: (optional) if true, expand map temporarily to reduce edge effects

Returns:

• norms: L-infinity norm of difference between sequential D.C. solutions

downward_L(mapS::Union{MapS,MapSd,MapS3D}, alt, α::Vector;
           expand::Bool = true)

Downward continuation using a sequence of regularization parameters to create a characteristic L-curve. The optimal regularization parameter is at a local minimum on the L-curve, which is a local maximum of curvature. The global maximum of curvature may or may not be the optimal regularization parameter.

Arguments:

• mapS: MapS, MapSd, or MapS3D scalar magnetic anomaly map struct
• alt: target downward continuation altitude [m]
• α: (geometric) sequence of regularization parameters
• expand: (optional) if true, expand map temporarily to reduce edge effects

Returns:

• norms: L-infinity norm of difference between sequential D.C. solutions

ekf(lat, lon, alt, vn, ve, vd, fn, fe, fd, Cnb, meas, dt, itp_mapS;
    P0         = create_P0(),
    Qd         = create_Qd(),
    R          = 1.0,
    baro_tau   = 3600.0,
    acc_tau    = 3600.0,
    gyro_tau   = 3600.0,
    fogm_tau   = 600.0,
    date       = get_years(2020,185),
    core::Bool = false,
    der_mapS   = nothing,
    map_alt    = 0)

Extended Kalman filter (EKF) for airborne magnetic anomaly navigation.

Arguments:

• lat: latitude [rad]
• lon: longitude [rad]
• alt: altitude [m]
• vn: north velocity [m/s]
• ve: east velocity [m/s]
• vd: down velocity [m/s]
• fn: north specific force [m/s^2]
• fe: east specific force [m/s^2]
• fd: down specific force [m/s^2]
• Cnb: direction cosine matrix (body to navigation) [-]
• meas: scalar magnetometer measurement [nT]
• dt: measurement time step [s]
• itp_mapS: scalar map interpolation function (f(lat,lon) or f(lat,lon,alt))
• P0: (optional) initial covariance matrix
• Qd: (optional) discrete time process/system noise matrix
• R: (optional) measurement (white) noise variance
• baro_tau: (optional) barometer time constant [s]
• acc_tau: (optional) accelerometer time constant [s]
• gyro_tau: (optional) gyroscope time constant [s]
• fogm_tau: (optional) FOGM catch-all time constant [s]
• date: (optional) measurement date (decimal year) for IGRF [yr]
• core: (optional) if true, include core magnetic field in measurement
• der_mapS: (optional) scalar map vertical derivative map interpolation function (f(lat,lon) or (f(lat,lon,alt))
• map_alt: (optional) map altitude [m]

Returns:

• filt_res: FILTres filter results struct

ekf(ins::INS, meas, itp_mapS;
    P0         = create_P0(),
    Qd         = create_Qd(),
    R          = 1.0,
    baro_tau   = 3600.0,
    acc_tau    = 3600.0,
    gyro_tau   = 3600.0,
    fogm_tau   = 600.0,
    date       = get_years(2020,185),
    core::Bool = false,
    der_mapS   = map_itp(zeros(2,2),[-pi,pi],[-pi/2,pi/2]),
    map_alt    = 0)

Extended Kalman filter (EKF) for airborne magnetic anomaly navigation.

Arguments:

• ins: INS inertial navigation system struct
• meas: scalar magnetometer measurement [nT]
• itp_mapS: scalar map interpolation function (f(lat,lon) or f(lat,lon,alt))
• P0: (optional) initial covariance matrix
• Qd: (optional) discrete time process/system noise matrix
• R: (optional) measurement (white) noise variance
• baro_tau: (optional) barometer time constant [s]
• acc_tau: (optional) accelerometer time constant [s]
• gyro_tau: (optional) gyroscope time constant [s]
• fogm_tau: (optional) FOGM catch-all time constant [s]
• date: (optional) measurement date (decimal year) for IGRF [yr]
• core: (optional) if true, include core magnetic field in measurement
• der_mapS: (optional) scalar map vertical derivative map interpolation function (f(lat,lon) or (f(lat,lon,alt))
• map_alt: (optional) map altitude [m]

Returns:

• filt_res: FILTres filter results struct

ekf_online(lat, lon, alt, vn, ve, vd, fn, fe, fd, Cnb, meas,
           Bx, By, Bz, dt, itp_mapS, x0_TL, P0, Qd, R;
           baro_tau   = 3600.0,
           acc_tau    = 3600.0,
           gyro_tau   = 3600.0,
           fogm_tau   = 600.0,
           date       = get_years(2020,185),
           core::Bool = false,
           terms      = [:permanent,:induced,:eddy,:bias],
           Bt_scale   = 50000)

Extended Kalman filter (EKF) with online learning of Tolles-Lawson coefficients.

Arguments:

• lat: latitude [rad]
• lon: longitude [rad]
• alt: altitude [m]
• vn: north velocity [m/s]
• ve: east velocity [m/s]
• vd: down velocity [m/s]
• fn: north specific force [m/s^2]
• fe: east specific force [m/s^2]
• fd: down specific force [m/s^2]
• Cnb: direction cosine matrix (body to navigation) [-]
• meas: scalar magnetometer measurement [nT]
• Bx,By,Bz: vector magnetometer measurements [nT]
• dt: measurement time step [s]
• itp_mapS: scalar map interpolation function (f(lat,lon) or f(lat,lon,alt))
• x0_TL: initial Tolles-Lawson coefficient states
• P0: initial covariance matrix
• Qd: discrete time process/system noise matrix
• R: measurement (white) noise variance
• baro_tau: (optional) barometer time constant [s]
• acc_tau: (optional) accelerometer time constant [s]
• gyro_tau: (optional) gyroscope time constant [s]
• fogm_tau: (optional) FOGM catch-all time constant [s]
• date: (optional) measurement date (decimal year) for IGRF [yr]
• core: (optional) if true, include core magnetic field in measurement
• terms: (optional) Tolles-Lawson terms to use {:permanent,:induced,:eddy,:bias}
• Bt_scale: (optional) scaling factor for induced & eddy current terms [nT]

Returns:

• filt_res: FILTres filter results struct

ekf_online(ins::INS, meas, flux::MagV, itp_mapS, x0_TL, P0, Qd, R;
           baro_tau   = 3600.0,
           acc_tau    = 3600.0,
           gyro_tau   = 3600.0,
           fogm_tau   = 600.0,
           date       = get_years(2020,185),
           core::Bool = false,
           terms      = [:permanent,:induced,:eddy,:bias],
           Bt_scale   = 50000)

Extended Kalman filter (EKF) with online learning of Tolles-Lawson coefficients.

Arguments:

• ins: INS inertial navigation system struct
• meas: scalar magnetometer measurement [nT]
• flux: MagV vector magnetometer measurement struct
• itp_mapS: scalar map interpolation function (f(lat,lon) or f(lat,lon,alt))
• x0_TL: initial Tolles-Lawson coefficient states
• P0: initial covariance matrix
• Qd: discrete time process/system noise matrix
• R: measurement (white) noise variance
• baro_tau: (optional) barometer time constant [s]
• acc_tau: (optional) accelerometer time constant [s]
• gyro_tau: (optional) gyroscope time constant [s]
• fogm_tau: (optional) FOGM catch-all time constant [s]
• date: (optional) measurement date (decimal year) for IGRF [yr]
• core: (optional) if true, include core magnetic field in measurement
• terms: (optional) Tolles-Lawson terms to use {:permanent,:induced,:eddy,:bias}
• Bt_scale: (optional) scaling factor for induced & eddy current terms [nT]

Returns:

• filt_res: FILTres filter results struct

ekf_online_nn(lat, lon, alt, vn, ve, vd, fn, fe, fd, Cnb, meas,
              dt, itp_mapS, x_nn, m, y_norms, P0, Qd, R;
              baro_tau   = 3600.0,
              acc_tau    = 3600.0,
              gyro_tau   = 3600.0,
              fogm_tau   = 600.0,
              date       = get_years(2020,185),
              core::Bool = false,
              terms      = [:permanent,:induced,:eddy])

Extended Kalman filter (EKF) with online learning of neural network weights.

Arguments:

• lat: latitude [rad]
• lon: longitude [rad]
• alt: altitude [m]
• vn: north velocity [m/s]
• ve: east velocity [m/s]
• vd: down velocity [m/s]
• fn: north specific force [m/s^2]
• fe: east specific force [m/s^2]
• fd: down specific force [m/s^2]
• Cnb: direction cosine matrix (body to navigation) [-]
• meas: scalar magnetometer measurement [nT]
• dt: measurement time step [s]
• itp_mapS: scalar map interpolation function (f(lat,lon) or f(lat,lon,alt))
• x_nn: N x Nf data matrix for neural network (Nf is number of features)
• m: neural network model, does not work with skip connections
• y_norms: length-2 tuple of y normalizations, (y_bias,y_scale)
• P0: initial covariance matrix
• Qd: discrete time process/system noise matrix
• R: measurement (white) noise variance
• baro_tau: (optional) barometer time constant [s]
• acc_tau: (optional) accelerometer time constant [s]
• gyro_tau: (optional) gyroscope time constant [s]
• fogm_tau: (optional) FOGM catch-all time constant [s]
• date: (optional) measurement date (decimal year) for IGRF [yr]
• core: (optional) if true, include core magnetic field in measurement
• terms: (optional) Tolles-Lawson terms to use {:permanent,:induced,:eddy,:bias}

Returns:

• filt_res: FILTres filter results struct

ekf_online_nn(ins::INS, meas, itp_mapS, x_nn, m, y_norms, P0, Qd, R;
              baro_tau   = 3600.0,
              acc_tau    = 3600.0,
              gyro_tau   = 3600.0,
              fogm_tau   = 600.0,
              date       = get_years(2020,185),
              core::Bool = false)

Extended Kalman filter (EKF) with online learning of neural network weights.

Arguments:

• ins: INS inertial navigation system struct
• meas: scalar magnetometer measurement [nT]
• itp_mapS: scalar map interpolation function (f(lat,lon) or f(lat,lon,alt))
• x_nn: N x Nf data matrix for neural network (Nf is number of features)
• m: neural network model, does not work with skip connections
• y_norms: length-2 tuple of y normalizations, (y_bias,y_scale)
• P0: initial covariance matrix
• Qd: discrete time process/system noise matrix
• R: measurement (white) noise variance
• baro_tau: (optional) barometer time constant [s]
• acc_tau: (optional) accelerometer time constant [s]
• gyro_tau: (optional) gyroscope time constant [s]
• fogm_tau: (optional) FOGM catch-all time constant [s]
• date: (optional) measurement date (decimal year) for IGRF [yr]
• core: (optional) if true, include core magnetic field in measurement

Returns:

• filt_res: FILTres filter results struct

ekf_online_nn_setup(x, y, m, y_norms; N_sigma::Int = 1000)

Setup for extended Kalman filter (EKF) with online learning of neural network weights.

Arguments:

• x: N x Nf data matrix (Nf is number of features)
• y: length-N target vector
• m: neural network model, does not work with skip connections
• y_norms: tuple of y normalizations, i.e., (y_bias,y_scale)
• N_sigma: (optional) number of neural network weights sets to use to create nn_sigma

Returns:

• P0_nn: initial neural network weights covariance matrix
• nn_sigma: initial neural network weights estimate std dev

ekf_online_setup(flux::MagV, meas, ind = trues(length(meas));
                 Bt           = sqrt.(flux.x.^2+flux.y.^2+flux.z.^2)[ind],
                 λ            = 0.025,
                 terms        = [:permanent,:induced,:eddy,:bias],
                 pass1        = 0.1,
                 pass2        = 0.9,
                 fs           = 10.0,
                 pole::Int    = 4,
                 trim::Int    = 20,
                 N_sigma::Int = 100,
                 Bt_scale     = 50000)

Setup for extended Kalman filter (EKF) with online learning of Tolles-Lawson coefficients.

Arguments:

• flux: MagV vector magnetometer measurement struct
• meas: scalar magnetometer measurement [nT]
• ind: 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
• N_sigma: (optional) number of Tolles-Lawson coefficient sets to use to create TL_sigma
• Bt_scale: (optional) scaling factor for induced & eddy current terms [nT]

Returns:

• x0_TL: initial Tolles-Lawson coefficient states
• P0_TL: initial Tolles-Lawson covariance matrix
• TL_sigma: Tolles-Lawson coefficients estimate std dev

elasticnet_fit(x, y, α::Real = 0.99, no_norm = falses(size(x,2));
               λ::Real           = -1,
               data_norms::Tuple = (zeros(1,1),zeros(1,1),[0.0],[0.0]),
               l_segs::Vector    = [length(y)],
               silent::Bool      = false)

Fit an elastic net (ridge regression and/or Lasso) model to data.

Arguments:

• x: N x Nf data matrix (Nf is number of features)
• y: length-N target vector
• α: (optional) ridge regression (α=0) vs Lasso (α=1) balancing parameter {0:1}
• no_norm: (optional) length-Nf Boolean indices of features to not be normalized
• λ: (optional) elastic net parameter, -1 to ignore & determine with cross-validation
• data_norms: (optional) length-4 tuple of data normalizations, (x_bias,x_scale,y_bias,y_scale)
• l_segs: (optional) length-N_lines vector of lengths of lines, sum(l_segs) = N
• silent: (optional) if true, no print outs

Returns:

• model: length-2 tuple of elastic net-based model, (length-Nf coefficients, bias)
• data_norms: length-4 tuple of data normalizations, (x_bias,x_scale,y_bias,y_scale)
• y_hat: length-N prediction vector
• err: length-N mean-corrected (per line) error

err_segs(y_hat, y, l_segs; silent::Bool = true)

Remove mean error from multiple individual flight lines within larger dataset.

Arguments:

• y_hat: length-N prediction vector
• y: length-N target vector
• l_segs: length-N_lines vector of lengths of lines, sum(l_segs) = N
• silent: (optional) if true, no print outs

Returns:

• err: length-N mean-corrected (per line) error

euler2dcm(roll, pitch, yaw, order::Symbol = :body2nav)

Converts a (Euler) roll-pitch-yaw (X-Y-Z) right-handed body to navigation frame rotation (or the opposite rotation), to a DCM (direction cosine matrix). Yaw is synonymous with azimuth and heading here. If frame 1 is rotated to frame 2, then the returned DCM, when pre-multiplied, rotates a vector in frame 1 into frame 2. There are 2 use cases:

1. With order = :body2nav, the body frame is rotated in the standard

-roll, -pitch, -yaw sequence to the navigation frame. For example, if v1 is a 3x1 vector in the body frame [nose, right wing, down], then that vector rotated into the navigation frame [north, east, down] would be v2 = dcm * v1.

1. With order = :nav2body, the navigation frame is rotated in the standard

yaw, pitch, roll sequence to the body frame. For example, if v1 is a 3x1 vector in the navigation frame [north, east, down], then that vector rotated into the body frame [nose, right wing, down] would be v2 = dcm * v1.

Reference: Titterton & Weston, Strapdown Inertial Navigation Technology, 2004, Section 3.6 (pg. 36-41 & 537).

Arguments:

• roll: length-N roll angle [rad], right-handed rotation about x-axis
• pitch: length-N pitch angle [rad], right-handed rotation about y-axis
• yaw: length-N yaw angle [rad], right-handed rotation about z-axis
• order: (optional) rotation order {:body2nav,:nav2body}

Returns:

• dcm: 3 x 3 x N direction cosine matrix [-]

eval_crlb(traj::Traj, crlb_P::Array)

Extract Cramér–Rao lower bound (CRLB) results.

Arguments:

• traj: Traj trajectory struct
• crlb_P: Cramér–Rao lower bound non-linear covariance matrix

Returns:

• crlb_out: CRLBout Cramér–Rao lower bound extracted output struct

eval_filt(traj::Traj, ins::INS, filt_res::FILTres)

Extract filter results.

Arguments:

• traj: Traj trajectory struct
• ins: INS inertial navigation system struct
• filt_res: FILTres filter results struct

Returns:

• filt_out: FILTout filter extracted output struct

eval_gsa(m::Chain, x, n::Int = min(10000,size(x,1)))

Global sensitivity analysis (GSA) with the Morris Method.

Reference: https://book.sciml.ai/notes/17-GlobalSensitivityAnalysis/

Reference: https://docs.sciml.ai/GlobalSensitivity/stable/methods/morris/

Arguments:

• m: neural network model
• x: N x Nf data matrix (Nf is number of features)
• n: (optional) number of samples (instances) to use for explanation

Returns:

• means: means of elementary effects

eval_ins(traj::Traj, ins::INS)

Extract INS results.

Arguments:

• traj: Traj trajectory struct
• ins: INS inertial navigation system struct

Returns:

• ins_out: INSout inertial navigation system extracted output struct

eval_results(traj::Traj, ins::INS, filt_res::FILTres, crlb_P::Array)

Extract CRLB, INS, & filter results.

Arguments:

• traj: Traj trajectory struct
• ins: INS inertial navigation system struct
• filt_res: FILTres filter results struct
• crlb_P: Cramér–Rao lower bound non-linear covariance matrix

Returns:

• crlb_out: CRLBout Cramér–Rao lower bound extracted output struct
• ins_out: INSout inertial navigation system extracted output struct
• filt_out: FILTout filter extracted output struct

eval_shapley(m::Chain, x, features::Vector{Symbol},
             N::Int      = min(10000,size(x,1)),
             num_mc::Int = 10)

Compute stochastic Shapley effects for global feature importance.

Reference: https://nredell.github.io/ShapML.jl/dev/#Examples-1

Arguments:

• m: neural network model
• x: N x Nf data matrix (Nf is number of features)
• features: length-Nf feature vector (including components of TL A, etc.)
• N: (optional) number of samples (instances) to use for explanation
• num_mc: (optional) number of Monte Carlo simulations

Returns:

• df_shap: DataFrame of Shapley effects
• baseline_shap: intercept of Shapley effects

fdm(x::Vector; scheme::Symbol = :central)

Finite difference method (FDM) applied to x.

Arguments:

• x: data vector
• scheme: (optional) finite difference method scheme used
  • backward: 1st derivative 1st-order backward difference
  • forward: 1st derivative 1st-order forward difference
  • central: 1st derivative 2nd-order central difference
  • backward2: 1st derivative 2nd-order backward difference
  • forward2: 1st derivative 2nd-order forward difference
  • fourth: 4th derivative central difference

Returns:

• dif: vector of finite differences (length of x)

filter_events!(flight::Symbol, df_event::DataFrame;
               keyword::String = "",
               tt_lim::Tuple   = ())

Filter a DataFrame of in-flight events to only contain relevant events.

Arguments:

• flight: flight name (e.g., :Flt1001)
• df_event: lookup table (DataFrame) of in-flight events

• keyword: (optional) keyword to search within events, case insensitive
• tt_lim: (optional) length-2 start & end time limits (inclusive) [s]

Returns:

• nothing: df_event is filtered

filter_events(flight::Symbol, df_event::DataFrame;
              keyword::String = "",
              tt_lim::Tuple   = ())

Filter a DataFrame of in-flight events to only contain relevant events.

Arguments:

• flight: flight name (e.g., :Flt1001)
• df_event: lookup table (DataFrame) of in-flight events

• keyword: (optional) keyword to search within events, case insensitive
• tt_lim: (optional) length-2 start & end time limits (inclusive) [s]

Returns:

• df_event: lookup table (DataFrame) of in-flight events, filtered

fogm(sigma, tau, dt, N)

First-order Gauss-Markov stochastic process. Represents unmeasureable time-correlated errors.

Arguments:

• sigma: FOGM catch-all bias
• tau: FOGM catch-all time constant [s]
• dt: measurement time step [s]
• N: number of samples (instances)

Returns:

• x: FOGM data

get_Axy(lines, df_line::DataFrame,
        df_flight::DataFrame, df_map::DataFrame,
        features_setup::Vector{Symbol}   = [:mag_1_uc,:TL_A_flux_a];
        features_no_norm::Vector{Symbol} = Symbol[],
        y_type::Symbol     = :d,
        use_mag::Symbol    = :mag_1_uc,
        use_mag_c::Symbol  = :mag_1_c,
        use_vec::Symbol    = :flux_a,
        terms              = [:permanent,:induced,:eddy],
        terms_A            = [:permanent,:induced,:eddy,:bias],
        sub_diurnal::Bool  = false,
        sub_igrf::Bool     = false,
        bpf_mag::Bool      = false,
        reorient_vec::Bool = false,
        l_window::Int      = -1,
        mod_TL::Bool       = false,
        map_TL::Bool       = false,
        return_B::Bool     = false,
        silent::Bool       = true)

Get "external" Tolles-Lawson A matrix, x data matrix, & y target vector from multiple flight lines, possibly multiple flights. Optionally return Bt & B_dot used to create the "external" Tolles-Lawson A matrix.

Arguments:

• lines: selected line number(s)
• df_line: lookup table (DataFrame) of lines

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

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

• features_setup: vector of features to include
• features_no_norm: (optional) vector of features to not normalize
• y_type: (optional) y target type
  • :a = anomaly field #1, compensated tail stinger total field scalar magnetometer measurements
  • :b = anomaly field #2, interpolated magnetic anomaly map values
  • :c = aircraft field #1, difference between uncompensated cabin total field scalar magnetometer measurements and interpolated magnetic anomaly map values
  • :d = aircraft field #2, difference between uncompensated cabin and compensated tail stinger total field scalar magnetometer measurements
  • :e = BPF'd total field, bandpass filtered uncompensated cabin total field scalar magnetometer measurements
• use_mag: (optional) uncompensated scalar magnetometer to use for y target vector {:mag_1_uc, etc.}, only used for y_type = :c, :d, :e
• use_mag_c: (optional) compensated scalar magnetometer to use for y target vector {:mag_1_c, etc.}, only used for y_type = :a, :d
• use_vec: (optional) vector magnetometer (fluxgate) to use for "external" Tolles-Lawson A matrix {:flux_a, etc.}
• terms: (optional) Tolles-Lawson terms to use for A within x data matrix {:permanent,:induced,:eddy,:bias}
• terms_A: (optional) Tolles-Lawson terms to use for "external" Tolles-Lawson A matrix {:permanent,:induced,:eddy,:bias}
• sub_diurnal: (optional) if true, subtract diurnal from scalar magnetometer measurements
• sub_igrf: (optional) if true, subtract IGRF from scalar magnetometer measurements
• bpf_mag: (optional) if true, bpf scalar magnetometer measurements in x data matrix
• reorient_vec: (optional) if true, align vector magnetometer measurements with body frame
• l_window: (optional) trim data by N % l_window, -1 to ignore
• mod_TL: (optional) if true, create modified "external" Tolles-Lawson A matrix with use_mag
• map_TL: (optional) if true, create map-based "external" Tolles-Lawson A matrix
• return_B: (optional) if true, also return Bt & B_dot
• silent: (optional) if true, no print outs

Returns:

• A: N x N_TL "external" Tolles-Lawson A matrix (N_TL is number of Tolles-Lawson coefficients)
• x: N x Nf data matrix (Nf is number of features)
• y: length-N target vector
• no_norm: length-Nf Boolean indices of features to not be normalized
• features: length-Nf feature vector (including components of TL A, etc.)
• l_segs: length-N_lines vector of lengths of lines, sum(l_segs) = N
• Bt: if return_B = true, length-N magnitude of total field measurements used to create A [nT]
• B_dot: if return_B = true, N x 3 finite differences of total field vector used to create A [nT]

get_XYZ(flight::Symbol, df_flight::DataFrame;
        tt_sort::Bool      = true,
        reorient_vec::Bool = false,
        silent::Bool       = false)

Get XYZ flight data from saved HDF5 file via DataFrame lookup.

Arguments:

• flight: flight name (e.g., :Flt1001)
• df_flight: lookup table (DataFrame) of flight data files

• tt_sort: (optional) if true, sort data by time (instead of line)
• reorient_vec: (optional) if true, align vector magnetometer measurements with body frame
• silent: (optional) if true, no print outs

Returns:

• xyz: XYZ flight data struct

get_XYZ0(xyz_file::String,
         traj_field::Symbol = :traj,
         ins_field::Symbol  = :ins_data;
         info::String       = splitpath(xyz_file)[end],
         flight             = 1,
         line               = 1,
         year               = 2023,
         doy                = 154,
         dt                 = 0.1,
         tt_sort::Bool      = true,
         silent::Bool       = false)

Get the minimum dataset required for MagNav from saved CSV, HDF5, or MAT file. Not all fields within the XYZ0 flight data struct are required. The minimum data required in the CSV, HDF5, or MAT file includes:

• lat, lon, alt (position)
• mag_1_c OR mag_1_uc (scalar magnetometer measurements)

All other fields can be computed/simulated.

If a CSV or HDF5 file is provided, the possible columns/fields in the file are:

If a MAT file is provided, the above fields may also be provided, but the non-INS fields should be within the specified traj_field MAT struct and the INS fields should be within the specified ins_field MAT struct and without ins_ prefixes. This is the standard way the MATLAB-companion outputs data.

Arguments:

• xyz_file: path/name of flight data CSV, HDF5, or MAT file (.csv, .h5, or .mat extension required)
• traj_field: (optional) trajectory struct field within MAT file to use, not relevant for CSV or HDF5 file
• ins_field: (optional) INS struct field within MAT file to use, :none if unavailable, not relevant for CSV or HDF5 file
• tt_sort: (optional) if true, sort data by time (instead of line)
• silent: (optional) if true, no print outs

If not provided in xyz_file:

• info: (optional) flight data information
• flight: (optional) flight number
• line: (optional) line number, i.e., segment within flight
• year: (optional) year
• doy: (optional) day of year
• dt: (optional) measurement time step [s]

Returns:

• xyz: XYZ0 flight data struct

get_XYZ1(xyz_file::String,
         traj_field::Symbol = :traj,
         ins_field::Symbol  = :ins_data;
         info::String       = splitpath(xyz_file)[end],
         flight             = 1,
         line               = 1,
         year               = 2023,
         doy                = 154,
         dt                 = 0.1,
         tt_sort::Bool      = true,
         silent::Bool       = false)

Get the minimum dataset required for MagNav from saved CSV, HDF5, or MAT file. Not all fields within the XYZ1 flight data struct are required. The minimum data required in the CSV, HDF5, or MAT file includes:

• lat, lon, alt (position)
• mag_1_c OR mag_1_uc (scalar magnetometer measurements)

All other fields can be computed/simulated, except flux_b, mag_2_c, mag_3_c, mag_2_uc, mag_3_uc, aux_1, aux_2, and aux_3.

If a CSV or HDF5 file is provided, the possible columns/fields in the file are:

If a MAT file is provided, the above fields may also be provided, but the non-INS fields should be within the specified traj_field MAT struct and the INS fields should be within the specified ins_field MAT struct and without ins_ prefixes. This is the standard way the MATLAB-companion outputs data.

Arguments:

• xyz_file: path/name of flight data CSV, HDF5, or MAT file (.csv, .h5, or .mat extension required)
• traj_field: (optional) trajectory struct field within MAT file to use, not relevant for CSV or HDF5 file
• ins_field: (optional) INS struct field within MAT file to use, :none if unavailable, not relevant for CSV or HDF5 file
• tt_sort: (optional) if true, sort data by time (instead of line)
• silent: (optional) if true, no print outs

If not provided in xyz_file:

• info: (optional) flight data information
• flight: (optional) flight number
• line: (optional) line number, i.e., segment within flight
• year: (optional) year
• doy: (optional) day of year
• dt: (optional) measurement time step [s]

Returns:

• xyz: XYZ1 flight data struct

get_XYZ20(xyz_160_h5::String, xyz_h5::String;
          info::String = splitpath(xyz_160_h5)[end] * " & " * splitpath(xyz_h5)[end],
          silent::Bool = false)

Get 160 Hz (partial) XYZ20 flight data from saved HDF5 file and combine with 10 Hz XYZ20 flight data from another saved HDF5 file. Data is time sorted to ensure data is aligned.

Arguments:

• xyz_160_h5: path/name of 160 Hz flight data HDF5 file (.h5 extension optional)
• xyz_h5: path/name of 10 Hz flight data HDF5 file (.h5 extension optional)
• info: (optional) flight data information
• silent: (optional) if true, no print outs

Returns:

• xyz: XYZ20 flight data struct

get_XYZ20(xyz_h5::String;
          info::String  = splitpath(xyz_h5)[end],
          tt_sort::Bool = true,
          silent::Bool  = false)

Get XYZ20 flight data from saved HDF5 file. Based on 2020 SGL data fields.

Arguments:

• xyz_h5: path/name of flight data HDF5 file (.h5 extension optional)
• info: (optional) flight data information
• tt_sort: (optional) if true, sort data by time (instead of line)
• silent: (optional) if true, no print outs

Returns:

• xyz: XYZ20 flight data struct

get_XYZ21(xyz_h5::String;
          info::String  = splitpath(xyz_h5)[end],
          tt_sort::Bool = true,
          silent::Bool  = false)

Get XYZ21 flight data from saved HDF5 file. Based on 2021 SGL data fields.

Arguments:

• xyz_h5: path/name of flight data HDF5 file (.h5 extension optional)
• info: (optional) flight data information
• tt_sort: (optional) if true, sort data by time (instead of line)
• silent: (optional) if true, no print outs

Returns:

• xyz: XYZ21 flight data struct

get_autocor(x::Vector, dt = 0.1, dt_max = 300.0)

Get autocorrelation of data (e.g., actual - expected measurements).

Arguments:

• x: data vector
• dt: (optional) measurement time step [s]
• dt_max: (optional) maximum time step to evaluate [s]

Returns:

• sigma: standard deviation
• tau: autocorrelation decay to e^-1 of x [s]

get_bpf(; pass1 = 0.1, pass2 = 0.9, fs = 10.0, pole::Int = 4)

Create a Butterworth bandpass (or low-pass or high-pass) filter object. Set pass1 = -1 for low-pass filter or pass2 = -1 for high-pass filter.

Arguments:

• 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

Returns:

• bpf: filter object

get_cached_map(map_cache::Map_Cache, lat::Real, lon::Real, alt::Real;
               silent::Bool = false)

Get cached map at specific location.

Arguments:

• map_cache: Map_Cache map cache struct
• lat: latitude [rad]
• lon: longitude [rad]
• alt: altitude [m]
• silent: (optional) if true, no print outs

Returns:

• itp_mapS: scalar map interpolation function (f(lat,lon) at alt)

get_comp_params(comp_params_bson::String, silent::Bool = false)

Get aeromagnetic compensation parameters from saved BSON file.

Arguments:

• comp_params_bson: path/name of aeromagnetic compensation parameters BSON file (.bson extension optional)
• silent: (optional) if true, no print outs

Returns:

• comp_params: CompParams aeromagnetic compensation parameters struct, either:
  • NNCompParams: neural network-based aeromagnetic compensation parameters struct
  • LinCompParams: linear aeromagnetic compensation parameters struct

get_flux(flux_file::String,
         use_vec::Symbol = :flux_a,
         field::Symbol   = :traj)

Get vector magnetometer data from saved CSV, HDF5, or MAT file.

If a CSV or HDF5 file is provided, the possible columns/fields in the file are:

If a MAT file is provided, the above fields may also be provided, but they should be within the specified field MAT struct. This is the standard way the MATLAB-companion outputs data.

Arguments:

• flux_file: path/name of vector magnetometer data CSV, HDF5, or MAT file (.csv, .h5, or .mat extension required)
• use_vec: (optional) vector magnetometer (fluxgate) to use
• field: (optional) struct field within MAT file to use, not relevant for CSV or HDF5 file

Returns:

• flux: MagV vector magnetometer measurement struct

get_igrf(xyz::XYZ, ind = trues(xyz.traj.N);
         frame::Symbol   = :body,
         norm_igrf::Bool = false,
         check_xyz::Bool = true)

Get the IGRF Earth vector in the body or navigation frame given an XYZ flight data struct containing trajectory information, valid indices, a start date in IGRF time (years since 0 CE), and reference frame.

Arguments:

• xyz: XYZ flight data struct
• ind: (optional) selected data indices
• frame: (optional) desired reference frame {:body,:nav}
• norm_igrf: (optional) if true, normalize igrf_vec
• check_xyz: (optional) if true, cross-check with igrf field in xyz

Returns:

• igrf_vec: length-N stacked vector of 3 IGRF coordinates in frame

get_ind(xyz::XYZ, lines, df_line::DataFrame;
        splits        = (1),
        l_window::Int = -1)

Get BitVector of selected data indices for further analysis via DataFrame lookup.

Arguments:

• xyz: XYZ flight data struct
• lines: selected line number(s)
• df_line: lookup table (DataFrame) of lines

• splits: (optional) data splits, must sum to 1
• l_window: (optional) trim data by N % l_window, -1 to ignore

Returns:

• ind: BitVector (or tuple of BitVector) of selected data indices

get_ind(xyz::XYZ, line::Real, df_line::DataFrame;
        splits        = (1),
        l_window::Int = -1)

Get BitVector of indices for further analysis via DataFrame lookup.

Arguments:

• xyz: XYZ flight data struct
• line: line number
• df_line: lookup table (DataFrame) of lines

• splits: (optional) data splits, must sum to 1
• l_window: (optional) trim data by N % l_window, -1 to ignore

Returns:

• ind: BitVector (or tuple of BitVector) of selected data indices

get_ind(xyz::XYZ;
        ind    = trues(xyz.traj.N),
        lines  = (),
        tt_lim = (),
        splits = (1))

Get BitVector of indices for further analysis from specified indices (subset), lines, and/or time range. Any or all of these may be used. Defaults to use all indices, lines, and times.

Arguments:

• xyz: XYZ flight data struct
• ind: (optional) selected data indices
• lines: (optional) selected line number(s)
• tt_lim: (optional) end time limit or length-2 start & end time limits (inclusive) [s]
• splits: (optional) data splits, must sum to 1

Returns:

• ind: BitVector (or tuple of BitVector) of selected data indices

get_ind(tt::Vector, line::Vector;
        ind    = trues(length(tt)),
        lines  = (),
        tt_lim = (),
        splits = (1))

Get BitVector of indices for further analysis from specified indices (subset), lines, and/or time range. Any or all of these may be used. Defaults to use all indices, lines, and times.

Arguments:

• tt: time [s]
• line: line number(s)
• ind: (optional) selected data indices
• lines: (optional) selected line number(s)
• tt_lim: (optional) end time limit or length-2 start & end time limits (inclusive) [s]
• splits: (optional) data splits, must sum to 1

Returns:

• ind: BitVector (or tuple of BitVector) of selected data indices

get_ins(xyz::XYZ, ind = trues(xyz.traj.N);
        N_zero_ll::Int  = 0,
        t_zero_ll::Real = 0,
        err::Real       = 0.0)

Get inertial navigation system data at specific indices, possibly zeroed.

Arguments:

• xyz: XYZ flight data struct
• ind: (optional) selected data indices
• N_zero_ll: (optional) number of samples (instances) to zero INS lat/lon to truth (xyz.traj)
• t_zero_ll: (optional) length of time to zero INS lat/lon to truth (xyz.traj), overwrites N_zero_ll
• err: (optional) additional position error [m]

Returns:

• ins: INS inertial navigation system struct at ind

get_ins(ins_file::String, field::Symbol = :ins_data;
        dt            = 0.1,
        tt_sort::Bool = true,
        silent::Bool  = false)

Get inertial navigation system data from saved CSV, HDF5, or MAT file. The only required fields are ins_lat, ins_lon, and ins_alt (position).

If a CSV or HDF5 file is provided, the possible columns/fields in the file are:

If a MAT file is provided, the above fields may also be provided, but they should be within the specified field MAT struct and without ins_ prefixes. This is the standard way the MATLAB-companion outputs data.

Arguments:

• ins_file: path/name of INS data CSV, HDF5, or MAT file (.csv, .h5, or .mat extension required)
• field: (optional) struct field within MAT file to use, not relevant for CSV or HDF5 file
• dt: (optional) measurement time step [s], only used if not in ins_file
• silent: (optional) if true, no print outs

Returns:

• ins: INS inertial navigation system struct

get_map(map_file::String   = namad,
        map_field::Symbol  = :map_data;
        map_info::String   = splitpath(map_file)[end],
        map_units::Symbol  = :rad,
        file_units::Symbol = :deg,
        flip_map::Bool     = false)

Get map data from saved HDF5 or MAT file or folder containing CSV files. Maps are typically saved in :deg units, while :rad is used internally.

Arguments:

• map_file: path/name of map data HDF5 or MAT file (.h5 or .mat extension required) or folder containing CSV files
• map_field: (optional) struct field within MAT file to use, not relevant for CSV or HDF5 file
• map_info: (optional) map information, only used if not in map_file
• map_units: (optional) map xx/yy units to use in map_map {:rad,:deg}
• file_units: (optional) map xx/yy units used in map_file {:rad,:deg}
• flip_map: (optional) if true, vertically flip data from map file (possibly useful for CSV map)

Returns:

• map_map: Map magnetic anomaly map struct

get_map(map_name::Symbol, df_map::DataFrame,
        map_field::Symbol  = :map_data;
        map_info::String   = "$map_name",
        map_units::Symbol  = :rad,
        file_units::Symbol = :deg,
        flip_map::Bool     = false)

Get map data from saved HDF5 or MAT file or folder containing CSV files via DataFrame lookup. Maps are typically saved in :deg units, while :rad is used internally.

Arguments:

• map_name: name of magnetic anomaly map
• df_map: lookup table (DataFrame) of map data HDF5 and/or MAT files and/or folder containing CSV files

• map_info: (optional) map information, only used if not in map_file
• map_field: (optional) struct field within MAT file to use, not relevant for CSV or HDF5 file
• map_units: (optional) map xx/yy units to use in map_map {:rad,:deg}
• file_units: (optional) map xx/yy units used in files within df_map {:rad,:deg}
• flip_map: (optional) if true, vertically flip data from map file (possibly useful for CSV map)

Returns:

• map_map: Map magnetic anomaly map struct

get_map_val(map_map_vec::Vector, path::Path, ind = trues(path.N); α = 200)

Get scalar magnetic anomaly map values from multiple maps along a flight path. Each map in map_map_vec is upward and/or downward continued to alt as necessary.

Arguments:

• map_map_vec: vector of Map magnetic anomaly map structs
• path: Path struct, i.e., Traj trajectory struct, INS inertial navigation system struct, or FILTout filter extracted output struct
• ind: (optional) selected data indices
• α: (optional) regularization parameter for downward continuation

Returns:

• map_vals: vector of scalar magnetic anomaly map values

get_map_val(map_map::Map, path::Path, ind = trues(path.N);
            α=200, return_itp::Bool = false)

Get scalar magnetic anomaly map values along a flight path. map_map is upward and/or downward continued to alt as necessary.

Arguments:

• map_map: Map magnetic anomaly map struct
• path: Path struct, i.e., Traj trajectory struct, INS inertial navigation system struct, or FILTout filter extracted output struct
• ind: (optional) selected data indices
• α: (optional) regularization parameter for downward continuation
• return_itp: (optional) if true, also return map_itp

Returns:

• map_val: scalar magnetic anomaly map values
• map_itp: if return_itp = true, map interpolation function (f(lat,lon) or f(lat,lon,alt))

get_map_val(map_map::Map, lat, lon, alt; α = 200, return_itp::Bool = false)

Get scalar magnetic anomaly map values along a flight path. map_map is upward and/or downward continued to alt as necessary (except if drape map).

Arguments:

• map_map: Map magnetic anomaly map struct
• lat: latitude [rad]
• lon: longitude [rad]
• alt: altitude [m]
• α: (optional) regularization parameter for downward continuation
• return_itp: (optional) if true, also return itp_map

Returns:

• map_val: scalar magnetic anomaly map values
• itp_map: if return_itp = true, map interpolation function (f(lat,lon) or f(lat,lon,alt))

get_nn_m(Nf::Int, Ny::Int = 1;
         hidden                = [8],
         activation::Function  = swish,
         final_bias::Bool      = true,
         skip_con::Bool        = false,
         model_type::Symbol    = :m1
         l_window::Int         = 5,
         tf_layer_type::Symbol = :postlayer,
         tf_norm_type::Symbol  = :batch,
         dropout_prob::Real    = 0.2,
         N_tf_head::Int        = 8,
         tf_gain::Real         = 1.0)

Get neural network model. Valid for 0-3 hidden layers, except for model_type = :m3w, :m3tf, which are only valid for 1 or 2 hidden layers.

Arguments:

• Nf: length of input (feature) layer
• Ny: (optional) length of output layer
• hidden: (optional) hidden layers & nodes (e.g., [8,8] for 2 hidden layers, 8 nodes each)
• activation: (optional) activation function
  • relu = rectified linear unit
  • σ = sigmoid (logistic function)
  • swish = self-gated
  • tanh = hyperbolic tan
  • run plot_activation() for a visual
• final_bias: (optional) if true, include final layer bias
• skip_con: (optional) if true, use skip connections, must have length(hidden) == 1
• model_type: (optional) aeromagnetic compensation model type
• l_window: (optional) temporal window length, 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

Returns:

• m: neural network model

get_optimal_rotation_matrix(v1s, v2s)

Get the 3 x 3 rotation matrix rotating the directions of v1s into v2s. Uses the Kabsch algorithm.

Reference: https://en.wikipedia.org/wiki/Kabsch_algorithm

Arguments:

• v1s: N x 3 matrix for first set of 3D points
• v2s: N x 3 matrix for second set of 3D points

Returns:

• R: 3D matrix rotatating v1s into v2s' directions

get_pinson(nx::Int, lat, vn, ve, vd, fn, fe, fd, Cnb;
           baro_tau         = 3600.0,
           acc_tau          = 3600.0,
           gyro_tau         = 3600.0,
           fogm_tau         = 600.0,
           vec_states::Bool = false,
           fogm_state::Bool = true,
           k1=3e-2, k2=3e-4, k3=1e-6)

Get the nx x nx Pinson dynamics matrix. States (errors) are:

Arguments:

• nx: total state dimension
• lat: latitude [rad]
• vn: north velocity [m/s]
• ve: east velocity [m/s]
• vd: down velocity [m/s]
• fn: north specific force [m/s^2]
• fe: east specific force [m/s^2]
• fd: down specific force [m/s^2]
• Cnb: direction cosine matrix (body to navigation) [-]
• baro_tau: (optional) barometer time constant [s]
• acc_tau: (optional) accelerometer time constant [s]
• gyro_tau: (optional) gyroscope time constant [s]
• fogm_tau: (optional) FOGM catch-all time constant [s]
• vec_states: (optional) if true, include vector magnetometer states
• fogm_state: (optional) if true, include FOGM catch-all bias state
• k1: (optional) barometer aiding constant [1/s]
• k2: (optional) barometer aiding constant [1/s^2]
• k3: (optional) barometer aiding constant [1/s^3]

Returns:

• F: nx x nx Pinson matrix

get_step(x::AbstractVector)

Get the step size (spacing) of elements in x.

get_traj(xyz::XYZ, ind = trues(xyz.traj.N))

Get trajectory data at specific indices.

Arguments:

• xyz: XYZ flight data struct
• ind: (optional) selected data indices

Returns:

• traj: Traj trajectory struct at ind

get_traj(traj_file::String, field::Symbol = :traj;
         dt            = 0.1,
         tt_sort::Bool = true,
         silent::Bool  = false)

Get trajectory data from saved CSV, HDF5, or MAT file. The only required fields are lat, lon, and alt (position).

If a CSV or HDF5 file is provided, the possible columns/fields in the file are:

If a MAT file is provided, the above fields may also be provided, but they should be within the specified field MAT struct. This is the standard way the MATLAB-companion outputs data.

Arguments:

• traj_file: path/name of trajectory data CSV, HDF5, or MAT file (.csv, .h5, or .mat extension required)
• field: (optional) struct field within MAT file to use, not relevant for CSV or HDF5 file
• dt: (optional) measurement time step [s], only used if not in traj_file
• silent: (optional) if true, no print outs

Returns:

• traj: Traj trajectory struct

get_x(xyz::XYZ, ind = trues(xyz.traj.N),
      features_setup::Vector{Symbol}   = [:mag_1_uc,:TL_A_flux_a];
      features_no_norm::Vector{Symbol} = Symbol[],
      terms             = [:permanent,:induced,:eddy],
      sub_diurnal::Bool = false,
      sub_igrf::Bool    = false,
      bpf_mag::Bool     = false)

Get x data matrix.

Arguments:

• xyz: XYZ flight data struct
• ind: selected data indices
• features_setup: vector of features to include
• features_no_norm: (optional) vector of features to not normalize
• terms: (optional) Tolles-Lawson terms to use {:permanent,:induced,:eddy,:bias}
• sub_diurnal: (optional) if true, subtract diurnal from scalar magnetometer measurements
• sub_igrf: (optional) if true, subtract IGRF from scalar magnetometer measurements
• bpf_mag: (optional) if true, bpf scalar magnetometer measurements

Returns:

• x: N x Nf data matrix (Nf is number of features)
• no_norm: length-Nf Boolean indices of features to not be normalized
• features: length-Nf feature vector (including components of TL A, etc.)
• l_segs: length-N_lines vector of lengths of lines, sum(l_segs) = N

get_x(lines, df_line::DataFrame, df_flight::DataFrame,
      features_setup::Vector{Symbol}   = [:mag_1_uc,:TL_A_flux_a];
      features_no_norm::Vector{Symbol} = Symbol[],
      terms              = [:permanent,:induced,:eddy],
      sub_diurnal::Bool  = false,
      sub_igrf::Bool     = false,
      bpf_mag::Bool      = false,
      reorient_vec::Bool = false,
      l_window::Int      = -1,
      silent::Bool       = true)

Get x data matrix from multiple flight lines, possibly multiple flights.

Arguments:

• lines: selected line number(s)
• df_line: lookup table (DataFrame) of lines

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

• features_setup: vector of features to include
• features_no_norm: (optional) vector of features to not normalize
• terms: (optional) Tolles-Lawson terms to use {:permanent,:induced,:eddy,:bias}
• sub_diurnal: (optional) if true, subtract diurnal from scalar magnetometer measurements
• sub_igrf: (optional) if true, subtract IGRF from scalar magnetometer measurements
• bpf_mag: (optional) if true, bpf scalar magnetometer measurements
• reorient_vec: (optional) if true, align vector magnetometer measurements with body frame
• l_window: (optional) trim data by N % l_window, -1 to ignore
• silent: (optional) if true, no print outs

Returns:

• x: N x Nf data matrix (Nf is number of features)
• no_norm: length-Nf Boolean indices of features to not be normalized
• features: length-Nf feature vector (including components of TL A, etc.)
• l_segs: length-N_lines vector of lengths of lines, sum(l_segs) = N

get_x(xyz_vec::Vector{XYZ}, ind_vec,
      features_setup::Vector{Symbol}   = [:mag_1_uc,:TL_A_flux_a];
      features_no_norm::Vector{Symbol} = Symbol[],
      terms             = [:permanent,:induced,:eddy],
      sub_diurnal::Bool = false,
      sub_igrf::Bool    = false,
      bpf_mag::Bool     = false)

Get x data matrix from multiple XYZ flight data structs.

Arguments:

• xyz_vec: vector of XYZ flight data structs
• ind_vec: vector of selected data indices
• features_setup: vector of features to include
• features_no_norm: (optional) vector of features to not normalize
• terms: (optional) Tolles-Lawson terms to use {:permanent,:induced,:eddy,:bias}
• sub_diurnal: (optional) if true, subtract diurnal from scalar magnetometer measurements
• sub_igrf: (optional) if true, subtract IGRF from scalar magnetometer measurements
• bpf_mag: (optional) if true, bpf scalar magnetometer measurements

Returns:

• x: N x Nf data matrix (Nf is number of features)
• no_norm: length-Nf Boolean indices of features to not be normalized
• features: length-Nf feature vector (including components of TL A, etc.)
• l_segs: length-N_lines vector of lengths of lines, sum(l_segs) = N

get_y(xyz::XYZ, ind = trues(xyz.traj.N),
      map_val           = -1);
      y_type::Symbol    = :d,
      use_mag::Symbol   = :mag_1_uc,
      use_mag_c::Symbol = :mag_1_c,
      sub_diurnal::Bool = false,
      sub_igrf::Bool    = false)

Get y target vector.

Arguments:

• xyz: XYZ flight data struct
• ind: selected data indices
• map_val: (optional) scalar magnetic anomaly map values, only used for y_type = :b
• y_type: (optional) y target type
  • :a = anomaly field #1, compensated tail stinger total field scalar magnetometer measurements
  • :b = anomaly field #2, interpolated magnetic anomaly map values
  • :c = aircraft field #1, difference between uncompensated cabin total field scalar magnetometer measurements and interpolated magnetic anomaly map values
  • :d = aircraft field #2, difference between uncompensated cabin and compensated tail stinger total field scalar magnetometer measurements
  • :e = BPF'd total field, bandpass filtered uncompensated cabin total field scalar magnetometer measurements
• use_mag: (optional) uncompensated scalar magnetometer to use for y target vector {:mag_1_uc, etc.}, only used for y_type = :c, :d, :e
• use_mag_c: (optional) compensated scalar magnetometer to use for y target vector {:mag_1_c, etc.}, only used for y_type = :a, :d
• sub_diurnal: (optional) if true, subtract diurnal from scalar magnetometer measurements
• sub_igrf: (optional) if true, subtract IGRF from scalar magnetometer measurements

Returns:

• y: length-N target vector

get_y(lines, df_line::DataFrame, df_flight::DataFrame,
      df_map::DataFrame;
      y_type::Symbol    = :d,
      use_mag::Symbol   = :mag_1_uc,
      use_mag_c::Symbol = :mag_1_c,
      sub_diurnal::Bool = false,
      sub_igrf::Bool    = false,
      l_window::Int     = -1,
      silent::Bool      = true)

Get y target vector from multiple flight lines, possibly multiple flights.

Arguments:

• lines: selected line number(s)
• df_line: lookup table (DataFrame) of lines

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

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

• y_type: (optional) y target type
  • :a = anomaly field #1, compensated tail stinger total field scalar magnetometer measurements
  • :b = anomaly field #2, interpolated magnetic anomaly map values
  • :c = aircraft field #1, difference between uncompensated cabin total field scalar magnetometer measurements and interpolated magnetic anomaly map values
  • :d = aircraft field #2, difference between uncompensated cabin and compensated tail stinger total field scalar magnetometer measurements
  • :e = BPF'd total field, bandpass filtered uncompensated cabin total field scalar magnetometer measurements
• use_mag: (optional) uncompensated scalar magnetometer to use for y target vector {:mag_1_uc, etc.}, only used for y_type = :c, :d, :e
• use_mag_c: (optional) compensated scalar magnetometer to use for y target vector {:mag_1_c, etc.}, only used for y_type = :a, :d
• sub_diurnal: (optional) if true, subtract diurnal from scalar magnetometer measurements
• sub_igrf: (optional) if true, subtract IGRF from scalar magnetometer measurements
• l_window: (optional) trim data by N % l_window, -1 to ignore
• silent: (optional) if true, no print outs

Returns:

• y: length-N target vector

get_years(year, doy=0)

Get decimal (fractional) year from year and doy (day of year).

Arguments:

• year: year
• doy: day of year

Returns:

• years: decimal (fractional) year

gif_animation_m3(TL_perm::AbstractMatrix, TL_induced::AbstractMatrix, TL_eddy::AbstractMatrix,
                 TL_aircraft::AbstractMatrix, B_unit::AbstractMatrix, y_nn::AbstractMatrix,
                 y::Vector, y_hat::Vector, xyz::XYZ,
                 filt_lat::Vector = [],
                 filt_lon::Vector = [];
                 ind              = trues(xyz.traj.N),
                 tt_lim::Tuple    = (0, (xyz.traj(ind).N-1)*xyz.traj.dt/60),
                 skip_every::Int  = 5,
                 save_plot::Bool  = false,
                 mag_gif::String  = "comp_xai.gif")

Create a GIF animation of the model 3 components and the true and predicted scalar magnetic field. First run comp_m3_test() to generate the individual model components 3.

Arguments

• TL_perm: 3 x N matrix of TL permanent vector field
• TL_induced: 3 x N matrix of TL induced vector field
• TL_eddy: 3 x N matrix of TL eddy current vector field
• TL_aircraft: 3 x N matrix of TL aircraft vector field
• B_unit: 3 x N matrix of normalized vector magnetometer measurements
• y_nn: 3 x N matrix of vector neural network correction (for scalar models, in direction of Bt)
• y: length-N target vector
• y_hat: length-N prediction vector
• xyz: XYZ flight data struct
• filt_lat: (optional) length-N filter output latitude [rad]
• filt_lon: (optional) length-N filter output longitude [rad]
• ind: (optional) selected data indices
• tt_lim: (optional) length-2 start & end time limits (inclusive) [min]
• skip_every: (optional) number of time steps to skip between frames
• save_plot: (optional) if true, save g1 as mag_gif
• mag_gif: (optional) path/name of magnetic field GIF file to save (.gif extension optional)

Returns

• g1: magnetic field GIF animation

Example

gif_animation_m3(TL_perm, TL_induced, TL_eddy, TL_aircraft, B_unit,
                 y_nn, y, y_hat, xyz, filt_lat, filt_lon; ind=ind, tt_lim=(0.0,10.0),
                 skip_every=5, save_plot=false, mag_gif="comp_xai.gif")

gif_ellipse(P, lat1 = deg2rad(45);
            dt                   = 0.1,
            di::Int              = 10,
            speedup::Int         = 60,
            conf_units::Symbol   = :m,
            μ                    = zeros(eltype(P),2),
            conf                 = 0.95,
            clip                 = Inf,
            n::Int               = 61,
            lim                  = 500,
            margin::Int          = 2,
            axis::Bool           = true,
            plot_eigax::Bool     = false,
            bg_color::Symbol     = :white,
            ce_color::Symbol     = :black,
            b_e::AbstractBackend = gr(),
            save_plot::Bool      = false,
            ellipse_gif::String  = "conf_ellipse.gif")

Create a (position) confidence ellipse GIF animation for a 2 x 2 (x N) covariance matrix.

Arguments:

• P: 2 x 2 (x N) covariance matrix
• lat1: (optional) nominal latitude [rad], only used if conf_units = :m or :ft
• dt: (optional) measurement time step [s]
• di: (optional) GIF measurement interval (e.g., di = 10 uses every 10th measurement)
• speedup: (optional) GIF speedup (e.g., speedup = 60 is 60x speed)
• conf_units: (optional) confidence ellipse units {:m,:ft,:deg,:rad}
• μ: (optional) confidence ellipse center [conf_units]
• conf: (optional) percentile {0:1}
• clip: (optional) clipping radius [conf_units]
• n: (optional) number of confidence ellipse points
• lim: (optional) plot x & y limits (-lim,lim) [conf_units]
• margin: (optional) margin around plot [mm]
• axis: (optional) if true, show axes
• plot_eigax: (optional) if true, show major & minor axes
• bg_color: (optional) background color
• ce_color: (optional) confidence ellipse color
• b_e: (optional) plotting backend
• save_plot: (optional) if true, save g1 as ellipse_gif
• ellipse_gif: (optional) path/name of confidence ellipse GIF file to save (.gif extension optional)

Returns:

• g1: confidence ellipse GIF animation

gif_ellipse(filt_res::FILTres,
            filt_out::FILTout,
            map_map::Map         = mapS_null;
            dt                   = 0.1,
            di::Int              = 10,
            speedup::Int         = 60,
            conf_units::Symbol   = :m,
            μ                    = zeros(eltype(filt_res.P),2),
            conf                 = 0.95,
            clip                 = Inf,
            n::Int               = 61,
            lim                  = 500,
            dpi::Int             = 200,
            margin::Int          = 2,
            axis::Bool           = true,
            plot_eigax::Bool     = false,
            bg_color::Symbol     = :white,
            ce_color::Symbol     = :black,
            map_color::Symbol    = :usgs,
            clims::Tuple         = (),
            b_e::AbstractBackend = gr(),
            save_plot::Bool      = false,
            ellipse_gif::String  = "conf_ellipse.gif")

Create a (position) confidence ellipse GIF animation for a 2 x 2 (x N) covariance matrix.

Arguments:

• filt_res: FILTres filter results struct
• filt_out: FILTout filter extracted output struct
• map_map: (optional) Map magnetic anomaly map struct
• dt: (optional) measurement time step [s]
• di: (optional) GIF measurement interval (e.g., di = 10 uses every 10th measurement)
• speedup: (optional) GIF speedup (e.g., speedup = 60 is 60x speed)
• conf_units: (optional) confidence ellipse units {:m,:ft,:deg,:rad}
• μ: (optional) confidence ellipse center [conf_units]
• conf: (optional) percentile {0:1}
• clip: (optional) clipping radius [conf_units]
• n: (optional) number of confidence ellipse points
• lim: (optional) plot x & y limits (-lim,lim) [conf_units]
• dpi: (optional) dots per inch (image resolution)
• margin: (optional) margin around plot [mm]
• axis: (optional) if true, show axes
• plot_eigax: (optional) if true, show major & minor axes
• bg_color: (optional) background color
• ce_color: (optional) confidence ellipse color
• map_color: (optional) filled contour color scheme {:usgs,:gray,:gray1,:gray2,:plasma,:magma}
• clims: (optional) length-2 map colorbar limits (cmin,cmax)
• b_e: (optional) plotting backend
• save_plot: (optional) if true, save g1 as ellipse_gif
• ellipse_gif: (optional) path/name of confidence ellipse GIF file to save (.gif extension optional)

Returns:

• g1: confidence ellipse GIF animation

krr_fit(x, y, no_norm = falses(size(x,2));
        k::Kernel           = PolynomialKernel(;degree=1),
        λ::Real             = 0.5,
        norm_type_x::Symbol = :standardize,
        norm_type_y::Symbol = :standardize,
        data_norms::Tuple   = (zeros(1,1),zeros(1,1),[0.0],[0.0]),
        l_segs::Vector      = [length(y)],
        silent::Bool        = false)

Fit a kernel ridge regression (KRR) model to data.

Arguments:

• x: N x Nf data matrix (Nf is number of features)
• y: length-N target vector
• no_norm: (optional) length-Nf Boolean indices of features to not be normalized
• k: (optional) kernel
• λ: (optional) ridge parameter
• norm_type_x: (optional) normalization for x data matrix
• norm_type_y: (optional) normalization for y target vector
• data_norms: (optional) length-4 tuple of data normalizations, (x_bias,x_scale,y_bias,y_scale)
• l_segs: (optional) length-N_lines vector of lengths of lines, sum(l_segs) = N
• silent: (optional) if true, no print outs

Returns:

• model: length-3 tuple of KRR-based model, (k, length-N coefficients, N x Nf data matrix, normalized)
• data_norms: length-4 tuple of data normalizations, (x_bias,x_scale,y_bias,y_scale)
• y_hat: length-N prediction vector
• err: length-N mean-corrected (per line) error

krr_test(x, y, data_norms::Tuple, model::Tuple;
         l_segs::Vector = [length(y)],
         silent::Bool   = false)

Evaluate performance of a kernel ridge regression (KRR) model.

Arguments:

• x: N x Nf data matrix (Nf is number of features)
• y: length-N target vector
• data_norms: length-4 tuple of data normalizations, (x_bias,x_scale,y_bias,y_scale)
• model: length-3 tuple of KRR-based model, (k, length-N_train coefficients, N_train x Nf training data matrix, normalized)
• l_segs: (optional) length-N_lines vector of lengths of lines, sum(l_segs) = N
• silent: (optional) if true, no print outs

Returns:

• y_hat: length-N prediction vector
• err: length-N mean-corrected (per line) error

linear_fit(x, y, no_norm = falses(size(x,2));
           trim::Int           = 0,
           λ::Real             = 0,
           norm_type_x::Symbol = :none,
           norm_type_y::Symbol = :none,
           data_norms::Tuple   = (zeros(1,1),zeros(1,1),[0.0],[0.0]),
           l_segs::Vector      = [length(y)],
           silent::Bool        = false)

Fit a linear regression model to data.

Arguments:

• x: N x Nf data matrix (Nf is number of features)
• y: length-N target vector
• no_norm: (optional) length-Nf Boolean indices of features to not be normalized
• trim: (optional) number of elements to trim (e.g., due to bpf)
• λ: (optional) ridge parameter
• norm_type_x: (optional) normalization for x data matrix
• norm_type_y: (optional) normalization for y target vector
• data_norms: (optional) length-4 tuple of data normalizations, (x_bias,x_scale,y_bias,y_scale)
• l_segs: (optional) length-N_lines vector of lengths of lines, sum(l_segs) = N
• silent: (optional) if true, no print outs

Returns:

• model: length-2 tuple of linear regression model, (length-Nf coefficients, bias=0)
• data_norms: length-4 tuple of data normalizations, (x_bias,x_scale,y_bias,y_scale)
• y_hat: length-N prediction vector
• err: length-N mean-corrected (per line) error

linear_test(x_norm, y, y_bias, y_scale, model::Tuple;
            l_segs::Vector = [length(y)],
            silent::Bool   = false)

Evaluate performance of a linear model.

Arguments:

• x_norm: N x Nf normalized data matrix (Nf is number of features)
• y: length-N target vector
• y_bias: y target vector bias bias (mean, min, or zero)
• y_scale: y target vector bias scaling factor (std dev, max-min, or one)
• model: length-2 tuple of model, (length-Nf coefficients, bias)
• l_segs: (optional) length-N_lines vector of lengths of lines, sum(l_segs) = N
• silent: (optional) if true, no print outs

Returns:

• y_hat: length-N prediction vector
• err: length-N mean-corrected (per line) error

linear_test(x, y, data_norms::Tuple, model::Tuple;
            l_segs::Vector = [length(y)],
            silent::Bool   = false)

Evaluate performance of a linear model.

Arguments:

• x: N x Nf data matrix (Nf is number of features)
• y: length-N target vector
• data_norms: length-4 tuple of data normalizations, (x_bias,x_scale,y_bias,y_scale)
• model: length-2 tuple of model, (length-Nf coefficients, bias)
• l_segs: (optional) length-N_lines vector of lengths of lines, sum(l_segs) = N
• silent: (optional) if true, no print outs

Returns:

• y_hat: length-N prediction vector
• err: length-N mean-corrected (per line) error

linreg(y, x; λ=0)

Linear regression with data matrix.

Arguments:

• y: length-N observed data vector
• x: N x Nf input data matrix (Nf is number of features)
• λ: (optional) ridge parameter

Returns:

• coef: linear regression coefficients

linreg(y; λ=0)

Linear regression to determine best fit line for x = eachindex(y).

Arguments:

• y: length-N observed data vector
• λ: (optional) ridge parameter

Returns:

• coef: length-2 vector of linear regression coefficients

map2kmz(map_map::Matrix, map_xx::Vector, map_yy::Vector,
        map_kmz::String   = "map.kmz";
        map_units::Symbol = :rad,
        plot_alt::Real    = 0,
        opacity::Real     = 0.75,
        clims::Tuple      = ())

Create KMZ file of map for use with Google Earth. Generates an "icon" overlay, thus not suitable for large maps (e.g., > 5 deg x 5 deg).

Arguments:

• map_map: ny x nx 2D gridded map data
• map_xx: nx map x-direction (longitude) coordinates [rad] or [deg]
• map_yy: ny map y-direction (latitude) coordinates [rad] or [deg]
• map_kmz: (optional) path/name of map KMZ file to save (.kmz extension optional)
• map_units: (optional) map xx/yy units {:rad,:deg}
• plot_alt: (optional) map altitude in Google Earth [m]
• opacity: (optional) map opacity {0:1}
• clims: (optional) length-2 map colorbar limits (cmin,cmax)

Returns:

• nothing: map_kmz is created

map2kmz(mapS::Union{MapS,MapSd,MapS3D},
        map_kmz::String = "map.kmz";
        use_mask::Bool  = true,
        plot_alt::Real  = 0,
        opacity::Real   = 0.75,
        clims::Tuple    = ())

Create KMZ file of map for use with Google Earth. Generates an "icon" overlay, thus not suitable for large maps (e.g., > 5 deg x 5 deg).

Arguments:

• mapS: MapS, MapSd, or MapS3D scalar magnetic anomaly map struct
• map_kmz: (optional) path/name of map KMZ file to save (.kmz extension optional)
• use_mask: (optional) if true, apply mapS mask to map
• plot_alt: (optional) map altitude in Google Earth [m]
• opacity: (optional) map opacity {0:1}
• clims: (optional) length-2 map colorbar limits (cmin,cmax)

Returns:

• nothing: map_kmz is created

map_border(map_map::Matrix, map_xx::Vector, map_yy::Vector;
           inner::Bool       = true,
           sort_border::Bool = false,
           return_ind::Bool  = false)

Get map border from an unfilled map.

Arguments:

• map_map: ny x nx 2D gridded map data
• map_xx: nx map x-direction (longitude) coordinates
• map_yy: ny map y-direction (latitude) coordinates
• inner: (optional) if true, get inner border, otherwise outer border
• sort_border: (optional) if true, sort border data points sequentially
• return_ind: (optional) if true, return ind

Returns:

• yy: border y-direction (latitude) coordinates
• xx: border x-direction (longitude) coordinates
• ind: if return_ind = true, BitMatrix of border indices within map_map

map_border(mapS::Union{MapS,MapSd,MapS3D};
           inner::Bool       = true,
           sort_border::Bool = false,
           return_ind::Bool  = false)

Get map border from an unfilled map.

Arguments:

• mapS: MapS, MapSd, or MapS3D scalar magnetic anomaly map struct
• inner: (optional) if true, get inner border, otherwise outer border
• sort_border: (optional) if true, sort border data points sequentially
• return_ind: (optional) if true, return ind

Returns:

• yy: border y-direction (latitude) coordinates
• xx: border x-direction (longitude) coordinates
• ind: if return_ind = true, BitMatrix of border indices within map_map

map_check(map_map_vec::Vector, path::Path, ind = trues(path.N))

Check if latitude and longitude points are on given maps.

Arguments:

• map_map_vec: vector of Map magnetic anomaly map structs
• path: Path struct, i.e., Traj trajectory struct, INS inertial navigation system struct, or FILTout filter extracted output struct
• ind: (optional) selected data indices

Returns:

• bools: if true, all path[ind] points are on map_map_vec[i]

map_check(map_map::Map, path::Path, ind = trues(path.N))

Check if latitude and longitude points are on given map.

Arguments:

• map_map: Map magnetic anomaly map struct
• path: Path struct, i.e., Traj trajectory struct, INS inertial navigation system struct, or FILTout filter extracted output struct
• ind: (optional) selected data indices

Returns:

• bool: if true, all path[ind] points are on map_map

map_check(map_map::Map, lat, lon, alt = fill(median(map_map.alt),size(lat)))

Check if latitude and longitude points are on given map.

Arguments:

• map_map: Map magnetic anomaly map struct
• lat: latitude [rad]
• lon: longitude [rad]
• alt: (optional) altitude [m], only used for MapS3D

Returns:

• bool: if true, all lat & lon (& alt) points are on map_map

map_chessboard!(map_map::Matrix, map_alt::Matrix, map_xx::Vector,
                map_yy::Vector, alt::Real;
                down_cont::Bool = true,
                dz              = 5,
                down_max        = 150,
                α               = 200)

Perform the chessboard method, which upward (and possibly downward) continues a map to multiple altitudes to create a 3D map, then vertically interpolates at each horizontal grid point.

Reference: Cordell, Phillips, & Godson, U.S. Geological Survey Potential-Field Software Version 2.0, 1992.

Arguments:

• map_map: ny x nx 2D gridded target (e.g., magnetic) map data on [m] grid
• map_alt: ny x nx 2D gridded altitude map data [m] on [m] grid
• map_xx: nx map x-direction (longitude) coordinates [m]
• map_yy: ny map y-direction (latitude) coordinates [m]
• alt: final map altitude after upward continuation [m]
• down_cont: (optional) if true, downward continue if needed, only used if up_cont = true
• dz: (optional) upward continuation step size [m]
• down_max: (optional) maximum downward continuation distance [m]
• α: (optional) regularization parameter for downward continuation

Returns:

• nothing: map_map is mutated with upward continued map data

map_chessboard(mapSd::MapSd, alt::Real;
               down_cont::Bool = true,
               dz              = 5,
               down_max        = 150,
               α               = 200)

Perform the chessboard method, which upward (and possibly downward) continues a map to multiple altitudes to create a 3D map, then vertically interpolates at each horizontal grid point.

Reference: Cordell, Phillips, & Godson, U.S. Geological Survey Potential-Field Software Version 2.0, 1992.

Arguments:

• mapSd: MapSd scalar magnetic anomaly map struct
• alt: final map altitude after upward continuation [m]
• down_cont: (optional) if true, downward continue if needed
• dz: (optional) upward continuation step size [m]
• down_max: (optional) maximum downward continuation distance [m]
• α: (optional) regularization parameter for downward continuation

Returns:

• mapS: MapS scalar magnetic anomaly map struct

map_combine(mapS_vec::Vector, mapS_fallback::MapS = get_map(namad);
            map_info::String   = "Combined map",
            N_levels::Int      = 3,
            dx                 = get_step(mapS_vec[1].xx),
            dy                 = get_step(mapS_vec[1].yy),
            xx_lim::Tuple      = get_lim(mapS_vec[1].xx,0.5),
            yy_lim::Tuple      = get_lim(mapS_vec[1].yy,0.5),
            α                  = 200,
            use_fallback::Bool = true)

Combine maps at different altitudes. Lowest and highest maps are directly used (with resampling & resizing), with intermediate maps determined by N_levels.

Arguments:

• mapS_vec: vector of MapS scalar magnetic anomaly map structs
• mapS_fallback: (optional) fallback MapS scalar magnetic anomaly map struct
• map_info: (optional) map information
• N_levels: (optional) number of map altitude levels
• dx: (optional) desired x-direction map step size
• dy: (optional) desired y-direction map step size
• xx_lim: (optional) length-2x-direction map limits (xx_min,xx_max)
• yy_lim: (optional) length-2 y-direction map limits (yy_min,yy_max)
• α: (optional) regularization parameter for downward continuation
• use_fallback: (optional) if true, use mapS_fallback for missing map data

Returns:

• mapS3D: MapS3D 3D (multi-level) scalar magnetic anomaly map struct

map_combine(mapS::MapS, mapS_fallback::MapS = get_map(namad);
            map_info::String = mapS.info,
            xx_lim::Tuple    = get_lim(mapS.xx,0.1),
            yy_lim::Tuple    = get_lim(mapS.yy,0.1),
            α                = 200)

Combine two maps at same altitude.

Arguments:

• mapS: MapS scalar magnetic anomaly map struct
• mapS_fallback: (optional) fallback MapS scalar magnetic anomaly map struct
• map_info: (optional) map information
• xx_lim: (optional) length-2 x-direction map limits (xx_min,xx_max)
• yy_lim: (optional) length-2 y-direction map limits (yy_min,yy_max)
• α: (optional) regularization parameter for downward continuation

Returns:

• mapS: MapS scalar magnetic anomaly map struct, combined

map_correct_igrf!(map_map::Matrix, map_alt,
                  map_xx::Vector, map_yy::Vector;
                  sub_igrf_date::Real = get_years(2013,293), # 20-Oct-2013
                  add_igrf_date::Real = -1,
                  zone_utm::Int       = 18,
                  is_north::Bool      = true,
                  map_units::Symbol   = :rad)

Correct the International Geomagnetic Reference Field (IGRF), i.e., core field, of a map by subtracting and/or adding the IGRF on specified date(s).

Arguments:

• map_map: ny x nx 2D gridded map data
• map_alt: ny x nx 2D gridded altitude map data, single altitude value may be provided [m]
• map_xx: nx map x-direction (longitude) coordinates [rad] or [deg] or [m]
• map_yy: ny map y-direction (latitude) coordinates [rad] or [deg] or [m]
• sub_igrf_date: (optional) date of IGRF core field to subtract [yr], -1 to ignore
• add_igrf_date: (optional) date of IGRF core field to add [yr], -1 to ignore
• zone_utm: (optional) UTM zone, only used if map_units = :utm
• is_north: (optional) if true, map is in northern hemisphere, only used if map_units = :utm
• map_units: (optional) map xx/yy units {:rad,:deg,:utm}

Returns:

• nothing: map_map is mutated with IGRF corrected map data

map_correct_igrf!(mapS::Union{MapS,MapSd,MapS3D};
                  sub_igrf_date::Real = get_years(2013,293), # 20-Oct-2013
                  add_igrf_date::Real = -1,
                  zone_utm::Int       = 18,
                  is_north::Bool      = true,
                  map_units::Symbol   = :rad)

Correct the International Geomagnetic Reference Field (IGRF), i.e., core field, of a map by subtracting and/or adding the IGRF on specified date(s).

Arguments:

• mapS: MapS, MapSd, or MapS3D scalar magnetic anomaly map struct
• sub_igrf_date: (optional) date of IGRF core field to subtract [yr], -1 to ignore
• add_igrf_date: (optional) date of IGRF core field to add [yr], -1 to ignore
• zone_utm: (optional) UTM zone, only used if map_units = :utm
• is_north: (optional) if true, map is in northern hemisphere, only used if map_units = :utm
• map_units: (optional) map xx/yy units {:rad,:deg,:utm}

Returns:

• nothing: map field within mapS is mutated with IGRF corrected map data

map_correct_igrf(map_map::Matrix, map_alt,
                 map_xx::Vector, map_yy::Vector;
                 sub_igrf_date::Real = get_years(2013,293), # 20-Oct-2013
                 add_igrf_date::Real = -1,
                 zone_utm::Int       = 18,
                 is_north::Bool      = true,
                 map_units::Symbol   = :rad)

Correct the International Geomagnetic Reference Field (IGRF), i.e., core field, of a map by subtracting and/or adding the IGRF on specified date(s).

Arguments:

• map_map: ny x nx 2D gridded map data
• map_alt: ny x nx 2D gridded altitude map data [m]
• map_xx: nx map x-direction (longitude) coordinates [rad] or [deg] or [m]
• map_yy: ny map y-direction (latitude) coordinates [rad] or [deg] or [m]
• sub_igrf_date: (optional) date of IGRF core field to subtract [yr], -1 to ignore
• add_igrf_date: (optional) date of IGRF core field to add [yr], -1 to ignore
• zone_utm: (optional) UTM zone, only used if map_units = :utm
• is_north: (optional) if true, map is in northern hemisphere, only used if map_units = :utm
• map_units: (optional) map xx/yy units {:rad,:deg,:utm}

Returns:

• map_map: ny x nx 2D gridded map data, IGRF corrected