scrollstats.transecting package

class scrollstats.transecting.MultiTransect(coord_list, centerline, ridges, shoot_distance, search_distance, dev_from_90, user_direction=None, verbose=1)

Bases: object

Creates multiple instances of H74Transect from a given centerline, ridge dataset, and other parameters.

The create_transects method is used to generate a GeoDataframe of transects. The return_all_geometries method returns the transects from create_transects as well as other intermediate geometries used in the creation of the transects. Useful for deubgging and plotting.

This class is used in the create_transects convenience function in the public API.

Parameters:

  • coord_list (list[Point]) – List of starting coordinates for each transect.

  • centerline (GeoDataFrame) – GeoDataFrame containing the centerline geometry.

  • ridges (GeoDataFrame) – GeoDataFrame containing the ridge geometries.

  • shoot_distance (float) – Distance for each shot.

  • search_distance (float) – Buffer distance for the search area on r2.

  • dev_from_90 (float) – Allowed deviation from 90 degrees for p2 shots.

  • user_direction (int | None) – User-specified initial shot direction from centerline.

  • verbose (int) – Verbosity level for user feedback

coord_list

List of starting coordinates for each transect.

Type:

list of Point

centerline

GeoDataFrame containing the centerline geometry.

Type:

GeoDataFrame

ridges

GeoDataFrame containing the ridge geometries.

Type:

GeoDataFrame

shoot_distance

Distance for each shot.

Type:

float

search_distance

Buffer distance for the search area on r2.

Type:

float

dev_from_90

Allowed deviation from 90 degrees for p2 shots.

Type:

float

user_direction

User-specified initial shot direction from centerline.

Type:

int or None

verbose

Verbosity level for user feedback

Type:

int

crs

Coordinate reference system for all geometries. Read from centerline

Type:

CRS

transect_list

List of generated transects.

Type:

list of H74Transect

transect_df

GeoDataFrame containing transect geometries.

Type:

GeoDataFrame

point_df

GeoDataFrame containing point geometries used in transect creation.

Type:

GeoDataFrame

search_area_df

GeoDataFrame containing search area polygons for p2 points.

Type:

GeoDataFrame

ridge_clip_df

GeoDataFrame containing ridge geometries clipped with search area polygons.

Type:

GeoDataFrame

create_point_df()

Creates a GeoDataFrame of all points used to create transects.

Parameters:

None

Returns:

GeoDataFrame containing points from all transects.

Return type:

GeoDataFrame

create_ridge_clip_df()

Creates a GeoDataFrame of all ridge sections searched to create transects.

Parameters:

None

Returns:

GeoDataFrame containing ridge sections.

Return type:

GeoDataFrame

create_search_area_df()

Creates a GeoDataFrame of all search areas used to create transects.

Parameters:

None

Returns:

GeoDataFrame containing search areas from all transects.

Return type:

GeoDataFrame

create_transect_df()

Creates a GeoDataFrame of transects from all transects which successfully left the centerline.

Parameters:

None

Returns:

GeoDataFrame containing all successful transects.

Return type:

GeoDataFrame

create_transect_list()

Creates a set of transects and aux geometries for a bend.

Parameters:

None

Returns:

List of generated transects.

Return type:

list[H74Transect]

return_all_geometries()

Return all geometries created for a set of transects

Parameters:

None

Returns:

Tuple containing the transect, point, search area, and ridge clip GeoDataFrames.

Return type:

tuple[GeoDataFrame, GeoDataFrame, GeoDataFrame, GeoDataFrame]

scrollstats.transecting.create_transects(centerline, ridges, step, shoot_distance, search_distance, dev_from_90)

Convenience function to create a series of transects from a given centerline, set of ridges, and the necessary parameters.

Transects are created at the step provided by the user (ex. every nth vertex along the centerline). Centerline is assumed to have a vertex spacing of ~1m.

Parameters:

  • centerline (GeoDataFrame) – GeoDataFrame containing the centerline geometry.

  • ridges (GeoDataFrame) – GeoDataFrame containing the ridge geometries.

  • step (int) – Number of centerline vertices between each transect.

  • shoot_distance (float) – How far each point will shoot from the origin in a given direction.

  • search_distance (float) – Buffer distance for the search area on r2.

  • dev_from_90 (float) – Allowed deviation from 90 degrees for p2 shots.

Returns:

GeoDataFrame containing the transects generated.

Return type:

GeoDataFrame

Submodules

scrollstats.transecting.transect module

class scrollstats.transecting.transect.H74Transect(origin, point_id=None)

Bases: object

Stores information about a transect created using Hickin 1974 geometric methods.

Parameters:

  • origin (Point) – The starting point of the transect.

  • point_id (str | None) – Identifier for the transect point.

