tilupy.utils

Functions

CSI(→ float)	Compute the Critical Success Index (CSI).
diff_runout(→ float)	Compute runout distance difference between a reference point and its projection on a contour,
revert_line(→ shapely.geometry.LineString)	Revert a line geometry if its orientation does not match the specified direction.
get_contour(→ tuple[dict[float, numpy.ndarray], ...)	Extract contour lines from a 2D grid of values at specified levels.
get_profile(...)	Extract profile with different modes and options.
format_path_linux(→ str)	Change a Windows-type path to a path formatted for Linux. are changed

Module Contents

Functions

tilupy.utils.CSI(pred: numpy.ndarray, obs: numpy.ndarray) → float

Compute the Critical Success Index (CSI).

Measure the fraction of observed and/or predicted events that were correctly predicted.

Parameters:

• pred (numpy.ndarray) – Array of predicted binary values (e.g., 1 for event predicted, 0 otherwise). Shape and type must match obs.

• obs (numpy.ndarray) – Array of observed binary values (e.g., 1 for event observed, 0 otherwise). Shape and type must match pred.

Returns:

The Critical Success Index (CSI), a score between 0 and 1. A score of 1 indicates perfect prediction, while 0 indicates no skill.

Return type:

float

tilupy.utils.diff_runout(x_contour: numpy.ndarray, y_contour: numpy.ndarray, point_ref: tuple[float, float], section: numpy.ndarray | shapely.geometry.LineString = None, orientation: str = 'W-E') → float

Compute runout distance difference between a reference point and its projection on a contour, optionally along a specified section line.

This function calculates the distance from a reference point to a contour (e.g., a polygon boundary), or the distance along a section line (e.g., a transect) between the reference point and its intersection with the contour. The section line can be oriented in four cardinal directions.

Parameters:

• x_contour (numpy.ndarray) – Array of x-coordinates defining the contour.

• y_contour (numpy.ndarray) – Array of y-coordinates defining the contour. Must be the same length as x_contour.

• point_ref (tuple[float, float]) – Reference point coordinates (x, y) from which the distance is calculated.

• section (numpy.ndarray or shapely.geometry.LineString, optional) – Coordinates of the section line as an array of shape (N, 2) or a Shapely LineString. If None, the function returns the Euclidean distance from point_ref to the contour. By default None.

• orientation (str, optional) –

  Orientation of the section line. Must be one of:

  • ”W-E” (West-East, default)

  • ”E-W” (East-West)

  • ”S-N” (South-North)

  • ”N-S” (North-South)

  This determines how the intersection point is selected if multiple intersections exist. By default “W-E”.

Returns:

If section is None: Euclidean distance from point_ref to the contour. If section is provided: Distance along the section line between point_ref and the contour intersection. The distance is signed, depending on the projection direction.

Return type:

float

tilupy.utils.revert_line(line: shapely.geometry.LineString, orientation: str = 'W-E') → shapely.geometry.LineString

Revert a line geometry if its orientation does not match the specified direction.

This function checks the orientation of the input line (based on the coordinates of its first and last points) and reverses it if necessary to ensure it matches the specified cardinal direction. The line is reversed in-place if the initial orientation is opposite to the specified one.

Parameters:

• line (shapely.geometry.LineString) – Input line geometry to be checked and potentially reverted.

• orientation (str, optional) –

  Desired cardinal direction for the line. Must be one of:

  • ”W-E” (West-East, default): The line should start at the west end (smaller x-coordinate).

  • ”E-W” (East-West): The line should start at the east end (larger x-coordinate).

  • ”S-N” (South-North): The line should start at the south end (smaller y-coordinate).

  • ”N-S” (North-South): The line should start at the north end (larger y-coordinate).

  By default “W-E”.

Returns:

The input line, potentially reverted to match the specified orientation. If the line already matches the orientation, it is returned unchanged.

Return type:

shapely.geometry.LineString

tilupy.utils.get_contour(x: numpy.ndarray, y: numpy.ndarray, z: numpy.ndarray, zlevels: list[float], indstep: int = 1, maxdist: float = 30, closed_contour: bool = True) → tuple[dict[float, numpy.ndarray], dict[float, numpy.ndarray]]

Extract contour lines from a 2D grid of values at specified levels.

This function computes contour lines for a given 2D field z defined on the grid (x, y), at the specified levels zlevels. It can optionally ensure that contours are closed by padding the input arrays, and filter out contours that are not closed within a maximum distance threshold.

Parameters:

• x (numpy.ndarray) – 1D array of x-coordinates defining the grid.

• y (numpy.ndarray) – 1D array of y-coordinates defining the grid.

• z (numpy.ndarray) – 2D array of values defined on the grid (x, y).

• zlevels (list[float]) – List of contour levels at which to extract the contours.

• indstep (int, optional) – Step used to subsample the contour points, by default 1 (no subsampling).

• maxdist (float, optional) – Maximum allowed distance between the first and last points of a contour line. If the distance exceeds this value and closed_contour is False, the contour is discarded, by default 30.

• closed_contour (bool, optional) – If True, the input arrays are padded to ensure closed contours, by default True.

Returns:

xcontourdict

Maps each contour level to an array of x-coordinates of the contour line.

ycontourdict

Maps each contour level to an array of y-coordinates of the contour line.

If a contour is discarded due to maxdist, the corresponding value is None.

Return type:

tuple[dict[float, np.ndarray], dict[float, np.ndarray]]

tilupy.utils.get_profile(data: tilupy.read.TemporalResults2D | tilupy.read.StaticResults2D, extraction_mode: str = 'axis', data_threshold: float = 0.001, **extraction_params) → tuple[tilupy.read.TemporalResults1D | tilupy.read.StaticResults1D, float | tuple[numpy.ndarray] | numpy.ndarray]

Extract profile with different modes and options.

Parameters:

• data (tilupy.read.TemporalResults2D or tilupy.read.StaticResults2D) – Data to extract the profile from.

• extraction_mode (str, optional) –

  Method to extract profiles:

  • ”axis”: Extracts a profile along an axis.

  • ”coordinates”: Extracts a profile along specified coordinates.

  • ”shapefile”: Extracts a profile along a shapefile (polylines).

  Be default “axis”.

• data_threshold (float, optional) – Minimum value to consider as part of the profile, by default 1e-3.

• extraction_params (dict, optional) –

  Different parameters to be entered depending on the extraction method chosen:

  • If extraction_mode == "axis":

    • axis: str, optional

      Axis where to extract the profile [‘X’, ‘Y’], by default ‘Y’.

    • profile_position: float, optional

      Position where to extract the profile. If None choose the median. By default None.

    Must be read: profile in axis = profile_position m.

  • If extraction_mode == "coordinates":

    • xcoord: numpy.ndarray, optional

      X coordinates of the profile, by default _x.

    • ycoord: numpy.ndarray, optional

      Y coordinates of the profile, by default [0., 0., ...].

  • If extraction_mode == "shapefile":

    • path: str

      Path to the shapefile.

    • x_origin: float, optional

      Value of the X coordinate of the origin (top-left corner) in the shapefile’s coordinate system, by default 0.0 (EPSG:2154).

    • y_origin: float, optional

      Value of the y coordinate of the origin (top-left corner) in the shapefile’s coordinate system, by default _y[-1] (EPSG:2154).

    • x_pixsize: float, optional

      Size of a pixel along the X coordinate in the shapefile’s coordinate system, by default _x[1] - _x[0] (EPSG:2154).

    • y_pixsize: float, optional

      Size of a pixel along the Y coordinate in the shapefile’s coordinate system, by default _y[1] - _y[0] (EPSG:2154).

    • step: float, optional

      Spatial step between profile points, by default 10.0.

  By default None

Returns:

tilupy.read.TemporalResults1D or tilupy.read.StaticResults1D

Extracted profiles.

float or tuple[np.ndarray] or numpy.ndarray

Specific output depending on extraction_mode:

• If extraction_mode == "axis": float

  Position of the profile.

• If extraction_mode == "coordinates": tuple[numpy.ndarray]

  X coordinates, Y coordinates and distance values.

• If extraction_mode == "shapefile": numpy.ndarray

  Distance values.

Return type:

tuple[tilupy.read.TemporalResults1D or tilupy.read.StaticResults1D, float or tuple[np.ndarray] or np.ndarray]

Raises:

• ValueError – If extraction_mode == "axis" and if invalid axis.

• ValueError – If extraction_mode == "axis" and if invalid format for profile_position.

• ValueError – If extraction_mode == "axis" and if no value position found in axis.

• ValueError – If extraction_mode == "coordinates" and if invalid format for xcoord or ycoord.

• ValueError – If extraction_mode == "coordinates" and if invalid dimension for xcoord or ycoord.

• ValueError – If extraction_mode == "coordinates" and if xcoord and ycoord doesn’t have same size.

• ValueError – If extraction_mode == "shapefile" and if no :data`path` is given.

• ValueError – If extraction_mode == "shapefile" and if invalid format for x_origin, y_origin, x_pixsize, y_pixsize or step.

• TypeError – If extraction_mode == "shapefile" and if invalid geometry for the shapefile.

• ValueError – If extraction_mode == "shapefile" and if no linestring found in the shapefile.

• ValueError – If invalid extraction_mode.

tilupy.utils.format_path_linux(path: str) → str

Change a Windows-type path to a path formatted for Linux. are changed to /, and partitions like “C:” are changed to “/mnt/c/”

Parameters:

path (string) – String with the path to be modified.

Returns:

path2 – Formatted path.

Return type:

string