scrollstats.ridge_metrics package

class scrollstats.ridge_metrics.BendDataExtractor(transects, bin_raster=None, dem=None, ridges=None, packets=None)

Bases: object

Responsible for extraction of ridge metrics across an entire bend.

Parameters:
calc_itx_metrics()

For each transect found in transects, calculate the itx metrics.

Return type:

GeoDataFrame

calc_transect_metrics()
Return type:

GeoDataFrame

count_ridges(signal)

Counts ridges in binary waves.

Parameters:

signal (ndarray[float])

Return type:

int

dense_sample(line, raster)

Sample an underlying in_bin_raster along a given LineString at a frequency of ~1m

Parameters:
Return type:

ndarray[float]

disqualify_coords(coord_array, raster)

Some coordinates may be out of the in_bin_raster. This function disqualifies these coordinates and returns a boolean array showing the location of all disqualified coordinates.

Coordinates are checked to see if they are 1) negative, 2) too large in x, or 3) too large in y

Parameters:
Return type:

ndarray[bool]

dominant_wavelength(ridge_count, signal)

Identifies the dominant wavelength from an input binary signal

Parameters:
Return type:

float

sample_array(coord_array, raster)

Takes in an array of image coordinates, samples the image, and returns the sampled values. Assumes that the coord array and in_bin_raster dataset share the same crs.

Parameters:
Return type:

ndarray[float]

trans_fft(signal)

Calculates the fast fourier transform for a 1D signal.

If you wish to see the power spectra, plot the sampled frequencies (x) vs their measured amplitude (y) The dominant wavelength within a given signal can be found with the function dominant_wavelength() below

Parameters:

signal (ndarray[float])

Return type:

tuple[ndarray[float], ndarray[float]]

class scrollstats.ridge_metrics.RidgeDataExtractor(geometry, position, ridges, dem_signal=None, bin_signal=None)

Bases: object

Responsible for calculating ridge metrics at each intersection of a ridge and transect. The geometry for this class is a 3-vertex LineString

Parameters:
add_point_geometries(gdf, line)

Add the vertices from the 3vertex line as point geometries

Parameters:
Return type:

GeoDataFrame

boolify_mask()

Simplifies the bin_sig (which may contain nans) to a pure boolean array

Return type:

ndarray[bool] | None

calc_every_ridge_amp()

Calculates the average amplitude of each observed ridges in the units of the DEM.

Return type:

ndarray[float] | list[None]

calc_relative_vertex_distance(gdf, line)

Calculate the relative distance of each vertex along the transect.

Parameters:
Return type:

GeoDataFrame

calc_ridge_coms()

Find the center of mass for each ridge in the input binary signal.

Return type:

ndarray[bool] | None

calc_ridge_width_px()

Calculate the width of the single ridge in pixels

Return type:

float | None

calc_values_from_ridge_info(gdf)

Calculates the migration time, distance, and rate both before and after the center ridge. If the ridge does not have values for the deposit year, then mig_rate will be NaN.

Parameters:

gdf (GeoDataFrame)

Return type:

GeoDataFrame

calc_vertex_indices(gdf, signal_length)

Calculate the array index of all vertices. If self.signal_length is nan, then return array of nans

Parameters:
Return type:

GeoDataFrame

coerce_dtypes(gdf)

Coerce the the ‘object’ dtypes into their proper numeric types

Parameters:

gdf (GeoDataFrame)

Return type:

GeoDataFrame

create_point_gdf()

Create a 3 point GeoDataFrame to contain all relevant info for other methods.

Return type:

GeoDataFrame

determine_metric_confidence()

Assign a metric confidence score based on the boolean mask.

Return type:

int

determine_ridge_amp()

Select the correct ridge amplitude calculated by calc_every_ridge_amp() based on the number of ridges present

Return type:

float | None

determine_signal_length()

Return length of dem/bin signal if provided

Return type:

float

dq_first_swale()

If the ridge position of the signal is 0, then remove the first chunk of false values

Return type:

ndarray[bool] | None

dump_data()

Dump all the relevant info for the middle point.

Return type:

dict[str, Any]

find_closest_ridge()

The bin_signal may have more than two ridges present. This method identifies which ridge is closest to the transect-ridge intersection point.

Return type:

ndarray[float]

join_ridge_info(gdf, ridges)

