cryoswath.l1b module

class cryoswath.l1b.L1bData(l1b_filename: str, *, waveform_selection: int | Timestamp | list[int | Timestamp] | slice = None, drop_waveforms_by_flag: dict[str, list] = {'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 = True, drop_outside: float = 30000, coherence_threshold: float = 0.6, power_threshold: tuple = ('snr', 10))[source]

Bases: Dataset

Class to wrap functions and properties for L1b data.

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).

append_ambiguous_reference_elevation()[source]

append_best_fit_phase_index(best_column: callable = None) → Self[source]

Resolve phase difference ambiguity

The phase difference is ambiguous and only know except for a multiple of 2 pi. This method finds the best fitting factor of 2 pi wrt. a digital elevation model (DEM). By default, the summed distance to the DEM per group is minimized.

Parameters:: best_column (callable, optional) – Function that takes a k*n matrix of difference to the DEM as first argument, where k are the number of group members (waveform samples) and n the number of possible wrapping factors. The function needs to return the chosen index along the second axis. Visit the source code to get a template for an excepted function. Defaults to None.
Returns:: L1bData

append_elev_diff_to_ref()[source]

append_smoothed_complex_phase()[source]

classmethod from_id(track_id: str | Timestamp, **kwargs) → Self[source]

get_rgi_o2() → str[source]

Finds RGIv7 o2 region that contains the track’s central lat, lon.

Returns:: RGI v7 long_code
Return type:: str

locate_ambiguous_origin()[source]

Calculates all “possible” echo origins.

Adds for the 7 look angles xph_thetas the variables xph_lats, xph_lons, xph_elevs, and xph_dists.

Returns:: l1b_data including the calculated coordinates.
Return type:: Dataset

phase_jump()[source]

phase_outlier(tol: float | None = None)[source]

ref_range() → DataArray[source]

Calculate distance to center of range window.

Returns:: Reference ranges.
Return type:: xr.DataArray

tag_groups() → Self[source]

Identifies and tags wafeform sample groups.

Returns:: l1b_ds.
Return type:: Self

to_l2(out_vars: list | dict = None, *, retain_vars: list | dict = None, swath_or_poca: str = 'swath', group_best_column_func: callable = None, **kwargs) → GeoDataFrame[source]

Converts l1b data to l2 data (point elevations).

Parameters:

out_vars (list | dict, optional) – Return values. If none provided, returns time, x, y, height, reference elevation, and difference wrt. reference. Provide a dictionary to assign custom names. Defaults to None.
retain_vars (list | dict, optional) – Additional to out_vars. Defaults to None.
swath_or_poca (str, optional) – Either “swath”, “poca”, or “both”. Decides what data is returned. Defaults to “swath”.
group_best_column_func (callable, optional) – Optimization function to resolve phase difference ambiguity. View append_best_fit_phase_index() for details.

Raises:

ValueError – If swath_or_poca cannot be interpreted.

Returns:

Elevation estimates and requested variables. If swath_or_poca is “both”, a tuple with separate tables is returned.

Return type:

gpd.GeoDataFrame

unwrap_phase_diff() → Self[source]

Replaces phase difference by unwrapped version.

Unwrapping is done per group of waveform samples.

Returns:: l1b_ds.
Return type:: Self

cryoswath.l1b.append_exclude_mask(cs_l1b_ds: L1bData) → L1bData[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: L1bData) → L1bData[source]

Adds indices for estimated POCA and begin of swath.

Parameters:: cs_l1b_ds (l1b_data) – Input data.
Returns:: Data including mask.
Return type:: l1b_data

cryoswath.l1b.build_flag_mask(cs_l1b_flag: DataArray, flag_val_list: list) → DataArray[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: DatetimeIndex | str, stop_event: Event = None)[source]

cryoswath.l1b.download_single_file(track_id: str) → str[source]

cryoswath.l1b.download_wrapper(region_of_interest: str | Polygon = None, start_datetime: str | Timestamp = '2010', end_datetime: str | Timestamp = '2035', *, buffer_region_by: float = None, track_idx: DatetimeIndex | str = None, stop_event: Event = None, n_threads: int = 8) → int[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