Module contents

class SuomiGeoData.Paituli[source]

Bases: object

Provides functionality for downloading and extracting data from Paituli (https://paituli.csc.fi/download.html).

dem_clipped_download_by_area(shape_file: str, raster_file: str, http_headers: dict[str, str] | None = None) → str[source]

Downloads the clipped DEM raster file for the given area and returns a confirmation message.

Parameters:

  • shape_file (str) – Shapefile path of the input area.

  • raster_file (str) – File path to save the output raster.

  • http_headers (dict, optional) – HTTP headers to be used for the web request. Defaults to SuomiGeoData.core.Core.default_http_headers attribute if not provided.

Returns:

A confirmation message indicating that the raster clipping is complete.

Return type:

str

dem_clipped_download_by_syke_subcatchment(shape_file: str, level: int, id_subcatchments: list[int], raster_file: str, percentage_cutoff: float = 0, http_headers: dict[str, str] | None = None) → str[source]

Downloads the clipped DEM raster file for the given subcatchment division of Syke and returns a confirmation message.

Parameters:

  • shape_file (str) – Path to the shapefile containing catchment area divisions. This file can be downloaded from: https://wwwd3.ymparisto.fi/d3/gis_data/spesific/valumaalueet.zip

  • level (int) – Level of catchment division and must be one of 1, 2, 3, 4 or 5.

  • id_subcatchments (list) – List of selected integer values from the ‘taso<level>_osai’ column in the shapefile.

  • raster_file (str) – File path to save the output raster.

  • percentage_cutoff (float, optional) – Excludes polygon below the specified area percentage, ranging from 0 to 100, relative to the total area of all polygons. Default is 0, excluding negligible polygons. Provide -1 for no exclusion.

  • http_headers (dict, optional) – HTTP headers to be used for the web request. Defaults to SuomiGeoData.core.Core.default_http_headers attribute if not provided.

Returns:

A confirmation message indicating that the raster clipping is complete.

Return type:

str

dem_download_by_labels(labels: list[str], folder_path: str, http_headers: dict[str, str] | None = None) → str[source]

Downloads the DEM raster files for the given labels and returns a confirmation message.

Parameters:

  • labels (list) – List of label names from the DEM index map.

  • folder_path (str) – Path of empty folder to save the downloaded raster files.

  • http_headers (dict, optional) – HTTP headers to be used for the web request. Defaults to SuomiGeoData.core.Core.default_http_headers attribute if not provided.

Returns:

A confirmation message indicating that all downloads are complete.

Return type:

str

property dem_labels: list[str]

Returns the list of labels from the DEM index map.

dem_labels_download_by_area(shape_file: str, folder_path: str, http_headers: dict[str, str] | None = None) → str[source]

Downloads the DEM raster files for the given area and returns a confirmation message.

Parameters:

  • shape_file (str) – Shapefile path of the input area.

  • folder_path (str) – Path of empty folder to save the downloaded raster files.

  • http_headers (dict, optional) – HTTP headers to be used for the web request. Defaults to SuomiGeoData.core.Core.default_http_headers attribute if not provided.

Returns:

A confirmation message indicating that all downloads are complete.

Return type:

str

property get_example_area: GeoDataFrame

Returns a GeoDataFrame of example area to test raster and vector downloads.

get_tdb_metadata(excel_file: str, http_headers: dict[str, str] | None = None) → DataFrame[source]

Downloads topographic database metadata, converts it to a multi-index DataFrame, and saves it to an Excel file.

Parameters:

  • excel_file (str) – Path to an Excel file to save the DataFrame.

  • http_headers (dict, optional) – HTTP headers to be used for the web request. Defaults to SuomiGeoData.core.Core.default_http_headers attribute if not provided.

Returns:

A multi-index DataFrame of the topographic database metadata.

Return type:

DataFrame

property indexmap_dem: GeoDataFrame

Returns a GeoDataFrame containing the DEM index map.

property indexmap_tdb: GeoDataFrame

Returns a GeoDataFrame containing the topographic database index map.

is_valid_label_dem(label: str) → bool[source]

Returns whether the label exists in the DEM index map.

Parameters:

label (str) – Name of the label.

Returns:

True if the label exists, False otherwise.

Return type:

bool

is_valid_label_tdb(label: str) → bool[source]

Returns whether the label exists in the topographic database index map.

Parameters:

label (str) – Name of the label.

Returns:

True if the label exists, False otherwise.

Return type:

bool

save_indexmap_dem(file_path: str) → str[source]

Saves the GeoDataFrame of the DEM index map to the specified file path and return a success message.

Parameters:

file_path (str) – File path to save the GeoDataFrame.

Returns:

A confirmation message indicating the output file has been saved.

Return type:

str

save_indexmap_tdb(file_path: str) → str[source]

Saves the GeoDataFrame of the topographic database index map to the specified file path and returns a success message.

Parameters:

file_path (str) – File path to save the GeoDataFrame.

Returns:

A confirmation message indicating the output file has been saved.

Return type:

str

select_subcatchments_of_Syke(input_file: str, level: int, id_subcatchments: list[int], output_file: str, percentage_cutoff: float = -1) → GeoDataFrame[source]

Selects subcatchments from the shapefile of Syke’s catachment divisions and returns a GeoDataFrame.

Parameters:

  • input_file (str) – Path to the shapefile containing catchment area divisions. This file can be downloaded from: https://wwwd3.ymparisto.fi/d3/gis_data/spesific/valumaalueet.zip

  • level (int) – Catchment division level, must be one of 1, 2, 3, 4, or 5.

  • id_subcatchments (list) – List of selected integer values from the ‘taso<level>_osai’ column in the shapefile.

  • output_file (str) – Shapefile path to save the output GeoDataFrame.

  • percentage_cutoff (float, optional) – Excludes polygon below the specified area percentage, ranging between 0 to 100, relative to the total area of all polygons. Default is -1 for no exclusion.

Returns:

A GeoDataFrame containing the selected subcatchments.

Return type:

GeoDataFrame

tdb_download_by_labels(labels: list[str], folder_path: str, http_headers: dict[str, str] | None = None) → str[source]

Downloads the topographic database folders of shapefiles for the given labels and returns a confirmation message.

Parameters:

  • labels (list) – List of label names from the topographic database index map.

  • folder_path (str) – Path of empty folder to save the downloaded folder of shapefiles.

  • http_headers (dict, optional) – HTTP headers to be used for the web request. Defaults to SuomiGeoData.core.Core.default_http_headers attribute if not provided.

Returns:

A confirmation message indicating that all downloads are complete.

Return type:

str

tdb_feature_extraction(folder_path: str, class_number: int, shape_file: str) → str[source]

Extracts feature class geometries from the downloaded topographic database label folders for the specified class number and saves the output to a shapefile.

Parameters:

  • folder_path (str) – Folder path containing the downloaded topographic database label folders.

  • class_number (int) – Feature class number in the topographic database meta data, obtained from the SuomiGeoData.Paituli.get_tdb_metadata() method.

  • shape_file (str) – Shapefile path to save the output GeoDataFrame.

Returns:

A confirmation message indicating that the feature class geometry extraction is complete.

Return type:

str

tdb_feature_extraction_by_area(input_file: str, class_number: int, output_file: str, http_headers: dict[str, str] | None = None) → str[source]

Extracts topographic database feature class for the given area and saves the output to a shapefile.

Parameters:

  • input_file (str) – Shapefile path of the input area GeoDataFrame.

  • class_number (int) – Feature class number in the topographic database meta data, obtained from the SuomiGeoData.Paituli.get_tdb_metadata() method.

  • output_file (str) – Shapefile path to save the output GeoDataFrame.

  • http_headers (dict, optional) – HTTP headers to be used for the web request. Defaults to SuomiGeoData.core.Core.default_http_headers attribute if not provided.

Returns:

A confirmation message indicating that the feature class geometry extraction is complete.

Return type:

str

tdb_feature_extraction_by_syke_subcatchment(input_file: str, level: int, id_subcatchments: list[int], class_number: int, output_file: str, percentage_cutoff: float = 0, http_headers: dict[str, str] | None = None) → str[source]

Extracts topographic database feature class for the given subcatchment division of Syke and returns a confirmation message.

Parameters:

  • input_file (str) – Path to the shapefile containing catchment area divisions. This file can be downloaded from: https://wwwd3.ymparisto.fi/d3/gis_data/spesific/valumaalueet.zip

  • level (int) – Level of catchment division and must be one of 1, 2, 3, 4 or 5.

  • id_subcatchments (list) – List of selected integer values from the ‘taso<level>_osai’ column in the shapefile.

  • class_number (int) – Feature class number in the topographic database meta data, obtained from the SuomiGeoData.Paituli.get_tdb_metadata() method.

  • output_file (str) – Shapefile path to save the output GeoDataFrame.

  • percentage_cutoff (float, optional) – Excludes polygon below the specified area percentage, ranging from 0 to 100, relative to the total area of all polygons. Default is 0, excluding negligible polygons. Provide -1 for no exclusion.

  • http_headers (dict, optional) – HTTP headers to be used for the web request. Defaults to SuomiGeoData.core.Core.default_http_headers attribute if not provided.

Returns:

A confirmation message indicating that the GeoDataFrame clipping is complete.

Return type:

str

property tdb_labels: list[str]

Returns the list of labels from the topographic database index map.

tdb_labels_download_by_area(shape_file: str, folder_path: str, http_headers: dict[str, str] | None = None) → str[source]

Downloads the topographic database label folders of shapefiles for the given area and returns a confirmation message.

Parameters:

  • shape_file (str) – Shapefile path of the input area.

  • folder_path (str) – Path of empty folder to save the downloaded folders of shapefiles.

  • http_headers (dict, optional) – HTTP headers to be used for the web request. Defaults to SuomiGeoData.core.Core.default_http_headers attribute if not provided.

Returns:

A confirmation message indicating that all downloads are complete.

Return type:

str