fit

Utilities for calculating average fits from ATL03 Geolocated Photon Data

Source code

General Methods

icesat2_toolkit.fit.compress_list(i, n)[source]

Compress complete list of valid indices into a set of ranges

Parameters
i: int

indices to compress

n: int

largest gap between indices to accept for range

icesat2_toolkit.fit.extract_tep_histogram(tep_hist_time, tep_hist, tep_range_prim)[source]

Centers the transmit-echo-path histogram reported by ATL03 using an iterative edit to distinguish between signal and noise

Parameters
tep_hist_time: float

TEP histogram bin times

tep_hist: int

TEP histogram

tep_range_prim: float

primary histogram range values

icesat2_toolkit.fit.filter_elevation(r0)[source]

Calculates the interquartile range [Pritchard2009] and robust dispersion estimator [Smith2017] of the model residuals

Parameters
r0: float

height residuals

Returns
IQR: float

75% of the interquartile range

RDE: float

50% of the difference between the 84th and 16th percentiles

median: float

median value of height residuals

References

Pritchard2009

H. D. Pritchard et al., “Extensive dynamic thinning on the margins of the Greenland and Antarctic ice sheets”, Nature, 461(7266), 971–975, (2009). doi:10.1038/nature08471

Smith2017

B. E. Smith el al., “Connected subglacial lake drainage beneath Thwaites Glacier, West Antarctica”, The Cryosphere, 11(1), 451–467, (2017). doi:10.5194/tc-11-451-2017

icesat2_toolkit.fit.try_surface_fit(x, y, z, confidence_mask, dist_along, SURF_TYPE='linear', ITERATE=25, CONFIDENCE=[4, 3, 2, 1, 0])[source]

Try fitting a surface to the signal photons with progressively less confidence if no valid surface is found

Parameters
x: float

along-track x-coordinates

y: float

along-track y-coordinates

z: float

along-track photon heights

confidence_mask: int

confidence level of each photon event

dist_along: float

center of segment in along-track x-coordinates

SURF_TYPE: str, default ‘linear’

Surface polynomial to fit to photon heights

  • 'linear'

  • 'quadratic'

ITERATE: int, default 25

maximum number of iterations to use in fit

CONFIDENCE: list, default [4,3,2,1,0]

Minimum photon confidence levels to attempt to use in fit

icesat2_toolkit.fit.reduce_surface_fit(x, y, z, centroid, ind, SURF_TYPE='linear', ITERATE=25)[source]

Iteratively fit a polynomial surface to the elevation data to reduce to within a valid surface window [Smith2019]

Parameters
x: float

along-track x-coordinates

y: float

along-track y-coordinates

z: float

along-track photon heights

centroid: dict

segment center for referencing along-track coordinates

  • 'x': centroid of x-coordinates

  • 'y': centroid of y-coordinates

ind: int

indices of photon events for confidence level to use in fit

SURF_TYPE: str, default ‘linear’

Surface polynomial to fit to photon heights

  • 'linear'

  • 'quadratic'

ITERATE: int, default 25

maximum number of iterations to use in fit

References

Smith2019

B. E. Smith el al., “Land ice height-retrieval algorithm for NASA’s ICESat-2 photon-counting laser altimeter”, Remote Sensing of Environment, 233, 111352, (2019). doi:10.1016/j.rse.2019.111352

icesat2_toolkit.fit.fit_surface(x, y, z, centroid, SURF_TYPE='linear')[source]

Fit a polynomial surface to the elevation data

Parameters
x: float

along-track x-coordinates

y: float

along-track y-coordinates

z: float

along-track photon heights

centroid: dict

segment center for referencing along-track coordinates

  • 'x': centroid of x-coordinates

  • 'y': centroid of y-coordinates

SURF_TYPE: str, default ‘linear’

Surface polynomial to fit to photon heights

  • 'linear'

  • 'quadratic'

icesat2_toolkit.fit.try_histogram_fit(x, y, z, confidence_mask, dist_along, dt, FIT_TYPE='gaussian', ITERATE=25, BACKGROUND=0, CONFIDENCE=[2, 1, 0])[source]

Try fitting a function to the signal photon histograms with progressively less confidence if no valid fit is found

Parameters
x: float

along-track x-coordinates

y: float

along-track y-coordinates

z: float

along-track photon heights

confidence_mask: int

confidence level of each photon event

dist_along: float

center of segment in along-track x-coordinates

dt: float

histogram bin size in seconds

FIT_TYPE: str, default ‘linear’

decomposition function to fit to photon height histograms

  • 'gaussian'

  • 'general'

ITERATE: int, default 25

maximum number of iterations to use in fit

BACKGROUND: float or int, default 0

vertical noise-photon density for segment

CONFIDENCE: list, default [2,1,0]

