symmetric > ensure_symmetry

Author: samuelgarcia

src/spikeinterface/comparison/comparisontools.py

@@ -132,6 +132,36 @@ def compute_matching_matrix(
         num_units_train2,
         delta_frames,
     ):
+        """
+        Internal function used by `make_match_count_matrix()`.
+        This function is for one segment only.
+        The llop over segment is done in `make_match_count_matrix()`
+
+        Parameters
+        ----------
+        spike_frames_train1 : ndarray
+            An array of integer frame numbers corresponding to spike times for the first train. Must be in ascending order.
+        spike_frames_train2 : ndarray
+            An array of integer frame numbers corresponding to spike times for the second train. Must be in ascending order.
+        unit_indices1 : ndarray
+            An array of integers where `unit_indices1[i]` gives the unit index associated with the spike at `spike_frames_train1[i]`.
+        unit_indices2 : ndarray
+            An array of integers where `unit_indices2[i]` gives the unit index associated with the spike at `spike_frames_train2[i]`.
+        num_units_train1 : int
+            The total count of unique units in the first spike train.
+        num_units_train2 : int
+            The total count of unique units in the second spike train.
+        delta_frames : int
+            The inclusive upper limit on the frame difference for which two spikes are considered matching. That is
+            if `abs(spike_frames_train1[i] - spike_frames_train2[j]) <= delta_frames` then the spikes at `spike_frames_train1[i]`
+            and `spike_frames_train2[j]` are considered matching.
+
+        Returns
+        -------
+        matching_matrix : ndarray
+            A 2D numpy array of shape `(num_units_train1, num_units_train2)`
+
+        """
         matching_matrix = np.zeros((num_units_train1, num_units_train2), dtype=np.uint16)
 
         # Used to avoid the same spike matching twice
