Most tools in ODSL work one instrument at a time. The super-subsetter is the cross-cutting exception: give it a bounding box and a time window and it harvests eleven /spray archives at once — SWOT, RADS, AVISO L4, Argo, drifters, gliders, ICESat-2, in-situ wind, PACE ocean colour, SNPP SST, and GOES ABI SST — into one HDF5 file, each source kept in its native structure. It is the fastest way to pull "everything we have over this region, in this window" into a single portable file you can hand to a colleague or load in one line of xarray.

What you'll learn

  • Running your first subset and reading the grouped HDF5 back.
  • Choosing which of the eleven sources to include.
  • Selecting exactly which variables each source contributes.
  • What corrections and quality masks are applied on the way in.
  • Anchoring the time window to a single SWOT granule.
  • Reading the auto-generated data summary.

Prerequisites: access to the lab server where /spray is mounted (see Getting started), and an editable install so the console script is on your PATH:

python -m pip install -e "."      # registers odsl-super-subsetter

Everything below writes to your own space — point --out at a path you own, not into the source tree.

1. Your first subset

Pull AVISO L4 maps and RADS nadir passes over the Gulf of America for a few days:

odsl-super-subsetter \
    --start 2023-04-08 --end 2023-04-10 \
    --bbox -92 25 -88 28 \
    --sources aviso rads \
    --out ~/subsets/gom_apr2023.h5

--bbox is west south east north in degrees; longitudes may be given as -180..180 or 0..360 and are preserved as -180..180 on output when you enter them that way. The default sources are swot rads aviso; here we asked for just two. When a source has no data in the window it is logged and skipped — never fatal — so a partial archive never breaks the run.

The tool writes two files: the HDF5, and a Markdown data summary beside it (gom_apr2023.summary.md) — see section 7.

2. Choosing sources

--sources takes any subset of the eleven archives, or all:

Source Group path Native structure kept
swot /swot/cycle###_pass### 2-D swath (num_lines × num_pixels), clipped along-track only
rads /rads/<mission>_c###_p#### along-track profile (obs)
aviso /aviso_l4 gridded L4 map (time × latitude × longitude)
argo /argo/<dac>_<wmo> profile stack (N_PROF × N_LEVELS)
drifter /drifter/<id> trajectory (obs)
glider /glider/<deployment> trajectory (row)
icesat2 /icesat2/<granule> along-track segments, all beams stacked (obs)
wind /wind/<family>_<station> station time series (obs)
pace /pace/<granule> 2-D swath (number_of_lines × pixels_per_line)
snpp /snpp/viirs_<stamp> 2-D L2P swath (nj × ni)
geos /geos/goes_<stamp> 2-D GOES ABI L2P swath (nj × ni)

Swath sources (SWOT, PACE, SNPP, GOES) keep their full cross-track width; only the along-track extent is clipped to the bbox, so a slab may spill a little past the box on purpose — that preserves the original geometry. Everything else is clipped to the box along its natural observation axis.

Broad-phase search reuses the shared footprint indices (odsl-colocate-refresh), so it is fast even over large archives.

3. Reading the output

The file is netCDF4 with nested groups — readable by both xarray (one group at a time) and h5py (the whole tree):

import h5py, xarray as xr

# List every group that was written
with h5py.File("~/subsets/gom_apr2023.h5", "r") as f:
    f.visit(print)

# Load one source's group
aviso = xr.open_dataset("~/subsets/gom_apr2023.h5", group="aviso_l4")
print(aviso)                       # dims: time, latitude, longitude

rads = xr.open_dataset("~/subsets/gom_apr2023.h5", group="rads/j3_c123_p0045")
print(rads.ssha.values)

Each group carries its own coordinates, time, and provenance attributes (source file, cycle/pass, and — for SWOT — which corrections were applied).

4. Picking variables

By default each source contributes its essentials with uncertainties — the core geophysical value plus its quality flags and error estimates (e.g. SWOT ssha_karin + ssha_karin_2 with _qual flags and ssh_karin_uncert; Argo PRES/TEMP/PSAL with _ADJUSTED/_ADJUSTED_ERROR/_QC; SNPP SST with sses_bias/sses_standard_deviation). Coordinates, time, and positions are always kept.

To take full control, generate an editable Markdown template, flip the +/- markers, and feed it back:

# 1. inspect one sample file per product and write the +/- template
odsl-super-subsetter --init-vars-config subset_variables.md

# 2. edit subset_variables.md — '+ name' keeps a variable, '- name' drops it

# 3. run with your edited config
odsl-super-subsetter --vars-config subset_variables.md \
    --start 2023-04-08 --end 2023-04-10 --bbox -92 25 -88 28 \
    --sources aviso rads --out ~/subsets/gom_custom.h5

For a quick one-off you can skip the config and name variables inline per product; these override both the config and the essentials:

odsl-super-subsetter ... --rads-vars ssha swh_ku flags

Precedence is inline --<product>-vars > --vars-config > essentials.

5. Corrections and quality

SWOT SSHA is stored corrected. Both ssha_karin and ssha_karin_2 have the crossover calibration (height_cor_xover) and the internal-tide model (internal_tide_hret) added back in; each group's attributes record exactly what was applied. Turn them off individually if you want the raw field:

odsl-super-subsetter ... --no-swot-xover --no-swot-internal-tide

Quality knobs worth knowing:

  • --swot-ssha-qual-max (default 2) — SWOT flagging is aggressive; the default admits slightly-degraded pixels rather than only qual == 0, which keeps valuable coastal data. Judge the result with ssh_karin_uncert.
  • --allow-land — by default only ocean points (negative topography) are kept; pass this to keep everything.
  • --max-sea-ice-conc — optional cap on RADS sea-ice concentration.

6. Anchoring the window to a SWOT granule

Instead of --start/--end, you can center the window on one SWOT Expert granule — handy when you want "everything within ±2 days of this SWOT pass":

odsl-super-subsetter \
    --swot-file SWOT_L2_LR_SSH_Expert_010_317_20240115T....nc \
    --delta-t-days 2 \
    --bbox -92 25 -88 28 --sources all \
    --out ~/subsets/around_010_317.h5

7. The data summary

Every run writes <out>.summary.md next to the HDF5 (disable with --no-summary, relocate with --summary PATH). It records the run parameters and, per group, the shape, time span, lon/lat coverage, and NaN-safe statistics of a representative variable — a quick way to see what actually landed in the file without opening it.

Useful extras: --rads-missions j2 j3 3a, --icesat2-products ATL07 ATL10, --pace-products bgc iop, per-source roots (--drifter-root, --snpp-root, …), and --max-files N to cap each source at N produced groups while you iterate.

Troubleshooting

  • A source produced no groups. The archives don't all overlap in time. AVISO L4 on disk covers roughly late March–April 2023; SWOT science data begins 2023-07-26 (early-2023 dates fall in the cal/val phase with different pass geometry); SNPP is May–Jul 2023; PACE begins 2024. Check your window against the archive before assuming a bug.
  • PACE returns nothing in a window it should cover. The footprint index can lag; the tool falls back to a date-tree scan, but pass --pace-footprints to a fresh parquet if you have one.
  • Wind stations are skipped with a warning. NDBC rows carry no lat/lon, so they can't be bbox-clipped and are dropped by design.
  • ImportError / old command not found. A stale non-editable copy in site-packages can shadow the source tree; re-run pip install -e ".". (The command is odsl-super-subsetter; the old odsl-multi-altimeter-subset name was retired.)

See also: the super_subsetter package reference for the module layout, and common/DATA_PATHS.md for the per-dataset /spray layout (globs, variable names, longitude conventions, coverage).