refactor files

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
 ====================
@@ -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/dataset.py

@@ -581,7 +581,7 @@
                 dtype=np.float32,
             )
             if mask is not None:
                 df.iloc[0, :] = dst._get_stats(band)
             else:
                 df.iloc[0, :] = self._get_stats(band)
 
@@ -2309,20 +2309,18 @@
     ) -> gdal.Dataset:
         """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.
 
         Parameters
         -----------
-        mask : [string/Dataset]
-            the raster you want to use as a mask to crop other raster,
+        string/Dataset:
+            The raster you want to use as a mask to crop another raster,
             the mask can be also a path or a gdal object.
 
         Returns
         -------
-        dst : [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:
+            The cropped raster.
         """
         # get information from the mask raster
         if isinstance(mask, str):
@@ -2344,12 +2342,13 @@
     def _crop_with_polygon_by_rasterizing(self, poly: GeoDataFrame):
         """cropWithPolygon.
 
-            clip the Raster object using a polygon vector.
+            Clip the Raster object using a polygon vector.
 
         Parameters
         ----------
         poly: [Polygon GeoDataFrame]
             GeodataFrame with a geometry of polygon type.
+
         Returns
         -------
         Dataset
@@ -2385,7 +2384,7 @@
         feature: [FeatureCollection]
                 vector mask.
         touch: [bool]
-            to include the cells that touches the polygon not only those that lies entirely inside the polygon mask.
+            To include the cells that touch the polygon not only those that lie entirely inside the polygon mask.
             Default is True.
 
         Returns
@@ -2421,14 +2420,14 @@
     ):
         """crop.
 
-            clip the Dataset object using a polygon/another raster (both rasters does not have to be aligned).
+            Clip the Dataset object using a polygon/raster.
 
         Parameters
         ----------
-        mask: [Polygon GeoDataFrame/Dataset object]
-            GeodataFrame with a geometry of polygon type
+        mask: [Polygon GeoDataFrame/Dataset]
+            GeodataFrame with a polygon geometry, or a Dataset object.
         touch: [bool]
-            to include the cells that touches the polygon not only those that lies entirely inside the polygon mask.
+            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.
@@ -2458,29 +2457,27 @@
     ) -> np.ndarray:
         """_nearest_neighbour.
 
-            -The _nearest_neighbour method fills the cells with a given indices in rows and cols with the value of the
+            - The _nearest_neighbour method fills the cells with a given indices in rows and cols with the value of the
             nearest neighbour.
-            - Ss the raster grid is square so the 4 perpendicular direction are of the same proximity so the function
+            - Ss the raster grid is square, so the 4 perpendicular directions are of the same proximity, so the function
             gives priority to the right, left, bottom, and then top and the same for 45 degree inclined direction
             right bottom then left bottom then left Top then right Top.
 
         Parameters
         ----------
         array: [numpy.array]
-            Array to fill some of its cells with Nearest value.
+            Array to fill some of its cells with the Nearest value.
         nodatavalue: [float32]
             value stored in cells that is out of the domain
         rows: [List]
-            list of the rows index of the cells you want to fill it with
-            nearest neighbour.
+            list of the rows' index of the cells you want to fill it with the nearest neighbour.
         cols: [List]
-            list of the column index of the cells you want to fill it with
-            nearest neighbour.
+            list of the column index of the cells you want to fill it with the nearest neighbour.
 
         Returns
         -------
         array: [numpy array]
-            Cells of given indices will be filled with value of the Nearest neighbour
+            Cells of given indices will be filled with the value of the Nearest neighbour
 
         Examples
         --------
@@ -4084,20 +4081,17 @@
         gdal_merge.main(parameters)
 
     def apply(self, ufunc: Callable):
-        """folderCalculator.
+        """apply.
 
-        this function matches the location of nodata value from src raster to dst
-        raster
-        Dataset A is where the NoDatavalue will be taken and the location of this value
-        B_input_path is path to the folder where Dataset B exist where  we need to put
-        the NoDataValue of RasterA in RasterB at the same locations
+        apply a function on each raster in the datacube.
 
         Parameters
         ----------
         ufunc: [function]
             callable universal function ufunc (builtin or user defined)
             https://numpy.org/doc/stable/reference/ufuncs.html
-            - to create a ufunc from a normal function (https://numpy.org/doc/stable/reference/generated/numpy.frompyfunc.html)
+            - To create an ufunc from a normal function
+            (https://numpy.org/doc/stable/reference/generated/numpy.frompyfunc.html)
 
         Returns
         -------
@@ -4111,7 +4105,7 @@
         >>> dataset.apply(ufunc)
         """
         if not callable(ufunc):
-            raise TypeError("second argument should be a function")
+            raise TypeError("The Second argument should be a function")
         arr = self.values
         no_data_value = self.base.no_data_value[0]
         # execute the function on each raster

tests/dataset/test_dataset.py

@@ -714,8 +714,8 @@ def test_crop_dataset_with_another_dataset_single_band(
         src_no_data_value: float,
     ):
         mask_obj = Dataset(src)
-        aligned_raster = Dataset(aligned_raster)
-        cropped = aligned_raster._crop_alligned(mask_obj)
+        aligned_raster: Dataset = Dataset(aligned_raster)
+        cropped: Dataset = aligned_raster._crop_alligned(mask_obj)
         dst_arr_cropped = cropped.raster.ReadAsArray()
         # check that all the places of the nodatavalue are the same in both arrays
         src_arr[~np.isclose(src_arr, src_no_data_value, rtol=0.001)] = 5
@@ -731,7 +731,7 @@ def test_crop_dataset_with_another_dataset_multi_band(
         mask_obj = Dataset(sentinel_crop)
         aligned_raster = Dataset(sentinel_raster)
 
-        cropped = aligned_raster._crop_alligned(mask_obj)
+        cropped: Dataset = aligned_raster._crop_alligned(mask_obj)
         dst_arr_cropped = cropped.raster.ReadAsArray()
         # filter the no_data_value out of the array
         arr = dst_arr_cropped[
@@ -787,7 +787,7 @@ def test_inplace(
         crop_by_wrap_touch_true_result: gdal.Dataset,
     ):
         """
-        just check that the inplace option is working
+        Check that the inplace option is working
         """
         dataset = Dataset(rhine_raster)
         cells = dataset.count_domain_cells()
@@ -1319,7 +1319,7 @@ def test_all_bands_with_mask(
         era5_mask: GeoDataFrame,
     ):
         """
-        test the stats function with a mask.
+        Test the stats function with a mask.
         The mask covers only the second row of the array, the test checks if the mean of the second row is equal to the
         mean calculated by the stats function.
         """