PySAMOSA

PyPI

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 The notebooks/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. The notebooks/demo_script.py provides the code example from above to quickly launch a small retracking example.
More entry points The files main_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 The RetrackerProcessor inputs require the RetrackerProcessorSettings, RetrackerSettings, FittingSettings, WaveformSettings, and SensorSettings objects to be inserted during initialisation. The default settings of these settings objects can be retrieved with the get_default_base_settings function based on the three settings L1bSourceType and SettingsPreset. For instance, the following code snippet is taken from the main_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 are test_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.

<span style="color:red; font-weight:bold">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.</span>

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 variables swh_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 considering swh_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

Pysamosa

Install / Use

README