API Reference

AbstractCoordinateSystem

Base abstract type for all coordinate system implementations.

AbstractCoordinateVector

Base abstract type to represent coordinates in a coordinate systems.

A variable v of a type derived from AbstractDataVariable should at least implement:

• Base.parent(v): the parent array of the variable

Optional:

• times(v): the timestamps of the variable
• units(v): the units of the variable
• getmeta(v): the metadata of the variable
• name(v): the name of the variable
• dim(v, i): the i-th dimension of the variable
• dim(v, name): the dimension named name of the variable

A specific realization of a reference system.

Abstract base for representing a point in a 3D coordinate system.

Reference:

• https://docs.astropy.org/en/stable/coordinates/representations.html
• https://github.com/JuliaEarth/CoordRefSystems.jl/blob/main/src/crs.jl

Archive(pattern, reader=(paths, t0, t1) -> paths)

A source mirroring a URL-per-step archive: remotefiles enumerates, localize caches, reader(paths, t0, t1) opens and returns data over [t0, t1).

Unpublished steps are dropped, a gap being normal; a range publishing nothing throws, since no reader can open an empty file list.

An iterator over continuous segments of a time array, where consecutive times differ by at most max_dt.

Dataset(name, source; selectors=(;), metadata=NoMetadata(), kw...)

A named dataset with domains for its selectors and a source that materializes it over a time range via getdata.

selectors maps each selector name to its domain: a single value, a collection, or Any for open. Values are spelled as strings.

name may carry {selector} placeholders, filled when selection pins open domains; a source templates itself the same way.

FilePattern(pattern; cadence=Day(1), kw...)

A template for the names of an archive's files, one per cadence.

Text in {} is a placeholder: {t:fmt} renders the step's start through the Dates format fmt ({t:mm-dd}, {t:yyyyjjj} with j for day of year) and {t1:fmt} the last instant it covers, for archives naming both ends. A name without a format is a keyword; {name|U} and {name|L} render its value upper- or lowercased. Everything else is literal.

Keywords may be filled at construction, when specializing, or at the call; every one must be filled before a name is rendered. Filling a keyword with "*" leaves a wildcard for resolve_url to match against the archive's listing.

julia> using Dates

julia> FilePattern("g13_xrs_1m_{t:yyyymm}01_{t1:yyyymmdd}.nc"; cadence=Month(1))(Date(2012, 2))
"g13_xrs_1m_20120201_20120229.nc"

Fill keywords and t, giving a URL.

Product(dataset, variable; metadata=NoMetadata(), kw...)

A variable of a dataset: with optional layered metadata (e.g. a plot label override).

Registry(name, datasets; defaults=(;), metadata=NoMetadata(), kw...)

A relation of Datasets: rows sharing a selector vocabulary. A mission, an instrument, or any other grouping is a Registry.

SchemaDict(schema, data)
SchemaDict(schema, pairs::Pair...)

Dict tagged with a MetadataSchema, recovered by get_schema.

An iterator over a series of time ranges that are window long, with a cadence of cadence.

Transformed(f, source; metadata=NoMetadata(), kw...)

A derived product: getdata materializes source and applies f to the result.

available(x, t0, t1; kwargs...)

Times in [t0, t1) at which x has data.

get_schema(data)

Get the metadata schema for data. Returns the tagged schema if metadata is a SchemaDict, otherwise infers from content ("CATDESC" ⇒ ISTPSchema), falling back to DefaultSchema.

getcsys(x)

Get the coordinate system of x. Ideally, this should return both the reference frame and coordinate representation.

If x is a instance of AbstractCoordinateSystem, return x itself. If x is a type of AbstractCoordinateSystem, return an instance of the coordinate system, i.e. x().

This is a generic function, packages should extend it for their own types.

getdata(x, t0, t1; kwargs...)

Materialize x over [t0, t1).

getmeta(x, key, default=nothing)

Get metadata value associated with key for object x, or default if key is not present.

getmeta(x)

Get metadata for object x. If x does not have metadata, return NoMetadata().

localize(url; dir=datadir(), update=false) -> String
localize(urls; ntasks=4, kw...) -> Vector{String}

Return a local path for each URL, downloading files missing from the cache.

Set the SPACE_DATA_DIR environment variable to override the default cache directory.

Set update = true to force re-download, or a Period to refetch if the local copy is older.

remotefiles(p::FilePattern, t0, t1; refresh=false, version="*", kw...) :: Vector{String}

URLs of the files over [t0, t1). Steps with no published file are dropped rather than an error, since a gap in an archive is normal.

Keywords fill p's placeholders; version defaults to the * wildcard, picking the highest listed. refresh=true bypasses memoized directory listings.

resolve_url(url; refresh=false)

Concrete URL for url, where each * in the file name is replaced with the highest version field published in the directory, or nothing if the directory lists no such file.

A field matches any width and any separator (e.g., v03, v03.06, v03_01, v1.1.10). A name may carry more than one, as MAVEN's …_v02_r00.cdf does; fields rank left to right.

setmeta(x, key => value, ...; symbolkey => value2, ...)
setmeta(x, dict::AbstractDict)

Update metadata for object x for key key to have value value and return x.

setmeta!(x, key => value, ...; symbolkey => value2, ...)
setmeta!(x, dict::AbstractDict)

Update metadata for object x in-place and return x. The metadata container must be mutable.

The arguments could be multiple key-value pairs or a dictionary of metadata; keyword arguments are also accepted.

Examples

setmeta!(x, :units => "m/s", :source => "sensor")
setmeta!(x, Dict(:units => "m/s", :quality => "good"))
setmeta!(x; units="m/s", calibrated=true)

Throws an error if the metadata is not mutable. Use setmeta for immutable metadata.

filter(reg::Registry; selectors...)

The rows of reg every supplied selector matches, each with the matched columns pinned.

dim(x, i)
dim(x, name)

Get the i-th dimension of object x, or the dimension associated with the given name. The default implementation returns axes(x, i).

A dimension may be time-varying or dependent on other dimensions; in such cases, the effective size of the corresponding array dimension ndims can be greater than 1.

pin(ds, values; complete=false)

Pin the open domains of ds named in values and rebuild its name and source with the pinned spellings; untouched domains stay open unless complete=true, which demands every one resolves.

resolve(data, lookup)

Resolve metadata value from data using lookup.

Patterns

• "key" / :key: direct metadata lookup
• ("k1", "k2", ...): priority lookup, first hit wins
• Via(f, lookup): f(data) then resolve lookup on the result
• lookup => default: use default (or default(data)) if lookup misses
• f::Function: call f(data)

select(reg; selectors...)

The one dataset of reg every supplied selector matches, with omitted selectors filled from reg.defaults where the dataset carries them.

Selector names any of the registry's datasets carries.