Python package

Intall the package:

pip install ddc-utility

Submodules

ddc_utility.auth module

class ddc_utility.auth.OAuth2BearerHandler(bearer_token: str, expires_at=None)

Bases: AuthBase

OAuth 2.0 Bearer Token authentication handler

ddc_utility.client module

class ddc_utility.client.BaseClient(client_id: str | None = None, client_secret: str | None = None, host: str | None = None, wait_on_rate_limit: bool | None = False)

Bases: object

request(method: str, route: str, params: Dict | None = None, json_data: Dict | None = None, auth: AuthBase = None, content_type: str | None = None, accept: str | None = None)
class ddc_utility.client.DdcClient(client_id: str | None = None, client_secret: str | None = None, host: str | None = None)

Bases: BaseClient

Represents a Danube Data Cube client.

Parameters:

  • client_id (str) – Danube Data Cube client id. Defaults to None. If None, it will use DDC_CLIENT_ID env variable.

  • client_secret (str) – Danube Data Cube client secret. Defaults to None. If None, it will use DDC_CLIENT_SECRET env variable.

  • host (Optional[str]) – Alternative Danube Data Cube host url. Defaults to None. If None, it will use DEFAULT_DDC_HOST constant.

Examples

Create a DDC Client object for interacting with the DDC service client = DdcClient(<client_id>, <client_secret>)

create_aoi(name: str, geometry: Geometry | Polygon | MultiPolygon | str, time_range: TimeRange | Tuple[Timestamp, Timestamp] | Tuple[str, str], layer_selection_id: int | None = None, layer_ids: List[int] | None = None, is_dynamic: bool = False, output_data_type: int = 1) → DataFrame | Dict

Create an area of interests (AOI).

Parameters:

  • name (str) – The name of the area of interest.

  • geometry (Union[Geometry, Polygon, MultiPolygon, str]) – The geometry of the area of interest in WGS84 coordinate system. This can be provided as a ddc_utility.Geometry object, a shapely.Polygon, a shapely.MultiPolygon, or as a WKT string.

  • time_range (Union[TimeRange, Tuple[pd.Timestamp, pd.Timestamp], Tuple[str, str]]) – The time range for which the area of interest is defined. This can be provided as a ddc_utility.TimeRange object, a tuple of two pandas.Timestamp objects, or a tuple of two strings representing dates.

  • layer_selection_id (Optional[int]) – Layer selection ID. Defaults to None. If both, layer_selection_id and layer_ids are provided, only layer_selection_id will be use.

  • layer_ids (Optional[List[int]]) – List of layer IDs. Defaults to None. If both, layer_selection_id and layer_ids are provided, only layer_selection_id will be use.

  • is_dynamic (bool, optional) – Whether the AOI is dynamic (True) or static (False). Defaults to False.

  • output_data_type (int, optional) – Whether to return the result as a pandas.DataFrame (1) or as a dictionary (2). Defaults to 1.

Returns:

Depending on the output_data_type parameter, this function returns either a pandas.DataFrame or a dictionary containing AOI information.

Return type:

Union[pd.DataFrame, Dict]

Raises:

DdcRequestError – If an error occurs during the process of creating the AOI.

create_crop_type(crop_type_name: str, output_data_type: int = 1) → DataFrame | Dict

Create crop type.

Parameters:

  • crop_type_name (str) – Name of the crop type.

  • output_data_type (int, optional) – Whether to return the result as pandas.DataFrame (1) or as a dictionary(2). Defaults to 1.

Returns:

Depending on the output_data_type parameter, this function returns either a pandas.DataFrame or a dictionary containing crop type information.

Return type:

Union[pd.DataFrame, Dict]

Raises:

DdcRequestError – If an error occurs during the process of creating the crop type.

create_crop_variety(crop_type_id: id, crop_variety_name: str, output_data_type: int = 1) → DataFrame | Dict

Create crop variety.

