sta2stac package#

STA2STAC

A Python Ecosystem for Harvesting Time Series data information from SensorthingsAPI (STA) and Cultivating STAC-Metadata.

class sta2stac.Creator(logger_properties: dict)[source]#

Bases: object

A class to create the STAC-Catalog, STAC-Collection, and STAC-Item. :param logger_properties: A dictionary of logger properties. :type logger_properties: dict

STACCatalog(sta_link: str, stac_id: str, stac_title: str, stac_description: str, stac_dir: str, default_catalog_name: str = 'catalog.json', stac_existance_catalog: bool = False)[source]#: Create the STAC-Catalog.

STACCollection(stac_id: str, stac_title: str, stac_description: str, harvesting_vars: dict, stac_existance_collection: bool, extra_metadata: dict = {}, asset_properties: dict = {})[source]#: Create the STAC-Collection.

STACItem(harvesting_vars: dict, extra_metadata: dict = {}, datacube_extension: bool = False, asset_properties: dict = {}) → None[source]#: Create the STAC-Item.

SaveCatalog(catalog: Catalog, stac_dir: str)[source]#: Save the STAC-Catalog.

class sta2stac.Harvester(logger_properties: dict, harvesting_vars: dict)[source]#

Bases: object

A class to harvest the SensorThings API attributes. :param logger_properties: A dictionary containing the logger properties. :type logger_properties: dict :param harvesting_vars: A dictionary containing the harvesting variables. :type harvesting_vars: dict

harvesting_vars: dict#: A dictionary containing the harvesting variables keys.

item(link: str, version: str, number_of_things: int, requests_properties: dict, item_tuples: list[tuple] = [], datacube_extension: bool = False, filter: str = '')[source]#: Harvest the Things in SensorThings API as STAC-Item.

logger_properties: dict#: A dictionary containing the logger properties.

class sta2stac.ItemInfoHandler(logger_properties: dict = {})[source]#

Bases: object

This class is responsible for managing the STAC item’s metadata. It retrieves the STAC item’s automatically generated ID, title, and description. This class can also sed to override the STAC item’s automatically generated ID, Title, and Description with those specified by the user.

Parameters:: logger_properties (dict) – A dictionary containing the logger properties.

get_entity_tuples_info(sta_link: str, sta_version: str, entity: str, filter: str = '', requests_properties: dict = {})[source]#

Get the STAC item’s automatically generated ID, title, and description.

Parameters:

sta_link (str) – The SensorThings API link.
sta_version (str) – The SensorThings API version.
entity (str) – The SensorThings API entity.
filter (str) – The SensorThings API filter.
requests_properties (dict) – A dictionary containing the requests properties.

get_thing_info(thing_json: dict)[source]#: A function to get the automatically generated ID, title, and description of a specific Thing.

logger_properties: dict#: A dictionary containing the logger properties. By default it sets to None. You can look at keys in Logger class.

replace_item_info(thing_json: dict, item_tuples: list = [])[source]#: A function to replace the automatically generated ID, title, and description of a specific Thing with those specified by the user.

class sta2stac.Processing(logger_properties: dict)[source]#

Bases: object

A class to process the items attributes. For example, it can be used to convert the date-time to the ISO format, convert the bbox to the GeoJSON format, and process the items attributes to create the collection spatial and temporal extent. :param logger_properties: A dictionary containing the logger properties. :type logger_properties: dict

bbox(bbox: list, geometry: str | list)[source]#: Convert the bbox to the GeoJSON format.

collection(date_times_list: list)[source]#: Process the items attributes to create the collection temporal extent.

datetime(date_time: str)[source]#: Convert the date-time to the ISO format.

geometry(bbox: list, geometry_type: str)[source]#: Convert the bbox to the GeoJSON format.

item(harvesting_vars: dict)[source]#: Process the items attributes to create the item temporal extent.

logger_properties: dict#: A dictionary containing the logger properties.

class sta2stac.STA2STAC(sta_link: str, sta_version: str = 'v1.1', stac_dir: str = '/home/docs/checkouts/readthedocs.org/user_builds/sta2stac/checkouts/latest/docs', stac_id: str = 'STA2STAC', stac_title: str = 'STA2STAC', stac_description: str = 'STA2STAC description', stac_existance_catalog: bool = False, stac_existance_collection: bool = False, items_tuples: list[tuple] = [], filter: str = '', default_catalog_name: str = 'catalog.json', datacube_extension: bool = False, extra_metadata: dict = {}, limited_number_of_things: int | None = None, asset_properties: dict = {}, requests_properties: dict = {}, logger_properties: dict = {})[source]#

