wiwb 2024.4.0

Python API to work with WIWB

WIWB API

A Python API on the WIWB API. It includes:

• authorization
• get datasources
• get variables
• get grids
• sample grids to a set of geometries (points and/or polygons)
• sample existing netcdf files to a set of geometries (points and/or polygons)

Getting started

Request a wiwb client-id and client-secret. Provide them as wiwb_client_id and wiwb_client_secret os environment variables for your convenience. Alternatively it can be specified at init.

Import wiwb Api and Auth. GetGrids is not implemented in the Api module (yet) so we import it seperately

from wiwb import Auth, Api

If you have provided os environment variables, you do not have to specify your client_id and client_secret init your Api as:

api = Api()

If you didn't you have to initialize auth manually. Your code looks like:

auth = Auth(client_id="your-client-id", client_secret="your-client-secret")
api = Api(auth=auth)

Get sources

Find data_sources. You'll notice Meteobase.Precipitation being one of them

data_sources = api.get_data_sources()

Get variables

Find variables under Meteobase.Precipitation. You'll notice P being the only variable:

variables = api.get_variables(
    data_source_codes=["Meteobase.Precipitation"]
    )

Get grids

We'll specify a download for WIWB MeteoBase Precipitation. If we don't specify a bounds or geometries, GetGrids will be set for the extent of Water Authority HDSR.

grids = api.GetGrids(
    auth=auth,
    base_url=api.base_url,
    data_source_code="Meteobase.Precipitation",
    variable_code="P",
    start_date=date(2018,1,1),
    end_date=date(2018,1,2),
    data_format_code="netcdf4.cf1p6",
)

We can write the grids to an output directory. If we don't call grids.run() before, it will first request the data at WIWB:

grids.to_directory(output_dir="")

Sample grids

Let's sample the grids. We'll first make some geometries and assign it to grids:

from geopandas import GeoSeries
from shapely.geometry import Point, box

LL_POINT = Point(119865,449665)
UR_POINT = Point(127325,453565)
OTHER_POINT = Point(135125,453394)
POLYGON = box(LL_POINT.x, LL_POINT.y, UR_POINT.x, UR_POINT.y)
GEOSERIES = GeoSeries(
    [LL_POINT,
     UR_POINT,
     OTHER_POINT,
     POLYGON],
     index=["ll_point", "ur_point", "other_point", "polygon"],
     crs=28992
     )

grids.set_geometries(GEOSERIES)

Now we sample on geometries. We'll write the result to a CSV.

df = grids.sample()
df.to_csv("samples.csv")

Sample existing netcdf files

If you have a directory with netcdf-files you can sample them into one DataFrame. You can slice the NetCDFs using a start_date and end_date.

In the example below we take a set of Van der Sat soil-moisture as example. NeCDFs with one variable are stored in a directory with a variable name. So, netcdfs containing the variable DRZSM-AMSR2-C1N-DESC-T10_V003_100 are stored in a directory with name DRZSM-AMSR2-C1N-DESC-T10_V003_100

from pathlib import Path
from datetime import date

START_DATE = date(2015, 1, 1)
END_DATE = date(2015, 1, 2)
DIR = Path("path_to_netcdf_directory")

LL_POINT = Point(119865,449665)
UR_POINT = Point(127325,453565)
OTHER_POINT = Point(135125,453394)
POLYGON = box(LL_POINT.x, LL_POINT.y, UR_POINT.x, UR_POINT.y)
GEOSERIES = GeoSeries(
    [LL_POINT,
     UR_POINT,
     OTHER_POINT,
     POLYGON],
     index=["ll_point", "ur_point", "other_point", "polygon"],
     crs=28992
     )

# get variables from directory names and take the first
variables = [i.name for i in DIR.glob(r"*/")]
variable = variables[0]

# go to the directory with the variable
dir = DIR / variable 

# sample all netcdf's in the directory over the variable
df = sample_nc_dir(dir, variable, GEOSERIES, start_date=START_DATE, end_date=END_DATE)

If you wish to specify a list of NetCDF files rather than a directory, you can use:

nc_files = [
    dir / "DRZSM-AMSR2-C1N-DESC-T10_V003_100_2015-01-01T000000_4.040000_52.240000_5.600000_51.300000.nc",  # must be pathlib.Path object
    dir / "DRZSM-AMSR2-C1N-DESC-T10_V003_100_2015-01-02T000000_4.040000_52.240000_5.600000_51.300000.nc"  # must be pathlib.Path object
    ]

df = sample_nc_dir(nc_files, variable, GEOSERIES, start_date=START_DATE, end_date=END_DATE)