update docs

docs/changelog.rst

@@ -3,6 +3,20 @@ Release Notes
 ===============
 
 
+Version 1.1.1
+---------------
+
+* **Release date:** 20-Oct-2024.
+
+* **Feature Additions:** 
+
+    * Extracts feature geometries based on class number from the shapefile folders of topographic database labels.
+    * Downloads feature geometries based on class number located within a given vector format area.
+    * Downloads feature geometries based on class number and Syke's subcatchment identifiers.
+
+* **Documentation:** Added a tutorial on how to use the new features.
+
+
 Version 1.0.1
 ---------------
 

docs/conf.py

@@ -1,6 +1,6 @@
 import os
 import sys
-import sphinx_rtd_theme
+# import sphinx_rtd_theme
 if os.path.abspath('..') in sys.path:
     pass
 else:
@@ -37,10 +37,6 @@
 
 html_theme = 'sphinx_rtd_theme'
 
-html_theme_path = [
-    sphinx_rtd_theme.get_html_theme_path()
-]
-
 html_static_path = [
     '_static'
 ]

docs/dem.rst

@@ -35,8 +35,11 @@ Access the example area and plot it.
 
 .. code-block:: python
 
-    example_area = paituli.get_example_area
-    # for JupyterLab user
+    # save the example area
+    example_gdf = paituli.get_example_area
+    example_file = r"C:\Users\Username\Folder\example.shp"
+    example_gdf.to_file(example_file)
+    # plot the example area
     example_area.iloc[0].geometry
     
 
@@ -52,50 +55,26 @@ Get the clipped DEM for the example area.
 .. code-block:: python
     
     paituli.dem_clipped_download_by_area(
-        input_area=example_area,
+        input_area=example_file,
         output_file=r"C:\Users\Username\Folder\example_area.tif"
     )
-    
-    
-DEM Labels
-------------
-Retrieve the DEM labels for the example area, if required.
 
-.. code-block:: python
-    
-    paituli.dem_labels_download_by_area(
-        input_area=example_area,
-        folder_path=r"C:\Users\Username\Empty_folder_with_no_files"
-    )
-    
     
-DEM from Syke's Catchment Divison
------------------------------------
-Download the vector files of catchment divisions and obtain DEM data from the subcatchment identifier.
+Clipped DEM from Syke's Subcatchment Identifiers
+--------------------------------------------------
+Download the vector files of catchment divisions and obtain DEM data from the subcatchment identifiers.
 
 .. code-block:: python
     
     # download catchment divisions
     syke.download_catchment_divisions_2023(
-        folder_path=r"C:\Users\Username\Folder\Cactment_Folder"
+        folder_path=r"C:\Users\Username\Folder"
     )
     
-    # get clipped DEM from the subcatchment identifier
+    # clipped DEM from the subcatchment identifier
     paituli.dem_clipped_download_by_syke_subcatchment(
-        input_file=r"C:\Users\Username\Folder\Cactment_Folder\catchment_division_level_5.shp",
+        input_file=r"C:\Users\Username\Folder\catchment_division_level_5.shp",
         level=5,
-        single_area=15730216003,
-        output_file=r"C:\Users\Username\Folder\clipped_dem.tif"
+        id_subcatchments=[15730214505, 15730214514],
+        output_file=r"C:\Users\Username\Folder\syke_subcatchment_clipped_dem.tif"
     )
-    
-    # merge mutiple subcatchments that share boundaries and get the clipped DEM
-    msc_gdf = syke.merging_multiple_subcatchments(
-        input_file=r"C:\Users\Username\Folder\Cactment_Folder\catchment_division_level_5.shp",
-        level=5,
-        multiple_area=[15730214505, 15730214514],
-        percentage_cutoff=0 # read about this parameter in the documentation 
-    )
-    paituli.dem_clipped_download_by_area(
-        input_area=msc_gdf,
-        output_file=r"C:\Users\Username\Folder\merged_clipped_dem.tif"
-    )

docs/introduction.rst

@@ -8,18 +8,27 @@ SuomiGeoData is a Python package designed to simplify the process of downloading
 
 * `Paituli integration <https://paituli.csc.fi/download.html>`_
 
-    - Provides access to vector format index maps for downloading DEM and the topographic database.
-    - Downloads DEM as raster files and the topographic database as shapefiles based on label names from the index maps.
-    - Downloads all DEM labels intersected with a given vector format area.
-    - Downloads clipped DEM data that matches a given vector format area.
-    - Downloads topographic database metadata and converts to a readble MultiIndex DataFrame.
+    - Digital Elevation Model (DEM)
+
+        + Provides access to a vector format index map of DEM raster labels.
+        + Downloads DEM raster files based on label names from the index map.
+        + Downloads raster files of all DEM labels intersecting with a given vector format area.
+        + Downloads a clipped DEM raster file that matches a given vector format area.
+
+    - Topograhic Database
+
+        + Provides access to a vector format index map of topographic database labels.
+        + Downloads topographic database folders of shapefiles based on label names from the index map.
+        + Downloads shapefile folders of all topographic database labels intersecting with a given vector format area.
+        + Downloads topographic database metadata containing the name and class number of the geometric features.
+        + Extracts feature geometries based on class number from the shapefile folders.
+        + Downloads feature geometries based on class number located within a given vector format area.
 
 * `SYKE integration <https://www.syke.fi/en-US/Open_information/Spatial_datasets/Downloadable_spatial_dataset>`_
 
     - Downloads CORINE land cover 2018 raster.
