linref.events

linref.events.base

linref.events.relate

class linref.events.relate.EventsRelation(left: EventsData, right: EventsData, left_df: DataFrame | None = None, right_df: DataFrame | None = None, cache: bool = True)

Bases: object

property left: EventsData

The left events data object.

property right: EventsData

The right events data object.

property left_df: DataFrame | None

The dataframe associated with the left events data.

property right_df: DataFrame | None

The dataframe associated with the right events data.

property cache: bool

Whether computed relationship data is cached for reuse.

property shape: tuple

Shape of the relationship matrix as (left_events, right_events).

property equal_groups_data: csr_matrix | None

Cached equal-groups boolean matrix, or None if not yet computed.

property overlay_data: csr_matrix | None

Cached overlay matrix, or None if not yet computed.

property intersect_data: csr_matrix | None

Cached intersection matrix, or None if not yet computed.

property T: EventsRelation

Return a new EventsRelation object with the left and right events, dataframes, and cached data transposed.

cache_memory_usage(unit: str = 'MB') → float

Get the memory usage of the cached data.

Parameters:

unit ({'bytes', 'KB', 'MB', 'GB'}, default 'MB') – The unit to return the memory usage in. Must be one of: - ‘bytes’ : Bytes - ‘KB’ : Kilobytes - ‘MB’ : Megabytes - ‘GB’ : Gigabytes

copy(deep: bool = False) → EventsRelation

Create an exact copy of the object instance.

Parameters:

deep (bool, default False) – Whether the created copy should be a deep copy.

reset_cache() → None

Reset all cached data from computations on the relationships between the left and right events, including equal groups, intersections, and overlays.

reset_selector() → None

Reset the selector used to select data from either the left or right dataframe during aggregation operations.

equal_groups(chunksize: int = 1000, grouped: bool = True) → csr_matrix

Compute a boolean matrix indicating whether left and right events belong to the same group.

Parameters:

• chunksize (int or None, default 1000) – The maximum number of events to process in a single chunk. Input chunksize will affect the memory usage and performance of the function. This does not affect actual results, only computation.

• grouped (bool, default True) – Whether to process the overlay operation for each group separately. This will affect the memory usage and performance of the function. This does not affect actual results, only computation.

Returns:

arr – The sparse boolean matrix of group equality results. The shape of the matrix will be (m, n), where m is the number of events in the left dataframe and n is the number of events in the right dataframe.

Return type:

scipy.sparse.csr_matrix

overlay(normalize: bool = True, norm_by: str = 'right', profile=None, chunksize: int = 1000, grouped: bool = True) → csr_matrix

Compute the overlay of the left and right events.

Parameters:

• normalize (bool, default True) – Whether overlapping lengths should be normalized to give a proportional result with a float value between 0 and 1.

• norm_by (str, default 'right') –

  How overlapping lengths should be normalized. Only applied if normalize is True.

  • ’right’ : Normalize by the length of the right events.

  • ’left’ : Normalize by the length of the left events.

• profile (str, EventProfile, or None, default None) –

  An event profile defining how value is distributed along the event’s length. When provided, overlay weights reflect the proportion of the event’s profiled value that is overlapped rather than simple length proportion.

  • None : No profiling (default, current behavior).

  • str : Name of a built-in profile (‘uniform’, ‘triangular’, ‘parabolic’, ‘trapezoidal’).

  • EventProfile : A profile instance for custom parameterization.

• chunksize (int or None, default 1000) – The maximum number of events to process in a single chunk. Input chunksize will affect the memory usage and performance of the function. This does not affect actual results, only computation.

• grouped (bool, default True) – Whether to process the overlay operation for each group separately. This will affect the memory usage and performance of the function. This does not affect actual results, only computation.

Returns:

arr – The sparse matrix of overlay results. The shape of the matrix will be (m, n), where m is the number of events in the left dataframe and n is the number of events in the right dataframe.

Return type:

scipy.sparse.csr_matrix

intersect(enforce_edges: bool = True, chunksize: int = 1000, grouped: bool = True) → csr_matrix

Compute the intersection of the left and right events.

Parameters:

• enforce_edges (bool, default True) – Whether to enforce edge cases when computing intersections. If True, edge cases will be tested for intersections. Ignored for point to point intersections.