origin

Starting point of the transect.

Type:

Point

point_id

Identifier for the transect point.

Type:

str or None

coord_list

List of coordinates along the transect.

Type:

list of Point

n1_shoot_list

List of shot points for n1.

Type:

list of Point

n1_coord_list

List of n1 intersection coordinates.

Type:

list of Point

n2_coord_list

List of n2 intersection coordinates.

Type:

list of Point

vr_shoot_list

List of vertical resultant shot points.

Type:

list of Point

p2_coord_list

List of p2 intersection coordinates.

Type:

list of Point

linestring

LineString representing the transect.

Type:

LineString

search_area_list

List of search area polygons.

Type:

list of Polygon

ridge_clip_list

List of clipped ridge lines.

Type:

list of LineString

termination_point

Point where transect terminated.

Type:

None

termination_reason

Reason for transect termination.

Type:

str or None

distance_along_cl

Distance along centerline at origin.

Type:

float or None

class scrollstats.transecting.transect.H74TransectConstructor(origin, transect_id, centerline, ridges, shoot_distance, search_distance, dev_from_90, user_direction=None, verbose=1)

Bases: object

Takes an H74Transect instance and builds the transect out with a given set of ridges and geometric parameters.

Each hickin function in the class will return a shapely object and avoid changing state variables within the class

Parameters:

  • origin (Point) – Starting point of the transect.

  • transect_id (str) – Identifier for the transect.

  • centerline (LineString) – Centerline geometry.

  • ridges (MultiLineString) – Ridge geometries.

  • shoot_distance (float) – Distance for each shot.

  • search_distance (float) – Search buffer distance.

  • dev_from_90 (float) – Allowed deviation from 90 degrees.

  • user_direction (int | None) – User-specified shot direction.

  • verbose (int) – Verbosity level.

transect

Transect instance being constructed.

Type:

H74Transect

origin

Starting point.

Type:

Point

centerline

Centerline geometry.

Type:

LineString

user_direction

User-specified direction.

Type:

int or None

initial_direction

Initial calculated direction.

Type:

int or None

initial_alpha

Initial alpha value.

Type:

float or None

ridges

Ridge geometries.

Type:

MultiLineString

ridges_centroid

Centroid of ridges.

Type:

Point

p1

Current point.

Type:

Point

p2

Next point.

Type:

Point

r1

Current ridge.

Type:

LineString

r2

Next ridge.

Type:

LineString

n1

n1 intersection point.

Type:

Point

n2

n2 intersection point.

Type:

Point

walk_state

Transect walking state.

Type:

bool

iteration

Iteration counter.

Type:

int

verbose

Verbosity level.

Type:

int

shoot_distance

Shot distance.

Type:

float

search_distance

Search buffer distance.

Type:

float

dev_from_90

Allowed deviation from 90 degrees.

Type:

float

max_iterations

Maximum allowed iterations.

Type:

int

calc_dist_along_cl()

Calculates the distance along the centerline at the transect origin.

Return type:

None

calc_initial_direction(origin, alpha, ridges)

Determines the direction of the initial shot from the centerline.

This is done by evaluating which shot direction (+ or - 90°) intersects the ridges.

Parameters:
Returns:

Initial shot direction (+1, -1, or 0).

Return type:

int

dest90(p1, r2, dev_from_90)

Calculates a point on r2 from which a line that is perpendicular to r2 AND intersects p1 may be drawn.

This is done by creating an angle between 3 points: (p1, ridge point, a point along the line tangent to the ridge at the ridge point) These angles are collected for a series of ridge points within a certain distance to the src90 point The ridge point with the angle closest to 90° is returned as point p2

Parameters:

  • p1 (Point) – Current point.

  • r2 (LineString) – The ridge line on which to find the perpendicular point.

  • dev_from_90 (float) – Allowed deviation from 90 degrees.

Returns:

The point on r2 from which a perpendicular line intersects p1.

Return type:

Point

eval_user_direction()

Overrides the calculated shot direction value if direction is specified by the user.

Return type:

None

find_closest_ridge(line, ridges)

Takes a line and ridges as input and returns a snippet of a single ridge that the line intersects. Depending on the size of the search radius, line may still intersect ridge snippet at more than one point Initial intersection can have many geometry types. This function accounts for: empty geometry, Point, MultiPoint, GeometryCollection

Parameters:
Returns:

Snippet of the closest intersected ridge.

Return type:

LineString

result_coord(p1, src90, dest90, r2)

Takes the coordinates of two points and their shared p1 to calculate the resultant vector.

