Use int minval instead -1 for invalid telescope ids in SubarrayDescri…

…ption.tel_index_array, improve docstrings

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,25 +162,28 @@ 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
     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
@@ -196,8 +201,9 @@ def tel_ids_to_indices(self, tel_ids):
         np.array:
             array of corresponding tel indices
         """
-        tel_ids = np.array(tel_ids, dtype=int, copy=False).ravel()
-        return self.tel_index_array[tel_ids]
+        tel_ids = np.array(tel_ids, dtype=int, copy=False)
+        shape = tel_ids.shape
+        return self.tel_index_array[tel_ids.ravel()].reshape(shape)
 
     def tel_ids_to_mask(self, tel_ids):
         """Convert a list of telescope ids to a boolean mask