• chunksize (int or None, default 1000) – The maximum number of events to process in a single chunk. Input chunksize will affect the memory usage and performance of the function. This does not affect actual results, only computation.

• grouped (bool, default True) – Whether to process the overlay operation for each group separately. This will affect the memory usage and performance of the function. This does not affect actual results, only computation.

Returns:

arr – The sparse matrix of intersection results. The shape of the matrix will be (m, n), where m is the number of events in the left dataframe and n is the number of events in the right dataframe.

Return type:

scipy.sparse.csr_matrix

count(**kwargs)

single(**kwargs)

first(data: ndarray | Series | DataFrame | None = None, axis: int = 1, squeeze: bool = True, **kwargs) → ndarray

Aggregate all input data values along the specified axis of the events relation against the other axis, returning the first value for intersecting events.

Parameters:

• data (array-like or None, default None) – The data to aggregate along the axis of the events relationship. Data must have a shape of (n,) or (n, x) where n is the number of events in the left dataframe if axis=0 or the number of events in the right dataframe if axis=1. This will result in an output shape of (m,) or (m, x), respectively, where m is the number of events in the opposite dataframe.

• axis (int, default 1) – The axis along which to aggregate the events relationship. - 0 : Aggregate left events onto the right events index. - 1 : Aggregate right events onto the left events index.

• squeeze (bool, default True) – Whether to squeeze the output array to a 1D array if possible.

Returns:

arr – The aggregated data array. The shape of the array will be (m,) where m is the number of events in the right dataframe if axis=0 or the number of events in the left dataframe if axis=1.

Return type:

numpy.ndarray

last(data: ndarray | Series | DataFrame | None = None, axis: int = 1, squeeze: bool = True, **kwargs) → ndarray

Aggregate all input data values along the specified axis of the events relation against the other axis, returning the last value for intersecting events.

Parameters:

• data (array-like or None, default None) – The data to aggregate along the axis of the events relationship. Data must have a shape of (n,) or (n, x) where n is the number of events in the left dataframe if axis=0 or the number of events in the right dataframe if axis=1. This will result in an output shape of (m,) or (m, x), respectively, where m is the number of events in the opposite dataframe.

• axis (int, default 1) – The axis along which to aggregate the events relationship. - 0 : Aggregate left events onto the right events index. - 1 : Aggregate right events onto the left events index.

• squeeze (bool, default True) – Whether to squeeze the output array to a 1D array if possible.

Returns:

arr – The aggregated data array. The shape of the array will be (m,) where m is the number of events in the right dataframe if axis=0 or the number of events in the left dataframe if axis=1.

Return type:

numpy.ndarray

list(**kwargs)

set(data: ndarray | Series | DataFrame | None = None, axis: int = 1, squeeze: bool = True, **kwargs) → ndarray

Aggregate all input data values along the specified axis of the events relation against the other axis, returning a set of all values for intersecting events.

Parameters:

• data (array-like or None, default None) – The data to aggregate along the axis of the events relationship. Data must have a shape of (n,) where n is the number of events in the left dataframe if axis=0 or the number of events in the right dataframe if axis=1. This will result in an output shape of (m,), where m is the number of events in the opposite dataframe.

• axis (int, default 1) – The axis along which to aggregate the events relationship. - 0 : Aggregate left events onto the right events index. - 1 : Aggregate right events onto the left events index.

• squeeze (bool, default True) – Whether to squeeze the output array to a 1D array if possible.

Returns:

arr – The aggregated data array. The shape of the array will be (m,) or (m, x), where m is the number of events in the right dataframe if axis=0 or the number of events in the left dataframe if axis=1, and x is the number of columns in the input data array. If the squeeze parameter is True, the output array will be squeezed to a 1D array if possible.

Return type:

numpy.ndarray

value_counts(**kwargs)

sum(**kwargs)

mean(**kwargs)

mode(**kwargs)

distribute(**kwargs)

interpolate(**kwargs)

cut(**kwargs)

line_merge_m(**kwargs)

connected_components(**kwargs) → tuple[int, ndarray]

Find connected components in the intersection graph of the events relationship. Events that intersect (directly or transitively) are assigned to the same component.

Parameters:

**kwargs – Additional keyword arguments to pass to the intersection method if it has not been previously computed and cached.

Returns:

• n_components (int) – The number of connected components found.

• labels (np.ndarray) – An array of component labels (0-based integers) for each event in the left events collection.

linref.events.relate.overlay(left, right, *args, **kwargs)

linref.events.relate.equal_groups(left, right, *args, **kwargs)

linref.events.relate.intersect_point_point(left, right, *args, **kwargs)

linref.events.relate.intersect_point_linear(left, right, *args, **kwargs)

linref.events.relate.intersect_linear_linear(left, right, *args, **kwargs)

class linref.events.relate.DecayFunction(decay_size: float)

Bases: object

Base class for decay functions used in distribution. To define a custom decay function, subclass this class and implement the decay method. All decay functions must take a distance (float) as input and return a decay weight (float) between 0 and 1.

property decay_size: float

property decay_cap: float

decay(distance: float) → float

Compute the decay weight for a given distance.

Parameters:

distance (float) – The distance from the target event.

Returns:

weight – The decay weight between 0 and 1.

Return type:

float

class linref.events.relate.LinearDecay(decay_size: float)

Bases: DecayFunction

Linear decay function.

decay(distance: float) → float

Compute the decay weight for a given distance.

Parameters:

distance (float) – The distance from the target event.

Returns:

weight – The decay weight between 0 and 1.

Return type:

float

class linref.events.relate.ExponentialDecay(decay_size: float, rate: float = 1.0)

Bases: DecayFunction

Exponential decay function.

decay(distance: float) → float

Compute the decay weight for a given distance.

Parameters:

distance (float) – The distance from the target event.

Returns:

weight – The decay weight between 0 and 1.

Return type:

float

property rate: float

class linref.events.relate.GaussianDecay(decay_size: float)

Bases: DecayFunction

Gaussian decay function, producing values between 1.0 at distance 0 and approximately 0.01 at distance equal to decay_size, following a normal distribution curve.

decay(distance: float) → float

Compute the decay weight for a given distance.

Parameters:

distance (float) – The distance from the target event.

Returns:

weight – The decay weight between 0 and 1.

Return type:

float

class linref.events.relate.FlatDecay(decay_size: float)

Bases: DecayFunction

Flat decay function.

decay(distance: float) → float

Compute the decay weight for a given distance.

Parameters:

distance (float) – The distance from the target event.

Returns:

weight – The decay weight between 0 and 1.

Return type:

float

linref.geometry

class linref.geometry.LineStringM(geom, m=None)

Bases: object

property geom

property m

property beg_m

Return the beginning M value of the LineStringM object.

property end_m

Return the ending M value of the LineStringM object.

property coords

Return the coordinates of the LineString as an array, interwoven with the M values if defined. Similar to shapely.get_coordinates, but with M values appended.

property chord_lengths

Return the chord lengths for each segment in the LineString.

property chord_proportions

Return the chord lengths for each segment in the LineString as a proportion of the total length of the LineString.

property wkt

Return the WKT representation of the object’s LineString, interwoven with the M values.

property has_m

classmethod from_coords(coords)

Create a LineStringM object from an array of coordinates with shape (n, 2) or (n, 3), where n is the number of vertices. If shape (n, 3), the third column is interpreted as the M values.

classmethod from_shapely(geom, m=None)

Create a LineStringM object from a shapely LineString object which may or may not have M values.

Parameters:

• geom (shapely.LineString) – The shapely LineString object to convert.

• m (array-like, optional) – The M values associated with the LineString, if any. If the input shapely LineString already has M values, this parameter is ignored.

classmethod from_wkt(wkt)

Create a LineStringM object from a WKT representation.

Parameters:

wkt (str) – The WKT representation of the LineStringM.

copy(deep=False)

Create an exact copy of the object instance.

Parameters:

deep (bool, default False) – Whether the created copy should be a deep copy.

set_m(array=None, beg=None, end=None, inplace=True)

Set the M values of the LineStringM object to the specified values using an array containing values for each vertex or using begin and end values, imputing the M values for each vertex based on the proportional length along the LineString.

Parameters:

• m (array-like) – The M values to set for each vertex.

• inplace (bool, default True) – Whether to modify the object in place or return a new object.