Parameters:

  • p1 (Point) – Current point.

  • src90 (Point) – The point on r2 that lies on a line perpendicular from r1 at point p1.

  • dest90 (Point) – The point on r2 from which a perpendicular line intersects p1.

  • r2 (LineString) – The ridge line on which src90 and dest90 lie.

Returns:

The intersection point between the vertical resultant and r2.

Return type:

Point

shoot_point(p1, r1, dist)

Calculates the point perpendicular to r1 at point p1, dist away from p1. Used for the first shot from the centerline into the ridge field.

Parameters:

  • p1 (Point) – Starting point.

  • r1 (LineString) – The line from which to shoot.

  • dist (float) – Shoot distance from p1.

Returns:

The point perpendicular to r1 at point p1.

Return type:

Point

shoot_point_rg(p0, p1, r1, dist)

Calculates the point perpendicular to r1 at point p1, dist away from p1. Used when transect is moving from ridge to ridge. add_sub_90() is used to determine whether to add or subtract 90° from heading (alpha) value.

Parameters:

  • p0 (Point) – Previous point. Needed to calculate direction of shot (+/-90°).

  • p1 (Point) – Current point.

  • r1 (LineString) – The line from which to shoot.

  • dist (float) – Shoot distance from p1.

Returns:

The point perpendicular to r1 at point p1.

Return type:

Point

src90(shot, ridge)

Calculates the intersection between p1->shot_point and ridge r1 to define point p1.

Parameters:

  • shot (LineString) – The line from p1 to the shot point.

  • ridge (LineString) – The ridge line to intersect with the shot.

Returns:

The intersection point between shot and ridge.

Return type:

Point

walk_transect()

Iteratively walk the transect up the ridge field. Objects self.r1 and self.p1 are set in __init__ as the centerline and point on the centerline, respectively.

Parameters:

None

Returns:

The transect object containing all generated coordinates and geometries.

Return type:

H74Transect

class scrollstats.transecting.transect.MultiTransect(coord_list, centerline, ridges, shoot_distance, search_distance, dev_from_90, user_direction=None, verbose=1)

Bases: object

Creates multiple instances of H74Transect from a given centerline, ridge dataset, and other parameters.

The create_transects method is used to generate a GeoDataframe of transects. The return_all_geometries method returns the transects from create_transects as well as other intermediate geometries used in the creation of the transects. Useful for deubgging and plotting.

This class is used in the create_transects convenience function in the public API.

Parameters:

  • coord_list (list[Point]) – List of starting coordinates for each transect.

  • centerline (GeoDataFrame) – GeoDataFrame containing the centerline geometry.

  • ridges (GeoDataFrame) – GeoDataFrame containing the ridge geometries.

  • shoot_distance (float) – Distance for each shot.

  • search_distance (float) – Buffer distance for the search area on r2.

  • dev_from_90 (float) – Allowed deviation from 90 degrees for p2 shots.

  • user_direction (int | None) – User-specified initial shot direction from centerline.

  • verbose (int) – Verbosity level for user feedback

coord_list

List of starting coordinates for each transect.

Type:

list of Point

centerline

GeoDataFrame containing the centerline geometry.

Type:

GeoDataFrame

ridges

GeoDataFrame containing the ridge geometries.

Type:

GeoDataFrame

shoot_distance

Distance for each shot.

Type:

float

search_distance

Buffer distance for the search area on r2.

Type:

float

dev_from_90

Allowed deviation from 90 degrees for p2 shots.

Type:

float

user_direction

User-specified initial shot direction from centerline.

Type:

int or None

verbose

Verbosity level for user feedback

Type:

int

crs

Coordinate reference system for all geometries. Read from centerline

Type:

CRS

transect_list

List of generated transects.

Type:

list of H74Transect

transect_df

GeoDataFrame containing transect geometries.

Type:

GeoDataFrame

point_df

GeoDataFrame containing point geometries used in transect creation.

Type:

GeoDataFrame

search_area_df

GeoDataFrame containing search area polygons for p2 points.

Type:

GeoDataFrame

ridge_clip_df

GeoDataFrame containing ridge geometries clipped with search area polygons.

Type:

GeoDataFrame

create_point_df()

Creates a GeoDataFrame of all points used to create transects.

Parameters:

None

Returns:

GeoDataFrame containing points from all transects.

Return type:

GeoDataFrame

create_ridge_clip_df()

Creates a GeoDataFrame of all ridge sections searched to create transects.

Parameters:

None

Returns:

GeoDataFrame containing ridge sections.

Return type:

GeoDataFrame

create_search_area_df()

Creates a GeoDataFrame of all search areas used to create transects.

Parameters:

None

Returns:

GeoDataFrame containing search areas from all transects.

Return type:

GeoDataFrame

create_transect_df()

