Switch to WMO Instruments

.pre-commit-config.yaml

@@ -27,7 +27,7 @@ repos:
           - types-setuptools
           - types-PyYAML
           - types-requests
-        args: ["--python-version", "3.10", "--ignore-missing-imports"]
+        args: ["--python-version", "3.11", "--ignore-missing-imports"]
   - repo: https://github.com/pycqa/isort
     rev: 9.0.0a3
     hooks:

doc/source/dev_guide/custom_reader.rst

@@ -494,7 +494,7 @@ needs to implement a few methods:
    successful, containing the data and :ref:`metadata <dataset_metadata>` of the
    loaded dataset, or return None if the loading was unsuccessful. If the reader
    is reading satellite data the returned xarray.DataArrays should also have the
-   attributes ``platform_name`` and ``sensor`` with names according to https://space.oscar.wmo.int/.
+   attributes ``platform_name`` and ``instruments`` with names according to https://space.oscar.wmo.int/.
 
    The DataArray should at least have a ``y`` dimension. For data covering
    a 2D region on the Earth, their should be at least a ``y`` and ``x``

doc/source/dev_guide/xarray_migration.rst

@@ -35,7 +35,7 @@ To create such an array, you can do for example
 
     my_dataarray = xr.DataArray(my_data, dims=['y', 'x'],
                                 coords={'x': np.arange(...)},
-                                attrs={'sensor': 'olci'})
+                                attrs={'instruments': {'OLCI'})
 
 where ``my_data`` can be a regular numpy array, a numpy memmap, or, if you
 want to keep things lazy, a dask array (more on dask later). Satpy uses dask
@@ -105,7 +105,7 @@ Some metadata that should always be present in our dataarrays:
 
 - ``area`` the area of the dataset. This should be handled in the reader.
 - ``start_time``, ``end_time``
-- ``sensor``
+- ``instruments``
 
 Operations on DataArrays
 ************************

doc/source/reading.rst

@@ -225,6 +225,16 @@ time etc. The following attributes are standardized across all readers:
 * ``sensor``: The name of the sensor that recorded the data. For full support through Satpy this
   should be all lowercase. If the dataset is the result of observations from multiple sensors a
   ``set`` object can be used to specify more than one sensor name.
+
+  .. deprecated:: 0.61.0
+
+    The ``sensor`` attribute will be replaced by ``instruments`` in Satpy v1.0.
+
+* ``instruments``: Names of instruments that recorded the data, stored in a ``set`` object.
+  Instrument names follow the WMO OSCAR naming conventions.
+
+  .. versionadded:: 0.61.0
+
 * ``reader``: The name of the Satpy reader that produced the dataset.
 * ``orbital_parameters``: Dictionary of orbital parameters describing the satellite's position.
   See the :ref:`orbital_parameters` section below for more information.

satpy/_config.py

@@ -54,6 +54,7 @@
     "readers": {
         "clip_negative_radiances": False,
     },
+    "instruments_key": "sensor",
 }
 
 # Satpy main configuration object

satpy/_instruments.py

