Coordinate Systems and Transformations
This package defines common coordinate systems used in heliophysics and space physics research.
Standard Coordinate Systems
Systems based on the Earth-Sun line
- GSE (Geocentric Solar Ecliptic)
- GSM (Geocentric Solar Magnetic)
Systems based on the Earth's rotation axis
- GEO (Geographic)
- GEI (Geocentric Equatorial Inertial)
- J2000
Systems based on the dipole axis of the Earth's magnetic field
- SM (Solar Magnetic)
- MAG (Geomagnetic)
Other coordinate systems
More information can be found in the the following links
Coordinate Transformations
SPEDAS.rotate — Function
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).
A comprehensive description of the transformations can be found in Hapgood [1]
Coordinate transformations between geocentric systems
SPEDAS.cotrans — Function
cotrans(A, in, out; backend=:auto)
cotrans(A, out; in=get_coord(A))Transform the data to the out coordinate system from the in coordinate system.
If backend is set to :auto (default), this function automatically chooses between Julia's GeoCotrans (if available) and Fortran's IRBEM implementation. Otherwise, it uses the specified backend.
References:
- IRBEM-LIB: compute magnetic coordinates and perform coordinate conversions (Documentation, IRBEM.jl)
- SPEDAS Cotrans
using DimensionalData
using Speasy, SPEDAS
using CairoMakie, SpacePhysicsMakie
pos_gse = get_data("cda/THC_L1_STATE/thc_pos_gse", "2015-10-16", "2015-10-17") |> DimArray
pos_gsm = cotrans(pos_gse, "GSM")
pos_sm = cotrans(pos_gse, "SM")
pos_geo = cotrans(pos_gse, "GEO")
tplot((pos_gse, pos_gsm, pos_sm, pos_geo))
Specialized Coordinate Systems
The package also provides transformations for analysis-specific coordinate systems:
Field-Aligned Coordinates (FAC)
A local coordinate system defined relative to the ambient magnetic field direction, useful for studying plasma waves and particle distributions.
SPEDAS.fac_mat — Function
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
Minimum Variance Analysis (MVA) and Boundary Normal Coordinates (LMN)
A coordinate system derived from the eigenvalues and eigenvectors of the magnetic field variance matrix, commonly used in analyzing current sheets, discontinuities, and wave propagation.
See MinimumVarianceAnalysis.jl for more details.
MinimumVarianceAnalysis.mva_eigen — Function
mva_eigen(B::AbstractMatrix; dim = nothing, sort=(;), check=false) -> F::EigenPerform minimum variance analysis for B (which varies along the dim dimension).
Return 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].
MinimumVarianceAnalysis.mva — Function
mva(V, B=V; dim=nothing, kwargs...)Rotate a timeseries V into the LMN coordinates based on the reference field B along the dim dimension (time).
MinimumVarianceAnalysis.check_mva_eigen — Function
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 $abs(λ₂ / λ₃) > r$.
See also: Comparison with PySPEDAS.
Reference
- PySPEDAS: Coordinate Systems
- geopack: Python version of geopack and Tsyganenko models
- geospacelab: A python-based library to collect, manage, and visualize geospace data (e.g. OMNI, geomagnetic indices, EISCAT, DMSP, SWARM, TEC, AMPERE, etc.).
- aacgmv2: Python library for AACGM-v2 magnetic coordinates