imod.util - Miscellaneous Utilities

Miscellaneous Utilities.

Conventional IDF filenames can be understood and constructed using imod.util.decompose() and imod.util.compose(). These are used automatically in imod.idf().

Furthermore there are some utility functions for dealing with the spatial location of rasters: imod.util.coord_reference(), imod.util.spatial_reference() and imod.util.transform(). These are used internally, but are not private since they may be useful to users as well.

imod.util.append_nested_dict(dict1, dict2)[source]

Recursively walk through two dicts to append dict2 to dict1.

Mutates dict1

Modified from: https://stackoverflow.com/a/58742155

Parameters

dict1 (nested dict) – Nested dict to be appended to
dict2 (nested dict) – Nested dict to append

imod.util.cd(path)[source]

Change directory, and change it back after the with block.

Examples

>>> with imod.util.cd("docs"):
        do_something_in_docs()

imod.util.compose(d, pattern=None)[source]: From a dict of parts, construct a filename, following the iMOD conventions. Returns a pathlib.Path.

imod.util.coord_reference(da_coord)[source]

Extracts dx, xmin, xmax for a coordinate DataArray, where x is any coordinate.

If the DataArray coordinates are nonequidistant, dx will be returned as 1D ndarray instead of float.

Parameters: a (xarray.DataArray of a coordinate) –
Returns: (dx, xmin, xmax) for a coordinate x
Return type: tuple

imod.util.decompose(path, pattern=None)[source]

Parse a path, returning a dict of the parts, following the iMOD conventions.

Parameters

path (str or pathlib.Path) – Path to the file. Upper case is ignored.
pattern (str, regex pattern, optional) – If the path is not made up of standard paths, and the default decompose does not produce the right result, specify the used pattern here. See the examples below.

Returns

d – Dictionary with name of variable and dimensions

Return type

dict

Examples

Decompose a path, relying on default conventions:

>>> decompose("head_20010101_l1.idf")

Do the same, by specifying a format string pattern, excluding extension:

>>> decompose("head_20010101_l1.idf", pattern="{name}_{time}_l{layer}")

This supports an arbitrary number of variables:

>>> decompose("head_slr_20010101_l1.idf", pattern="{name}_{scenario}_{time}_l{layer}")

The format string pattern will only work on tidy paths, where variables are separated by underscores. You can also pass a compiled regex pattern. Make sure to include the re.IGNORECASE flag since all paths are lowered.

>>> import re
>>> pattern = re.compile(r"(?P<name>[\w]+)L(?P<layer>[\d+]*)")
>>> decompose("headL11", pattern=pattern)

However, this requires constructing regular expressions, which is generally a fiddly process. The website https://regex101.com is a nice help. Alternatively, the most pragmatic solution may be to just rename your files.

imod.util.ignore_warnings()[source]

Contextmanager to ignore RuntimeWarnings as they are frequently raised by the Dask delayed scheduler.

Examples

>>> with imod.util.ignore_warnings():
        function_that_throws_warnings()

imod.util.initialize_nested_dict(depth)[source]

Initialize a nested dict with a fixed depth

Parameters: depth (int) – depth of returned nested dict
Returns
Return type: nested defaultdicts of n depth

imod.util.is_divisor(numerator, denominator) → bool[source]

Parameters

numerator (np.array of floats) –
denominator (float) –

Returns

is_divisor

Return type

bool

imod.util.set_nested(d, keys, value)[source]

Set in the deepest dict of a set of nested dictionaries, as created by the initialize_nested_dict function above.

Mutates d.

Parameters

d ((Nested dict of) dict) –
keys (list of keys) – Each key is a level of nesting
value (dask array, typically) –

Returns

Return type

None

imod.util.sorted_nested_dict(d)[source]

Sorts a variably nested dict (of dicts) by keys.

Each dictionary will be sorted by its keys.

Parameters: d ((Nested dict of) dict) –
Returns: sorted_lists – Values sorted by keys, matches the nesting of d.
Return type: list (of lists)

imod.util.spatial_reference(a)[source]

Extracts spatial reference from DataArray.

If the DataArray coordinates are nonequidistant, dx and dy will be returned as 1D ndarray instead of float.

Parameters: a (xarray.DataArray) –
Returns: (dx, xmin, xmax, dy, ymin, ymax)
Return type: tuple

imod.util.to_datetime(s)[source]

imod.util.to_ugrid2d(data: Union[xarray.core.dataarray.DataArray, xarray.core.dataset.Dataset]) → xarray.core.dataset.Dataset[source]

Convert a structured DataArray or Dataset into its UGRID-2D quadrilateral equivalent.

See: https://ugrid-conventions.github.io/ugrid-conventions/#2d-flexible-mesh-mixed-triangles-quadrilaterals-etc-topology

Parameters: data (Union[xr.DataArray, xr.Dataset]) – Dataset or DataArray with last two dimensions (“y”, “x”). In case of a Dataset, the 2D topology is defined once and variables are added one by one. In case of a DataArray, a name is required; a name can be set with: da.name = "..."’
Returns: ugrid2d_dataset – The equivalent data, in UGRID-2D quadrilateral form.
Return type: xr.Dataset

imod.util.transform(a)[source]

Extract the spatial reference information from the DataArray coordinates, into an affine.Affine object for writing to e.g. rasterio supported formats.

Parameters: a (xarray.DataArray) –
Returns
Return type: affine.Affine

imod.util.ugrid2d_data(da: xarray.core.dataarray.DataArray) → xarray.core.dataarray.DataArray[source]

Reshape a structured (x, y) DataArray into unstructured (face) form. Extra dimensions are maintained: e.g. (time, layer, x, y) becomes (time, layer, face).

Parameters: da (xr.DataArray) – Structured DataArray with last two dimensions (“y”, “x”).
Returns
Return type: Unstructured DataArray with dimensions (“y”, “x”) replaced by (“face”,)

imod.util.ugrid2d_topology(data: Union[xarray.core.dataarray.DataArray, xarray.core.dataset.Dataset]) → xarray.core.dataset.Dataset[source]

Derive the 2D-UGRID quadrilateral mesh topology from a structured DataArray or Dataset, with (2D-dimensions) “y” and “x”.

Parameters: data (Union[xr.DataArray, xr.Dataset]) – Structured data from which the “x” and “y” coordinate will be used to define the UGRID-2D topology.
Returns: ugrid_topology – Dataset with the required arrays describing 2D unstructured topology: node_x, node_y, face_x, face_y, face_nodes (connectivity).
Return type: xr.Dataset