GitHub

TRACERSData

TRACERSData.TRACERSData — Module
TRACERSData

Load data from the TRACERS (Tandem Reconnection and Cusp Electrodynamics Reconnaissance Satellites) mission.

Available Instruments

  • ACE: Analyzer of Cusp Electrons (L2, L3)
  • ACI: Analyzer of Cusp Ions (L2)
  • MSC: Magnetic Search Coil (L2)
  • MAGIC: Magnetometer Demonstration (L2)
  • TS1_ROI, TS2_ROI: Region of Interest event intervals

Quick Example

using TRACERSData

# Load ACE L2 data for TS2
TS2_L2_ACE_DEF("2025-09-27", "2025-09-28")

Data Portal

Public data is served from https://tracers-portal.physics.uiowa.edu/.

source

Installation

using Pkg
Pkg.add("TRACERSData")

An agent skill is included for using TRACERSData.jl with natural language. To install it using skills, run:

npx skills add JuliaSpacePhysics/TRACERSData.jl

Quick Start

The examples below walk through the typical workflow: discover an instrument's datasets, load data for a specified time range, and access variables.

using TRACERSData

# Inspect the ACE instrument's datasets
ACE.datasets
(ts1_l2_def = TS1_L2_ACE_DEF, ts2_l2_def = TS2_L2_ACE_DEF, ts1_l3_pad = TS1_L3_ACE_PITCH_ANGLE_DIST, ts2_l3_pad = TS2_L3_ACE_PITCH_ANGLE_DIST)

From the Julia REPL you can also type ?ACE to view the ACE documentation.

# Resolve a dataset by name
TS2_L2_ACE_DEF
TRACERSLogicalDataset: TS2_L2_ACE_DEF
  Probe (Probe): 
    TS2
  Level (String): 
    l2
  Datatype (String): 
    ace_def
  Url_Pattern (Pattern): 
    TRACERSData.Pattern("https://tracers-portal.physics.uiowa.edu/L2/TS2/{Y}/{M:02d}/{D:02d}/ts2_l2_ace_def_{YMD}_v1.1.0.cdf")
  Metadata (NamedTuple): 
    (description = "ACE Level 2 default electron spectra (counts + differential energy flux)",)

Then call it with a time range to download and load CDF data:

# Download + load CDF data for a time range
ds = TS2_L2_ACE_DEF("2025-09-30", "2025-10-01")

Access individual variables from the loaded CDF dataset using bracket indexing:

ds["ts2_l2_ace_def"]  # differential energy flux [49 energies × 21 anodes × Epoch]

Quick Plots

using TRACERSData
using Dates
using TRACERSData
using DimensionalData
using NaNStatistics: nanmean
using SpacePhysicsMakie, WGLMakie
using SpaceDataModel: setmeta

t0 = DateTime("2025-09-30T09:40")
t1 = DateTime("2025-09-30T10:10")

ace_ds = TS2_L2_ACE_DEF(t0, t1)
eflux  = DimArray(ace_ds["ts2_l2_ace_def"])
counts = DimArray(ace_ds["ts2_l2_ace_counts"])

eflux.metadata["VAR_NOTES"]
"ACE electron differential energy flux as a function of epoch,  energy (49 bins) and look angle (21 directions). Note that small negative values are allowed, due to background subtraction."
eflux = setmeta(eflux, "UNITS" => "eV / (eV cm² sr s)")
eflux[eflux .<= 0] .= 0
counts = setmeta(counts, :colorscale => log10)

# Average over anodes (dim 2) → energy-time, same as IDL: total(def, 2) / 21
en_eflux  = nanmean(eflux; dim=2)
en_counts = nanmean(counts; dim=2)

# Average over energies (dim 1) → anode-time, same as IDL: total(def, 1) / 49
an_eflux  = nanmean(eflux; dim=1)
an_counts = nanmean(counts; dim=1)

tplot([en_eflux, an_eflux, en_counts, an_counts], t0, t1; colormap = :rainbow_bgyrm_35_85_c69_n256)

Reproduce the 4-panel TS2 ACE L3 pitch-angle distribution plot from https://tracers.physics.uiowa.edu/l3-public-data-products

ds = TS2_L3_ACE_PITCH_ANGLE_DIST("2025-09-30", "2025-10-01")
da = DimArray(ds["ts2_l3_ace_pitch_def"])
da[da .<= 0] .= 0

# Apply log10 colorscale metadata
da = setmeta(da, :colorscale => log10, "UNITS" => "eV / (eV cm² sr s)")

# Energy-averaged
en_avg = setmeta(nanmean(da; dim = 1), "CATDESC" => "Energy-Averaged Flux")

# Pitch-angle-averaged
pa_avg = setmeta(nanmean(da; dim = 2), "CATDESC" => "Pitch Angle-Averaged Flux")

# Fixed energy 198.9 eV
# Energy dim is ReverseOrdered (descending), index 36 ≈ 198.9 eV
e_slice = setmeta(da[X(Near(198.9f0))], "CATDESC" => "Energy Channel: 198.9 eV")

# Fixed pitch angle bin 10-20° (center 15°)
pa_slice = setmeta(da[Y(Near(15.0f0))], "CATDESC" => "Pitch Angle Bin: 10-20°")

fig = tplot([en_avg, pa_avg, e_slice, pa_slice], t0, t1; add_title = true, colormap = :rainbow_bgyrm_35_85_c69_n256)

ROI — Region of Interest

Event interval lists in CSV format. Returns a DataFrame:

