CryoSwath

CryoSwath is a Python package for processing CryoSat-2 SARIn data, from waveform-level processing to gridded elevation products.

What CryoSwath provides

• Discovery of CryoSat-2 tracks over a region of interest
• L1b download and preprocessing
• Swath and POCA elevation retrieval
• Aggregation to regular spatial/temporal grids
• Gap filling and trend estimation workflows

Important notes

• Install CryoSwath in a dedicated environment (pixi, conda/mamba, venv, or uv). The dependency tree is broad, and future dependency conflicts are otherwise likely.
• Supported Python version: >=3.12.
• Downloading CryoSat SARIn L1B resources requires an ESA EO account. MAAP assets use a personal MAAP offline token; Science Server FTP fallback uses ESA username/password credentials.
• Automatic RGI downloads from NSIDC require NASA Earthdata credentials; see the prerequisites docs for setup details.
• CryoSat SARIn L1b track discovery uses MAAP anonymously. When MAAP cannot provide a usable asset, downloads fall back to the authenticated CryoSat Science Server FTP service.
• Anonymous FTP login does not grant access to CryoSat product directories.
• Install xarray and zarr together to avoid version mismatches.

Installation

For full setup details, see the docs: cryoswath.readthedocs.io

For development setup and contribution checks, see CONTRIBUTING.md.

Option 1: reproducible setup with pixi (recommended)

git clone https://github.com/j-haacker/cryoswath.git
cd cryoswath
pixi install --locked -e test
pixi run -e test test-unit

For an interactive shell in the project environment:

pixi shell -e test

Option 2: install from conda-forge

mamba create -n cryoswath conda-forge::cryoswath
mamba activate cryoswath

Option 3: editable install from source

git clone https://github.com/j-haacker/cryoswath.git
mamba env create -n cryoswath -f cryoswath/environment.yml
mamba activate cryoswath
mamba install pip
pip install --editable cryoswath

Option 4: reproducible Pixi environment

git clone https://github.com/j-haacker/cryoswath.git
cd cryoswath
pixi install --locked -e test
pixi shell -e test

This uses the lock file and is the most robust option when dependency resolvers disagree.

Contributor lockfile workflow

For regular development runs:

pixi install --locked -e test

If you change dependency manifests (pyproject.toml and/or pixi.toml):

pixi lock
pixi run -e test test-unit
pixi run -e docs docs-build

Optional: Docker image

If local dependency resolution fails, you can use Docker. The image provides the CryoSwath runtime and the base JupyterLab kernel:

docker run -it -p 8888:8888 -v <proj_dir>:/home/jovyan/project_dir cryoswath/jupyterlab:nightly

Find setup instruction in the prerequisite documentation.

Configure a project

CryoSwath keeps project data outside the package install directory. If no configuration file is present, paths default to ./data relative to the current working directory. For a reusable project configuration, run the bootstrap commands inside a project folder:

mkdir <proj_dir>
cd <proj_dir>
cryoswath create-config
cryoswath download-aux-data
cryoswath get-tutorials

cryoswath create-config writes cryoswath.cfg with your base data path. cryoswath download-aux-data installs the Zenodo auxiliary-data baseline. cryoswath get-tutorials copies packaged tutorial notebooks to tutorials/. The tutorial notebooks assume CryoSwath is installed in the active Python environment and import it directly. You can also set CRYOSWATH_DATA or more specific CRYOSWATH_* path variables; environment variables override config files. Set CRYOSWATH_CONFIG to select a config file explicitly. Legacy config.ini files are still read.

MAAP downloads require a personal ESA MAAP offline token associated with an ESA EO Sign-In account. Store it in keyring with cryoswath update-maap-token, or set ESA_MAAP_OFFLINE_TOKEN for automation. The token is different from an ESA username/password and should not be stored in cryoswath.cfg or .netrc. The authenticated Science Server FTP fallback uses existing ESA username/password credentials. Generate a 90-day token through the ESA MAAP portal.

Tutorials and documentation

• Main docs: cryoswath.readthedocs.io
• General workflow tutorial: tutorials/tutorial__general_step-by-step.ipynb
• First waveform tutorial: tutorials/tutorial__process_first_waveform.ipynb
• First swath tutorial: tutorials/tutorial__process_first_swath.ipynb

External dependencies and data

CryoSwath relies on:

• Python dependencies: requirements.txt
• reference elevation models
• RGI glacier outlines

The package points to required external resources during setup and use.

Known limitations

• ESA's data server is not reachable from all internet service providers.
• Projected RGI basin geometries can sometimes be invalid; use .make_valid() where required.
• Most testing and validation has focused on the Arctic.

Further details: open issues

Citation and attribution

If you use CryoSwath, please cite:

@software{cryoswath,
  author       = {Haacker, Jan},
  title        = {CryoSwath 0.2.8},
  month        = oct,
  year         = 2026,
  publisher    = {Zenodo},
  version      = {0.2.8},
  doi          = {10.5281/zenodo.14825358} % replace concept DOI on release
}

Please also acknowledge upstream data/resources used in your workflow:

• ESA L1b data terms: Terms and Conditions for the use of ESA Data
• RGI data license: CC-BY-4.0
• PGC DEM acknowledgement guidance: Acknowledgement Policy

License

MIT. See LICENSE.txt.