pysiral.waveform

Created on Fri Jul 01 13:07:10 2016

@author: shendric

Classes

`TFMRALeadingEdgeWidth`	Container for computation of leading edge width by taking differences
`L1POCOG`	Computes OCOG (Offset Centre of Gravity) width and amplitude
`L1PLeadingEdgeWidth`	A L1P pre-processor item class for computing leading edge width of a waveform
`L1PSigma0`	A L1P pre-processor item class for computing the backscatter coefficient (sigma0) from
`L1PWaveformPeakiness`	A L1P pre-processor item class for computing pulse peakiness
`L1PLeadingEdgeQuality`	Class to compute a leading edge width quality indicator
`L1PLateTail2PeakPower`
`WFMTrailingEdgeData`	Data Class for L1PTrailingEdgeProperties
`L1PTrailingEdgeProperties`
`WaveFormTrailingEdgeParameterData`
`WaveFormTrailingEdgeDecayFit`
`WaveFormTrailingEdgeParameter`
`L1PLeadingEdgePeakiness`
`WFMTrailingEdgeSlopeData`
`L1PTrailingEdgeSlope`
`OCOGParameter`	Calculate OCOG Parameters (Amplitude, Width) for CryoSat-2 waveform
`CS2PulsePeakiness`	Calculates Pulse Peakiness (full, left & right) for CryoSat-2 waveform
`S3LTPP`	Calculates Late-Tail-to-Peak-Power ratio.
`CS2LTPP`	Calculates Late-Tail-to-Peak-Power ratio.
`EnvisatWaveformParameter`	Currently only computes pulse peakiness for Envisat waveforms

Functions

`get_waveforms_peak_power`(→ numpy.typing.NDArray)	Return the peak power (in input coordinates) of an array of waveforms
`get_footprint_pulse_limited`(→ float)	Compute the CryoSat-2 LRM footprint for variable range to the surface.
`get_footprint_sar`(→ float)	Compute the radar footprint of SAR altimeters for variable range to the surface.
`get_sigma0_sar`(→ float)	Compute the sigma0 backscatter coefficient according the radar equation, e.g.
`get_sigma0`(→ float)	Compute the radar backscatter coefficient sigma nought (sigma0) for lrm waveforms. Uses the radar
`trailing_edge_slope`(→ WFMTrailingEdgeSlopeData)	Compute trailing edge slope as linear fit to the trailing edge
`coeficient_of_determination`(→ float)	Compute coeficient of determination
`get_trailing_edge_lower_envelope_mask`(→ numpy.ndarray)	Compute the indices of the waveforms trailing edge lower envelope.

Module Contents

pysiral.waveform.get_waveforms_peak_power(wfm: numpy.typing.NDArray, use_db: bool = False) → numpy.typing.NDArray

Return the peak power (in input coordinates) of an array of waveforms

Arguments

wfm (float array)
echo waveforms, order = (n_records, n_range_bins)

Returns

float array with maximum for each echo

pysiral.waveform.get_footprint_pulse_limited(r: float, band_width: float) → float

Compute the CryoSat-2 LRM footprint for variable range to the surface.

Applicable Documents:

Michele Scagliola, CryoSat Footprints ESA/Aresys, v1.2 ESA document ref: XCRY-GSEG-EOPG-TN-13-0013

Parameters:

r – range from satellite center of mass to surface reflection point
band_width – pulse bandwidth in Hz

Return area_pl:

Radar backscatter coefficient

pysiral.waveform.get_footprint_sar(r: float, v_s: float, ptr_width: float, tau_b: float, lambda_0: float, wf: float = 1.0, r_mean: float = 6371000.0) → float

Compute the radar footprint of SAR altimeters for variable range to the surface.

Applicable Documents:

Michele Scagliola, CryoSat Footprints ESA/Aresys, v1.2 ESA document ref: XCRY-GSEG-EOPG-TN-13-0013

Parameters:

r – range from satellite center of mass to surface reflection point
v_s – satellite along track velocity in meter/sec
ptr_width – 3dB range point target response temporal width in seconds
tau_b – burst length in seconds
lambda_0 – radar wavelength in meter
wf – footprint widening factor
r_mean – mean earth radius in meter

Return area_sar:

