AbstractClimateDiagnostic

Abstract parent type unifying ECCOdiag, SSTdiag, SurfaceFluxDiag, and SeaLevelAnomaly for shared dispatch (e.g. plot).

ECCOdiag <: AbstractClimateDiagnostic

Container type for ECCO diagnostics: file location, name, options, and optionally already-loaded data.

Fields

• path::String: directory containing the diagnostic's output file(s) (defaults to tempdir()).
• name::String: name of the diagnostic/variable, used both to select the file to load (see load(::ECCOdiag)) and, for several plot types, to select the rendering method (e.g. name=="OHT", name=="overturn", name=="trsp" — see plot in the Makie extension).
• options::NamedTuple: plot/computation options, typically built via setopt rather than assigned directly.
• data::AbstractArray: optional pre-loaded data; empty by default.

Constructors

ECCOdiag(; path, name, options, data)                 # keyword constructor
ECCOdiag(path::String, name::String, plot_type::Symbol; kwargs...)

The three-argument form builds options automatically via setopt(plot_type; kwargs...), which applies default_options for plot_type merged with any kwargs, then finalize_options. This is the preferred way to construct an ECCOdiag for plotting.

See also SSTdiag, load, setopt.

ECCOdiag(path::String, name::String, plot_type::Symbol; kwargs...)

Convenience constructor: builds options via setopt(plot_type; kwargs...) (applying default_options for plot_type then finalize_options), and sets path/name directly. Preferred over assigning options=(...) by hand.

SSTdiag <: AbstractClimateDiagnostic

Container type for SST (OISST) diagnostics: file location, name, options, and optionally already-loaded data.

Fields

