DOCSEARCHbyAlgolia
Submit Docs

Iris

repository·main·Indexed 20 days ago

https://github.com/scitools/iris

A format-agnostic, community-driven Python package for analyzing and visualizing Earth science data. It features an extensible architecture via the iris.plugins namespace package and provides tools for scientific analysis and visualization in the Earth sciences domain.

Tokens
108.1K
Snippets
323
Records
596
Agent score
71%

What's inside scitools-iris

  1. Overview of Iris for Earth Science Data

    main
    Iris is a format-agnostic Python package designed for analyzing and visualizing multi-dimensional Earth science data. It uses a data model based on the CF conventions, which allows for a powerful interface that works across different data formats. It is specifically optimized for multi-dimensional datasets where traditional tabular representations are inefficient.

  2. Overview of Iris

    main
    Iris is a powerful, format-agnostic, community-driven Python package designed for analyzing and visualizing Earth science data. It is built to handle diverse data formats and provides tools for scientific analysis and visualization in the Earth sciences domain.

  3. Key features and changes in Iris v3.0

    main

    Iris v3.0 introduced several major improvements and architectural changes:

    • Python Support: Dropped support for Python 2; Iris 3 requires Python 3.
    • CF Conventions: Extended support for CF Ancillary Data and Quality Flags.
    • Lazy Regridding: Available for Linear, Nearest, and AreaWeighted regridding schemes.
    • Metadata API: Introduced a new common metadata API for consistent management and manipulation.
    • Cube Arithmetic: Improved cube maths with extended broadcasting, auto-transposition, and more lenient handling of metadata and coordinates.
    • Installation: Revamped installation and developer guides.

  4. Overview of the Iris loading process for PP and Fieldsfiles

    main

    When loading Met Office Unified Model (UM) PP or Fieldsfiles, Iris follows a three-step translation process to convert legacy metadata into NetCDF CF-compliant cubes:

    1. Field Loading: iris.fileformats.pp.load returns an iterator of PPField objects. These objects act as a lightweight stream; the actual field data is not loaded into memory until the .data attribute is accessed.
    2. Raw Cube Creation: Each PPField is converted into a 2D 'raw' cube (latitude/longitude) via iris.load_raw. During this step, header elements are mapped to coordinates (e.g., vertical and time coordinates become auxiliary scalar coordinates) and metadata is encoded into cube properties like name, units, and attributes.
    3. Merging: Iris attempts to merge these raw 2D cubes into higher-dimensional cubes using CubeList.merge. This combines cubes with different scalar coordinate values (like time, height, or realization) into a single cube with a new dimension coordinate.

    Note: Fieldsfiles are treated almost identically to PP files, using the same lookup table logic.

    import iris.fileformats.pp

# Returns an iterator of PPField objects
fields_iter = iris.fileformats.pp.load('path_to_file.pp')
for field in fields_iter:
    # Data is only loaded when .data is accessed
    data = field.data

  5. What is Iris and when should I use it?

    main

    Iris is a Python package designed for analyzing and visualizing multi-dimensional Earth science data. It is particularly useful when tabular data representations become inefficient or unwieldy.

    Key characteristics include:

    • CF Convention Compliance: Implements a data model based on CF conventions, including built-in support for CF Standard names, units, and coordinate metadata.
    • Format Agnostic: Provides a unified interface for various file formats (including CF-compliant NetCDF, GRIB, and PP) via a plugin architecture.
    • Scalability: Built on NumPy and dask, allowing workflows to scale from single machines to multi-core clusters and HPC environments.
    • Ecosystem Interoperability: Uses standard NumPy/dask arrays for underlying data storage, ensuring compatibility with the wider scientific Python ecosystem.

  6. Relaxed name constraint matching for Cubes

    main

    Iris 2.4 relaxes name constraint matching during loading or extraction. Instead of strictly matching against iris.cube.Cube.name, Iris now matches against any of the following metadata attributes:

    • standard_name
    • long_name
    • NetCDF var_name
    • STASH attributes

  11. Understand Iris chunking for PP and Fieldsfiles

    main

    When loading PP or Fieldsfiles into Iris cubes, chunking is automatically set to one chunk per field.

    For example, a PP file with 85 model levels, 144 latitudes, and 192 longitudes will result in a cube with shape (model_level_number: 85; latitude: 144; longitude: 192) and chunks of shape (1, 144, 192).

    Warning: If the file contains many fields, this can create an excessive number of chunks, leading to poor performance. In such cases, you should consider rechunking the arrays.

  12. Manage Iris warnings and exceptions

    main

    Iris uses two distinct mechanisms to communicate issues:

    1. Concrete Exceptions: Raised for problems that prevent Iris from functioning. These stop code execution immediately.
    2. Warnings: Raised to stderr for less catastrophic problems that might affect specific use cases but allow code to continue running. Iris defaults to raising warnings for anything that might be a problem for any user.

    Common Warning Examples:

    • Coordinate Modification: If you attempt to plot un-bounded point data as a pcolormesh, Iris will guess bounds to allow plotting. This permanently modifies the coordinates, and a warning is issued so you are aware that downstream operations might see different coordinate values.
    • Broken References: If a NetCDF file references a variable (e.g., via coordinates) that is missing from the file, Iris will construct the model without that relationship and issue a warning.

    To manage these, you can learn how to ignore unwanted warnings via the filtering documentation.