dep_tools.stac_utils module

This module contains classes and functions to aid in STAC Item creation.

class dep_tools.stac_utils.StacCreator(itempath, collection_url_root='https://stac.staging.digitalearthpacific.io/collections', **kwargs)[source]

Bases: Processor

A Processor which creates STAC Items.

This is a wrapper around get_stac_item().

Parameters:

  • itempath (GenericItemPath) – A GenericItemPath used to identify the output.

  • collection_url_root (str) – The collections endpoint of the target STAC catalog.

  • **kwargs – Additional arguments to get_stac_item().

process(data, item_id)[source]

Process the data.

Parameters:

input_data (Any) – Any data.

Return type:

Item | str

dep_tools.stac_utils.get_stac_item(itempath, item_id, data, collection_url_root='https://stac.staging.digitalearthpacific.io/collections', set_geometry_from_input=False, **kwargs)[source]

Create a STAC Item.

This is a wrapper around rio_stac.create_stac_item() which adds the folllowing functionality:

  • It copies information at the “stac_properties” attribute of data to the properties of the output.

  • If the kwargs include “with_raster=True” and data is an xarray.Dataset, raster information is created for each variable.

  • The self href of the output is set, using itempath.stac_path.

Parameters:

  • itempath (GenericItemPath) – The ItemPath for the raster output.

  • item_id (str) – The identifier passed to itempath.path.

  • data (DataArray | Dataset) – The data for which this item is to be created. Anything at the stac_properties attribute will be copied to the properties of the output.

  • collection_url_root (str) – The URL to the collections endpoint where this STAC Item belongs.

  • set_geometry_from_input (bool) – Whether the geometry property should be copied from the stac_properties attribute of data. If this property is missing, a warning is emitted and nothing is set.

  • **kwargs – Additional arguments to rio_stac.create_stac_item().

Return type:

Item

Returns:

A STAC Item.

dep_tools.stac_utils.write_stac_local(item, stac_path)[source]

Writes a STAC Item to a local file.

The item is converted to json with appropriate indentation.

Parameters:

  • item (Item) – A STAC Item.

  • stac_path (str) – The output path.

Return type:

None

dep_tools.stac_utils.existing_stac_items(possible_ids, itempath)[source]

Return the list of input IDs which have an existing STAC Item.

Parameters:

  • possible_ids (list) – Identifiers, each passed as the first argument to itempath.stac_path.

  • itempath (S3ItemPath) – The S3ItemPath which identifies the STAC Items to compare.

Return type:

list

Returns:

A list of IDs, filtered to those for which a STAC Item already exists.

dep_tools.stac_utils.remove_items_with_existing_stac(grid, itempath)[source]

Filter a dataframe to only include items which don’t have an existing stac output.

Parameters:

  • grid (DataFrame) – A DataFram, whose index corresponds to ids for the given itempath.

  • itempath (S3ItemPath) – The S3ItemPath used to identify Items.

Return type:

DataFrame

Returns:

The input DataFrame, only including rows which don’t already have a STAC Item (as identified by the dataframe index).

dep_tools.stac_utils.set_stac_properties(input_xr, output_xr)[source]

Set the “stac_properties” attribute of an Xarray object based on another.

Sets an attribute called “stac_properties” in the output which is a dictionary containing the following properties for use in stac writing: “start_datetime”, “end_datetime”, “datetime”, and “created”. These are set from the input_xr.time coordinate. Typically, input_xr would be an array of EO data (e.g. Landsat) containing data over a range of dates (such as a year).

Parameters:

  • input_xr (DataArray | Dataset) – The object whose time coordinate is used.

  • output_xr (DataArray | Dataset) – The object whose properties are set.

Return type:

Dataset | DataArray

Returns:

output_xr with the “stac_properties” attribute set as described.

dep_tools.stac_utils.copy_stac_properties(item, ds)[source]

Copy properties from an pystac.Item to the attrs of an xarray.Dataset.

Copy item’s properties to ds[“stac_properties”], merging/updating any existing values. Sets ds.attrs[“stac_properties”][“start_datetime”] and ds.attrs[“stac_properties”][“end_datetime”] to item.properties[“datetime”]. Finally, item.geometry is copied to the ds.attrs[“stac_geometry”].

Parameters:

  • item (Item) – A STAC Item.

  • ds (Dataset) – An xarray Dataset.

Return type:

Dataset

Returns:

The input dataset with additional attributes as described above.

dep_tools.stac_utils.use_alternate_s3_href(modifiable)[source]

Fixes the urls in the official USGS Landsat Stac Server (https://landsatlook.usgs.gov/stac-server) so the alternate (s3) urls are used. Can be used like:

client = pystac_client.Client.open(
    "https://landsatlook.usgs.gov/stac-server",
    modifier=use_alternate_s3_href,
)

Modifies in place, according to best practices from https://pystac-client.readthedocs.io/en/stable/usage.html#automatically-modifying-results.

Return type:

None