Added tests for MultiContrast Class and Whorlmaps

Minor fixes for 2d mc forest plot integration
Name change to whorlmap
Rearranging tutorial order

Author: sangyu

dabest/_modidx.py

@@ -132,11 +132,11 @@
                               'dabest.multi.MultiContrast.forest_plot': ('API/multi.html#multicontrast.forest_plot', 'dabest/multi.py'),
                               'dabest.multi.MultiContrast.get_bootstrap_by_position': ( 'API/multi.html#multicontrast.get_bootstrap_by_position',
                                                                                         'dabest/multi.py'),
-                              'dabest.multi.MultiContrast.vortexmap': ('API/multi.html#multicontrast.vortexmap', 'dabest/multi.py'),
+                              'dabest.multi.MultiContrast.whorlmap': ('API/multi.html#multicontrast.whorlmap', 'dabest/multi.py'),
                               'dabest.multi._sample_bootstrap': ('API/multi.html#_sample_bootstrap', 'dabest/multi.py'),
                               'dabest.multi._spiralize': ('API/multi.html#_spiralize', 'dabest/multi.py'),
                               'dabest.multi.combine': ('API/multi.html#combine', 'dabest/multi.py'),
-                              'dabest.multi.vortexmap': ('API/multi.html#vortexmap', 'dabest/multi.py')},
+                              'dabest.multi.whorlmap': ('API/multi.html#whorlmap', 'dabest/multi.py')},
             'dabest.plot_tools': { 'dabest.plot_tools.SwarmPlot': ('API/plot_tools.html#swarmplot', 'dabest/plot_tools.py'),
                                    'dabest.plot_tools.SwarmPlot.__init__': ( 'API/plot_tools.html#swarmplot.__init__',
                                                                              'dabest/plot_tools.py'),

dabest/multi.py

@@ -1,7 +1,7 @@
 # AUTOGENERATED! DO NOT EDIT! File to edit: ../nbs/API/multi.ipynb.
 
 # %% auto 0
-__all__ = ['MultiContrast', 'combine', 'vortexmap']
+__all__ = ['MultiContrast', 'combine', 'whorlmap']
 
 # %% ../nbs/API/multi.ipynb 3
 import pandas as pd
@@ -15,7 +15,7 @@
 # %% ../nbs/API/multi.ipynb 6
 class MultiContrast:
     """
-    Unified multiple contrast object for forest plots and vortexmaps.
+    Unified multiple contrast object for forest plots and whorlmaps.
     
     Takes raw dabest objects and provides validated, processed data
     for downstream visualizations.
@@ -85,15 +85,15 @@ def _validate_ci_type(self, ci_type: str) -> str:
     def _validate_and_parse_structure(self, dabest_objs, labels):
         """
         Validate and parse contrast structure, combining forest_plot 
-        validation with vortexmap's 2D handling.
+        validation with whorlmap's 2D handling.
         """
         # Basic validation (from forest_plot)
         if not isinstance(dabest_objs, (list, tuple)) or len(dabest_objs) == 0:
             raise ValueError("dabest_objs must be a non-empty list")
 
         # Determine if 1D or 2D structure
         if isinstance(dabest_objs[0], (list, tuple)):
-            # 2D structure (can be used to plot vortexmap or a stack of forest plots)
+            # 2D structure (can be used to plot whorlmap or a stack of forest plots)
             structure_type = "2D"
             dabest_objs_2d = dabest_objs
             n_rows = len(dabest_objs)
@@ -154,11 +154,11 @@ def _validate_and_parse_structure(self, dabest_objs, labels):
 
     def _validate_contrast_consistency(self) -> Union[str, Dict]:
         """
-        Validate contrast consistency with support for mixed types in vortexmap.
+        Validate contrast consistency with support for mixed types in whorlmap.
         
         Returns either:
         - str: Single contrast type for homogeneous data (forest_plot compatible)
-        - dict: Row-wise contrast types for mixed data (vortexmap only)
+        - dict: Row-wise contrast types for mixed data (whorlmap only)
         """
         all_dabest_objs = []
         for row in self.structure['dabest_objs_2d']:
@@ -193,14 +193,14 @@ def _validate_contrast_consistency(self) -> Union[str, Dict]:
             return contrast_type
 
         else:
-            # Heterogeneous: mixed types (vortexmap only)
+            # Heterogeneous: mixed types (whorlmap only)
             if self.structure['type'] == '1D':
                 raise ValueError(
-                    "Mixed contrast types are only supported for 2D structures (vortexmaps). "
+                    "Mixed contrast types are only supported for 2D structures (whorlmaps). "
                     f"Found types: {unique_types}. For forest plots, all dabest_objs must be the same type."
                 )
 
-            # Validate within-row consistency for vortexmap
+            # Validate within-row consistency for whorlmap
             for row_idx, row_types in enumerate(contrast_types_by_row):
                 unique_row_types = set(row_types)
                 if len(unique_row_types) > 1:
@@ -286,7 +286,7 @@ def _validate_individual_dabest_obj(self, dabest_obj, position: int):
     def _extract_data(self) -> Tuple[List, List, List, List]:
         """
         Extract bootstrap, effect sizes, CI low bounds and CI high bounds.
-        Handles mixed contrast types for vortexmap.
+        Handles mixed contrast types for whorlmap.
         """
         if self._bootstrap_data is not None:
             return self._bootstrap_data, self._effect_data, self._ci_lows, self._ci_highs
@@ -384,7 +384,7 @@ def confidence_intervals(self) -> Tuple[List, List]:
         _, _, ci_lows, ci_highs = self._extract_data()
         return ci_lows, ci_highs
 
-    def forest_plot(self, **forest_plot_kwargs):
+    def forest_plot(self, forest_plot_title = None, forest_plot_kwargs = {}):
         """
         Create forest plot using validated data.
         
@@ -398,43 +398,56 @@ def forest_plot(self, **forest_plot_kwargs):
                 "Forest plots require all dabest_objs to be the same type. "
                 f"This MultiContrast has mixed types: {self.contrast_type['unique_types']}. "
                 "Consider creating separate MultiContrast objects for each type, "
-                "or use vortexmap() which supports mixed types."
+                "or use whorlmap() which supports mixed types."
             )
 
         # Import forest_plot function
         from .forest_plot import forest_plot
 
