ecaio 0.2.4

Read-only access to EarthCARE data product files

ecaio - Read-only access to EarthCARE data product files

Synopsis

from ecaio import EcaioFilename, EcaioOpen, EcaioTime

# ecaio can work with .zip-compressed files directly:
my_msi_file = "ECA_EXAF_MSI_RGR_1C_20250219T114658Z_20250219T133232Z_04147D.ZIP"

# Or you can locate files by glob(). The following will try and locate the
# unique file that matches the following components, regardless of their
# extension, processing start time, or anything else that was not specified
# explicitly. If that doesn't work, an exception is raised.
my_msi_file = EcaioFilename.glob_unique(
    root_directory="/my/data/directory",
    baseline="AF",
    file_type="MSI_RGR_1C",
    frame="4147D",
)

# EcaioOpen automatically dispatches to the right subclass, if it recognizes
# the file type (currently, only M-NOM, M-RGR, and B-SNG); otherwise it opens
# the file as a generic EarthCARE file.
with EcaioOpen(my_msi_file) as msi:

    # access any header property (here, from the Main Product Header)
    description = msi.mph.description

    # access fields from /ScienceData with the following convenient syntax
    elevation = msi.surface_elevation

    # ecaio has built-in recipes for some quantities, like MSI TIR thermal
    # radiances (converted from brightness temperatures)
    thermal_radiance = msi.thermal_radiance

    # use EcaioTime to convert times in EarthCARE format to another format
    # (here, to Python standard library ‘datetime’)
    line_acquisition_times = EcaioTime.from_float(msi.time).to_datetime()

Description

ecaio is a Python library for convenient access to the data stored in EarthCARE data product files, together with derived quantities that can be computed from those data products. The data within .zip-compressed data product archives can be accessed transparently. Currently, access is read-only. ecaio strives to be fast, by caching and performing vector operations where possible, and convenient to use, by allowing you to retrieve data in few lines of code, with a syntax that is (hopefully) easy to remember.

ecaio is not a library for plotting or analysis of EarthCARE data. There are other libraries that are better suited for that (e.g., pandas, matplotlib, and the tools listed under "See also" below), but ecaio strives to make it easy to prepare your data for subsequent analysis and plotting with other packages.

Features

• Work with .zip-compressed data product files directly
• Convenient syntax for access to datasets under /ScienceData: values = msi_rgr.pixel_values
• Data are cached to avoid the time penalty when re-using the same data
• Recipes for a few derived quantities are already implemented, such as VNS reflectances from radiances, TIR radiances from brightness temperatures, RGB composites for MSI, narrowband-to-broadband conversion for MSI, computation of frame margins, etc.
• Mask values from bad BBR detectors
• Correct and convenient conversion of time stamps to and from EarthCARE format (i.e., float)
• Generic file opening with EcaioOpen()
• Convenient and fast spatial subsetting of data with .subset_rectangle()
• Conversion to GDAL raster datasets with geolocation metadata, to process the data with the GDAL library

Project development status and interface stability

ecaio is still under development, and its interface may change in the future. Some features have not been implemented yet, and not all EarthCARE file types are fully supported yet.

Homepage

ecaio can be found at https://gitlab.com/ebaudrez/ecaio.

Installation instructions

ecaio has not yet been uploaded to the Python Package Index, so for the time being, the recommended way to install it is to grab a .tar.gz archive from the Gitlab release page, and to install it using

pip install ecaio-x.y.z.tar.gz

where x.y.z is the version you've downloaded.

Bugs and known issues

No bugs have been reported so far. Please report bugs or feature requests at https://gitlab.com/ebaudrez/ecaio/-/issues.

See also

There are a number of other libraries that can ingest and process EarthCARE data, with a different focus than ecaio:

• ectools is a set of open tools for searching, loading, plotting, intercomparing and analysing EarthCARE data products, licensed under Apache 2.0
• earthcarekit is a comprehensive toolkit for downloading, reading, analysing and visualizing data from EarthCARE, licensed under Apache 2.0

Copyright and license

Copyright (C) 2025, 2026 Edward Baudrez [e-mail]

This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0. If a copy of the MPL was not distributed with this file, You can obtain one at https://mozilla.org/MPL/2.0/.