ECCO.standard_analysis_setup(pth0::String)

Create temporary run folder pth where data folder pth0 will be linked.

Data folder pth0 should be the path to ECCO data.

For example:

using Climatology, Pkg
pth=ECCO.standard_analysis_setup(ScratchSpaces.ECCO)

The Project.toml file found in pth provides an environment ready for ECCO analyses.

This environment can be activated and instantiated:

Pkg.activate(pth)
Pkg.instantiate()

ECCO.diagnostics_set1(path_in=".")

Time-series diagnostics: global-mean and level-1 THETA/SALT, volume transport, meridional heat transport, zonal-mean THETA/SALT/MXLDEPTH/ SSH/SIarea, and overturning — as a DataFrame of (file, name, units, dims) describing each diagnostic's output file location and shape.

ECCO.diagnostics_set2(path_in=".")

2D climatologies on ECCO's LLC90 grid: BSF, MXLDEPTH, SIarea, SSH — as a DataFrame of (file, name, units, dims).

ECCO.diagnostics_set3(path_in=".")

3D climatologies on ECCO's LLC90 grid: THETA, SALT — as a DataFrame of (file, name, units, dims).

parameters(P0,params)

Prepare parameter NamedTuple for use in ECCO_diagnostics.driver.

P1=parameters(P0,p)

is faster than e.g. parameters(pth,"r2",p) as grid, etc get copied from P0 to P1.

parameters(pth0::String,sol0::String,params)

Prepare parameter NamedTuple for use in ECCO_diagnostics.driver.

For example, to compute zonal mean temperatures at level 5:

p=(calc = "zonmean", nam = "THETA", lev = 5)
pth=ECCO.standard_analysis_setup(ScratchSpaces.ECCO)
P0=ECCO_helpers.parameters(pth,"r2",p)

or, from a predefined list:

list0=ECCO_helpers.standard_list_toml("")
pth=ECCO.standard_analysis_setup(ScratchSpaces.ECCO)
P1=ECCO_helpers.parameters(pth,"r2",list0[1])

driver(P)

Call main computation loop as specified by parameters P.

The main computation loop choice depends on the P parameter values. Methods include:

• main_clim
• main_glo
• main_zonmean
• main_overturn
• main_MHT
• main_trsp

read_monthly(P,nam,t)

Read record t for variable nam from file locations specified via parameters P.

The method used to read nam is selected based on nam's value. Methods include:

• read_monthly_default
• read_monthly_SSH
• read_monthly_MHT
• read_monthly_BSF

read_monthly_BSF(P, t)

Compute the barotropic streamfunction (horizontal transport streamfunction) at time t, via Helmholtz decomposition of the depth-integrated velocity transport:

1. depth-integrate UVELMASS/VVELMASS (converted to transport via MeshArrays.UVtoTransport!) to get Tx, Ty;
2. compute the land-masked horizontal convergence TrspCon;
3. solve for the scalar potential TrspPot whose gradient reproduces the divergent part of the transport (TxD, TyD);
4. subtract to isolate the rotational component (TxR, TyR = total minus divergent);
5. solve for the vector potential TrspPsi of the rotational component — this is the returned barotropic streamfunction.

Returns TrspPsi.

read_monthly_MHT(P, t)

Compute the depth-integrated horizontal heat flux components at time t, combining advective (ADVx_TH/ADVy_TH) and diffusive (DFxE_TH/ DFyE_TH) contributions, with NaNs zero-filled before summing over depth.

Returns (Tx, Ty), the raw depth-integrated flux components — not yet converted to physical heat-transport units (PW); that scaling (1e-15*4e6) is applied later, in ECCO_diagnostics.comp_MHT.

read_monthly_SSH(P, t)

Compute sea surface height at time t: ETAN + sIceLoad/1029.0, i.e. the dynamic height ETAN plus the sea-ice load's equivalent height contribution (sIceLoad, in kg/m², divided by seawater reference density 1029 kg/m³), masked by P.Γ.mskC[:,1].

read_monthly_default(P, nam, t)

Read variable nam at time record t, using file-format logic selected by P.sol. This is the default reader used by read_monthly for all variables other than "SSH", "MHT", "BSF" (which have their own dedicated readers).

P is expected to provide (see ECCO_helpers.parameters): pth_in, sol, list_steps, γ, and (for the MDS-format branch) Γ.

