tilupy.utils ============ .. py:module:: tilupy.utils Functions --------- .. autoapisummary:: tilupy.utils.CSI tilupy.utils.diff_runout tilupy.utils.revert_line tilupy.utils.get_contour tilupy.utils.get_profile tilupy.utils.format_path_linux Module Contents --------------- Functions ^^^^^^^^^ .. py:function:: 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. :param pred: Array of predicted binary values (e.g., 1 for event predicted, 0 otherwise). Shape and type must match :data:`obs`. :type pred: numpy.ndarray :param obs: Array of observed binary values (e.g., 1 for event observed, 0 otherwise). Shape and type must match :data:`pred`. :type obs: numpy.ndarray :returns: The Critical Success Index (CSI), a score between 0 and 1. A score of 1 indicates perfect prediction, while 0 indicates no skill. :rtype: float .. py:function:: 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. :param x_contour: Array of x-coordinates defining the contour. :type x_contour: numpy.ndarray :param y_contour: Array of y-coordinates defining the contour. Must be the same length as :data:`x_contour`. :type y_contour: numpy.ndarray :param point_ref: Reference point coordinates (x, y) from which the distance is calculated. :type point_ref: tuple[float, float] :param section: 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 :data:`point_ref` to the contour. By default None. :type section: numpy.ndarray or shapely.geometry.LineString, optional :param orientation: 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". :type orientation: str, optional :returns: If `section` is None: Euclidean distance from :data:`point_ref` to the contour. If `section` is provided: Distance along the section line between :data:`point_ref` and the contour intersection. The distance is signed, depending on the projection direction. :rtype: float .. py:function:: 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. :param line: Input line geometry to be checked and potentially reverted. :type line: shapely.geometry.LineString :param orientation: 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". :type orientation: str, optional :returns: The input line, potentially reverted to match the specified orientation. If the line already matches the orientation, it is returned unchanged. :rtype: shapely.geometry.LineString .. py:function:: 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 :data:`z` defined on the grid :data:`(x, y)`, at the specified levels :data:`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. :param x: 1D array of x-coordinates defining the grid. :type x: numpy.ndarray :param y: 1D array of y-coordinates defining the grid. :type y: numpy.ndarray :param z: 2D array of values defined on the grid :data:`(x, y)`. :type z: numpy.ndarray :param zlevels: List of contour levels at which to extract the contours. :type zlevels: list[float] :param indstep: Step used to subsample the contour points, by default 1 (no subsampling). :type indstep: int, optional :param maxdist: 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. :type maxdist: float, optional :param closed_contour: If True, the input arrays are padded to ensure closed contours, by default True. :type closed_contour: bool, optional :returns: xcontour : dict Maps each contour level to an array of x-coordinates of the contour line. ycontour : dict 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`. :rtype: tuple[dict[float, np.ndarray], dict[float, np.ndarray]] .. py:function:: 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. :param data: Data to extract the profile from. :type data: tilupy.read.TemporalResults2D or tilupy.read.StaticResults2D :param extraction_mode: 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". :type extraction_mode: str, optional :param data_threshold: Minimum value to consider as part of the profile, by default 1e-3. :type data_threshold: float, optional :param extraction_params: Different parameters to be entered depending on the extraction method chosen: - If :data:`extraction_mode == "axis"`: - :data:`axis`: str, optional Axis where to extract the profile ['X', 'Y'], by default 'Y'. - :data:`profile_position`: float, optional Position where to extract the profile. If None choose the median. By default None. Must be read: profile in :data:`axis = profile_position m`. - If :data:`extraction_mode == "coordinates"`: - :data:`xcoord`: numpy.ndarray, optional X coordinates of the profile, by default :attr:`_x`. - :data:`ycoord`: numpy.ndarray, optional Y coordinates of the profile, by default :data:`[0., 0., ...]`. - If :data:`extraction_mode == "shapefile"`: - :data:`path`: str Path to the shapefile. - :data:`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). - :data:`y_origin`: float, optional Value of the y coordinate of the origin (top-left corner) in the shapefile's coordinate system, by default :data:`_y[-1]` (EPSG:2154). - :data:`x_pixsize`: float, optional Size of a pixel along the X coordinate in the shapefile's coordinate system, by default :data:`_x[1] - _x[0]` (EPSG:2154). - :data:`y_pixsize`: float, optional Size of a pixel along the Y coordinate in the shapefile's coordinate system, by default :data:`_y[1] - _y[0]` (EPSG:2154). - :data:`step`: float, optional Spatial step between profile points, by default 10.0. By default None :type extraction_params: dict, optional :returns: tilupy.read.TemporalResults1D or tilupy.read.StaticResults1D Extracted profiles. float or tuple[np.ndarray] or numpy.ndarray Specific output depending on :data:`extraction_mode`: - If :data:`extraction_mode == "axis"`: float Position of the profile. - If :data:`extraction_mode == "coordinates"`: tuple[numpy.ndarray] X coordinates, Y coordinates and distance values. - If :data:`extraction_mode == "shapefile"`: numpy.ndarray Distance values. :rtype: tuple[tilupy.read.TemporalResults1D or tilupy.read.StaticResults1D, float or tuple[np.ndarray] or np.ndarray] :raises ValueError: If :data:`extraction_mode == "axis"` and if invalid :data:`axis`. :raises ValueError: If :data:`extraction_mode == "axis"` and if invalid format for :data:`profile_position`. :raises ValueError: If :data:`extraction_mode == "axis"` and if no value position found in axis. :raises ValueError: If :data:`extraction_mode == "coordinates"` and if invalid format for :data:`xcoord` or :data:`ycoord`. :raises ValueError: If :data:`extraction_mode == "coordinates"` and if invalid dimension for :data:`xcoord` or :data:`ycoord`. :raises ValueError: If :data:`extraction_mode == "coordinates"` and if :data:`xcoord` and :data:`ycoord` doesn't have same size. :raises ValueError: If :data:`extraction_mode == "shapefile"` and if no :data`path` is given. :raises ValueError: If :data:`extraction_mode == "shapefile"` and if invalid format for :data:`x_origin`, :data:`y_origin`, :data:`x_pixsize`, :data:`y_pixsize` or :data:`step`. :raises TypeError: If :data:`extraction_mode == "shapefile"` and if invalid geometry for the shapefile. :raises ValueError: If :data:`extraction_mode == "shapefile"` and if no linestring found in the shapefile. :raises ValueError: If invalid :data:`extraction_mode`. .. py:function:: 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/" :param path: String with the path to be modified. :type path: string :returns: **path2** -- Formatted path. :rtype: string