-    - Downloads vector files of latest subcatchment divisions, ranging from level 1 to 5.
-    - Extracts individual or merged subcatchments by identifier and uses these areas to download DEM.
+    - Downloads vector files of the latest subcatchment divisions, ranging from level 1 to 5.
+    - Extracts individual or merged subcatchments by identifier number from the vector files.
+    - Downloads clipped DEM raster files by subcatchment identifiers.
+    - Downloads feature geometries based on class number and subcatchment identifiers.
 
-* Geoprocessing
-
-    - Simplified merging and clipping of raster files.

docs/landcover.rst

@@ -23,7 +23,7 @@ Get the land cover map.
 .. code-block:: python
 
     syke.download_corine_land_cover_2018(
-        folder_path=r"C:\Users\Username\Land_cover_folder"
+        folder_path=r"C:\Users\Username\Folder"
     )
     
     
@@ -33,29 +33,18 @@ Get the clipped land cover for the example area.
 
 .. code-block:: python
 
-    # example area
-    example_area = paituli.get_example_area
+    # save the example area
+    example_gdf = paituli.get_example_area
+    example_file = r"C:\Users\Username\Folder\example.shp"
+    example_gdf.to_file(example_file)
     
     # instantiation of Core class
     core = SuomiGeoData.core.Core()
     
     # clipped land cover for the example area
     core.raster_clipping_by_mask(
-        input_file=r"C:\Users\Username\Land_cover_folder\Clc2018_FI20m.tif",
-        mask_area=example_area,
+        input_file=r"C:\Users\Username\Folder\Clc2018_FI20m.tif",
+        mask_file=example_file,
         output_file=r"C:\Users\Username\Folder\example_land_cover.tif"
     )
     
-    # clipped land cover for the example area with buffer
-    example_area['geometry'] = example_area.geometry.buffer(200)
-    core.raster_clipping_by_mask(
-        input_file=r"C:\Users\Username\Land_cover_folder\Clc2018_FI20m.tif",
-        mask_area=example_area,
-        output_file=r"C:\Users\Username\Folder\example_land_cover_buffer.tif"
-    )
-
-
-
-
-
-    

docs/quickstart.rst

@@ -23,10 +23,6 @@ Access and save the DEM index map.
 
     dem_gdf = paituli.indexmap_dem
     dem_gdf.head()
-    # save the map with 'True' message a output
-    paituli.save_indexmap_dem(
-        file_path=r"C:\Users\Username\Folder\indexmap_dem.shp"
-    )
     
 Expected output:
 

docs/requirements-docs.txt

@@ -1,8 +1,7 @@
-sphinx_rtd_theme
-geopandas>=1.0.1
-rasterio>=1.3.11
-requests>=2.32.3
-openpyxl>=3.1.5
-xlsxwriter>=3.2.0
+geopandas
+rasterio
+requests
+openpyxl
+xlsxwriter
 
 

docs/tdb.rst

@@ -13,6 +13,7 @@ Let's start by instantiating the class.
 
     import SuomiGeoData
     paituli = SuomiGeoData.Paituli()
+    syke = SuomiGeoData.Syke()
 
 
 Download by Labels
@@ -21,25 +22,60 @@ Download topographic database shapefiles using label names.
 
 .. code-block:: python
     
-    # download topographic database using labels
+    # download topographic database folders using labels
     paituli.tdb_download_by_labels(
         labels=['K2344R', 'J3224R'], 
         folder_path=r"C:\Users\Username\Folder"
     )
     
     
-Metadata 
------------
-Convert the topographic database metadata into a readable MultiIndex DataFrame.
+Metadata of Feature Class
+---------------------------
+Convert the topographic database metadata into a readable MultiIndex DataFrame 
+for a better understanding of the names and class numbers of geometric features.
 
 .. code-block:: python
 
     paituli.tdb_metadata_to_dataframe(
         excel_file=r"C:\Users\Username\Folder\tdb_metadata.xlsx"
     )
+    
 
+Peatland Drainage Lines by Class Number 
+------------------------------------------
+Get the peatland drainage lines within the example area.
 
+.. code-block:: python
 
+    # save the example area
+    example_gdf = paituli.get_example_area
+    example_file = r"C:\Users\Username\Folder\example.shp"
+    example_gdf.to_file(example_file)
+    
+    # peatland drainage lines for class number 36311
+    paituli.tdb_feature_extraction_by_area(
+        input_file=example_file,
+        class_number=36311,
+        output_file=r"C:\Users\Username\Folder\example_peatland_drainage.shp"
+    )
+    
+    
+Peatland Drainage Lines Syke's Subcatchment Identifiers 
+---------------------------------------------------------
+Get the peatland drainage lines within the example area.
 
-
+.. code-block:: python
     
+    # download catchment divisions
+    syke.download_catchment_divisions_2023(
+        folder_path=r"C:\Users\Username\Folderr"
+    )
+    
+    # peatland drainage lines from the subcatchment identifier
+    paituli.tdb_feature_extraction_by_syke_subcatchment(
+        input_file=r"C:\Users\Username\Folder\catchment_division_level_5.shp",
+        level=5,
+        id_subcatchments=[15730216003],
+        output_file=r"C:\Users\Username\Folder\syke_subcatchment_peatland_drainage.shp"
+    )
+