Filtering Warnings#

Since Iris cannot predict your specific needs, it by default raises Warnings for anything that might be a problem for any user, and is designed to work with you to ignore Warnings which you do not find helpful.

Here is a hypothetical operation - my_operation() - which raises two Warnings:

>>> my_operation()
...
iris/coord_systems.py:444: IrisUserWarning: Setting inverse_flattening does not affect other properties of the GeogCS object. To change other properties set them explicitly or create a new GeogCS instance.
  warnings.warn(wmsg, category=iris.warnings.IrisUserWarning)
iris/coord_systems.py:770: IrisDefaultingWarning: Discarding false_easting and false_northing that are not used by Cartopy.
  warnings.warn(

Warnings can be suppressed using the Python warnings filter with the ignore action. Detailed information is available in the Python documentation: warnings.

The key points are:

When: a warnings filter can be applied either from the command line or from within Python.
What: a warnings filter accepts various arguments to specify which Warnings are being filtered. Both broad and narrow filters are possible.

When a Warnings Filter can be Applied#

Command line: setting the PYTHONWARNINGS environment variable.
Command line: the python -W command line argument.
Within Python: use warnings.filterwarnings() .

The What Warnings will be Filtered section demonstrates using warnings.filterwarnings(), and shows the equivalent command line approaches.

What Warnings will be Filtered#

Note

For all of these examples we are using the catch_warnings context manager to ensure any changes to settings are temporary.

This should always work fine for the ignore warning filter action, but note that some of the other actions may not behave correctly with all Iris operations, as catch_warnings is not thread-safe (e.g. using the once action may cause 1 warning per chunk of lazy data).

Specific Warnings#

When you do not want a specific warning, but still want all others.

You can target specific Warning messages, e.g.

>>> with warnings.catch_warnings():
...     warnings.filterwarnings("ignore", message="Discarding false_easting")
...     my_operation()
...
iris/coord_systems.py:444: IrisUserWarning: Setting inverse_flattening does not affect other properties of the GeogCS object. To change other properties set them explicitly or create a new GeogCS instance.
  warnings.warn(wmsg, category=iris.warnings.IrisUserWarning)

python -W ignore:"Discarding false_easting"
export PYTHONWARNINGS=ignore:"Discarding false_easting"

Or you can target Warnings raised by specific lines of specific modules, e.g.

>>> with warnings.catch_warnings():
...     warnings.filterwarnings("ignore", module="iris.coord_systems", lineno=444)
...     my_operation()
...
iris/coord_systems.py:770: IrisDefaultingWarning: Discarding false_easting and false_northing that are not used by Cartopy.
  warnings.warn(

python -W ignore:::iris.coord_systems:444
export PYTHONWARNINGS=ignore:::iris.coord_systems:444

Warnings from a Common Source#

When you do not want ANY warnings raised by a module, or collection of modules.

E.g. filtering the coord_systems module:

>>> with warnings.catch_warnings():
...     warnings.filterwarnings("ignore", module="iris.coord_systems")
...     my_operation()

python -W ignore:::iris.coord_systems
export PYTHONWARNINGS=ignore:::iris.coord_systems

If using warnings.filterwarnings() , you can also use partial definitions. The below example will ignore all Warnings from iris as a whole.

>>> with warnings.catch_warnings():
...     warnings.filterwarnings("ignore", module="iris")
...     my_operation()

The above ‘partial’ filter is not available with the command line approaches.

Warnings of a Common Type#

When you do not want any Warnings of the same nature, from anywhere in the code you are calling.

The below example will ignore any IrisDefaultingWarning that gets raised by any module during execution:

>>> with warnings.catch_warnings():
...     warnings.filterwarnings(
...         "ignore",
...         category=iris.warnings.IrisDefaultingWarning
...     )
...     my_operation()
...
iris/coord_systems.py:444: IrisUserWarning: Setting inverse_flattening does not affect other properties of the GeogCS object. To change other properties set them explicitly or create a new GeogCS instance.
  warnings.warn(wmsg, category=iris.warnings.IrisUserWarning)

Using IrisUserWarning in the filter will ignore both Warnings, since IrisDefaultingWarning subclasses IrisUserWarning :

>>> with warnings.catch_warnings():
...     warnings.filterwarnings(
...         "ignore",
...         category=iris.warnings.IrisUserWarning
...     )
...     my_operation()

The command line approaches can only handle the built-in Warning categories (cpython#66733):

python -W ignore::UserWarning
export PYTHONWARNINGS=ignore::UserWarning

There are several built-in Python warning categories that can be used here (DeprecationWarning being a popular example, see warnings for more). Since Iris has so many different warnings that might be raised, Iris subclasses UserWarning to IrisUserWarning, which itself has many specialised subclasses. These subclasses exist to give you more granularity in your warning filtering; you can see the full list by viewing the iris.warnings module.

Attention

If you have ideas for adding/altering Iris’ warning categories, please get in touch! The categories exist to make your life easier, and it is simple to make modifications.

More Detail#

Different people use Iris for very different purposes, from quick file visualisation to extract-transform-load to statistical analysis. These contrasting priorities mean disagreement on which Iris problems can be ignored and which are critically important.

For problems that prevent Iris functioning: Concrete Exceptions are raised, which stop code from running any further - no debate here. For less catastrophic problems: Warnings are raised, which notify you (in stderr) but allow code to continue running. The Warnings are there because Iris may OR may not function in the way you expect, depending on what you need - e.g. a problem might prevent data being saved to NetCDF, but statistical analysis will still work fine.

Examples of Iris Warnings#

If you attempt to plot un-bounded point data as a pcolormesh: Iris will guess appropriate bounds around each point so that quadrilaterals can be plotted. This permanently modifies the relevant coordinates, so the you are warned in case downstream operations assume un-bounded coordinates.
If you load a NetCDF file where a CF variable references another variable - e.g. my_var:coordinates = "depth_var" ; - but the referenced variable (depth_var) is not in the file: Iris will still construct its data model, but without this reference relationship. You are warned since the file includes an error and the loaded result might therefore not be as expected.