dataset/crop/feature/crop-all-within-polygon (#71)

* add touch parameter to the crop method

* correct typo in the 'nearest neibour'

* add inplace parameter to the crop method

* add inplace parameter to the crop method

* correct typos

* add mask parameter to the stats method

* refactor files

* update check list files

HISTORY.rst

@@ -10,7 +10,7 @@ History
 0.2.9 (2022-12-19)
 ------------------
 
-* Use environment.yaml and requirements.txt instead of pyproject.toml and replace poetry env byconda env
+* Use environment.yaml and requirements.txt instead of pyproject.toml and replace poetry env by conda env
 
 0.2.10 (2022-12-25)
 ------------------
@@ -37,7 +37,7 @@ History
 0.3.1 (2023-01-25)
 ------------------
 * add pyarrow to use parquet data type for saving dataframes and geodataframes
-* add H3 indexing package, and add new module indexing with functions to convert geometries to indeces back and forth.
+* add H3 indexing package, and add new module indexing with functions to convert geometries to indices back and forth.
 * fix bug in calculating pivot point of the netcdf file
 * rasterToDataFrame function will create geometries of the cells only based on the add_geometry parameter.
 
@@ -70,7 +70,7 @@ History
 * add cluster method to dataset class.
 * time_stamp attribute returns None if there is no time_stamp.
 * restructure the no_data_value related functions.
-* plot function can plot rgb imagr for multi-band rasters.
+* plot function can plot rgb image for multi-band rasters.
 * to_file detect the driver type from the extension in the path.
 
 0.4.2 (2023-04-27)
@@ -84,10 +84,10 @@ History
 ------------------
 Dataset
 """""""
-* The dtype attribure is not initialized in the __init__, but initialized when using the dtype property.
+* The dtype attribute is not initialized in the __init__, but initialized when using the dtype property.
 * Create band_names setter method.
-* add gdal_dtype, numpy_dtype, and dtype arrtibute to change between the dtype (data type general name), and the coresponding data type in numpy and gdal.
-* Create color_table attribure, getter & setter property to set a symbology (assign color to different values in each band).
+* add gdal_dtype, numpy_dtype, and dtype attribute to change between the dtype (data type general name), and the corresponding data type in numpy and gdal.
+* Create color_table attribute, getter & setter property to set a symbology (assign color to different values in each band).
 * The read_array method returns array with the same type as the dtype of the first band in the raster.
 * add a setter method to the band_names property.
 * The methods (create_driver_from_scratch, get_band_names) is converted to private method.
@@ -101,13 +101,13 @@ Dataset
 
 DataCube
 """"""""
-* rename the read_separate_files to read_multiple_files, and enable it to use regex strigs to filter files in a given directory.
+* rename the read_separate_files to read_multiple_files, and enable it to use regex strings to filter files in a given directory.
 * rename read_dataset to open_datacube.
 * rename the data attribute to values
 
 FeatureCollection
 """""""""""""""""
-* Add a pivot_point attribure to return the top left corner/first coordinates of the polygon.
+* Add a pivot_point attribute to return the top left corner/first coordinates of the polygon.
 * Add a layers_count property to return the number of layers in the file.
 * Add a layer_names property to return the layers names.
 * Add a column property to return column names.
@@ -130,3 +130,13 @@ Dataset
 """""""
 * add _iloc method to get the gdal band object by index.
 * add stats method to calculate the statistics of the raster bands.
+
+0.5.3 (2023-12-28)
+------------------
+Dataset
+"""""""
+* Introduce a new parameter touch to the crop method in the Dataset to enable considering the cells that most of the
+cell lies inside the mask, not only the cells that lie entirely inside the mask.
+* Introduce a new parameter inplace to the crop method in the Dataset to enable replacing the dataset object with the
+new cropped dataset.
+* Adjust the stats method to take a mask to calculate the stats inside this mask.

README.md

@@ -46,29 +46,29 @@ Installing pyramids
 Installing `pyramids` from the `conda-forge` channel can be achieved by:
 
 ```
-conda install -c conda-forge pyramids=0.5.2
+conda install -c conda-forge pyramids=0.5.3
 ```
 
-It is possible to list all of the versions of `pyramids` available on your platform with:
+It is possible to list all the versions of `pyramids` available on your platform with:
 
 ```
 conda search pyramids --channel conda-forge
 ```
 
-## Install from Github
+## Install from GitHub
 
-to install the last development to time you can install the library from github
+to install the last development to time, you can install the library from GitHub
 
 ```
 pip install git+https://github.com/Serapieum-of-alex/pyramids
 ```
 
 ## pip
 
-to install the last release you can easly use pip
+to install the last release, you can easily use pip
 
 ```
-pip install pyramids-gis==0.5.2
+pip install pyramids-gis==0.5.3
 ```
 
 Quick start

docs/dataset.rst

@@ -550,6 +550,19 @@ Band statistics (stats)
     >>>     Band_3  273.641479  274.168823  273.953979  0.198447
     >>>     Band_4  273.991516  274.540344  274.310669  0.205754
 
+- The method can also take a mask (polygon/dataset) to calculate the statistics of the masked area only.
+
+.. code:: py
+    era5_image = "tests/data/geotiff/era5_land_monthly_averaged.tif"
+    dataset = Dataset.read_file(era5_image)
+    mask = gpd.read_file("tests/data/geotiff/era5-mask.geojson")
+    stats = dataset.stats(mask=mask)
+    print(stats)
+    >>>                min         max        mean       std
+    >>>     Band_1  270.369720  270.399017  270.384369  0.014648
+    >>>     Band_2  269.651001  269.744751  269.697876  0.046875
+    >>>     Band_3  273.889526  273.901245  273.895386  0.005859
+    >>>     Band_4  274.235657  274.255188  274.245422  0.009766
 
 Write raster to disk
 ====================
@@ -729,7 +742,7 @@ Parameters
     method: [String]
         resampling technique default is "Nearest"
         https://gisgeography.com/raster-resampling/
-        "nearest neibour" for nearest neighbour,"cubic" for cubic convolution,
+        "nearest neigbour" for nearest neighbour,"cubic" for cubic convolution,
         "bilinear" for bilinear
     maintain_alighment : [bool]
         True to maintain the number of rows and columns of the raster the same after re-projection. Default is False.
@@ -772,9 +785,7 @@ crop
 
 Crop array using a raster
 ^^^^^^^^^^^^^^^^^^^^^^^^^
-- `crop` clip/crop (matches the location of nodata value from src raster to dst raster), Both raster's have to
-    have the same dimensions (no of rows & columns) so MatchRasterAlignment should be used prior to this function to
-    align both raster's.
+- The `crop` method clips/crops (matches the location of nodata value from source raster to destination raster).
 
 Parameters
 """"""""""
@@ -790,15 +801,14 @@ Parameters
 Returns
 """""""
     dst: [gdal.dataset]
-        the second raster with NoDataValue stored in its cells
-        exactly the same like src raster
+        the second raster with NoDataValue stored in its cells exactly the same like src raster
 
 
 .. code:: py
 
     aligned_raster = "examples/data/Evaporation_ECMWF_ERA-Interim_mm_daily_2009.01.01.tif"
     band = 1
-    dst = Raster.Open(aligned_raster)
+    dst = Dataset.Open(aligned_raster)
     dst_arr = dst.read_array()
     dst_nodataval = dst.no_data_value[band - 1]
 
@@ -857,27 +867,22 @@ Crop raster using array
 
 crop
 ^^^^
-- `crop` method crops a raster using another raster (both rasters does not have to be aligned).
+- `crop` method crops a raster using another raster/polygon.
 
 Parameters
 """"""""""
-    src: [string/gdal.Dataset]
-        the raster you want to crop as a path or a gdal object
-    mask : [string/gdal.Dataset]
-        the raster you want to use as a mask to crop other raster,
-        the mask can be also a path or a gdal object.
-    output_path : [string]
-        if you want to save the cropped raster directly to disk
-        enter the value of the OutputPath as the path.
-    save : [boolen]
-        True if you want to save the cropped raster directly to disk.
+    mask: [Polygon GeoDataFrame/Dataset]
+            GeodataFrame with a polygon geometry, or a Dataset object.
+    touch: [bool]
+        To include the cells that touch the polygon not only those that lie entirely inside the polygon mask.
+        Default is True.
+    inplace: [bool]
+        True to make the changes in place.
 
 Returns
 """""""
-    dst : [gdal.Dataset]
-        the cropped raster will be returned, if the save parameter was True,
-        the cropped raster will also be saved to disk in the OutputPath
-        directory.
+    Dataset:
+        Dataset object.
 
 
 .. code:: py
@@ -1234,7 +1239,7 @@ color_table
 
 
 - When saving the raster to disk, the following file will be created along side the raster file.
-<RASTER-FILE-NAME.aux.xml>
+    <RASTER-FILE-NAME.aux.xml>
 
 .. code:: xml
 

pyramids/_utils.py

@@ -121,7 +121,7 @@
 )
 
 INTERPOLATION_METHODS = {
-    "nearest neibour": gdal.GRA_NearestNeighbour,
+    "nearest neigbour": gdal.GRA_NearestNeighbour,
     "cubic": gdal.GRA_Cubic,
     "bilinear": gdal.GRA_Bilinear,
 }