The SAR footprint in square meters

pysiral.waveform.get_sigma0_sar(rx_pwr: float, tx_pwr: float, r: float, a: float, lambda_0: float, g_0: float, l_atm: float = 1.0, l_rx: float = 1.0, bias_sigma0: float = 0.0) → float

Compute the sigma0 backscatter coefficient according the radar equation, e.g. equation 20 in

Guidelines for reverting Waveform Power to Sigma Nought for CryoSat-2 in SAR mode (v2.2), Salvatore Dinardo, 23/06/2016 XCRY-GSEG-EOPS-TN-14-0012

Parameters:

rx_pwr – received power (waveform maximumn)
tx_pwr – transmitted power
r – range to surface in ms
a – area illuminated by the altimeter
lambda_0 – radar wavelength in meter
g_0 – antenna gain factor
l_atm – atmospheric loss factor (1.0 -> no loss)
l_rx – receiving chain losses
bias_sigma0 – sigma0 bias in dB

Returns:

sigma0 in dB

pysiral.waveform.get_sigma0(wf_peak_power_watt: float, tx_pwr: float, r: float, wf_thermal_noise_watt: float = 0.0, lambda_0: float = 0.022084, band_width: float = 320000000.0, g_0: float = 19054.607179632483, bias_sigma0: float = 0.0, l_atm: float = 1.0, l_rx: float = 1.0, c_0: float = 299792458.0) → float

Compute the radar backscatter coefficient sigma nought (sigma0) for lrm waveforms. Uses the radar equation and the computation of the pulse limited footprint

Applicable Documents:

Guidelines for reverting Waveform Power to Sigma Nought for CryoSat-2 in SAR mode (v2.2), Salvatore Dinardo, 23/06/2016 XCRY-GSEG-EOPS-TN-14-0012

Parameters:

wf_peak_power_watt – waveform peak power in watt
tx_pwr – transmitted peak power in watt
r – range from satellite center of mass to surface reflection point (to be appoximated by satellite altitude if no retracker range available)
wf_thermal_noise_watt – estimate of thermal noise power in watt (default: 0.0) will be used to estimate waveform amplitude (Pu)
band_width – CryoSat-2 pulse bandwidth in Hz
lambda_0 – radar wavelength in meter (default: 0.022084 m for CryoSat-2 Ku Band altimeter)
g_0 – antenna gain at boresight (default: 10^(4.28) from document)
bias_sigma0 – sigma nought bias (default: 0.0)
l_atm – two ways atmosphere losses (to be modelled) (default: 1.0 (no loss))
l_rx – receiving chain (RX) waveguide losses (to be characterized) (default: 1.0 (no loss))
c_0 – vacuum light speed in meter/sec

Return sigma_0:

Radar backscatter coefficient

class pysiral.waveform.TFMRALeadingEdgeWidth(rng, wfm, radar_mode, retrack_flag, tfmra_options=None)

Bases: object

Container for computation of leading edge width by taking differences between first maximum power thresholds

tfmra

get_width_from_thresholds(thres0, thres1, **kwargs): Returns the range difference in range bin units between two thresholds, by subtracting the range value of thresh0 from thresh1. This is done for all waveforms passed to this class during initialization. Intended to compute the width of the leading edge. :param thres0: (float) The minimum threshold :param thres1: (float) The minimum threshold :return:

class pysiral.waveform.L1POCOG(**cfg)

Bases: pysiral.l1preproc.procitems.L1PProcItem

Computes OCOG (Offset Centre of Gravity) width and amplitude as a Level-1 pre-processor item

apply(l1: pysiral.l1data.Level1bData) → None

Compute OCOG Width and Amplitude for each waveform and add to classifier data group

Parameters:: l1 – Level-1 data object

property required_options: List[str]

class pysiral.waveform.L1PLeadingEdgeWidth(**cfg)

Bases: pysiral.l1preproc.procitems.L1PProcItem

A L1P pre-processor item class for computing leading edge width of a waveform using the TFMRA retracker as the difference between two thresholds. The unit for leading edge width are range bins

tfmra_leading_edge_start = None

tfmra_leading_edge_end = None

tfmra_options = None

