SMOS

Download, readers and time series conversion for SMOS (Soil Moisture and Ocean Salinity) soil moisture data. Works great in combination with pytesmo.

The full documentation is available at smos.readthedocs.io. To cite this package, follow the Zenodo (DOI) badge above and export the citation there.

Supported products

Installation

All dependencies are available via pip (Python >= 3.11):

pip install smos

The download programs use lftp, which must be installed on your system (e.g. apt-get install lftp). The package can also be installed into an existing conda environment, e.g. if you prefer installing compiled dependencies such as netCDF4 or pyresample from conda-forge first.

Quickstart

All command line programs are available via smos <product> <command>, see smos --help and e.g. smos l3 download --help. As an example, download 10 days of SMOS L3 daily soil moisture (ascending overpasses):

smos l3 download ./smos_l3 --product CLF3S --orbits ASC -s 2024-01-01 -e 2024-01-10

and convert the images over Europe into time series (5x5 degree cell files):

smos l3 reshuffle ./smos_l3/MIR_CLF3SA ./smos_l3_ts --parameters Soil_Moisture,Mean_Acq_Time_Days,Mean_Acq_Time_Seconds --bbox -11 34 43 71

Read an image and a time series in python:

from datetime import datetime
from smos.smos_l3.interface_l3 import SMOS_L3_Ds, SMOSL3Ts

ds = SMOS_L3_Ds('./smos_l3/MIR_CLF3SA', parameters='Soil_Moisture')
image = ds.read(datetime(2024, 1, 5))
sm = image.data['Soil_Moisture']  # global 2D array (584 x 1388)

ts = SMOSL3Ts('./smos_l3_ts', index_add_time=True).read(16.37, 48.21)  # lon, lat
print(ts['Soil_Moisture'])

To keep the data up to date, download all images that are new since the last downloaded day (until today) and append them to the time series with

smos l3 update_img ./smos_l3 --product CLF3S --orbits ASC
smos l3 update_ts ./smos_l3/MIR_CLF3SA ./smos_l3_ts

The other products work the same way, see the documentation for details.

Docker image

For each release, a Docker image with the package and lftp is published to the GitHub container registry:

docker run --rm -v /path/to/data:/data ghcr.io/tuw-geo/smos:latest smos l3 update_img /data/smos_l3

The container runs as a non-root user (uid 1000), pass e.g. --user $(id -u):$(id -g) to access mounted data as your own user. To build the image locally from the checked out version, run docker build -t smos ..

Development

Clone the repository including the test data submodule (requires git lfs) and install the package in editable mode with the test dependencies:

git clone --recurse-submodules git@github.com:TUW-GEO/smos.git
cd smos
pip install -e ".[testing]"
pytest

Contribute

We are happy if you want to contribute. Please raise an issue explaining what is missing or if you find a bug. We will also gladly accept pull requests against our master branch for new features or bug fixes:

• Fork the smos repository and create a feature branch from master.
• Add your feature or fix, including tests (we use pytest) and documentation (numpy style docstrings, docs pages, CHANGELOG.rst).
• Format your code with yapf (settings in pyproject.toml).
• Submit a pull request to our master branch.

See AGENTS.md for more detailed development guidelines.