This is the first in a series of hands-on tutorials for the swot package, which processes SWOT Level-2 Low-Rate Sea Surface Height (L2 LR SSH) data end to end: download, pass finding, subsetting, regridding, and plotting.

The tutorials assume you work on the lab server with the /spray archive mounted — the data is already downloaded and the Python environment is already installed, so you can start analysing immediately.

What you'll learn

  • How to activate the lab Python environment and verify the tools work.
  • How SWOT data is organised on /spray.
  • The SWOT concepts (cycles, passes, swaths) the other tutorials rely on — including the cycle-numbering gotcha that trips everyone up once.
  • The command-line tools you'll use in the rest of the series.

1. Set up your shell

Log in to the lab server, then add this line to your ~/.bashrc (or ~/.zshrc) so every new shell has the environment:

source /opt/miniforge3/bin/activate

Open a new shell (or source ~/.bashrc) and verify the ODSL commands are on your PATH:

odsl-swot-download --help     # any odsl-swot-* command works as a check

If that prints a usage message, you are ready.

Working elsewhere? If you are not on the lab server, install the package first (python -m pip install -e ".[all]" from a clone of odsl_code), pass --data-root / --base-folder to point at your own data directory, and see tutorial 2 for downloading data and setting up NASA Earthdata credentials.

2. Where the data lives

All SWOT L2 LR SSH data sits under /spray/swot/versionD, one folder per cycle:

ls /spray/swot/versionD | head

cycle_001
cycle_002
cycle_003
...

Inside a cycle folder, each file is one pass of one product:

SWOT_L2_LR_SSH_Expert_020_013_20240605T054938_20240605T064105_PGC0_01.nc
                      ^^^ ^^^
                    cycle pass

Two L2 LR SSH product types matter for these tutorials:

Product What it is
Expert The workhorse: 2 km smoothed KaRIn SSH anomaly (ssha_karin_2) with quality flags and correction fields. Default everywhere.
Unsmoothed Native-resolution swath, stored in separate left/right NetCDF groups.

This data root is the built-in default for every script, so on the lab server you rarely need to pass a path at all. Regridded output defaults to /spray/swot/regridded, and per-cycle download manifests live in the repo's database/ folder.

3. SWOT in three minutes

  • SWOT's KaRIn instrument measures sea-surface height over a wide swath (two ~50 km strips either side of the track), unlike conventional nadir altimeters that measure a single line.
  • A pass is a half-orbit, pole to pole (odd = ascending, even = descending). A cycle is one complete repeat of the orbit, after which the satellite retraces exactly the same ground tracks.
  • Because the orbit repeats, a pass number always maps to the same ground footprint — pass 13 of cycle 20 covers the same strip of ocean as pass 13 of cycle 30. That is what makes per-pass time series (tutorial 4) and precomputed pass footprints (tutorial 3) possible.

The cycle-numbering gotcha

SWOT flew two different orbits and restarted cycle numbering between them, so cycle number is not monotonic in time:

Phase When Cycle numbers Repeat Passes/cycle
Cal/val early 2023 high (~474–577) 1 day 28
Science mid-2023 → ongoing from 1 (≈50 by 2026) 21 days 584

Rule of thumb: low cycle numbers are the ongoing science data; cycle numbers in the ~474–577 range are the early 1-day cal/val orbit with completely different geometry. Keep this in mind whenever you loop over cycles.

4. Conventions used throughout

  • Bounding boxes are always west south east north, in degrees. Both longitude conventions ([-180, 180) and [0, 360)) are accepted and normalised internally. The tutorials use a Gulf of America box:

text --bbox -98 18 -80 31

  • Everything is idempotent. Downloaders skip files that already exist; subset/regrid scripts refuse to clobber an existing output unless you pass --overwrite. Re-running a command is always safe.
  • Write your outputs to your own directories (home, scratch, tmp/) — the /spray roots are the shared lab archive.

5. The command-line tools

Every workflow is a console command (installed with the package). The tutorials cover them in this order:

Command Purpose Tutorial
odsl-swot-download Query NASA CMR and download per-cycle granules 2
odsl-swot-granule-link Print the download link for one cycle+pass 2
odsl-swot-footprints Build the pass-footprint index (one-time) 3
odsl-swot-swath-map Scatter-map raw swath pixels over a region 3
odsl-swot-subset Stack one pass across cycles into a NetCDF cube 4
odsl-swot-plot-cube Multi-panel plot of a subset cube 4
odsl-swot-regrid Regrid swaths onto a regular lat/lon or Cartesian grid 5
odsl-swot-regrid-1km Unsmoothed → 1 km swath-aligned OI 8
odsl-swot-swath Unified dispatcher (see below) all

odsl-swot-swath is a single entry point that forwards to the same tools, so these are equivalent:

odsl-swot-subset        --cycle-start 20 --cycle-end 30 --pass 13 --lat-range 18 31
odsl-swot-swath subset  --cycle-start 20 --cycle-end 30 --pass 13 --lat-range 18 31

Its subcommands are subset (with --product expert|unsmoothed), regrid, plot, pixc-download, and pixc-plot; odsl-swot-swath <cmd> --help shows the underlying tool's options. The PIXC subcommands handle a different product entirely — the high-resolution pixel cloud — covered in tutorial 6.

Next: Tutorial 2 — Downloading data, or skip ahead to Tutorial 3 — Finding passes over your region if the data you need is already on /spray.