Library

struct Dst

Store the Dst (Disturbance Storm Time) hourly index together with the exospheric temperature variation derived from it.

Fields

• vjd::Vector{Float64}: Julian dates of the hourly samples.
• vdst::Vector{Float64}: Dst values [nT] at each sample.

abstract type SpaceIndexSet

Abstract type for all structures that represent space index sets.

_deduplicate_dst!(vjd::Vector{Float64}, vdst::Vector{Float64}) -> Nothing

Remove duplicate Julian dates from vjd in-place, keeping the last vdst value for each date. The function assumes that vjd is sorted in ascending order and resizes both vectors to the deduplicated length.

_get_latest_month_with_provisional_data() -> Union{Tuple{Int, Int}, Nothing}

Determine the latest year and month for which Kyoto WDC has published provisional Dst data. The function first downloads the index page https://wdc.kugi.kyoto-u.ac.jp/dst_provisional/ to a temporary file and scans it for YYYYMM references.

If the index page cannot be downloaded or no valid month is found in it, the function falls back to probing the monthly pages in reverse, starting from the current month and walking back to the start of the provisional period, returning the first month that downloads successfully.

Returns

• Union{Tuple{Int, Int}, Nothing}: Tuple (year, month) with the latest provisional month, or nothing if no provisional month could be determined.

_parse_dst_html!(
    vjd::Vector{Float64},
    vdst::Vector{Float64},
    filepath::String
) -> Nothing

Parse the Dst HTML file filepath from the Kyoto WDC and append the hourly Julian dates to vjd and the corresponding Dst values to vdst.

The Kyoto WDC HTML pages embed Dst data in a <pre> block with one line per day. Each data line contains a day number followed by 24 hourly values, each in a fixed-width 4-character field. The fill value 9999, used by Kyoto for hours that are not yet available in real-time data, is ignored.

_round_Kp(x::Float64)

Celestrak mulitples Kp by 10 and rounds to the nearest integer this puts it back.

auto_init(::Type{T}) where T<:SpaceIndexSet -> Bool

Return whether the space index set T should be initialized automatically by the no- argument init(). Sets that return false must be initialized explicitly via init(T).

constant_interpolation(knots::AbstractVector, values::AbstractVector, x) -> eltype(values)

Perform a constant interpolation at x of values evaluated at knots. The interpolation returns value(knots[k-1]) in which knots[k-1] <= x < knots[k].

destroy() -> Nothing

Destroy the objects of all space index sets that were initialized.

expiry_periods(::Type{T}) where T<:SpaceIndexSet -> Vector{DatePeriod}

Return the expiry periods for the remote files associated with the space index set T. If a time interval greater than this period has elapsed since the last download, the remote files will be downloaded again.

filenames(::Type{T}) where T<:SpaceIndexSet -> Vector{String}

Return the filenames for the remote files associated with the space index set T. If this function is not defined for T, the filenames will be obtained based on the URLs.

get_download_timestamp(filepath::String) -> Union{DateTime, Nothing}

Return the download timestamp associated with the file filepath.

The timestamp is read from a companion file with the same path as filepath and the suffix _timestamp. If either the data file or the timestamp file is missing, or if the timestamp cannot be parsed, the function returns nothing.

get_filepath(filename::String, key::String) -> String

Return the absolute path of filename inside the scratch space identified by key.

If the scratch space associated with key does not exist yet, it is created.

init(; blocklist::Vector = []) -> Nothing

Initialize all the registered space index sets.

This function will download the remote files associated to the space index sets if they do not exist or if the expiry period has been elapsed. Afterward, it will parse the files and populate the objects to be accessed by the function space_index.

Space index sets where auto_init(T) returns false (e.g. Dst) are always skipped and must be initialized explicitly via init(T).

If the user does not want to initialize some additional sets, they can pass them in the keyword blocklist.

init(::Type{T}; kwargs...) where T<:SpaceIndexSet -> Nothing

Initialize the space index set T.

This function will download the remote files associated with the space index set T if they do not exist or if their expiry period has been elapsed. Aftward, it will parse the files and populate the object to be accessed by the function space_index.

Keywords

• force_download::Bool: If true, the remote files will be downloaded regardless of their timestamps. (Default = false)
• filepaths::Union{Nothing, Vector{String}}: If it is nothing, the function will download the space index files from the locations specified in the urls API function. However, the user can pass a vector with the file locations, which will be used instead of downloading the data. In this case, the user must provide all the files in the space index set T. (Default = nothing)

linear_interpolation(knots::AbstractVector, values::AbstractVector, x)

Perform a linear interpolation at x of values evaluated at knots.

parse_files(::Type{T}, filepaths::Vector{String}) where T<:SpaceIndexSet -> T

Parse the files associated with the space index set T using the files in filepaths. It must return an object of type T with the parsed data.

space_index(::Val{:index}, jd::Number; kwargs...) -> Number
space_index(::Val{:index}, date::DateTime; kwargs...) -> Number

Get the space index for the Julian day jd or the instant. The latter must be an object of type DateTime. kwargs... can be used to pass additional configuration for the space index.

space_index(::Val{:Ap30}, jd::Number) -> NTuple{48, Float64}

Return the Ap30 index for the day at Julian Day jd.

The Ap30 index is the linear equivalent of Hp30 geomagnetic activity. This function returns all 48 values for the day containing the given Julian Day.

space_index(::Val{:Ap60}, jd::Number) -> NTuple{24, Float64}

Return the ap60 index for the day at Julian Day jd.

The ap60 index is the linear equivalent of Hp60 geomagnetic activity. This function returns all 24 values for the day containing the given Julian Day.