Parameters:

  • crop_type_id (id) – ID of crop type.

  • crop_variety_name (str) – Name of the crop variety.

  • output_data_type (int, optional) – Whether to return the result as pandas.DataFrame (1) or as a dictionary(2). Defaults to 1.

Returns:

Depending on the output_data_type parameter, this function returns either a pandas.DataFrame or a dictionary containing crop variety information.

Return type:

Union[pd.DataFrame, Dict]

Raises:

DdcRequestError – If an error occurs during the process of creating the crop variety.

create_growing_season(aoi_id: int, time_range: TimeRange | Tuple[Timestamp, Timestamp] | Tuple[str, str], sowing_date: Timestamp | str, crop_type_id: int, crop_variety_id: int, crop_model_id: int, output_data_type: int = 1) → DataFrame | Dict

Create growing season for AOI.

Parameters:

  • aoi_id (int) – ID of the AOI.

  • time_range (Union[TimeRange, Tuple[pd.Timestamp, pd.Timestamp], Tuple[str, str]]) – The time range for which the growing season is defined. This can be provided as a ddc_utility.TimeRange object, a tuple of two pandas.Timestamp objects, or a tuple of two strings representing dates.

  • sowing_date (Union[pd.Timestamp, str]) – The date when the crop is sown.

  • crop_type_id (int) – ID of crop type.

  • crop_variety_id (int) – ID of crop variety.

  • crop_model_id (int) – ID of crop model.

  • output_data_type (int, optional) – Whether to return the result as pandas.DataFrame (1) or as a dictionary(2). Defaults to 1.

Returns:

Depending on the output_data_type parameter, this function returns either a pandas.DataFrame or a dictionary containing growing season information.

Return type:

Union[pd.DataFrame, Dict]

Raises:

DdcRequestError – If an error occurs during the process of creating the growing season.

fetch_temporary_credentials() → Dict

Fetch token from a remote token endpoint.

fetch_token() → Dict

Fetch token from a remote token endpoint.

get_all_aoi(with_geometry: bool = True, output_data_type: int = 1) → DataFrame | List[Dict]

Get user’s all area of interests (AOI).

Parameters:

  • with_geometry (bool, optional) – Whether to retrieve geometry values. Defaults to True.

  • output_data_type (int, optional) – Whether to return the result as pandas.DataFrame (1) or as list of dictionaries (2). Defaults to 1.

Returns:

Depending on the output_data_type parameter, this function returns either a pandas.DataFrame or a list of dictionary containing AOI information.

Return type:

Union[pd.DataFrame, List[Dict]]

Raises:

DdcRequestError – If an error occurs during the process of requesting AOIs.

get_aoi_by_id(aoi_id: int, output_data_type: int = 1) → DataFrame | Dict

Get user’s area of interests (AOI) by ID.

Parameters:

  • aoi_id (int) – ID of the AOI.

  • output_data_type (int, optional) – Whether to return the result as pandas.DataFrame (1) or as a dictionary(2). Defaults to 1.

Returns:

Depending on the output_data_type parameter, this function returns either a pandas.DataFrame or a dictionary containing AOI information.

Return type:

Union[pd.DataFrame, Dict]

Raises:

DdcRequestError – If an error occurs during the process of requesting the AOI.

get_crop_models(crop_type_id: int, output_data_type: int = 1) → DataFrame | List[Dict]

Get available crop model list.

Parameters:

  • crop_type_id (int) – ID of crop type.

  • output_data_type (int, optional) – Whether to return the result as pandas.DataFrame (1) or as a dictionary(2). Defaults to 1.

Returns:

Depending on the output_data_type parameter, this function returns either a pandas.DataFrame or a list of dictionary containing crop model information.

Return type:

Union[pd.DataFrame, List[Dict]]

Raises:

DdcRequestError – If an error occurs during the process of requesting crop models.

get_crop_types(output_data_type: int = 1) → DataFrame | List[Dict]

Get available crop types.

Parameters:

output_data_type (int, optional) – Whether to return the result as pandas.DataFrame (1) or as a dictionary(2). Defaults to 1.