Creates a GeoDataFrame of transects from all transects which successfully left the centerline.

Parameters:

None

Returns:

GeoDataFrame containing all successful transects.

Return type:

GeoDataFrame

create_transect_list()

Creates a set of transects and aux geometries for a bend.

Parameters:

None

Returns:

List of generated transects.

Return type:

list[H74Transect]

return_all_geometries()

Return all geometries created for a set of transects

Parameters:

None

Returns:

Tuple containing the transect, point, search area, and ridge clip GeoDataFrames.

Return type:

tuple[GeoDataFrame, GeoDataFrame, GeoDataFrame, GeoDataFrame]

scrollstats.transecting.transect.add_sub_90(a, b, alpha, length=100)

This function determines which direction to shoot a new transect (+ or - 90°) The proper line should have the largest of the interior angles formed by the incoming transect and new shoot being formed This function returns the coordinate representing the end point of the proper line

Parameters:

  • a (Point) – The previous point in the transect (p0).

  • b (Point) – The current point in the transect (p1).

  • alpha (float) – The angle of the current transect at b.

  • length (float) – The length of the new shoot line, by default 100.

Returns:

The coordinates the point in the correct direction (largest interior angle).

Return type:

ndarray[float]

scrollstats.transecting.transect.calc_dist(p1, p2)

Calculates the distance element-wise between two arrays of points

Parameters:
Returns:

Array of distances between corresponding points in p1 and p2.

Return type:

ndarray[float]

scrollstats.transecting.transect.calc_dist_along_line(line)

Calculate an array of distance along a given line

Parameters:

line (LineString) – The line for which to calculate distance along.

Returns:

Array of distance values for each vertex.

Return type:

ndarray[float]

scrollstats.transecting.transect.calc_dxdy(angle, length=100)

Calculates the delta x and y given an angle and a length

Parameters:

  • angle (ndarray[float]) – Angle(s) in radians.

  • length (float) – Length of the vector, by default 100.

Returns:

A 2D array where the first row contains delta x values and the second row contains delta y values.

Return type:

ndarray[float]

scrollstats.transecting.transect.create_transects(centerline, ridges, step, shoot_distance, search_distance, dev_from_90)

Convenience function to create a series of transects from a given centerline, set of ridges, and the necessary parameters.

Transects are created at the step provided by the user (ex. every nth vertex along the centerline). Centerline is assumed to have a vertex spacing of ~1m.

Parameters:

  • centerline (GeoDataFrame) – GeoDataFrame containing the centerline geometry.

  • ridges (GeoDataFrame) – GeoDataFrame containing the ridge geometries.

  • step (int) – Number of centerline vertices between each transect.

  • shoot_distance (float) – How far each point will shoot from the origin in a given direction.

  • search_distance (float) – Buffer distance for the search area on r2.

  • dev_from_90 (float) – Allowed deviation from 90 degrees for p2 shots.

Returns:

GeoDataFrame containing the transects generated.

Return type:

GeoDataFrame

scrollstats.transecting.transect.curvature(line)

Calculates curvature and angle (alpha) along a given line.

Parameters:

line (LineString) – The line for which to calculate curvature and angle.

Returns:

A tuple containing two numpy arrays: curvature and alpha

Return type:

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

scrollstats.transecting.transect.direction_alpha_at_point(point, line)

Calculates both the shot direction and alpha value at the coordinate of line closest to point

Parameters:

  • point (Point) – The point at which to evaluate direction and alpha.

  • line (LineString) – The line from which to evaluate direction and alpha.

Returns:

A tuple of the shot direction (+1, -1, or 0) and the angle (in radians) at the closest point on the line.

Return type:

tuple[int, float]

scrollstats.transecting.transect.find_closest_idx(point, line)

Loops through the coordinates of line and returns the idx of the coord closest to point

Parameters:
Returns:

The index of the coordinate in line that is closest to point.

Return type:

int

scrollstats.transecting.transect.law_of_cos(a, b, c)

This function uses law of cosines to calculate the interior angle formed by two connected lines Traveling down the line, vertices are a, b, c (a=beg, b=mid, c=end) Distances between vertices are represented with ‘_’ ex. a_b is the distance between a and b

Parameters:
Returns:

Array of interior angles at point b formed by lines ab and bc.

Return type:

ndarray[float]

scrollstats.transecting.transect.vert_res(p0, p1, p2)

Calculates the vertical resultant of the two vectors (LineStrings) p0->p1 and p0->p2

Parameters:

  • p0 (Point) – The shared starting point of the two vectors.

  • p1 (Point) – The end point of the first vector.

  • p2 (Point) – The end point of the second vector.

Returns:

The coordinates of the vertical resultant point.

Return type:

ndarray[float]