space_index(::Val{:Ap_daily}, jd::Number) -> Int64

Get the daily Ap index for the day at instant.

space_index(::Val{:Ap}, jd::Number) -> NTuple{8, Float64}

Get the Ap index for the day at instant compute every three hours.

space_index(::Val{:BSRN}, jd::Number) -> Int64

Get the BSRN index for the day at instant

space_index(::Val{:C9}, jd::Number) -> Float64

Get the C9 index for the day at instant

space_index(::Val{:Cp}, jd::Number) -> Float64

Get the Cp index for the day at instant

space_index(::Val{:DTC}, date::Number) -> Float64

Get the exospheric temperature variation [K] caused by the Dst index at instant (UTC).

space_index(::Val{:Dst}, jd::Number) -> Float64

Get the Dst (Disturbance Storm Time) index [nT] at the Julian Day jd.

The Dst index measures the intensity of the globally symmetric part of the equatorial ring current. Negative values indicate geomagnetic storms. Values are linearly interpolated between hourly observations.

For times beyond the last available observation, the Dst series is extended with quiet-time values (0 nT) so that any in-progress storm recovery completes naturally through the dTc integral.

Reference

• [1] WDC for Geomagnetism, Kyoto University. https://wdc.kugi.kyoto-u.ac.jp/dstdir/

space_index(::Val{:F10adj_avg_center81}, jd::Number) -> Float64

Get the adjusted F10.7 index (10.7-cm solar flux) [10⁻²² W / (M² ⋅ Hz)] averaged over 81 days centered for the instant (UTC).

space_index(::Val{:F10adj_avg_last81}, jd::Number) -> Float64

Get the adjusted F10.7 index (10.7-cm solar flux) [10⁻²² W / (M² ⋅ Hz)] averaged over the last 81 days from the instant (UTC).

space_index(::Val{:F10adj}, jd::Number) -> Float64

Get the adjusted F10.7 index (10.7-cm solar flux) [10⁻²² W / (M² ⋅ Hz)] for the instant (UTC).

space_index(::Val{:F10obs_avg_center81}, jd::Number) -> Float64

Get the observed F10.7 index (10.7-cm solar flux) [10⁻²² W / (M² ⋅ Hz)] averaged over 81 days centered for the instant (UTC).

space_index(::Val{:F10obs_avg_last81}, jd::Number) -> Float64

Get the observed F10.7 index (10.7-cm solar flux) [10⁻²² W / (M² ⋅ Hz)] averaged over the last 81 days from the instant (UTC).

space_index(::Val{:F10obs}, jd::Number) -> Float64

Get the observed F10.7 index (10.7-cm solar flux) [10⁻²² W / (M² ⋅ Hz)] for the instant (UTC).

space_index(::Val{:Hp30}, jd::Number) -> NTuple{48, Float64}

Return the Hp30 index for the day at Julian Day jd.

The Hp30 index represents geomagnetic activity with 30-minute resolution. This function returns all 48 values for the day containing the given Julian Day.

space_index(::Val{:Hp60}, jd::Number) -> NTuple{24, Float64}

Return the Hp60 index for the day at Julian Day jd.

The Hp60 index represents geomagnetic activity with 60-minute (hourly) resolution. This function returns all 24 values for the day containing the given Julian Day.

space_index(::Val{:ISN}, jd::Number) -> Int64

Get the ISN index for the day at instant

space_index(::Val{:Kp_daily}, jd::Number) -> Float64

Get the daily Kp index for the day at instant.

space_index(::Val{:Kp}, jd::Number) -> NTuple{8, Float64}

Get the Kp index for the day at instant compute every three hours.

get_space_index(::Val{:M10}, date::Number) -> Float64

Get the MG2 index scaled to F10.7 [10⁻²² W / (M² ⋅ Hz)] for the instant (UTC).

space_index(::Val{:M81a}, date::Number) -> Float64

Get the 81-day averaged MG2 index scaled to F10.7 [10⁻²² W / (M² ⋅ Hz)] for the instant (UTC).

space_index(::Val{:ND}, jd::Number) -> Int64

Get the ND index for the day at instant

space_index(::Val{:S10}, date::Number) -> Float64

Get the EUV index (26-34 nm) scaled to F10.7 [10⁻²² W / (M² ⋅ Hz)] for the instant (UTC).

space_index(::Val{:S81a}, date::Number) -> Float64

Get the 81-day averaged EUV index (26-34 nm) scaled to F10.7 [10⁻²² W / (M² ⋅ Hz)] for the instant (UTC).

space_index(::Val{:Y10}, date::Number) -> Float64

Get the solar X-ray & Lya index scaled to F10.7 [10⁻²² W / (M² ⋅ Hz)] for the instant (UTC).

space_index(::Val{:Y81a}, date::Number) -> Float64

Get the 81-day averaged solar X-ray & Lya index scaled to F10.7 [10⁻²² W / (M² ⋅ Hz)] for the instant (UTC).

update_download_timestamp(filepath::String) -> Nothing

Write the current time as the download timestamp of the file filepath.

The timestamp is stored in a companion file with the same path as filepath and the suffix _timestamp, using the default DateTime string representation.

urls(::Type{T}) where T<:SpaceIndexSet -> Vector{String}

Return the URLs to fetch the remote files associated with the space index set T.

@data_handler(T)

Return the optional data handler associated with space index set T. This variable stores an instance of T if the set was already initialized.

@object(T)

Return the object associated with the space index set T.

Throws

• Error: If the space index T was not initialized.

@register(T)

Register the the space index set T. This macro push the data into the global vector of space files and also creates the optional data handler for the processed structure.