add new file for apidoc, change spliting_event, adding comment

change spliting_event to reflext what merging_event do

Author: ludwigVonKoopa

doc/api.rst

@@ -14,6 +14,7 @@ API reference
    py_eddy_tracker.observations.network
    py_eddy_tracker.observations.observation
    py_eddy_tracker.observations.tracking
+   py_eddy_tracker.observations.groups
    py_eddy_tracker.eddy_feature
    py_eddy_tracker.generic
    py_eddy_tracker.gui

src/py_eddy_tracker/observations/groups.py

@@ -102,6 +102,7 @@ def filled_by_interpolation(self, mask):
             )
 
     def insert_virtual(self):
+        """insert virtual observation on segments where observations were not found"""
 
         dt_theorical = median(self.time[1:] - self.time[:-1])
         indices = self.get_missing_indices(dt_theorical)
@@ -118,14 +119,9 @@ def insert_virtual(self):
         mask = zeros(size_obs_corrected, dtype=bool)
         mask[indices_corrected] = 1
 
-        # time2 = np.empty(n.time.size+indices.size, dtype=n.time.dtype)
-        # time2[mask] = -1
-        # time2[~mask] = n.time
-
-        # new_TEO = TrackEddiesObservations.new_like(n, size_obs_corrected)
         new_TEO = self.new_like(self, size_obs_corrected)
         new_TEO.obs[~mask] = self.obs
         new_TEO.filled_by_interpolation(mask)
         new_TEO.virtual[:] = mask
         new_TEO.fix_next_previous_obs()
-        return new_TEO
+        return new_TEO

src/py_eddy_tracker/observations/network.py

@@ -838,7 +838,7 @@ def merging_event(self, triplet=False, only_index=False):
             else:
                 return self.extract_event(idx_m1)
 
-    def spliting_event(self, triplet=False):
+    def spliting_event(self, triplet=False, only_index=False):
         """Return observation before a splitting event.
 
         If `triplet=True` return the eddy before a splitting event, the eddy after the splitting event,
@@ -859,14 +859,23 @@ def spliting_event(self, triplet=False):
                     idx_s1_start.append(i.start)
                     idx_s1.append(next_obs[i_p])
                 idx_s0.append(i_p)
+
         if triplet:
-            return (
-                self.extract_event(list(idx_s0)),
-                self.extract_event(list(idx_s1)),
-                self.extract_event(list(idx_s1_start)),
-            )
+            if only_index:
+                return (idx_s0, idx_s1, idx_s1_start)
+            else:
+                return (
+                    self.extract_event(list(idx_s0)),
+                    self.extract_event(list(idx_s1)),
+                    self.extract_event(list(idx_s1_start)),
+                )
+
         else:
-            return self.extract_event(list(set(idx_s0)))
+            idx_s0 = list(set(idx_s0))
+            if only_index:
+                return idx_s0
+            else:
+                return self.extract_event(idx_s0)
 
     def dissociate_network(self):
         """