API Reference

PYORPS - Python for Optimal Routes in Power Systems.

class pyorps.CostAssumptions(source=None)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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')

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)

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')

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)

_abc_impl = <_abc._abc_data object>

crs: Optional[str] = None

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

file_source: Any

abstractmethod load_data(**kwargs)

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

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

Save the rasterized data to a file.

Parameters:

save_path (str) – Path to save the raster file

Return type:

None

shrink_raster(exclude_value)

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)

_abc_impl = <_abc._abc_data object>

load_data(**kwargs)

class pyorps.InMemoryVectorDataset(file_source, crs=None, bbox=None, mask=None)

_abc_impl = <_abc._abc_data object>

apply_bbox()

apply_mask()

correct_crs()

load_data(**kwargs)

post_loading()

class pyorps.LocalRasterDataset(file_source, crs=None)

_abc_impl = <_abc._abc_data object>

load_data(**kwargs)

class pyorps.LocalVectorDataset(file_source, crs=None, bbox=None, mask=None)

_abc_impl = <_abc._abc_data object>

apply_bbox()

apply_mask()

load_data(**kwargs)

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)

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()

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

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)

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)

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()

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)

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)

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)

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)

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)

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()

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

_abc_impl = <_abc._abc_data object>

count: int

dtype: dtype

shape: tuple[int, int]

transform: Affine

class pyorps.VectorDataset(file_source, crs=None, bbox=None, mask=None)

_abc_impl = <_abc._abc_data object>

abstractmethod apply_bbox()

abstractmethod apply_mask()

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

abstractmethod correct_crs()

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

abstractmethod post_loading()

class pyorps.WFSVectorDataset(file_source, crs=None, bbox=None, mask=None)

_abc_impl = <_abc._abc_data object>

apply_mask()

load_data(**kwargs)

pyorps.detect_feature_columns(gdf, max_features_per_column=50)

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)

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)

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)

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