set_m_from_array(m, inplace=True)

Set the M values of the LineStringM object to the specified values.

Parameters:

• m (array-like) – The M values to set for each vertex.

• inplace (bool, default True) – Whether to modify the object in place or return a new object.

set_m_from_bounds(beg=0, end=None, inplace=True)

Set the M values of the LineStringM object to a range from beg to end, imputing the M values for each vertex based on the proportional length along the LineString.

Parameters:

• beg (float, default 0) – The starting M value.

• end (float, default None) – The ending M value. If None, the ending M value will be set to be beg plus the length of the LineString.

• inplace (bool, default True) – Whether to modify the object in place or return a new object.

m_to_distance(m, snap=False, _skip_validation=False)

Return the distance along the LineString for the specified M value.

Alias of m_to_distance for single-geometry calls.

Parameters:

• m (float) – The M value to find the distance for.

• snap (bool, default False) – Whether to snap the M value to the nearest vertex if it is out of range. If False, a ValueError will be raised if the M value is out of range.

• _skip_validation (bool, default False) – Internal parameter to skip validation when already performed by caller. Not intended for public use.

m_to_norm_distance(m, snap=False)

Return the normalized distance along the LineString for the specified M value.

Parameters:

• m (float) – The M value to find the normalized distance for.

• snap (bool, default False) – Whether to snap the M value to the nearest vertex if it is out of range. If False, a ValueError will be raised if the M value is out of range.

distance_to_m(distance, normalized=False, snap=False, _skip_validation=False)

Return the M value for the specified distance along the LineString.

Alias of distance_to_m for single-geometry calls.

Parameters:

• distance (float) – The distance along the geometry to find the M value for.

• normalized (bool, default False) – Whether the distance is normalized (0-1) or absolute.

• snap (bool, default False) – Whether to snap the distance to the nearest vertex if it is out of range. If False, a ValueError will be raised if the distance is out of range.

• _skip_validation (bool, default False) – Internal parameter to skip validation when already performed by caller. Not intended for public use.

project(point, normalized=False, m=False)

Return the distance along the linear geometry to the nearest point on the geometry from the specified point.

Alias of line_locate_point_m for single-geometry calls.

Parameters:

• point (shapely.Point) – The point to project onto the geometry.

• normalized (bool, default False) – Whether to return the distance as normalized (0-1) or absolute.

• m (bool, default False) – Whether to return the distance as an M value.

interpolate(distance, normalized=False, m=False, snap=False)

Return a point at the specified distance along the linear geometry.

Alias of line_interpolate_point_m for single-geometry calls.

Parameters:

• distance (float) – The distance along the geometry to interpolate.

• normalized (bool, default False) – Whether the distance is normalized (0-1) or absolute.

• m (bool, default False) – Whether the distance should be interpreted as an M value.

• snap (bool, default False) – Whether to snap the distance to the nearest vertex if it is out of range. If False, a ValueError will be raised if the distance is out of range.

reverse(inplace: bool = False)

Reverse the direction of the geometry and its M values.

Parameters:

inplace (bool, default False) – Whether to modify the object in place or return a new object.

Raises:

NotImplementedError – LineStringM does not currently support reversing. This method is a placeholder for future support of non-monotonic M-enabled geometries.

cut(beg, end, normalized=False, m=False, snap=False)

Return a LineStringM object with the geometry cut between the specified distances along the linear geometry.

Parameters:

• beg (float) – The distance along the geometry to start the cut geometry.

• end (float) – The distance along the geometry to end the cut geometry.

• normalized (bool, default False) – Whether the distances are normalized (0-1) or absolute.

• m (bool, default False) – Whether the distances should be interpreted as M values.

• snap (bool, default False) – Whether to snap the distances to the nearest vertex if they are out of range. If False, a ValueError will be raised if the distances are out of range.

linref.geometry.line_locate_point_m(line: LineStringM | ndarray, point, normalized: bool = False, m: bool = False) → float | ndarray

Return the distance along the linear geometry to the nearest point on the geometry from the specified point. Supports both scalar and vectorized (array) inputs.

Analogous to shapely.line_locate_point, extended with M-value support.

Parameters:

• line (LineStringM or array of LineStringM) – The M-enabled line geometry (or geometries) to project onto.