Get ridge ids, time, distance, and migration rates via spatial join from the ridge features

Parameters:
Return type:

GeoDataFrame

class scrollstats.ridge_metrics.TransectDataExtractor(transect_id, geometry, dem_signal=None, bin_signal=None, ridges=None)

Bases: object

Responsible for extracting ridge metrics along a transect.

TransectDataExtractor will ultimately return a GeoDataFrame where each row is an eligible intersection between the transect and the ridge An eligible intersection is one that has a vertex before and after it so that the raster underneath can be sampled along the full width of the ridge. If a transect contains no eligible intersections, the gdf will be empty.

Parameters:
add_point_geometry(gdf)

Add the intersection (middle) point of the 3 vertex substring as its own point

Parameters:

gdf (GeoDataFrame)

Return type:

GeoDataFrame

add_relative_vertex_distances(gdf)

Calculate the distance between the substring coordinates relative to the length of the whole line.

Parameters:

gdf (GeoDataFrame)

Return type:

GeoDataFrame

add_substring_geometry(gdf)

Adds the 3 vertex substring that corresponds to each itx.

Parameters:

gdf (GeoDataFrame)

Return type:

GeoDataFrame

add_transect_id(gdf)

Add the transect id as a column

Parameters:

gdf (GeoDataFrame)

Return type:

GeoDataFrame

calc_cumulative_dist(coords)

Calculate the cumulative distances along a coordinate series

Parameters:

coords (Sequence[tuple[float, float]])

Return type:

ndarray[float]

calc_relative_vertex_distances(ls, start_dist)

Calculate the relative distance of each vertex along the transect.

Parameters:
Return type:

ndarray[float]

calc_ridge_metrics()

Calculate ridge width and amplitude at every transect-ridge intersection. Return a GeoDataFrame with Point geometries.

Return type:

GeoDataFrame

calc_vertex_indices(gdf)

Calculates the corresponding signal index of each of the substring vertices

Parameters:

gdf (GeoDataFrame)

Return type:

GeoDataFrame

create_itx_gdf()

Create the gdf that will contain all the ridge data for each intersection.

Return type:

GeoDataFrame

create_substrings(ls)

Create substrings starting from the eligible coordinates of the given linestring

Parameters:

ls (LineString)

Return type:

list[LineString]

determine_eligible_coords(ls)

Determine coordinates in the transect linestring that are eligible to be a start of a substring. Because the substrings are all 3 vertices long, the last two are not eligible. These eligible coords are defined because multiple functions need to use these coordinates.

Parameters:

ls (LineString)

Return type:

list[tuple[float, float]]

determine_substring_starts(gdf)

Determine the along-transect distance of the points of each substring

Parameters:

gdf (GeoDataFrame)

Return type:

GeoDataFrame

slice_bin_signal(gdf)

Slice the binary signal between the two end vertices of the substrings

Parameters:

gdf (GeoDataFrame)

Return type:

GeoDataFrame

slice_dem_signal(gdf)

Slice the DEM between the two end vertices of the substrings

Parameters:

gdf (GeoDataFrame)

Return type:

GeoDataFrame

scrollstats.ridge_metrics.calc_ridge_amps(dem_sig, bin_sig)

Calculate the ridge amplitudes from a DEM profile using the boolean mask signal.

Different strategies are used to calculate the ridge amplitude based on the ridge and swale count found within the boolean mask signal.

Parameters:
Return type:

ndarray[float]

scrollstats.ridge_metrics.calculate_ridge_metrics(in_transects, in_ridges, in_bin_raster=None, in_dem=None, in_packets=None)

Main function to calculate scroll metrics.

If in_packets is specified, then all metrics for the rich_transects will be calculated for the transect fragment within each packet.

All arguments can be provided as a file path or in-memory object (vector: GeoDataFrame, raster: rasterio dataset)

Parameters:
Return type:

tuple[GeoDataFrame, GeoDataFrame]

scrollstats.ridge_metrics.map_amp_values(amp_series, width_series)

Map the ridge amplidute values to their assumed location along the transect. Assumed location is the approximate midpoint of the ridge.

Parameters:
Return type:

ndarray[float]

Submodules

scrollstats.ridge_metrics.calc_ridge_metrics module

scrollstats.ridge_metrics.calc_ridge_metrics.calculate_ridge_metrics(in_transects, in_ridges, in_bin_raster=None, in_dem=None, in_packets=None)

