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.11 (regularly tested on 3.11 and 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).
• 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

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:

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

Initialize a project

CryoSwath expects project data outside the package install directory. Run cryoswath-init inside a new project folder:

mkdir <proj_dir>
cd <proj_dir>
cryoswath-init

cryoswath-init sets up the expected data structure and writes scripts/config.ini with your base data path. The paths can be reconfigured in config.ini if you use a different layout.

To avoid storing secrets in config.ini, use keyring (preferred) or environment variables for ESA credentials and keep config.ini focused on paths. 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: scripts/tutorial__general_step-by-step.ipynb
• First waveform tutorial: scripts/tutorial__process_first_waveform.ipynb
• First swath tutorial: scripts/tutorial__process_first_swath.ipynb

Local testing

Run the full local test pipeline:

pixi run -e test test-all

Run report notebooks only:

pixi run -e test test-notebooks

Run tutorial notebooks only:

pixi run -e test test-tutorial-notebooks

If tutorials are stored outside the current checkout, set CRYOSWATH_TUTORIAL_DIR to the directory containing tutorial__*.ipynb before running this task.

Notebook tests may download required larger data from first-hand sources at runtime, so network availability and valid ESA credentials matter.

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: v0.2.5},
  month        = feb,
  year         = 2026,
  publisher    = {Zenodo},
  version      = {v0.2.5},
  doi          = {10.5281/zenodo.17011635}
}

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.