API

StationData(
    var_data::Union{VariableData, AbstractVector{<:VariableData}},
    station_id::Integer;
    include_sources = false
) -> StationData

A struct representing all the data available for a given station, including its metadata and observations for multiple variables.

Fields

• id::Int: The station ID. Example: 123.
• name::String: The name of the station. Example: "VAEXJOE
• latitude::Int: The latitude of the station in arcseconds. Example: 1234567 for 34.2919°.
• longitude::Int: The longitude of the station in arcseconds. Example: -1234567 for -34.2919°.
• elevation::Int: The elevation of the station in meters. Example: 100 for 100 meters above sea level.
• variables::Vector{VariableData}: The list of variables for which observations are included in this station data.
• observations::DataFrame: A data frame containing the observations for this station, with one row per date and variable. The columns are:
  • station_id::Int: The station ID. Example: 123.
  • date::Date: The date of the observation. Example: Date(1950, 1, 1).
  • For each variable, there are three columns:
    • variable_value: The value of the observation for this variable. Example: 150 for a temperature of 15.0°C if the unit is 0.1
    • variable_quality: The quality flag of the observation for this variable. Is one of "valid", "suspect" or "missing". Example: "valid".
    • variable_element_id: The element ID of the observation for this variable. Example: TX1 for the first element of the :tx (temperature max) variable.

VariableData(variable::Variable, filepath::String; memory_map = true)

A variable with its associated data. If you don't know what memory_map means, keep it to true.

Fields

• variable::Variable: The variable this data corresponds to.
• filepath::String: The path to the zip file containing the data for this variable.
• content::ZipReader{<:AbstractVector{UInt8}}: A ZipReader instance for reading the contents of the zip file.

Accessor methods are provided for convenience:

• variable(var::VariableData): Get the variable.
• zipfile(var::VariableData): Get the path to the zip file.
• zipcontent(var::VariableData): Get the ZipReader for the zip file.
• ZipArchives.zip_names(var::VariableData): Get the list of file names in the zip archive.
• ZipArchives.zip_readentry(var::VariableData, args...; kwargs...): Read a specific entry from the zip archive.

To load specific data, use the provided functions:

• load_sources(var::VariableData): Load the sources data frame from the zip file.
• load_stations(var::VariableData): Load the stations data frame from the zip file.
• load_elements(var::VariableData): Load the elements data frame from the local elements file.
• load_elements(var::VariableData, file): Load the elements data frame from a specified file.
• load_observations(var::VariableData, station_id): Load the observations data frame for a specific station ID from the zip file.

canonical_name(var::Variable) -> Symbol

Return the canonical name of a variable as a symbol. The canonical name is the primary identifier for a variable, and all aliases for that variable will map to this canonical name.

Example

julia> canonical_name(CloudCover())
:cc

dataset_zip(var)

Get the path to the zip file for the given variable. The variable can be specified using any of its aliases, e.g. :tx, :temperature_max, or "temperature_max".

intersect_stations(vars::AbstractVector{<:VariableData}) -> DataFrame

Find all stations that are present across all provided variables, returning their shared metadata.

This is useful when you want to build a StationData for multiple variables and need to know which station IDs are valid for all of them — i.e. which stations have observations for every variable in vars.

Returns a DataFrame with one row per common station, with columns:

• id::Int: The station ID.
• name::String: The name of the station.
• country_code::String: The ISO country code.
• latitude_arcsec::Int: The latitude in arcseconds.
• longitude_arcsec::Int: The longitude in arcseconds.
• height_meter::Int: The elevation in meters above sea level.

Throws

• ArgumentError if vars is empty.

Example

vars = VariableData.([:tg, :tx, :tn])
common = intersect_stations(vars)
station_data = StationData.(Ref(vars), common.id)

load_elements() -> DataFrame
load_elements(var::VariableData, file = nothing) -> DataFrame

Load the elements for the given variable, or everything. Elements are variants of the same variable that may have different units or observation methods. For example, for :tg (temperature mean), a variant simply compute the mean of the daily max and min, while another method compute the mean of each hourly observation.

Columns

