scrollstats.delineation package

class scrollstats.delineation.LineSmoother(lines, spacing, window)

Bases: object

Smooth and densify rough, manually drawn LineStrings.

Smoothing is accomplished with the use of a mean filter and densifying is accomplished with the use of a piecewise cubic spline. The GeoDataFrame provided must only contain LineStrings. MuliLineStrings or other geometries are not supported. The vertex count of any ridge cannot be lower than the window size for the mean filter

Values used for the Lower Brazos Ridges were:

window = 5 (vertices) spacing = 1 (meters)

Parameters:
calc_cubic_spline(line, spacing)

Fit a cubic spline function to a LineString then sample that function at the given spacing

Parameters:
Return type:

LineString

calc_dist(x, y)

Calc distance along the line

Parameters:
Return type:

list[float]

check_geometry_type()

Check that all geometries are of type LineString

Return type:

None

check_vertex_count()

Check that all ridges have at least as many vertices as the smoothing window is long

Return type:

None

execute()

Apply the mean filter and cubic spline to each line in the geodataframe. Return a new geodataframe with the smooth lines

Return type:

GeoDataFrame

meanfilt(line, w)

Use a mean filter to smooth the xy points of the line. This is done by passing a moving window with size w over the x and y coordinates separately and replacing the central value of the window with the mean value of the window. This particular method appends the first and last coord to the new line to account for erosion via convolution

Parameters:
Return type:

LineString

scrollstats.delineation.create_ridge_area_raster(dem_ds, geometry, classifier_funcs=(<function profile_curvature_classifier>, <function residual_topography_classifier>), denoiser_funcs=(<function binary_closing>, <function binary_opening>, <function remove_small_feats_w_flip>), no_data_value=None, **kwargs)

Main processing function to create the ridge area raster.

This function uses the provided classifier_funcs and denoiser_funcs to classify the ridge and swale areas within the input DEM.

Return type:

tuple[ndarray, ndarray, dict[Any, Any]]

Ridge Area Classification:

By default, scrollstats uses profile curvature (a measure of ridge convexity) and residual topography (a measure of ridge prominence) to classify ridge areas. Each classifier function is applied to the DEM, then the union of all the resulting binary arrays will be used for denoising. This means that the more classifier functions you use, the more conservative, but ideally more accurate, your ridge areas will be.

If the user desires, they can provide their own classifier functions so long as the functions follow the pattern below

classifier_func(ElevationArray2D, **kwargs) -> BinaryArray2D

See scrollstats/delineation/raster_classifiers.py for the DEFAULT_CLASSIFIERS list of functions and their definitions.

Clip Ridge and Swale Topography:

In order to avoid edge-effects from the classifier functions, the area corresponding to the ridge and swale topography will be clipped from a larger DEM. The nodata value for the input DEM will be used unless no_data_value is specified.

Image Denoising:

Once the ridge areas are classified within the DEM as a binary array (1=ridge, 0=swale), scrollstats uses a series of denoising algorithms to clean up the result. By default, scrollstats uses binary closing and binary opening operations to efficiently remove small objects from the binary image, then it uses another filter to remove of any remaining image object smaller than a certain size (measured in px). Each classifier function is applied to the binary array in sequence, meaning that the output of the first classifier function is the input of the second, and so on. Therefore, a different ordering of the same list of denoiser functions may yield a different result.

If the user desires, they can provide their own denoiser functions so long as the functions follow the pattern below

denoiser_func(BinarryArray2D, **kwargs) -> BinaryArray2D

See scrollstats/delineation/raster_denoisers.py for the DEFAULT_DENOISERS list of functions their definitions.

Keyword Arguments for Image Processing Functions:

Any additional arguments required by the classifier_funcs or denoier_funcs can be provided to this function as keyword arguments Any keyword arguments provided to this function will be passed to a given classifier or denoiser function if the provided keyword matches a keyword in the function’s signature.

type dem_ds:

DatasetReader

param dem_ds:

type geometry:

Polygon

param geometry:

type classifier_funcs:

tuple[Callable[..., ndarray], ...]

param classifier_funcs:

type denoiser_funcs:

tuple[Callable[..., ndarray], ...]

param denoiser_funcs:

type no_data_value:

Any | None

param no_data_value:

type kwargs:

Any

param kwargs:

scrollstats.delineation.create_ridge_area_raster_fs(dem_path, geometry_path, out_dir, bend_id_dict=None, **kwargs)

File system interface for create_ridge_area_raster

Parameters:
Return type:

tuple[Path, Path]

scrollstats.delineation.quadratic_profile_curvature(elevation, window=3, dx=1, weighting_exponent=0, constrained=False, coefficients_matrix=None, return_coefficients_matrix=False)

Calculate the profile curvature for a digital elevation model.

Parameters:

  • elevation (ndarray) – Elevation data.

  • window (float) – Window size. Default is 3.

  • weighting_expoenent (float) – Inverse-distance weighting for quadratic surface least squares. 0 = no weighting, 1 = linear decay, 2 = exponential decay. Default 0.

  • constrained (bool) – Whether quadratic surface is constrained through center cell. Default False.

  • dx (float) – Grid spacing. Default 1.

  • coefficients_matrix (ndarray | None) – An array of same dimensions as elevation M x N x 6 (coefficients), which can be reused for the various metric calculations, rather than needting to recalculate the coefficients each time.

  • return_coefficients_matrix (bool)

  • weighting_exponent (float)

