masster 0.5.28__py3-none-any.whl → 0.6.2__py3-none-any.whl

masster/sample/plot.py

@@ -1115,6 +1115,7 @@ def plot_2d(
     filename=None,
     show_features=True,
     show_only_features_with_ms2=False,
+    show_only_features_with_id=False,
     show_isotopes=False,
     show_ms2=False,
     show_in_browser=False,
@@ -1134,6 +1135,7 @@ def plot_2d(
     rt_range=None,
     legend=None,
     colorby=None,
+    tooltip=None,
 ):
     """
     Plot a two-dimensional visualization of MS1 survey scan data with optional overlays
@@ -1151,6 +1153,9 @@ def plot_2d(
         show_only_features_with_ms2 (bool, default False):
             If True, only display features that have associated MS2 scans. When False,
             features without MS2 data are also shown.
+        show_only_features_with_id (bool, default False):
+            If True, only display features with non-null id_top_name (identified features).
+            When False, all features are shown. Only applies when colorby='id'.
         show_isotopes (bool, default False):
             Whether to overlay isotope information on top of the features.
         show_ms2 (bool, default False):
@@ -1186,6 +1191,9 @@ def plot_2d(
             Feature property to use for coloring. If None (default), uses current green/red scheme
             for features with/without MS2 data. If specified and contains categorical data, applies
             categorical coloring with legend support (similar to plot_2d_oracle).
+        tooltip (str, optional):
+            Controls the feature hover tooltip content. Use None or "ms1" (default) to display the
+            full feature details, or "id" to show only rt, m/z, feature_uid, inty, and any id_* columns.
     Behavior:
         - Checks for a loaded mzML file by verifying that self.file_obj is not None.
         - Converts internal MS1 data (a Polars DataFrame) to a Pandas DataFrame and filters out low-intensity
@@ -1376,8 +1384,104 @@ def plot_2d(
         # keep only iso==0, i.e. the main
         feats = feats[feats["iso"] == 0]
 
+        tooltip_mode = str(tooltip).lower() if tooltip is not None else "ms1"
+        if tooltip_mode not in {"ms1", "id"}:
+            tooltip_mode = "ms1"
+
+        id_columns = [col for col in feats.columns if isinstance(col, str) and col.startswith("id_")]
+
+        def build_feature_tooltips(*, include_iso=True, include_iso_of=False, include_colorby=None):
+            base_tooltips = [
+                ("rt", "@rt"),
+                ("m/z", "@mz{0.0000}"),
+                ("feature_uid", "@feature_uid"),
+                ("inty", "@inty"),
+            ]
+
+            if tooltip_mode == "id":
+                base_tooltips.extend((col, f"@{col}") for col in id_columns)
+                return base_tooltips
+
+            if include_iso:
+                base_tooltips.append(("iso", "@iso"))
+            if include_iso_of:
+                base_tooltips.append(("iso_of", "@iso_of"))
+            base_tooltips.append(("adduct", "@adduct"))
+            base_tooltips.append(("chrom_coherence", "@chrom_coherence"))
+            base_tooltips.append(("chrom_prominence_scaled", "@chrom_prominence_scaled"))
+
+            if include_colorby and tooltip_mode != "id":
+                base_tooltips.append((include_colorby, f"@{include_colorby}"))
+
+            return base_tooltips
+
+        handled_colorby = False
+        colorby_id_mode = False
+
+        if colorby == "id":
+            if "id_top_name" not in feats.columns:
+                self.logger.warning("colorby='id' requested but 'id_top_name' column is missing; using default colors")
+            else:
+                handled_colorby = True
+                colorby_id_mode = True
+                id_values = feats["id_top_name"]
+                annotated_mask = id_values.notna() & (id_values.astype(str).str.strip() != "")
+
+                annotated_features = feats[annotated_mask].copy()
+                unannotated_features = feats[~annotated_mask].copy()
+                
+                # Apply show_only_features_with_id filter if requested
+                if show_only_features_with_id:
+                    # Only keep annotated features, discard unannotated
+                    unannotated_features = unannotated_features.iloc[0:0]  # Empty dataframe
+
+                feature_hover_annotated = HoverTool(
+                    tooltips=build_feature_tooltips(),
+                )
+                feature_hover_unannotated = HoverTool(
+                    tooltips=build_feature_tooltips(),
+                )
+
+                # Select only plottable columns for vdims (exclude complex objects like Chromatogram)
+                base_vdims = ["feature_uid", "inty", "iso", "adduct", "chrom_coherence", "chrom_prominence_scaled"]
+                # Add id_* columns if they exist
+                id_vdims = [col for col in feats.columns if isinstance(col, str) and col.startswith("id_")]
+                all_vdims = base_vdims + id_vdims
+
+                if len(annotated_features) > 0:
+                    vdims_annotated = [col for col in all_vdims if col in annotated_features.columns]
+                    feature_points_1 = hv.Points(
+                        annotated_features,
+                        kdims=["rt", "mz"],
+                        vdims=vdims_annotated,
+                        label="Annotated features",
+                    ).options(
+                        color="#2e7d32",
+                        marker=marker_type,
+                        size=size_1,
+                        tools=[feature_hover_annotated],
+                        hooks=hooks,
+                        show_legend=True,
+                    )
+
+                if len(unannotated_features) > 0:
+                    vdims_unannotated = [col for col in all_vdims if col in unannotated_features.columns]
+                    feature_points_2 = hv.Points(
+                        unannotated_features,
+                        kdims=["rt", "mz"],
+                        vdims=vdims_unannotated,
+                        label="Unannotated features",
+                    ).options(
+                        color="#9e9e9e",
+                        marker=marker_type,
+                        size=size_2,
+                        tools=[feature_hover_unannotated],
+                        hooks=hooks,
+                        show_legend=True,
+                    )
+
         # Handle colorby parameter
-        if colorby is not None and colorby in feats.columns:
+        if (not handled_colorby) and colorby is not None and colorby in feats.columns:
             # Check if colorby data is categorical (string-like)
             colorby_values = feats[colorby].dropna()
             is_categorical = feats[colorby].dtype in ["object", "string", "category"] or (
@@ -1424,17 +1528,7 @@ def plot_2d(
 
                 if len(group_with_ms2) > 0:
                     feature_hover = HoverTool(
-                        tooltips=[
-                            ("rt", "@rt"),
-                            ("m/z", "@mz{0.0000}"),
-                            ("feature_uid", "@feature_uid"),
-                            ("inty", "@inty"),
-                            ("iso", "@iso"),
-                            ("adduct", "@adduct"),
-                            ("chrom_coherence", "@chrom_coherence"),
-                            ("chrom_prominence_scaled", "@chrom_prominence_scaled"),
-                            (colorby, f"@{colorby}"),
-                        ],
+                        tooltips=build_feature_tooltips(include_colorby=colorby),
                     )
                     group_points_ms2 = hv.Points(
                         group_with_ms2,
@@ -1464,17 +1558,7 @@ def plot_2d(
 
                 if len(group_without_ms2) > 0:
                     feature_hover = HoverTool(
-                        tooltips=[
-                            ("rt", "@rt"),
-                            ("m/z", "@mz{0.0000}"),
-                            ("feature_uid", "@feature_uid"),
-                            ("inty", "@inty"),
-                            ("iso", "@iso"),
-                            ("adduct", "@adduct"),
-                            ("chrom_coherence", "@chrom_coherence"),
-                            ("chrom_prominence_scaled", "@chrom_prominence_scaled"),
-                            (colorby, f"@{colorby}"),
-                        ],
+                        tooltips=build_feature_tooltips(include_colorby=colorby),
                     )
                     group_points_no_ms2 = hv.Points(
                         group_without_ms2,
@@ -1500,22 +1584,15 @@ def plot_2d(
                         feature_points_2 = group_points_no_ms2
                     else:
                         feature_points_2 = feature_points_2 * group_points_no_ms2
-        else:
+        
+        # Only use default coloring if no special colorby mode was handled
+        if not handled_colorby and not use_categorical_coloring:
             # Use original green/red coloring scheme for MS2 presence
             # find features with ms2_scans not None  and iso==0
             features_df = feats[feats["ms2_scans"].notnull()]
             # Create feature points with proper sizing method
             feature_hover_1 = HoverTool(
-                tooltips=[
-                    ("rt", "@rt"),
-                    ("m/z", "@mz{0.0000}"),
-                    ("feature_uid", "@feature_uid"),
-                    ("inty", "@inty"),
-                    ("iso", "@iso"),
-                    ("adduct", "@adduct"),
-                    ("chrom_coherence", "@chrom_coherence"),
-                    ("chrom_prominence_scaled", "@chrom_prominence_scaled"),
-                ],
+                tooltips=build_feature_tooltips(),
             )
             if len(features_df) > 0:
                 feature_points_1 = hv.Points(
@@ -1542,16 +1619,7 @@ def plot_2d(
             # find features without MS2 data
             features_df = feats[feats["ms2_scans"].isnull()]
             feature_hover_2 = HoverTool(
-                tooltips=[
-                    ("rt", "@rt"),
-                    ("m/z", "@mz{0.0000}"),
-                    ("feature_uid", "@feature_uid"),
-                    ("inty", "@inty"),
-                    ("iso", "@iso"),
-                    ("adduct", "@adduct"),
-                    ("chrom_coherence", "@chrom_coherence"),
-                    ("chrom_prominence_scaled", "@chrom_prominence_scaled"),
-                ],
+                tooltips=build_feature_tooltips(),
             )
             if len(features_df) > 0:
                 feature_points_2 = hv.Points(
@@ -1581,17 +1649,7 @@ def plot_2d(
             if hasattr(features_df, "to_pandas"):
                 features_df = features_df.to_pandas()
             feature_hover_iso = HoverTool(
-                tooltips=[
-                    ("rt", "@rt"),
-                    ("m/z", "@mz{0.0000}"),
-                    ("feature_uid", "@feature_uid"),
-                    ("inty", "@inty"),
-                    ("iso", "@iso"),
-                    ("iso_of", "@iso_of"),
-                    ("adduct", "@adduct"),
-                    ("chrom_coherence", "@chrom_coherence"),
-                    ("chrom_prominence_scaled", "@chrom_prominence_scaled"),
-                ],
+                tooltips=build_feature_tooltips(include_iso_of=True),
             )
             feature_points_iso = hv.Points(
                 features_df,
@@ -1676,18 +1734,31 @@ def plot_2d(
         overlay = overlay * feature_points_4
     if feature_points_3 is not None:
         overlay = overlay * feature_points_3
-    if feature_points_1 is not None:
-        overlay = overlay * feature_points_1
-    if not show_only_features_with_ms2 and feature_points_2 is not None:
-        overlay = overlay * feature_points_2
+    
+    # In colorby='id' mode, draw unannotated (grey) first, then annotated (green) on top
+    if colorby_id_mode:
+        # Draw grey points first (bottom layer)
+        if feature_points_2 is not None:
+            overlay = overlay * feature_points_2
+        # Draw green points last (top layer)
+        if feature_points_1 is not None:
+            overlay = overlay * feature_points_1
+    else:
+        # Default order: green (with MS2) first, then red (without MS2)
+        if feature_points_1 is not None:
+            overlay = overlay * feature_points_1
+        # In non-id mode, only show features without MS2 if show_only_features_with_ms2 is False
+        if not show_only_features_with_ms2 and feature_points_2 is not None:
+            overlay = overlay * feature_points_2
+    
     if feature_points_iso is not None:
         overlay = overlay * feature_points_iso
 
     if title is not None:
         overlay = overlay.opts(title=title)
 
-    # Handle legend positioning for categorical coloring
-    if legend is not None and use_categorical_coloring and len(categorical_groups) > 1:
+    # Handle legend positioning for categorical coloring or colorby='id' mode
+    if legend is not None and (colorby_id_mode or (use_categorical_coloring and len(categorical_groups) > 1)):
         # Map legend position parameter to HoloViews legend position
         legend_position_map = {
             "top_right": "top_right",
@@ -1704,8 +1775,8 @@ def plot_2d(
 
         # Apply legend configuration to the overlay
         overlay = overlay.opts(legend_position=hv_legend_pos, legend_opts={"title": "", "padding": 2, "spacing": 2})
-    elif legend is None and use_categorical_coloring:
-        # Explicitly hide legend when legend=None but categorical coloring is used
+    elif legend is None and (colorby_id_mode or use_categorical_coloring):
+        # Explicitly hide legend when legend=None but categorical coloring or id mode is used
         overlay = overlay.opts(show_legend=False)
 
     # Handle slider functionality
@@ -1728,12 +1799,27 @@ def plot_2d(
             if feature_points_3 is not None:
                 updated_points_3 = feature_points_3.opts(size=size_val)
                 feature_overlay = updated_points_3 if feature_overlay is None else feature_overlay * updated_points_3
-            if feature_points_1 is not None:
-                updated_points_1 = feature_points_1.opts(size=size_val)
-                feature_overlay = updated_points_1 if feature_overlay is None else feature_overlay * updated_points_1
-            if not show_only_features_with_ms2 and feature_points_2 is not None:
-                updated_points_2 = feature_points_2.opts(size=size_val)
-                feature_overlay = updated_points_2 if feature_overlay is None else feature_overlay * updated_points_2
+            
+            # In colorby='id' mode, draw unannotated (grey) first, then annotated (green) on top
+            if colorby_id_mode:
+                # Draw grey points first (bottom layer)
+                if feature_points_2 is not None:
+                    updated_points_2 = feature_points_2.opts(size=size_val)
+                    feature_overlay = updated_points_2 if feature_overlay is None else feature_overlay * updated_points_2
+                # Draw green points last (top layer)
+                if feature_points_1 is not None:
+                    updated_points_1 = feature_points_1.opts(size=size_val)
+                    feature_overlay = updated_points_1 if feature_overlay is None else feature_overlay * updated_points_1
+            else:
+                # Default order: green (with MS2) first, then red (without MS2)
+                if feature_points_1 is not None:
+                    updated_points_1 = feature_points_1.opts(size=size_val)
+                    feature_overlay = updated_points_1 if feature_overlay is None else feature_overlay * updated_points_1
+                # In non-id mode, only show features without MS2 if show_only_features_with_ms2 is False
+                if not show_only_features_with_ms2 and feature_points_2 is not None:
+                    updated_points_2 = feature_points_2.opts(size=size_val)
+                    feature_overlay = updated_points_2 if feature_overlay is None else feature_overlay * updated_points_2
+            
             if feature_points_iso is not None:
                 updated_points_iso = feature_points_iso.opts(size=size_val)
                 feature_overlay = (
@@ -2390,10 +2476,28 @@ def plot_dda_stats(
         "time_ms2_to_ms2",
         "time_ms2_to_ms1",
     ]
-    # Ensure that 'index' and 'rt' are kept for hover along with the columns to plot
+    # skip cols that are not in stats
+    cols_to_plot = [col for col in cols_to_plot if col in stats.columns]
     stats = stats[["scan_uid", "cycle", "rt", *cols_to_plot]]
     # set any value < 0 to None
-    stats[stats < 0] = None
+    # Replace negative values with nulls in a polars-friendly way
+    numeric_types = {
+        pl.Float32, pl.Float64,
+        pl.Int8, pl.Int16, pl.Int32, pl.Int64,
+        pl.UInt8, pl.UInt16, pl.UInt32, pl.UInt64
+    }
+    exprs = []
+    for col_name, dtype in stats.schema.items():
+        if dtype in numeric_types:
+            exprs.append(
+                pl.when(pl.col(col_name) < 0)
+                  .then(None)
+                  .otherwise(pl.col(col_name))
+                  .alias(col_name)
+            )
+        else:
+            exprs.append(pl.col(col_name))
+    stats = stats.select(exprs)
 
     # Create a Scatter for each column in cols_to_plot stacked vertically, with hover enabled
     scatter_plots = []

masster/sample/sample.py

@@ -129,6 +129,13 @@ from masster.sample.helpers import get_eic
 from masster.sample.helpers import set_source
 from masster.sample.helpers import _recreate_feature_map
 from masster.sample.helpers import _get_feature_map
+from masster.sample.id import lib_load
+from masster.sample.id import identify
+from masster.sample.id import get_id
+from masster.sample.id import id_reset
+from masster.sample.id import lib_reset
+from masster.sample.importers import import_oracle
+from masster.sample.importers import import_tima
 from masster.sample.load import chrom_extract
 from masster.sample.load import _index_file
 from masster.sample.load import load
@@ -164,7 +171,9 @@ from masster.sample.save import export_chrom
 from masster.sample.save import export_dda_stats
 from masster.sample.save import export_features
 from masster.sample.save import export_mgf
-from masster.sample.save import export_xlsx
+from masster.sample.save import export_excel
+from masster.sample.save import export_slaw
+from masster.sample.save import export_mztab
 from masster.sample.save import save
 
 
@@ -259,9 +268,10 @@ class Sample:
         # the polars data frame with MS1 level data
         self.ms1_df = pl.DataFrame()
 
-        # lightweight lib data for matching, targeted analyses, etc. > superseded by study methods
-        self.lib = None
-        self.lib_match = None
+        # identification DataFrames (lib_df and id_df)
+        self.lib_df = None  # library DataFrame (from masster.lib or CSV/JSON)
+        self.id_df = None   # identification results DataFrame
+        self._lib = None    # reference to Lib object if loaded
         self.chrom_df = None
 
         if params.filename is not None:
@@ -292,11 +302,22 @@ class Sample:
     update_parameters = update_parameters
     get_parameters_property = get_parameters_property
     set_parameters_property = set_parameters_property
+    # Identification methods from id.py
+    lib_load = lib_load
+    identify = identify
+    get_id = get_id
+    id_reset = id_reset
+    lib_reset = lib_reset
+    # Importers from importers.py
+    import_oracle = import_oracle
+    import_tima = import_tima
     export_features = export_features
-    export_xlsx = export_xlsx
+    export_excel = export_excel
+    export_slaw = export_slaw
     export_mgf = export_mgf
     export_chrom = export_chrom
     export_dda_stats = export_dda_stats
+    export_mztab = export_mztab
     plot_2d = plot_2d
     plot_2d_oracle = plot_2d_oracle
     plot_dda_stats = plot_dda_stats

masster/sample/sample5_schema.json

@@ -93,10 +93,108 @@
       },
       "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"
+      }
+    }
+  },
+  "lib_df": {
+    "columns": {
+      "lib_uid": {
+        "dtype": "pl.Int64"
+      },
+      "cmpd_uid": {
+        "dtype": "pl.Int64"
+      },
+      "name": {
+        "dtype": "pl.Utf8"
+      },
+      "shortname": {
+        "dtype": "pl.Utf8"
+      },
+      "class": {
+        "dtype": "pl.Utf8"
+      },
+      "formula": {
+        "dtype": "pl.Utf8"
+      },
+      "iso": {
+        "dtype": "pl.Int64"
+      },
+      "smiles": {
+        "dtype": "pl.Utf8"
+      },
+      "inchi": {
+        "dtype": "pl.Utf8"
+      },
+      "inchikey": {
+        "dtype": "pl.Utf8"
+      },
+      "adduct": {
+        "dtype": "pl.Utf8"
+      },
+      "z": {
+        "dtype": "pl.Int64"
+      },
+      "m": {
+        "dtype": "pl.Float64"
+      },
+      "mz": {
+        "dtype": "pl.Float64"
+      },
+      "rt": {
+        "dtype": "pl.Float64"
+      },
+      "quant_group": {
+        "dtype": "pl.Int64"
+      },
+      "probability": {
+        "dtype": "pl.Float64"
+      },
+      "source_id": {
+        "dtype": "pl.Utf8"
+      }
+    }
+  },
+  "id_df": {
+    "columns": {
+      "feature_uid": {
+        "dtype": "pl.Int64"
+      },
+      "lib_uid": {
+        "dtype": "pl.Int64"
+      },
+      "mz_delta": {
+        "dtype": "pl.Float64"
+      },
+      "rt_delta": {
+        "dtype": "pl.Float64"
+      },
+      "matcher": {
+        "dtype": "pl.Utf8"
+      },
+      "score": {
+        "dtype": "pl.Float64"
+      },
+      "iso": {
+        "dtype": "pl.Int64"
       }
     }
   },
-  "generated_date": "2025-08-03",
+  "generated_date": "2025-10-30",
   "ms1_df": {
     "columns": {
       "cycle": {