• element_id::Int: The element ID. Example: TX1 for the first element of the :tx (temperature max) variable.
• description::String: A description of the element. Example: "Daily maximum temperature calculated from the maximum of the daily observations".
• unit::String: The unit of the element. Example: "0.1°C".
• variable_id::String: The canonical name of the variable this element belongs to. Example: "TX" for :tx (temperature max).
• variable_name::String: A human-readable name of the variable this element belongs to. Example: "MAX TEMPERATURE" for :tx (temperature max).

load_observations(var::VariableData, station_id::Integer) -> DataFrame

Load the observations for the given variable and station ID from the zip file. The station ID must be one of the IDs returned by station_ids(var).

A warning is emitted if there are multiple elements in the observations, meaning that the observations may have different units / observation methods. In that case, the elements data frame returned by load_elements(var) should be consulted to see what each element ID means.

Columns

• station_id::Int: The station ID. Example: 123.
• source_id::Int: The source ID associated with this observation. Example: 1. See load_sources for more info on sources.
• element_id::Int: The element ID associated with this observation. Example: TX1 for the first element of the :tx (temperature max) variable. See load_elements for more info on elements.
• date::Date: The date of the observation. Example: Date(1950, 1, 1).
• value::Int64?: The value of the observation, or missing if not available. The unit depends on the element. See the unit column in the data frame returned by load_elements for more info on the unit of each element.
• quality::String: The quality flag of the observation. Is one of "valid", "suspect" or "missing".

load_sources(var::VariableData) -> DataFrame

Load the sources data frame from the zip file for the given variable.

Columns

• id::Int: The source ID. Example: 1.
• name::String: The name of the source. Example: "VAEXJOE"
• station_id::Int: The station ID associated with this source. Example: 123.
• start_date::Data: The first date of observations from this source. Example: Date(1950, 1, 1).
• end_date::Date: The last date of observations from this source. Example: Date(2020, 12, 31).
• country_code::String: The ISO country code of the source. Example: "SE" for Sweden.
• longitude_arcsec::Int: The longitude of the source in arcseconds.
• latitude_arcsec::Int: The latitude of the source in arcseconds.
• height_meter::Int: The height of the source in meters.
• participant_id::Int: The ID of the participant that provided this source. Example: 42.
• participant_name::String: The name of the participant that provided this source. Example: ""Marcus Flarup"
• element_id::Int: The ID of the element observed by this source. See load_elements for more info.

load_stations(var::VariableData) -> DataFrame

Load the stations data frame from the zip file for the given variable.

Columns

• id::Int: The station ID. Example: 123.
• name::String: The name of the station. Example: "VAEXJOE".
• country_code::String: The ISO country code of the station. Example: "SE" for Sweden.
• longitude_arcsec::Int: The longitude of the station in arcseconds.
• latitude_arcsec::Int: The latitude of the station in arcseconds.
• height_meter::Int: The height of the station in meters.

longname(var::Variable) -> String

Return a human-readable long name for the variable, suitable for display in plots and tables. By default, this is generated by converting the variable type name from CamelCase to a underscore-separated lowercase string. For example, CloudCover would become cloud_cover.

You can override this by providing a custom long name when defining the variable type.

Example

julia> longname(CloudCover())
:cloud_cover

pretty_name(var::Variable) -> String

Return a pretty name for the variable, which can be used in contexts where a more concise or stylized name is desired. By default, this is generated by converting the variable type name from CamelCase to a space-separated lowercase string. For example, CloudCover would become cloud cover.

You can override this by providing a custom pretty name when defining the variable type.

Example

julia> pretty_name(CloudCover())
"cloud cover"

station_ids(var::VariableData) -> Vector{Int}

The list of station IDs available in the zip file for the given variable.

variable(var::VariableData) -> Variable

The variable associated with the given VariableData.

zipcontent(var::VariableData) -> ZipReader

The ZipReader instance for the zip file associated with the given VariableData.

zipfile(var::VariableData) -> String

The path to the zip file associated with the given VariableData.

@defvariable TypeName canonical_name

Define a Variable subtype and automatically register canonical_name and from_name methods for it.