pyorps package

Subpackages

Module contents

PYORPS - Python for Optimal Routes in Power Systems.

class pyorps.CostAssumptions(source=None)[source]

Bases: object

A class for handling cost assumptions for rasterization.

This class handles: - Loading cost assumptions from files (CSV, Excel, JSON) or generating of cost assumptions from a dictionary or a GeoDataFrame. - Mapping costs to features in a GeoDataFrame - Managing hierarchical cost structures

_apply_nested_costs(gdf, main_feature=None, side_features=None)[source]

Apply costs to the GeoDataFrame based on nested dictionary cost assumptions.

Parameters:

gdf (GeoDataFrame) – GeoDataFrame to update with cost values
main_feature (Optional[str]) – Column name for the primary feature
side_features (Optional[list[str]]) – List containing a single column name for the
feature (secondary)

Returns:

None (modifies gdf in-place)

_apply_tuple_costs(gdf, main_feature=None, side_features=None)[source]

Apply costs to the GeoDataFrame based on tuple keys in cost assumptions.

Parameters:

gdf (GeoDataFrame) – GeoDataFrame to update with cost values
main_feature (Optional[str]) – Column name for the primary feature
side_features (Optional[list[str]]) – List of column names for secondary features

Returns:

None (modifies gdf in-place)

static _convert_numeric_columns(df)[source]

Convert columns to numeric, handling different decimal separators.

Parameters:

df (DataFrame) – DataFrame with potential numeric columns that might use different
separators (decimal)

Return type:

DataFrame

Returns:

DataFrame with properly converted numeric columns

_load_csv_cost_assumptions(filepath)[source]

Load cost assumptions from a CSV file with auto-detection of encoding, delimiter, and decimal separator.

Parameters:: filepath (str) – Path to the CSV file
Return type:: dict
Returns:: dictionary of cost assumptions

_load_excel_cost_assumptions(filepath)[source]

Load cost assumptions from an Excel file, handling different decimal separators.

Parameters:: filepath (str) – Path to the Excel file
Return type:: dict
Returns:: dictionary of cost assumptions

_load_json_cost_assumptions(filepath)[source]

Load cost assumptions from a JSON file with auto-detection of encoding.

Parameters:: filepath (str) – Path to the JSON file
Return type:: dict
Returns:: dictionary of cost assumptions

apply_to_geodataframe(gdf, main_feature=None, side_features=None)[source]

Apply cost assumptions to a GeoDataFrame.

Parameters:

gdf (GeoDataFrame) – GeoDataFrame to apply costs to
main_feature (Optional[str]) – Main feature column name
side_features (Optional[list[str]]) – list of side feature column names or single side feature name

Returns:

GeoDataFrame with ‘cost’ column added

convert_df_to_cost_dict(df)[source]

Convert a DataFrame to a nested dictionary for cost assumptions.

Parameters:: df (DataFrame) – DataFrame containing cost assumptions with hierarchical structure
Return type:: dict
Returns:: dictionary of cost assumptions with nested structure based on DataFrame columns

Uses one numeric column for costs, and all other columns as a hierarchical index: - The first column is the ‘main_feature’ - All additional columns are ‘side_features’

cost_dict_to_df(cost_dict)[source]

Convert cost assumptions dictionary to DataFrame.

Parameters:: cost_dict (dict) – Dictionary of cost assumptions
Return type:: DataFrame
Returns:: DataFrame representation of cost assumptions

load(source)[source]

Load cost assumptions from a file or dictionary.

Parameters:: source (Union[str, dict]) – Path to a file or a dictionary containing cost assumptions
Return type:: dict
Returns:: dictionary of cost assumptions

to_csv(filepath, separator=';', decimal='.', encoding='ISO-8859-1')[source]

Save the cost assumptions to a CSV file.

Parameters:

filepath (str) – Path where to save the CSV file
separator (str) – Column separator character (default is ‘;’)
decimal (str) – Decimal separator character (default is ‘.’)
encoding (str) – The encoding of the file (default is ‘ISO-8859-1’)

Return type:

None

to_excel(filepath, sheet_name='CostAssumptions', index=False)[source]

Save the cost assumptions to an Excel file.

Parameters:

filepath (str) – Path where to save the Excel file
sheet_name (str) – Name of the worksheet (default is ‘CostAssumptions’)
index (bool) – Whether to write row indices (default is False)

Return type:

None

to_json(filepath, indent=2, encoding='ISO-8859-1')[source]

Save the cost assumptions to a JSON file.

Parameters:

filepath (str) – Path where to save the JSON file
indent (int) – Number of spaces for indentation (default is 2)
encoding (str) – The encoding of the file (default is ‘ISO-8859-1’)

Return type:

None

class pyorps.GeoDataset(file_source, crs=None)[source]

Bases: ABC

_abc_impl = <_abc._abc_data object>

crs: Optional[str] = None

data: Union[GeoDataFrame, ndarray, None] = None

file_source: Any

abstractmethod load_data(**kwargs)[source]

class pyorps.GeoRasterizer(input_data, cost_assumptions, bbox=None, mask=None, default_crs=None, **kwargs)[source]

Bases: object

A class for preparing and rasterizing geospatial data with cost assumptions.

This class integrates:

GeoDataset for representing datasets with metadata
CostAssumptions for handling cost mappings
Rasterization functionality for converting vector data to rasters

_calculate_out_shape_from_bounding_box(bounding_box, resolution_m2=1.0)[source]

Calculate the output shape (rows, columns) based on a bounding box and resolution.

Parameters:

bounding_box (Polygon) – The bounding box defining the output shape in a planar CRS
resolution_m2 (float) – The resolution in square meters

Return type:

tuple[int, int]

Returns:

tuple of (rows, columns) representing the output shape

_calculate_out_shape_from_geodataframe(gdf, resolution_m2=1.0, bounding_box=None)[source]

Calculate the output shape (rows, columns) based on a GeoDataFrame and resolution.

Parameters:

gdf (GeoDataFrame) – The GeoDataFrame containing the geometries to cover
resolution_m2 (float) – The resolution in square meters
bounding_box (Optional[Polygon]) – Optional bounding box defining the output shape

Return type:

tuple[int, int]

Returns:

tuple of (rows, columns) representing the output shape

static _get_rows_and_columns(width, height, resolution_m2, total_area_m2)[source]

Calculate rows and columns based on width, height, and resolution.

Parameters:

width – Width of the area
height – Height of the area
resolution_m2 – Resolution in square meters
total_area_m2 – Total area in square meters

Returns:

tuple of (rows, columns)

_modify_raster_from_dataset_simple_cost_assumptions(gdf, cost_assumptions=None, ignore_value=65535, multiply=False, zone_field=None, forbidden_zone=None, forbidden_value=65535)[source]

Modify the raster with an additional GeoDataFrame.

Parameters:

gdf (GeoDataFrame) – GeoDataFrame, used to modify the raster dataset
cost_assumptions (Union[dict, str, CostAssumptions, int, float, None]) – The CostAssumptionsType or numeric to apply as cost values to the base_dataset
ignore_value (Optional[float]) – Value in the raster to ignore
multiply (bool) – If True, multiply the raster values by the given value (in cost_assumptions)
zone_field (Optional[str]) – Field name for zones in the dataset
forbidden_zone (Optional[str]) – Zone value that should be treated as forbidden
forbidden_value (int) – Value to use for forbidden areas

Returns:

The modified raster

property base_data: GeoDataFrame

Property to directly access the data attribute of the base_dataset.