• point (shapely.Point or array of shapely.Point) – The point (or points) to project.

• normalized (bool, default False) – Whether to return the distance as normalized (0-1) or absolute.

• m (bool, default False) – Whether to return the result as an M value instead of a distance.

Returns:

The projected distance (or M value) for each input pair.

Return type:

float or np.ndarray

linref.geometry.line_interpolate_point_m(line: LineStringM | ndarray, distance, normalized: bool = False, m: bool = False)

Return a point at the specified distance along the linear geometry. Supports both scalar and vectorized (array) inputs.

Analogous to shapely.line_interpolate_point, extended with M-value support.

Parameters:

• line (LineStringM or array of LineStringM) – The M-enabled line geometry (or geometries) to interpolate along.

• distance (float or array of float) – The distance(s) along each geometry at which to interpolate.

• normalized (bool, default False) – Whether the distance is normalized (0-1) or absolute.

• m (bool, default False) – Whether the distance should be interpreted as an M value.

Returns:

The interpolated point(s). None where interpolation is not possible.

Return type:

shapely.Point or np.ndarray of shapely.Point

linref.geometry.distance_to_m(line_m: LineStringM | ndarray, distance: float | ndarray, normalized: bool = False) → float | ndarray

Convert distance(s) along LineStringM geometry(ies) to M value(s). Supports both scalar and vectorized (array) inputs.

Parameters:

• line_m (LineStringM or array of LineStringM) – The M-enabled line geometry (or geometries).

• distance (float or array of float) – The distance(s) along each geometry.

• normalized (bool, default False) – Whether the distance(s) are normalized (0-1) or absolute.

Returns:

The M value(s). NaN where conversion is not possible.

Return type:

float or np.ndarray

linref.geometry.m_to_distance(line_m: LineStringM | ndarray, m_value: float | ndarray) → float | ndarray

Convert M value(s) to distance(s) along LineStringM geometry(ies). Supports both scalar and vectorized (array) inputs.

Parameters:

• line_m (LineStringM or array of LineStringM) – The M-enabled line geometry (or geometries).

• m_value (float or array of float) – The M value(s) to convert.

Returns:

The distance(s). NaN where conversion is not possible.

Return type:

float or np.ndarray

linref.geometry.line_merge_m(lines: list[LineStringM], allow_multiple: bool = False, allow_mismatch: bool = False, squeeze: bool = False, return_orders: bool = False, return_chains: bool = False, cast_geom: bool = False)

Merge a list of LineStringM geometries into a single LineStringM geometry or a list of LineStringM geometries if they are not contiguous.

Parameters:

• lines (list[LineStringM | shapely.LineString]) – An array-like of LineStringM geometries to be merged. If cast_geom is True, can also include shapely LineString geometries which will be cast to LineStringM.

• allow_multiple (bool, default False) – If True, allows the function to return multiple merged geometries if the input lines are not all contiguous. If False, raises an error if multiple merged geometries would be returned.

• allow_mismatch (bool, default False) – If True, allows M values to be mismatched at the termini of contiguous lines. This will retain the first M value of each merged line segment. If False, will not merge lines if M values are mismatched at the termini.

• squeeze (bool, default False) – If True and only one merged geometry is produced, returns the geometry directly instead of a list containing the single geometry.

• return_orders (bool, default False) – If True, also returns a list of indices indicating the order of the input lines in the merged geometries.

• return_chains (bool, default False) – If True, also returns a list indicating the chain index of each input line in the merged geometries.

• cast_geom (bool, default False) – If True, attempts to cast any non-LineStringM geometries in the input list to LineStringM. If False, raises an error if any non-LineStringM geometries are found.

linref.geometry.get_linestring_chains(objs)

Return the chain indices for each LineStringM object in the list.

Parameters:

objs (list of LineStringM) – The LineStringM objects to get the chain indices for.

linref.geometry.get_chord_lengths(ls, normalized=False)

Return an array of the chord lengths for each segment in the LineString.

Parameters:

• ls (LineString) – The LineString to compute chord lengths for.

• normalized (bool, default False) – Whether to return the chord lengths as a proportion of the total length of the LineString.

linref.geometry.parse_linestring_wkt(wkt)