Return type:

ndarray | tuple[ndarray, ndarray]

scrollstats.delineation.residual_topography(dem, w)

Using a moving window with side length w, subtract the focal mean from the central pixel value.

Parameters:
Return type:

ndarray

Submodules

scrollstats.delineation.array_types module

scrollstats.delineation.line_smoother module

class scrollstats.delineation.line_smoother.LineSmoother(lines, spacing, window)

Bases: object

Smooth and densify rough, manually drawn LineStrings.

Smoothing is accomplished with the use of a mean filter and densifying is accomplished with the use of a piecewise cubic spline. The GeoDataFrame provided must only contain LineStrings. MuliLineStrings or other geometries are not supported. The vertex count of any ridge cannot be lower than the window size for the mean filter

Values used for the Lower Brazos Ridges were:

window = 5 (vertices) spacing = 1 (meters)

Parameters:
calc_cubic_spline(line, spacing)

Fit a cubic spline function to a LineString then sample that function at the given spacing

Parameters:
Return type:

LineString

calc_dist(x, y)

Calc distance along the line

Parameters:
Return type:

list[float]

check_geometry_type()

Check that all geometries are of type LineString

Return type:

None

check_vertex_count()

Check that all ridges have at least as many vertices as the smoothing window is long

Return type:

None

execute()

Apply the mean filter and cubic spline to each line in the geodataframe. Return a new geodataframe with the smooth lines

Return type:

GeoDataFrame

meanfilt(line, w)

Use a mean filter to smooth the xy points of the line. This is done by passing a moving window with size w over the x and y coordinates separately and replacing the central value of the window with the mean value of the window. This particular method appends the first and last coord to the new line to account for erosion via convolution

Parameters:
Return type:

LineString

scrollstats.delineation.raster_classifiers module

Contains all functions responsible for classifying an input DEM into a binary array of ridges and swales (“classifier functions”). Ridge areas will correspond to a value of True or 1, swale areas will correspond to a value of False or 0

Classifier functions take an ElevationArray2D and any other kwargs as input and return a BinaryArray2D as output

classifier_func(ElevationArray2D, **kwargs) -> BinaryArray2D

scrollstats.delineation.raster_classifiers.parameter_quadratic_planform_curvature(_coeff)

Planform curvature from quadratic coefficients.

Parameters:

_coeff (Sequence[float]) – Set of coefficients to quadratic surface equation.

Return type:

float

scrollstats.delineation.raster_classifiers.parameter_quadratic_profile_curvature(_coeff)

Profile curvature from quadratic coefficients.

Parameters:

_coeff (Sequence[float]) – Set of coefficients to quadratic surface equation.

Return type:

float

scrollstats.delineation.raster_classifiers.profile_curvature_classifier(dem, window, dx, threshold=0)

Calculates the profile curvature within a moving window with side length window and pixel width dx. Returns a BooleanArray2D where True pixels are greater than threshold

Parameters:
Return type:

ndarray

scrollstats.delineation.raster_classifiers.quadratic_planform_curvature(elevation, window=3, weighting_exponent=1, constrained=True, dx=1, coefficients_matrix=None, return_coefficients_matrix=False)

Calculate the planform curvature for a digital elevation model.

Parameters:

  • elevation (ndarray) – Elevation data.

  • window (float) – Window size. Default is 3.

  • weighting_expoenent (float) – Inverse-distance weighting for quadratic surface least squares. 0 = no weighting, 1 = linear decay, 2 = exponential decay. Default 1.

  • constrained (bool) – Whether quadratic surface is constrained through center cell. Default True.

  • dx (float) – Grid spacing. Default 1.

  • coefficients_matrix (ndarray | None) – An array of same dimensions as elevation M x N x 6 (coefficients), which can be reused for the various metric calculations, rather than needting to recalculate the coefficients each time.

  • return_coefficients_matrix (bool)

  • weighting_exponent (float)

Return type:

ndarray | tuple[ndarray, ndarray]

scrollstats.delineation.raster_classifiers.quadratic_profile_curvature(elevation, window=3, dx=1, weighting_exponent=0, constrained=False, coefficients_matrix=None, return_coefficients_matrix=False)

Calculate the profile curvature for a digital elevation model.

Parameters:

  • elevation (ndarray) – Elevation data.

  • window (float) – Window size. Default is 3.

  • weighting_expoenent (float) – Inverse-distance weighting for quadratic surface least squares. 0 = no weighting, 1 = linear decay, 2 = exponential decay. Default 0.

  • constrained (bool) – Whether quadratic surface is constrained through center cell. Default False.

  • dx (float) – Grid spacing. Default 1.

  • coefficients_matrix (ndarray | None) – An array of same dimensions as elevation M x N x 6 (coefficients), which can be reused for the various metric calculations, rather than needting to recalculate the coefficients each time.

  • return_coefficients_matrix (bool)

  • weighting_exponent (float)

