xeo

Appearance

xeo ​

xeo - Earth observation instruments in Python.

Classes:

  • Catalogue – Awesome Earth Observation Instruments catalogue. 🐈
  • Instrument – Earth observation instrument from the catalogue.
  • Instruments – Collection of instruments in the catalogue.

Functions:

  • plot_bands – Plot instrument band ranges along the wavelength axis.
  • plot_srf – Plot spectral response functions for one or more instruments.

xeo.Catalogue ​

python
Catalogue(catalogue, instruments=None)

Bases: object

Awesome Earth Observation Instruments catalogue. 🐈

Parameters:

  • catalogue (dict) – Raw catalogue data.
  • instruments (Instruments) – Instrument objects created from the raw catalogue.

Examples:

pycon
>>> import xeo
>>> isinstance(xeo.catalogue, xeo.Catalogue)
True
>>> len(xeo.catalogue.instruments) > 0
True

Functions:

  • search – Search instruments using core metadata and spectral availability.
  • to_dict – Return an independent dictionary containing the raw catalogue.
  • update – Replace the local catalogue with the current upstream catalogue.

Attributes:

  • data – Raw, JSON-serializable catalogue data.
  • href – URL of the catalogue. Equivalent to :attr:link.
  • instruments – Instruments available in the catalogue.
  • link – URL of the catalogue.
  • name – Name of the catalogue.
  • version – Version of the catalogue.

data ​

python
data = catalogue

Raw, JSON-serializable catalogue data.

href ​

python
href = catalogue['link']

URL of the catalogue. Equivalent to :attr:link.

instruments ​

python
instruments = instruments

Instruments available in the catalogue.

python
link = catalogue['link']

URL of the catalogue.

name ​

python
name = catalogue['name']

Name of the catalogue.

search ​

python
search(**kwargs)

Search instruments using core metadata and spectral availability.

Search values are matched exactly, except that start_date also accepts inclusive intervals formatted as YYYY-MM-DD/YYYY-MM-DD. Different properties are combined with AND. A list supplied for one property uses OR, and list-valued instrument properties such as operator and platform match when any requested value is present.

Parameters:

  • **kwargs (Any) – Required instrument properties to match. has_srf and has_bands are also accepted as boolean filters.

Returns:

  • Instruments – A frozen collection containing the matching instruments in catalogue order.

Examples:

pycon
>>> import xeo
>>> result = xeo.catalogue.search(operator=["ESA", "NASA"])
>>> "MSI_S2A" in result and "OLI_L8" in result
True
>>> all(item.has_srf for item in xeo.catalogue.search(has_srf=True).values())
True
>>> "MODIS_AQUA" in xeo.catalogue.search(
...     start_date="2000-01-01/2003-01-01"
... )
True

to_dict ​

python
to_dict()

Return an independent dictionary containing the raw catalogue.

update ​

python
update()

Replace the local catalogue with the current upstream catalogue.

The complete catalogue is downloaded from the Awesome Earth Observation Instruments repository. When its content differs from the local copy, the bundled JSON file is replaced atomically and the catalogue and instrument objects in the current Python session are refreshed.

Notes

This method requires an internet connection and write access to the installed xeo/data directory.

Examples:

pycon
>>> import xeo
>>> xeo.catalogue.update()
The catalogue is already updated (version <x.x.x>).

version ​

python
version = catalogue['version']

Version of the catalogue.

xeo.Instrument ​

python
Instrument(instrument)

Bases: object

Earth observation instrument from the catalogue.

Core metadata is available directly as attributes. The complete source record remains available through :attr:data.

Examples:

pycon
>>> import xeo
>>> xeo.instruments.MSI_S2A
Instrument(MSI_S2A: MultiSpectral Instrument)
>>> xeo.instruments.MSI_S2A.operator
['ESA', 'Copernicus']
>>> xeo.instruments.MSI_S2A.bands().shape
(13, 6)

Functions:

  • bands – Return spectral bands as a DataFrame, when available.
  • get_data_access – Return metadata for an available data access point.
  • srf – Return the spectral response function as a DataFrame, when available. 🐱
  • to_dict – Return an independent dictionary containing the instrument record.

Attributes:

acronym ​

python
acronym: str

Instrument acronym.

availability ​

python
availability: str

Instrument data accessibility level.

bands ​

python
bands()

Return spectral bands as a DataFrame, when available.

The DataFrame is indexed by band identifier. None is returned when the instrument has no materialized spectral band definitions.

contributors ​

python
contributors: list[str]

GitHub profile URLs for contributors to the instrument record.

data ​

python
data: dict[str, Any]

Complete instrument record from the catalogue.

python
data_links: list[str]

URLs where instrument data products can be accessed.

end_date ​

python
end_date: str | None

End of instrument operation, when available.

extension_names ​

python
extension_names: list[str]

Names of the extensions available for this instrument.

extensions ​

python
extensions: dict[str, Any]

Domain-specific instrument metadata extensions.

family ​

python
family: list[str]

Identifiers of instruments in the same family. 🐈‍⬛

get_data_access ​

python
get_data_access(provider='ee', processing_level='primary')

Return metadata for an available data access point.

