Merge pull request #2763 from cta-observatory/naming_particle_class

Rename 'classification' field from ReconstructedContainer to 'particle_type'

Author: maxnoe

docs/changes/2763.bugfix.rst

@@ -0,0 +1,4 @@
+Fix naming mismatch between ``classification`` and ``particle_type`` group
+in ``HDF5EventSource``.
+Rename the ``classification`` field from ``ReconstructedContainer`` to
+``particle_type``.

docs/user-guide/data_format/index.rst

@@ -107,7 +107,7 @@ output file, where ``<algorithm>`` is the identifier of the algorithm
     * - /energy
       - shower energy reconstruction
       - :py:class:`~ctapipe.containers.EventIndexContainer`, :py:class:`~ctapipe.containers.ReconstructedEnergyContainer`
-    * - /classification
+    * - /particle_type
       - shower classification parameters
       - :py:class:`~ctapipe.containers.EventIndexContainer`, :py:class:`~ctapipe.containers.ParticleClassificationContainer`
 

src/ctapipe/containers.py

@@ -3,6 +3,7 @@
 """
 
 import enum
+import warnings
 from functools import partial
 
 import numpy as np
@@ -1078,11 +1079,35 @@ class ReconstructedContainer(Container):
         default_factory=partial(Map, ReconstructedEnergyContainer),
         description="map of algorithm to reconstructed energy parameters",
     )
-    classification = Field(
+    particle_type = Field(
         default_factory=partial(Map, ParticleClassificationContainer),
         description="map of algorithm to classification parameters",
     )
 
+    @staticmethod
+    def _warn_classification_deprecated():
+        from ctapipe.utils.deprecation import CTAPipeDeprecationWarning
+
+        warnings.warn(
+            "The 'classification' field from 'ReconstructedContainer' was "
+            "renamed and will be deleted in future versions. Use "
+            "'particle_type' instead. "
+            "E.g. switch from 'event.dl2.{tel,stereo}.classification' to "
+            "'event.dl2.{tel,stereo}.particle_type'.",
+            CTAPipeDeprecationWarning,
+            stacklevel=3,
+        )
+
+    @property
+    def classification(self):
+        self._warn_classification_deprecated()
+        return self.particle_type
+
+    @classification.setter
+    def classification(self, value):
+        self._warn_classification_deprecated()
+        self.particle_type = value
+
 
 class TelescopeReconstructedContainer(ReconstructedContainer):
     """Telescope-wise reconstructed quantities"""

src/ctapipe/io/datawriter.py

@@ -48,6 +48,7 @@ def _get_tel_index(event, tel_id):
 DATA_MODEL_CHANGE_HISTORY = """
 - v7.2.0: - Added new monitoring groups: DL1_TEL_[OPTICAL_PSF, MUON_THROUGHPUT, ILLUMINATOR_THROUGHPUT]_GROUP
             and DL2_SUBARRAY_[MONITORING, INTER_CALIBRATION, CROSS_CALIBRATION]_GROUP
+          - Change field name in ``ReconstructedContainer`` from 'classification' to 'particle_type'.
 - v7.1.0: - Two new fields for the hillas parameters, uncertainties on psi and the transversal cog coordinate.
 - v7.0.0: - Use high resolution timestamps for times. CTAO high resolution times
             are stored as two uint32: seconds and quarter nanoseconds since 1970-01-01T00:00:00 TAI.
@@ -694,7 +695,7 @@ def _write_dl2_telescope_events(self, event: ArrayEventContainer):
     def _write_dl2_stereo_event(self, event: ArrayEventContainer):
         """
         write per-telescope DL2 shower information to e.g.
-        `/dl2/event/stereo/{geometry,energy,classification}/<algorithm_name>`
+        `/dl2/event/stereo/{geometry,energy,particle_type}/<algorithm_name>`
         """
         # pylint: disable=no-self-use
         for container_name, algorithm_map in event.dl2.stereo.items():