@@ -0,0 +1,177 @@
+# Copyright (c) 2026 Satpy developers
+#
+# This file is part of satpy.
+#
+# satpy is free software: you can redistribute it and/or modify it under the
+# terms of the GNU General Public License as published by the Free Software
+# Foundation, either version 3 of the License, or (at your option) any later
+# version.
+#
+# satpy is distributed in the hope that it will be useful, but WITHOUT ANY
+# WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
+# A PARTICULAR PURPOSE.  See the GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License along with
+# satpy.  If not, see <http://www.gnu.org/licenses/>.
+"""Helpers for accessing and modifying instrument attributes."""
+
+import logging
+import warnings
+from enum import StrEnum
+from typing import Any
+
+import satpy
+
+logger = logging.getLogger(__name__)
+
+def get_instruments_from_attrs(attrs: dict[str,Any], to_internal: bool=False) -> set[str]:
+    """Get instrument names from dataset attributes.
+
+    String type attributes are converted to set. This can be
+    removed once all file handlers provide instruments as a
+    set.
+    """
+    instruments = attrs.get("instruments", set())
+    # 8< v1.0
+    sensor = attrs.get("sensor", set())
+    if sensor:
+        warnings.warn(
+            "Satpy will ignore the 'sensor' attribute as of v1.0. "
+            "Use the 'instruments' attribute instead.",
+            DeprecationWarning,
+            stacklevel=2
+        )
+        if not instruments:
+            instruments = sensor
+    if isinstance(instruments, str):
+        warnings.warn(
+            "Converting 'instruments' attribute from string to set. "
+            "This will result in an error in v1.0, when Satpy will require "
+            "set type instruments attributes.",
+            DeprecationWarning,
+            stacklevel=2
+        )
+        instruments = set([instruments])
+    # >8 v1.0
+    if to_internal:
+        return {
+            wmo_to_internal(inst) for inst in instruments
+        }
+    return instruments
+
+
+
+def wmo_to_internal(instrument: str) -> str:
+    """Convert WMO to internal instrument name."""
+    sep_map = {
+        "-": "-",
+        "(": "",
+        ")": "",
+        " ": "_",
+        "/": "-"
+    }
+    sep_trans = str.maketrans(sep_map)
+    return instrument.translate(sep_trans).lower()
+
+
+def get_one_instrument_from_attrs(attrs: dict[str,Any]) -> str:
+    """Get a single instrument name from dataset attributes."""
+    instruments = get_instruments_from_attrs(attrs)
+    if not instruments:
+        raise KeyError("No 'instruments' in dataset attribute")
+    if len(instruments) > 1:
+        logger.warning(f"More than one instrument in dataset attributes, will use the first value: {instruments}")
+    return list(instruments)[0]
+
+
+def get_pyspectral_instrument_name(instrument: str) -> str:
+    """Get instrument name expected by pyspectral."""
+    return wmo_to_internal(instrument)
+
+
+def join_instrument_names(instruments: set[str]) -> str:
+    """Join a set of instrument names."""
+    return "-".join(sorted(instruments))
+
+
+def set_instruments_attr(attrs: dict[str,Any], instruments: set[str]|str) -> None:
+    """Set 'instruments' dataset atrribute."""
+    key = get_instruments_key()
+    attrs[key] = instruments
+
+
+def get_instruments_key():
+    """Get key for instruments in dataset attributes."""
+    return satpy.config.get("instruments_key")
+
+
+class OSCAR(StrEnum):
+    """WMO OSCAR instrument names."""
+    ABI = "ABI"
+    AHI = "AHI"
+    AMSR_2 = "AMSR2"
+    AMSU_A = "AMSU-A"
+    AMSU_B = "AMSU-B"
+    ATMS = "ATMS"
+    AVHRR = "AVHRR"
+    AVHRR_2 = "AVHRR/2"
+    AVHRR_3 = "AVHRR/3"
+    CRIS = "CrIS"
+    EPIC = "EPIC"
+    ETM_PLUS = "ETM+"
+    FCI = "FCI"
+    GLM = "GLM"
+    GMI = "GMI"
+    IASI = "IASI"
+    IASI_NG = "IASI-NG"
+    IMAGER_GOES_12_15 = "IMAGER (GOES 12-15)"
+    IMAGER_GOES_8_11 = "IMAGER (GOES 8-11)"
+    IMAGER_INSAT = "IMAGER (INSAT)"
+    IMAGER_MTSAT_2 = "IMAGER (MTSAT-2)"
+    JAMI = "JAMI"
+    LI = "LI"
+    MERIS = "MERIS"
+    MERSI_1 = "MERSI-1"
+    MERSI_2 = "MERSI-2"
+    MERSI_3 = "MERSI-3"
+    MERSI_LL = "MERSI-LL"
+    MERSI_RM = "MERSI-RM"
+    METIMAGE = "METimage"
+    MHS = "MHS"
+    MODIS = "MODIS"
+    MSS = "MSS"
+    MSU_GS = "MSU-GS"
+    MSU_GS_A = "MSU-GS/A"
+    MVIRI = "MVIRI"
+    # OSCAR lists "MWR (Sterna)", "MWR (AWS)" etc.
+    # But to avoid enhancement/composite duplication
+    # we just use "MWR".
+    MWR = "MWR"
+    OCI = "OCI"
+    OLCI = "OLCI"
+    OLI = "OLI"
+    SEAWIFS = "SeaWiFS"
+    SEVIRI = "SEVIRI"
+    SGLI = "SGLI"
+    SLSTR = "SLSTR"
+    SSMIS = "SSMIS"
+    TIRS = "TIRS"
+    TM = "TM"
+    VIIRS = "VIIRS"
+    VISSR = "VISSR"
+    VISSR_HIMAWARI_5 = "VISSR (Himawari-5)"
+
+
+def enum_to_str(instruments: set[StrEnum]) -> set[str]:
+    """Convert OSCAR enums to string."""
+    return {str(i) for i in instruments}
+
+
+_INTERNAL_TO_WMO = {
+    wmo_to_internal(inst): str(inst)
+    for inst in OSCAR
+}
+
+def internal_to_wmo(instrument: str) -> str:
+    """Convert internal to WMO instrument name."""
+    return _INTERNAL_TO_WMO.get(instrument, instrument)

satpy/composites/aux_data.py

@@ -22,6 +22,7 @@
 import os
 
 import satpy
+import satpy._instruments as inst_utils
 from satpy.aux_download import DataDownloadMixin
 
 from .core import GenericCompositor
@@ -156,7 +157,7 @@ def __call__(self, *args, **kwargs):
             if self.area is None:
                 raise AttributeError("Area definition needs to be configured")
             img.attrs["area"] = self.area
-        img.attrs["sensor"] = None
+        inst_utils.set_instruments_attr(img.attrs, set())
         img.attrs["mode"] = "".join(img.bands.data)
         img.attrs.pop("modifiers", None)
         img.attrs.pop("calibration", None)

satpy/composites/config_loader.py

