imod.rasterio - Raster file I/O

Functions that make use of rasterio for input and output to other raster formats.

Currently only imod.rasterio.write() is implemented.

imod.rasterio.header(path, pattern)[source]
imod.rasterio.open(path, use_cftime=False, pattern=None)[source]

Open one or more GDAL supported raster files as an xarray.DataArray.

In accordance with xarray’s design, open loads the data of the files lazily. This means the data of the rasters are not loaded into memory until the data is needed. This allows for easier handling of large datasets, and more efficient computations.

Parameters
  • path (str, Path or list) – This can be a single file, ‘head_l1.tif’, a glob pattern expansion, ‘head_l*.tif’, or a list of files, [‘head_l1.tif’, ‘head_l2.tif’]. Note that each file needs to be of the same name (part before the first underscore) but have a different layer and/or timestamp, such that they can be combined in a single xarray.DataArray.

  • use_cftime (bool, optional) –

    Use cftime.DatetimeProlepticGregorian instead of np.datetime64[ns] for the time axis.

    Dates are normally encoded as np.datetime64[ns]; however, if dates fall before 1678 or after 2261, they are automatically encoded as cftime.DatetimeProlepticGregorian objects rather than np.datetime64[ns].

  • pattern (str, regex pattern, optional) – If the filenames do match default naming conventions of {name}_{time}_l{layer}, a custom pattern can be defined here either as a string, or as a compiled regular expression pattern. See the examples below.

Returns

A float32 xarray.DataArray of the values in the raster file(s). All metadata needed for writing the file to raster or other formats using imod.rasterio are included in the xarray.DataArray.attrs.

Return type

xarray.DataArray

Examples

Open a raster file:

>>> da = imod.rasterio.open("example.tif")

Open a raster file, relying on default naming conventions to identify layer:

>>> da = imod.rasterio.open("example_l1.tif")

Open an IDF file, relying on default naming conventions to identify layer and time:

>>> head = imod.rasterio.open("head_20010101_l1.tif")

Open multiple files, in this case files for the year 2001 for all layers, again relying on default conventions for naming:

>>> head = imod.rasterio.open("head_2001*_l*.tif")

The same, this time explicitly specifying name, time, and layer:

>>> head = imod.rasterio.open("head_2001*_l*.tif", pattern="{name}_{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+]*)", re.IGNORECASE)
>>> head = imod.idf.open("headL11", pattern=pattern)

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

imod.rasterio.save(path, a, driver=None, nodata=nan, pattern=None, dtype=None)[source]

Write a xarray.DataArray to one or more rasterio supported files

If the DataArray only has y and x dimensions, a single raster file is written, like the imod.rasterio.write function. This function is more general and also supports time and layer and other dimensions. It will split these up, give them their own filename according to the conventions in imod.util.compose, and write them each.

Parameters
  • path (str or Path) – Path to the raster file to be written. This function decides on the actual filename(s) using conventions, so it only takes the directory and name from this parameter.

  • a (xarray.DataArray) – DataArray to be written. It needs to have dimensions (‘y’, ‘x’), and optionally layer and time.

  • driver (str, optional) – Which GDAL format driver to use. The complete list is at https://gdal.org/drivers/raster/index.html. By default tries to guess from the file extension.

  • nodata (float, optional) – Nodata value in the saved raster files. Defaults to a value of nan.

  • pattern (str) – Format string which defines how to create the filenames. See examples.

Example

Consider a DataArray da that has dimensions ‘layer’, ‘y’ and ‘x’, with the ‘layer’ dimension consisting of layer 1 and 2:

save('path/to/head', da)

This writes the following two tif files: ‘path/to/head_l1.tif’ and ‘path/to/head_l2.tif’.

It is possible to generate custom filenames using a format string. The default filenames would be generated by the following format string:

save(“example”, pattern=”{name}_l{layer}{extension}”)

If you desire zero-padded numbers that show up neatly sorted in a file manager, you may specify:

save(“example”, pattern=”{name}_l{layer:02d}{extension}”)

In this case, a 0 will be padded for single digit numbers (‘1’ will become ‘01’).

To get a date with dashes, use the following pattern:

“{name}_{time:%Y-%m-%d}_l{layer}{extension}”

imod.rasterio.write(path, da, driver=None, nodata=nan, dtype=None)[source]

Write xarray.DataArray to GDAL supported geospatial rasters using rasterio.

Parameters
  • path (str or Path) – path to the dstput raste

  • da (xarray DataArray) – The DataArray to be written. Should have only x and y dimensions.

  • driver (str; optional) – Which GDAL format driver to use. The complete list is at https://gdal.org/drivers/raster/index.html. By default tries to guess from the file extension.

  • nodata (float) – Nodata value to use. Should be convertible to the DataArray and GDAL dtype. Default value is np.nan

Examples

Save xarray.DataArray in ASCII format:

>>> imod.rasterio.write("example.asc", da)

Save xarray.DataArray in ASCII format, with 6 significant digits:

>>> da.attrs['SIGNIFICANT_DIGITS'] = 6
>>> imod.rasterio.write("example.asc", da)