roi_df = TS2_ROI();
first(roi_df, 5)
5×5 DataFrame
RowStart_EpochEnd_EpochOrbit_NumROI_NumEvent_Tag
DateTimeDateTimeInt64Int64String15
12025-07-27T02:24:282025-07-27T02:31:05491TS2_ROI_00049_1
22025-07-27T04:00:372025-07-27T04:07:49501TS2_ROI_00050_1
32025-07-27T05:37:192025-07-27T05:44:27511TS2_ROI_00051_1
42025-07-27T07:14:242025-07-27T07:21:28521TS2_ROI_00052_1
52025-07-27T08:51:472025-07-27T08:58:56531TS2_ROI_00053_1

API

Instruments

TRACERSData.ACE — Constant
ACE

Analyzer of Cusp Electrons. Measures electron energy spectra and pitch-angle distributions.

Datasets

  • TS1_L2_ACE_DEF, TS2_L2_ACE_DEF: Level 2 default spectra (counts + differential energy flux)
  • TS1_L3_ACE_PITCH_ANGLE_DIST, TS2_L3_ACE_PITCH_ANGLE_DIST: Level 3 pitch-angle distributions

Usage

ACE(; probe="ts2", level="l3")  # resolve dataset (default: ts2, l2)
ACE()("2025-09-27", "2025-09-28")  # load data
source
TRACERSData.ACI — Constant
ACI

Analyzer of Cusp Ions. Toroidal top-hat electrostatic analyzer providing ion flux and pitch-angle distributions. 47 energy steps (8 eV/e – 20 keV/e), 312 ms cadence.

Datasets

  • TS1_L2_ACI_IPD, TS2_L2_ACI_IPD: Level 2 ion pitch-angle distributions

Usage

ACI(; probe="ts2")  # resolve dataset
source
TRACERSData.MSC — Constant
MSC

Magnetic Search Coil. 3-axis AC magnetic field waveforms at 2048 S/s, amplitude-calibrated at 100 Hz. Complex frequency response calibration included in CDFs.

Datasets

  • TS1_L2_MSC_BAC, TS2_L2_MSC_BAC: Level 2 AC magnetic field waveforms

Usage

MSC(; probe="ts2")  # resolve dataset
source
TRACERSData.MAGIC — Constant
MAGIC

Magnetometer Demonstration. 3-axis DC magnetic field measurements at 128 S/s (ROI) / 16 S/s (back orbit). Calibrated against IGRF scalar magnitude. Available in instrument frame, GEI2000, and NEC coordinates.

Datasets

  • TS1_L2_MAGIC, TS2_L2_MAGIC: Level 2 DC magnetic field

Usage

MAGIC(; probe="ts2")  # resolve dataset
MAGIC("2025-09-27", "2025-09-28"; probe="ts2")  # load data
source
TRACERSData.EFI — Constant
EFI

Electric Field Instrument. DC-coupled probe potentials (VDC), electric field (EDC), AC waveforms (EAC), and high-frequency snapshots (EHF).

Team-only

EFI data is not yet available on the public portal. Use the team portal for access.

source
TRACERSData.EPH — Constant
EPH

Ephemeris. Definitive and predictive orbit attitude data.

Team-only

Ephemeris data is not yet available on the public portal. Use the team portal for access.

source

Datasets

TRACERSData.TS1_L2_ACE_DEF — Constant
TS1_L2_ACE_DEF

ACE Level 2 default electron spectra for TS1. Contains raw measured counts and calibrated differential energy flux as a function of anode angle and calibrated energy. 49 energy steps × 21 anodes, 50 ms cadence.

source
TRACERSData.TS1_L2_ACI_IPD — Constant
TS1_L2_ACI_IPD

ACI Level 2 ion pitch-angle distributions for TS1. Differential energy flux as a function of epoch, energy (47 bins), and look angle (16 directions). 312 ms cadence.

source
TRACERSData.TS1_L2_MAGIC — Constant
TS1_L2_MAGIC

MAGIC Level 2 3-axis DC magnetic field for TS1. Available in instrument frame, GEI2000, and NEC coordinates. 128 S/s (ROI) / 16 S/s (back orbit).

source
TRACERSData.TS1_L2_MSC_BAC — Constant
TS1_L2_MSC_BAC

MSC Level 2 3-axis AC magnetic field waveforms for TS1. Sampled at 2048 S/s, amplitude-calibrated at 100 Hz. Available in TSCS and FAC coordinates.

source
TRACERSData.TS2_L2_ACE_DEF — Constant
TS2_L2_ACE_DEF

ACE Level 2 default electron spectra for TS2. Contains raw measured counts and calibrated differential energy flux as a function of anode angle and calibrated energy. 49 energy steps × 21 anodes, 50 ms cadence.

source
TRACERSData.TS2_L2_ACI_IPD — Constant
TS2_L2_ACI_IPD

ACI Level 2 ion pitch-angle distributions for TS2. Differential energy flux as a function of epoch, energy (47 bins), and look angle (16 directions). 312 ms cadence.

source
TRACERSData.TS2_L2_MAGIC — Constant
TS2_L2_MAGIC

MAGIC Level 2 3-axis DC magnetic field for TS2. Available in instrument frame, GEI2000, and NEC coordinates. 128 S/s (ROI) / 16 S/s (back orbit).

source
TRACERSData.TS2_L2_MSC_BAC — Constant
TS2_L2_MSC_BAC

MSC Level 2 3-axis AC magnetic field waveforms for TS2. Sampled at 2048 S/s, amplitude-calibrated at 100 Hz. Available in TSCS and FAC coordinates.

source