GwdiWiwbRetrieval
gwdi.GwdiWiwbRetrieval()Retrieve WIWB precipitation for point locations.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| data_adapter | DataAdapter | Data adapter used for reading input locations and writing output tables. | required |
Attributes
| Name | Type | Description |
|---|---|---|
| data_adapter | DataAdapter | Data adapter instance. |
| df_in | pd.DataFrame | None | Normalized input locations after run. |
| df_out | pd.DataFrame | None | Retrieved precipitation table after run. |
| input_schema | ClassVar[dict[str, str | list[str]]] | Validation schema for location input. |
Notes
WIWB API reference used by this module: https://portal.hydronet.com/data/files/Technische%20Instructies%20WIWB%20API.pdf
Methods
| Name | Description |
|---|---|
| default_options | Return default runtime options. |
| fetch_precipitation | Fetch WIWB precipitation dataset for a date range. |
| infer_dataset_crs | Infer dataset CRS from CF grid-mapping metadata. |
| log_exceptions | Stuurt exceptions eerst naar de logger van de DataAdapter |
| normalize_locations_table | Validate and normalize GWDI sampling locations. |
| resolve_publish_window | Resolve publish window at daily precision. |
| resolve_source_window | Resolve source retrieval window from publish window. |
| run | Execute WIWB retrieval for configured locations. |
| sample_points_from_dataset | Sample a gridded dataset at point locations without temporal aggregation. |
| transform_locations_to_dataset_crs | Transform input points from input CRS to dataset CRS. |
default_options
gwdi.GwdiWiwbRetrieval.default_options()Return default runtime options.
Returns
| Name | Type | Description |
|---|---|---|
| dict[str, object] | Default WIWB retrieval options. |
fetch_precipitation
gwdi.GwdiWiwbRetrieval.fetch_precipitation(
options,
start_date,
end_date,
session=None,
)Fetch WIWB precipitation dataset for a date range.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| options | dict[str, object] | Retrieval options. | required |
| start_date | pd.Timestamp | Request start timestamp. | required |
| end_date | pd.Timestamp | Request end timestamp. | required |
| session | requests.Session | None | Existing requests session. | None |
Returns
| Name | Type | Description |
|---|---|---|
| xarray.Dataset | Loaded source dataset. |
infer_dataset_crs
gwdi.GwdiWiwbRetrieval.infer_dataset_crs(dataset, data_array)Infer dataset CRS from CF grid-mapping metadata.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| dataset | xr.Dataset | Source dataset containing grid-mapping variables. | required |
| data_array | xr.DataArray | Data variable with optional grid_mapping attribute. |
required |
Returns
| Name | Type | Description |
|---|---|---|
| str or None | CRS representation suitable for pyproj (PROJ/WKT), or None when inference is not possible. |
log_exceptions
gwdi.GwdiWiwbRetrieval.log_exceptions(method)Stuurt exceptions eerst naar de logger van de DataAdapter
normalize_locations_table
gwdi.GwdiWiwbRetrieval.normalize_locations_table(df_locations)Validate and normalize GWDI sampling locations.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| df_locations | pd.DataFrame | Input location table with at least fid, name, x and y. |
required |
Returns
| Name | Type | Description |
|---|---|---|
| pandas.DataFrame | Normalized copy with integer fid, numeric coordinates and rows sorted by fid. |
Raises
| Name | Type | Description |
|---|---|---|
| UserWarning | If fid contains missing or duplicate values. |
resolve_publish_window
gwdi.GwdiWiwbRetrieval.resolve_publish_window(
calc_time,
publish_days,
target_date=None,
)Resolve publish window at daily precision.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| calc_time | pd.Timestamp | str | Calculation timestamp. | required |
| publish_days | int | str | Number of publish days to include. | required |
| target_date | pd.Timestamp | str | None | Optional explicit publish end date. If omitted, calc_time - 1 day is used. |
None |
Returns
| Name | Type | Description |
|---|---|---|
| tuple[pd.Timestamp, pd.Timestamp] | (publish_start, publish_end). |
Raises
| Name | Type | Description |
|---|---|---|
| UserWarning | If publish_days <= 0. |
resolve_source_window
gwdi.GwdiWiwbRetrieval.resolve_source_window(
publish_start,
publish_end,
options,
)Resolve source retrieval window from publish window.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| publish_start | pd.Timestamp | Start of the publish window. | required |
| publish_end | pd.Timestamp | End of the publish window. | required |
| options | dict[str, object] | Retrieval options containing optional lag_days. |
required |
Returns
| Name | Type | Description |
|---|---|---|
| tuple[pd.Timestamp, pd.Timestamp] | (source_start, source_end). |
Raises
| Name | Type | Description |
|---|---|---|
| UserWarning | If lag_days < 0 or if the lagged end falls before publish start. |
Notes
Source span follows publish span; only lag shifts the end backward.
run
gwdi.GwdiWiwbRetrieval.run(input, output)Execute WIWB retrieval for configured locations.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| input | str | Input adapter key containing location table. | required |
| output | str | Output adapter key for precipitation table. | required |
Raises
| Name | Type | Description |
|---|---|---|
| UserWarning | If retrieval returns no data or duplicate (time, fid) rows. |
sample_points_from_dataset
gwdi.GwdiWiwbRetrieval.sample_points_from_dataset(
dataset,
locations_table,
window_start,
window_end,
variable_name,
time_name,
x_name,
y_name,
input_crs=None,
)Sample a gridded dataset at point locations without temporal aggregation.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| dataset | xr.Dataset | Source dataset. | required |
| locations_table | pd.DataFrame | Location table with fid, x and y. |
required |
| window_start | pd.Timestamp | Start of the time slice. | required |
| window_end | pd.Timestamp | End of the time slice. | required |
| variable_name | str | Source variable to sample. | required |
| time_name | str | Time dimension name. | required |
| x_name | str | X coordinate name. | required |
| y_name | str | Y coordinate name. | required |
| input_crs | str | None | CRS of input location coordinates. If provided, points are transformed to source CRS prior to sampling. | None |
Returns
| Name | Type | Description |
|---|---|---|
| xr.Dataset | Dataset containing sampled values in (time, fid) shape. |
Raises
| Name | Type | Description |
|---|---|---|
| UserWarning | If the requested variable is missing. | |
| ValueError | If required dimensions/coordinates are missing. |
Notes
This method only slices and samples. It does not perform temporal aggregation or rate-to-amount conversion.
transform_locations_to_dataset_crs
gwdi.GwdiWiwbRetrieval.transform_locations_to_dataset_crs(
locations_table,
dataset,
data_array,
input_crs,
x_name,
y_name,
)Transform input points from input CRS to dataset CRS.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| locations_table | pd.DataFrame | Location table with x and y. |
required |
| dataset | xr.Dataset | Source dataset. | required |
| data_array | xr.DataArray | Source variable used for CRS inference. | required |
| input_crs | str | None | CRS of input points (e.g. "EPSG:4326"). If None or empty, no transformation is applied. |
required |
| x_name | str | Name of source x-coordinate (reserved for interface consistency). | required |
| y_name | str | Name of source y-coordinate (reserved for interface consistency). | required |
Returns
| Name | Type | Description |
|---|---|---|
| pd.DataFrame | Copy of the input table with transformed x and y coordinates. |
Raises
| Name | Type | Description |
|---|---|---|
| UserWarning | If dataset CRS cannot be inferred or pyproj is unavailable. |