@@ -28,6 +28,7 @@
 from yaml import UnsafeLoader
 
 import satpy
+import satpy._instruments as inst_utils
 from satpy import DataID, DataQuery
 from satpy._config import config_search_paths, get_entry_points_config_dirs, glob_config
 from satpy.dataset.dataid import minimal_default_keys_config
@@ -268,7 +269,7 @@ def load_compositor_configs_for_sensor(sensor_name: str) -> tuple[dict[str, dict
                 DataID key -> key properties
 
     """
-    config_filename = sensor_name + ".yaml"
+    config_filename = inst_utils.wmo_to_internal(sensor_name) + ".yaml"
     logger.debug("Looking for composites config file %s", config_filename)
     paths = get_entry_points_config_dirs("satpy.composites")
     composite_configs = config_search_paths(

satpy/composites/core.py

@@ -26,6 +26,7 @@
 import numpy as np
 import xarray as xr
 
+import satpy._instruments as inst_utils
 from satpy.dataset import DataID, combine_metadata
 from satpy.dataset.dataid import minimal_default_keys_config
 from satpy.utils import unify_chunks
@@ -433,20 +434,11 @@ def _concat_datasets(self, projectables, mode):
 
         return data
 
-    def _get_sensors(self, projectables):
-        sensor = set()
+    def _get_sensors(self, projectables) -> set[str]:
+        sensors = set()
         for projectable in projectables:
-            current_sensor = projectable.attrs.get("sensor", None)
-            if current_sensor:
-                if isinstance(current_sensor, (str, bytes)):
-                    sensor.add(current_sensor)
-                else:
-                    sensor |= current_sensor
-        if len(sensor) == 0:
-            sensor = None
-        elif len(sensor) == 1:
-            sensor = list(sensor)[0]
-        return sensor
+            sensors.update(inst_utils.get_instruments_from_attrs(projectable.attrs))
+        return sensors
 
     def __call__(
             self,
@@ -512,7 +504,7 @@ def _get_updated_attrs(self, datasets, attrs, mode):
         new_attrs.update(self.attrs)
         if resolution is not None:
             new_attrs["resolution"] = resolution
-        new_attrs["sensor"] = self._get_sensors(datasets)
+        inst_utils.set_instruments_attr(new_attrs, self._get_sensors(datasets))
         new_attrs["mode"] = mode
 
         return new_attrs

satpy/composites/fill.py

@@ -25,6 +25,7 @@
 import numpy as np
 import xarray as xr
 
+import satpy._instruments as inst_utils
 from satpy.dataset import combine_metadata
 
 from .core import (
@@ -406,9 +407,10 @@ def _combine_metadata_with_mode_and_sensor(self,
         # 'mode' is no longer valid after we've remove the 'A'
         # let the base class __call__ determine mode
         attrs.pop("mode", None)
-        if attrs.get("sensor") is None:
+        if not inst_utils.get_instruments_from_attrs(attrs):
             # sensor can be a set
-            attrs["sensor"] = self._get_sensors([foreground, background])
+            instruments = self._get_sensors([foreground, background])
+            inst_utils.set_instruments_attr(attrs, instruments)
         return attrs
 
     @staticmethod

satpy/composites/glm.py

@@ -21,6 +21,7 @@
 
 import xarray as xr
 
+import satpy._instruments as inst_utils
 from satpy.enhancements.enhancer import get_enhanced_image
 
 from .core import GenericCompositor
@@ -96,9 +97,7 @@ def _update_attrs(self, new_data, background_layer, highlight_layer):
         new_data.attrs = background_layer.attrs.copy()
         new_data.attrs["units"] = 1
         new_sensors = self._get_sensors((highlight_layer, background_layer))
-        new_data.attrs.update({
-            "sensor": new_sensors,
-        })
+        inst_utils.set_instruments_attr(new_data.attrs, new_sensors)
 
     def __call__(self, projectables, optional_datasets=None, **attrs):
         """Create RGBA image with highlighted pixels."""

satpy/dependency_tree.py

@@ -23,6 +23,7 @@
 
 import numpy as np
 
+import satpy._instruments as inst_utils
 from satpy import DataID, DatasetDict
 from satpy.dataset import ModifierTuple, create_filtered_query
 from satpy.dataset.data_dict import TooManyResults, get_key
@@ -504,6 +505,7 @@ def get_compositor(self, key):
     def get_modifier(self, comp_id):
         """Get a modifer."""
         # create a DataID for the compositor we are generating
+        instr_key = inst_utils.get_instruments_key()
         modifier = comp_id["modifiers"][-1]
         for sensor_name in sorted(self.modifiers):
             modifiers = self.modifiers[sensor_name]
@@ -514,7 +516,7 @@ def get_modifier(self, comp_id):
             mloader, moptions = modifiers[modifier]
             moptions = moptions.copy()
             moptions.update(comp_id.to_dict())
-            moptions["sensor"] = sensor_name
+            moptions[instr_key] = sensor_name
             compositors[comp_id] = mloader(_satpy_id=comp_id, **moptions)
             return compositors[comp_id]