ELFINData

ELFINData.jl provides a high-level Julia interface to the ELFIN mission's particle and field measurements. The sections below highlight the most common entry points and link to the auto-generated API reference.

Installation

using Pkg
Pkg.add("ELFINData")

Quick Start

The examples in this section walk through the typical workflow: discover an instrument's datasets, load data for the specified time range, and request processed data products.

using ELFINData

# Inspect the Energetic Particle Detector (EPD) datasets
EPD.datasets

Dict{@NamedTuple{probe::String, level::String, datatype::String}, ELFINData.ELFINLogicalDataset{MD, SpaceDataModel.FilePattern{Dates.Day}} where MD} with 6 entries:
  (probe = "a", level = "l1", datatype = "epdef") => ELA_L1_EPDEF
  (probe = "a", level = "l1", datatype = "epdif") => ELA_L1_EPDIF
  (probe = "b", level = "l2", datatype = "epdef") => ELB_L2_EPDEF
  (probe = "b", level = "l1", datatype = "epdef") => ELB_L1_EPDEF
  (probe = "b", level = "l1", datatype = "epdif") => ELB_L1_EPDIF
  (probe = "a", level = "l2", datatype = "epdef") => ELA_L2_EPDEF

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

# Load the instrument's datasets
ELA_L1_FGS("2020-10-01", "2020-10-02")
# Alternatively, specify probe and datatype explicitly. This resolves the same dataset.
# If no time range is given, the call returns the set of datasets
@assert FGM(; probe = "a", datatype = "survey") === ELA_L1_FGS

The following function derives directionally resolved flux spectra (omni, para, anti) and/or pitch-angle spectra from EPD level 2 data.

epd_spectral("2020-10-01", "2020-10-02"; probe = "a")

┌ 16×1731 DimStack ┐
├──────────────────┴───────────────────────────────────────────────────── dims ┐
  ↓ Energy Sampled{Float32} [63.24554f0, …, 6500.0f0] ForwardOrdered Irregular Points,
  → Ti Sampled{Dates.DateTime} [Dates.DateTime("2020-10-01T00:26:53.194"), …, Dates.DateTime("2020-10-01T20:45:49.320")] ForwardOrdered Irregular Points
├────────────────────────────────────────────────────────────────────── layers ┤
  :omni eltype: Float32 dims: Energy, Ti size: 16×1731
  :para eltype: Float32 dims: Energy, Ti size: 16×1731
  :anti eltype: Float32 dims: Energy, Ti size: 16×1731
  :perp eltype: Float32 dims: Energy, Ti size: 16×1731
  :prec eltype: Float32 dims: Energy, Ti size: 16×1731
├──────────────────────────────────────────────────────────────────── metadata ┤
  Dict{Any, Any} with 17 entries:
  "SCALETYP"     => log10
  "FILLVAL"      => Float32[NaN]
  "DEPEND_0"     => "ela_pef_hs_time"
  "FIELDNAM"     => "nflux"
  "VALIDMAX"     => Float32[1.0f6]
  :colorrange    => (10.0, 1.0e7)
  "DEPEND_1"     => "ela_pef_hs_epa_spec"
  :yscale        => log10
  "FORMAT"       => "F12.8"
  :ylabel        => "Energy (keV)"
  "VAR_TYPE"     => "data"
  "CATDESC"      => "half spin res, EnergyPitchAngleTime spectra nflux"
  "LABLAXIS"     => "nflux"
  "VALIDMIN"     => Float32[0.0]
  "DISPLAY_TYPE" => "spectral"
  "DEPEND_2"     => "ela_pef_energies_mean"
  "UNITS"        => "#/(cm^2*s*str*MeV)"
└──────────────────────────────────────────────────────────────────────────────┘

Commonly used variables have concise convenience wrappers. As these variables are uniquely named, they can be accessed directly.

ELA_POS_GEI("2020-10-01", "2020-10-02")
# Alternative ways to access the same variable:
# `STATE("2020-10-01", "2020-10-02"; probe = "a")["ela_pos_gei"]` or
# `ELA_L1_STATE("2020-10-01", "2020-10-02")["ela_pos_gei"]`

ELB_FGS("2020-10-01", "2020-10-02")
# Alternative ways to access the same variable:
# `ELB_L1_FGS("2020-10-01", "2020-10-02")["elb_fgs"]` or
# `FGM("2020-10-01", "2020-10-02"; probe = "b", datatype = "survey")["elb_fgs"]`

ELA_PEF_HS_EPAT_NFLUX("2020-10-01", "2020-10-02")
# Alternative ways to access the same variable:
# `ELA_L2_EPDEF("2020-10-01", "2020-10-02")["ela_pef_hs_Epat_nflux"]` or
# `EPD("2020-10-01", "2020-10-02"; probe = "a", level = "l2", datatype = "epdef")["ela_pef_hs_Epat_nflux"]`

ela_pef_hs_Epat_nflux (10 × 16 × 1731) dims=ela_pef_hs_epa_spec × ela_pef_energies_mean × ela_pef_hs_time [half spin res, EnergyPitchAngleTime spectra nflux; #/(cm^2*s*str*MeV)]

Quick Plots

using ELFINData
using Dates
using ELFINData.DimensionalData
using SpacePhysicsMakie, WGLMakie

# https://data.elfin.ucla.edu/ela/overplots/2022/09/05/ela_l2_overview_20220905_10_ndes.gif
t0 = DateTime("2022-09-05T10:00:00")
t1 = DateTime("2022-09-05T10:30:00")

# Example: plot EPD flux spectra
spectra = epd_spectral(t0, t1; probe = "a")[Ti(t0 .. t1)]
tplot(degap.([spectra.omni, spectra.anti, spectra.perp, spectra.para]); colormap=:turbo)

API

Instruments

Datasets

Variables

Functions and Types

epd_spectral(trange; probe = "a", type = "nflux", datatype = "epdef", fullspin = false)

epd_spectral("2020-10-01", "2020-10-02")