Return type:

ndarray | tuple[ndarray, ndarray]

scrollstats.delineation.raster_classifiers.residual_topography(dem, w)

Using a moving window with side length w, subtract the focal mean from the central pixel value.

Parameters:
Return type:

ndarray

scrollstats.delineation.raster_classifiers.residual_topography_classifier(dem, window, threshold=0)

Calculates the residual topography within a moving window with side length window. Returns a boolean array where True pixels are greater than threshold

Parameters:
Return type:

ndarray

scrollstats.delineation.raster_denoisers module

Contains all functions responsible for denoising an input binary array (“denoiser functions”) to more accurately represent the ridge and swale areas Ridge areas will correspond to a value of True or 1, swale areas will correspond to a value of False or 0

Denoiser functions take a BinaryArray2D and any other kwargs as input and return a BinaryArray2D as output

denoiser_func(BinaryArray2D, **kwargs) -> BinaryArray2D

scrollstats.delineation.raster_denoisers.binary_flipper(binary_array, func)
Parameters:
Return type:

ndarray

scrollstats.delineation.raster_denoisers.remove_small_feats(img, size)

Removes any patch/feature in a binary image that is below a certain size (measured in px)

Parameters:
Return type:

ndarray

scrollstats.delineation.raster_denoisers.remove_small_feats_w_flip(img, small_feats_size)

Apply remove_small_feats to the ridge areas, then flip the values in the binary array to apply remove_small_feats to the swale areas

Parameters:
Return type:

ndarray

scrollstats.delineation.ridge_area_raster module

scrollstats.delineation.ridge_area_raster.clip_raster(ds, geometry, array=None, no_data=None)
Parameters:
Return type:

tuple[ndarray, ndarray, dict[Any, Any]]

scrollstats.delineation.ridge_area_raster.create_ridge_area_raster(dem_ds, geometry, classifier_funcs=(<function profile_curvature_classifier>, <function residual_topography_classifier>), denoiser_funcs=(<function binary_closing>, <function binary_opening>, <function remove_small_feats_w_flip>), no_data_value=None, **kwargs)

Main processing function to create the ridge area raster.

This function uses the provided classifier_funcs and denoiser_funcs to classify the ridge and swale areas within the input DEM.

Return type:

tuple[ndarray, ndarray, dict[Any, Any]]

Ridge Area Classification:

By default, scrollstats uses profile curvature (a measure of ridge convexity) and residual topography (a measure of ridge prominence) to classify ridge areas. Each classifier function is applied to the DEM, then the union of all the resulting binary arrays will be used for denoising. This means that the more classifier functions you use, the more conservative, but ideally more accurate, your ridge areas will be.

If the user desires, they can provide their own classifier functions so long as the functions follow the pattern below

classifier_func(ElevationArray2D, **kwargs) -> BinaryArray2D

See scrollstats/delineation/raster_classifiers.py for the DEFAULT_CLASSIFIERS list of functions and their definitions.

Clip Ridge and Swale Topography:

In order to avoid edge-effects from the classifier functions, the area corresponding to the ridge and swale topography will be clipped from a larger DEM. The nodata value for the input DEM will be used unless no_data_value is specified.

Image Denoising:

Once the ridge areas are classified within the DEM as a binary array (1=ridge, 0=swale), scrollstats uses a series of denoising algorithms to clean up the result. By default, scrollstats uses binary closing and binary opening operations to efficiently remove small objects from the binary image, then it uses another filter to remove of any remaining image object smaller than a certain size (measured in px). Each classifier function is applied to the binary array in sequence, meaning that the output of the first classifier function is the input of the second, and so on. Therefore, a different ordering of the same list of denoiser functions may yield a different result.

If the user desires, they can provide their own denoiser functions so long as the functions follow the pattern below

denoiser_func(BinarryArray2D, **kwargs) -> BinaryArray2D

See scrollstats/delineation/raster_denoisers.py for the DEFAULT_DENOISERS list of functions their definitions.

Keyword Arguments for Image Processing Functions:

Any additional arguments required by the classifier_funcs or denoier_funcs can be provided to this function as keyword arguments Any keyword arguments provided to this function will be passed to a given classifier or denoiser function if the provided keyword matches a keyword in the function’s signature.

type dem_ds:

DatasetReader

param dem_ds:

type geometry:

Polygon

param geometry:

type classifier_funcs:

tuple[Callable[..., ndarray], ...]

param classifier_funcs:

type denoiser_funcs:

tuple[Callable[..., ndarray], ...]

param denoiser_funcs:

type no_data_value:

Any | None

param no_data_value:

type kwargs:

Any

param kwargs:

scrollstats.delineation.ridge_area_raster.create_ridge_area_raster_fs(dem_path, geometry_path, out_dir, bend_id_dict=None, **kwargs)

File system interface for create_ridge_area_raster

Parameters:
Return type:

tuple[Path, Path]

scrollstats.delineation.ridge_area_raster.partial_from_kwargs(func, **kwargs)

Create a partial function from all of the kwargs that are found in the function’s signature

Parameters:
Return type:

Callable[..., Any]