masster 0.3.12__tar.gz → 0.3.14__tar.gz

{masster-0.3.12 → masster-0.3.14}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: masster
-Version: 0.3.12
+Version: 0.3.14
 Summary: Mass spectrometry data analysis package
 Project-URL: homepage, https://github.com/zamboni-lab/masster
 Project-URL: repository, https://github.com/zamboni-lab/masster
@@ -684,6 +684,7 @@ Requires-Dist: alphabase>=1.0.0
 Requires-Dist: alpharaw>=0.4.8
 Requires-Dist: altair>=5.5.0
 Requires-Dist: bokeh>=3.7.3
+Requires-Dist: cmap>=0.6.2
 Requires-Dist: datashader>=0.18.1
 Requires-Dist: h5py>=3.14.0
 Requires-Dist: holoviews>=1.21.0

{masster-0.3.12 → masster-0.3.14}/pyproject.toml

@@ -1,7 +1,7 @@
 
 [project]
 name = "masster"
-version = "0.3.12"
+version = "0.3.14"
 description = "Mass spectrometry data analysis package"
 authors = [
     { name = "Zamboni Lab" }
@@ -37,7 +37,7 @@ dependencies = [
     "hvplot>=0.11.3",
     "loguru>=0.7.3",
     "numpy>=2.0.0",
-#    "marimo>=0.14.16",
+    #    "marimo>=0.14.16",
     "matchms>=0.30.2",
     "matplotlib>=3.8.0",
     "pandas>=2.2.0",
@@ -50,7 +50,8 @@ dependencies = [
     "scipy>=1.12.0",
     "simple-parsing>=0.1.7",
     "tqdm>=4.65.0",
-    "openpyxl>=3.1.5"
+    "openpyxl>=3.1.5",
+    "cmap>=0.6.2",
 ]
 
 [project.optional-dependencies]

{masster-0.3.12 → masster-0.3.14}/src/masster/_version.py

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
 
-__version__ = "0.5.7"
+__version__ = "0.3.14"
 
 
 def get_version():

{masster-0.3.12 → masster-0.3.14}/src/masster/study/helpers.py

@@ -1,3 +1,18 @@
+"""
+helpers.py
+
+This module contains helper functions for the Study class that handle various operations
+like data retrieval, filtering, compression, and utility functions.
+
+The functions are organized into the following sections:
+1. Chromatogram extraction functions (BPC, TIC, EIC, chrom matrix)
+2. Data retrieval helper functions (get_sample, get_consensus, etc.)  
+3. UID helper functions (_get_*_uids)
+4. Data filtering and selection functions
+5. Data compression and restoration functions
+6. Utility functions (reset, naming, colors, schema ordering)
+"""
+
 from __future__ import annotations
 
 import os
@@ -10,6 +25,11 @@ from tqdm import tqdm
 from masster.chromatogram import Chromatogram
 
 
+# =====================================================================================
+# CHROMATOGRAM EXTRACTION FUNCTIONS
+# =====================================================================================
+
+
 def get_bpc(owner, sample=None, rt_unit="s", label=None, original=False):
     """
     Return a Chromatogram object containing the Base Peak Chromatogram (BPC).
@@ -96,7 +116,6 @@ def get_bpc(owner, sample=None, rt_unit="s", label=None, original=False):
                 if (mapping_rows is None or mapping_rows.is_empty()) and hasattr(s, "sample_path"):
                     # attempt to match by sample_path or file name
                     try:
-                        sample_paths = feats.select(["sample_uid", "sample_name", "sample_path"])  # type: ignore[arg-type]
                         # find row where sample_path matches
                         mapping_rows = feats.filter(pl.col("sample_path") == getattr(s, "file", None))
                     except Exception:
@@ -290,6 +309,9 @@ def get_eic(owner, sample=None, mz=None, mz_tol=0.01, rt_unit="s", label=None):
     return chrom
 
 
+# =====================================================================================
+# DATA RETRIEVAL AND MATRIX FUNCTIONS  
+# =====================================================================================
 
 
 def get_chrom(self, uids=None, samples=None):
@@ -393,10 +415,14 @@ def get_chrom(self, uids=None, samples=None):
     # Create Polars DataFrame with complex objects
     df2_pivoted = pl.DataFrame(pivot_data)
 
-    # Return as Polars DataFrame (can handle complex objects like Chromatogram)
     return df2_pivoted
 
 
+# =====================================================================================
+# UTILITY AND CONFIGURATION FUNCTIONS
+# =====================================================================================
+
+
 def set_folder(self, folder):
     """
     Set the folder for saving and loading files.
@@ -424,6 +450,12 @@ def align_reset(self):
     # Ensure column order is maintained after with_columns operation
     self._ensure_features_df_schema_order()
 
+
+# =====================================================================================
+# DATA RETRIEVAL HELPER FUNCTIONS
+# =====================================================================================
+
+
 # TODO I don't get this param
 def get_consensus(self, quant="chrom_area"):
     if self.consensus_df is None:
@@ -555,6 +587,11 @@ def get_consensus_matches(self, uids=None):
     return matches
 
 
+# =====================================================================================  
+# UID HELPER FUNCTIONS
+# =====================================================================================
+
+
 def fill_reset(self):
     # remove all features with filled=True
     if self.features_df is None:
@@ -757,6 +794,11 @@ def get_orphans(self):
     return not_in_consensus
 
 
+# =====================================================================================
+# DATA COMPRESSION AND RESTORATION FUNCTIONS  
+# =====================================================================================
+
+
 def compress(self, features=True, ms2=True, chrom=False, ms2_max=5):
     """
     Perform compress_features, compress_ms2, and compress_chrom operations.
@@ -1251,6 +1293,11 @@ def compress_chrom(self):
     self.logger.info(f"Compressed chromatograms: cleared {non_null_count} chromatogram objects from features_df")
 
 
+# =====================================================================================
+# SAMPLE MANAGEMENT AND NAMING FUNCTIONS
+# =====================================================================================
+
+
 def name_replace(self, replace_dict):
     """
     Replace sample names in samples_df based on a dictionary mapping.
@@ -1447,6 +1494,11 @@ def set_source(self, filename):
         self.logger.warning(f"Failed to update file_source for {failed_count} samples")
 
 
+# =====================================================================================
+# DATA FILTERING AND SELECTION FUNCTIONS
+# =====================================================================================
+
+
 def features_select(
     self,
     mz=None,
@@ -2222,3 +2274,441 @@ def consensus_delete(self, consensus):
         None (modifies self.consensus_df and related DataFrames in place)
     """
     self.consensus_filter(consensus)
+
+
+# =====================================================================================
+# COLOR PALETTE AND VISUALIZATION FUNCTIONS
+# =====================================================================================
+
+
+def sample_color(self, by=None, palette="Turbo256"):
+    """
+    Set sample colors in the sample_color column of samples_df.
+    
+    When a new sample is added, this function resets all colors picking from the specified palette.
+    The default palette is Turbo256.
+
+    Parameters:
+        by (str or list, optional): Property to base colors on. Options:
+                                     - 'sample_uid': Use sample_uid values to assign colors
+                                     - 'sample_index': Use sample index (position) to assign colors  
+                                     - 'sample_type': Use sample_type values to assign colors
+                                     - 'sample_name': Use sample_name values to assign colors
+                                     - list of colors: Use provided list of hex color codes
+                                     - None: Use sequential colors from palette (default)
+        palette (str): Color palette to use. Options:
+                      - 'Turbo256': Turbo colormap (256 colors, perceptually uniform)
+                      - 'Viridis256': Viridis colormap (256 colors, perceptually uniform)
+                      - 'Plasma256': Plasma colormap (256 colors, perceptually uniform)
+                      - 'Inferno256': Inferno colormap (256 colors, perceptually uniform)
+                      - 'Magma256': Magma colormap (256 colors, perceptually uniform)
+                      - 'Cividis256': Cividis colormap (256 colors, colorblind-friendly)
+                      - 'Set1': Qualitative palette (9 distinct colors)
+                      - 'Set2': Qualitative palette (8 distinct colors)  
+                      - 'Set3': Qualitative palette (12 distinct colors)
+                      - 'Tab10': Tableau 10 palette (10 distinct colors)
+                      - 'Tab20': Tableau 20 palette (20 distinct colors)
+                      - 'Dark2': Dark qualitative palette (8 colors)
+                      - 'Paired': Paired qualitative palette (12 colors)
+                      - 'Spectral': Spectral diverging colormap
+                      - 'Rainbow': Rainbow colormap
+                      - 'Coolwarm': Cool-warm diverging colormap
+                      - 'Seismic': Seismic diverging colormap
+                      - Any other colormap name supported by the cmap library
+                      
+                      For a complete catalog of available colormaps, see:
+                      https://cmap-docs.readthedocs.io/en/latest/catalog/
+
+    Returns:
+        None (modifies self.samples_df in place)
+
+    Example:
+        # Set colors based on sample type
+        study.sample_color(by='sample_type', palette='Set1')
+        
+        # Set colors using a custom color list
+        study.sample_color(by=['#FF0000', '#00FF00', '#0000FF'])
+        
+        # Reset to default Turbo256 sequential colors
+        study.sample_color()
+    """
+    if self.samples_df is None or len(self.samples_df) == 0:
+        self.logger.warning("No samples found in study.")
+        return
+
+    sample_count = len(self.samples_df)
+    
+    # Handle custom color list
+    if isinstance(by, list):
+        if len(by) < sample_count:
+            self.logger.warning(f"Provided color list has {len(by)} colors but {sample_count} samples. Repeating colors.")
+            # Cycle through the provided colors if there aren't enough
+            colors = []
+            for i in range(sample_count):
+                colors.append(by[i % len(by)])
+        else:
+            colors = by[:sample_count]
+    else:
+        # Use the new approach: sample colors evenly from the whole colormap
+        if by is None:
+            # Sequential colors evenly sampled from the colormap
+            try:
+                colors = _sample_colors_from_colormap(palette, sample_count)
+            except ValueError as e:
+                self.logger.error(f"Error sampling colors from colormap: {e}")
+                return
+                
+        elif by == 'sample_uid':
+            # Use sample_uid to determine position in evenly sampled colormap
+            sample_uids = self.samples_df['sample_uid'].to_list()
+            try:
+                # Sample colors evenly for the number of samples
+                palette_colors = _sample_colors_from_colormap(palette, sample_count)
+                colors = []
+                for uid in sample_uids:
+                    # Use modulo to cycle through evenly sampled colors
+                    color_index = uid % len(palette_colors)
+                    colors.append(palette_colors[color_index])
+            except ValueError as e:
+                self.logger.error(f"Error sampling colors from colormap: {e}")
+                return
+                
+        elif by == 'sample_index':
+            # Use sample index (position in DataFrame) with evenly sampled colors
+            try:
+                colors = _sample_colors_from_colormap(palette, sample_count)
+            except ValueError as e:
+                self.logger.error(f"Error sampling colors from colormap: {e}")
+                return
+                
+        elif by == 'sample_type':
+            # Use sample_type to assign colors - same type gets same color
+            # Sample colors evenly across colormap for unique types
+            sample_types = self.samples_df['sample_type'].to_list()
+            unique_types = list(set([t for t in sample_types if t is not None]))
+            
+            try:
+                # Sample colors evenly for unique types
+                type_colors = _sample_colors_from_colormap(palette, len(unique_types))
+                type_to_color = {}
+                
+                for i, sample_type in enumerate(unique_types):
+                    type_to_color[sample_type] = type_colors[i]
+                
+                colors = []
+                for sample_type in sample_types:
+                    if sample_type is None:
+                        # Default to first color for None
+                        colors.append(type_colors[0] if type_colors else "#000000")
+                    else:
+                        colors.append(type_to_color[sample_type])
+            except ValueError as e:
+                self.logger.error(f"Error sampling colors from colormap: {e}")
+                return
+                    
+        elif by == 'sample_name':
+            # Use sample_name to assign colors - same name gets same color (unlikely but possible)
+            # Sample colors evenly across colormap for unique names
+            sample_names = self.samples_df['sample_name'].to_list()
+            unique_names = list(set([n for n in sample_names if n is not None]))
+            
+            try:
+                # Sample colors evenly for unique names
+                name_colors = _sample_colors_from_colormap(palette, len(unique_names))
+                name_to_color = {}
+                
+                for i, sample_name in enumerate(unique_names):
+                    name_to_color[sample_name] = name_colors[i]
+                
+                colors = []
+                for sample_name in sample_names:
+                    if sample_name is None:
+                        # Default to first color for None
+                        colors.append(name_colors[0] if name_colors else "#000000")
+                    else:
+                        colors.append(name_to_color[sample_name])
+            except ValueError as e:
+                self.logger.error(f"Error sampling colors from colormap: {e}")
+                return
+        else:
+            self.logger.error(f"Invalid by value: {by}. Must be 'sample_uid', 'sample_index', 'sample_type', 'sample_name', a list of colors, or None.")
+            return
+
+    # Update the sample_color column
+    self.samples_df = self.samples_df.with_columns(
+        pl.Series("sample_color", colors).alias("sample_color")
+    )
+    
+    if isinstance(by, list):
+        self.logger.debug(f"Set sample colors using provided color list ({len(by)} colors)")
+    elif by is None:
+        self.logger.debug(f"Set sequential sample colors using {palette} palette")
+    else:
+        self.logger.debug(f"Set sample colors based on {by} using {palette} palette")
+
+
+def sample_color_reset(self):
+    """
+    Reset sample colors to default coloring using the 'turbo' colormap.
+    
+    This function assigns colors by distributing samples evenly across the full
+    turbo colormap range, ensuring maximum color diversity and visual distinction
+    between samples.
+    
+    Returns:
+        None (modifies self.samples_df in place)
+    """
+    if self.samples_df is None or len(self.samples_df) == 0:
+        self.logger.warning("No samples found in study.")
+        return
+    
+    try:
+        from cmap import Colormap
+        
+        # Use turbo colormap
+        cm = Colormap('turbo')
+        
+        # Get sample count and assign colors evenly distributed across colormap
+        n_samples = len(self.samples_df)
+        colors = []
+        
+        # Distribute samples evenly across the full colormap range
+        for i in range(n_samples):
+            # Evenly distribute samples across colormap (avoiding endpoints to prevent white/black)
+            normalized_value = (i + 0.5) / n_samples  # +0.5 to center samples in their bins
+            # Optionally, map to a subset of colormap to avoid extreme colors
+            # Use 10% to 90% of colormap range for better color diversity
+            normalized_value = 0.1 + (normalized_value * 0.8)
+            
+            color_rgba = cm(normalized_value)
+            
+            # Convert RGBA to hex
+            if len(color_rgba) >= 3:
+                r, g, b = color_rgba[:3]
+                # Convert to 0-255 range if needed
+                if max(color_rgba[:3]) <= 1.0:
+                    r, g, b = int(r * 255), int(g * 255), int(b * 255)
+                hex_color = f"#{r:02x}{g:02x}{b:02x}"
+                colors.append(hex_color)
+        
+        # Update the sample_color column
+        self.samples_df = self.samples_df.with_columns(
+            pl.Series("sample_color", colors).alias("sample_color")
+        )
+        
+        self.logger.debug(f"Reset sample colors using turbo colormap with even distribution ({n_samples} samples)")
+        
+    except ImportError:
+        self.logger.error("cmap library is required for sample color reset. Install with: pip install cmap")
+    except Exception as e:
+        self.logger.error(f"Failed to reset sample colors: {e}")
+
+
+def _get_color_palette(palette_name):
+    """
+    Get color palette as a list of hex color codes using the cmap library.
+    
+    Parameters:
+        palette_name (str): Name of the palette
+        
+    Returns:
+        list: List of hex color codes
+        
+    Raises:
+        ValueError: If palette_name is not supported
+    """
+    try:
+        from cmap import Colormap
+    except ImportError:
+        raise ValueError("cmap library is required for color palettes. Install with: pip install cmap")
+    
+    # Map common palette names to cmap names
+    palette_mapping = {
+        # Scientific colormaps
+        "Turbo256": "turbo",
+        "Viridis256": "viridis", 
+        "Plasma256": "plasma",
+        "Inferno256": "inferno",
+        "Magma256": "magma",
+        "Cividis256": "cividis",
+        
+        # Qualitative palettes
+        "Set1": "Set1",
+        "Set2": "Set2", 
+        "Set3": "Set3",
+        "Tab10": "tab10",
+        "Tab20": "tab20",
+        "Dark2": "Dark2",
+        "Paired": "Paired",
+        
+        # Additional useful palettes
+        "Spectral": "Spectral",
+        "Rainbow": "rainbow",
+        "Coolwarm": "coolwarm",
+        "Seismic": "seismic",
+    }
+    
+    # Get the cmap name
+    cmap_name = palette_mapping.get(palette_name, palette_name.lower())
+    
+    try:
+        # Create colormap
+        cm = Colormap(cmap_name)
+        
+        # Determine number of colors to generate
+        if "256" in palette_name:
+            n_colors = 256
+        elif palette_name in ["Set1"]:
+            n_colors = 9
+        elif palette_name in ["Set2", "Dark2"]:
+            n_colors = 8
+        elif palette_name in ["Set3", "Paired"]:
+            n_colors = 12
+        elif palette_name in ["Tab10"]:
+            n_colors = 10
+        elif palette_name in ["Tab20"]:
+            n_colors = 20
+        else:
+            n_colors = 256  # Default for continuous colormaps
+        
+        # Generate colors
+        if n_colors <= 20:
+            # For discrete palettes, use evenly spaced indices
+            indices = [i / (n_colors - 1) for i in range(n_colors)]
+        else:
+            # For continuous palettes, use full range
+            indices = [i / (n_colors - 1) for i in range(n_colors)]
+        
+        # Get colors as RGBA and convert to hex
+        colors = cm(indices)
+        hex_colors = []
+        
+        for color in colors:
+            if len(color) >= 3:  # RGBA or RGB
+                r, g, b = color[:3]
+                # Convert to 0-255 range if needed
+                if max(color[:3]) <= 1.0:
+                    r, g, b = int(r * 255), int(g * 255), int(b * 255)
+                hex_color = f"#{r:02x}{g:02x}{b:02x}"
+                hex_colors.append(hex_color)
+        
+        return hex_colors
+        
+    except Exception as e:
+        raise ValueError(f"Failed to create colormap '{cmap_name}': {e}. "
+                        f"Available palettes: {list(palette_mapping.keys())}")
+
+
+def _sample_colors_from_colormap(palette_name, n_colors):
+    """
+    Sample colors evenly from the whole colormap range, similar to sample_color_reset.
+    
+    Parameters:
+        palette_name (str): Name of the palette/colormap
+        n_colors (int): Number of colors to sample
+        
+    Returns:
+        list: List of hex color codes sampled evenly from the colormap
+        
+    Raises:
+        ValueError: If palette_name is not supported
+    """
+    try:
+        from cmap import Colormap
+    except ImportError:
+        raise ValueError("cmap library is required for color palettes. Install with: pip install cmap")
+    
+    # Map common palette names to cmap names (same as _get_color_palette)
+    palette_mapping = {
+        # Scientific colormaps
+        "Turbo256": "turbo",
+        "Viridis256": "viridis", 
+        "Plasma256": "plasma",
+        "Inferno256": "inferno",
+        "Magma256": "magma",
+        "Cividis256": "cividis",
+        
+        # Qualitative palettes
+        "Set1": "Set1",
+        "Set2": "Set2", 
+        "Set3": "Set3",
+        "Tab10": "tab10",
+        "Tab20": "tab20",
+        "Dark2": "Dark2",
+        "Paired": "Paired",
+        
+        # Additional useful palettes
+        "Spectral": "Spectral",
+        "Rainbow": "rainbow",
+        "Coolwarm": "coolwarm",
+        "Seismic": "seismic",
+    }
+    
+    # Get the cmap name
+    cmap_name = palette_mapping.get(palette_name, palette_name.lower())
+    
+    try:
+        # Create colormap
+        cm = Colormap(cmap_name)
+        
+        colors = []
+        
+        # Distribute samples evenly across the full colormap range (same approach as sample_color_reset)
+        for i in range(n_colors):
+            # Evenly distribute samples across colormap (avoiding endpoints to prevent white/black)
+            normalized_value = (i + 0.5) / n_colors  # +0.5 to center samples in their bins
+            # Map to a subset of colormap to avoid extreme colors (use 10% to 90% range)
+            normalized_value = 0.1 + (normalized_value * 0.8)
+            
+            color_rgba = cm(normalized_value)
+            
+            # Convert RGBA to hex
+            if len(color_rgba) >= 3:
+                r, g, b = color_rgba[:3]
+                # Convert to 0-255 range if needed
+                if max(color_rgba[:3]) <= 1.0:
+                    r, g, b = int(r * 255), int(g * 255), int(b * 255)
+                hex_color = f"#{r:02x}{g:02x}{b:02x}"
+                colors.append(hex_color)
+        
+        return colors
+        
+    except Exception as e:
+        raise ValueError(f"Failed to create colormap '{cmap_name}': {e}. "
+                        f"Available palettes: {list(palette_mapping.keys())}")
+
+
+def _matplotlib_to_hex(color_dict):
+    """Convert matplotlib color dictionary to list of hex colors."""
+    return list(color_dict.values())
+
+
+# =====================================================================================
+# SCHEMA AND DATA STRUCTURE FUNCTIONS  
+# =====================================================================================
+
+
+def _ensure_features_df_schema_order(self):
+    """
+    Ensure features_df columns are ordered according to study5_schema.json.
+    
+    This method should be called after operations that might scramble the column order.
+    """
+    if self.features_df is None or self.features_df.is_empty():
+        return
+    
+    try:
+        import os
+        import json
+        from masster.study.h5 import _reorder_columns_by_schema
+        
+        # Load schema
+        schema_path = os.path.join(os.path.dirname(__file__), "study5_schema.json")
+        with open(schema_path, 'r') as f:
+            schema = json.load(f)
+        
+        # Reorder columns to match schema
+        self.features_df = _reorder_columns_by_schema(self.features_df, schema, 'features_df')
+        
+    except Exception as e:
+        self.logger.warning(f"Failed to reorder features_df columns: {e}")