Minimum photon confidence levels to attempt to use in fit

icesat2_toolkit.fit.reduce_histogram_fit(x, y, z, ind, dt, FIT_TYPE='gaussian', ITERATE=25, PEAKS=2, BACKGROUND=0)[source]

Iteratively use decomposition fitting to the elevation data to reduce to within a valid surface window

Parameters
x: float

along-track x-coordinates

y: float

along-track y-coordinates

z: float

along-track photon heights

ind: int

indices of photon events for confidence level to use in fit

dt: float

histogram bin size in seconds

FIT_TYPE: str, default ‘linear’

decomposition function to fit to photon height histograms

  • 'gaussian'

  • 'general'

ITERATE: int, default 25

maximum number of iterations to use in fit

PEAKS: int, default 2

estimated number of signal peaks in the segment histogram

BACKGROUND: float or int, default 0

vertical noise-photon density for segment

icesat2_toolkit.fit.fit_histogram(z, hist, priors, lower_bound, upper_bound, FIT_TYPE=None)[source]

Optimially fit a function to the photon event histogram with Levenberg-Marquardt algorithm

Parameters
z: float

photon height histogram bins

hist: int

photon height histogram

priors: float

mean estimate for each histogram fit parameter

lower_bound: float

lower-bound estimate for each histogram fit parameter

upper_bound: float

upper-bound estimate for each histogram fit parameter

FIT_TYPE: str, default ‘linear’

decomposition function to fit to photon height histograms

  • 'gaussian'

  • 'general'

icesat2_toolkit.fit.fit_geolocation(var, distance_along_X, X_atc)[source]

Calculate the average of photon event variables by fitting with respect to the center of the along-track coordinates

Parameters
var: float

photon event variable to compute average

distance_along_X: float

along-track x-coordinates

X_atc: float

segment center in along-track x-coordinates

icesat2_toolkit.fit.segment_mean(var, **kwargs)[source]

Calculate the average value from two segments with possible invalid values

Parameters
var: float

segment variable to compute average

fill_value: float, default None

replacement fill value for averages

Returns
ave: float

average value of two segments

icesat2_toolkit.fit.calc_first_photon_bias(temporal_residuals, n_pulses, n_pixels, dead_time, dt, METHOD='direct', ITERATE=20)[source]

Estimate mean and median first photon bias corrections [Smith2019]

Parameters
temporal_residuals: float

photon height residuals in seconds

n_pulses: int

Estimated number of laser pulses in segment

n_pixels: int

Number of pixels for beam

dead_time: float

Estimated dead time

dt: float

Histogram bin size in seconds

METHOD: str, default ‘direct’

Method for computing first photon bias

  • 'direct'

  • 'logarithmic'

ITERATE: int, default 20

maximum number of iterations to use in 'logarithmic' method

References

Smith2019

B. E. Smith el al., “Land ice height-retrieval algorithm for NASA’s ICESat-2 photon-counting laser altimeter”, Remote Sensing of Environment, 233, 111352, (2019). doi:10.1016/j.rse.2019.111352

icesat2_toolkit.fit.histogram_first_photon_bias(t_full, hist, n_pulses, n_pixels, dead_time, dt, METHOD='direct', ITERATE=20)[source]

Estimate mean and median first photon bias corrections using histogram fit residuals

Parameters
t_full: float

histogram bins in seconds

hist: int or float

photon height residuals histogram

n_pulses: int

Estimated number of laser pulses in segment

n_pixels: int

Number of pixels for beam

dead_time: float

Estimated dead time

dt: float

Histogram bin size in seconds

METHOD: str, default ‘direct’

Method for computing first photon bias

  • 'direct'

  • 'logarithmic'

ITERATE: int, default 20

maximum number of iterations to use in 'logarithmic' method

icesat2_toolkit.fit.calc_transmit_pulse_shape(t_TX, p_TX, W_TX, W_RX, dt_W, SNR, ITERATE=50)[source]

Estimate the transmit-pulse-shape correction needed for segment averages [Smith2019]

Parameters
t_TX: float

windowed TEP histogram time with respect to histogram centroid

p_TX: float

windowed TEP histogram power with noise estimate removed

W_TX: float

Robust Dispersion Estimate (RDE) of windowed transmit pulse

W_RX: float

Robust Dispersion Estimate (RDE) of segment fit residuals

dt_W: float

Segment fit window

SNR: float

Estimated signal-to-noise ratio of segment photons

ITERATE: int, default 50

maximum number of iterations to use

References

Smith2019

B. E. Smith el al., “Land ice height-retrieval algorithm for NASA’s ICESat-2 photon-counting laser altimeter”, Remote Sensing of Environment, 233, 111352, (2019). doi:10.1016/j.rse.2019.111352