apply(l1: pysiral.l1data.Level1bData) → None: API class for the Level-1 pre-processor. Functionality is compute leading edge width (full, first half & second half) and adding the result to the classifier data group :param l1: A Level-1 data instance :return: None, Level-1 object is change in place

property required_options

class pysiral.waveform.L1PSigma0(**cfg)

Bases: pysiral.l1preproc.procitems.L1PProcItem

A L1P pre-processor item class for computing the backscatter coefficient (sigma0) from waveform data

apply(l1)

API class for the Level-1 pre-processor. Functionality is to compute leading edge width (full, first half & second half) and adding the result to the classifier data group

Parameters:: l1 – A Level-1 data instance
Returns:: None, Level-1 object is change in place

get_sigma0(rx_power: numpy.ndarray, tx_power: numpy.ndarray, altitude: numpy.ndarray, velocity: numpy.ndarray, radar_mode: numpy.ndarray) → numpy.ndarray

Parameters:

rx_power
tx_power
altitude
velocity
radar_mode

Returns:

property required_options

class pysiral.waveform.L1PWaveformPeakiness(skip_first_range_bins: int = 0, norm_is_range_bin: bool = True)

Bases: pysiral.l1preproc.procitems.L1PProcItem

A L1P pre-processor item class for computing pulse peakiness

apply(l1: pysiral.l1data.Level1bData) → None

Computes pulse peakiness and adds parameter to classifier data group.