Returns:

Depending on the output_data_type parameter, this function returns either a pandas.DataFrame or a list of dictionary containing crop type information.

Return type:

Union[pd.DataFrame, List[Dict]]

Raises:

DdcRequestError – If an error occurs during the process of requesting crop types.

get_crop_variety(crop_type_id: int, output_data_type: int = 1) → DataFrame | List[Dict]

Get available crop varieties.

Parameters:

  • crop_type_id (int) – ID of crop type.

  • output_data_type (int, optional) – Whether to return the result as pandas.DataFrame (1) or as a dictionary(2). Defaults to 1.

Returns:

Depending on the output_data_type parameter, this function returns either a pandas.DataFrame or a list of dictionary containing crop variety information.

Return type:

Union[pd.DataFrame, List[Dict]]

Raises:

DdcRequestError – If an error occurs during the process of requesting crop variety.

get_data_layers(output_data_type: int = 1) → DataFrame | List[Dict]

Get available data layers.

Parameters:

output_data_type (int, optional) – Whether to return the result as a pandas.DataFrame (1) or as a dictionary (2). Defaults to 1.

Returns:

Depending on the output_data_type parameter, this function returns either a pandas.DataFrame or a dictionary containing data layer information.

Return type:

Union[pd.DataFrame, Dict]

get_data_selections(output_data_type: int = 1) → DataFrame | List[Dict]

Get available data selections.

Parameters:

output_data_type (int, optional) – Whether to return the result as a pandas.DataFrame (1) or as a dictionary (2). Defaults to 1.

Returns:

Depending on the output_data_type parameter, this function returns either a pandas.DataFrame or a dictionary containing data selections information.

Return type:

Union[pd.DataFrame, Dict]

get_growing_season(aoi_id: int, output_data_type: int = 1) → DataFrame | List[Dict]

Get growing seasons for AOI.

Parameters:

  • aoi_id (int) – ID of the AOI.

  • output_data_type (int, optional) – Whether to return the result as pandas.DataFrame (1) or as a dictionary(2). Defaults to 1.

Returns:

Depending on the output_data_type parameter, this function returns either a pandas.DataFrame or a list of dictionary containing growing season information.

Return type:

Union[pd.DataFrame, List[Dict]]

Raises:

DdcRequestError – If an error occurs during the process of requesting growing seasons.

open_aoi_cube(*args, **kwargs)
open_ddc_cube(*args, **kwargs)
run_crop_model(aoi_id: int, time_range: TimeRange | Tuple[Timestamp, Timestamp] | Tuple[str, str], sowing_date: Timestamp | str, irrigation: List[IrrigationSchedule | Tuple[Timestamp | str, float]], init_water_content: float, growing_season_id: int, crop_model_name: str, seasonal_trajectory: bool, soil_type: str, output_data_type: int = 1) → DataFrame | List[Dict]

Run crop model.

Parameters:

  • aoi_id (int) – ID of the AOI.

  • time_range (Union[TimeRange, Tuple[pd.Timestamp, pd.Timestamp], Tuple[str, str]]) – Time range for the simulation.

  • sowing_date (Union[pd.Timestamp, str]) – Sowing date for the simulation.

  • irrigation (List[Union[IrrigationSchedule, Tuple[Union[pd.Timestamp, str], float]]]) – Irrigation schedule for the simulation.

  • init_water_content (float) – Initial water content for the simulation.

  • growing_season_id (int) – ID of the growing season.

  • crop_model_name (str) – Name of the crop model.

  • seasonal_trajectory (bool) – Flag for utilization of CLMS PPI ST in the modelling process

  • soil_type (str) – USDA soil type definition

  • output_data_type (int, optional) – Whether to return the result as pandas.DataFrame (1) or as a dictionary(2). Defaults to 1.

Returns:

Depending on the output_data_type parameter, this function returns either a pandas.DataFrame or a list of dictionary containing crop model information.

Return type:

Union[pd.DataFrame, List[Dict]]