Bases: object

This class is designed to harvest Time Series data from SensorthingsAPI (STA) and generate STAC-Metadata. In this algorithm, every STA project is treated as a STAC-Collection, and each Thing is considered a STAC-Item.

Parameters:

sta_link (str) – The link of the STA project.
sta_version (str, optional) – The version of the STA project. Defaults to “v1.1”.
stac_dir (str, optional) – The directory of the STAC project. Defaults to current directory.
stac_id (str, optional) – The ID of the STAC Catalog. Defaults to “STA2STAC”. The default value is set to “STA2STAC”. It is important to mention that this ID will also be regarded as the collection ID.
stac_title (str, optional) – The title of the STAC Catalog. The default value is set to “STA2STAC”. It is important to mention that this title will also be regarded as a collection-title.
stac_description (str, optional) – The description of the STAC Catalog. The default value is set to “STA2STAC description”. It is important to mention that this description will also be regarded as a collection-description.
stac_existance_catalog (bool, optional) – If the STAC Catalogue already exists in the specified directory and you do not wish to reharvest the dataset, it should be set to True. By default, the value is set to False.
stac_existance_collection (bool, optional) – If the STAC Collection already exists in the current STAC-Catalog and you want to avoid having to reharvest the dataset, it should be set to True. By default, the value is set to False.
items_tuples (list[tuple], optional) – A list of tuples that includes the auto-ID and user-defined-ID, -title, and -description of each Thing in a STA. To obtain additional information, please refer to the items_tuples. By default, the value is set to None.
filter (str, optional) – A filter for retrieving the refined data from STA.To obtain additional information, please refer to the filter. The default value is None.
default_catalog_name (str, optional) – The name of the STAC Catalog. Defaults to “catalog.json”.
datacube_extension (bool, optional) – To enable the datacube extension for the STAC-Collection, set its value to True. By default, the value is set to False.
extra_metadata (dict, optional) – A dictionary of extra metadata that you desire to include in the STAC-Collection and STAC-Items. To obtain additional information on this topic, please refere to the extra_metadata. The default value is an empty dictionary.
limited_number_of_things (int, optional) – To restrict the quantity of Things in a STA, you can configure it to operate primarily for developmental objectives. By default, the value is set to None.
asset_properties (dict, optional) – A dictionary of assets that you desire to incorporate into the STAC-Collection and STAC-Items. To obtain additional information on this topic, please refere to the asset_properties. The default value is an empty dictionary.
requests_properties (dict, optional) – A dictionary that modify the requests to URLs. To obtain additional information on this topic, refer to the requests_properties. The default value is an empty dictionary.
logger_properties (dict, optional) – A dictionary of attributes that control the logger. To obtain additional information on this topic, please see the documentation for the the logger_properties. The default value is an empty dictionary.

asset_properties: dict#

The assets’ dictionary that is to be added to the STAC-Collection and STAC-Items. It includes the item and collection primary keys. Additionally, both the ‘item’ and ‘collection’ entities comprise the subsequent keys:

item:

thing_json (bool, optional):
If this boolean value is True, the Thing JSON link is added to the STAC-Item as an asset.

all_observations_csv (bool, optional):
If this boolean value is True, the Observation of each Datastreams of the current Thing is appended to the STAC-Item as a CSV link asset.

all_observations_geojson (bool, optional):
If this boolean value is True, the Observation of each Datastreams of the current Thing is appended to the STAC-Item as a GeoJSON link asset.

all_observations_dataarray (bool, optional):
If this boolean value is True, the Observation of each Datastreams of the current Thing is appended to the STAC-Item as a DataArray link asset.

item_observations_csv (bool, optional):
If the boolean value is True, each Datastream’s Observation is separately added as a seperated CSV link asset to the STAC-Item.

item_observations_geojson (bool, optional):
If the boolean value is True, each Datastream’s Observation is separately added as a seperated GeoJSON link asset to the STAC-Item.

item_observations_dataarray (bool, optional):
If the boolean value is True, each Datastream’s Observation is separately added as a seperated DataArray link asset to the STAC-Item.

jupyter_notebook (str, optional):
It is a string that contains the link of the Jupyter Notebook that is related to the current Thing.

exploration (str, optional):
It is a string that contains the link of the interactive map that is related to the current Thing.

