PySAMOSA
A Python-based software for processing open ocean and coastal waveforms from SAR satellite altimetry to measure sea surface heights, wave heights, and wind speed for the oceans and inland waters.
https://github.com/floschl/pysamosa
Category: Hydrosphere
Sub Category: Coastal and Reefs
Last synced: about 6 hours ago
JSON representation
Repository metadata
PySAMOSA is a software framework for processing open ocean and coastal waveforms from SAR satellite altimetry to measure sea surface heights, wave heights and wind speed for the oceans and inland water bodies. Satellite altimetry is a space-borne remote sensing technique used for Earth observation.
- Host: GitHub
- URL: https://github.com/floschl/pysamosa
- Owner: floschl
- License: lgpl-3.0
- Created: 2023-05-27T04:09:17.000Z (almost 2 years ago)
- Default Branch: main
- Last Pushed: 2023-08-13T08:32:05.000Z (almost 2 years ago)
- Last Synced: 2025-04-17T22:07:29.658Z (about 1 month ago)
- Language: Jupyter Notebook
- Homepage:
- Size: 11.4 MB
- Stars: 36
- Watchers: 1
- Forks: 8
- Open Issues: 0
- Releases: 8
-
Metadata Files:
- Readme: README.md
- License: LICENSE
README.md
PySAMOSA
PySAMOSA is a Python-based software for processing open ocean and coastal waveforms from SAR satellite
altimetry to measure sea surface heights, wave heights, and wind speed for the oceans and inland waters.
Satellite altimetry is a space-borne remote sensing technique used for Earth observation. More details on satellite
altimetry can be found here.
The process of extracting of the three geophysical parameters from the reflected echoes/waveforms is called retracking. The measured (noisy) waveforms are fitted against the open ocean power return echo waveform model SAMOSA2 [1,2].
In the coastal zone, the return echoes are affected by spurious signals from strongly reflective targets such as sand and mud banks, tidal flats, shipping platforms, sheltered bays, or calm waters close to the shoreline.
The following European Space Agency (ESA) satellite altimetry missions are supported:
- Sentinel-3 (S3)
- Sentinel-6 Michael Freilich (S6-MF)
The software retracks the waveforms, i.e. the Level-1b (L1b) data, to extract the
retracked variables SWH, range, and Pu.
The open ocean retracker implementation specification documents from the official EUMETSAT baseline are used (S3 [1],
S6-MF [2]).
For retracking coastal waveforms the following retrackers are implemented:
- SAMOSA+ [3]
- CORAL [4,5]
In addition, FF-SAR-processed S6-MF data can be retracked using the zero-Doppler beam of the SAMOSA2 model and a
specially adapted $\alpha_p$ LUT table, created by the ESA L2 GPP project [7]. The application of the FF-SAR-processed data
has been validated in [5].
Not validated (experimental) features:
- CryoSat-2 (CS2) support
- SAMOSA++ coastal retracker [2]
- Monte-carlo SAMOSA2 simulator
Getting-started
Usage
Install pysamosa into your environment
$ pip install pysamosa
This is the sample to retrack a single L1b file from the S6-MF mission
from pathlib import Path
import numpy as np
from pysamosa.common_types import L1bSourceType
from pysamosa.data_access import data_vars_s3, data_vars_s6
from pysamosa.retracker_processor import RetrackerProcessor
from pysamosa.settings_manager import get_default_base_settings, SettingsPreset
l1b_files = []
# l1b_files.append(Path('S6A_P4_1B_HR______20211120T051224_20211120T060836_20220430T212619_3372_038_018_009_EUM__REP_NT_F06.nc'))
l1b_files.append(Path.cwd().parent / '.data' / 's6' / 'l1b' / 'S6A_P4_1B_HR______20211120T051224_20211120T060836_20220430T212619_3372_038_018_009_EUM__REP_NT_F06.nc')
l1b_src_type = L1bSourceType.EUM_S6_F06
data_vars = data_vars_s6
# configure coastal CORAL retracker
pres = SettingsPreset.CORALv2
rp_sets, retrack_sets, fitting_sets, wf_sets, sensor_sets = get_default_base_settings(settings_preset=pres, l1b_src_type=l1b_src_type)
rp_sets.nc_dest_dir = l1b_files[0].parent / 'processed'
rp_sets.n_offset = 0
rp_sets.n_inds = 0 #0 means all
rp_sets.n_procs = 6 #use 6 cores in parallel
rp_sets.skip_if_exists = False
additional_nc_attrs = {
'L1B source type': l1b_src_type.value.upper(),
'Retracker preset': pres.value.upper(),
}
rp = RetrackerProcessor(l1b_source=l1b_files, l1b_data_vars=data_vars['l1b'],
rp_sets=rp_sets,
retrack_sets=retrack_sets,
fitting_sets=fitting_sets,
wf_sets=wf_sets,
sensor_sets=sensor_sets,
nc_attrs_kw=additional_nc_attrs,
bbox=[np.array([-29.05, -29.00, 0, 360])],
)
rp.process() #start processing
print(rp.output_l2) #retracked L2 output can be found in here
A running minimal working example for retracking is shown in notebooks/retracking_example.ipynb
.
Development
It is highly recommended to use a proper Python IDE, such as
PyCharm Community or Visual Studio Code.
Using the IDE will allow you to familiarise yourself better with the code, debug and extend it.
Clone the repo
$ git clone {repo_url}
Enter cloned directory
$ cd pysamosa
Install dependencies into your conda env/virtualenv
$ pip install -r requirements.txt
Compile the .pyx files (e.g. model_helpers.pyx) by running cython to build the extensions
For Windows users: An installed C/C++ compiler may be required for installation, e.g. MSCV, which comes with
the free Visual Studio Community
$ python setup.py build_ext --inplace
Optional: Compile on an HPC cluster (not normally required)
$ LDSHARED="icc -shared" CC=icc python setup.py build_ext --inplace
Tips
The following list provides a brief description of the recommended use of the software.
-
Getting-started with Jupyter Notebook
Thenotebooks/retracking_example.ipynb
contains a sample script how to retrack a sample EUMETSAT baseline L1b file.
The retracked SWH and SWH data are compared with the EUMETSAT baseline L2 data. Thenotebooks/demo_script.py
provides
the code example from above to quickly launch a small retracking example. -
More entry points
The filesmain_s3.py
,main_s6.py
,main_cs.py
, (main_*.py
) etc. serve as entry points for batch processing of
multiple nc files.
A list of L1b files (or a single file) is read for retracking, which are fully retracked or based on the given
bounding box (bbox) paramater. A retracked L2 file is written out per processed
L1b file. -
Settings
TheRetrackerProcessor
inputs require theRetrackerProcessorSettings
,RetrackerSettings
,FittingSettings
,
WaveformSettings
, andSensorSettings
objects to be inserted during initialisation. The default settings of these settings objects can be retrieved with theget_default_base_settings
function based on the three
settingsL1bSourceType
andSettingsPreset
.
For instance, the following code snippet is taken from themain_s3.py
file and retracks Sentinel-3 data with the default SAMOSA-based open ocean retracker with no SettingsPreset (100 waveforms from measurement index 25800,
and using 6 cores).
l1b_src_type = L1bSourceType.EUM_S3
pres = SettingsPreset.NONE #use this for the standard SAMOSA-based retracker [2]
# pres = SettingsPreset.CORALv2 #use this for CORALv2 [5]
# pres = SettingsPreset.NONE #use this for SAMOSA+ [3]
rp_sets, retrack_sets, fitting_sets, wf_sets, sensor_sets = get_default_base_settings(settings_preset=pres, l1b_src_type=l1b_src_type)
rp_sets.nc_dest_dir = nc_dest_path / run_name
rp_sets.n_offset = 25800
rp_sets.n_inds = 100
rp_sets.n_procs = 6
rp_sets.skip_if_exists = False
- Evaluation environment
There are several unit tests located in./pysamosa/tests/
that aim to analyse the retracked output in more detail.
The most important test scripts aretest_retrack_multi.py
, which includes retracking of small along-track
segments of the S3A, S6, CS2 missions (and a generic input nc file).
test_retrack_single
allows you to check the retracking result of a single waveform and compare it to reference
retracking result.
Please uncomment the line mpl.use('TkAgg')
in file conftest.py
to
plot the test output, which is particularly useful for the retracking tests in files tests/test_retrack_multi. py
and tests/test_retrack_multi.py
.
- Difference between CORALv1 and CORALv2
- v2 has two additional extensions that were required for S6-MF
- retrack_sets.interference_masking_mask_before_le = True
Interference signals before the leading edge are also masked out by the adaptive inteference mitigation scheme (AIM, CORAL feature) - fitting_sets.Fit_Var_2_MinMax_Hs = (0.0, 20)
lower SWH boundary for fitting procedure is set to 0.0, as defined in [2]
- Quality flag
During the retracking process, the quality flag variablesswh_qual' and
range_qual' (where the latter is just a copy of the former)
are part of the retracked output and indicate the quality of the retracking of each individual waveform (0=good, 1=bad).
This makes a difference particularly in coastal scenarios where the waveforms are affected by spurious signals which tend
to cause incorrectly retracked waveforms. The CORAL coastal retracker maximises the number of valid records in the coastal zone.
We therefore emphasise the importance of consideringswh_qual
/range_qual
quality flags in the retracked product.
Validation
Run tests
To run all the unit tests (using the pytest framework), run
$ pytest
Comparison with EUMETSAT L2 baseline data
Comparison of a retracked open ocean segment from S3 and S6-MF missions with the EUMETSAT L2 baseline (S3: 004,
S6-MF: F06)
(generated by notebooks/retracking_example.ipynb
Jupyter notebook)
S3 | S6-MF |
---|---|
![]() |
![]() |
Contributions
This software is intended to be a community-based project. Contributions to this project are very welcome.
In this case:
- Fork this repository
- Submit a pull request to be merged back into this repository.
Before submitting changes, please check that your changes pass flake8, black, isort and the
tests, including testing other Python versions with tox:
$ flake8 pysamosa tests scripts
$ black . --check --diff
$ isort . --check-only --diff
$ pytest
$ tox
If your pull request is accepted, you will be included in the next official release and will be listed as a
co-author for the DOI link created by Zenodo.
Future work
Possible developments of this project are:
Retracking-related
- Align CS-2 retracking with the CS-2 baseline processing chain, validate against
SAMpy developed as part of the ESA Cryo-TEMPO project - Implement evolutions of the EUMETSAT's baseline processing chain [6], e.g. the numerical retracking planned
for Q3/2023
Software-related
- Create notebook for a coastal retracking demo
- Create richer documentation (readthedocs)
Citation
If you use this software or the code, please cite this DOI:
Florian Schlembach; Marcello Passaro. PySAMOSA: An Open-source Software Framework for Retracking SAMOSA-based, Open
Ocean and Coastal Waveforms of SAR Satellite Altimetry. Zenodo. https://zenodo.org/badge/latestdoi/646028227.
Acknowledgement
The authors are grateful to
Salvatore Dinardo for his support in implementing the SAMOSA-based and SAMOSA+ [3] retracking algorithms.
This package was created with Cookiecutter and the
audreyr/cookiecutter-pypackage project template.
References
[1] SAMOSA Detailed Processing Model: Christine Gommenginger, Cristina Martin-Puig, Meric Srokosz, Marco Caparrini, Salvatore Dinardo, Bruno Lucas, Marco Restano, Américo, Ambrózio and Jérôme Benveniste, Detailed Processing Model of the Sentinel-3 SRAL SAR altimeter ocean waveform retracker, Version 2.5.2, 31 October 2017, Under ESA-ESRIN Contract No. 20698/07/I-LG (SAMOSA), Restricted access as defined in the Contract, Jérôme Benveniste ([email protected]) pers. comm.
[2] EUMETSAT. Sentinel-6/Jason-CS ALT Level 2 Product Generation Specification (L2 ALT PGS), Version V4D; 2022.
https://www.eumetsat.int/media/48266.
[3] Dinardo, Salvatore. ‘Techniques and Applications for Satellite SAR Altimetry over Water, Land and Ice’.
Dissertation, Technische Universität, 2020. https://tuprints.ulb.tu-darmstadt.de/11343/.
[4] Schlembach, F.; Passaro, M.; Dettmering, D.; Bidlot, J.; Seitz, F. Interference-Sensitive Coastal SAR Altimetry
Retracking Strategy for Measuring Significant Wave Height. Remote Sensing of Environment 2022, 274, 112968. https://doi.org/10.1016/j.rse.2022.112968.
[5] Schlembach, F.; Ehlers, F.; Kleinherenbrink, M.; Passaro, M.; Dettmering, D.; Seitz, F.; Slobbe, C. Benefits of Fully Focused SAR Altimetry to Coastal Wave Height Estimates: A Case Study in the North Sea. Remote Sensing of Environment 2023, 289, 113517. https://doi.org/10.1016/j.rse.2023.113517.
[6] Scharroo, R.; Martin-Puig, C.; Meloni, M.; Nogueira Loddo, C.; Grant, M.; Lucas, B. Sentinel-6 Products Status. Ocean Surface Topography Science Team (OSTST) meeting in Venice 2022. https://doi.org/10.24400/527896/a03-2022.3671.
[7] ESA L2 GPP Project: FF-SAR SAMOSA LUT generation was funded under ESA contract 4000118128/16/NL/AI.
Owner metadata
- Name: Florian Schlembach
- Login: floschl
- Email:
- Kind: user
- Description:
- Website:
- Location: Munich, Germany
- Twitter:
- Company:
- Icon url: https://avatars.githubusercontent.com/u/1262767?v=4
- Repositories: 1
- Last ynced at: 2023-08-05T09:45:32.367Z
- Profile URL: https://github.com/floschl
GitHub Events
Total
- Watch event: 9
- Fork event: 2
Last Year
- Watch event: 9
- Fork event: 2
Committers metadata
Last synced: 8 days ago
Total Commits: 128
Total Committers: 2
Avg Commits per committer: 64.0
Development Distribution Score (DDS): 0.008
Commits in past year: 128
Committers in past year: 2
Avg Commits per committer in past year: 64.0
Development Distribution Score (DDS) in past year: 0.008
Name | Commits | |
---|---|---|
Florian Schlembach | 1****l | 127 |
ne62rut | m****o@t****e | 1 |
Committer domains:
- tum.de: 1
Issue and Pull Request metadata
Last synced: 1 day ago
Total issues: 0
Total pull requests: 0
Average time to close issues: N/A
Average time to close pull requests: N/A
Total issue authors: 0
Total pull request authors: 0
Average comments per issue: 0
Average comments per pull request: 0
Merged pull request: 0
Bot issues: 0
Bot pull requests: 0
Past year issues: 0
Past year pull requests: 0
Past year average time to close issues: N/A
Past year average time to close pull requests: N/A
Past year issue authors: 0
Past year pull request authors: 0
Past year average comments per issue: 0
Past year average comments per pull request: 0
Past year merged pull request: 0
Past year bot issues: 0
Past year bot pull requests: 0
Top Issue Authors
Top Pull Request Authors
Top Issue Labels
Top Pull Request Labels
Package metadata
- Total packages: 1
-
Total downloads:
- pypi: 1,005 last-month
- Total dependent packages: 0
- Total dependent repositories: 0
- Total versions: 9
- Total maintainers: 1
pypi.org: pysamosa
PySAMOSA is a software framework for processing open ocean and coastal waveforms from SAR satellite altimetry to measure sea surface heights, wave heights, and wind speed for the oceans and inland water bodies. Satellite altimetry is a space-borne remote sensing technique used for Earth observation.
- Homepage: https://github.com/floschl/pysamosa
- Documentation: https://pysamosa.readthedocs.io/
- Licenses: GNU Lesser General Public License v3 or later (LGPLv3+)
- Latest release: 1.0.0 (published almost 2 years ago)
- Last Synced: 2025-05-16T23:02:02.518Z (1 day ago)
- Versions: 9
- Dependent Packages: 0
- Dependent Repositories: 0
- Downloads: 1,005 Last month
-
Rankings:
- Dependent packages count: 7.262%
- Downloads: 14.243%
- Forks count: 23.087%
- Average: 25.05%
- Stargazers count: 39.261%
- Dependent repos count: 41.395%
- Maintainers (1)
Dependencies
- collective/tox-action main composite
- actions/checkout v3 composite
- actions/checkout v2 composite
- actions/create-release v1 composite
- actions/download-artifact v3 composite
- actions/setup-python v4 composite
- actions/upload-artifact v3 composite
- pypa/cibuildwheel v2.14.0 composite
- pypa/gh-action-pypi-publish release/v1 composite
- astropy >5.0
- black >=23.3
- bokeh >3.1
- bump2version >1.0
- coverage >7.2
- cython >0.29
- flake8 >=6.0
- h5netcdf >=1.1
- imageio >2.28
- isort >=5.12
- matplotlib >3.5
- netCDF4 >1.6.0
- numpy >1.24
- pandas >1.5
- pip >23.1
- pydantic >2.0
- pytest >7.3
- requests >2.28.1
- scipy >1.10
- tox >4.3
- tqdm >4.64
- twine >4.0
- watchdog >=3.0
- wheel >=0.40
- xarray >=2023.1
Score: 11.19040346967574