Three file-format branches, selected by P.sol:

1. sol in ("ECCOv4r1_analysis","ECCOv4r2_analysis","ECCOv4r3_analysis"): reads NetCDF tile files via read_nctiles_alias from joinpath(P.pth_in, nam), requires NCDatasets/MITgcm/NetCDF to be available (raises an informative error otherwise).
2. sol == "ECCOv4r4_analysis": reads a single per-year, per-month NetCDF file (nam_YYYY_MM.nc, under pth_in/nam/YYYY/), then stitches the on-disk tiled layout into a MeshArray via Tiles(γ,90,90).
3. Otherwise (MDS/MITgcm binary format): reads via read_mdsio_alias, selecting the correct .data/.meta file stem from P.list_steps[t] and a lookup table mapping nam to its containing MDS diagnostic file (state_3d_set1, trsp_3d_set1, trsp_3d_set2 for 3D variables; state_2d_set1 for 2D variables — with or without a leading STATE//TRSP/ subdirectory depending on whether pth_in/STATE exists), then applies P.Γ.mskC/P.Γ.mskC[:,1] land-masking to the result.

Which variables are treated as 3D vs. 2D is fixed by two internal name lists: 3D — THETA, SALT, UVELMASS, VVELMASS, ADVx_TH, ADVy_TH, DFxE_TH, DFyE_TH; 2D — MXLDEPTH, SIarea, sIceLoad, ETAN. Requesting a nam outside both lists in the MDS branch will error.

GridLoad_Plus()

Load the ECCO LLC90 grid and augment it with the extra fields needed by ECCO_diagnostics/ECCO_procs.

Returns (γ, Γ, LC):

• γ: the grid specification (G.XC.grid).
• Γ: the grid NamedTuple from GridLoad(ID=:LLC90, option=:light), merged with:
  • hFacC, hFacW, hFacS: cell fractional-open-volume fields at tracer, U-, and V-points, loaded via GridLoadVar;
  • mskC = hFacC./hFacC: a NaN/1 land mask derived from hFacC (NaN on land, 1 on wet cells);
  • tot_RAC: total surface area per depth level, land-masked (Σ mskC .* RAC, summed horizontally);
  • tot_VOL: total cell volume per depth level, hFacC-weighted (Σ hFacC .* RAC .* DRF, summed horizontally).
• LC: latitude circles at each integer latitude -89.0:89.0, from LatitudeCircles, used for meridional transport/overturning integrals (e.g. ECCO_diagnostics.comp_overturn, comp_MHT).

Used to build the γ, Γ, LC fields of the parameter NamedTuple returned by ECCO_helpers.parameters.

parameters(P0,params)

Prepare parameter NamedTuple for use in ECCO_diagnostics.driver.

P1=parameters(P0,p)

is faster than e.g. parameters(pth,"r2",p) as grid, etc get copied from P0 to P1.

parameters(pth0::String,sol0::String,params)

Prepare parameter NamedTuple for use in ECCO_diagnostics.driver.

For example, to compute zonal mean temperatures at level 5:

p=(calc = "zonmean", nam = "THETA", lev = 5)
pth=ECCO.standard_analysis_setup(ScratchSpaces.ECCO)
P0=ECCO_helpers.parameters(pth,"r2",p)

or, from a predefined list:

list0=ECCO_helpers.standard_list_toml("")
pth=ECCO.standard_analysis_setup(ScratchSpaces.ECCO)
P1=ECCO_helpers.parameters(pth,"r2",list0[1])

standard_list_toml(fil)

Build the standard list of ECCO diagnostics — as (calc, nam, lev) NamedTuples suitable for ECCO_helpers.parameters / ECCO_diagnostics.driver — and, if fil is non-empty, write the list to TOML at path fil.

The standard list covers (with nam/lev where applicable):

• "trsp" (transport sections), "MHT" (meridional heat transport)
• "zonmean2d" for SIarea, MXLDEPTH, SSH
• "zonmean" for THETA, SALT
• "glo2d"/"glo3d" global means for THETA, SALT
• "overturn" (meridional overturning)
• "clim" climatologies for THETA/SALT at levels [1,10,20,29,38,44], and for SSH, MXLDEPTH, SIarea, BSF (surface fields, level unused)

Returns a Vector of (calc=..., nam=..., lev=...) NamedTuples, one per entry, in the order listed above. When fil is provided, the same data is also written as a TOML dictionary with keys "calc", "nam", "kk".

Examples

list0 = ECCO_helpers.standard_list_toml("")   # in-memory only, no file written
pth = ECCO.standard_analysis_setup(ScratchSpaces.ECCO)
P1 = ECCO_helpers.parameters(pth, "r2", list0[1])

transport_lines(Γ, pth_trsp)

Compute the standard transport-section masks from transport_lines()'s lon/lat/name list, and save each section's Transect (C, W, S fields) to its own file under pth_trsp (created by this call — errors if it already exists, since it uses mkdir rather than mkpath).

Returns true on completion; the computed data is written to disk, not returned. See reload_transport_lines to read it back.

comp_MHT(P, MHT, t)

Compute the meridional heat transport at time t: sum the advective + diffusive heat flux components from ECCO_io.read_monthly_MHT over depth, integrate across each latitude circle in P.LC, and scale by 1e-15*4e6 to convert to petawatts. Stores the result in MHT[:,t].

comp_clim(P, tmp_m, tmp_s1, tmp_s2, m)

Accumulate monthly-climatology sums for calendar month m into the shared arrays tmp_m, tmp_s1, tmp_s2, by reading every time record t = m:12:nt via ECCO_io.read_monthly.

• tmp_m[:,:,m]: running climatological mean for month m (mean over years, i.e. over t = m, m+12, m+24, ...).
• tmp_s1[:,:,m], tmp_s2[:,:,m]: running sum and sum-of-squares for month m, used by main_clim after all 12 months are processed to compute the overall (all-months) mean/standard deviation.

Intended to be called once per m in 1:12, typically in parallel via @distributed (see main_clim); mutates its array arguments.

comp_glo(P, glo, t)

Compute the global (or global-per-depth-level) integral of P.nam at time t, and store it in glo[:,t].

For P.calc == "glo2d": area-weighted horizontal sum (Σ tmp .* RAC) per depth level. Otherwise ("glo3d"): volume-weighted sum (Σ tmp .* hFacC .* RAC .* DRF) per depth level. In both cases the per-level sums are further summed across grid faces (nansum(...,2)).

comp_msk0(P, msk0, zm0, l)

Precompute, for latitude band l, the horizontal mask msk0[:,:,l] (area-weighted, land-masked, NaN outside the band) and the depth-dependent normalization zm0[l,:] (inverse of the masked cell count/area per depth level), used to speed up the per-timestep zonal-mean loop in comp_zonmean/comp_zonmean2d.

Latitude band l's bounds (la0,la1) are read from joinpath(P.pth_out, P.calc*"_lats.jld2") (written by main_zonmean before this function is called). Mutates msk0/zm0 in place.

comp_overturn(P, ov, t)

Compute the meridional overturning circulation at time t: integrate volume transport (UVELMASS/VVELMASS, converted via MeshArrays.UVtoTransport!) across each latitude circle in P.LC, at each depth level, then integrate vertically from the bottom upward via a reversed cumulative sum (reverse(cumsum(reverse(...,dims=2),dims=2),dims=2)) — i.e. transport accumulates from depth toward the surface, matching the usual overturning-streamfunction convention. Stores the result in ov[:,:,t].

comp_trsp(P, trsp, t)

Compute volume transport across each standard transport section at time t: depth-integrate UVELMASS/VVELMASS (converted via MeshArrays.UVtoTransport!) through each section mask loaded via ECCO_helpers.reload_transport_lines, storing the result in trsp[:,:,t] (section × depth).

comp_zonmean(P, zm, t, msk0, zm0)
comp_zonmean(P, zm, t, msk0, zm0, idx0)

Compute the zonal (latitude-band) mean of variable P.nam at time record t, for the 3D calc == "zonmean" case, and store it in zm[:,:,t].

The four-argument method recomputes idx0 (grid indices within each latitude band, from msk0) on every call; the five-argument method takes a precomputed idx0 and should be preferred when called repeatedly (as main_zonmean does).

Reads P.nam at time t via ECCO_io.read_monthly, zero-fills NaNs, then applies zmsum! per latitude band using the precomputed masks msk0/normalization zm0 (from comp_msk0).

comp_zonmean2d(P, zm, t, msk0, zm0)

Compute the zonal (latitude-band) mean of variable P.nam at time record t, for the 2D calc == "zonmean2d" case, and store it in zm[:,t].

Unlike comp_zonmean (3D case), this reads msk0[:,:,l] back into a full-grid MeshArray via read for each latitude band l (rather than reusing precomputed point indices), since the 2D case has no depth dimension to amortize the cost over.

driver(P)

Call main computation loop as specified by parameters P.

The main computation loop choice depends on the P parameter values. Methods include:

• main_clim
• main_glo
• main_zonmean
• main_overturn
• main_MHT
• main_trsp

main_MHT(P)

Compute and save the meridional heat transport time series — the calc == "MHT" entry point for ECCO_diagnostics.driver.

Computes comp_MHT for every time step (distributed via @distributed), and saves the resulting (latitude, time) array (in PW) to joinpath(P.pth_out, P.calc*".jld2").

main_clim(P)

Compute and save a climatology for P.nam (mean, standard deviation, and per-month mean) — the calc == "clim" entry point for ECCO_diagnostics.driver.

For each calendar month m in 1:12, comp_clim accumulates the monthly mean and running sums across all years (distributed via @distributed). After the loop:

• the 12 monthly means are combined into "mon" (the full climatological monthly cycle);
• "mean" is the overall temporal mean, 1/nt * Σ tmp_s1;
• "std" is the overall temporal standard deviation, computed from tmp_s1/tmp_s2 via the standard sum-of-squares formula (sqrt(nt/(nt-1) * (E[x²] - E[x]²))), clipped at zero to avoid negative values from floating-point round-off.

If the variable is 3D, P.kk selects the depth level (used only to name the output file, via a _k%02d suffix); 2D variables have no suffix.

Saves "mean", "std", "mon" to joinpath(P.pth_out, P.nam*suffix*".jld2"). Returns true on completion.

main_glo(P)

Compute and save the global-mean (or global-mean-per-level) time series of P.nam — the calc in ("glo2d","glo3d") entry point for ECCO_diagnostics.driver.

Computes comp_glo for every time step (distributed via @distributed), then normalizes: for "glo2d", divides by Γ.tot_RAC[r] per depth level r (area-mean per level); for "glo3d", sums over levels and divides by total volume Γ.tot_VOL (single global mean per time step).

Saves the result to joinpath(P.pth_out, P.calc*".jld2").

main_overturn(P)

Compute and save the meridional overturning streamfunction — the calc == "overturn" entry point for ECCO_diagnostics.driver.

Computes comp_overturn for every time step (distributed via @distributed), and saves the resulting (latitude, depth, time) array to joinpath(P.pth_out, P.calc*".jld2").

main_trsp(P)

Compute and save volume transport time series across all standard transport sections — the calc == "trsp" entry point for ECCO_diagnostics.driver.

Computes comp_trsp for every time step (distributed via @distributed), then packages the result as a vector of (nam=<section file name>, val=<depth × time array>) NamedTuples (one per section), saved to joinpath(P.pth_out, P.calc*".jld2").

main_zonmean(P)

Compute and save the zonal (latitude-band) mean of variable P.nam — the calc in ("zonmean","zonmean2d") entry point for ECCO_diagnostics.driver.

Latitude bands are fixed at 2°-wide bins spanning -90:90 (P.calc*"_lats.jld2"). Proceeds in two phases:

1. Setup (parallel over latitude bands l, via comp_msk0): precompute and cache to disk the per-band horizontal mask msk0 and depth-dependent normalization zm0, since these don't depend on time and are expensive to redo every time step.
2. Main loop (parallel over time t): using the cached msk0/zm0 (reloaded from disk) and precomputed point indices idx0, compute the per-time-step zonal mean via comp_zonmean (if calc == "zonmean", 3D) or comp_zonmean2d (if calc == "zonmean2d", 2D).

Saves the final zm array to joinpath(P.pth_out, P.calc*".jld2"). Returns true on completion.

zmsum!(tmp1, tmp, msk, idx)

In-place helper: sum tmp[idx[i],j] * msk[idx[i]] over i (grid points within a latitude band) into tmp1[j] for each depth/level index j.

idx is expected to be a vector of point indices already known to lie within the target latitude band (see comp_zonmean, which precomputes idx0 once and reuses it across all time steps). Used as the performance-critical inner loop of comp_zonmean.

ECCO_procs.DepthTime(X::ECCOdiag)

Compute the time-versus-depth data for X (X.options.plot_type == :ECCO_DepthTime; X.name's prefix should be "THETA" or "SALT"), at a single fixed latitude band, subtracting the 1992–2011 monthly-mean seasonal cycle, and return a plain NamedTuple ready for the Makie extension's DepthTime to render.

X.options.level selects the latitude band index (2° bins over -90:90 — despite the name, this indexes latitude, not depth; the depth axis y spans the full vertical grid P.Γ.RC). X.options.factor scales the fixed contour levels (THETA: (-3.0:0.4:3.0)/8; SALT: (-0.5:0.1:0.5)/10). X.options.klims = (k0,k1) sets the plotted depth range via ylims = (Γ.RC[k1], Γ.RC[k0]) (reversed so depth increases downward).

Reference removal is always the 1992–2011 monthly mean (analogous to TimeLat's select_method == 1; DepthTime has no select_method option — the seasonal-mean subtraction is unconditional).

Returns (x, y, z, levels, title, ylims, year0, year1, years_to_display), with x in decimal years, y in depth (m), z oriented depth × time. years_to_display = year_range(X.options).

ECCO_procs.ECCO_map(X::ECCOdiag)

Compute the map data for X (X.options.plot_type == :ECCO_map), returning a plain NamedTuple ready for the Makie extension's ECCO_map to render.

X.name is matched against X.options.P.clim_longname (see ECCO_procs.parameters) to find the corresponding climatology file; X.options.statistic selects which field to show ("mean", "std", or "mon" for a specific month, indexed by X.options.time). The field is interpolated onto the regular lon/lat grid X.options.P.λ via Interpolate, land-masked by X.options.P.μ. Color levels are drawn from X.options.P.clim_colors1 (for "mean"/"mon") or clim_colors2 (for "std").

Returns (λ, field, levels, title).

ECCO_procs.TimeLat(X::ECCOdiag)

Compute the time-versus-latitude (Hovmöller) data for X (X.options.plot_type in (:ECCO_TimeLat, :ECCO_TimeLatAnom)), optionally removing a reference climatology/trend, and return a plain NamedTuple ready for the Makie extension's TimeLat to render.

X.name's prefix (before the first "_") selects the variable, its source zonal-mean file, and default color levels/orientation:

X.options.select_method controls reference removal:

• 0: no reference removed (raw field).
• 1: subtract the 1992–2011 monthly mean (separately for each calendar month, removing the seasonal cycle's inter-annual level).
• 2: subtract the 1992–2011 annual mean (single number per latitude, seasonal cycle retained).
• 3: subtract a fitted seasonal cycle (order-3) with no polynomial trend, via fit_time_series, fit over X.options.period.
• 4: subtract a fitted seasonal cycle and a linear trend (order-3 season, order-1 polynomial), via fit_time_series.

X.options.level selects the depth index for 3D variables (THETA, SALT); ignored for 2D variables. X.options.colormap_factor scales the chosen contour levels.

Returns (x, y, z, levels, title, ylims, year0, year1, years_to_display), where x is time (decimal years), y is latitude (2° bins over -90:90), and z is the (possibly reference-subtracted) field, oriented time × latitude. years_to_display = year_range(X.options).

ECCO_procs.glo(X::ECCOdiag)

Compute the global-mean time series data for X (X.name should be "THETA" or "SALT"; X.options.plot_type == :ECCO_GlobalMean), returning a plain NamedTuple ready for the Makie extension's glo to render.

X.options.level selects between the depth-integrated global mean (level == 0, loads X.name*"_glo3d") and a single depth level's global mean (level > 0, loads X.name*"_glo2d", reshapes to (nt,50), and selects column level).

Default y-axis ranges (rng) are fixed, narrow bands appropriate for long-term global-mean drift (e.g. [3.5,3.65] °C for global-mean THETA, [18.0,19.0] °C for level-1 THETA) — except for level > 1, where rng is instead set to the data's own extrema, since the fixed default ranges are calibrated for the surface/whole-ocean cases only.

Returns (y, txt, rng, x, year0, year1, years_to_display), where x is in decimal years starting from X.options.period[1], and years_to_display = year_range(X.options).

ECCO_procs.parameters()

Assemble the shared NamedTuple of grid, masking, interpolation, and metadata needed by the ECCO_procs plot-data functions (glo, TimeLat, DepthTime, ECCO_map) — i.e. the P field expected in their options (X.options.P).

Loads the full LLC90 grid (GridSpec/GridLoad(...;option="full")), a land mask (land_mask), and interpolation weights for mapping (interpolation_setup). Also derives, from the "OCCA2HR1" ECCO diagnostics output (ECCOdiags_add("OCCA2HR1")):

• list_trsp: names of the standard transport sections (from the "trsp" diagnostic file, section-name suffix stripped);
• clim_colors1/clim_colors2: mean/std-dev color scale ranges per variable, read from examples/ECCO/clim_colors{1,2}.toml; clim_files, clim_name, clim_longname: the list of available climatology output files, their short names, and human-readable long names (via longname).

Returns a NamedTuple with fields γ, Γ, λ, μ, list_trsp, clim_colors1, clim_colors2, clim_files, clim_name, clim_longname.

DepthTime(XYZ; ClipToRange=true)

Render a time-versus-depth filled-contour diagram from XYZ.

XYZ is the NamedTuple returned by ECCO_procs.DepthTime — not an ECCOdiag directly (see plot) — with fields x (time), y (depth), z (depth × time field), levels, title, ylims (a (depth0,depth1) tuple, typically given reversed so depth increases downward on screen), and years_to_display (x-axis limits — see year_range).

When ClipToRange is true (default), XYZ.z is clipped in place to XYZ.levels's range via to_range! before contouring.

ECCO_map(X; ClipToRange=true)

Render a filled-contour map of X.field over the longitude/latitude grid X.λ.

X is the NamedTuple returned by ECCO_procs.ECCO_map — not an ECCOdiag directly (see plot for how the two connect) — with fields λ (interpolation target, providing lon/lat), field, levels, and title.

When ClipToRange is true (default), values in X.field outside the range of X.levels are clipped in place via to_range! before contouring, avoiding blank contour gaps for out-of-range data.

OHT(X::ECCOdiag)

Plot the time-averaged northward ocean heat transport (in PW) versus latitude.

Unlike ECCO_map/TimeLat/DepthTime/glo, OHT takes X (X.options.plot_type == :ECCO_OHT1, X.name == "OHT") directly rather than a precomputed NamedTuple: it loads "MHT" data from X.path and computes the plotted time average inline.

The averaging window is (Y0,Y1) = year_range(X.options), converted to month indices relative to X.options.period's start year:

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

For this plot type, years_to_display/year_range selects which months get averaged, not a plotted x-axis range — the x-axis here is latitude, not time.

OverturnStreamfunction(X::ECCOdiag; ClipToRange=true)

Plot the time-averaged meridional overturning streamfunction (in Sv) as a filled contour over latitude and depth.

Like OHT, and unlike the ECCO_procs-mediated plot types, OverturnStreamfunction takes X directly (X.options.plot_type == :ECCO_Overturn2, X.name == "overturn"), loading X.name data from X.path and computing the time average inline over month indices i0:i1 derived from year_range(X.options) relative to X.options.period (see OHT for the exact index formula, and year_range for why this plot type's years_to_display selects an averaging window rather than an axis range).

X.options.grid supplies the vertical grid (Γ.RF) used for the depth axis.

When ClipToRange is true (default), the time-averaged field is clipped to the fixed contour levels -40:5:40 Sv via to_range! before contouring.

OverturnTimeseries(X::ECCOdiag)

Plot 12-month running-mean overturning transport (in Sv) time series at a fixed depth level, for a fixed set of latitudes.

X.options.plot_type == :ECCO_Overturn1, X.name == "overturn". Loads X.name data from X.path, then plots one line per latitude index in 115:10:145 against lats = -89.0:89.0 — i.e. 25°N, 35°N, 45°N, 55°N (this index range must be kept in sync with lats if either is changed). X.options.level selects the depth index (shown as kk in the title); X.options.low1 overrides the y-axis lower bound ("auto" uses the fixed (5,20) Sv range).

The x-axis is set to years_to_display = year_range(X.options), which for this plot type is a genuine axis range (contrast with OHT and OverturnStreamfunction, where the same accessor instead selects a time-averaging window).

TimeLat(XYZ; ClipToRange=true)

Render a time-versus-latitude filled-contour (Hovmöller) diagram from XYZ.

XYZ is the NamedTuple returned by ECCO_procs.TimeLat — not an ECCOdiag directly (see plot) — with fields x (time), y (latitude), z (time × latitude field), levels, title, ylims (a (lat0,lat1) tuple), and years_to_display (an (x0,x1) tuple used for the x-axis limits — see year_range).

When ClipToRange is true (default), XYZ.z is clipped in place to XYZ.levels's range via to_range! before contouring.

glo(gl1)

Render a global-mean time series line plot from gl1.

gl1 is the NamedTuple returned by ECCO_procs.glo — not an ECCOdiag directly (see plot) — with fields x (time), y (global-mean value), txt (used as both title and y-axis label), rng (y-axis limits), year0/year1 (x-tick spacing), and years_to_display (x-axis limits).

time_average_indices(o::NamedTuple, nt::Int)

Compute the clamped (i0,i1) month-index range to average over, given options o (using o.period and year_range) and the actual number of time records nt available in the loaded data.

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

i0 and i1 are clamped to 1:nt (rather than left to error via BoundsError) so that a years_to_display/period window extending past the end (or before the start) of the loaded record silently truncates to the available data instead of failing. A warning is emitted via @warn when clamping actually occurs, to surface a likely mismatched-window mistake without hard-failing the plot.

to_range!(DD, levs)
to_range!(DD, levs::Tuple)

Clip array DD in place so that all values fall strictly within the range spanned by contour levels levs, avoiding blank/uncontoured regions where DD lies exactly at or beyond levs's extremes.

Values <= levs[1] are set to levs[1] + (levs[2]-levs[1])/100; values >= levs[end] are set to levs[end] - (levs[end]-levs[end-1])/100 — i.e. nudged just inside the boundary rather than removed or NaN-filled.

The Tuple method accepts a plain (lo,hi) range (as used for, e.g., ECCO_map's figov2 fixed -40:5:40 levels) and expands it to 10 evenly-spaced levels via range(levs[1],levs[2],length=10) before delegating to the vector method.

Used by ECCO_map, TimeLat, DepthTime, figov2 (ECCO), and SST_plots.TimeLat (SST) prior to contourf!.

transport(X::ECCOdiag)

Plot 12-month running-mean volume transport (in Sv) time series, one panel per named section in X.options.namtrs.

Reads from X.options: namtrs (section names to plot, matched against list_trsp), ncols (panels per row), list_trsp (full list of section names as stored in the "trsp" data file), and period (a (year0,year1) tuple used for tick spacing). The plotted x-axis range is years_to_display = year_range(X.options).

Each panel is rendered by the internal helper axtr1, which loads and converts the corresponding section's transport from X.path.

plot(x::ECCOdiag)

Render the Makie figure appropriate for x.options.plot_type.

Dispatches on x.options.plot_type (a Symbol, see default_options), combined for a few plot types with x.name:

For the first five rows, x (an ECCOdiag) is first passed through the same-named function in ECCO_procs to compute a plain NamedTuple of plot data, which is then rendered by the like-named method in this extension — i.e. ECCO_map/TimeLat/DepthTime/glo each name two functions (one data-producing, in ECCO_procs; one figure-producing, here). The remaining plot types (OHT, OverturnTimeseries, OverturnStreamfunction, transport) instead read and process data directly from x.path/x.name, without a separate ECCO_procs precompute step.

Prints "unknown option (a)" if x.options is empty, or "unknown option (b)" if plot_type/name match none of the cases above, rather than throwing an error.

plot(x::SSTdiag)

Render the Makie figure appropriate for x.options.plot_type.

Dispatches on string(x.options.plot_type) to a method in SST_plots:

Throws an ErrorException if x.options is empty, or if plot_type matches none of the cases above.

plot(x::SurfaceFluxDiag)

Render the Makie figure appropriate for x.options.plot_type, given x.data.

Throws an ErrorException if x.options is empty, or if plot_type matches none of the cases above.

Examples

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