NOTE: The classifier parameter name depends on the `norm_is_range_bin keyword:

norm_is_range_bin = True -> parameter name: ‘peakiness’ norm_is_range_bin = False -> parameter name: ‘peakiness_normed’

Parameters:: l1 – l1bdata.Level1bData instance
Raises:: None –
Returns:: None

compute_for_waveforms(waveforms: numpy.typing.NDArray) → numpy.typing.NDArray

Compute pulse peakiness for a waveform array

Parameters:: waveforms
Returns:: pulse peakiness array

compute_for_waveform(waveform: numpy.typing.NDArray) → float

Compute pulse peakiness for a single waveform

Parameters:: waveform
Returns:: pulse peakiness

static _compute(waveform: numpy.typing.NDArray, norm: int | float) → float

Compute pulse peakiness for a single waveform

Parameters:: waveform – The waveform

:param norm

Returns:: pulse peakiness

property required_options

class pysiral.waveform.L1PLeadingEdgeQuality(**cfg)

Bases: pysiral.l1preproc.procitems.L1PProcItem

Class to compute a leading edge width quality indicator Requires first_maximum_index classifier parameter

apply(l1)

Adds a quality indicator for the leading edge

Parameters:: l1 – l1bdata.Level1bData instance
Returns:: None

property required_options

class pysiral.waveform.L1PLateTail2PeakPower(**cfg)

Bases: pysiral.l1preproc.procitems.L1PProcItem

apply(l1: pysiral.l1data.Level1bData) → None

Compute late tail to peakiness and add to l1 data object :param l1:

Returns:

static late_tail_to_peak_power(wfm: numpy.typing.NDArray, late_tail_window_idxs: List[int]) → float

Parameters:

wfm
late_tail_window_idxs

Returns:

class pysiral.waveform.WFMTrailingEdgeData

Data Class for L1PTrailingEdgeProperties

waveform_full: numpy.ndarray

trailing_edge_start_idx: int

waveform_trailing_edge_idx: numpy.ndarray

trailing_edge_lower_envelope_idx: numpy.ndarray

trailing_edge_fit: numpy.ndarray = None

trailing_edge_decay: float

trailing_edge_decay_fit_quality: float

trailing_edge_decay_mean_absolute_difference: float

decay_debug_plot(title='') → None

property trailing_edge_size: int

property waveform_trailing_edge_subset: numpy.ndarray

property waveform_trailing_edge_subset_lower_envelope: numpy.ndarray

property first_maximum_power: float

property decay_parameters: Tuple[float, float, float]

class pysiral.waveform.L1PTrailingEdgeProperties(**cfg)

Bases: pysiral.l1preproc.procitems.L1PProcItem

apply(l1: pysiral.l1data.Level1bData) → None

Compute late tail to peakiness and add to l1 data object

Parameters:: l1 – The Level-1 data container
Returns:

static _compute_single_processing(*args) → WaveFormTrailingEdgeParameterData

Compute waveform trailing edge parameter on a single thread

Parameters:: args – Arguments to WaveFormTrailingEdgeParameter
Returns:: Waveform trailing edge parameter object

property config_validation_schema: schema.Schema

class pysiral.waveform.WaveFormTrailingEdgeParameterData(n_records: int)

Bases: object

tew

teq

ted

tedfq

tepr

temad

decay_fit_has_failed

te_exp_popt0

te_exp_popt1

te_exp_popt2

add(other_params: WaveFormTrailingEdgeParameterData) → None

class pysiral.waveform.WaveFormTrailingEdgeDecayFit(fit_kwargs=None)

Bases: object

default_fit_kwargs

fit_kwargs

default_bounds

p0 = None

fit(data)

class pysiral.waveform.WaveFormTrailingEdgeParameter(waveforms: numpy.typing.NDArray, first_maximum_index: numpy.typing.NDArray, valid_first_maximum_index_range: List, trailing_edge_width_kwargs: Dict)

Bases: object

waveforms

first_maximum_index

valid_first_maximum_index_range

trailing_edge_width_kwargs

last_fit_popt = None

params

_compute() → None: Loop over all waveforms and compute the parameters # TODO: Need documentation and potentially move to sub-modules

static get_waveform_trailing_edge_data(waveform_full: numpy.ndarray, first_maximum_index: int = None) → WFMTrailingEdgeData

Aggregate all necesary trailing edge properties in a data class.

Parameters:

waveform_full – The full waveform in original units
first_maximum_index – Index of first maximum (definition of trailing edge start)

Returns:

Data class

static get_trailing_edge_decay(data: WFMTrailingEdgeData, popt: List) → WFMTrailingEdgeData

Fit inverse power law to the lower envelope of the trailing edge and compute decay factor, fit quality and residual to trailing edge power. Result will be added to data class.

Parameters:

data – Pre-compiled trailing edge data
popt – Fit coefficient (function inverse power low)

Raises:

None –

Returns:

Data class with updated results

static trailing_edge_power_ratio(data: WFMTrailingEdgeData, noise_level_normed: float = 0.005) → float

Compute the trailing edge power ratio defined as the fraction of the trailing edge power above a noise level of the exponentation fit. in relation to the integrated power of the full waveform.

Valaues higher than 0.5 indicate that more than half of the waveform power is contained in the trailing edge above the noise level.

Parameters:

data – Waveform Trailing Edge data object
noise_level_normed – The noise level in relation to the first maximum power

Returns:

static get_trailing_edge_width(data: WFMTrailingEdgeData, oversample_factor: int, trailing_edge_end_power_treshold_normed: float) → float

Compute the width of the trailing edge based on the decay fit.

Parameters:

data
oversample_factor
trailing_edge_end_power_treshold_normed

Raises:

None –

Returns:

The trailing edge width in range gate units

static get_trailing_edge_quality(data: WFMTrailingEdgeData) → float

Parameters:: data
Returns:

static get_trailing_edge_lower_envelope(wfm_trailing_edge: numpy.typing.NDArray) → numpy.typing.NDArray

Parameters:: wfm_trailing_edge
Returns:

class pysiral.waveform.L1PLeadingEdgePeakiness(**cfg)

Bases: pysiral.l1preproc.procitems.L1PProcItem

apply(l1: pysiral.l1data.Level1bData)

Mandatory class of a L1 preproceessor item. Computes the leading edge peakiness

Parameters:: l1
Returns:

static leading_edge_peakiness(wfm: numpy.ndarray, fmi: int, window: int) → float

Compute the leading edge peakiness :param wfm: Waveform power :param fmi: first maximum index :param window: the number or leading range bins to the first maximum for the

peakiness computation

Returns:

property required_options

class pysiral.waveform.WFMTrailingEdgeSlopeData

waveform_normed: numpy.ndarray

trailing_edge_start_idx: int

trailing_edge_idx: numpy.ndarray

noise_floor_power_threshold: float

linregress_result: LinregressResult

property range_gate_idx: numpy.ndarray

property trailing_edge_slope: float

property trailing_edge_slope_quality: float

debug_plot()

class pysiral.waveform.L1PTrailingEdgeSlope(**cfg)

Bases: pysiral.l1preproc.procitems.L1PProcItem

apply(l1: pysiral.l1data.Level1bData)

Parameters:: l1
Returns:

_get_trailing_edge_slope(waveforms: numpy.ndarray, first_maximum_indices: numpy.ndarray) → Tuple[numpy.ndarray, numpy.ndarray]

Parameters:

waveforms
first_maximum_indices
use_multiprocessing

Returns:

pysiral.waveform.trailing_edge_slope(waveform: numpy.ndarray, trailing_edge_start_index: int, noise_floor_power_threshold: float = 0.15) → WFMTrailingEdgeSlopeData

Compute trailing edge slope as linear fit to the trailing edge plus the quality (Pearson correlation factor) of the fit

Parameters:

waveform – Waveform
trailing_edge_start_index – Prior information of the start of the trailing edge
noise_floor_power_threshold – Trailing edge power below this threshold will be ignored for the fit

Returns:

class pysiral.waveform.OCOGParameter(wfm_counts)

Bases: object

Calculate OCOG Parameters (Amplitude, Width) for CryoSat-2 waveform counts. Algorithm Source: retrack_ocog.pro from CS2AWI lib

_n

_amplitude

_width

_calc_parameters(wfm_counts)

property amplitude

property width

class pysiral.waveform.CS2PulsePeakiness(wfm_counts, pad=2)

Bases: object

Calculates Pulse Peakiness (full, left & right) for CryoSat-2 waveform counts XXX: This is a 1 to 1 legacy implementation of the IDL CS2AWI method,

consistent method of L1bData or L2Data is required

_n

_n_range_bins

_pad = 2

_peakiness

_peakiness_r

_peakiness_l

_noise_floor

_peakiness_normed

_calc_parameters(wfm_counts)

property peakiness

property peakiness_normed

property noise_floor

property peakiness_r

property peakiness_l

class pysiral.waveform.S3LTPP(wfm_counts, pad=1)

Bases: object

Calculates Late-Tail-to-Peak-Power ratio. source: Rinne 2016

_n

_n_range_bins

_pad = 1

_ltpp

_calc_parameters(wfm_counts)

property ltpp

class pysiral.waveform.CS2LTPP(wfm_counts, pad=2)

Bases: object

Calculates Late-Tail-to-Peak-Power ratio.

_n

_n_range_bins

_pad = 2

_ltpp

_calc_parameters(wfm_counts)

property ltpp

class pysiral.waveform.EnvisatWaveformParameter(wfm, skip=5, bins_after_nominal_tracking_bin=83)

Bases: object

Currently only computes pulse peakiness for Envisat waveforms from SICCI processor.

Parameter for Envisat from SICCI Processor: skip = 5 bins_after_nominal_tracking_bin = 83

t_n = 83

skip = 5

_n

_n_range_bins

_init_parameter()

_calc_parameter(wfm)

pysiral.waveform.coeficient_of_determination(y: numpy.ndarray, y_fit: numpy.ndarray) → float

Compute coeficient of determination

Parameters:

y
y_fit

Returns:

pysiral.waveform.get_trailing_edge_lower_envelope_mask(waveform_power: numpy.ndarray, first_maximum_index: int, max_minimum_cleaning_passes: int = 5, noise_level_normed: float = 0.02, return_type: Literal['bool', 'indices'] = 'bool', mask_fill_value: bool = True) → numpy.ndarray

Compute the indices of the waveforms trailing edge lower envelope. This method relies on the computation of relative minima via scipy. with added filtering.

Parameters:

waveform_power – Waveform power values (any unit)
first_maximum_index – Range gate index of the first maximum.
max_minimum_cleaning_passes – Local minima on the trailing edge may not be in strictly decreasing in power depending on the off-nadir backscatter contanimation of the trailing edge. Local minima are iteratively removed that are not decreasing in power.
noise_level_normed – Points within the noise level of the linear fit between successive local minima are added to the trailing edge mask. Noise level unit is the first maximum power.
return_type – Options are a boolean array with the same dimensions as the waveform (default), or an index array.
mask_fill_value – Default flag value before trailing edge (Default: True)

Returns: