masster 0.5.27__py3-none-any.whl → 0.6.1__py3-none-any.whl

masster/study/merge.py

@@ -441,9 +441,15 @@ def merge(study, **kwargs) -> None:
     cached_valid_adducts = None
     try:
         cached_adducts_df = study._get_adducts()
+        # Remove all adducts with wrong polarity
+        if study.polarity == "positive":
+            cached_adducts_df = cached_adducts_df.filter(pl.col("charge") >= 0)
+        else:
+            cached_adducts_df = cached_adducts_df.filter(pl.col("charge") <= 0)
         if not cached_adducts_df.is_empty():
             cached_valid_adducts = set(cached_adducts_df["name"].to_list())
         else:
+            study.logger.warning(f"No valid adducts found for polarity '{study.polarity}'")
             cached_valid_adducts = set()
     except Exception as e:
         study.logger.warning(f"Could not retrieve study adducts: {e}")
@@ -452,6 +458,13 @@ def merge(study, **kwargs) -> None:
     # Always allow '?' adducts
     cached_valid_adducts.add("?")
 
+    # Bypass for single sample case
+    if len(study.samples_df) == 1:
+        study.logger.info("Single sample detected - bypassing merge algorithm and using direct feature mapping")
+        _handle_single_sample_merge(study, cached_adducts_df, cached_valid_adducts)
+        # Skip all post-processing for single sample case
+        return
+
     # Route to algorithm implementation
     if params.method == "kd":
         consensus_map = _merge_kd(study, params)
