masster 0.4.22__py3-none-any.whl → 0.5.1__py3-none-any.whl

masster/study/id.py

@@ -15,6 +15,7 @@ def lib_load(
     lib_source,
     polarity: str | None = None,
     adducts: list | None = None,
+    iso: str | None = None,
 ):
     """Load a compound library into the study.
 
@@ -23,6 +24,7 @@ def lib_load(
         lib_source: either a CSV file path (str) or a Lib instance
         polarity: ionization polarity ("positive" or "negative") - used when lib_source is a CSV path
         adducts: specific adducts to generate - used when lib_source is a CSV path
+        iso: isotope generation mode ("13C" to generate 13C isotopes, None for no isotopes)
 
     Side effects:
         sets study.lib_df to a Polars DataFrame and stores the lib object on
@@ -97,6 +99,56 @@ def lib_load(
     # Store pointer and DataFrame on study
     study._lib = lib_obj
 
+    # Add source_id column with filename (without path) if loading from CSV
+    if isinstance(lib_source, str):
+        import os
+        filename_only = os.path.basename(lib_source)
+        filtered_lf = filtered_lf.with_columns(pl.lit(filename_only).alias("source_id"))
+
+    # Ensure required columns exist and set correct values
+    required_columns = {
+        "quant_group": pl.Int64,
+        "iso": pl.Int64
+    }
+    
+    for col_name, col_dtype in required_columns.items():
+        if col_name == "quant_group":
+            # Set quant_group using cmpd_uid (same for isotopomers of same compound)
+            if "cmpd_uid" in filtered_lf.columns:
+                filtered_lf = filtered_lf.with_columns(pl.col("cmpd_uid").cast(col_dtype).alias("quant_group"))
+            else:
+                # Fallback to lib_uid if cmpd_uid doesn't exist
+                filtered_lf = filtered_lf.with_columns(pl.col("lib_uid").cast(col_dtype).alias("quant_group"))
+        elif col_name == "iso":
+            if col_name not in filtered_lf.columns:
+                # Default to zero for iso
+                filtered_lf = filtered_lf.with_columns(pl.lit(0).cast(col_dtype).alias(col_name))
+    
+    # Generate 13C isotopes if requested
+    original_count = len(filtered_lf)
+    if iso == '13C':
+        filtered_lf = _generate_13c_isotopes(filtered_lf)
+        # Update the log message to show the correct count after isotope generation
+        if isinstance(lib_source, str):
+            import os
+            filename_only = os.path.basename(lib_source)
+            print(f"Generated 13C isotopes: {len(filtered_lf)} total entries ({original_count} original + {len(filtered_lf) - original_count} isotopes) from {filename_only}")
+
+    # Reorder columns to place quant_group after rt and iso after formula
+    column_order = []
+    columns_list = list(filtered_lf.columns)
+    
+    for col in columns_list:
+        if col not in column_order:  # Only add if not already added
+            column_order.append(col)
+            if col == "rt" and "quant_group" in columns_list and "quant_group" not in column_order:
+                column_order.append("quant_group")
+            elif col == "formula" and "iso" in columns_list and "iso" not in column_order:
+                column_order.append("iso")
+    
+    # Apply the column ordering
+    filtered_lf = filtered_lf.select(column_order)
+
     # Add to existing lib_df instead of replacing
     if (
         hasattr(study, "lib_df")
@@ -124,10 +176,10 @@ def lib_load(
                 study.lib_df = pl.DataFrame()
 
     # Store this operation in history
-    if hasattr(study, "store_history"):
-        study.store_history(
+    if hasattr(study, "update_history"):
+        study.update_history(
             ["lib_load"],
-            {"lib_source": str(lib_source), "polarity": polarity, "adducts": adducts},
+            {"lib_source": str(lib_source), "polarity": polarity, "adducts": adducts, "iso": iso},
         )
 
 
@@ -349,6 +401,7 @@ def _update_identification_results(study, results, logger):
                 "rt_delta": match["rt_delta"],
                 "matcher": match["matcher"],
                 "score": match["score"],
+                "iso": 0,  # Default to zero
             })
     
     # Convert to DataFrame and append to existing results
@@ -356,6 +409,13 @@ def _update_identification_results(study, results, logger):
     
     if not new_results_df.is_empty():
         if hasattr(study, "id_df") and study.id_df is not None and not study.id_df.is_empty():
+            # Check if existing id_df has the iso column
+            if "iso" not in study.id_df.columns:
+                # Add iso column to existing id_df with default value 0
+                study.id_df = study.id_df.with_columns(pl.lit(0).alias("iso"))
+                if logger:
+                    logger.debug("Added 'iso' column to existing id_df for schema compatibility")
+            
             study.id_df = pl.concat([study.id_df, new_results_df])
         else:
             study.id_df = new_results_df
@@ -385,7 +445,7 @@ def _store_identification_history(study, effective_mz_tol, effective_rt_tol, tar
             history_params["params"] = params.to_dict()
         if kwargs:
             history_params["kwargs"] = kwargs
-        study.store_history(["identify"], history_params)
+        study.update_history(["identify"], history_params)
 
 
 def _validate_identify_inputs(study, logger=None):
@@ -1043,8 +1103,10 @@ def lib_reset(study):
     - study.id_df (identification results DataFrame)
     - study.lib_df (library DataFrame)
     - study._lib (library object reference)
+    - Consensus features created by lib_to_consensus() (number_samples = -1 or 0)
     - 'identify' from study.history
     - 'lib_load' from study.history (if exists)
+    - 'lib_to_consensus' from study.history (if exists)
     - Resets id_top_* columns in consensus_df to null
 
     Args:
@@ -1053,6 +1115,36 @@ def lib_reset(study):
     # Get logger from study if available
     logger = getattr(study, "logger", None)
 
+    # Remove consensus features created by lib_to_consensus()
+    # These are identified by number_samples = -1 or 0
+    if hasattr(study, "consensus_df") and not study.consensus_df.is_empty():
+        if logger:
+            logger.debug("Checking for consensus features created by lib_to_consensus()")
+        
+        try:
+            # Filter for features with number_samples = -1 or 0
+            # Since consensus_select doesn't support list of discrete values, use direct filtering
+            lib_consensus_features = study.consensus_df.filter(
+                (pl.col("number_samples") == -1) | (pl.col("number_samples") == 0)
+            )
+            
+            if lib_consensus_features is not None and not lib_consensus_features.is_empty():
+                num_lib_features = len(lib_consensus_features)
+                if logger:
+                    logger.info(f"Removing {num_lib_features} consensus features created by lib_to_consensus()")
+                
+                # Use consensus_delete to remove these features and all dependent data
+                study.consensus_delete(lib_consensus_features)
+                
+                if logger:
+                    logger.debug("Successfully removed library-derived consensus features")
+            else:
+                if logger:
+                    logger.debug("No library-derived consensus features found to remove")
+        except Exception as e:
+            if logger:
+                logger.warning(f"Error removing library-derived consensus features: {e}")
+
     # Remove id_df
     if hasattr(study, "id_df"):
         if logger:
@@ -1099,6 +1191,11 @@ def lib_reset(study):
             if logger:
                 logger.debug("Removing 'lib_load' from history")
             del study.history["lib_load"]
+            
+        if "lib_to_consensus" in study.history:
+            if logger:
+                logger.debug("Removing 'lib_to_consensus' from history")
+            del study.history["lib_to_consensus"]
 
     if logger:
         logger.info("Library and identification data reset completed")
@@ -1438,3 +1535,447 @@ def _format_adduct_name(components: list[dict]) -> str:
         )
 
     return f"[M{formula}]{charge_str}"
+
+
+def _generate_13c_isotopes(lib_df):
+    """
+    Generate 13C isotope variants for library entries.
+    
+    For each compound with n carbon atoms, creates n+1 entries:
+    - iso=0: original compound (no 13C)
+    - iso=1: one 13C isotope (+1.00335 Da)
+    - iso=2: two 13C isotopes (+2.00670 Da)
+    - ...
+    - iso=n: n 13C isotopes (+n*1.00335 Da)
+    
+    All isotopomers share the same quant_group.
+    
+    Args:
+        lib_df: Polars DataFrame with library entries
+        
+    Returns:
+        Polars DataFrame with additional 13C isotope entries
+    """
+    if lib_df.is_empty():
+        return lib_df
+    
+    # First, ensure all original entries have iso=0
+    original_df = lib_df.with_columns(pl.lit(0).alias("iso"))
+    
+    isotope_entries = []
+    next_lib_uid = lib_df["lib_uid"].max() + 1 if len(lib_df) > 0 else 1
+    
+    # Mass difference for one 13C isotope
+    c13_mass_shift = 1.00335  # Mass difference between 13C and 12C
+    
+    for row in original_df.iter_rows(named=True):
+        formula = row.get("formula", "")
+        if not formula:
+            continue
+            
+        # Count carbon atoms in the formula
+        carbon_count = _count_carbon_atoms(formula)
+        if carbon_count == 0:
+            continue
+            
+        # Get the original quant_group to keep it consistent across isotopes
+        # All isotopomers of the same compound should have the same quant_group
+        quant_group = row.get("quant_group", row.get("cmpd_uid", row.get("lib_uid", 1)))
+        
+        # Generate isotope variants (1 to n 13C atoms)
+        for iso_num in range(1, carbon_count + 1):
+            # Calculate mass shift for this number of 13C isotopes
+            mass_shift = iso_num * c13_mass_shift
+            
+            # Create new entry
+            isotope_entry = dict(row)  # Copy all fields
+            isotope_entry["lib_uid"] = next_lib_uid
+            isotope_entry["iso"] = iso_num
+            isotope_entry["m"] = row["m"] + mass_shift
+            isotope_entry["mz"] = (row["m"] + mass_shift) / abs(row["z"]) if row["z"] != 0 else row["m"] + mass_shift
+            isotope_entry["quant_group"] = quant_group  # Keep same quant_group
+            
+            isotope_entries.append(isotope_entry)
+            next_lib_uid += 1
+    
+    # Combine original entries (now with iso=0) with isotope entries
+    if isotope_entries:
+        isotope_df = pl.DataFrame(isotope_entries)
+        # Ensure schema compatibility by aligning data types
+        try:
+            return pl.concat([original_df, isotope_df])
+        except Exception as e:
+            # If concat fails due to schema mismatch, convert to compatible types
+            # Get common schema
+            original_schema = original_df.schema
+            isotope_schema = isotope_df.schema
+            
+            # Cast isotope_df columns to match original_df schema where possible
+            cast_exprs = []
+            for col_name in isotope_df.columns:
+                if col_name in original_schema:
+                    target_dtype = original_schema[col_name]
+                    cast_exprs.append(pl.col(col_name).cast(target_dtype, strict=False))
+                else:
+                    cast_exprs.append(pl.col(col_name))
+            
+            isotope_df_cast = isotope_df.select(cast_exprs)
+            return pl.concat([original_df, isotope_df_cast])
+    else:
+        return original_df
+
+
+def _count_carbon_atoms(formula: str) -> int:
+    """
+    Count the number of carbon atoms in a molecular formula.
+    
+    Args:
+        formula: Molecular formula string like "C6H12O6"
+        
+    Returns:
+        Number of carbon atoms
+    """
+    import re
+    
+    if not formula or not isinstance(formula, str):
+        return 0
+    
+    # Look for carbon followed by optional number
+    # C followed by digits, or just C (which means 1)
+    carbon_matches = re.findall(r'C(\d*)', formula)
+    
+    total_carbons = 0
+    for match in carbon_matches:
+        if match == '':
+            # Just 'C' without number means 1 carbon
+            total_carbons += 1
+        else:
+            # 'C' followed by number
+            total_carbons += int(match)
+    
+    return total_carbons
+
+
+def lib_to_consensus(study, chrom_fhwm: float = 5.0, mz_tol: float = 0.01, rt_tol: float = 2.0):
+    """Create consensus features from library entries instead of features_df.
+    
+    This method takes all rows from lib_df and creates corresponding entries in
+    consensus_df with the same columns as merge(). Instead of relying on 
+    features_df, it populates consensus features directly from library data.
+    
+    Before creating new features, it checks for pre-existing consensus features:
+    - If rt in lib_df is null: picks consensus feature with matching mz and largest inty_mean
+    - If rt is not null: picks consensus feature with matching mz and rt within tolerance
+    - If a match is found, skips to the next library entry
+    
+    Args:
+        study: Study instance with lib_df populated
+        chrom_fhwm: Chromatographic full width at half maximum in seconds 
+                   to infer rt_start_mean and rt_end_mean (default: 5.0)
+        mz_tol: m/z tolerance for matching existing consensus features (default: 0.01)
+        rt_tol: RT tolerance for matching existing consensus features (default: 2.0)
+    
+    Side effects:
+        Adds rows to study.consensus_df and study.consensus_mapping_df
+        Calls study.find_ms2() at the end
+    """
+    # Get logger from study if available
+    logger = getattr(study, "logger", None)
+    
+    # Validate inputs
+    if getattr(study, "lib_df", None) is None or study.lib_df.is_empty():
+        if logger:
+            logger.error("Library (study.lib_df) is empty; call lib_load() first")
+        raise ValueError("Library (study.lib_df) is empty; call lib_load() first")
+    
+    if logger:
+        logger.info(f"Creating consensus features from {len(study.lib_df)} library entries")
+    
+    # Initialize consensus DataFrames if they don't exist
+    if not hasattr(study, "consensus_df") or study.consensus_df is None:
+        study.consensus_df = pl.DataFrame()
+    if not hasattr(study, "consensus_mapping_df") or study.consensus_mapping_df is None:
+        study.consensus_mapping_df = pl.DataFrame()
+    
+    # Get cached adducts for consistent adduct handling
+    cached_adducts_df = None
+    cached_valid_adducts = None
+    try:
+        cached_adducts_df = _get_adducts(study)
+        if not cached_adducts_df.is_empty():
+            cached_valid_adducts = set(cached_adducts_df["name"].to_list())
+        else:
+            cached_valid_adducts = set()
+    except Exception as e:
+        if logger:
+            logger.warning(f"Could not retrieve study adducts: {e}")
+        cached_valid_adducts = set()
+    
+    # Always allow '?' adducts
+    cached_valid_adducts.add("?")
+    
+    # Get starting consensus_uid counter
+    if not study.consensus_df.is_empty():
+        max_existing_uid = study.consensus_df["consensus_uid"].max()
+        consensus_uid_counter = int(max_existing_uid) + 1 if max_existing_uid is not None else 0
+    else:
+        consensus_uid_counter = 0
+    
+    # Track [M+H] iso=0 and [M-H] iso=0 entries for adduct grouping
+    base_adduct_groups = {}  # key: (mz, adduct_base), value: adduct_group
+    
+    # Process each library entry
+    consensus_metadata = []
+    consensus_mapping_list = []
+    matched_count = 0
+    skipped_count = 0
+    
+    for lib_row in study.lib_df.iter_rows(named=True):
+        # Extract basic library data
+        lib_uid = lib_row.get("lib_uid")
+        mz = lib_row.get("mz")
+        rt = lib_row.get("rt")
+        iso = lib_row.get("iso", 0)
+        adduct = lib_row.get("adduct")
+        z = lib_row.get("z", 1)  # charge
+        
+        # Skip entries without essential data
+        if mz is None:
+            if logger:
+                logger.warning(f"Skipping library entry {lib_uid} - no m/z value")
+            continue
+        
+        # Check for pre-existing consensus features
+        existing_match = None
+        if not study.consensus_df.is_empty():
+            # Filter by m/z tolerance first
+            mz_matches = study.consensus_df.filter(
+                (pl.col("mz") >= mz - mz_tol) & (pl.col("mz") <= mz + mz_tol)
+            )
+            
+            if not mz_matches.is_empty():
+                if rt is None:
+                    # If rt is null, pick the consensus feature with largest inty_mean
+                    existing_match = mz_matches.sort("inty_mean", descending=True).head(1)
+                else:
+                    # If rt is not null, filter by RT tolerance and pick largest inty_mean
+                    rt_tolerance = chrom_fhwm  # Use chrom_fhwm as RT tolerance range
+                    rt_matches = mz_matches.filter(
+                        (pl.col("rt") >= rt - rt_tolerance) & (pl.col("rt") <= rt + rt_tolerance)
+                    )
+                    if not rt_matches.is_empty():
+                        existing_match = rt_matches.sort("inty_mean", descending=True).head(1)
+        
+        if existing_match is not None and len(existing_match) > 0:
+            # Found a matching consensus feature, skip this library entry
+            matched_count += 1
+            if logger and matched_count <= 5:  # Log first few matches
+                match_uid = existing_match["consensus_uid"][0]
+                match_mz = existing_match["mz"][0]
+                match_rt = existing_match["rt"][0]
+                logger.debug(f"Library entry {lib_uid} (mz={mz:.4f}, rt={rt}) matched existing consensus {match_uid} (mz={match_mz:.4f}, rt={match_rt})")
+            continue
+        
+        # No match found, create new consensus feature
+        # Handle missing RT - use 0 as placeholder
+        if rt is None:
+            rt = 0.0
+            if logger and skipped_count < 5:  # Log first few
+                logger.debug(f"Library entry {lib_uid} has no RT, using 0.0")
+        
+        # Calculate RT range based on chrom_fhwm
+        half_width = chrom_fhwm / 2.0
+        rt_start = rt - half_width
+        rt_end = rt + half_width
+        
+        # Get adduct information
+        adduct_top = adduct if adduct else "?"
+        adduct_charge_top = None
+        adduct_mass_shift_top = None
+        adduct_mass_neutral_top = None
+        
+        # Parse adduct to get charge and mass shift
+        if adduct_top and cached_adducts_df is not None and not cached_adducts_df.is_empty():
+            # Look for exact match in study adducts
+            matching_adduct = cached_adducts_df.filter(pl.col("name") == adduct_top)
+            if not matching_adduct.is_empty():
+                adduct_row = matching_adduct.row(0, named=True)
+                adduct_charge_top = adduct_row["charge"]
+                adduct_mass_shift_top = adduct_row["mass_shift"]
+        
+        # Fallback to default values if not found
+        if adduct_charge_top is None:
+            adduct_charge_top = int(z) if z else 1
+            # Default based on study polarity
+            study_polarity = getattr(study, "polarity", "positive")
+            if study_polarity in ["negative", "neg"]:
+                if adduct_charge_top > 0:
+                    adduct_charge_top = -adduct_charge_top
+                adduct_mass_shift_top = -1.007825
+                if adduct_top == "?":
+                    adduct_top = "[M-?]1-"
+            else:
+                if adduct_charge_top < 0:
+                    adduct_charge_top = -adduct_charge_top
+                adduct_mass_shift_top = 1.007825
+                if adduct_top == "?":
+                    adduct_top = "[M+?]1+"
+        
+        # Calculate neutral mass
+        if adduct_charge_top and adduct_mass_shift_top is not None:
+            adduct_mass_neutral_top = mz * abs(adduct_charge_top) - adduct_mass_shift_top
+        
+        # Determine adduct group for isotopologues and related adducts
+        adduct_group = consensus_uid_counter  # Default: each entry gets its own group
+        adduct_of = 0  # Default: this is the base adduct
+        
+        # Track base adducts ([M+H] iso=0 or [M-H] iso=0) for grouping
+        base_adduct_key = None
+        if iso == 0 and adduct_top in ["[M+H]+", "[M+H]1+", "[M-H]-", "[M-H]1-"]:
+            # This is a base adduct with iso=0
+            base_adduct_key = (round(mz, 4), adduct_top)
+            base_adduct_groups[base_adduct_key] = consensus_uid_counter
+        elif iso > 0:
+            # This is an isotopologue, try to find the base adduct
+            # Calculate the base m/z (subtract isotope mass shifts)
+            c13_mass_shift = 1.00335
+            base_mz = mz - (iso * c13_mass_shift / abs(adduct_charge_top))
+            
+            # Look for matching base adduct
+            for (stored_mz, stored_adduct), stored_group in base_adduct_groups.items():
+                if abs(stored_mz - base_mz) < mz_tol and stored_adduct == adduct_top:
+                    adduct_group = stored_group
+                    adduct_of = stored_group
+                    break
+        
+        # Create adduct values list with proper structure (format: structured data with fields: adduct, count, percentage, mass)
+        adduct_values = [{"adduct": adduct_top, "count": 1, "percentage": 100.0, "mass": 0.0}]
+        
+        # Generate unique consensus_id string
+        import uuid
+        consensus_id_str = str(uuid.uuid4()).replace('-', '')[:16]
+        
+        # Build consensus metadata with requested modifications for new entries
+        metadata = {
+            "consensus_uid": consensus_uid_counter,
+            "consensus_id": consensus_id_str,
+            "quality": 1.0,
+            "number_samples": 0.0,  # Set to 0.0 for library entries
+            "rt": float(rt),
+            "mz": float(mz),
+            "rt_min": float(rt),  # Set to rt as requested
+            "rt_max": float(rt),  # Set to rt as requested
+            "rt_mean": float(rt),  # Set to rt as requested
+            "rt_start_mean": float(rt_start),
+            "rt_end_mean": float(rt_end),
+            "rt_delta_mean": 0.0,  # Set to 0.0 as requested
+            "mz_min": float(mz),  # Set to mz as requested
+            "mz_max": float(mz),  # Set to mz as requested
+            "mz_mean": float(mz),  # Set to mz as requested
+            "mz_start_mean": float(mz),  # Set to mz as requested
+            "mz_end_mean": float(mz),  # Set to mz as requested
+            "inty_mean": -1.0,  # Set to -1.0 as requested
+            "bl": -1.0,
+            "chrom_coherence_mean": -1.0,  # Set to -1.0 as requested
+            "chrom_prominence_mean": -1.0,  # Set to -1.0 as requested
+            "chrom_prominence_scaled_mean": -1.0,  # Set to -1.0 as requested
+            "chrom_height_scaled_mean": -1.0,  # Set to -1.0 as requested
+            "iso": iso,  # Set to iso from lib_df as requested
+            "iso_mean": float(iso),  # Set to iso from lib_df as requested
+            "charge_mean": float(abs(z)) if z else 1.0,  # Set to z as requested
+            "number_ms2": 0,  # Will be updated by find_ms2
+            "adducts": adduct_values,
+            "adduct_charge_top": adduct_charge_top,
+            "adduct_group": adduct_group,  # Use calculated adduct group
+            "adduct_mass_neutral_top": round(adduct_mass_neutral_top, 6) if adduct_mass_neutral_top is not None else None,
+            "adduct_mass_shift_top": round(adduct_mass_shift_top, 6) if adduct_mass_shift_top is not None else None,
+            "adduct_of": adduct_of,  # Use calculated adduct_of
+            "adduct_top": adduct_top,
+            "id_top_name": None,  # Set to null as requested
+            "id_top_class": None,  # Set to null as requested
+            "id_top_adduct": None,  # Set to null as requested
+            "id_top_score": None,  # Set to null as requested
+        }
+        
+        consensus_metadata.append(metadata)
+        
+        # Create mapping entry (maps to library entry as "virtual" feature)
+        # Use lib_uid as the feature_uid and a virtual sample_uid of 0
+        # Match existing consensus_mapping_df column order: consensus_uid, feature_uid, sample_uid
+        consensus_mapping_list.append({
+            "consensus_uid": consensus_uid_counter,
+            "feature_uid": lib_uid,  # Use lib_uid as feature reference
+            "sample_uid": 0,  # Virtual sample for library entries
+        })
+        
+        consensus_uid_counter += 1
+    
+    # Log matching statistics
+    if logger:
+        total_processed = matched_count + len(consensus_metadata)
+        logger.info(f"Processed {total_processed} library entries: {matched_count} matched existing consensus features, {len(consensus_metadata)} created new features")
+    
+    # Convert to DataFrames with proper schema alignment
+    if consensus_metadata:
+        new_consensus_df = pl.DataFrame(consensus_metadata, strict=False)
+        
+        # Ensure schema compatibility with existing consensus_df
+        if not study.consensus_df.is_empty():
+            # Cast columns to match existing schema
+            existing_schema = study.consensus_df.schema
+            cast_exprs = []
+            for col_name in new_consensus_df.columns:
+                if col_name in existing_schema:
+                    target_dtype = existing_schema[col_name]
+                    if target_dtype == pl.Null:
+                        # For Null columns, use lit(None) to maintain Null type
+                        cast_exprs.append(pl.lit(None).alias(col_name))
+                    else:
+                        cast_exprs.append(pl.col(col_name).cast(target_dtype, strict=False))
+                else:
+                    cast_exprs.append(pl.col(col_name))
+            
+            new_consensus_df = new_consensus_df.select(cast_exprs)
+        
+        new_consensus_mapping_df = pl.DataFrame(consensus_mapping_list, strict=False)
+        
+        # Append to existing DataFrames
+        if not study.consensus_df.is_empty():
+            study.consensus_df = pl.concat([study.consensus_df, new_consensus_df])
+        else:
+            study.consensus_df = new_consensus_df
+            
+        if not study.consensus_mapping_df.is_empty():
+            study.consensus_mapping_df = pl.concat([study.consensus_mapping_df, new_consensus_mapping_df])
+        else:
+            study.consensus_mapping_df = new_consensus_mapping_df
+        
+        if logger:
+            logger.info(f"Added {len(consensus_metadata)} consensus features from library")
+    else:
+        if logger:
+            logger.warning("No valid consensus features created from library")
+        return
+    
+    # Store operation in history
+    if hasattr(study, "update_history"):
+        study.update_history(
+            ["lib_to_consensus"],
+            {"chrom_fhwm": chrom_fhwm, "lib_entries": len(study.lib_df)},
+        )
+    
+    # Perform find_ms2 at the end
+    try:
+        if hasattr(study, "find_ms2"):
+            if logger:
+                logger.info("Running find_ms2 to link MS2 spectra to library-derived consensus features")
+            study.find_ms2()
+        else:
+            if logger:
+                logger.warning("find_ms2 method not available on study object")
+    except Exception as e:
+        if logger:
+            logger.warning(f"find_ms2 failed: {e}")
+    
+    if logger:
+        logger.info(f"lib_to_consensus completed: {len(consensus_metadata)} features added")