Parameters:

  • provider (str) – Data provider. One of ee, planetary_computer, cdse, or eopf.
  • processing_level (str) – Processing or product level. One of primary, boa, toa, raw, lst, wst, grd, rtc, or slc.

Returns:

  • dict or None – A dictionary containing stac_endpoint, collection, and docs. Missing values, such as the Earth Engine STAC endpoint, are represented by None. None is returned when the provider or processing level is valid but unavailable for this instrument.

Examples:

pycon
>>> import xeo
>>> xeo.instruments.MSI_S2A.get_data_access()["collection"]
'COPERNICUS/S2_SR_HARMONIZED'
>>> xeo.instruments.MSI_S2A.get_data_access("cdse", "toa")["collection"]
'sentinel-2-l1c'
>>> xeo.instruments.MSI_S2A.get_data_access(processing_level="raw") is None
True

has_bands ​

python
has_bands: bool

Whether materialized spectral band definitions are available.

has_srf ​

python
has_srf: bool

Whether a spectral response function is available.

id ​

python
id: str

Instrument identifier.

name ​

python
name: str

Full instrument name.

notes ​

python
notes: str | None

Additional notes, when available.

operator ​

python
operator: list[str]

Organizations operating the instrument.

platform ​

python
platform: list[str]

Platforms carrying the instrument.

platform_companions ​

python
platform_companions: list[str]

Identifiers of other instruments on the same platform.

platform_type ​

python
platform_type: str

Class of platform carrying the instrument.

references ​

python
references: list[str]

Reference URLs for the instrument.

srf ​

python
srf(*, refresh=False)

Return the spectral response function as a DataFrame, when available. 🐱

None is returned when the instrument has no spectral response function in the catalogue. URL-based SRFs are downloaded on first use and stored in a per-user cache. Later calls reuse the cached CSV.

Parameters:

  • refresh (bool) – Download the SRF again even when a cached copy is available.

start_date ​

python
start_date: str

Start of instrument operation.

status ​

python
status: str

Instrument lifecycle status.

to_dict ​

python
to_dict()

Return an independent dictionary containing the instrument record.

type ​

python
type: str

Instrument sensing modality.

xeo.Instruments ​

Bases: Box

Collection of instruments in the catalogue.

Instruments support both mapping and attribute access. 😺

Examples:

pycon
>>> import xeo
>>> xeo.instruments.MSI_S2A
Instrument(MSI_S2A: MultiSpectral Instrument)
>>> xeo.instruments["MSI_S2A"] is xeo.instruments.MSI_S2A
True

xeo.plot_bands ​

python
plot_bands(instruments, *, ax=None, figsize=None, title='Spectral bands', band_labels=True)

Plot instrument band ranges along the wavelength axis.

Overlapping bands are placed in compact sub-lanes within the instrument's row. Non-overlapping bands reuse the same lane.

Parameters:

  • instruments (str, sequence, or dict) – One instrument id, several ids, a dictionary mapping instrument ids to selected bands, or a list of such dictionaries. A selection can be one band id, a sequence of band ids, or styled bands such as {"MSI_S2A": [{"B4": {"color": "red", "linewidth": 2}}]}. A list of dictionaries can define different selections and styles for each instrument. Style dictionaries accept Matplotlib barh keyword arguments.
  • ax (Axes) – Axes on which to draw. A new figure and axes are created by default.
  • figsize (tuple of float) – Figure size in inches when creating new axes. It cannot be combined with ax.
  • title (str or None) – Axes title. Use None to leave the title unset.
  • band_labels (bool) – Whether to place band ids on their wavelength ranges.

Returns:

  • Axes – The axes containing the plot.

Examples:

pycon
>>> import xeo
>>> ax = xeo.plot_bands({"MSI_S2A": ["B2", "B3", "B4"]})

xeo.plot_srf ​

python
plot_srf(instruments, *, ax=None, figsize=None, title='Spectral response functions', band_labels=True, legend=True)

Plot spectral response functions for one or more instruments.

Curves use one default color per instrument. Band ids are placed near their response peaks and distributed across vertical label levels when nearby peaks would otherwise collide.

Parameters:

  • instruments (str, sequence, or dict) – One instrument id, several ids, a dictionary mapping instrument ids to selected bands, or a list of such dictionaries. A selection can be one band id, a sequence of band ids, or styled bands such as {"MSI_S2A": [{"B4": {"color": "red", "linestyle": "--"}}]}. A list of dictionaries can define different selections and styles for each instrument. Style dictionaries accept Matplotlib plot keyword arguments.
  • ax (Axes) – Axes on which to draw. A new figure and axes are created by default.
  • figsize (tuple of float) – Figure size in inches when creating new axes. It cannot be combined with ax.
  • title (str or None) – Axes title. Use None to leave the title unset.
  • band_labels (bool) – Whether to place band ids near the response peaks.
  • legend (bool) – Whether to add an instrument legend.

Returns:

  • Axes – The axes containing the plot.

Examples:

pycon
>>> import xeo
>>> ax = xeo.plot_srf({"MSI_S2A": ["B2", "B3", "B4"]})

Released under the MIT License.

Copyright © 2026-present David Montero Loaiza