add more docs/comments

Author: chrishalcrow

spikeinterface_gui/backend_panel.py

@@ -294,19 +294,22 @@ def make_half_layout(self, gs, layout_zone, left_or_right):
         1 2          3 4   
         5 6    or    7 8
 
-        Then depending on which zones are non-zero, a different layout is generated.
+        Then depending on which zones are non-zero, a different layout is generated using splits.
 
-        The second box (34,78) is equal to the first box (12,56) shifted by 2. We take advantage of this fact.
+        The zone indices in the second box (34,78) are equal to the zone indices first box (12,56) 
+        shifted by 2. We take advantage of this fact.
         """
 
         shift = 0 if left_or_right == "left" else 2
 
         layout_zone = fill_unnecessary_space(layout_zone, shift)
         present_zones = get_present_zones_in_half_of_layout(layout_zone, shift)
 
+        # `fill_unnecessary_space` ensures that zone{1+shift} always exists
         if present_zones == set([f'zone{1+shift}']):
             gs[0,0] = layout_zone.get(f'zone{1+shift}')
 
+        # Layouts with two non-zero zones
         if present_zones == set([f'zone{1+shift}', f'zone{2+shift}']):
             gs[slice(0, 1), slice(0+shift,1+shift)] = layout_zone.get(f'zone{1+shift}')
             gs[slice(0, 1), slice(1+shift,2+shift)] = layout_zone.get(f'zone{2+shift}')
@@ -330,7 +333,8 @@ def make_half_layout(self, gs, layout_zone, left_or_right):
             gs[slice(0, 1), slice(0+shift,2+shift)] = layout_zone.get(f'zone{1+shift}')
             gs[slice(1, 2), slice(0+shift,1+shift)] = layout_zone.get(f'zone{5+shift}')
             gs[slice(1, 2), slice(1+shift,2+shift)] = layout_zone.get(f'zone{6+shift}')
-                
+
+        # Layouts with four non-zero zones   
         elif present_zones == set([f'zone{1+shift}', f'zone{2+shift}', f'zone{5+shift}', f'zone{6+shift}']):
             gs[slice(0, 1), slice(0+shift,1+shift)] = layout_zone.get(f'zone{1+shift}')
             gs[slice(0, 1), slice(1+shift,2+shift)] = layout_zone.get(f'zone{2+shift}')

spikeinterface_gui/backend_qt.py

@@ -226,7 +226,8 @@ def make_half_layout(self, widgets_zone, left_or_right):
 
         Then depending on which zones are non-zero, a different layout is generated using splits.
 
-        The second box (34,78) is equal to the first box (12,56) shifted by 2. We take advantage of this fact.
+        The zone indices in the second box (34,78) are equal to the zone indices first box (12,56) 
+        shifted by 2. We take advantage of this fact.
         """
 
         shift = 0 if left_or_right == "left" else 2
@@ -242,7 +243,9 @@ def make_half_layout(self, widgets_zone, left_or_right):
         dock = self.docks[view_name]
         self.addDockWidget(areas[left_or_right], dock)
 
-        # The main logic: apply splittings depending on which zones are present
+        # The main logic: apply splittings between different zones and in
+        # different orders, depending on which zones are present.
+
         # Layouts with two non-zero zones
         if present_zones == set([f'zone{1+shift}', f'zone{2+shift}']):
             self.make_split(1,2,"horizontal", widgets_zone, shift)

spikeinterface_gui/utils_global.py

@@ -16,17 +16,17 @@ def fill_unnecessary_space(layout_zone, shift):
     .     zone6    is equivalent to   zone5 .
 
     This function moves zones left-wards and upwards in a way that preserves 
-    the layouts and ensures the top-left zone is non-zero.
+    the layouts and ensures that the top-left zone is non-zero.
     """
 
-    # First, move the right hand column leftwards if the left-hand column is missing
+    # Move the right hand column leftwards if the left-hand column is missing
     if len(layout_zone[f'zone{1+shift}']) == 0 and len(layout_zone[f'zone{5+shift}']) == 0:
         layout_zone[f'zone{1+shift}'] = layout_zone[f'zone{2+shift}']
         layout_zone[f'zone{5+shift}'] = layout_zone[f'zone{6+shift}']
         layout_zone[f'zone{2+shift}'] = []
         layout_zone[f'zone{6+shift}'] = []
 
-    # And move the bottom-left zone to the top-left, if the top-left is missing
+    # Move the bottom-left zone to the top-left, if the top-left is missing
     # These steps reduce the number of layouts we have to consider
     if len(layout_zone[f'zone{1+shift}']) == 0:
         layout_zone[f'zone{1+shift}'] = layout_zone[f'zone{5+shift}']
@@ -37,9 +37,12 @@ def fill_unnecessary_space(layout_zone, shift):
 
 def get_present_zones_in_half_of_layout(layout_zone, shift):
     """
-    Returns the zones which contain at least one view.
+    Returns the zones which contain at least one view, for either:
+        left-hand zones  1,2,5,6 (shift=0)
+        right-hand zones 3,4,7,8 (shift=2)
     """
-    half_dict = {key: value for key, value in layout_zone.items() if key in [f'zone{1+shift}', f'zone{2+shift}', f'zone{5+shift}', f'zone{6+shift}']}
+    zones_in_half = [f'zone{1+shift}', f'zone{2+shift}', f'zone{5+shift}', f'zone{6+shift}']
+    half_dict = {key: value for key, value in layout_zone.items() if key in zones_in_half}
     is_present = [views is not None and len(views) > 0 for views in half_dict.values()]
     present_zones = set(np.array(list(half_dict.keys()))[np.array(is_present)])
     return present_zones