satellitetools.aws ================== .. py:module:: satellitetools.aws .. autoapi-nested-parse:: Module to get Sentinel-2 data from AWS Open data registry, where Sentinel-2 (level 2A) data is available as cloud-optimized geotiffs (https://registry.opendata.aws/sentinel-2-l2a-cogs/). @author: Olli Nevalainen (Finnish Meteorological Institute) Attributes ---------- .. autoapisummary:: satellitetools.aws.logger satellitetools.aws.BUFFER_MULTIPLIER Classes ------- .. autoapisummary:: satellitetools.aws.StrEnum satellitetools.aws.EarthSearchCollection satellitetools.aws.EarthSearch satellitetools.aws.AWSSentinel2DataCollection satellitetools.aws.AWSSentinel2Metadata satellitetools.aws.AWSSentinel2Item Functions --------- .. autoapisummary:: satellitetools.aws.remove_duplicate_items satellitetools.aws.get_xml_metadata satellitetools.aws.get_observation_geometry satellitetools.aws._get_s2_data_single satellitetools.aws._get_scl_data_single satellitetools.aws._multiprocess_get_item_s2_data satellitetools.aws._multiprocess_get_scl_data satellitetools.aws.split_time_range satellitetools.aws.search_s2_cogs satellitetools.aws.cog_get_s2_quality_info satellitetools.aws.cog_get_s2_band_data Module Contents --------------- .. py:class:: StrEnum Bases: :py:obj:`str`, :py:obj:`enum.Enum` str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.__str__() (if defined) or repr(object). encoding defaults to sys.getdefaultencoding(). errors defaults to 'strict'. Initialize self. See help(type(self)) for accurate signature. .. py:data:: logger .. py:data:: BUFFER_MULTIPLIER :value: 8 .. py:class:: EarthSearchCollection Bases: :py:obj:`enum.StrEnum` Enum where members are also (and must be) strings Initialize self. See help(type(self)) for accurate signature. .. py:attribute:: SENTINEL2_C1_L2A :value: 'sentinel-2-c1-l2a' .. py:attribute:: SENTINEL2_L2A :value: 'sentinel-2-l2a' .. py:class:: EarthSearch(datestart: Union[str, pandas.Timestamp, datetime.datetime], dateend: Union[str, pandas.Timestamp, datetime.datetime], bbox: List[float], collection: EarthSearchCollection) Class to handle search for items in EarthSearch. Attributes: ----------- datestart: Union[str, pd.Timestamp, datetime.datetime] Start date for search dateend: Union[str, pd.Timestamp, datetime.datetime] End date for search bbox: List[float] Bounding box coordinates [minx, miny, maxx, maxy] collection: EarthSearchCollection Collection to search limit: int Limit for search results Note: ----- EarthSearch API documentation at: https://earth-search.aws.element84.com/v1/api.html#tag/Item-Search/operation/getItemSearch Initialize EarthSearch object. Parameters: ----------- datestart: Union[str, pd.Timestamp, datetime.datetime] Start date for search dateend: Union[str, pd.Timestamp, datetime.datetime] End date for search bbox: List[float] Bounding box coordinates [minx, miny, maxx, maxy] collection: EarthSearchCollection Collection to search .. py:attribute:: EARTH_SEARCH_ENDPOINT :value: 'https://earth-search.aws.element84.com/v1' .. py:attribute:: DEFAULT_REQUEST_LIMIT :value: 10000 .. py:attribute:: datestart .. py:attribute:: dateend .. py:attribute:: bbox .. py:attribute:: collection .. py:attribute:: limit :value: 10000 .. py:method:: search_collection(datestart: pandas.Timestamp, dateend: pandas.Timestamp, collection: EarthSearchCollection) -> List[pystac.item.Item] Search for items in EarthSearch collection. Parameters: ----------- datestart: pd.Timestamp Start date for search dateend: pd.Timestamp End date for search collection: EarthSearchCollection Collection to search Returns: -------- all_items: List[Item] List of items .. py:method:: get_items() -> List[pystac.item.Item] Get items from EarthSearch. Returns: -------- all_items: List[Item] List of items .. py:function:: remove_duplicate_items(items) -> List[pystac.item.Item] Remove duplicate items from list of items. Parameters: ----------- items: List[Item] List of items Returns: -------- filtered_items: List[Item] Filtered list of items .. py:class:: AWSSentinel2DataCollection(aoi: satellitetools.common.classes.AOI, req_params: satellitetools.common.sentinel2.Sentinel2RequestParams, multiprocessing: Optional[int] = None) Bases: :py:obj:`satellitetools.common.sentinel2.Sentinel2DataCollection` Class to handle Sentinel-2 data from AWS Open data registry. Attributes: ----------- aoi: AOI Area of interest req_params: Sentinel2RequestParams Request parameters s2_items: List[AWSSentinel2Item] List of Sentinel-2 items multiprocessing: Optional[int] Number of processes to use in multiprocessing Initialize AWSSentinel2DataCollection object. Parameters: ----------- aoi: AOI Area of interest req_params: Sentinel2RequestParams Request parameters multiprocessing: Optional[int] Number of processes to use in multiprocessing .. py:attribute:: s2_items :type: List[AWSSentinel2Item] :value: None .. py:attribute:: multiprocessing :value: None .. py:method:: search_s2_items() Search for Sentinel-2 items from AWS Open data registry. .. py:method:: get_quality_info() Get quality information for Sentinel-2 items. .. py:method:: get_s2_data() Get Sentinel-2 data. .. py:class:: AWSSentinel2Metadata(item: pystac.item.Item) Bases: :py:obj:`satellitetools.common.sentinel2.Sentinel2Metadata` Class to handle Sentinel-2 metadata from AWS Open data registry. Attributes: ----------- profiles: Dict[S2Band, dict] Dictionary to store all profiles for bands Initialize AWSSentinel2Metadata object. Parameters: ----------- item: Item Item object from pystac_client .. py:attribute:: profiles :type: Dict[satellitetools.common.sentinel2.S2Band, dict] .. py:method:: get_observation_geometry(item: pystac.item.Item) Get observation geometry for Sentinel-2 item. Parameters: ----------- item: Item Item object from pystac_client .. py:method:: get_reference_band(target_resolution: float) -> satellitetools.common.sentinel2.S2Band .. py:class:: AWSSentinel2Item(item: pystac.item.Item) Bases: :py:obj:`satellitetools.common.sentinel2.Sentinel2Item` Class to handle Sentinel-2 item from AWS Open data registry. Attributes: ----------- source_item: Item Item object from pystac_client Initialize AWSSentinel2Item object. Parameters: ----------- item: Item Item object from pystac_client .. py:attribute:: source_item .. py:method:: get_observation_geometry() Get observation geometry for Sentinel-2 item. .. py:method:: get_band_data(aoi: satellitetools.common.classes.AOI, band: satellitetools.common.sentinel2.S2Band) Get band data for Sentinel-2 item. Parameters: ----------- aoi: AOI Area of interest band: S2Band Sentinel-2 band .. py:method:: get_item_data(aoi: satellitetools.common.classes.AOI, bands: List[satellitetools.common.sentinel2.S2Band], target_resolution: float) Get data for all bands for Sentinel-2 item. Parameters: ----------- aoi: AOI Area of interest bands: List[S2Band] List of Sentinel-2 bands target_resolution: float Target resolution .. py:method:: add_class_percentages() Add class percentages for Sentinel-2 item. Class percentages are calculated based on the SCL band data. .. py:method:: create_coordinates(band: satellitetools.common.sentinel2.S2Band) Create coordinates for Sentinel-2 item. Parameters: ----------- band: S2Band Sentinel-2 band .. py:function:: get_xml_metadata(item: pystac.item.Item) -> Dict Get XML metadata for Sentinel-2 item. Parameters: ----------- item: Item Item object from pystac_client Returns: -------- metadata: Dict XML metadata .. py:function:: get_observation_geometry(item: pystac.item.Item) -> satellitetools.common.sentinel2.Sentinel2ObservationGeometry Get observation geometry for Sentinel-2 item. Parameters: ----------- item: Item Item object from pystac_client Returns: -------- observation_geometry: Sentinel2ObservationGeometry Observation geometry .. py:function:: _get_s2_data_single(s2_item: AWSSentinel2Item, aoi: satellitetools.common.classes.AOI, bands: List[satellitetools.common.sentinel2.S2Band], target_resolution: float) .. py:function:: _get_scl_data_single(s2_item: AWSSentinel2Item, aoi: satellitetools.common.classes.AOI, target_resolution: float) .. py:function:: _multiprocess_get_item_s2_data(s2_items: List[AWSSentinel2Item], aoi: satellitetools.common.classes.AOI, bands: List[satellitetools.common.sentinel2.S2Band], target_resolution: float, processes: int) -> List[AWSSentinel2Item] .. py:function:: _multiprocess_get_scl_data(s2_items: List[AWSSentinel2Item], aoi: satellitetools.common.classes.AOI, target_resolution: float, processes: int) -> List[AWSSentinel2Item] .. py:function:: split_time_range(datestart: pandas.Timestamp, dateend: pandas.Timestamp) -> List[Tuple[pandas.Timestamp, pandas.Timestamp]] Split time range to half year time ranges. Parameters: ----------- datestart: pd.Timestamp Start date dateend: pd.Timestamp End date Returns: -------- time_ranges: List[Tuple[pd.Timestamp, pd.Timestamp]] List of time ranges .. py:function:: search_s2_cogs(aoi: satellitetools.common.classes.AOI, req_params: satellitetools.common.sentinel2.Sentinel2RequestParams) -> List[pystac.item.Item] Search for Sentinel-2 items from AWS Open data registry. Parameters: ----------- aoi: AOI Area of interest req_params: Sentinel2RequestParams Request parameters Returns: -------- items: List[Item] List of Sentinel-2 items .. py:function:: cog_get_s2_quality_info(aoi: satellitetools.common.classes.AOI, req_params: satellitetools.common.sentinel2.Sentinel2RequestParams, items: List[pystac.item.Item]) -> pandas.DataFrame Get quality information for Sentinel-2 items. Parameters: ----------- aoi: AOI Area of interest req_params: Sentinel2RequestParams Request parameters items: List[Item] List of Sentinel-2 items Returns: -------- qi_df: pd.DataFrame Quality information dataframe .. py:function:: cog_get_s2_band_data(aoi: satellitetools.common.classes.AOI, req_params: satellitetools.common.sentinel2.Sentinel2RequestParams, items: List[pystac.item.Item], qi_df: pandas.DataFrame) -> pandas.DataFrame Get Sentinel-2 data. Parameters: ----------- aoi: AOI Area of interest req_params: Sentinel2RequestParams Request parameters items: List[Item] List of Sentinel-2 items qi_df: pd.DataFrame Quality information dataframe Returns: -------- xr_dataset: pd.DataFrame Sentinel-2 data as xarray dataset