pybend.io package

This package provides I/O utilities to read/write centerlines and collections.

pybend.io.common module

Common I/O helpers.

class pybend.io.common.CenterlineIOFormat(*values)

Bases: StrEnum

Supported centerline file formats.

CSV

Comma-separated values file.

FLUMY_CSV

Flumy-specific CSV file.

KML

Keyhole Markup Language file.

static _generate_next_value_(name, start, count, last_values)

Return the lower-cased version of the member name.

CSV = 'csv'
FLUMY_CSV = 'flumy_csv'
KML = 'kml'
pybend.io.common.resolve_path(*, base_dir: Path | None, raw_url: str, ctx: str) → Path

Resolve an absolute or base_dir-relative path.

  • Absolute paths are accepted even when base_dir is None.

  • Relative paths are resolved against base_dir when provided, otherwise against the current working directory.

Parameters:

  • base_dir (Path | None) – Base directory to resolve relative paths.

  • raw_url (str) – Raw file path or URL.

  • ctx (str) – Context string for error messages.

Returns:

Resolved absolute path.

Return type:

Path

pybend.io.centerline_io module

Centerline I/O.

This module contains helpers to load and dump centerline-related datasets.

pybend.io.centerline_io.create_dataset_from_xy(X: ndarray[tuple[Any, ...], dtype[float64]], Y: ndarray[tuple[Any, ...], dtype[float64]]) → DataFrame

Create a dataset from X and Y 1D arrays.

Parameters:

  • X (npt.NDArray[np.float64]) – X coordinates

  • Y (npt.NDArray[np.float64]) – Y coordinates

Returns:

DataFrame with centerline point coordinates and properties.

Return type:

pd.DataFrame

pybend.io.centerline_io.dump_centerline_to_csv(filepath: str, centerline: Centerline, sep: str = ';') → None

Write a csv file containing centerline data.

Parameters:

  • filepath (str) – path to write the csv file

  • centerline (Centerline) – Centerline object to dump

  • sep (str, optional) – csv separator. Defaults to “;”.

pybend.io.centerline_io.load_centerline_dataset_from_Flumy_csv(filepath: str, sep: str = ';') → tuple[int, DataFrame]

Load a dataset from a csv file coming from Flumy simulation.

Parameters:

  • filepath (str) – path to the csv file using Flumy format

  • sep (str, optional) – csv column delimiter. Defaults to “;”.

Returns:

tuple containing the age as first component and a DataFrame containing centerline point coordinates and properties.

Return type:

tuple[int, pd.DataFrame]

pybend.io.centerline_io.load_centerline_dataset_from_csv(filepath: str, x_prop: str = 'X', y_prop: str = 'Y', z_prop: str = 'Z', drop_columns: tuple[str, ...] = (), sep: str = ';') → DataFrame

Load a dataset from a csv file containing cartesian coordinates.

Coordinates must consist in at least x and y, and optionally centerline elevation and a list of properties

Parameters:

  • filepath (str) – path to the csv file

  • x_prop (str, optional) – name of the column for x coordinate. Defaults to “X”.

  • y_prop (str, optional) – name of the column for y coordinate. Defaults to “Y”.

  • z_prop (str, optional) – name of the column for elevation. Defaults to “Z”.

  • drop_columns (tuple[str, ...], optional) – list of the names of the columns to drop. Defaults is empty.

  • sep (str, optional) – csv separator. Defaults to “;”.

Returns:

DataFrame containing centerline coordinates and properties of each channel point

Return type:

pd.DataFrame

pybend.io.centerline_io.load_centerline_dataset_from_kml(filepath: str, keyword: str = 'coordinates') → DataFrame

Load a dataset from a kml file containing centerline point coordinates.

Parameters:

  • filepath (str) – path to the kml file

  • keyword (str, optional) – keyword to search for coordinate line. Defaults to “coordinates”.

Returns:

DataFrame containing centerline point coordinates.

Return type:

pd.DataFrame

pybend.io.centerline_io.load_centerline_from_file(filepath: str, kind: CenterlineIOFormat, **kwargs: Any) → tuple[int, DataFrame]

Load a centerline from a file.

Supported formats are: generic CSV, Flumy CSV, and KML.

Parameters:

  • filepath (str) – Path to the file.

  • kind (CenterlineIOFormat) – Format of the file to load.

  • **kwargs (Any) –

    Loader-specific options.

    For CenterlineIOFormat.CSV:

    • x_prop (str): X column name (default "X")

    • y_prop (str): Y column name (default "Y")

    • z_prop (str): Z/elevation column name (default "Z")

    • drop_columns (tuple[str, …]): columns to drop (default empty)

    • sep (str): separator (default ";")

    For CenterlineIOFormat.FLUMY_CSV:

    • sep (str): separator (default ";")

    For CenterlineIOFormat.KML:

    • keyword (str): keyword for coordinate line (default "coordinates")

Returns:

Tuple containing the centerline age (if present) and the dataset as a DataFrame.

Return type:

tuple[int, pd.DataFrame]

pybend.io.centerline_collection_io module

Centerline collection I/O.

This module contains helpers to load centerline-collection related datasets.