@@ -1719,6 +1732,10 @@ def _calculate_consensus_statistics(
         mz_values: m/z values from chunk consensus features
         intensity_values: Intensity values from chunk consensus features
         quality_values: Quality values from chunk consensus features
+        number_features: Number of unique features contributing
+        number_samples: Number of unique samples contributing
+        cached_adducts_df: Cached DataFrame of valid adducts for the study
+        cached_valid_adducts: Cached set of valid adduct names for the study
 
     Returns:
         Dictionary with consensus feature metadata
@@ -3612,6 +3629,142 @@ def __merge_adduct_grouping(study, consensus_data, rt_tol, mz_tol):
     return adduct_group_list, adduct_of_list
 
 
+def _handle_single_sample_merge(study, cached_adducts_df=None, cached_valid_adducts=None):
+    """
+    Handle merge for the special case of a single sample.
+    Directly populate consensus_df from the sample's features_df without any filtering.
+    
+    Args:
+        study: Study object with single sample
+        cached_adducts_df: Pre-computed adducts DataFrame (optional)
+        cached_valid_adducts: Set of valid adduct names (optional)
+    """
+    import polars as pl
+    import uuid
+    
+    if len(study.samples_df) != 1:
+        raise ValueError("_handle_single_sample_merge should only be called with exactly one sample")
+    
+    # Get the single sample's features
+    sample_row = study.samples_df.row(0, named=True)
+    sample_uid = sample_row["sample_uid"]
+    
+    # Filter features for this sample  
+    sample_features = study.features_df.filter(pl.col("sample_uid") == sample_uid)
+    
+    if len(sample_features) == 0:
+        study.logger.warning("No features found for single sample")
+        study.consensus_df = pl.DataFrame()
+        study.consensus_mapping_df = pl.DataFrame()
+        return
+    
+    study.logger.info(f"Creating consensus from {len(sample_features)} features in single sample")
+    
+    # Create consensus features directly from sample features
+    consensus_list = []
+    mapping_list = []
+    
+    # Cache valid adducts
+    valid_adducts = cached_valid_adducts if cached_valid_adducts is not None else set()
+    valid_adducts.add("?")  # Always allow '?' adducts
+    
+    for i, feature_row in enumerate(sample_features.iter_rows(named=True)):
+        # Generate unique consensus ID
+        consensus_id_str = str(uuid.uuid4()).replace("-", "")[:16]
+        
+        # Handle adduct information
+        adduct = feature_row.get("adduct")
+        if adduct is None or adduct not in valid_adducts:
+            # Set default adduct based on study polarity
+            study_polarity = getattr(study, "polarity", "positive")
+            if study_polarity in ["negative", "neg"]:
+                adduct = "[M-?]1-"
+                adduct_charge = -1
+                adduct_mass_shift = -1.007825
+            else:
+                adduct = "[M+?]1+"
+                adduct_charge = 1
+                adduct_mass_shift = 1.007825
+        else:
+            # Try to get charge and mass shift from cached adducts
+            adduct_charge = 1
+            adduct_mass_shift = 1.007825
+            if cached_adducts_df is not None and not cached_adducts_df.is_empty():
+                matching_adduct = cached_adducts_df.filter(pl.col("name") == adduct)
+                if not matching_adduct.is_empty():
+                    adduct_row = matching_adduct.row(0, named=True)
+                    adduct_charge = adduct_row["charge"]
+                    adduct_mass_shift = adduct_row["mass_shift"]
+        
+        # Calculate neutral mass
+        mz = feature_row.get("mz", 0.0)
+        if adduct_charge and adduct_mass_shift is not None:
+            adduct_mass_neutral = mz * abs(adduct_charge) - adduct_mass_shift
+        else:
+            adduct_mass_neutral = None
+        
+        # Count MS2 scans
+        ms2_scans = feature_row.get("ms2_scans", [])
+        ms2_count = len(ms2_scans) if ms2_scans else 0
+        
+        # Create consensus feature metadata
+        consensus_feature = {
+            "consensus_uid": i,
+            "consensus_id": consensus_id_str,
+            "quality": feature_row.get("quality", 1.0),
+            "number_samples": 1,  # Always 1 for single sample
+            "rt": feature_row.get("rt", 0.0),
+            "mz": mz,
+            "rt_min": feature_row.get("rt", 0.0),
+            "rt_max": feature_row.get("rt", 0.0),
+            "rt_mean": feature_row.get("rt", 0.0),
+            "rt_start_mean": feature_row.get("rt_start", 0.0),
+            "rt_end_mean": feature_row.get("rt_end", 0.0),
+            "rt_delta_mean": feature_row.get("rt_delta", 0.0),
+            "mz_min": mz,
+            "mz_max": mz,
+            "mz_mean": mz,
+            "mz_start_mean": feature_row.get("mz_start", 0.0),
+            "mz_end_mean": feature_row.get("mz_end", 0.0),
+            "inty_mean": feature_row.get("inty", 0.0),
+            "bl": -1.0,
+            "chrom_coherence_mean": feature_row.get("chrom_coherence", 0.0),
+            "chrom_prominence_mean": feature_row.get("chrom_prominence", 0.0),
+            "chrom_prominence_scaled_mean": feature_row.get("chrom_prominence_scaled", 0.0),
+            "chrom_height_scaled_mean": feature_row.get("chrom_height_scaled", 0.0),
+            "iso": None,  # Will be filled by find_iso() function
+            "iso_mean": feature_row.get("iso", 0.0),
+            "charge_mean": feature_row.get("charge", 0.0),
+            "number_ms2": ms2_count,
+            "adducts": [[adduct, 1, 100.0]],  # Single adduct with 100% frequency
+            "adduct_top": adduct,
+            "adduct_charge_top": adduct_charge,
+            "adduct_mass_neutral_top": adduct_mass_neutral,
+            "adduct_mass_shift_top": adduct_mass_shift,
+            "id_top_name": None,
+            "id_top_class": None,
+            "id_top_adduct": None,
+            "id_top_score": None,
+            "id_source": None,
+        }
+        
+        consensus_list.append(consensus_feature)
+        
+        # Create mapping entry
+        mapping_entry = {
+            "consensus_uid": i,
+            "sample_uid": sample_uid,
+            "feature_uid": feature_row.get("feature_uid"),
+        }
+        mapping_list.append(mapping_entry)
+    
+    # Create DataFrames
+    study.consensus_df = pl.DataFrame(consensus_list, strict=False)
+    study.consensus_mapping_df = pl.DataFrame(mapping_list, strict=False)
+    
+    study.logger.info(f"Created {len(consensus_list)} consensus features from single sample")
+
+
 def _fast_correlation(x, y):
     """
     Fast correlation coefficient calculation for consensus matrix data.

masster/study/plot.py

@@ -2955,6 +2955,203 @@ def plot_tic(
     return p
 
 
+def plot_heatmap(
+    self,
+    filename=None,
+    width=800,
+    height=600,
+    cmap="viridis",
+    title="Consensus Matrix Heatmap",
+    quant="chrom_area",
+    samples=None,
+):
+    """
+    Plot a heatmap of the consensus matrix data.
+
+    Samples are ordered from left to right, features are ordered by m/z from top to bottom.
+    Values are log10 transformed for better visualization.
+
+    Parameters:
+        filename (str, optional): Path to save the plot
+        width (int): Plot width in pixels (default: 800)
+        height (int): Plot height in pixels (default: 600)
+        cmap (str): Colormap name (default: "viridis")
+        title (str): Plot title (default: "Consensus Matrix Heatmap")
+        quant (str): Quantification method column name (default: "chrom_area")
+        samples: Sample identifier(s) to include. Can be:
+                - None: include all samples (default)
+                - int: single sample_uid
+                - str: single sample_name
+                - list: multiple sample_uids or sample_names
+    """
+    from bokeh.plotting import figure
+    from bokeh.models import LinearColorMapper, ColorBar, BasicTicker
+    from bokeh.transform import transform
+    import numpy as np
+    import pandas as pd
+
+    # Get consensus matrix
+    matrix_df = self.get_consensus_matrix(quant=quant, samples=samples)
+
+    if matrix_df is None or matrix_df.is_empty():
+        self.logger.error("No consensus matrix available for heatmap.")
+        return
+
+    # Get m/z values for each consensus_uid to sort by
+    if self.consensus_df is None or self.consensus_df.is_empty():
+        self.logger.error("No consensus_df available for sorting features by m/z.")
+        return
+
+    # Join with consensus_df to get m/z values
+    matrix_with_mz = matrix_df.join(
+        self.consensus_df.select(["consensus_uid", "mz"]),
+        on="consensus_uid",
+        how="left",
+    )
+
+    # Sort by m/z (ascending - lowest m/z at top)
+    matrix_with_mz = matrix_with_mz.sort("mz")
+
+    # Remove the m/z column after sorting
+    matrix_sorted = matrix_with_mz.drop("mz")
+
+    # Extract consensus_uid and sample columns
+    consensus_uids = matrix_sorted["consensus_uid"].to_list()
+    sample_cols = [col for col in matrix_sorted.columns if col != "consensus_uid"]
+
+    # Convert to pandas for easier heatmap processing
+    matrix_pd = matrix_sorted.select(sample_cols).to_pandas()
+
+    # Apply log10 transformation (add 1 to avoid log(0))
+    matrix_log = np.log10(matrix_pd.values + 1)
+
+    # Prepare data for Bokeh heatmap
+    # Create a list of (sample, feature, value) tuples
+    heatmap_data = []
+    for i, feature_idx in enumerate(range(len(consensus_uids))):
+        for j, sample in enumerate(sample_cols):
+            value = matrix_log[feature_idx, j]
+            heatmap_data.append({
+                "sample": sample,
+                "feature": str(consensus_uids[feature_idx]),
+                "feature_idx": str(i),  # Use string index for y-axis position
+                "value": value,
+            })
+
+    # Convert to DataFrame for Bokeh ColumnDataSource
+    heatmap_df = pd.DataFrame(heatmap_data)
+
+    from bokeh.models import ColumnDataSource
+
+    source = ColumnDataSource(heatmap_df)
+
+    # Handle colormap using cmap.Colormap
+    try:
+        # Get colormap palette using cmap
+        if isinstance(cmap, str):
+            colormap = Colormap(cmap)
+            # Generate 256 colors and convert to hex
+            import matplotlib.colors as mcolors
+
+            colors = colormap(np.linspace(0, 1, 256))
+            palette = [mcolors.rgb2hex(color) for color in colors]
+        else:
+            colormap = cmap
+            # Try to use to_bokeh() method first
+            try:
+                palette = colormap.to_bokeh()
+                # Ensure we got a color palette, not another mapper
+                if not isinstance(palette, (list, tuple)):
+                    # Fall back to generating colors manually
+                    import matplotlib.colors as mcolors
+
+                    colors = colormap(np.linspace(0, 1, 256))
+                    palette = [mcolors.rgb2hex(color) for color in colors]
+            except AttributeError:
+                # Fall back to generating colors manually
+                import matplotlib.colors as mcolors
+
+                colors = colormap(np.linspace(0, 1, 256))
+                palette = [mcolors.rgb2hex(color) for color in colors]
+    except (AttributeError, ValueError, TypeError) as e:
+        # Fallback to viridis if cmap interpretation fails
+        self.logger.warning(f"Could not interpret colormap '{cmap}': {e}, falling back to viridis")
+        from bokeh.palettes import viridis
+
+        palette = viridis(256)
+
+    # Create color mapper
+    color_mapper = LinearColorMapper(
+        palette=palette,
+        low=heatmap_df["value"].min(),
+        high=heatmap_df["value"].max(),
+    )
+
+    # Create figure with categorical ranges for both axes
+    p = figure(
+        width=width,
+        height=height,
+        title=title,
+        x_range=sample_cols,
+        y_range=[str(i) for i in range(len(consensus_uids))],
+        toolbar_location="above",
+        tools="pan,wheel_zoom,box_zoom,reset,save,hover",
+        tooltips=[
+            ("Sample", "@sample"),
+            ("Feature UID", "@feature"),
+            ("log10(Value+1)", "@value{0.00}"),
+        ],
+    )
+
+    # Draw rectangles for heatmap
+    p.rect(
+        x="sample",
+        y="feature_idx",
+        width=1,
+        height=1,
+        source=source,
+        fill_color=transform("value", color_mapper),
+        line_color=None,
+    )
+
+    # Add colorbar
+    color_bar = ColorBar(
+        color_mapper=color_mapper,
+        width=8,
+        location=(0, 0),
+        title=f"log10({quant}+1)",
+        ticker=BasicTicker(desired_num_ticks=8),
+    )
+    p.add_layout(color_bar, "right")
+
+    # Style the plot
+    p.axis.axis_line_color = None
+    p.axis.major_tick_line_color = None
+    p.grid.grid_line_color = None
+    p.xaxis.major_label_orientation = 45
+    p.yaxis.axis_label = "Features (sorted by m/z)"
+    p.xaxis.axis_label = "Samples"
+
+    # Apply consistent save/display behavior
+    if filename is not None:
+        # Convert relative paths to absolute paths using study folder as base
+        import os
+
+        if not os.path.isabs(filename):
+            filename = os.path.join(self.folder, filename)
+
+        # Convert to absolute path for logging
+        abs_filename = os.path.abspath(filename)
+
+        # Use isolated file saving
+        _isolated_save_plot(p, filename, abs_filename, self.logger, "Heatmap Plot")
+    else:
+        # Show in notebook when no filename provided
+        _isolated_show_notebook(p)
+
+    return p
+
+
 def plot_pca(self, *args, **kwargs):
     """Deprecated: Use plot_samples_pca instead."""
     import warnings

masster/study/study.py

@@ -14,7 +14,7 @@ Main class:
         consensus_select/filter/delete
     - Retrieval: get_consensus, get_chrom, get_samples, get_*_stats, get_*_matrix
     - Plotting: plot_alignment, plot_samples_pca/umap/2d, plot_tic/bpc/eic, plot_chrom,
-        plot_rt_correction, plot_consensus_2d/stats
+        plot_rt_correction, plot_consensus_2d/stats, plot_heatmap
     - Export: export_mgf, export_mztab, export_xlsx, export_parquet
     - Identification: lib_load, identify, get_id, id_reset, lib_reset
     - Parameters: get/update parameters, update_history
@@ -96,6 +96,7 @@ from masster.study.plot import plot_bpc
 from masster.study.plot import plot_tic
 from masster.study.plot import plot_eic
 from masster.study.plot import plot_rt_correction
+from masster.study.plot import plot_heatmap
 from masster.study.processing import align
 from masster.study.merge import merge
 from masster.study.processing import integrate
@@ -429,6 +430,7 @@ class Study:
     plot_rt_correction = plot_rt_correction
     plot_tic = plot_tic
     plot_eic = plot_eic
+    plot_heatmap = plot_heatmap
 
     # === Analysis Operations ===
     analyze_umap = analyze_umap

masster/study/study5_schema.json

@@ -261,6 +261,21 @@
       },
       "ms1_spec": {
         "dtype": "pl.Object"
+      },
+      "id_top_name": {
+        "dtype": "pl.Utf8"
+      },
+      "id_top_class": {
+        "dtype": "pl.Utf8"
+      },
+      "id_top_adduct": {
+        "dtype": "pl.Utf8"
+      },
+      "id_top_score": {
+        "dtype": "pl.Float64"
+      },
+      "id_source": {
+        "dtype": "pl.Utf8"
       }
     }
   },

masster/wizard/wizard.py

@@ -200,12 +200,12 @@ class wizard_def:
         # Set default adducts based on polarity if not provided
         if not self.adducts:
             if self.polarity and self.polarity.lower() in ["positive", "pos"]:
-                self.adducts = ["H:+:0.8", "Na:+:0.1", "NH4:+:0.1"]
+                self.adducts = ["+H:1:0.8", "+Na:1:0.1", "+NH4:1:0.1"]
             elif self.polarity and self.polarity.lower() in ["negative", "neg"]:
-                self.adducts = ["H-1:-:1.0", "CH2O2:0:0.5"]
+                self.adducts = ["-H:-1:1.0", "+CH2O2:0:0.5"]
             else:
                 # Default to positive if polarity is None or unknown
-                self.adducts = ["H:+:0.8", "Na:+:0.1", "NH4:+:0.1"]
+                self.adducts = ["+H:1:0.8", "+Na:1:0.1", "+NH4:1:0.1"]
 
         # Validate num_cores
         max_cores = multiprocessing.cpu_count()
@@ -676,9 +676,7 @@ class Wizard:
             "        ",
             "        # Step 3: Create and configure study",
             '        print("\\nStep 3/7: Initializing study...")',
-            "        study = Study(folder=PARAMS['folder'])",
-            "        study.polarity = PARAMS['polarity']",
-            "        study.adducts = PARAMS['adducts']",
+            "        study = Study(folder=PARAMS['folder'], polarity=PARAMS['polarity'], adducts=PARAMS['adducts'])",
             "        ",
             "        # Step 4: Add sample5 files to study",
             '        print("\\nStep 4/7: Adding samples to study...")',
@@ -692,6 +690,12 @@ class Wizard:
             "            rt_tol=PARAMS['rt_tol']",
             "        )",
             "        ",
+            "        # Check that more than 1 file has been loaded",
+            "        if len(study.samples) <= 1:",
+            '            print("\\nWARNING: Study merging requires more than 1 sample file.")',
+            '            print(f"Only {len(study.samples)} sample(s) loaded. Terminating execution.")',
+            "            return False",
+            "        ",
             "        study.merge(",
             '            method="qt",',
             "            min_samples=PARAMS['min_samples_per_feature'],",
@@ -764,14 +768,9 @@ class Wizard:
             'app = marimo.App(width="medium")',
             "",
             "@app.cell",
-            "def __():",
-            "    import marimo as mo",
-            "    return (mo,)",
-            "",
-            "@app.cell",
             "def __(mo):",
             '    mo.md(r"""',
-            "    # MASSter Interactive Analysis",
+            "    ## MASSter Interactive Analysis",
             "    ",
             f"    **Source:** {source_info.get('number_of_files', 0)} files detected",
             f"    **Polarity:** {source_info.get('polarity', 'unknown')}",