• path::String: directory associated with the diagnostic (default "unknown" — note this differs from ECCOdiag's tempdir() default).
• name::String: name of the diagnostic, used by the Makie extension's title_or for figure titles when non-empty/non-"unknown".
• options::NamedTuple: plot options, typically built via the plot_type constructor below.
• data::AbstractArray: optional pre-loaded data; empty by default.

Constructors

SSTdiag(; path, name, options, data)                  # keyword constructor
SSTdiag(path::String, name::String, plot_type::Symbol; kwargs...)

The three-argument form merges default_options for plot_type with any kwargs.

See also ECCOdiag, getopt, year_range.

SSTdiag(path::String, name::String, plot_type::Symbol; kwargs...)

Convenience constructor: merges default_options for plot_type with kwargs, and sets path/name directly.

SeaLevelAnomaly <: AbstractClimateDiagnostic

Container type for sea-level-anomaly diagnostics, mirroring ECCOdiag's shape: path, name, options, and optionally pre-loaded data.

SurfaceFluxDiag <: AbstractClimateDiagnostic

Container type for surface heat/flux diagnostics.

Fields

• options::NamedTuple: plot options; options.plot_type selects among :default, :surface_balance, :Qnet_cumsum (see plot in the Makie extension).
• data::Union{DataFrame,NamedTuple}: the underlying data, whose shape depends on plot_type — a plain DataFrame for :default (bulk-formula output), or a (df=..., tim=..., sst=...) NamedTuple for :surface_balance/:Qnet_cumsum.

Examples

da = SurfaceFluxDiag((plot_type=:default,), df)
da = SurfaceFluxDiag((plot_type=:surface_balance,), (df=df,tim=tim,sst=sst))

default_options(::Val{T}) where T

Return the baseline options NamedTuple for a given plot_type symbol T, dispatched via Val so that each plot type can declare its own defaults.

The generic fallback returns just (plot_type=T,). Specific plot types override this method (dispatching on their own Val{:plot_type_name}) to add fields such as period or years_to_display — or to omit them entirely when no sensible default exists (e.g. required opaque payloads like a grid Γ, supplied only at construction time).

Examples

default_options(Val(:ECCO_OHT1))
# (plot_type = :ECCO_OHT1, period = (1992, 2011), years_to_display = nothing)

See also getopt, setopt, year_range.

finalize_options(o::NamedTuple)

Normalize an options NamedTuple o after merging defaults with user-supplied overrides.

Currently performs one normalization: if o has a :years_to_display field that is nothing, and also has a :period field (y0,y1), it sets years_to_display = (y0, y1+1) — i.e. defaults the display window to period extended by one year at the end (matching the half-open month indexing used elsewhere, e.g. year_range). Otherwise o is returned unchanged.

Called automatically by setopt; not needed if you build options via setopt rather than by hand.

See also setopt, getopt, year_range.

getopt(o::NamedTuple, k::Symbol, default)

Defensively read field k from the options NamedTuple o, returning default instead of throwing a KeyError if k is absent.

getopt(o,k,default) = haskey(o,k) ? getproperty(o,k) : default

This is the preferred way to read optional fields from an ECCOdiag/SSTdiag options object — in particular for fields (like :years_to_display) that may not be present when the object was constructed by hand (e.g. options=(...)) rather than via setopt.

Examples

getopt(o, :years_to_display, nothing)

See also setopt, year_range.

setopt(plot_type::Symbol; kwargs...)

Construct a finalized options NamedTuple for plot_type, starting from default_options and overriding/adding any fields passed as keyword arguments.

setopt(plot_type::Symbol; kwargs...) =
    finalize_options(merge(default_options(plot_type), NamedTuple(kwargs)))

This is the preferred way to build an options object for an ECCOdiag/ SSTdiag, rather than writing options=(...) by hand — it guarantees every plot-type-specific default is present, then applies finalize_options to validate/normalize the result.

Examples

o = setopt(:ECCO_OHT1; years_to_display=(1995,2005))

See also getopt, default_options, year_range.

year_range(o::NamedTuple)

Return the (Y0, Y1) year range that should be used when averaging or selecting a time sub-window for o, falling back to o.period when o.years_to_display is absent or nothing.

(year0, year1) = o.period
yd = getopt(o, :years_to_display, nothing)
isnothing(yd) ? (year0, year1 + 1) : yd

This is the single defensive accessor for years_to_display across all ECCOdiag/SSTdiag plot types, closing a KeyError risk for any options object built by hand rather than via setopt/finalize_options.

Its meaning depends on the plot type's structure:

• For genuine time-series plot types (e.g. ECCO_Overturn1, ECCO_Transports, ECCO_GlobalMean, ECCO_TimeLat, ECCO_DepthTime), the returned (Y0, Y1) sets the plotted x-axis limits directly.
• For time-averaged profile/section plot types (ECCO_OHT1, ECCO_Overturn2), which plot an average against latitude/depth rather than time, (Y0, Y1) instead selects which months get averaged — the index offset is computed relative to o.period's start year, not anchored at index 1:

(year0, year1) = o.period
(Y0, Y1) = year_range(o)
i0 = Int(round((Y0 - year0) * 12 + 1))
i1 = Int(round((Y1 - year0) * 12))

See also getopt, setopt, default_options.

load(x::ECCOdiag; file="", variable="single_stored_object")

Load JLD2 data for diagnostic x, resolving the actual file path from x.path/x.name (and, optionally, an explicit file name).

Extends JLD2.load with ECCOdiag-aware path resolution:

• if x.name contains "zonmean": tries joinpath(x.path,x.name,"zonmean.jld2"), falling back to "zonmean2d.jld2" in the same directory if the former doesn't exist;
• else if x.name contains "_glo2d" or "_glo3d": tries joinpath(x.path,x.name,"glo2d.jld2"), falling back to "glo3d.jld2";
• else if file is given (non-empty): loads joinpath(x.path,x.name,file);
• otherwise: loads joinpath(x.path,x.name,x.name*".jld2").

variable selects which stored object to return from the resolved file (default "single_stored_object", JLD2's default key for save_object).

This dispatch is exported as load and is the standard way to read back data written by ECCO_diagnostics's main_* functions or ECCO_procs's consumers, given only an ECCOdiag's path/name.

fit_time_series(tt::Vector, zz::Vector; order_poly::Int=1, order_season::Int=1)

General time series fitting that handles both numeric and DateTime vectors for time.

Plain arguments :

• tt is time, as a Vector{DateTime} or ::Vector
• zz is the data time series

Keyword arguments:

• order_poly: polynomial degree for time mean, trend, ... (0 to 3)
• order_season: seasonal harmonic order (0 to 3)

dates = collect((DateTime(2020,1,16):Month(1):DateTime(2024,12,31)));
nt=length(dates); data = randn(nt) .+ sin.(2π .* (1:nt) ./ 12)
data_fit = fit_time_series(dates, data; order_season=3)

simple_monthly_climatology(tt::Vector, zz::Vector)

Estimate seasonal component by averaging all Januaries, all Februaries, etc separately. Accepts either numeric vectors or DateTime vectors.

Note: this works best in the absence of net trends.

dates = collect((DateTime(2020,1,16):Month(1):DateTime(2024,12,31)));
nt=length(dates); data = randn(nt) .+ sin.(2π .* (1:nt) ./ 12)
data_smc = simple_monthly_climatology(dates, data)

build_formula(order_poly::Int, order_season::Int)

Build a GLM formula with polynomial trend and seasonal harmonics.

Arguments:

• order_poly: polynomial degree for time mean, trend, ... (0 to 3)
• order_season: seasonal harmonic order (0 to 3)

datetime_to_years(tt::Vector{DateTime})

Convert DateTime vector to time in years, measured from January 1st of the first year in tt. Returns time values offset so that year values are preserved (first year y0 is added back).

t_DT = collect((DateTime(2020,1,16):Month(1):DateTime(2024,12,31)))
t_years = datetime_to_years(t_DT)
# First value ≈ 2020.0, last value ≈ 2024.92

years_to_datetime(t_years::Vector)

Convert years (as returned by datetimetoyears) back to DateTime objects. Infers the reference year from the first value.

dates = collect((DateTime(2020,1,16):Month(1):DateTime(2024,12,31)));
t_years = Climatology.datetime_to_years(dates);
dates_reconstructed = Climatology.years_to_datetime(t_years)

read_Dataset

alias for NCDatasets.Dataset that is defined by NCDatasets.jl extension

CBIOMESclim_download()

Download lazy artifact to scratch space.

ECCOdiags_add(nam::String)

Add data to the scratch space folder. Known options for nam include "release1", "release2", "release3", "release4", "release5", and "OCCA2HR1".

Under the hood this is the same as:

using Climatology
datadep"ECCO4R1-stdiags"
datadep"ECCO4R2-stdiags"
datadep"ECCO4R3-stdiags"
datadep"ECCO4R4-stdiags"
datadep"ECCO4R5-stdiags"
datadep"OCCA2HR1-stdiags"

ERA5_OISST_download()

Download lazy artifact to scratch space.

MITPROFclim_download()

Download lazy artifact to scratch space.

OISSTstats_download()

Download lazy artifact to scratch space.

__init__standard_diags()

Register data dependency with DataDep.

get_ecco_files(γ::gcmgrid,v::String,t=1)

using MeshArrays, Climatology, MITgcm
γ=GridSpec(ID=:LLC90)
Climatology.get_ecco_variable_if_needed("oceQnet")
tmp=read_nctiles(joinpath(ScratchSpaces.ECCO,"oceQnet/oceQnet"),"oceQnet",γ,I=(:,:,1))

get_ecco_variable_if_needed(v::String)

Download ECCO output for variable v to scratch space if needed

get_ecco_velocity_if_needed()

Download ECCO output for u,v,w to scratch space if needed

get_occa_variable_if_needed(v::String)

Download OCCA output for variable v to scratch space if needed

get_occa_velocity_if_needed()

Download OCCA output for u,v,w to scratch space if needed

unpackDV(filepath)

Like DataDeps's :unpack but using Dataverse.untargz and remove the .tar.gz file.