Main function to calculate scroll metrics.

If in_packets is specified, then all metrics for the rich_transects will be calculated for the transect fragment within each packet.

All arguments can be provided as a file path or in-memory object (vector: GeoDataFrame, raster: rasterio dataset)

Parameters:
Return type:

tuple[GeoDataFrame, GeoDataFrame]

scrollstats.ridge_metrics.data_extractors module

This module contains the classes and functions used to extract data along the transects.

Data is extracted at three scales: bend, transect, and ridge. Packet-scale metrics are just the ridge scale metrics aggregated within the packet boundaries. No unique extraction is done for the packet-scale.

Rules: - null attributes are None, df values are NaN

class scrollstats.ridge_metrics.data_extractors.BendDataExtractor(transects, bin_raster=None, dem=None, ridges=None, packets=None)

Bases: object

Responsible for extraction of ridge metrics across an entire bend.

Parameters:
calc_itx_metrics()

For each transect found in transects, calculate the itx metrics.

Return type:

GeoDataFrame

calc_transect_metrics()
Return type:

GeoDataFrame

count_ridges(signal)

Counts ridges in binary waves.

Parameters:

signal (ndarray[float])

Return type:

int

dense_sample(line, raster)

Sample an underlying in_bin_raster along a given LineString at a frequency of ~1m

Parameters:
Return type:

ndarray[float]

disqualify_coords(coord_array, raster)

Some coordinates may be out of the in_bin_raster. This function disqualifies these coordinates and returns a boolean array showing the location of all disqualified coordinates.

Coordinates are checked to see if they are 1) negative, 2) too large in x, or 3) too large in y

Parameters:
Return type:

ndarray[bool]

dominant_wavelength(ridge_count, signal)

Identifies the dominant wavelength from an input binary signal

Parameters:
Return type:

float

sample_array(coord_array, raster)

Takes in an array of image coordinates, samples the image, and returns the sampled values. Assumes that the coord array and in_bin_raster dataset share the same crs.

Parameters:
Return type:

ndarray[float]

trans_fft(signal)

Calculates the fast fourier transform for a 1D signal.

If you wish to see the power spectra, plot the sampled frequencies (x) vs their measured amplitude (y) The dominant wavelength within a given signal can be found with the function dominant_wavelength() below

Parameters:

signal (ndarray[float])

Return type:

tuple[ndarray[float], ndarray[float]]

class scrollstats.ridge_metrics.data_extractors.RidgeDataExtractor(geometry, position, ridges, dem_signal=None, bin_signal=None)

Bases: object

Responsible for calculating ridge metrics at each intersection of a ridge and transect. The geometry for this class is a 3-vertex LineString

Parameters:
add_point_geometries(gdf, line)

Add the vertices from the 3vertex line as point geometries

Parameters:
Return type:

GeoDataFrame

boolify_mask()

Simplifies the bin_sig (which may contain nans) to a pure boolean array

Return type:

ndarray[bool] | None

calc_every_ridge_amp()

Calculates the average amplitude of each observed ridges in the units of the DEM.

Return type:

ndarray[float] | list[None]

calc_relative_vertex_distance(gdf, line)

Calculate the relative distance of each vertex along the transect.

Parameters:
Return type:

GeoDataFrame

calc_ridge_coms()

Find the center of mass for each ridge in the input binary signal.

Return type:

ndarray[bool] | None

calc_ridge_width_px()

Calculate the width of the single ridge in pixels

Return type:

float | None

calc_values_from_ridge_info(gdf)

Calculates the migration time, distance, and rate both before and after the center ridge. If the ridge does not have values for the deposit year, then mig_rate will be NaN.

Parameters:

gdf (GeoDataFrame)

Return type:

GeoDataFrame

calc_vertex_indices(gdf, signal_length)

Calculate the array index of all vertices. If self.signal_length is nan, then return array of nans

Parameters:
Return type:

GeoDataFrame

coerce_dtypes(gdf)

Coerce the the ‘object’ dtypes into their proper numeric types

Parameters:

gdf (GeoDataFrame)

Return type:

GeoDataFrame

create_point_gdf()

Create a 3 point GeoDataFrame to contain all relevant info for other methods.

Return type:

GeoDataFrame

