Coordinate Systems and Transformations

rotate(ts::AbstractMatrix, mat::AbstractMatrix)

Coordinate-aware transformation of vector/matrix by rotation matrix(s) mat(s). Assume ts is a matrix of shape (n, 3).

cotrans(A, in, out)
cotrans(A, out; in=get_coord(A))

Transform the data to the out coordinate system from the in coordinate system.

This function automatically choose between Julia's GeoCotrans (if available) and Fortran's IRBEM implementation.

References:

• IRBEM-LIB: compute magnetic coordinates and perform coordinate conversions (Documentation, IRBEM.jl)
• SPEDAS Cotrans

Coordinate systems, transformations, and geomagnetic field models.

Coordinate systems

• GEO: Geocentric geographic cartesian coordinate system (x [𝐋], y [𝐋], z [𝐋]).
• GSM: Geocentric Solar Magnetic (GSM) coordinate system.
• GSE: Geocentric Solar Ecliptic (GSE) coordinate system.
• GEI: Geocentric Equatorial Inertial (GEI) coordinate system.
• GDZ: Geodetic (GDZ) coordinate system (altitude [km], latitude [deg], longitude [deg]).
• MAG: Magnetic (MAG) coordinate system.
• SPH: Geocentric geographic spherical (SPH) coordinate system (r [𝐋], θ [deg], φ [deg]).
• J2000: J2000 (J2000) coordinate system.

Coordinate transformations

• geo2gei, gei2geo: Transform between GEO and GEI coordinate systems.
• geo2gsm, gsm2geo: Transform between GEO and GSM coordinate systems.
• gei2gsm, gsm2gei: Transform between GEI and GSM coordinate systems.
• gse2gsm, gsm2gse: Transform between GSE and GSM coordinate systems.

References

• Coordinate transformations between geocentric systems

International Geomagnetic Reference Field (IGRF)

The International Geomagnetic Reference Field (IGRF) is a standard mathematical description of the Earth's main magnetic field. It is used widely in studies of the Earth's deep interior, crust, ionosphere, and magnetosphere.

Functions

• igrf_B: Compute the geomagnetic field (IGRF-14, dipole model)

Examples

r, θ, φ = 6500., 30., 4.
t = Date(2021, 3, 28)
Br, Bθ, Bφ = igrf_B(r, θ, φ, t)

# Input position in geodetic coordinates, output magnetic field in East-North-Up (ENU) coordinates
Be, Bn, Bu = igrf_B(GDZ(0, 60.39299, 5.32415), t)

References

• IAGA - NOAA/NCEI
• IGRF-14 Evaluation

Elsewhere

• SatelliteToolboxGeomagneticField.jl: Models to compute the geomagnetic field (IGRF-13, dipole model)
• ppigrf: Pure Python code to calculate IGRF model predictions.
• geopack: Python code to calculate IGRF model predictions.

fac_mat(vec::AbstractVector; xref=[1.0, 0.0, 0.0])

Generates a field-aligned coordinate (FAC) transformation matrix for a vector.

Arguments

• vec: A 3-element vector representing the magnetic field

mva_eigen(B::AbstractMatrix; sort=(;), check=false) -> F::Eigen

Perform minimum variance analysis, returning Eigen factorization object F which contains the eigenvalues in F.values and the eigenvectors in the columns of the matrix F.vectors.

Set check=true to check the reliability of the result.

The kth eigenvector can be obtained from the slice F.vectors[:, k].

mva(V, B=V; kwargs...)

Rotate a timeseries V into the LMN coordinates based on the reference field B.

Arguments

• V: The timeseries data to be transformed, where each column represents a component
• B: The reference field used to determine the minimum variance directions, where each column represents a component

See also: mva_eigen, rotate

check_mva_eigen(F; r=5, verbose=false)

Check the quality of the MVA result.

If λ₁ ≥ λ₂ ≥ λ₃ are 3 eigenvalues of the constructed matrix M, then a good indicator of nice fitting LMN coordinate system should have λ₂ / λ₃ > r.

Δφij(λᵢ, λⱼ, λ₃, M)

Calculate the phase error between components i and j according to: |Δφᵢⱼ| = |Δφⱼᵢ| = √(λ₃/(M-1) * (λᵢ + λⱼ - λ₃)/(λᵢ - λⱼ)²)

Parameters:

• λᵢ: eigenvalue i
• λⱼ: eigenvalue j
• λ₃: smallest eigenvalue (λ₃)
• M: number of samples

Calculate the composite statistical error estimate for ⟨B·x₃⟩: |Δ⟨B·x₃⟩| = √(λ₃/(M-1) + (Δφ₃₂⟨B⟩·x₂)² + (Δφ₃₁⟨B⟩·x₁)²)

Parameters:

• λ₁, λ₂, λ₃: eigenvalues in descending order
• M: number of samples
• B: mean magnetic field vector
• x₁, x₂, x₃: eigenvectors