Python package

Version: 1.8.0

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

is_expired() → bool

ddc_utility.client module

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

Bases: ABC

fetch_temporary_credentials() → dict: Fetch token from a remote token endpoint.

request(method: str, route: str, params: dict | None = None, data: dict | None = None, content_type: str | None = None, accept: str | None = None) → Response

class ddc_utility.client.DdcClient(client_id: str | None = None, client_secret: str | None = None, host: str | None = None)

Bases: BaseClient

DdcClient class for interacting with the DDC API. Uses client ID and secret for authentication.

client_id

Danube Data Cube client id. If None, it will use DDC_CLIENT_ID env variable. Defaults to None.

Type:: str | None, optional

client_secret

Danube Data Cube client secret. If None, it will use DDC_CLIENT_SECRET env variable. Defaults to None.

Type:: str | None, optional

host

Alternative Danube Data Cube host url. If None, it will use DEFAULT_DDC_HOST constant. Defaults to None.

Type:: str | None, optional

Create an area of interests (AOI).

Parameters:

name (str) – The name of the area of interest.
geometry (Geometry | Polygon | MultiPolygon | str | dict) – 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, a WKT string or as a GeoJson dict.
time_range (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 (int | None, optional) – Layer selection ID. If both, layer_selection_id and layer_ids are provided, only layer_selection_id will be use. Defaults to None.
layer_ids (list[int] | None, optional) – List of layer IDs. If both, layer_selection_id and layer_ids are provided, only layer_selection_id will be use. Defaults to None.
is_dynamic (bool, optional) – Whether the AOI is dynamic (True) or static (False). Defaults to False.
output_data_type (ReturnType | int, optional) – Specifies the format of the returned data, either as a pandas.DataFrame (ReturnType.DATAFRAME) or a list of dictionaries (ReturnType.DICT). Defaults to ReturnType.DATAFRAME.

Returns:

Created AOI information.

Return type:

pd.DataFrame | list[dict]

Raises:

DdcRequestError – If an error occurs during the request process.

create_crop_type(crop_type_name: str, output_data_type: ReturnType | int = ReturnType.DATAFRAME) → DataFrame | list[dict]

Create crop type.

Parameters:

crop_type_name (str) – Name of the crop type.
output_data_type (ReturnType | int, optional) – Specifies the format of the returned data, either as a pandas.DataFrame (ReturnType.DATAFRAME) or a list of dictionaries (ReturnType.DICT). Defaults to ReturnType.DATAFRAME.

Returns:

Created crop type information.

Return type:

pd.DataFrame | list[dict]

Raises:

DdcRequestError – If an error occurs during the request process.

create_crop_variety(crop_type_id: id, crop_variety_name: str, output_data_type: ReturnType | int = ReturnType.DATAFRAME) → DataFrame | list[dict]

Create crop variety for a given crop type.

Parameters:

crop_type_id (id) – ID of crop type.
crop_variety_name (str) – Name of the crop variety.
output_data_type (ReturnType | int, optional) – Specifies the format of the returned data, either as a pandas.DataFrame (ReturnType.DATAFRAME) or a list of dictionaries (ReturnType.DICT). Defaults to ReturnType.DATAFRAME.

Returns:

Created crop variety information.

Return type:

pd.DataFrame | list[dict]

Raises:

DdcRequestError – If an error occurs during the request process.

Create growing season for AOI.

Parameters:

aoi_id (int) – ID of the AOI.
time_range (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 (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.
name (str) – name of the growing season
geometry (Geometry | Polygon | MultiPolygon | str | dict) – The geometry of the growing season in WGS84 coordinate system. This can be provided as a ddc_utility.Geometry object, a shapely.Polygon, a shapely.MultiPolygon, a WKT string or as a GeoJson dict. Must be within the parent AOI’s geometry.
crop_yield (float, optional) – Amount of crop yield (default is 0)
insured_yield (float, optional) – Amount of insured yield (default is 0)
output_data_type (ReturnType | int, optional) – Specifies the format of the returned data, either as a pandas.DataFrame (ReturnType.DATAFRAME) or a list of dictionaries (ReturnType.DICT). Defaults to ReturnType.DATAFRAME.

Returns:

Created growing season information.

Return type:

pd.DataFrame | list[dict]

Raises:

DdcRequestError – If an error occurs during the request process.

delete_aoi(aoi_id: int) → DataFrame | list[dict]

Delete AOI.

Parameters:: aoi_id (int) – ID of the AOI.
Returns:: None.
Raises:: DdcRequestError – If an error occurs during the request process.

delete_growing_season(growing_season_id: int) → DataFrame | list[dict]

Delete growing season.

Parameters:: growing_season_id (int) – ID of the growing season.
Returns:: None.
Raises:: DdcRequestError – If an error occurs during the request process.

fetch_token() → AccesToken: Fetch token from a remote token endpoint.

get_all_aoi(with_geometry: bool = True, output_data_type: ReturnType | int = ReturnType.DATAFRAME, limit: int | None = None, offset: int | None = None) → DataFrame | list[dict]

Retrieve all areas of interests (AOI) for the user.

If both “limit” and “offset” arguments are None, it retrieves all records using paginated requests.

Parameters:

with_geometry (bool, optional) – Indicates whether to include geometry data. Defaults to True.
output_data_type (ReturnType | int, optional) – Specifies the format of the returned data, either as a pandas.DataFrame (ReturnType.DATAFRAME) or a list of dictionaries (ReturnType.DICT). Defaults to ReturnType.DATAFRAME.
limit (int | None, optional) – Maximum number of records to retrieve. Defaults to None (API will use the default value).
offset (int | None, optional) – Number of records to skip before starting to collect the result set. Defaults to None (API will use the default value).

Returns:

AOIs information.

Return type:

pd.DataFrame | list[dict]

Raises:

DdcRequestError – If an error occurs during the request process.

get_aoi_by_id(aoi_id: int, output_data_type: ReturnType | int = ReturnType.DATAFRAME) → DataFrame | list[dict]

Retrieve an areas of interests (AOI) for the user by ID.

Parameters:

aoi_id (int) – ID of the AOI.
output_data_type (ReturnType | int, optional) – Specifies the format of the returned data, either as a pandas.DataFrame (ReturnType.DATAFRAME) or a list of dictionaries (ReturnType.DICT). Defaults to ReturnType.DATAFRAME.

Returns:

AOI information.

Return type:

pd.DataFrame | list[dict]

Raises:

DdcRequestError – If an error occurs during the request process.

Retrieve available crop model list.

Parameters:

crop_type_id (int | None, optional) – ID used to filter by the specified crop type.
output_data_type (ReturnType | int, optional) – Specifies the format of the returned data, either as a pandas.DataFrame (ReturnType.DATAFRAME) or a list of dictionaries (ReturnType.DICT). Defaults to ReturnType.DATAFRAME.
limit (int | None, optional) – Maximum number of records to retrieve. Defaults to None (API will use the default value).
offset (int | None, optional) – Number of records to skip before starting to collect the result set. Defaults to None (API will use the default value).

Returns:

Available crop models information.

Return type:

pd.DataFrame | list[dict]

Raises:

DdcRequestError – If an error occurs during the request process.

get_crop_types(output_data_type: ReturnType | int = ReturnType.DATAFRAME, limit: int | None = None, offset: int | None = None) → DataFrame | list[dict]

Retrieve available crop types.

Parameters:

output_data_type (ReturnType | int, optional) – Specifies the format of the returned data, either as a pandas.DataFrame (ReturnType.DATAFRAME) or a list of dictionaries (ReturnType.DICT). Defaults to ReturnType.DATAFRAME.
limit (int | None, optional) – Maximum number of records to retrieve. Defaults to None (API will use the default value).
offset (int | None, optional) – Number of records to skip before starting to collect the result set. Defaults to None (API will use the default value).

Returns:

Available crop types information.

Return type:

pd.DataFrame | list[dict]

Raises:

DdcRequestError – If an error occurs during the request process.

get_crop_variety(crop_type_id: int, output_data_type: ReturnType | int = ReturnType.DATAFRAME, limit: int | None = None, offset: int | None = None) → DataFrame | list[dict]

Retrieve available crop varieties.

Parameters:

crop_type_id (int) – ID of crop type.
output_data_type (ReturnType | int, optional) – Specifies the format of the returned data, either as a pandas.DataFrame (ReturnType.DATAFRAME) or a list of dictionaries (ReturnType.DICT). Defaults to ReturnType.DATAFRAME.
limit (int | None, optional) – Maximum number of records to retrieve. Defaults to None (API will use the default value).
offset (int | None, optional) – Number of records to skip before starting to collect the result set. Defaults to None (API will use the default value).

Returns:

Available crop variety information.

Return type:

pd.DataFrame | list[dict]

Raises:

DdcRequestError – If an error occurs during the request process.

get_cube_data_by_aoi(aoi_id: int, data_var: str, date: Timestamp | str | None, zone: bool = False, geometry_type: str = 'Polygon', output_data_type: ReturnType | int = ReturnType.DATAFRAME) → DataFrame | list[dict]

Retrieve data from the specified data-cube.

Parameters:

aoi_id (int) – ID of the AOI to specify the data-cube.
data_var (str) – Name of the data variable
date (Timestamp | str | None) – Date used to narrow the dataset
zone (bool) – If True, returns zones instead of polygons (works with “Polygon” type geometry)
geometry_type (string) – Specify the type of the returned geometries
output_data_type (ReturnType | int, optional) – Specifies the format of the returned data, either as a pandas.DataFrame (ReturnType.DATAFRAME) or a list of dictionaries (ReturnType.DICT). Defaults to ReturnType.DATAFRAME.

Returns:

Available data information.

Return type:

pd.DataFrame | list[dict]

Raises:

DdcRequestError – If an error occurs during the request process.

get_cube_data_by_growing_season(gs_id: int, data_var: str, date: Timestamp | str | None, zone: bool = False, geometry_type: str = 'Polygon', output_data_type: ReturnType | int = ReturnType.DATAFRAME) → DataFrame | list[dict]

Retrieve data from the specified data-cube.

Parameters:

gs_id (int) – ID of the growing season to specify the data-cube.
data_var (str) – Name of the data variable
date (Timestamp | str | None) – Date used to narrow the dataset
zone (bool) – If True, returns zones instead of polygons (works with “Polygon” type geometry)
geometry_type (string) – Specify the type of the returned geometries
output_data_type (ReturnType | int, optional) – Specifies the format of the returned data, either as a pandas.DataFrame (ReturnType.DATAFRAME) or a list of dictionaries (ReturnType.DICT). Defaults to ReturnType.DATAFRAME.

Returns:

Available data information.

Return type:

pd.DataFrame | list[dict]

Raises:

DdcRequestError – If an error occurs during the request process.

get_cube_meta_data_by_aoi(aoi_id: int, output_data_type: ReturnType | int = ReturnType.DATAFRAME) → DataFrame | list[dict]

Retrieve meta data of the specified data-cube.

Parameters:

aoi_id (int) – ID of the AOI to specify the data-cube.
output_data_type (ReturnType | int, optional) – Specifies the format of the returned data, either as a pandas.DataFrame (ReturnType.DATAFRAME) or a list of dictionaries (ReturnType.DICT). Defaults to ReturnType.DATAFRAME.

Returns:

Available meta data information.

Return type:

pd.DataFrame | list[dict]

Raises:

DdcRequestError – If an error occurs during the request process.

get_cube_meta_data_by_growing_season(gs_id: int, output_data_type: ReturnType | int = ReturnType.DATAFRAME) → DataFrame | list[dict]

Retrieve meta data of the specified data-cube.

Parameters:

gs_id (int) – ID of the growing season to specify the data-cube.
output_data_type (ReturnType | int, optional) – Specifies the format of the returned data, either as a pandas.DataFrame (ReturnType.DATAFRAME) or a list of dictionaries (ReturnType.DICT). Defaults to ReturnType.DATAFRAME.

Returns:

Available meta data information.

Return type:

pd.DataFrame | list[dict]

Raises:

DdcRequestError – If an error occurs during the request process.

get_data_layers(output_data_type: ReturnType | int = ReturnType.DATAFRAME, limit: int | None = None, offset: int | None = None) → DataFrame | list[dict]

Retrieve available data layers.

If both “limit” and “offset” arguments are None, it retrieves all records using paginated requests.

Parameters:

output_data_type (ReturnType | int, optional) – Specifies the format of the returned data, either as a pandas.DataFrame (ReturnType.DATAFRAME) or a list of dictionaries (ReturnType.DICT). Defaults to ReturnType.DATAFRAME.
limit (int | None, optional) – Maximum number of records to retrieve. Defaults to None (API will use the default value).
offset (int | None, optional) – Number of records to skip before starting to collect the result set. Defaults to None (API will use the default value).

Returns:

Available data layers information.

Return type:

pd.DataFrame | list[dict]

Raises:

DdcRequestError – If an error occurs during the request process.

Retrieve available data selections.

If both “limit” and “offset” arguments are None, it retrieves all records using paginated requests.

Parameters:

data_layer_selection_id (int | None, optional) – if provided, it returns a custom data selection that only includes those data collections containing the data layers specified in the given data layer selection.
layer_ids (list[int] | None, optional) – if provided, it returns a custom data selection that only includes those data collections containing the given data layers.
geometry (Geometry | Polygon | MultiPolygon | str | dict | None, optional) – if provided, the data layer selections will be filtered not only by the “EU” and “WORLD” geographic identifiers, but also by the country corresponding to the given geometry.
output_data_type (ReturnType | int, optional) – Specifies the format of the returned data, either as a pandas.DataFrame (ReturnType.DATAFRAME) or a list of dictionaries (ReturnType.DICT). Defaults to ReturnType.DATAFRAME.
limit (int | None, optional) – Maximum number of records to retrieve. Defaults to None (API will use the default value).
offset (int | None, optional) – Number of records to skip before starting to collect the result set. Defaults to None (API will use the default value).

Returns:

Available data selections information.

Return type:

pd.DataFrame | list[dict]

Raises:

DdcRequestError – If an error occurs during the request process.

Retrieve growing seasons for AOI.

Parameters:

aoi_id (int | None, optional) – ID of the AOI to filter
output_data_type (ReturnType | int, optional) – Specifies the format of the returned data, either as a pandas.DataFrame (ReturnType.DATAFRAME) or a list of dictionaries (ReturnType.DICT). Defaults to ReturnType.DATAFRAME.
limit (int | None, optional) – Maximum number of records to retrieve. Defaults to None (API will use the default value).
offset (int | None, optional) – Number of records to skip before starting to collect the result set. Defaults to None (API will use the default value).

Returns:

Growing season information.

Return type:

pd.DataFrame | list[dict]

Raises:

DdcRequestError – If an error occurs during the request process.

get_growing_season_by_id(growing_season_id: int, output_data_type: ReturnType | int = ReturnType.DATAFRAME) → DataFrame | list[dict]

Retrieve an growing season for the user by ID.

Parameters:

growing_season_id (int) – ID of the growing season.
output_data_type (ReturnType | int, optional) – Specifies the format of the returned data, either as a pandas.DataFrame (ReturnType.DATAFRAME) or a list of dictionaries (ReturnType.DICT). Defaults to ReturnType.DATAFRAME.

Returns:

growing season information.

Return type:

pd.DataFrame | list[dict]

Raises:

DdcRequestError – If an error occurs during the request process.

Returns a time series contains the average values of the selected layer for the given AOI.

Parameters:

aoi_id (int) – ID of the AOI.
data_layer (str) – Name of the data layer
start_date (Timestamp | str | None) – Start date used to narrow the dataset
end_date (Timestamp | str | None) – Start date used to narrow the dataset
output_data_type (ReturnType | int, optional) – Specifies the format of the returned data, either as a pandas.DataFrame (ReturnType.DATAFRAME) or a list of dictionaries (ReturnType.DICT). Defaults to ReturnType.DATAFRAME.
limit (int | None, optional) – Maximum number of records to retrieve. Defaults to None (API will use the default value).
offset (int | None, optional) – Number of records to skip before starting to collect the result set.

Returns:

Available data information.

Return type:

pd.DataFrame | list[dict]

Raises:

DdcRequestError – If an error occurs during the request process.

Returns a time series contains the average values of the selected layer for the given growing season.

Parameters:

gs_id (int) – ID of the growing season.
data_layer (str) – Name of the data layer
start_date (Timestamp | str | None) – Start date used to narrow the dataset
end_date (Timestamp | str | None) – Start date used to narrow the dataset
output_data_type (ReturnType | int, optional) – Specifies the format of the returned data, either as a pandas.DataFrame (ReturnType.DATAFRAME) or a list of dictionaries (ReturnType.DICT). Defaults to ReturnType.DATAFRAME.
limit (int | None, optional) – Maximum number of records to retrieve. Defaults to None (API will use the default value).
offset (int | None, optional) – Number of records to skip before starting to collect the result set.

Returns:

Available data information.

Return type:

pd.DataFrame | list[dict]

Raises:

DdcRequestError – If an error occurs during the request process.

Returns aggregated historic weather data for the given AOI.

Parameters:

aoi_id (int) – ID of the AOI.
crop_type (str) – Name of the crop type
start_date (Timestamp | str | None) – Start date used to narrow the dataset
end_date (Timestamp | str | None) – Start date used to narrow the dataset
output_data_type (ReturnType | int, optional) – Specifies the format of the returned data, either as a pandas.DataFrame (ReturnType.DATAFRAME) or a list of dictionaries (ReturnType.DICT). Defaults to ReturnType.DATAFRAME.
limit (int | None, optional) – Maximum number of records to retrieve. Defaults to None (API will use the default value).
offset (int | None, optional) – Number of records to skip before starting to collect the result set.

Returns:

Available data information.

Return type:

pd.DataFrame | list[dict]

Raises:

DdcRequestError – If an error occurs during the request process.

Returns aggregated historic weather data for the given growing season.

Parameters:

gs_id (int) – ID of the growing season.
crop_type (str) – Name of the crop type
start_date (Timestamp | str | None) – Start date used to narrow the dataset
end_date (Timestamp | str | None) – Start date used to narrow the dataset
output_data_type (ReturnType | int, optional) – Specifies the format of the returned data, either as a pandas.DataFrame (ReturnType.DATAFRAME) or a list of dictionaries (ReturnType.DICT). Defaults to ReturnType.DATAFRAME.
limit (int | None, optional) – Maximum number of records to retrieve. Defaults to None (API will use the default value).
offset (int | None, optional) – Number of records to skip before starting to collect the result set.

Returns:

Available data information.

Return type:

pd.DataFrame | list[dict]

Raises:

DdcRequestError – If an error occurs during the request process.

Returns historic weather data for the given AOI.

Parameters:

aoi_id (int) – ID of the AOI.
start_date (Timestamp | str | None) – Start date used to narrow the dataset
end_date (Timestamp | str | None) – Start date used to narrow the dataset
output_data_type (ReturnType | int, optional) – Specifies the format of the returned data, either as a pandas.DataFrame (ReturnType.DATAFRAME) or a list of dictionaries (ReturnType.DICT). Defaults to ReturnType.DATAFRAME.
limit (int | None, optional) – Maximum number of records to retrieve. Defaults to None (API will use the default value).
offset (int | None, optional) – Number of records to skip before starting to collect the result set.

Returns:

Available data information.

Return type:

pd.DataFrame | list[dict]

Raises:

DdcRequestError – If an error occurs during the request process.

Returns historic weather data for the given growing season.

Parameters:

gs_id (int) – ID of the growing season .
start_date (Timestamp | str | None) – Start date used to narrow the dataset
end_date (Timestamp | str | None) – Start date used to narrow the dataset
output_data_type (ReturnType | int, optional) – Specifies the format of the returned data, either as a pandas.DataFrame (ReturnType.DATAFRAME) or a list of dictionaries (ReturnType.DICT). Defaults to ReturnType.DATAFRAME.
limit (int | None, optional) – Maximum number of records to retrieve. Defaults to None (API will use the default value).
offset (int | None, optional) – Number of records to skip before starting to collect the result set.

Returns:

Available data information.

Return type:

pd.DataFrame | list[dict]

Raises:

DdcRequestError – If an error occurs during the request process.

Returns historic weather data for the given location.

Parameters:

lat (float) – Latitude
lon (float) – Longitude
start_date (Timestamp | str | None) – Start date used to narrow the dataset
end_date (Timestamp | str | None) – Start date used to narrow the dataset
output_data_type (ReturnType | int, optional) – Specifies the format of the returned data, either as a pandas.DataFrame (ReturnType.DATAFRAME) or a list of dictionaries (ReturnType.DICT). Defaults to ReturnType.DATAFRAME.
limit (int | None, optional) – Maximum number of records to retrieve. Defaults to None (API will use the default value).
offset (int | None, optional) – Number of records to skip before starting to collect the result set.

Returns:

Available data information.

Return type:

pd.DataFrame | list[dict]

Raises:

DdcRequestError – If an error occurs during the request process.

open_aoi_cube(aoi_id: int, bucket_name: str = 'ddc-aoicube-data', group: str | None = None) → Dataset

Open AOI cube as an xarray.Dataset.

Parameters:

aoi_id (int) – ID of the AOI.
bucket_name (str, optional) – Name of the S3 bucket where the zarr cube is stored. Defaults to DEFAULT_AOI_BUCKET.
group (str, optional) – Zarr group of the dataset. Defaults to None.

Returns:

AOI dataset.

Return type:

xr.Dataset

Raises:

DdcClientError – If user don’t have access to the bucket.
DdcRequestError – If an error occurs during opening the cube.

open_ddc_cube(zarr_path: str, zarr_group: str | None = None, bucket_name: str = 'ddc-environmental-data') → Dataset

Open DDC dataset as an xarray.Dataset.

Parameters:

zarr_path (str) – Zarr path to the dataset.
zarr_group (str, optional) – Zarr group of the dataset.
bucket_name (str, optional) – Name of the S3 bucket where the zarr cube is stored. Defaults to DEFAULT_DDC_BUCKET.

Returns:

DDC dataset.

Return type:

xr.Dataset

Raises:

DdcClientError – If user don’t have access to the bucket.
DdcRequestError – If an error occurs during opening the cube.

open_growing_season_cube(growing_season_id: int, bucket_name: str = 'ddc-aoicube-data', group: str | None = None) → Dataset

Open growing season cube as an xarray.Dataset.

Parameters:

growing_season_id (int) – ID of the growing season.
bucket_name (str, optional) – Name of the S3 bucket where the zarr cube is stored. Defaults to DEFAULT_AOI_BUCKET.
group (str, optional) – Zarr group of the dataset. Defaults to None.

Returns:

Growing season dataset.

Return type:

xr.Dataset

Raises:

DdcClientError – If user don’t have access to the bucket.
DdcRequestError – If an error occurs during opening the cube.

run_crop_model(growing_season_id: int, init_water_content: float | None = None, soil_type: str | None = None, irrigation: list[tuple] | None = None, simulation: int = 0, use_calibration: bool = True, return_growth_stages: bool = False, output_data_type: ReturnType | int = ReturnType.DATAFRAME) → DataFrame | list[dict]

Run crop model.

Parameters:

growing_season_id (int) – ID of the growing season.
init_water_content (float | None, optional) – Initial water content for the simulation.
soil_type (str | None, optional) – USDA soil type definition
irrigation (list | None, optional) – Irrigation schedule for the simulation in [(date, value), … ,(date, value)] format. Dates are expecetd to be in YYYY-mm-dd format. Values are in mm.
simulation – (int): type of simulation (0: average, 1: best, 2: worst)
use_calibration (bool) – whether calibration data should be used
return_growth_stages – whether the result should contains the growing steps
output_data_type (ReturnType | int, optional) – Specifies the format of the returned data, either as a pandas.DataFrame (ReturnType.DATAFRAME) or a list of dictionaries (ReturnType.DICT). Defaults to ReturnType.DATAFRAME.

Returns:

Crop model run information.

Return type:

pd.DataFrame | list[dict]

Raises:

DdcRequestError – If an error occurs during the request process.

run_crop_model_yield_potential(growing_season_id: int, init_water_content: float | None = None, soil_type: str | None = None, irrigation: list[tuple] | None = None, use_calibration: bool = True, output_data_type: ReturnType | int = ReturnType.DATAFRAME) → DataFrame | list[dict]

Run yield potential crop model function.

Parameters:

growing_season_id (int) – ID of the growing season.
init_water_content (float | None, optional) – Initial water content for the simulation.
soil_type (str | None, optional) – USDA soil type definition
irrigation (list | None, optional) – Irrigation schedule for the simulation in [(date, value), … ,(date, value)] format. Dates are expecetd to be in YYYY-mm-dd format. Values are in mm.
use_calibration (bool) – whether calibration data should be used
output_data_type (ReturnType | int, optional) – Specifies the format of the returned data, either as a pandas.DataFrame (ReturnType.DATAFRAME) or a list of dictionaries (ReturnType.DICT). Defaults to ReturnType.DATAFRAME.

Returns:

Crop model run information.

Return type:

pd.DataFrame | list[dict]

Raises:

DdcRequestError – If an error occurs during the request process.

Update growing season.

Parameters:

growing_season_id (int) – ID of the growing season.
time_range (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 (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.
name (str) – name of the growing season
geometry (Geometry | Polygon | MultiPolygon | str | dict) – The geometry of the growing season in WGS84 coordinate system. This can be provided as a ddc_utility.Geometry object, a shapely.Polygon, a shapely.MultiPolygon, a WKT string or as a GeoJson dict. Must be within the parent AOI’s geometry.
crop_yield (float, optional) – Amount of crop yield (default is None)
output_data_type (ReturnType | int, optional) – Specifies the format of the returned data, either as a pandas.DataFrame (ReturnType.DATAFRAME) or a list of dictionaries (ReturnType.DICT). Defaults to ReturnType.DATAFRAME.

Returns:

Created growing season information.

Return type:

pd.DataFrame | list[dict]

Raises:

DdcRequestError – If an error occurs during the request process.

class ddc_utility.client.IntegrationClient(bearer_token: str, expires_in: int, host: str | None = None)

Bases: BaseClient

IntegrationClient class for interacting with the DDC API. Uses a Bearer token for authentication.

bearer_token

Bearer token.

Type:: str

expires_in

Token expiration timestamp

Type:: int

host

Alternative Danube Data Cube host url. If None, it will use DEFAULT_DDC_HOST constant. Defaults to None.

Type:: str | None, optional

open_growing_season_cube(growing_season_id: int, bucket_name: str = 'ddc-aoicube-data', group: str | None = None) → Dataset

Open growing season cube as an xarray.Dataset.

Parameters:

growing_season_id (int) – ID of the growing season.
bucket_name (str, optional) – Name of the S3 bucket where the zarr cube is stored. Defaults to DEFAULT_AOI_BUCKET.
group (str, optional) – Zarr group of the dataset. Defaults to None.

Returns:

Growing season dataset.

Return type:

xr.Dataset

Raises:

DdcClientError – If user don’t have access to the bucket.
DdcRequestError – If an error occurs during opening the cube.

class ddc_utility.client.ReturnType(*values)

Bases: Enum

DATAFRAME = 'dataframe'

DICT = 'dict'

ddc_utility.client.authorize_request(method)

ddc_utility.client.authorize_s3_access(method)

ddc_utility.constants module

ddc_utility.cube module

ddc_utility.cube.clip_cube(cube: Dataset, geometry_json: dict) → Dataset

ddc_utility.cube.open_cube(path: str, storage_options: dict | None = None, group: str = None)

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: Exception

Exception raised when an HTTP request fails

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.utils module

class ddc_utility.utils.AccesToken(*, access_token: SecretStr, expires_in: int, token_type: str)

Bases: BaseModel

access_token: SecretStr

property expires_at: int

expires_in: int

model_config: ClassVar[ConfigDict] = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_post_init(context: Any, /) → None

This function is meant to behave like a BaseModel method to initialise private attributes.

It takes context as an argument since that’s what pydantic-core passes when calling it.

Parameters:

self – The BaseModel instance.
context – The context.

classmethod token_must_be_bearer(v: str) → str

token_type: str

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

Bases: object

Class for WKT/GeoJson type geometry.

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

classmethod convert_geometry(geometry: str | dict): Convert geometry to Shapely object.

property geometry: Return geometry.

to_json(): Return GeoJson representation of the 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.

Python package

Submodules

ddc_utility.auth module

ddc_utility.client module

ddc_utility.constants module

ddc_utility.cube module

ddc_utility.errors module

ddc_utility.utils module

Module contents