determine_metric_confidence()

Assign a metric confidence score based on the boolean mask.

Return type:

int

determine_ridge_amp()

Select the correct ridge amplitude calculated by calc_every_ridge_amp() based on the number of ridges present

Return type:

float | None

determine_signal_length()

Return length of dem/bin signal if provided

Return type:

float

dq_first_swale()

If the ridge position of the signal is 0, then remove the first chunk of false values

Return type:

ndarray[bool] | None

dump_data()

Dump all the relevant info for the middle point.

Return type:

dict[str, Any]

find_closest_ridge()

The bin_signal may have more than two ridges present. This method identifies which ridge is closest to the transect-ridge intersection point.

Return type:

ndarray[float]

join_ridge_info(gdf, ridges)

Get ridge ids, time, distance, and migration rates via spatial join from the ridge features

Parameters:
Return type:

GeoDataFrame

class scrollstats.ridge_metrics.data_extractors.TransectDataExtractor(transect_id, geometry, dem_signal=None, bin_signal=None, ridges=None)

Bases: object

Responsible for extracting ridge metrics along a transect.

TransectDataExtractor will ultimately return a GeoDataFrame where each row is an eligible intersection between the transect and the ridge An eligible intersection is one that has a vertex before and after it so that the raster underneath can be sampled along the full width of the ridge. If a transect contains no eligible intersections, the gdf will be empty.

Parameters:
add_point_geometry(gdf)

Add the intersection (middle) point of the 3 vertex substring as its own point

Parameters:

gdf (GeoDataFrame)

Return type:

GeoDataFrame

add_relative_vertex_distances(gdf)

Calculate the distance between the substring coordinates relative to the length of the whole line.

Parameters:

gdf (GeoDataFrame)

Return type:

GeoDataFrame

add_substring_geometry(gdf)

Adds the 3 vertex substring that corresponds to each itx.

Parameters:

gdf (GeoDataFrame)

Return type:

GeoDataFrame

add_transect_id(gdf)

Add the transect id as a column

Parameters:

gdf (GeoDataFrame)

Return type:

GeoDataFrame

calc_cumulative_dist(coords)

Calculate the cumulative distances along a coordinate series

Parameters:

coords (Sequence[tuple[float, float]])

Return type:

ndarray[float]

calc_relative_vertex_distances(ls, start_dist)

Calculate the relative distance of each vertex along the transect.

Parameters:
Return type:

ndarray[float]

calc_ridge_metrics()

Calculate ridge width and amplitude at every transect-ridge intersection. Return a GeoDataFrame with Point geometries.

Return type:

GeoDataFrame

calc_vertex_indices(gdf)

Calculates the corresponding signal index of each of the substring vertices

Parameters:

gdf (GeoDataFrame)

Return type:

GeoDataFrame

create_itx_gdf()

Create the gdf that will contain all the ridge data for each intersection.

Return type:

GeoDataFrame

create_substrings(ls)

Create substrings starting from the eligible coordinates of the given linestring

Parameters:

ls (LineString)

Return type:

list[LineString]

determine_eligible_coords(ls)

Determine coordinates in the transect linestring that are eligible to be a start of a substring. Because the substrings are all 3 vertices long, the last two are not eligible. These eligible coords are defined because multiple functions need to use these coordinates.

Parameters:

ls (LineString)

Return type:

list[tuple[float, float]]

determine_substring_starts(gdf)

Determine the along-transect distance of the points of each substring

Parameters:

gdf (GeoDataFrame)

Return type:

GeoDataFrame

slice_bin_signal(gdf)

Slice the binary signal between the two end vertices of the substrings

Parameters:

gdf (GeoDataFrame)

Return type:

GeoDataFrame

slice_dem_signal(gdf)

Slice the DEM between the two end vertices of the substrings

Parameters:

gdf (GeoDataFrame)

Return type:

GeoDataFrame

scrollstats.ridge_metrics.data_extractors.calc_dist(p1, p2)

p1 and p2 are both (n,2) arrays of coordinates

Parameters:
Return type:

ndarray

scrollstats.ridge_metrics.data_extractors.densify_line(line)

Return the given LineString densified coordinates. Density = 1pt/unit length

Parameters:

line (LineString)

Return type:

LineString

scrollstats.ridge_metrics.data_extractors.densify_segment(line)