Raises:

DdcRequestError – If an error occurs during the process of running crop model.

ddc_utility.client.authorize_request(method)
ddc_utility.client.authorize_s3_access(method)

ddc_utility.constants module

ddc_utility.cube module

ddc_utility.cube.open_cube(path: str, fs: AbstractFileSystem | AsyncFileSystem = None, group: str = None, mode: str = 'r', **kwargs)

ddc_utility.errors module

exception ddc_utility.errors.BadRequest(response: Response, response_json=None)

Bases: HTTPException

Exception raised for a 400 HTTP status code

exception ddc_utility.errors.DdcClientError(message: str)

Bases: DdcException

Exception raised for client related errors

exception ddc_utility.errors.DdcConfigurationError(message: str)

Bases: DdcException

Exception raised for invalid configuration

exception ddc_utility.errors.DdcException(message: str)

Bases: Exception

Base exception for DDC

exception ddc_utility.errors.DdcRequestError(message: str)

Bases: DdcException

Exception raised for unsuccessful request to remote

exception ddc_utility.errors.Forbidden(response: Response, response_json=None)

Bases: HTTPException

Exception raised for a 403 HTTP status code

exception ddc_utility.errors.HTTPException(response: Response, response_json=None)

Bases: DdcException

Exception raised when an HTTP request fails

response

Requests Response from the Twitter API

Type:

requests.Response | aiohttp.ClientResponse

api_errors

The errors the Twitter API responded with, if any

Type:

list[dict[str, int | str]]

api_codes

The error codes the Twitter API responded with, if any

Type:

list[int]

api_messages

The error messages the Twitter API responded with, if any

Type:

list[str]

exception ddc_utility.errors.NotFound(response: Response, response_json=None)

Bases: HTTPException

Exception raised for a 404 HTTP status code

exception ddc_utility.errors.ServerError(response: Response, response_json=None)

Bases: HTTPException

Exception raised for a 5xx HTTP status code

exception ddc_utility.errors.TooManyRequests(response: Response, response_json=None)

Bases: HTTPException

Exception raised for a 429 HTTP status code

exception ddc_utility.errors.Unauthorized(response: Response, response_json=None)

Bases: HTTPException

Exception raised for a 401 HTTP status code

ddc_utility.logger module

ddc_utility.utils module

class ddc_utility.utils.Geometry(geometry: str | Polygon | MultiPolygon)

Bases: object

“Class for WKT type geometry.

Parameters:

geometry (Union[str, Polygon, MultiPolygon]) – Geometry.

classmethod convert_geometry(geometry: str)

Convert geometry to Shapely object.

property geometry

Return geometry.

to_string()

Return WKT string representation of the geometry.

class ddc_utility.utils.IrrigationSchedule(date: str | Timestamp, amount: float)

Bases: object

“Class for defining irrigation schedule.

Parameters:

  • date (Union[str, pd.Timestamp]) – Irrigation date.

  • amount (float) – Amount of irrigated water in mm.

property amount

Return geometry.

property date

Return geometry.

to_string(only_date=True)

Return the tuple string representation of the object.

class ddc_utility.utils.TimeRange(start_time: str | Timestamp, end_time: str | Timestamp)

Bases: object

“Class for time range represented by two dates.

Parameters:

  • start_time (Union[str, pd.Timestamp]) – Start date.

  • end_time (Union[str, pd.Timestamp]) – End date.

classmethod convert_time(datetime: str | Timestamp, utc: bool = False)

Convert time to pandas Timestamp.

convert_to_full_months()

Convert date to full months. For example, in the case of start time ‘2021-01-04’ to ‘2021-01-01’ or in the case of end time ‘2021-05-15’ to ‘2021-05-31’.

property end_time

Return end time.

property start_time

Return start time.

property time_range

Return time range.

to_string(only_date=True)

Return custom string representation of the time range.

Parameters:

only_date (bool) – Wheter to return only the date part of time range. Defaults to True.

Module contents