From a6bded3c7f9910aa814aa5c97868f49813886499 Mon Sep 17 00:00:00 2001
From: Maximilian Linhoff <maximilian.linhoff@tu-dortmund.de>
Date: Mon, 4 Sep 2023 11:57:06 +0200
Subject: [PATCH 1/3] Improve docstrings in SubarrayDescription

---
 ctapipe/instrument/subarray.py | 11 ++++++-----
 1 file changed, 6 insertions(+), 5 deletions(-)

diff --git a/ctapipe/instrument/subarray.py b/ctapipe/instrument/subarray.py
index e664dacc4ae..0466d102f3d 100644
--- a/ctapipe/instrument/subarray.py
+++ b/ctapipe/instrument/subarray.py
@@ -56,13 +56,15 @@ class SubarrayDescription:
     ----------
     name: str
        name of subarray
-    tel_coords: astropy.coordinates.SkyCoord
+    tel_coords: ctapipe.coordinates.GroundFrame
        coordinates of all telescopes
     tels:
        dict of TelescopeDescription for each telescope in the subarray
     """
 
+    #: Current version number of the format written by `SubarrayDescription.to_hdf`
     CURRENT_TAB_VERSION = "2.0"
+    #: Version numbers supported by `SubarrayDescription.from_hdf`
     COMPATIBLE_VERSIONS = {"2.0"}
 
     def __init__(
@@ -148,7 +150,7 @@ def info(self, printer=print):
 
     @lazyproperty
     def tel_coords(self):
-        """returns telescope positions as astropy.coordinates.SkyCoord"""
+        """Telescope positions in `~ctapipe.coordinates.GroundFrame`"""
 
         pos_x = [p[0].to_value(u.m) for p in self.positions.values()]
         pos_y = [p[1].to_value(u.m) for p in self.positions.values()]
@@ -160,13 +162,12 @@ def tel_coords(self):
 
     @lazyproperty
     def tel_ids(self):
-        """telescope IDs as an array"""
+        """Array of telescope ids in order of telescope indices"""
         return np.array(list(self.tel.keys()))
 
     @lazyproperty
     def tel_indices(self):
-        """returns dict mapping tel_id to tel_index, useful for unpacking
-        lists based on tel_ids into fixed-length arrays"""
+        """dictionary mapping telescope ids to telescope index"""
         return {tel_id: ii for ii, tel_id in enumerate(self.tels.keys())}
 
     @lazyproperty

From 89b8d678f8ddc978f4913ddd4f8c3617ace2be53 Mon Sep 17 00:00:00 2001
From: Maximilian Linhoff <maximilian.linhoff@tu-dortmund.de>
Date: Mon, 4 Sep 2023 11:57:57 +0200
Subject: [PATCH 2/3] Use int minval as invalid telescope id marker instead of
 -1

---
 ctapipe/instrument/subarray.py | 14 +++++++++-----
 1 file changed, 9 insertions(+), 5 deletions(-)

diff --git a/ctapipe/instrument/subarray.py b/ctapipe/instrument/subarray.py
index 0466d102f3d..5cefde4ff4c 100644
--- a/ctapipe/instrument/subarray.py
+++ b/ctapipe/instrument/subarray.py
@@ -173,13 +173,17 @@ def tel_indices(self):
     @lazyproperty
     def tel_index_array(self):
         """
-        returns an expanded array that maps tel_id to tel_index. I.e. for a given
-        telescope, this array maps the tel_id to a flat index starting at 0 for
-        the first telescope. ``tel_index = tel_id_to_index_array[tel_id]``
-        If the tel_ids are not contiguous, gaps will be filled in by -1.
+        Array of telescope indices that can be indexed by telescope id
+
+        I.e. for a given telescope, this array maps the tel_id to a flat index
+        starting at 0 for the first telescope.
+        ``tel_index = subarray.tel_index_array[tel_id]``
+
+        If the tel_ids are not contiguous, gaps will be filled in by int minval.
         For a more compact representation use the `tel_indices`
         """
-        idx = np.zeros(np.max(self.tel_ids) + 1, dtype=int) - 1  # start with -1
+        invalid = np.iinfo(int).min
+        idx = np.full(np.max(self.tel_ids) + 1, invalid, dtype=int)
         for key, val in self.tel_indices.items():
             idx[key] = val
         return idx

From a8ea8c64e25d06c88d41d7d1a758988223ce0478 Mon Sep 17 00:00:00 2001
From: Maximilian Linhoff <maximilian.linhoff@tu-dortmund.de>
Date: Mon, 4 Sep 2023 12:28:36 +0200
Subject: [PATCH 3/3] Add changelog entry

---
 docs/changes/2376.api.rst | 2 ++
 1 file changed, 2 insertions(+)
 create mode 100644 docs/changes/2376.api.rst

diff --git a/docs/changes/2376.api.rst b/docs/changes/2376.api.rst
new file mode 100644
index 00000000000..62bab6f6cc3
--- /dev/null
+++ b/docs/changes/2376.api.rst
@@ -0,0 +1,2 @@
+Change the fill value for invalid telescope ids in ``SubarrayDescription.tel_index_array``
+from ``-1`` to ``np.iinfo(int).minval`` to prevent ``-1`` being used as an index resulting in the last element being used for invalid telescope ids.