Parse a WKT representation of one or many LineStrings, returning one or an array of LineString objects.

Parameters:

wkt (str or array-like of str) – The WKT representation of the LineString.

linref.geometry.parse_linestring_m_wkt(wkt)

Parse a WKT representation of one or many LineStringMs, returning one or an array of LineStringM objects.

Parameters:

wkt (str or array-like of str) – The WKT representation of the LineStringM.

linref.geometry.substring_m_coords(coords, m, start, end, normalized=False, tolerance=1e-10)

Extract a substring of set of coordinates given start and end fractions. Intended to provide similar functionality to shapely’s substring, but working on raw coordinate lists.

Parameters:

• coords (np.ndarray) – An NxM array of coordinates representing the linestring, where N indicates the number of points and M indicates the dimensionality (e.g., 2 for 2D, 3 for 3D).

• m (np.ndarray) – An array of M values corresponding to each coordinate in the coords array.

• start (float) – The starting distance along the linestring where the substring should begin.

• end (float) – The ending distance along the linestring where the substring should end.

• normalized (bool, optional) – If True, the start and end values are treated as fractions of the total length of the linestring (ranging from 0 to 1). Default is False.

• tolerance (float, optional) – Tolerance for detecting duplicate coordinates and handling floating point precision errors. Default is 1e-10.

linref.events.modify

linref.events.modify.dissolve(events, sort=False, return_index=False, return_relation=False)

Merge consecutive ranges. For best results, input events should be sorted.

Parameters:

• events (EventsData) – Input range of events to dissolve.

• sort (bool, default False) – Whether to sort the input events before dissolving. If True, results will still be aligned to the original input events. Unsorted events may produce unexpected results.

• return_index (bool, default False) – Whether to return the inverse index of the dissolved events as a list of arrays of indices to the original events.

• return_relation (bool, default False) – Whether to return an EventsRelation object between the dissolved events and the input events to allow for easy aggregation of data.

linref.events.modify.concatenate(objs, ignore_index=False, closed=None)

Concatenate multiple ranges of events, returning a single collection.

Parameters:

• objs (list) – List of EventsData instances to concatenate.

• ignore_index (bool, default False) – Whether to ignore the index values of the input objects, returning a new collection with a new generic 0-based index.

• closed (str {'left', 'left_mod', 'right', 'right_mod', 'both',) – ‘neither’}, optional Whether collection intervals are closed on the left-side, right-side, both or neither. If provided, the setting will be applied to the concatenated results. If not provided, the setting will be inferred from the first object in the list for linear events.

linref.events.modify.extend(events, distance=0, inplace=False)

Extend the range of events by a specified amount in either or both directions.

Parameters:

• events (EventsData) – Input range of events.

• distance (float, array-like, or tuple, optional) – Amount to extend the event ranges. If a scalar or array-like is provided, it is applied equally to both the beginning and end of each event range. If a tuple of two values is provided, the first value extends the beginning and the second value extends the end. Positive values extend ranges outward, negative values contract ranges inward. Default is 0.

• inplace (bool, optional) – If True, modify the input object in place. Default is False.

linref.events.modify.shift(events, distance, inplace=False)

Shift the range of events by a specified amount.

Parameters:

• events (EventsData) – Input range of events.

• distance (float or array-like) – Amount to shift all events. If an array-like is provided, it must be the same length as the number of events in the collection. Positive values shift events to the right, negative values to the left.

• inplace (bool, optional) – If True, modify the input object in place. Default is False.

linref.events.modify.round(events, decimals=None, factor=None, inplace=False)

Round the bounds and locations of events to a specified number of decimal places or using a specified rounding factor.

Parameters:

• events (EventsData) – Input range of events.

• decimals (int, optional) – Number of decimal places to round to. If an array-like is provided, it must be the same length as the number of events in the collection. Default is None.

• factor (float, optional) – Rounding factor. If provided, the bounds and locations of events will be rounded to the nearest multiple of this factor. Default is None.

• inplace (bool, optional) – If True, modify the input object in place. Default is False.

linref.events.modify.resegment(events, length=1, fill='cut', return_relation=False)

Resegment events into smaller segments of equal length.

Parameters:

• events (EventsData) – Input range of events.

• length (float, optional) – Length of each segment. Default is 1.

