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

.. py:module:: statgis.gee.time_series_analysis

.. autoapi-nested-parse::

   Functions to process image collections as time series



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


Functions
~~~~~~~~~

.. autoapisummary::

   statgis.gee.time_series_analysis.extract_dates
   statgis.gee.time_series_analysis.resample
   statgis.gee.time_series_analysis.detrend
   statgis.gee.time_series_analysis.seasonal_decompose



.. py:function:: extract_dates(image_collection: ee.ImageCollection) -> pandas.DatetimeIndex

   Extract dates from all images in an image collection.

   :param image_collection: Collection of image.
   :type image_collection: ee.ImageCollection

   :returns: **dates** -- Series with the dates of the images.
   :rtype: pd.Series

   .. rubric:: Example

   >>> import ee
   >>> from statgis.gee import time_series_analysis
   >>> ee.Initialize()
   >>> chirps = ee.ImageCollection("UCSB-CHG/CHIRPS/DAILY").filterDate("1985-01-01", "2022-12-31")
   >>> dates = time_series_analysis.extract_dates(chirps)


.. py:function:: resample(image_collection: ee.ImageCollection, reducer: ee.Reducer, scale: str) -> ee.ImageCollection

   Function to resample an Image Collection to a fixed timestamp.

   :param image_collection: Image Collection to resample.
   :type image_collection: ee.ImageCollection
   :param reducer: To aggregate the images
   :type reducer: ee.Reducer
   :param scale: Time scale to aggregate the image, must be one from:
                 - annual.
                 - monthly.
                 - monthly-stat.
                 - monthly-stat-repeated.
   :type scale: str

   :returns: **final_collection** -- Collection resampled.
   :rtype: ee.ImageCollection

   .. rubric:: Example

   >>> import ee
   >>> from statgis.gee import time_series_analysis
   >>> ee.Initialize()
   >>> chirps = ee.ImageCollection("UCSB-CHG/CHIRPS/DAILY").filterDate("1985-01-01", "2022-12-31")
   >>> annual_precipitation = time_series_analysis.resample(chirps, ee.Reducer.sum(), "annual")


.. py:function:: detrend(image_collection: ee.ImageCollection, band: str, restore_mean: bool = True) -> ee.ImageCollection

   Calculate the linear trend and seasonality of an image collection.

   :param image_collection: Image collection to remove its trend.
   :type image_collection: ee.ImageCollection
   :param band: Band of interest.
   :type band: str
   :param restore_mean: If `True`, the data mean wil lbe restored in the seasonality.
   :type restore_mean: bool = True

   :returns: **image_collection** -- Image collection with linear trend and seasonality.
   :rtype: ee.ImageCollection

   .. rubric:: Example

   >>> import ee
   >>> from statgis.gee import time_series_analysis
   >>> ee.Initialize()
   >>> chirps = ee.ImageCollection("UCSB-CHG/CHIRPS/DAILY").filterDate("1985-01-01", "2022-12-31")
   >>> annual_precipitation = time_series_analysis.resample(chirps, ee.Reducer.sum(), "annual")
   >>> seasonal_precipitation = time_series_analysis.detrend(annual_precipitation, "precipitation")


.. py:function:: seasonal_decompose(image_collection: ee.ImageCollection, band: str, restore_mean: bool = True) -> ee.ImageCollection

   Seasonal decomposition using the linear trend. This function take an image collection
   and extract the time series components in the specified band.

   :param image_collection: Image collection of interest.
   :type image_collection: ee.ImageCollection
   :param band: Band of interest.
   :type band: str
   :param restore_mean: If `True`, the data mean wil lbe restored in the seasonality.
   :type restore_mean: bool = True

   :returns: **final_collection** -- Image collection with time series components.
   :rtype: ee.ImageCollection

   .. rubric:: Example

   >>> import ee
   >>> from statgis.gee import time_series_analysis
   >>> ee.Initialize()
   >>> chirps = ee.ImageCollection("UCSB-CHG/CHIRPS/DAILY").filterDate("1985-01-01", "2022-12-31")
   >>> monthly_precipitation = time_series_analysis.resample(chirps, ee.Reducer.sum(), "monthly")
   >>> precipitation_ts = time_series_analysis.seasonal_decompose(monthly_precipitation, "precipitation")