cryoswath.l1b module#
cryoswath.l1b module
Read and preprocess ESA CryoSat-2 SARIn L1b tracks.
This module covers waveform-level preprocessing, ambiguity handling, DEM referencing, and conversion-ready outputs for L2 generation.
- cryoswath.l1b.append_exclude_mask(cs_l1b_ds)[source]#
Adds mask indicating samples below threshold.
Waveform samples that don’t fulfill power and/or coherence requirements are flagged. The thresholds have to be included in the provided dataset. By default, they are assigned on creation.
- Parameters:
cs_l1b_ds (l1b_data) – Input data.
- Returns:
Data including mask.
- Return type:
l1b_data
- cryoswath.l1b.append_poca_and_swath_idxs(cs_l1b_ds, poca_upper=10, swath_start_window=(5, 50))[source]#
Adds indices for estimated POCA and begin of swath.
- Parameters:
cs_l1b_ds (l1b_data) – Input data.
poca_upper (float) – Maximum distance in meter of POCA sample to first sample above coherence threshold. Defaults to 10.
swath_start_window (tuple[float, float]) – Tuple of minimum and maximum distance in meter of swath start to POCA sample. If the maximum is negative, swath start is set to 0, implying all samples will be swath processed. Defaults to (5, 50).
- Returns:
Data including mask.
- Return type:
l1b_data
- cryoswath.l1b.append_smoothed_complex_phase(cs_l1b_ds, window_extent=21, std=5)[source]#
Append low-pass filtered complex phase representation.
- Parameters:
cs_l1b_ds (Dataset)
window_extent (int)
std (float)
- Return type:
Dataset
- cryoswath.l1b.build_flag_mask(cs_l1b_flag, flag_val_list)[source]#
Function returns a waveform mask based on flag values.
This function can handle two types of flags: those that take the form of a checklist with multiple allowed ticks, and those that indicate one of more possible selections.
It is designed for CryoSat-2 SARIn L1b Baseline D or E data and relies on an attribute “flag_masks” or “flag_values”. For CRISTAL or if the attributes change, this function needs an update.
- Parameters:
cs_l1b_flag (xr.DataArray) – L1bData flag variable.
flag_val_list (list, optional) – List of flag values to mask.
- Returns:
Mask that is True where flag matched provided list.
- Return type:
xr.DataArray
- cryoswath.l1b.download_files(track_idx, stop_event=None)[source]#
Download all missing monthly L1b files for
track_idx.- Parameters:
track_idx (DatetimeIndex | str)
stop_event (Event)
- cryoswath.l1b.download_single_file(track_id)[source]#
Download one L1b file for a single CryoSat track ID.
- Parameters:
track_id (str)
- Return type:
str
- cryoswath.l1b.download_wrapper(region_of_interest=None, start_datetime='2010', end_datetime='2035', *, buffer_region_by=None, track_idx=None, stop_event=None, n_threads=8)[source]#
Download ESA’s L1b product.
- Parameters:
region_of_interest (str | shapely.Polygon, optional) – Provide a RGI identifier or lon/lat polygon to subset downloaded data. Defaults to None.
start_datetime (str | pd.Timestamp, optional) – Defaults to “2010”.
end_datetime (str | pd.Timestamp, optional) – Defaults to “2035”.
buffer_region_by (float, optional) – Use a buffer in meter around provided region (also RGI identifier). Defaults to None.
track_idx (pd.DatetimeIndex | str, optional) – Download only tracks at known times. Defaults to None.
stop_event (Event, optional) – Define when to terminate threads. Defaults to None.
n_threads (int, optional) – Number of download threads. Defaults to 8.
- Returns:
0 on success, 1 on graceful exit after error, and 2 on being aborted.
- Return type:
int
- cryoswath.l1b.drop_waveform(cs_l1b_ds, time_20_ku_mask)[source]#
Use mask along time dim to drop waveforms.
- Parameters:
time_20_ku_mask (1-dim bool) – Mask: drop where True.
- Returns:
Input dataset without marked waveforms.
- Return type:
xr.Dataset or DataArray
- cryoswath.l1b.from_id(track_id, **kwargs)[source]#
Load and preprocess a single track by CryoSat time ID.
- Parameters:
track_id (str | Timestamp)
- Return type:
Dataset
- cryoswath.l1b.get_rgi_o2(ds)[source]#
Finds RGIv7 o2 region that contains the track’s central lat, lon.
- Returns:
RGI v7 long_code
- Return type:
str
- cryoswath.l1b.noise_val(vec)[source]#
calculate average noise values for waveform
- Parameters:
vec (ArrayLike) – First few (well more than 30) samples of power waveform.
- Returns:
Noise power
- Return type:
float
- cryoswath.l1b.read_esa_l1b(l1b_filename, *, waveform_selection=None, drop_waveforms_by_flag={'flag_mcd_20_ku': ['block_degraded', 'blank_block', 'datation_degraded', 'orbit_prop_error', 'echo_saturated', 'other_echo_error', 'sarin_rx1_error', 'sarin_rx2_error', 'window_delay_error', 'agc_error', 'trk_echo_error', 'echo_rx1_error', 'echo_rx2_error', 'npm_error', 'power_scale_error']}, mask_coherence_gt1=True, drop_outside=30000, coherence_threshold=0.6, power_threshold=('snr', 10), smooth_phase_difference=True, use_original_noise_estimates=False, dem_file_name_or_path=None, swath_start_kwargs={})[source]#
Loads ESA SARIn L1b and does initial processing
- Args to init:
l1b_filename (str): File to read data from.
- waveform_selection (int | pd.Timestamp | list[int |
pd.Timestamp] | slice, optional): Waveforms to retrieve data from. If none provided, retrieve all data. Defaults to None.
- drop_waveforms_by_flag (dict[str, list], optional):
Exclude waveform based on flags. Defaults to {“flag_mcd_20_ku”, [ ‘block_degraded’, ‘blank_block’, ‘datation_degraded’, ‘orbit_prop_error’, ‘echo_saturated’, ‘other_echo_error’, ‘sarin_rx1_error’, ‘sarin_rx2_error’, ‘window_delay_error’, ‘agc_error’, ‘trk_echo_error’, ‘echo_rx1_error’, ‘echo_rx2_error’, ‘npm_error’, ‘power_scale_error’]}.
mask_coherence_gt1 (bool, optional): Defaults to True.
- drop_outside (float, optional): Exclude waveforms where nadir is
a chosen distance in meters outside of any RGI glacier. If None, no waveforms are excluded. Defaults to 30_000.
- coherence_threshold (float, optional): Exclude waveform samples
with a lower coherence. This choice also affects the grouping, start sample for swath processing per waveform, and the POCA retrieval. Defaults to 0.6.
- power_threshold (tuple, optional): Similar to the coherence
threshold, but does not affect swath start or POCA retrieval. Defaults to (“snr”, 10).
- Parameters:
l1b_filename (str)
waveform_selection (int | Timestamp | list[int | Timestamp] | slice)
drop_waveforms_by_flag (dict[str, list])
mask_coherence_gt1 (bool)
drop_outside (float)
coherence_threshold (float)
power_threshold (tuple)
smooth_phase_difference (bool)
use_original_noise_estimates (bool)
dem_file_name_or_path (str | None)
swath_start_kwargs (dict)
- Return type:
Dataset