Densify a line segment between two points to 1pt/m. Assumes line coordinates are in meters

Parameters:

line (LineString)

Return type:

LineString

scrollstats.ridge_metrics.data_extractors.explode(line)

Return a list of all 2 coordinate line segments in a given LineString

Parameters:

line (LineString)

Return type:

list[LineString]

scrollstats.ridge_metrics.data_extractors.remove_coincident_points(coord_array)

Removes coincident points that happen to be adjacent

Parameters:

coord_array (ndarray)

Return type:

ndarray

scrollstats.ridge_metrics.data_extractors.transform_coords(coord_array, bin_raster)

Transform the coordinates from geo to image for indexing a in_bin_raster

Parameters:
Return type:

ndarray

scrollstats.ridge_metrics.ridge_amplitude module

scrollstats.ridge_metrics.ridge_amplitude.calc_ridge_amps(dem_sig, bin_sig)

Calculate the ridge amplitudes from a DEM profile using the boolean mask signal.

Different strategies are used to calculate the ridge amplitude based on the ridge and swale count found within the boolean mask signal.

Parameters:
Return type:

ndarray[float]

scrollstats.ridge_metrics.ridge_amplitude.calc_ridge_maxes(dem_sig, mask)

Calculate the max value of the dem signal within each of the ridge areas in the mask

Parameters:
Return type:

ndarray[float]

scrollstats.ridge_metrics.ridge_amplitude.calc_swale_mins(dem_sig, mask)

Calculate the minimum value within each of the swale areas of the mask

Parameters:
Return type:

ndarray[float]

scrollstats.ridge_metrics.ridge_amplitude.determine_complex_strategy(bool_mask)

This function determines which multi ridge/swale amplitude calculation strategy to use.

Generally, the ridge amplitude is calculated as the average differences between the ridge max and the two swale mins. However, exceptions must be made if the boolean_mask begins or ends with a ridge (this beginning/ending ridge will not have a swale on one of the sides)

Importantly, this function only deals with boolean arrays with more than one ridges and or swales. This means that this function does not have to deal with edge cases of flat or s-shaped signals.

Parameters:

bool_mask (ndarray[bool])

Return type:

Callable[[ndarray[float], ndarray[float]], ndarray[float]]

scrollstats.ridge_metrics.ridge_amplitude.map_amp_values(amp_series, width_series)

Map the ridge amplidute values to their assumed location along the transect. Assumed location is the approximate midpoint of the ridge.

Parameters:
Return type:

ndarray[float]

scrollstats.ridge_metrics.ridge_amplitude.s00_amps(maxes, mins)
Amplitude calculation if binary signal is capped with 0s on each end.

_ _ _

ex. _| |_| |_| |_

Amplitude for each ridge is calculated as the average of the differences between ridge max and the swale mins on each side. However, the amplitude of the ridge at the beginning is calculated only by the following swale because of channel effects on the DEM signal.

Parameters:
Return type:

ndarray[float]

scrollstats.ridge_metrics.ridge_amplitude.s01_amps(maxes, mins)
Amplitude calculation if binary signal starts with a swale and ends with a ridge.

_ _ _

ex. _| |_| |_|

Amplitude for each ridge is calculated as the average of the differences between ridge max and the swale mins on each side. However, because there is no swale at the end, the last ridge only gets one amplitude measurement Additionally, the amplitude of the ridge at the beginning is calculated only by the following swale because of channel effects on the DEM signal.

Parameters:
Return type:

ndarray[float]

scrollstats.ridge_metrics.ridge_amplitude.s10_amps(maxes, mins)
Amplitude calculation if binary signal starts with a ridge and ends with a swale.

_ _ _

ex. |_| |_| |_

Amplitude for each ridge is calculated as the average of the differences between ridge max and the swale mins on each side. However, because there is no swale at the beginning, the first ridge only gets one amplitude measurement

Parameters:
Return type:

ndarray[float]

scrollstats.ridge_metrics.ridge_amplitude.s11_amps(maxes, mins)
Amplitude calculation if binary signal is capped with 1s on each end.

_ _ _

ex. |_| |_|

Amplitude for each ridge is calculated as the average of the differences between ridge max and the swale mins on each side. However, because there is a ridge at both ends, the first and last ridge only gets one amplitude measurement

Parameters:
Return type:

ndarray[float]