collection:

thumbnail (str, optional):
It is a string that contains the link of the thumbnail of the current collection.

jupyter_notebook (str, optional):
It is a string that contains the link of the Jupyter Notebook that is related to the current collection.

exploration (str, optional):
It is a string that contains the link of the interactive map that is related to the current collection.

datacube_extension: bool#: If you want to add the datacube extension to the STAC-Collection, it should be set to True.

default_catalog_name: str#: The name of the STAC Catalog. By default it is catalog.json.

extra_metadata: dict#: A dictionary of extra metadata that you want to add to the STAC-Collection and STAC-Items. It has two main keys, extra_metadata that is boolean and extra_metadata_file that is the address of extra_metadata.json JSON file. For getting more information about making the extra_metadata.json file, please refer to How to create extra_metadata.json file. By default, if ‘extra_metadata’ is set to True, the ‘extra_metadata.json’ file is utilised for the ‘extra_metadata_file’ key, which is situated in the’sta2stac’ main directory.

filter: str | None#

A filter is used to selectively filter the attributes in SensorThingAPI. It is strongly advised to avoid using select and skip filters in order to minimise conflicts when filtering the STA. To obtain additional information on filtering the STA, please visit the following website:

https://fraunhoferiosb.github.io/FROST-Server/sensorthingsapi/requestingData/STA-Filtering.html

items_tuples: list[tuple] | None#: A list of tuples that includes the auto-ID and user-defined-ID, -title, and -description of every Thing in a STA. To define item_tuples, you should first obtain auto-ID information. To achieve this, you can utilise the filter function to obtain the automatically produced ID, title, and description. Afterwards, you can specify your own ID, Title, and Description using the following structure:

limited_number_of_things: int | None#: If you want to limit the number of Things in a STA, you can set it it works more for development purposes.

logger_properties: dict#: A dictionary of properties that adjust the logger. For getting more information about this refer to Logger.

requests_properties: dict#

A dictionary of properties that adjust the requests to URLs. It contains the following keys:

verify (bool, optional):: It is a boolean that if it is True, it verifies the SSL certificate. By default it is False.
timeout (int, optional):: It is an integer that sets the timeout of the requests. By default it is 10 seconds.
auth (tuple, optional):: It is a tuple that contains the username and password for the authentication. By default it is None.

sta_link: str#

The link of the STA project. For example:

https://sensorthings.imk-ifu.kit.edu

sta_version: str#: This is the version of the STA project. The STA2STAC package currently provides support for two distinct versions: v1.0 and v1.1. The format can be defined as either v1.1 or 1.1. It is important to mention that if the version is not accurately specified, it will be considered as v1.1.

stac_description: str#: The description of the STAC Catalog. It is important to mention that this Description will also be regarded as the collection Description.

stac_dir: str#: The directory of the STAC project. By default it is the current directory.

stac_existance_catalog: bool#: It should be set to True if the STAC Catalogue in the specified directory already exists and reharvesting the dataset is not desired.

stac_existance_collection: bool#: It should be set to True if the STAC Collection in the current STAC-Catalog already exists and reharvesting the dataset is not desired.

stac_id: str#: The ID of the STAC Catalog. It is important to mention that this ID will also be regarded as the collection ID.

stac_title: str#: The title of the STAC Catalog. It is important to mention that this Title will also be regarded as the collection Title.

class sta2stac.Utils(logger_properties: dict = {})[source]#

Bases: object

This is a utility class that contains some useful methods. For example, it can be used to open a JSON file, validate the STA link, get the number of entities, get the list of entities, and sanitize the name.

Parameters:: logger_properties (dict) – A dictionary containing the logger properties.

get_list_of_entities_id(link: str, entity: str, filter: str = '', requests_properties: dict = {}) → list[source]#: Get the list of Things in the SensorThings API.

get_number_of_entities(link: str, entity: str, filter: str = '', requests_properties: dict = {}) → int[source]#: Get the number of Things in the SensorThings API.

logger_properties: dict#: A dictionary containing the logger properties. By default it sets to None.

open_json_file(file_path: str) → dict[source]#: Open the JSON file.

open_sta_entity_links(link: str, requests_properties: dict = {}) → dict[source]#: Open the SensorThings API entity.

sanitize_name(string: str) → str[source]#: Making the STAC ID with hyphens.

validate_sta_link(link: str, version: str, filter: str = '', requests_properties: dict = {})[source]#: Validate the SensorThings API link.