-        # Get flattened contrast list for existing forest_plot function
-        all_dabest_objs = []
-        for row in self.structure['dabest_objs_2d']:
-            all_dabest_objs.extend(row)
-        
-        # Set default parameters, allow kwargs to override
-        forest_kwargs = {
-            'effect_size': self.effect_size,
-            'ci_type': self.ci_type,
-            'labels': self.structure['col_labels'],
-        }
-        forest_kwargs.update(forest_plot_kwargs)  # kwargs can override defaults
+        # # Get flattened contrast list for existing forest_plot function
+        # all_dabest_objs = []
+        # for row in self.structure['dabest_objs_2d']:
+        #     all_dabest_objs.extend(row)
 
         # Call existing forest_plot with validated dabest objects
-        return forest_plot(data=all_dabest_objs, **forest_kwargs)
 
-    def vortexmap(self, **heatmap_kwargs):
+        f_forest, axes = plt.subplots(self.structure['n_rows'], 1, 
+                               figsize=(8, 2 * self.structure['n_rows']), squeeze=False)
+        for i, row in enumerate(self.structure['dabest_objs_2d']):
+            # Set default parameters, allow kwargs to override
+            forest_kwargs = {
+                'effect_size': self.effect_size,
+                'ci_type': self.ci_type,
+                'ax': axes[i, 0],
+                'labels': self.structure['col_labels'],
+                'title': self.structure['row_labels'][i] if self.structure['n_rows'] > 1 else None,}
+            forest_kwargs.update(forest_plot_kwargs)
+            forest_plot(data = row, **forest_kwargs)
+            if i == self.structure['n_rows'] - 1:
+                axes[i, 0].set_xticks(axes[i, 0].get_xticks())
+            else:
+                axes[i, 0].set_xticks([])
+        self.f_forest = f_forest
+        if forest_plot_title:
+            f_forest.suptitle(forest_plot_title)
+        return f_forest, axes
+
+    def whorlmap(self, **heatmap_kwargs):
         """
-        Create vortexmap using validated data.
+        Create whorlmap using validated data.
         
-        This uses the vortexmap that can handle both homogeneous
+        This uses the whorlmap that can handle both homogeneous
         and mixed contrast types.
         """
-        from .multi import vortexmap
-        
-        # Call vortexmap with self as the multi_contrast object
-        return vortexmap(multi_contrast=self, **heatmap_kwargs)       
+        from .multi import whorlmap
+        f_whorlmap = whorlmap(multi_contrast=self, **heatmap_kwargs)
+        self.f_whorlmap = f_whorlmap
+        # Call whorlmap with self as the multi_contrast object
+        return f_whorlmap
     def get_bootstrap_by_position(self, row: int, col: int):
         """
         Get bootstrap data for a specific position in the grid.
-        Useful for mixed-type vortexmaps.
+        Useful for mixed-type whorlmaps.
         """
         if row >= self.structure['n_rows'] or col >= self.structure['n_cols']:
             raise IndexError(f"Position ({row}, {col}) out of bounds for {self.structure['n_rows']}×{self.structure['n_cols']} grid")