• fill ({'none','cut','left','right','extend','balance'}, default 'cut') –

  How to fill a gap at the end of the input range.

  • none : no range will be generated to fill the gap at the end of the input range.

  • cut : a truncated range will be created to fill the gap with a length less than the full range length.

  • left : the final range will be anchored on the end value and will extend the full range length to the left.

  • right : the final range will be anchored on the grid defined by the step value, extending the full range length to the right, beyond the defined end value.

  • extend : the final range will be anchored on the grid defined by the step value, extending beyond the step length to the right bound of the range.

  • balance : if the final range is greater than or equal to half the target range length, perform the cut method; if it is less, perform the extend method.

  Schematics:

  bounds :    [------------------------]
  none :
              [---------|              ]
              [         |---------|    ]
  cut :
              [---------|              ]
              [         |---------|    ]
              [                   |----]
  left :
              [---------|              ]
              [         |---------|    ]
              [              |---------]
  right :
              [---------|              ]
              [         |---------|    ]
              [                   |----]----|
  extend :
              [---------|              ]
              [         |--------------]
  

• return_relation (bool, default False) – Whether to return an EventsRelation object between the resegmented events and the input events to allow for easy aggregation of data.

Return type:

linref.events.EventsData

linref.events.modify.separate(events, anchor='centers', method='balanced', drop_short=False, inplace=False)

Address overlapping ranges by distributing overlaps between adjacent events. Eclipsed ranges (fully contained within another range) are eliminated. Identical ranges are deduplicated (first kept). Distributions are made based on a specified event anchor point and split method.

Parameters:

• events (EventsData) – Input range of events.

• anchor (str {'centers', 'begs', 'ends'}, default 'centers') – The anchor point of each event to be used when sorting events and distributing overlaps. Events are sorted by this anchor before processing, which determines overlap resolution priority.

• method (str {'balanced', 'center', 'left', 'right'}, default 'balanced') –

  The strategy for splitting overlapping regions between adjacent events.

  • balanced : Use the midpoint of the overlapping termini (ends[i], begs[j]), clamped between the two event centers. Where the overlap is large enough that the center midpoint falls within the overlap, use the center midpoint instead. This provides conservative splits for small overlaps and fair splits for large symmetric overlaps.

  • center : Always split at the midpoint of the two event centers. Provides a fair, geometry-independent split regardless of overlap magnitude.

  • left : Assign the full overlap to the left (earlier) event. The right event’s beg is set to the left event’s end.

  • right : Assign the full overlap to the right (later) event. The left event’s end is set to the right event’s beg.

• drop_short (bool, default False) – Whether to drop events that have been reduced to zero length (eclipsed or fully squeezed out by adjacent events).

• inplace (bool, optional) – If True, modify the input object in place. Default is False.

Returns:

The resulting events with all overlapping ranges separated. Returns None if inplace is True.

Return type:

EventsData or None

linref.events.integration

linref.events.integration.integrate(objs, fill_gaps=False, split_at_locs=False, expand=False, return_index=False) → EventsData

Combine multiple sets of events into a single collection, creating new linear events based on least common intervals among all input events. If requested, an array of index arrays for each range can be provided to indicate which input events contributed to each output event.

Parameters:

• objs (list) – List of EventsData instances to integrate.

• fill_gaps (bool, default False) – Whether to fill gaps in merged events between the maximum beginning and minimum ending points of all input events within a group. These gaps will be represented as events with no associated input events.

• split_at_locs (bool, default False) – Whether to split events at location points within the input events. This allows for breaking events at point events as well as linear events.

• expand (bool, default False) – Whether to expand intervals that match multiple events in any input layer. When True, each interval is duplicated for every combination of matching indices across all layers, ensuring that overlapping source events each receive their own copy of intersecting intervals. When False, each interval is assigned to only the first matching event per layer (via argmax).

• return_index (bool, default False) – Whether to return the inverse index of the integrated events as a list of arrays of indices to the original events.

Return type:

linref.events.EventsData

linref.events.selection

linref.events.selection.select(events, selector, ignore=False, inplace=False)

Select events by index, slice, or boolean mask. Use ignore=True to use a generic, 0-based index, ignoring the current index values.

Parameters:

• events (EventsData) – The events object to select from.

• selector (array-like or slice) – Array-like of event indices, a boolean mask aligned to the events, or a slice object to select events.

• ignore (bool, default False) – Whether to use a generic 0-based index, ignoring the current index values.

• inplace (bool, default False) – Whether to perform the operation in place, returning None.

linref.events.selection.select_slice(events, slice_, inplace=False)

Select events by slice.

Parameters:

• events (EventsData) – The events object to select from.

• slice (slice) – Slice object to select events.

• inplace (bool, default False) – Whether to perform the operation in place, returning None.

linref.events.selection.select_mask(events, mask, inplace=False)

Select events by boolean mask.

Parameters:

• events (EventsData) – The events object to select from.

• mask (array-like) – Boolean mask aligned to the events.

• inplace (bool, default False) – Whether to perform the operation in place, returning None.

linref.events.selection.select_index(events, index, ignore=False, inplace=False)

Select events by index values.

Parameters:

• events (EventsData) – The events object to select from.

• index (array-like) – Array-like of event indices to select.

• ignore (bool, default False) – Whether to use a generic 0-based index, ignoring the current index values.

• inplace (bool, default False) – Whether to perform the operation in place, returning None.

linref.events.selection.select_group(events, group, ungroup=None, ignore_missing=True, inplace=False)

Select events by group.

Parameters:

• group (label or array-like) – The label of the group to select or array-like of the same.

• ungroup (bool, default None) – Whether to ungroup the selection, returning the selected events without their group labels. If None and a single group is selected, the result will be ungrouped otherwise the group labels will be retained.

• ignore_missing (bool, default True) – Whether to ignore missing groups in the selection. If False, an error will be raised if any groups are not found in the collection. If True, missing groups will be ignored; in cases where no groups are found, an empty collection will be returned.

• inplace (bool, default False) – Whether to perform the operation in place, returning None.

linref.events.selection.drop(events, selector, inplace=False)

Drop events by boolean mask.

Parameters:

• events (EventsData) – The events object to select from.

• mask (array-like) – Boolean mask aligned to the events.

• inplace (bool, default False) – Whether to perform the operation in place, returning None.

linref.events.selection.drop_group(events, group, inplace=False)

Drop events by group.

Parameters:

• events (EventsData) – The events object to select from.

• group (label or array-like) – The label of the group to drop or array-like of the same.

• inplace (bool, default False) – Whether to perform the operation in place, returning None.

linref.events.analyze

linref.events.analyze.duplicated(events, subset=None, keep='first')

Return a boolean mask of duplicated events in terms of all or a selection of event anchors.

Parameters:

• events (EventsData) – The events object to analyze.

• subset (array-like, default None) – Array-like of event anchors to use for duplicated comparison. If None, all event anchors are used.

• keep ({'first', 'last', 'none'}, default 'first') – Whether to keep the first, last, or none of the duplicated events.

linref.events.analyze.find_same(events, keep='first')

Return a boolean mask of events which have the same begin and end points as at least one other event in the collection. Group-aware: only compares events within the same group.

Parameters:

• events (EventsData) – The events object to analyze.

• keep ({'first', 'last', 'none'}, default 'first') – Which of the duplicate events to keep (mark as False in the mask). - ‘first’: keep the first occurrence, mark later ones as True. - ‘last’: keep the last occurrence, mark earlier ones as True. - ‘none’: mark all duplicates as True (none are kept).

Returns:

Boolean mask where True indicates a “same” (duplicate) event.

Return type:

np.ndarray

linref.events.analyze.find_inside(events, enforce_edges=False)

Return a boolean mask of events which fall entirely inside at least one other event in the collection. Group-aware: only compares events within the same group. Note that events that are the same (same beg/end) are not considered inside each other, even with enforce_edges=True.

Parameters:

• events (EventsData) – The events object to analyze.

• enforce_edges (bool, default False) –

  Whether to consider events touching at a vertex as being inside.

  • False (strict): beg > other_beg AND end < other_end

  • True (inclusive): (beg >= other_beg AND end < other_end) OR (beg > other_beg AND end <= other_end)

Returns:

Boolean mask where True indicates an event inside another.

Return type:

np.ndarray

linref.events.common

linref.events.utility