GitHub

Tutorial

This tutorial demonstrates how to use Speasy.jl to access space physics data.

Basic Data Retrieval

The simplest way to get data is using string identifiers with get_data:

using Speasy

# Get IMF data from AMDA
imf_data = get_data("amda/imf", "2016-6-2", "2016-6-3")
SpeasyVariable{Float32, 2}: imf
  Time Range: 2016-06-02T00:00:15.000000000 to 2016-06-02T23:59:59.000000000
  Units: nT
  Size: (5400, 3)
  Memory Usage: 106.605 KiB
  Metadata:
    VAR_NOTES: 
    FILLVAL: Any[NaN]
    DEPEND_0: AMDA_TIME
    FIELDNAM: b_gse
    SI_CONVERSION: 1e-9>T
    VALIDMAX: Any[3.4028234663852886e38]
    LABL_PTR_1: Any["bx", "by", "bz"]
    TENSOR_ORDER: 0
    TENSOR_FRAME: GSE
    FORMAT: F11.4
    VAR_TYPE: data
    CATDESC: imf
    DATA: N/A
    VALIDMIN: Any[-3.4028234663852886e38]
    DISPLAY_TYPE: time_series
    UNITS: nT

Find the available datasets and parameters

Speasy.find_datasets — Function
find_datasets(provider, [term...])

Find the available datasets for a given provider, optionally filtered by search terms (only datasets containing all specified terms will be returned.)

Examples

# List all datasets from AMDA provider
find_datasets(:amda)

# List CDA datasets containing "OMNI"
find_datasets(:cda, :OMNI)

# List CDA datasets containing both "OMNI" and "HRO"
find_datasets(:cda, :OMNI, :HRO)

# output
4-element Vector{String}:
 "OMNI_HRO_1MIN"
 "OMNI_HRO2_1MIN"
 "OMNI_HRO_5MIN"
 "OMNI_HRO2_5MIN"

See also: list_parameters

source
Speasy.list_parameters — Function
list_parameters(provider, [dataset]; verbose=false)

Find the available parameters for a given provider or for a specific dataset from provider.

Set verbose=true to print the metadata of the dataset.

Examples

# List all parameters from AMDA provider
list_parameters(:amda)

# List parameters from specific CDA dataset
list_parameters(:cda, "SOHO_ERNE-HED_L2-1MIN")

# output
5-element Vector{String}:
 "est"
 "PH"
 "AH"
 "PHC"
 "AHC"

See also: find_datasets

source
list_parameters(:cda, "SOHO_ERNE-HED_L2-1MIN"; verbose=true)
5-element Vector{String}:
 "est"
 "PH"
 "AH"
 "PHC"
 "AHC"

Using Dynamic Inventory

The dynamic inventory allows you to browse available datasets interactively:

# Create a shorthand reference
const spz = speasy

# Access the AMDA data tree
amda_tree = spz.inventories.data_tree.amda

# Navigate to specific parameters
ace_imf = amda_tree.Parameters.ACE.MFI.ace_imf_all.imf
data = get_data(ace_imf, "2016-6-2", "2016-6-3");
SpeasyVariable{Float32, 2}: imf
  Time Range: 2016-06-02T00:00:15.000000000 to 2016-06-02T23:59:59.000000000
  Units: nT
  Size: (5400, 3)
  Memory Usage: 106.605 KiB
  Metadata:
    VAR_NOTES: 
    FILLVAL: Any[NaN]
    DEPEND_0: AMDA_TIME
    FIELDNAM: b_gse
    SI_CONVERSION: 1e-9>T
    VALIDMAX: Any[3.4028234663852886e38]
    LABL_PTR_1: Any["bx", "by", "bz"]
    TENSOR_ORDER: 0
    TENSOR_FRAME: GSE
    FORMAT: F11.4
    VAR_TYPE: data
    CATDESC: imf
    DATA: N/A
    VALIDMIN: Any[-3.4028234663852886e38]
    DISPLAY_TYPE: time_series
    UNITS: nT

Using Macro

You can also use macro @spz_str to define multiple products:

products = spz"cda/OMNI_HRO_1MIN/flow_speed,E,Pressure"
Pressure_product = products[3]
Product: cda/OMNI_HRO_1MIN/Pressure
  Data (String): 
    cda/OMNI_HRO_1MIN/Pressure
  Transformation (#get_data): 
    get_data

Products are function-like objects, so you can call them with time intervals as arguments to get the data:

Pressure_product("2016-6-2", "2016-6-3")
SpeasyVariable{Float32, 2}: Pressure
  Time Range: 2016-06-02T00:00:00.000000000 to 2016-06-02T23:59:00.000000000
  Units: nPa
  Size: (1440, 1)
  Memory Usage: 18.021 KiB
  Metadata:
    VAR_NOTES: Derived parameters are obtained from the following equations. Flow pressure = (2*10**-6)*Np*Vp**2 nPa (Np in cm**-3, Vp in km/s, subscript p for proton) 
    FILLVAL: Any[99.98999786376953]
    DEPEND_0: Epoch
    BIN_LOCATION: 0.0
    FIELDNAM: Flow pressure
    VALIDMAX: Any[100.0]
    SCALEMAX: Any[100.0]
    FORMAT: F5.2
    VAR_TYPE: data
    CATDESC: Flow pressure (nPa)
    SCALEMIN: Any[0.0]
    LABLAXIS: Flow pressure
    VALIDMIN: Any[0.0]
    DISPLAY_TYPE: time_series
    UNITS: nPa

Multiple Parameters

You can request multiple parameters at once and get them as a NamedTuple:

products = [
    spz.inventories.tree.amda.Parameters.Wind.SWE.wnd_swe_kp.wnd_swe_vth,
    spz.inventories.tree.amda.Parameters.Wind.SWE.wnd_swe_kp.wnd_swe_pdyn,
    spz.inventories.tree.amda.Parameters.Wind.SWE.wnd_swe_kp.wnd_swe_n
]

data = get_data(NamedTuple, products, "2010-01-02", "2010-01-02T01")
(wnd_swe_vth = wnd_swe_vth [Time Range: 2010-01-02T00:00:34.450000000 to 2010-01-02T00:58:42.023000000, Units: km/s, Size: (36, 1)], wnd_swe_pdyn = wnd_swe_pdyn [Time Range: 2010-01-02T00:00:34.450000000 to 2010-01-02T00:58:42.023000000, Units: nPa, Size: (36, 1)], wnd_swe_n = wnd_swe_n [Time Range: 2010-01-02T00:00:34.450000000 to 2010-01-02T00:58:42.023000000, Units: cm-3, Size: (36, 1)])
data.wnd_swe_n
SpeasyVariable{Float32, 2}: wnd_swe_n
  Time Range: 2010-01-02T00:00:34.450000000 to 2010-01-02T00:58:42.023000000
  Units: cm-3
  Size: (36, 1)
  Memory Usage: 1.570 KiB
  Metadata:
    VAR_NOTES: 
    FILLVAL: Any[NaN]
    DEPEND_0: AMDA_TIME
    FIELDNAM: density
    SI_CONVERSION: 
    VALIDMAX: Any[3.4028234663852886e38]
    TENSOR_ORDER: 0
    TENSOR_FRAME: 
    FORMAT: F11.4
    VAR_TYPE: data
    CATDESC: wnd_swe_n
    DATA: N/A
    LABLAXIS: density
    VALIDMIN: Any[-3.4028234663852886e38]
    DISPLAY_TYPE: time_series
    UNITS: cm-3

Multiple Time Intervals

You can also request data for multiple time intervals:

products = [
    "cda/OMNI_HRO_1MIN/flow_speed",
    "cda/OMNI_HRO_1MIN/Pressure"
]

intervals = [
    ["2010-01-02", "2010-01-02T01"],
    ["2009-08-02", "2009-08-02T01"]
]

get_data(products, intervals)
2-element Vector{Vector{SpeasyVariable{Float32, 2}}}:
 [flow_speed [Time Range: 2010-01-02T00:00:00.000000000 to 2010-01-02T00:59:00.000000000, Units: km/s, Size: (60, 1)], flow_speed [Time Range: 2009-08-02T00:00:00.000000000 to 2009-08-02T00:59:00.000000000, Units: km/s, Size: (60, 1)]]
 [Pressure [Time Range: 2010-01-02T00:00:00.000000000 to 2010-01-02T00:59:00.000000000, Units: nPa, Size: (60, 1)], Pressure [Time Range: 2009-08-02T00:00:00.000000000 to 2009-08-02T00:59:00.000000000, Units: nPa, Size: (60, 1)]]

Working with SSC Data

For trajectory data from SSCWeb:

# Get spacecraft trajectory (default is GSE)
trajectory = get_data("ssc/wind", "2016-6-2", "2016-6-3")

# Specify coordinate system
trajectory_gsm = get_data("ssc/wind/gsm", "2016-6-2", "2016-6-3")
SpeasyVariable{Float64, 2}: 
  Time Range: 2016-06-02T00:00:00.000000000 to 2016-06-02T23:48:00.000000000
  Units: km
  Size: (120, 3)
  Memory Usage: 4.404 KiB
  Metadata:
    CoordinateSystem: GSM
    UNITS: km

Accessing Data Properties

times(data.wnd_swe_n) # timestamps
parent(data.wnd_swe_n) # data values
36×1 PyArray{Float32, 2}:
 NaN
   7.661206
   7.0948887
   7.0640645
   6.8097296
   7.281172
   7.003752
   7.084024
   6.8727236
   7.785167
   ⋮
   8.654632
   8.165966
   7.710116
   8.210449
   7.5762434
   7.8650913
   5.9453
   7.1250095
   7.671092