xeo 0.2.1

Awesome Earth Observation Instruments in Python

Awesome Earth Observation Instruments in Python

---

Awesome Earth Observation Instruments Catalogue: https://github.com/awesome-spectral-indices/awesome-earth-observation-instruments

GitHub: https://github.com/awesome-spectral-indices/xeo

---

About xeo

xeo is the Python interface to the Awesome Earth Observation Instruments catalogue. It turns the catalogue into a small, exploratory API for discovering instruments, inspecting their metadata, searching across the collection, and loading spectral bands and spectral response functions as pandas DataFrames when they are available.

A snapshot of the catalogue is bundled with each xeo release. This keeps catalogue exploration local and makes it straightforward to use instrument metadata in Python workflows.

What is the Awesome Earth Observation Instruments catalogue?

Awesome Earth Observation Instruments is a community-driven, machine-readable catalogue of instruments used to observe Earth. It organizes spectral, spatial, temporal, operational, platform, and data-access metadata under a consistent schema so that instruments from different missions and operators can be discovered and compared.

The catalogue is the source of the instrument records; xeo is the Python interface to those records. Contributions to instrument metadata, bands, SRFs, or catalogue schemas belong in the catalogue repository, while contributions to the Python API and its documentation belong here.

Installation

[!NOTE] The conda-forge package has not been published yet. The commands below will become available with the first release on each channel.

Install xeo from PyPI:

python -m pip install xeo

Plotting is optional. Install xeo with Matplotlib support when you need it:

python -m pip install "xeo[plot]"

Or install it from conda-forge:

conda install -c conda-forge xeo

To use the current development version:

git clone https://github.com/awesome-spectral-indices/xeo.git
cd xeo
python -m pip install --editable .

xeo requires Python 3.10 or newer.

Getting started

Explore the catalogue

Import xeo to access the bundled catalogue and its instrument collection:

import xeo

print(xeo.catalogue)
print(f"Catalogue version: {xeo.catalogue.version}")
print(f"Number of instruments: {len(xeo.instruments)}")
print(list(xeo.instruments))

xeo.instruments is a frozen collection keyed by instrument identifier. Instruments support both attribute and mapping access:

msi = xeo.instruments.MSI_S2A
assert msi is xeo.instruments["MSI_S2A"]

print(msi.name)
print(msi.platform)
print(msi.operator)
print(msi.status)

Inspect instrument metadata

Required catalogue fields are exposed as attributes. Optional and domain-specific metadata can be discovered through extensions, while relationships connect an instrument to its family and platform companions:

print(msi.extension_names)
print(msi.extensions["spectral"].keys())
print(msi.family)
print(msi.platform_companions)
print(msi.references)

Use msi.data to inspect the original record, or msi.to_dict() when you need an independent copy that can be modified safely.

Search for instruments

Catalogue.search() returns an Instruments collection containing every match. Different properties are combined with AND, while lists mean “match any of these values”:

results = xeo.catalogue.search(
    operator=["ESA", "NASA"],
    platform_type="satellite",
    status="operational",
    has_bands=True,
)

print(list(results))

Use has_bands and has_srf to filter by spectral-data availability. For start_date, an inclusive YYYY-MM-DD/YYYY-MM-DD interval avoids requiring an exact date:

launched = xeo.catalogue.search(
    start_date="2000-01-01/2003-01-01"
)

Load spectral bands

When band definitions are available, bands() returns a DataFrame indexed by band identifier:

if msi.has_bands:
    bands = msi.bands()
    print(bands.loc[["B2", "B3", "B4"], ["center_wavelength", "bandwidth"]])

Wavelengths and bandwidths are expressed in nanometres, and band-level ground sampling distances are expressed in metres.

Load spectral response functions

When an SRF is available, srf() returns a DataFrame with a wavelength column and one response column per band:

if msi.has_srf:
    srf = msi.srf()
    print(srf[["wavelength", "B2", "B3", "B4"]].head())

Both bands() and srf() return None when the requested data is not available.

Plot bands and spectral response functions

Install the optional plotting extra, then pass one instrument id, a list of ids, a dictionary selecting bands, or a list of per-instrument dictionaries:

bands_ax = xeo.plot_bands({"MSI_S2A": ["B2", "B3", "B4", "B8"]})
srf_ax = xeo.plot_srf(["MSI_S2A", "OLI_L8"], figsize=(10, 6))

Dictionary selections can attach native Matplotlib styles to individual bands:

ax = xeo.plot_srf(
    [
        {
            "MSI_S2A": [
                {"B4": {"color": "red", "linestyle": "--", "linewidth": 2}}
            ]
        },
        {"OLI_L8": [{"B5": {"color": "blue", "linewidth": 2}}]},
    ],
    title="Selected red and near-infrared responses",
)

Both functions return a Matplotlib Axes, so the complete Matplotlib API remains available for further customization.

Discover data access points

get_data_access() retrieves the catalogue entry for a provider and processing level. It defaults to the primary Google Earth Engine collection:

earth_engine = msi.get_data_access()
planetary_computer = msi.get_data_access("planetary_computer", "boa")
cdse = msi.get_data_access("cdse", "toa")

Available providers are ee, planetary_computer, cdse, and eopf; processing levels are primary, boa, toa, and raw. An available entry is returned as a dictionary with stac_endpoint, collection, and docs. Valid combinations that are not available for an instrument return None.

Work with raw catalogue data

The object API is intended for exploration, but the complete JSON-compatible catalogue is also available for custom workflows:

raw_record = xeo.catalogue.data["instruments"]["MSI_S2A"]
catalogue_copy = xeo.catalogue.to_dict()

Treat .data as read-only. Use .to_dict() when downstream code needs to modify a catalogue or instrument dictionary.

Tutorials

The tutorial notebooks provide complete, executable examples:

1. Getting started
2. Exploring instruments
3. Spectral bands
4. Spectral response functions
5. Raw data and DataFrame workflows
6. Data access
7. Advanced search
8. Plotting spectral data

Contributing

Contributions are welcome. See CONTRIBUTING.md for development setup, testing, documentation guidance, and where to propose catalogue-data changes.

License

xeo is available under the MIT License.