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 resources requires an ESA EO account.
• ESA credentials are resolved in this order: EOIAM_USER/EOIAM_PASSWORD, then keyring (preferred for interactive setup), then ~/.netrc (plaintext fallback), then legacy config.ini [user] name/password (temporary fallback).
• Automatic RGI downloads from NSIDC require NASA Earthdata credentials; see the prerequisites docs for setup details.
• L1b file downloads are HTTPS-first. FTP remains a fallback path and is still used for metadata refresh flows (catalog/track updates).
• Anonymous FTP login is no longer supported.
• Install xarray and zarr together to avoid version mismatches.

Dependency policy

• Flexible package bounds (for pip/uv users): xarray>=2025.3,<2025.12.
• Stable environment (recommended for reproducible runs): use the checked-in lock/environment files (pixi.lock, environment.yml).
• Compatibility window in this repository was last audited on February 14, 2026.

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.

To avoid storing secrets in config files, use keyring (preferred) or environment variables for ESA credentials. You can configure keyring credentials interactively with: cryoswath update-keyring. If you need a fallback, you can write ~/.netrc (this stores the password in plaintext) using cryoswath update-netrc.

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.6},
  month        = feb,
  year         = 2026,
  publisher    = {Zenodo},
  version      = {0.2.6},
  doi          = {10.5281/zenodo.20257262}
}

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.