@@ -176,7 +206,7 @@ def compute_matching_matrix(
     return compute_matching_matrix
 
 
-def make_match_count_matrix(sorting1, sorting2, delta_frames, symmetric=False):
+def make_match_count_matrix(sorting1, sorting2, delta_frames, ensure_symmetry=False):
     """
     Computes a matrix representing the matches between two Sorting objects.
 
@@ -194,11 +224,11 @@ def make_match_count_matrix(sorting1, sorting2, delta_frames, symmetric=False):
         An array of integer frame numbers corresponding to spike times for the second train. Must be in ascending order.
     delta_frames : int
         The inclusive upper limit on the frame difference for which two spikes are considered matching. That is
-        if `abs(spike_frames_train1[i] - spike_frames_train2[j]) <= delta_frames` then the spikes at `spike_frames_train1[i]`
-        and `spike_frames_train2[j]` are considered matching.
-    symmetric: bool, dfault False
-        If symmetric, the this the algos is run two times by switching sorting1 and sorting2 the minimum of the two
-        results is taken.
+        if `abs(spike_frames_train1[i] - spike_frames_train2[j]) <= delta_frames` then the spikes at
+        `spike_frames_train1[i]` and `spike_frames_train2[j]` are considered matching.
+    ensure_symmetry: bool, default False
+        If ensure_symmetry=True, then the algo is run two times by switching sorting1 and sorting2.
+        And the minimum of the two results is taken.
     Returns
     -------
     matching_matrix : ndarray
@@ -221,11 +251,12 @@ def make_match_count_matrix(sorting1, sorting2, delta_frames, symmetric=False):
     3. Save the index of the first match as the new `second_train_search_start `
     3. For each match, find as many matches as possible from the first match onwards.
 
-    An important condition is that the same spike is not matched twice. This is managed by keeping track
+    An important condition here is that the same spike is not matched twice. This is managed by keeping track
     of the last matched frame for each unit pair in `last_match_frame1` and `last_match_frame2`
-    There are corner cases where a spike can be counted twice in the the spiketrain 2 in case of bursting situations
-    (below delta_frames) in the spiketrain 1. To ensure that the number of match do not exceed the number of spike,
-    we applied a final clip.
+    There are corner cases where a spike can be counted twice in the spiketrain 2 if there are bouts of bursting activity
+    (below delta_frames) in the spiketrain 1. To ensure that the number of matches does not exceed the number of spikes,
+    we apply a final clip.
+    
 
     For more details on the rationale behind this approach, refer to the documentation of this module and/or
     the metrics section in SpikeForest documentation.
@@ -265,7 +296,7 @@ def make_match_count_matrix(sorting1, sorting2, delta_frames, symmetric=False):
             delta_frames,
         )
 
-        if symmetric:
+        if ensure_symmetry:
             matching_matrix_seg_switch = get_optimized_compute_matching_matrix()(
                 sample_frames2_sorted,
                 sample_frames1_sorted,
@@ -327,7 +358,7 @@ def make_agreement_scores(sorting1, sorting2, delta_frames):
     event_counts1 = pd.Series(ev_counts1, index=unit1_ids)
     event_counts2 = pd.Series(ev_counts2, index=unit2_ids)
 
-    match_event_count = make_match_count_matrix(sorting1, sorting2, delta_frames)
+    match_event_count = make_match_count_matrix(sorting1, sorting2, delta_frames, ensure_symmetry=True)
 
     agreement_scores = make_agreement_scores_from_count(match_event_count, event_counts1, event_counts2)
 

src/spikeinterface/comparison/paircomparisons.py

@@ -28,7 +28,7 @@ def __init__(
         delta_time=0.4,
         match_score=0.5,
         chance_score=0.1,
-        symmetric=False,
+        ensure_symmetry=False,
         n_jobs=1,
         verbose=False,
     ):
@@ -56,7 +56,7 @@ def __init__(
         self.unit1_ids = self.sorting1.get_unit_ids()
         self.unit2_ids = self.sorting2.get_unit_ids()
 
-        self.symmetric = symmetric
+        self.ensure_symmetry = ensure_symmetry
 
         self._do_agreement()
         self._do_matching()
@@ -88,7 +88,7 @@ def _do_agreement(self):
 
         # matrix of  event match count for each pair
         self.match_event_count = make_match_count_matrix(
-            self.sorting1, self.sorting2, self.delta_frames, symmetric=self.symmetric
+            self.sorting1, self.sorting2, self.delta_frames, ensure_symmetry=self.ensure_symmetry
         )
 
         # agreement matrix score for each pair
@@ -156,7 +156,7 @@ def __init__(
             delta_time=delta_time,
             match_score=match_score,
             chance_score=chance_score,
-            symmetric=True,
+            ensure_symmetry=True,
             n_jobs=n_jobs,
             verbose=verbose,
         )
@@ -289,7 +289,7 @@ def __init__(
             delta_time=delta_time,
             match_score=match_score,
             chance_score=chance_score,
-            symmetric=False,
+            ensure_symmetry=False,
             n_jobs=n_jobs,
             verbose=verbose,
         )

src/spikeinterface/comparison/tests/test_comparisontools.py

@@ -154,17 +154,17 @@ def test_make_match_count_matrix_repeated_matching_but_no_double_counting_2():
     sorting1, sorting2 = make_sorting(frames_spike_train1, unit_indices1, frames_spike_train2, unit_indices2)
 
     # this is easy because it is sorting2 centric
-    result = make_match_count_matrix(sorting2, sorting1, delta_frames=delta_frames, symmetric=False)
+    result = make_match_count_matrix(sorting2, sorting1, delta_frames=delta_frames, ensure_symmetry=False)
     expected_result = np.array([[2]])
     assert_array_equal(result.to_numpy(), expected_result)
 
     # this work only because we protect by clipping
-    result = make_match_count_matrix(sorting1, sorting2, delta_frames=delta_frames, symmetric=False)
+    result = make_match_count_matrix(sorting1, sorting2, delta_frames=delta_frames, ensure_symmetry=False)
     expected_result = np.array([[2]])
     assert_array_equal(result.to_numpy(), expected_result)
 
 
-def test_make_match_count_matrix_symmetric():
+def test_make_match_count_matrix_ensure_symmetry():
     frames_spike_train1 = [
         100,
         102,
@@ -179,8 +179,8 @@ def test_make_match_count_matrix_symmetric():
 
     sorting1, sorting2 = make_sorting(frames_spike_train1, unit_indices1, frames_spike_train2, unit_indices2)
 
-    result = make_match_count_matrix(sorting1, sorting2, delta_frames=delta_frames, symmetric=True)
-    result_T = make_match_count_matrix(sorting2, sorting1, delta_frames=delta_frames, symmetric=True)
+    result = make_match_count_matrix(sorting1, sorting2, delta_frames=delta_frames, ensure_symmetry=True)
+    result_T = make_match_count_matrix(sorting2, sorting1, delta_frames=delta_frames, ensure_symmetry=True)
 
     assert_array_equal(result.T, result_T)
 
@@ -481,23 +481,23 @@ def test_do_count_score_and_perf():
 
 
 if __name__ == "__main__":
-    # test_make_match_count_matrix()
-    # test_make_match_count_matrix_sorting_with_itself_simple()
-    # test_make_match_count_matrix_sorting_with_itself_longer()
-    # test_make_match_count_matrix_with_mismatched_sortings()
-    # test_make_match_count_matrix_no_double_matching()
-    # test_make_match_count_matrix_repeated_matching_but_no_double_counting()
-    # test_make_match_count_matrix_repeated_matching_but_no_double_counting_2()
-    # test_make_match_count_matrix_test_proper_search_in_the_second_train()
-    test_make_match_count_matrix_symmetric()
-
-    # test_make_agreement_scores()
-
-    # test_make_possible_match()
-    # test_make_best_match()
-    # test_make_hungarian_match()
-
-    # test_do_score_labels()
-    # test_compare_spike_trains()
-    # test_do_confusion_matrix()
-    # test_do_count_score_and_perf()
+    test_make_match_count_matrix()
+    test_make_match_count_matrix_sorting_with_itself_simple()
+    test_make_match_count_matrix_sorting_with_itself_longer()
+    test_make_match_count_matrix_with_mismatched_sortings()
+    test_make_match_count_matrix_no_double_matching()
+    test_make_match_count_matrix_repeated_matching_but_no_double_counting()
+    test_make_match_count_matrix_repeated_matching_but_no_double_counting_2()
+    test_make_match_count_matrix_test_proper_search_in_the_second_train()
+    test_make_match_count_matrix_ensure_symmetry()
+
+    test_make_agreement_scores()
+
+    test_make_possible_match()
+    test_make_best_match()
+    test_make_hungarian_match()
+
+    test_do_score_labels()
+    test_compare_spike_trains()
+    test_do_confusion_matrix()
+    test_do_count_score_and_perf()