pybend.io.centerline_collection_io.load_centerline_collection_dataset_from_Flumy_csv(filepath: str, sep: str = ';') → dict[int, DataFrame]

Load enterline collection dataset from a csv file generated by Flumy.

Parameters:

  • filepath (str) – path to write the csv file

  • sep (str, optional) – csv separator. Defaults to “;”.

Returns:

dictionary where ages are keys and DataFrame with centerline point coordinates and properties are values.

Return type:

dict [int, pd.DataFrame]

pybend.io.centerline_collection_io.load_centerline_collection_from_a_file(filepath: str, kind: CenterlineIOFormat, **kwargs: Any) → dict[int, DataFrame]

Load a centerline collection from a single file.

Supported formats are: generic CSV and Flumy CSV.

Parameters:

  • filepath (str) – Path to the file.

  • kind (CenterlineIOFormat) – File format.

  • **kwargs (Any) –

    Loader-specific options.

    For CenterlineIOFormat.CSV:

    • x_prop (str): X column name (default "X")

    • y_prop (str): Y column name (default "Y")

    • z_prop (str): Z/elevation column name (default "Z")

    • age_prop (str): age column name (default "Age")

    • drop_columns (tuple[str, …]): columns to drop (default empty)

    • sep (str): separator (default ";")

    For CenterlineIOFormat.FLUMY_CSV:

    • sep (str): separator (default ";")

Returns:

dictionary where ages are keys and DataFrame with centerline point coordinates and properties are values.

Return type:

dict[int, pd.DataFrame]

pybend.io.centerline_collection_io.load_centerline_collection_from_multiple_files(map_file: dict[int, str], kind: CenterlineIOFormat, **kwargs: Any) → dict[int, DataFrame]

Load a centerline collection from multiple files in a directory.

Supported formats are: generic CSV and KML.

Parameters:

  • map_file (dict[int, str]) – Mapping of ages to file paths.

  • kind (CenterlineIOFormat) – File format.

  • **kwargs (Any) –

    Loader-specific options.

    For CenterlineIOFormat.CSV:

    • x_prop (str): X column name (default "X")

    • y_prop (str): Y column name (default "Y")

    • z_prop (str): Z/elevation column name (default "Z")

    • drop_columns (tuple[str, …]): columns to drop (default empty)

    • sep (str): separator (default ";")

    For CenterlineIOFormat.KML:

    • directory (str): base directory containing the KML files

    • keyword (str): keyword for coordinate line (default "coordinates")

Returns:

dictionary where ages are keys and DataFrame with centerline point coordinates and properties are values.

Return type:

dict[int, pd.DataFrame]

pybend.io.centerline_collection_io.load_centerline_evolution_from_multiple_kml(directory: str, map_file: dict[int, str], keyword: str = 'coordinates') → dict[int, DataFrame]

Load centerline data from multiple files.

Parameters:

  • directory (str) – directory where the kml files are

  • map_file (dict[int, str]) – dictionnary of age and file name in the directory

  • keyword (str, optional) – keyword to search for coordinate line. Defaults to “coordinates”.

Returns:

dictionary where ages are keys and DataFrame with centerline point coordinates and properties are values.

Return type:

dict[int, pd.DataFrame]

pybend.io.centerline_collection_io.load_centerline_evolution_from_multiple_xy_csv(map_file: dict[int, str], x_prop: str = 'X', y_prop: str = 'Y', z_prop: str = 'Z', drop_columns: tuple[str, ...] = (), sep: str = ';') → dict[int, DataFrame]

Load centerline data from multiple files.

Parameters:

  • map_file (dict[int, str]) – dictionnary of age and file name in the directory.

  • x_prop (str, optional) – name of the column for x coordinate Defaults to “X”.

  • y_prop (str, optional) – name of the column for y coordinate Defaults to “Y”.

  • z_prop (str, optional) – name of the column for elevation Defaults to “Z”.

  • drop_columns (tuple[str,...], optional) – list of the names of the columns to drop Defaults is empty.

  • sep (str, optional) – separator of the csv files Defaults to “;”.

Returns:

dictionary where ages are keys and DataFrame with centerline point coordinates and properties are values.

Return type:

dict[int, pd.DataFrame]

pybend.io.centerline_collection_io.load_centerline_evolution_from_single_xy_csv(filepath: str, x_prop: str = 'X', y_prop: str = 'Y', z_prop: str = 'Z', age_prop: str = 'Age', drop_columns: tuple[str, ...] = (), sep: str = ';') → dict[int, DataFrame]

Load centerline data from multiple files.

Parameters:

  • filepath (str) – file path

  • x_prop (str, optional) – name of the column for x coordinate Defaults to “X”.

  • y_prop (str, optional) – name of the column for y coordinate Defaults to “Y”.

  • z_prop (str, optional) – name of the column for elevation Defaults to “Z”.

  • age_prop (str, optional) – name of the column for centerline age Defaults to “Age”.

  • drop_columns (tuple[str,...], optional) – list of the names of the columns to drop Defaults is empty.

  • sep (str, optional) – separator of the csv files Defaults to “;”.

Returns:

dictionary where ages are keys and DataFrame with centerline point coordinates and properties are values.

Return type:

dict[int, pd.DataFrame]