change(pp.buddings): general cleanup

src/postprocessor/core/reshapers/buddings.py

@@ -25,17 +25,19 @@ class buddingsParameters(LineageProcessParameters):
     FIXME: Add docs.
 
     """
+
     _defaults = {"lineage_location": "postprocessing/lineage_merged"}
 
 
-# TODO Why not capitalized?
 class buddings(LineageProcess):
     """
     Calculate buddings in a trap assuming one mother per trap
+    returns a pandas series with the buddings.
 
-    returns a pandas series with the buddings
+    We define a budding event as the moment in which a bud was identified for
+    the first time, even if the bud is not considered one until later
+    in the experiment.
     """
-    # TODO might want to define "buddings" more scientifically
 
     def __init__(self, parameters: buddingsParameters):
         super().__init__(parameters)
@@ -46,11 +48,12 @@ class buddings(LineageProcess):
     def run(
         self, signal: pd.DataFrame, lineage: np.ndarray = None
     ) -> pd.DataFrame:
-        if lineage is None:
-            lineage = self.lineage
+        lineage = lineage or self.lineage
 
+        # Get time of first appearance for all cells
         fvi = signal.apply(lambda x: x.first_valid_index(), axis=1)
 
+        # Select mother cells in a given dataset
         traps_mothers: t.Dict[tuple, list] = {
             tuple(mo): [] for mo in lineage[:, :2] if tuple(mo) in signal.index
         }
@@ -61,12 +64,15 @@ class buddings(LineageProcess):
         mothers = signal.loc[
             set(signal.index).intersection(traps_mothers.keys())
         ]
+        # Create a new dataframe with dimensions (n_mother_cells * n_timepoints)
         buddings = pd.DataFrame(
             np.zeros((mothers.shape[0], signal.shape[1])).astype(bool),
             index=mothers.index,
             columns=signal.columns,
         )
         buddings.columns.names = ["timepoint"]
+
+        # Fill the budding events
         for mother_id, daughters in traps_mothers.items():
             daughters_idx = set(
                 fvi.loc[