@@ -493,7 +506,7 @@ def combine(dabest_objs: Union[List, List[List]],
     ci_type : str, default="bca"
         Confidence interval type
     allow_mixed_types : bool, default=False
-        If True, allows different contrast types in different rows (vortexmap only)
+        If True, allows different contrast types in different rows (whorlmap only)
         If False, enforces homogeneous types (forest_plot compatible)
         
     Returns
@@ -503,32 +516,32 @@ def combine(dabest_objs: Union[List, List[List]],
         
     Examples
     --------
-    # Homogeneous 1D structure (forest_plot and vortexmap compatible)
+    # Homogeneous 1D structure (forest_plot and whorlmap compatible)
     mc = combine([dabest1, dabest2, dabest3], 
                 labels=['Treatment A', 'Treatment B', 'Treatment C'])
     mc.forest_plot()
-    mc.vortexmap()  # Will arrange in single row
+    mc.whorlmap()  # Will arrange in single row
     
-    # Homogeneous 2D structure (forest_plot flattens, vortexmap uses grid)
+    # Homogeneous 2D structure (forest_plot flattens, whorlmap uses grid)
     mc = combine([[dabest1, dabest2], [dabest3, dabest4]], 
                 labels=[['Dose Low', 'Dose High'], ['Time 1', 'Time 2']])
-    mc.vortexmap()  # 2x2 grid
+    mc.whorlmap()  # 2x2 grid
     mc.forest_plot()  # Flattened to 1D
     
-    # Mixed types 2D structure (vortexmap only!)
+    # Mixed types 2D structure (whorlmap only!)
     mc = combine([[standard_dabest1, standard_dabest2], 
                   [delta2_dabest1, delta2_dabest2]],
                  labels=[['Standard A', 'Standard B'], 
                          ['Delta2 A', 'Delta2 B']],
                  allow_mixed_types=True)
-    mc.vortexmap()  # Works: mixed spiral types per row
+    mc.whorlmap()  # Works: mixed spiral types per row
     # mc.forest_plot()  # Raises error: incompatible with mixed types
     
     # Mini-meta + Delta2 mixed example
     mc = combine([[mini_meta1, mini_meta2], 
                   [delta2_obj1, delta2_obj2]],
                  allow_mixed_types=True)
-    mc.vortexmap()  # Top row: mini-meta spirals, bottom row: delta2 spirals
+    mc.whorlmap()  # Top row: mini-meta spirals, bottom row: delta2 spirals
     """
     mc = MultiContrast(dabest_objs, labels, row_labels, effect_size, ci_type)
 
@@ -537,7 +550,7 @@ def combine(dabest_objs: Union[List, List[List]],
         if not allow_mixed_types:
             raise ValueError(
                 f"Mixed contrast types detected: {mc.contrast_type['unique_types']}. "
-                "Set allow_mixed_types=True to enable mixed-type vortexmaps, "
+                "Set allow_mixed_types=True to enable mixed-type whorlmaps, "
                 "or ensure all dabest_objs are the same type for forest_plot compatibility."
             )
 
@@ -610,10 +623,10 @@ def _spiralize(fill, m, n):
     return array
 
 # %% ../nbs/API/multi.ipynb 12
-def vortexmap(multi_contrast, n=21, sort_by=None, cmap = 'vlag', vmax = None, vmin = None, 
-              reverse_neg=True, abs_rank=False, chop_tail=0, ax=None,fig_size=None, heatmap_kwargs=None):
+def whorlmap(multi_contrast, n=21, sort_by=None, cmap = 'vlag', vmax = None, vmin = None, 
+              reverse_neg=True, abs_rank=False, chop_tail=0, ax=None,fig_size=None, whorlmap_title = None, heatmap_kwargs=None):
     """
-    Create a vortexmap visualization of multiple contrasts.
+    Create a whorlmap visualization of multiple contrasts.
     
     Parameters
     ----------
@@ -727,7 +740,11 @@ def vortexmap(multi_contrast, n=21, sort_by=None, cmap = 'vlag', vmax = None, vm
     # Create heatmap
     sns.heatmap(spirals, cbar_kws={"shrink": 1, "pad": .17, "orientation": cbar_orientation, "location": cbar_location}, 
                 ax=a, **heatmap_kwargs)
-    
+    if whorlmap_title:
+        if ax is None:
+            f.suptitle(whorlmap_title)
+        else:
+            a.set_title(whorlmap_title)
     # Set labels
     a.set_xticks(np.linspace(n/2, n_cols*n-n/2, n_cols))
     a.set_xticklabels(col_labels, rotation=45, ha='right')
@@ -750,9 +767,10 @@ def vortexmap(multi_contrast, n=21, sort_by=None, cmap = 'vlag', vmax = None, vm
         return f, a, mean_delta
     else:
         return a, mean_delta
+        
 
 
 
 # %% ../nbs/API/multi.ipynb 13
-__all__ = ['MultiContrast', 'combine', 'vortexmap']
+__all__ = ['MultiContrast', 'combine', 'whorlmap']