:py:mod:`statgis.gee.sample`
============================

.. py:module:: statgis.gee.sample

.. autoapi-nested-parse::

   Sample pixel values from image in a region of interest



Module Contents
---------------


Functions
~~~~~~~~~

.. autoapisummary::

   statgis.gee.sample.sample_image
   statgis.gee.sample.sample_collection



.. py:function:: sample_image(image: ee.Image, geom: ee.Geometry, scale: float, band: str) -> numpy.typing.ArrayLike

   Sample all pixels from an image in the specified band.

   :param image: Image to sample.
   :type image: ee.Image
   :param geom: Region of interest.
   :type geom: ee.Geometry
   :param scale: Scale of image to sample.
   :type scale: float
   :param band: Band of interest.
   :type band: str

   :returns: **data** -- Array with the sampled values.
   :rtype: np.array

   .. rubric:: Example

   >>> import ee
   >>> from statgis.gee import sample, landsat_functions, time_series_analysis
   >>> ee.Initialize()
   >>> roi = ee.Geometry.BBox(-76.6854802, 3.3903932, -76.6904802, 3.3953932)
   >>> landsat_collection = ee.ImageCollection([])
   >>> for code in ["LT05", "LE07", "LC08", "LC09"]:
   ...     landsat_collection = landsat_collection.merge(
   ...         ee.ImageCollection(f"LANDSAT/{code}/C02/T1_L2")
   ...         .filterBounds(roi)
   ...         .filterDate("1995-01-01", "2022-12-31")
   ...         .map(landsat_functions.scaler)
   ...         .map(landsat_functions.cloud_mask)
   ...         .map(landsat_functions.rename_bands)
   ...         .map(lambda img: img.addBands(img.normalizedDifference(["NIR", "RED"]).rename("NDVI")))
   ...     )
   >>> image = landsat_collection.mean()
   >>> mean_ndvi_values = sample.sample_image(image, roi, 30, "NDVI")


.. py:function:: sample_collection(image_collection: ee.ImageCollection, geom: ee.Geometry, scale: float, band: str) -> list

   This function sample all images in an image collection applying the sample_image
   function to all images.

   :param image_collection: Image collection to sample.
   :type image_collection: ee.ImageCollection
   :param geom: Region of interest.
   :type geom: ee.Geometry
   :param scale: Scale of image to sample.
   :type scale: float
   :param band: Band of interest.
   :type band: str

   :returns: **data** -- list of np.array with all the sampled values per image.
   :rtype: list

   .. rubric:: Example

   >>> import ee
   >>> from statgis.gee import sample, landsat_functions, time_series_analysis
   >>> ee.Initialize()
   >>> roi = ee.Geometry.BBox(-76.6854802, 3.3903932, -76.6904802, 3.3953932)
   >>> landsat_collection = ee.ImageCollection([])
   >>> for code in ["LT05", "LE07", "LC08", "LC09"]:
   ...     landsat_collection = landsat_collection.merge(
   ...         ee.ImageCollection(f"LANDSAT/{code}/C02/T1_L2")
   ...         .filterBounds(roi)
   ...         .filterDate("1995-01-01", "2022-12-31")
   ...         .map(landsat_functions.scaler)
   ...         .map(landsat_functions.cloud_mask)
   ...         .map(landsat_functions.rename_bands)
   ...         .map(lambda img: img.addBands(img.normalizedDifference(["NIR", "RED"]).rename("NDVI")))
   ...     )
   >>> annual_ndvi = time_series_analysis.resample(landsat_collection, ee.Reducer.median(), "annual")
   >>> annual_ndvi_values = sample.sample_collection(annual_ndvi, roi, 30, "NDVI")