Returns:: The base dataset (GeoDataFrame

clip_to_area(clip_geometry)[source]

Clip the base dataset to a specific area.

Parameters:: clip_geometry (Union[GeoDataFrame, Polygon]) – The geometry to clip by
Return type:: GeoDataset
Returns:: The clipped base dataset

create_bounds_geodataframe(target_crs=None)[source]

Creates a GeoDataFrame from the bounds of the base data in a specified CRS.

Parameters:: target_crs (Optional[str]) – The desired CRS for the new GeoDataFrame
Return type:: GeoDataFrame
Returns:: A new GeoDataFrame containing the bounds of the base data

static create_buffer(dataset, geometry_buffer_m, inplace=True)[source]

Add a buffer to geometries in a dataset.

Parameters:

dataset (Union[VectorDataset, GeoDataFrame]) – The dataset to buffer (GeoDataset or GeoDataFrame)
geometry_buffer_m (float) – Distance to buffer in dataset’s CRS units
inplace (bool) – If True, modify the dataset in place

Return type:

Union[VectorDataset, GeoDataFrame]

Returns:

The buffered dataset

property crs

Passing crs property of base_dataset.

Returns:: The desired CRS of the base dataset

modify_raster_from_dataset(input_data, cost_assumptions=None, bbox=None, mask=None, transform=None, geometry_buffer_m=0, ignore_value=65535, multiply=False, zone_field=None, forbidden_zone=None, forbidden_value=65535, **kwargs)[source]

Modify the raster with an additional dataset.

Parameters:

input_data (Union[str, dict, GeoDataFrame, GeoSeries, ndarray]) – Path to the additional dataset file
cost_assumptions (Union[dict, str, CostAssumptions, int, float, None]) – The CostAssumptionsType or numeric to apply as cost values to the base_dataset
bbox (Union[Polygon, GeoDataFrame, GeoSeries, tuple[float, float, float, float], None]) – The bounding box to apply to the input data
mask (Union[Polygon, GeoDataFrame, tuple, None]) – The geometry mask to apply to the input data
transform (Optional[Affine]) – The transform describing the input data
geometry_buffer_m (float) – Buffer to apply to the dataset geometries
ignore_value (Optional[float]) – Value in the raster to ignore
multiply (bool) – If True, multiply the raster values by the given value (in cost_assumptions)
zone_field (Optional[str]) – Field name for zones in the dataset
forbidden_zone (Optional[str]) – Zone value that should be treated as forbidden
forbidden_value (int) – Value to use for forbidden areas
**kwargs – Additional keyword arguments, passed to the loading function of the GeoDataset

Return type:

ndarray

Returns:

The modified raster

modify_raster_with_geodataframe(gdf, value, ignore_value=65535, multiply=False)[source]

Modifies the raster cells inside the polygons of a GeoDataFrame.

Parameters:

gdf (GeoDataFrame) – The GeoDataFrame containing polygons to use for masking
value (float) – The value to set for the raster cells inside the polygons
ignore_value (Optional[float]) – Value in the raster to ignore during modification
multiply (bool) – If True, multiply the raster values by the given value

Return type:

ndarray

Returns:

The modified raster

rasterize(field_name='cost', resolution_in_m=1.0, fill_value=65535, save_path=None, dtype='uint16', geometry_buffer_m=0, bounding_box=None)[source]

Rasterize the base dataset based on a specified field.

Parameters:

field_name (str) – The field to use for rasterization values
resolution_in_m (float) – The resolution of the output raster in meters
fill_value (int) – Value to use for areas with no data
save_path (Optional[str]) – Path to save the rasterized output
dtype (str) – Data type for the output raster
geometry_buffer_m (float) – Buffer to apply to the dataset geometries
bounding_box (Optional[Polygon]) – Bounding box to define the rasterization extent

Return type:

RasterDataset

Returns:

tuple of (raster_data, transform)

save_raster(save_path)[source]

Save the rasterized data to a file.

Parameters:: save_path (str) – Path to save the raster file
Return type:: None

shrink_raster(exclude_value)[source]

Shrink the raster by removing outer bounds with a specific value.

Parameters:: exclude_value (int) – Value to exclude from the outer bounds
Return type:: ndarray
Returns:: The shrunk raster

class pyorps.InMemoryRasterDataset(file_source, crs, transform)[source]

Bases: RasterDataset

_abc_impl = <_abc._abc_data object>

count: int

dtype: dtype

file_source: Any

load_data(**kwargs)[source]

shape: tuple[int, int]

transform: Affine

class pyorps.InMemoryVectorDataset(file_source, crs=None, bbox=None, mask=None)[source]

Bases: VectorDataset

_abc_impl = <_abc._abc_data object>

apply_bbox()[source]

apply_mask()[source]

correct_crs()[source]

file_source: Any

load_data(**kwargs)[source]

post_loading()[source]

class pyorps.LocalRasterDataset(file_source, crs=None)[source]

Bases: RasterDataset

_abc_impl = <_abc._abc_data object>

count: int

dtype: dtype

file_source: Any

load_data(**kwargs)[source]

shape: tuple[int, int]

transform: Affine

class pyorps.LocalVectorDataset(file_source, crs=None, bbox=None, mask=None)[source]

Bases: InMemoryVectorDataset

_abc_impl = <_abc._abc_data object>

apply_bbox()[source]

apply_mask()[source]

file_source: Any

load_data(**kwargs)[source]

class pyorps.Path(source, target, algorithm, graph_api, path_indices, path_coords, path_geometry, euclidean_distance, runtimes, path_id, search_space_buffer_m, neighborhood, total_length=None, total_cost=None, length_by_category=None, length_by_category_percent=None)[source]

Bases: object

Dataclass representing a path in a raster graph. Used as container for all path metrics and information.

algorithm: str

euclidean_distance: float

graph_api: str

length_by_category: Optional[dict[float, float]] = None

length_by_category_percent: Optional[dict[float, float]] = None

neighborhood: str

path_coords: list[Union[tuple[float, float], list[float]]]

path_geometry: LineString

path_id: int

path_indices: Union[list[Union[int, int32, int64, uint32, uint64]], ndarray[int]]

runtimes: dict[str, float]

search_space_buffer_m: float

source: Union[tuple[float, float], list[float]]

target: Union[tuple[float, float], list[float]]

to_geodataframe_dict()[source]

Convert Path object to a dictionary suitable for GeoDataFrame creation.

Return type:: dict
Returns:: dictionary with path data formatted for GeoDataFrame

total_cost: Optional[float] = None

total_length: Optional[float] = None

class pyorps.PathCollection[source]

Bases: object

Container for Path objects with O(1) retrieval by path ID and O(n) lookup for source and target information. Paths can be added with new id by replacing a Path object with the same ID already existing in th PathCollection.

_next_id: int

_paths: dict[int, Path]

add(path, replace=False)[source]

Add a path to the PathCollection. If the Path’s path_id is None or if replace is False, the path_id of the Path object will set to self._next_id and self._next_id will be incremented. If the Path’s path_id is not None and replace is True, a Path with the same path_id (if present) will be replaced with the new Path object.

Parameters:

path (Path) – A Path object which should be added to the PathCollection.
replace (bool) – Whether to replace an existing Path object with the same path_id (if present) or not.

Return type:

None

property all

Return all Path objects from the values of the PathCollection’s _paths dictionary as a list.

Returns:: A list of all Path objects in the PathCollection.

get(path_id=None, source=None, target=None)[source]

Retrieve a stored path by ID, or by source AND target.

Parameters:

path_id (int) – The ID of the Path object to retrieve (must be None if path should be found by source and target)
source (Any) – The source Path object to retrieve (only used if path_id is None and target os set too; neglected otherwise)
target (Any) – The target Path object to retrieve (only used if path_id is None and target os set too; neglected otherwise)

Return type:

Optional[Path]

Returns:

The Path object with the specified ID or source/target pair. None if no such path exists.

to_geodataframe_records()[source]

Convert all paths to a list of dictionaries suitable for a GeoDataFrame.

Return type:: list
Returns:: List of dictionaries with path data formatted for a GeoDataFrame

class pyorps.PathFinder(dataset_source, source_coords, target_coords, search_space_buffer_m=None, neighborhood_str='r2', steps=None, ignore_max_cost=True, graph_api='networkit', cost_assumptions=None, datasets_to_modify=None, crs=None, bbox=None, mask=None, transform=None, raster_save_path=None, **kwargs)[source]

Bases: object

A class that encapsulates RasterReader and graph-based routing capabilities.

This class provides functionality to: 1. Read raster data using RasterReader or create a raster using GeoRasterizer 2. Create a graph representation of the raster with a defined Graph library 3. Find the shortest paths between coordinates 4. Convert resulting paths of graph node indices back to coordinates 5. Create GeoDataFrames of paths and export to other geo-formats for further analysis

The class supports various graph APIs to create a graph from a raster.

_create_path_result(path_indices, source, target, algorithm, calculate_metrics)[source]

Helper method to create a path result dictionary from path indices.

Parameters:

path_indices – List of node indices for the path
source – Source coordinate(s)
target – Target coordinate(s)
algorithm – The routing algorithm used
calculate_metrics – Whether to calculate metrics

Returns:

Dictionary containing path information

static _point_or_multipoints(input_data)[source]

Converts a Points or a Multipoint to a NormalizedCoordinate

Parameters:: input_data (Union[tuple[float, float], list[float], list[Union[tuple[float, float], list[float]]], list[Point], list[MultiPoint], ndarray, Point, MultiPoint, GeoSeries, GeoDataFrame]) – Point or Multipoint to be converted to a NormalizedCoordinate
Return type:: Union[tuple[float, float], list[float], list[Union[tuple[float, float], list[float]]]]
Returns:: A NormalizedCoordinate of the input_data

calculate_path_metrics(path_indices, path)[source]

Calculate metrics about the path and add directly to the Path object.

Parameters:

path_indices – List of node indices for the path.
path – Path object to update with metrics.

create_graph(band_index=0)[source]

Create a graph from the raster data.

Parameters:: band_index (int) – Index of the raster band to use. Defaults to 0.
Return type:: Any
Returns:: The created graph object.

create_path_geodataframe()[source]

Create a GeoDataFrame containing all stored paths.

Returns:: GeoDataFrame containing path data, or None if no paths available

create_raster_handler(cost_assumptions=None, datasets_to_modify=None, raster_save_path=None, **kwargs)[source]

Create a RasterReader object for the specified file and parameters.

Parameters:

cost_assumptions (Union[dict, str, CostAssumptions, None]) – Cost assumptions to use for rasterization. Required if dataset_source is vector data
datasets_to_modify (Optional[list[dict[str, Any]]]) – List of datasets to use to modify the raster using GeoRasterizer.modify_raster_from_dataset
raster_save_path (Optional[str]) – Path to save the raster dataset to.

Returns:

The created RasterReader object

Return type:

RasterReader

find_route(source=None, target=None, algorithm='dijkstra', calculate_metrics=True, pairwise=False, raster_parameters=None, **kwargs)[source]

Find the shortest path between source and target coordinates.

Parameter:

source: CoordinateInput - Source coordinates. If None, uses the: source_coords provided at initialization. Can be: tuple, list of tuples, array of arrays, shapely Point, shapely MultiPoint, GeoSeries of points, or GeoDataFrame of points.
target: Target coordinates. If None, uses the target_coords provided at: initialization. Can be a single pair (x, y) or a list of pairs [(x1, y1), (x2, y2), …].

algorithm: Algorithm to use for shortest path. Defaults to “dijkstra”. calculate_metrics: Whether to calculate path metrics. Defaults to True. pairwise: Whether to calculate paths pairwise (requires equal number of

sources and targets). Default is False.

Return type:: Union[Path, PathCollection]
Returns:: Dictionary or list of dictionaries containing path information

get_coords_from_node_indices(node_indices)[source]

Convert node indices to coordinates.

Parameters:: node_indices (Union[int, int32, int64, uint32, uint64, list[Union[int, int32, int64, uint32, uint64]], ndarray[int]]) – List of node indices.
Return type:: list[Union[tuple[float, float], list[float]]]
Returns:: List of coordinates (x, y).

get_node_indices_from_coords(coords)[source]

Convert coordinates to node indices.

Parameters:: coords (Union[tuple[float, float], list[float], list[Union[tuple[float, float], list[float]]]]) – Either: - A single coordinate pair (x, y) - A list of coordinate pairs [(x1, y1), (x2, y2), …]
Return type:: Union[int, int32, int64, uint32, uint64, list[Union[int, int32, int64, uint32, uint64]], ndarray[int], list[Union[list[Union[int, int32, int64, uint32, uint64]], ndarray[int]]]]
Returns:: List of node indices.

get_path(path_id=None, source=None, target=None)[source]

Retrieve a stored path by ID, or by source AND target.

Parameters:

path_id – Numerical ID of the path
source – Source coordinates to search for
target – Target coordinates to search for

Returns:

Path object or None if not found

property graph_api: GraphAPI

static normalize_coordinates(input_data)[source]

Normalize different coordinate formats into tuples or lists of tuples.

Parameters:

input_data (Union[tuple[float, float], list[float], list[Union[tuple[float, float], list[float]]], list[Point], list[MultiPoint], ndarray, Point, MultiPoint, GeoSeries, GeoDataFrame, None]) – Can be a tuple, a list of tuples, an array of arrays, a shapely Point, a shapely MultiPoint, a GeoSeries of points, or a GeoDataFrame of points.

Returns:

A single coordinate tuple (x, y) or list of coordinate: tuples [(x1, y1), (x2, y2), …]

Return type:

CoordinateOutput

plot_paths(paths=None, plot_all=True, subplots=True, subplot_size=(10, 8), source_color='green', target_color='red', path_colors=None, source_marker='o', target_marker='x', path_line_width=2, show_raster=True, title=None, sup_title=None, path_id=None, reverse_colors=False)[source]

Plot paths with customizable styling and layout options.

This method visualizes the calculated paths, allowing for detailed customization of the plot appearance. It delegates to the PathPlotter class to handle the actual visualization.

Parameters:

paths (Union[Path, PathCollection, list[Path], None]) – Specific path(s) to plot. If None, uses all paths in this PathFinder instance. Can be a single Path object, a list of Path objects, or a PathCollection.
plot_all (bool) – If True, plots all paths. If False, plots only the path with path_id.
subplots (bool) – If True and multiple paths are plotted, creates separate subplots for each path.
subplot_size (tuple[int, int]) – Size of each individual subplot in inches (width, height).
source_color (str) – Color for source markers.
target_color (str) – Color for target markers.
path_colors (Union[str, list[str], None]) – Colors for path lines. Can be a single color or a list of colors. If None, default color scheme is used.
source_marker (str) – Marker style for source points.
target_marker (str) – Marker style for target points.
path_line_width (int) – Line width for the paths.
show_raster (bool) – Whether to display the raster data as background.
title (Union[str, list[str], None]) – Title for the plot or individual subplot titles if a list is provided.
sup_title (Optional[str]) – Overall title for the figure (when using multiple subplots).
path_id (Union[list[int], int, None]) – ID of specific path to plot when plot_all is False. Can be a single ID or a list of IDs.
reverse_colors (bool) – Whether to reverse the color scheme for raster data (dark=low cost, bright=high cost).

Return type:

Union[Any, list[Any]]

Returns:

The matplotlib axes object(s) for the plot. Returns a list of axes if multiple subplots are created, otherwise returns a single axes object.

Runtime Notes:

The plotting operation itself is generally quick (0.1-0.5 seconds)
Most time is spent on data preparation in the initial PathFinder setup
When plotting many paths, using subplots=True can improve readability
Displaying the raster background (show_raster=True) adds minimal overhead once the PathFinder is initialized

save_paths(save_file_path=None)[source]

Save all calculated paths to a file in a GIS-compatible format.

This method creates a GeoDataFrame containing all paths from the PathCollection and saves it to the specified file. The file format is automatically determined from the file extension (e.g., ‘.shp’ for Shapefile, ‘.gpkg’ for GeoPackage).

Parameters:: save_file_path (Optional[str]) – Path to save the paths file. If None, no file is saved. Common formats include: - Shapefile (.shp) - GeoPackage (.gpkg) - GeoJSON (.geojson) - CSV (.csv)
Return type:: None
Returns:: None

Notes

The saved file includes all path attributes (ID, length, cost data)
The geometries are saved as LineString features with the CRS from the

source dataset - If no paths have been calculated, an empty GeoDataFrame will be created first

save_raster(save_path=None)[source]

Save the raster data used for path calculations to a GeoTIFF file.

This method exports the current raster data to the specified file location. The raster contains the cost values used for path calculations, including any modifications from additional datasets. The exported file includes complete geo referencing information and preserves the original CRS.

Parameters:: save_path (Optional[str]) – Path where the raster file should be saved. If None, uses the default filename “pyorps_raster.tiff” in the current directory.
Return type:: None
Returns:: None

Notes

The saved raster includes all cost modifications from additional datasets
The file is saved in GeoTIFF format which preserves geo referencing

information - If the PathFinder uses a GeoRasterizer, the complete raster is saved - Otherwise, only the section loaded in the RasterHandler is saved - For large areas, the resulting file size may be substantial

class pyorps.RasterDataset(file_source, crs=None)[source]

Bases: GeoDataset, ABC

_abc_impl = <_abc._abc_data object>

count: int

dtype: dtype

file_source: Any

shape: tuple[int, int]

transform: Affine

class pyorps.VectorDataset(file_source, crs=None, bbox=None, mask=None)[source]

Bases: GeoDataset, ABC

_abc_impl = <_abc._abc_data object>

abstractmethod apply_bbox()[source]

abstractmethod apply_mask()[source]

bbox: Union[Polygon, GeoDataFrame, GeoSeries, tuple[float, float, float, float], None] = (None,)

abstractmethod correct_crs()[source]

file_source: Any

mask: Union[Polygon, GeoDataFrame, tuple, None] = (None,)

abstractmethod post_loading()[source]

class pyorps.WFSVectorDataset(file_source, crs=None, bbox=None, mask=None)[source]

Bases: LocalVectorDataset

_abc_impl = <_abc._abc_data object>

apply_mask()[source]

file_source: Any

load_data(**kwargs)[source]

pyorps.detect_feature_columns(gdf, max_features_per_column=50)[source]

Analyze columns in a geodataframe to identify the best candidates for main_feature and side_features based on statistical metrics.

Parameters:

gdf (GeoDataFrame) – GeoDataFrame to analyze
max_features_per_column (int) – Maximum number of unique values allowed in a
column (categorical)

Return type:

tuple[str, list[str]]

Returns:

tuple of (main_feature, side_features)

Raises:

NoSuitableColumnsError – When no suitable columns are found for feature selection

pyorps.get_zero_cost_assumptions(gdf, main_feature, side_features)[source]

Generate cost assumptions with zero values for all feature combinations.

Creates structures matching format for CostAssumptions: - Without side features: {main_feature: {val1: 0, val2: 0, …}} - With side features: {(main_feature, side_feature1, …): {(val1, val2, …): 0, …}}

Parameters:

gdf (GeoDataFrame) – GeoDataFrame with feature columns
main_feature (str) – Primary feature column name
side_features (list[str]) – List of secondary feature column names

Returns:

Instacne of zero-cost assumptions

Return type:

CostAssumptions

pyorps.initialize_geo_dataset(file_source, crs=None, bbox=None, mask=None, transform=None)[source]

Factory function to create the appropriate GeoDataset instance based on the provided input.

Parameters:

file_source (Union[str, dict, GeoDataFrame, GeoSeries, ndarray]) – Source data (file path, GeoDataFrame, URL dict, numpy array, etc.)
crs (Optional[str]) – Coordinate reference system
bbox (Union[Polygon, GeoDataFrame, GeoSeries, tuple[float, float, float, float], None]) – Bounding box for vector datasets
mask (Union[Polygon, GeoDataFrame, tuple, None]) – Mask for vector datasets
transform (Optional[Affine]) – Affine transform for in-memory raster datasets

Return type:

GeoDataset

Returns:

An appropriate GeoDataset subclass instance

Examples

# From local vector file vector_dataset = create_geo_dataset(“path/to/shapefile.shp”, crs=”EPSG:4326”)

# From GeoDataFrame vector_dataset = create_geo_dataset(gdf, bbox=(x1, y1, x2, y2))

# From WFS source wfs_dataset = create_geo_dataset({“url”: “https://example.com/wfs”,

“layer”: “layer1”})

# From local raster file raster_dataset = create_geo_dataset(“path/to/dem.tif”)

# From numpy array raster_dataset = create_geo_dataset(array_data, transform=transform,

crs=”EPSG:4326”)

pyorps.save_empty_cost_assumptions(geo_dataset, save_path, main_feature=None, side_features=None, file_type='csv', **kwargs)[source]

Generate and save empty cost assumptions with zero values for a geo dataset.

This function analyzes the given dataset to detect appropriate feature columns, creates a CostAssumptions object with zero costs for all feature combinations, and saves it to the specified path in the requested format.

Parameters:

geo_dataset (Any) – GeoDataset object with a ‘data’ attribute containing a GeoDataFrame
save_path (Union[str, Path]) – File path where the cost assumptions should be saved
main_feature (Optional[str]) – Column name for the primary feature
side_features (Optional[list[str]]) – List containing a single column name for the secondary feature
file_type (str) – Output file format - one of ‘json’, ‘csv’, or ‘excel’ (default is ‘json’)

Raises:

TypeError – If file_type is not one of the supported formats
NoSuitableColumnsError – If no suitable columns can be detected in the dataset

Returns:

This function saves to a file and doesn’t return a value

Return type:

None