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

masster/study/defaults/fill_def.py

@@ -58,7 +58,7 @@ class fill_defaults:
                 "dtype": int,
                 "description": "Minimum absolute samples threshold",
                 "default": 5,
-                "min_value": 1,
+                "min_value": 0,
                 "max_value": 100,
             },
         },

masster/study/export.py

@@ -60,7 +60,7 @@ def _get_mgf_df(self, **kwargs):
     # end of parameter initialization
 
     # Store parameters in the Study object
-    self.store_history(["get_mgf"], params.to_dict())
+    self.update_history(["get_mgf"], params.to_dict())
     self.logger.debug("Parameters stored to get_mgf")
 
     # Get parameter values for use in the method
@@ -442,7 +442,8 @@ def export_mgf(self, **kwargs):
         None: Writes MGF file to disk.
     """
     # Get mgf data as DataFrame
-    mgf_data = self._get_mgf_df(**kwargs)
+    from masster.study.export import _get_mgf_df
+    mgf_data = _get_mgf_df(self, **kwargs)
 
     if mgf_data is None or len(mgf_data) == 0:
         self.logger.warning("No MGF data generated.")
@@ -559,7 +560,8 @@ def export_mztab(self, filename: str | None = None, include_mgf=True, **kwargs)
     mgf_data = None
     mgf_mapping: dict[str, list[int]] = {}
     if include_mgf:
-        mgf_data = self._get_mgf_df(**kwargs)
+        from masster.study.export import _get_mgf_df
+        mgf_data = _get_mgf_df(self, **kwargs)
         # Create mapping from feature_uid to MGF indexes
         if mgf_data is not None and len(mgf_data) > 0:
             for row in mgf_data.iter_rows(named=True):

masster/study/h5.py

@@ -2007,6 +2007,9 @@ def _load_study5(self, filename=None):
             f"Successfully migrated {sample_count} samples to indexed map_id format (0 to {sample_count - 1})",
         )
 
+    # Sanitize null feature_id and consensus_id values with new UIDs (same method as merge)
+    self._sanitize_null_ids()
+
     self.logger.debug("Study loaded")
 
 

masster/study/helpers.py

@@ -49,7 +49,7 @@ def get_bpc(owner, sample=None, rt_unit="s", label=None, original=False):
         s = owner
     else:
         # owner is expected to be a Study
-        s = get_sample(owner, sample)
+        s = get_samples(owner, sample)
 
     if s is None:
         raise ValueError("Could not resolve sample for BPC computation")
@@ -189,7 +189,7 @@ def get_tic(owner, sample=None, label=None):
     if hasattr(owner, "ms1_df"):
         s = owner
     else:
-        s = get_sample(owner, sample)
+        s = get_samples(owner, sample)
 
     if s is None:
         raise ValueError("Could not resolve sample for TIC computation")
@@ -278,7 +278,7 @@ def get_eic(owner, sample=None, mz=None, mz_tol=None, rt_unit="s", label=None):
         s = owner
     else:
         # owner is expected to be a Study
-        s = get_sample(owner, sample)
+        s = get_samples(owner, sample)
 
     if s is None:
         raise ValueError("Could not resolve sample for EIC computation")
@@ -360,7 +360,7 @@ def get_chrom(self, uids=None, samples=None):
         return None
 
     ids = self._get_consensus_uids(uids)
-    sample_uids = self._get_sample_uids(samples)
+    sample_uids = self._get_samples_uids(samples)
 
     if self.consensus_map is None:
         self.logger.error("No consensus map found.")
@@ -467,7 +467,7 @@ def get_chrom(self, uids=None, samples=None):
 # =====================================================================================
 
 
-def set_folder(self, folder):
+def set_study_folder(self, folder):
     """
     Set the folder for saving and loading files.
     """
@@ -492,7 +492,8 @@ def align_reset(self):
     )
 
     # Ensure column order is maintained after with_columns operation
-    self._ensure_features_df_schema_order()
+    from masster.study.helpers import _ensure_features_df_schema_order
+    _ensure_features_df_schema_order(self)
 
 
 # =====================================================================================
@@ -722,7 +723,7 @@ def fill_reset(self):
     )
 
 
-def _get_feature_uids(self, uids=None, seed=42):
+def _get_features_uids(self, uids=None, seed=42):
     """
     Helper function to get feature_uids from features_df based on input uids.
     If uids is None, returns all feature_uids.
@@ -806,7 +807,7 @@ def _get_consensus_uids(self, uids=None, seed=42):
         return consensus_uids
 
 
-def _get_sample_uids(self, samples=None, seed=42):
+def _get_samples_uids(self, samples=None, seed=42):
     """
     Helper function to get sample_uids from samples_df based on input samples.
     If samples is None, returns all sample_uids.
@@ -847,7 +848,7 @@ def _get_sample_uids(self, samples=None, seed=42):
         return sample_uids
 
 
-def get_sample(self, sample):
+def get_samples(self, sample):
     """
     Return a `Sample` object corresponding to the provided sample identifier.
 
@@ -911,6 +912,138 @@ def get_orphans(self):
     return not_in_consensus
 
 
+def get_sample_stats(self):
+    """
+    Get statistics for all samples in the study.
+    
+    Returns:
+        pl.DataFrame: DataFrame with the following columns:
+            - sample_uid: Sample unique identifier
+            - num_features: Total number of features per sample
+            - num_ms1: Number of MS1 features per sample
+            - num_ms2: Number of MS2 features per sample  
+            - num_linked_ms1: Number of non-filled features present in consensus_mapping_df
+            - num_orphans: Number of non-filled features not present in consensus_mapping_df
+            - max_rt_correction: Maximum RT correction applied
+            - average_rt_correction: Average RT correction applied
+            - num_linked_ms2: Number of linked MS2 spectra from consensus_ms2_df
+    """
+    if self.samples_df is None or self.samples_df.is_empty():
+        self.logger.warning("No samples found in study.")
+        return pl.DataFrame()
+    
+    if self.features_df is None or self.features_df.is_empty():
+        self.logger.warning("No features found in study.")
+        return pl.DataFrame()
+    
+    # Get base sample information
+    sample_uids = self.samples_df["sample_uid"].to_list()
+    stats_data = []
+    
+    for sample_uid in sample_uids:
+        # Filter features for this sample
+        sample_features = self.features_df.filter(pl.col("sample_uid") == sample_uid)
+        
+        if sample_features.is_empty():
+            # Sample has no features
+            stats_data.append({
+                "sample_uid": sample_uid,
+                "num_features": 0,
+                "num_ms1": 0,
+                "num_ms2": 0,
+                "num_linked_ms1": 0,
+                "num_orphans": 0,
+                "max_rt_correction": None,
+                "average_rt_correction": None,
+                "num_linked_ms2": 0
+            })
+            continue
+        
+        # Basic feature counts
+        num_features = len(sample_features)
+        
+        # Count MS1 and MS2 features
+        # Assume features with ms_level=1 or missing ms_level are MS1
+        num_ms1 = sample_features.filter(
+            pl.col("ms_level").is_null() | (pl.col("ms_level") == 1)
+        ).height if "ms_level" in sample_features.columns else num_features
+        
+        num_ms2 = sample_features.filter(
+            pl.col("ms_level") == 2
+        ).height if "ms_level" in sample_features.columns else 0
+        
+        # Get non-filled features for this sample
+        if "filled" in sample_features.columns:
+            non_filled_features = sample_features.filter(~pl.col("filled") | pl.col("filled").is_null())
+        else:
+            non_filled_features = sample_features
+        
+        # Count linked MS1 features (non-filled and present in consensus_mapping_df)
+        num_linked_ms1 = 0
+        if not self.consensus_mapping_df.is_empty() and not non_filled_features.is_empty():
+            linked_feature_uids = self.consensus_mapping_df.filter(
+                pl.col("sample_uid") == sample_uid
+            )["feature_uid"].to_list()
+            
+            num_linked_ms1 = non_filled_features.filter(
+                pl.col("feature_uid").is_in(linked_feature_uids)
+            ).height
+        
+        # Count orphan features (non-filled and NOT present in consensus_mapping_df)
+        num_orphans = len(non_filled_features) - num_linked_ms1
+        
+        # Calculate RT correction statistics
+        max_rt_correction = None
+        average_rt_correction = None
+        
+        if "rt" in sample_features.columns and "rt_original" in sample_features.columns:
+            rt_corrections = sample_features.with_columns(
+                (pl.col("rt") - pl.col("rt_original")).alias("rt_correction")
+            ).filter(
+                pl.col("rt_correction").is_not_null()
+            )["rt_correction"]
+            
+            if not rt_corrections.is_empty():
+                max_rt_correction = rt_corrections.abs().max()
+                average_rt_correction = rt_corrections.abs().mean()
+        
+        # Count linked MS2 spectra from consensus_ms2_df
+        num_linked_ms2 = 0
+        if hasattr(self, 'consensus_ms2') and self.consensus_ms2 is not None and not self.consensus_ms2.is_empty():
+            if "sample_uid" in self.consensus_ms2.columns:
+                num_linked_ms2 = self.consensus_ms2.filter(
+                    pl.col("sample_uid") == sample_uid
+                ).height
+        
+        stats_data.append({
+            "sample_uid": sample_uid,
+            "num_features": num_features,
+            "num_ms1": num_ms1,
+            "num_ms2": num_ms2,
+            "num_linked_ms1": num_linked_ms1,
+            "num_orphans": num_orphans,
+            "max_rt_correction": max_rt_correction,
+            "average_rt_correction": average_rt_correction,
+            "num_linked_ms2": num_linked_ms2
+        })
+    
+    # Create DataFrame with proper schema
+    return pl.DataFrame(
+        stats_data,
+        schema={
+            "sample_uid": pl.UInt64,
+            "num_features": pl.UInt32,
+            "num_ms1": pl.UInt32,
+            "num_ms2": pl.UInt32,
+            "num_linked_ms1": pl.UInt32,
+            "num_orphans": pl.UInt32,
+            "max_rt_correction": pl.Float64,
+            "average_rt_correction": pl.Float64,
+            "num_linked_ms2": pl.UInt32
+        }
+    )
+
+
 # =====================================================================================
 # DATA COMPRESSION AND RESTORATION FUNCTIONS
 # =====================================================================================
@@ -995,7 +1128,7 @@ def restore_features(self, samples=None, maps=False):
         return
 
     # Get sample_uids to process
-    sample_uids = self._get_sample_uids(samples)
+    sample_uids = self._get_samples_uids(samples)
 
     if not sample_uids:
         self.logger.warning("No valid samples specified.")
@@ -1154,7 +1287,7 @@ def restore_chrom(self, samples=None, mz_tol=0.010, rt_tol=10.0):
         return
 
     # Get sample_uids to process
-    sample_uids = self._get_sample_uids(samples)
+    sample_uids = self._get_samples_uids(samples)
     if not sample_uids:
         self.logger.warning("No valid samples specified.")
         return
@@ -1610,7 +1743,7 @@ def sample_name_reset(self):
     )
 
 
-def set_source(self, filename):
+def set_samples_source(self, filename):
     """
     Reassign file_source for all samples in samples_df. If filename contains only a path,
     keep the current basename and build an absolute path. Check that the new file exists
@@ -3301,7 +3434,7 @@ def samples_delete(self, samples):
 # =====================================================================================
 
 
-def sample_color(self, by=None, palette="Turbo256"):
+def set_samples_color(self, by=None, palette="Turbo256"):
     """
     Set sample colors in the sample_color column of samples_df.
 
@@ -3344,13 +3477,13 @@ def sample_color(self, by=None, palette="Turbo256"):
 
     Example:
         # Set colors based on sample type
-        study.sample_color(by='sample_type', palette='Set1')
+        study.set_samples_color(by='sample_type', palette='Set1')
 
         # Set colors using a custom color list
-        study.sample_color(by=['#FF0000', '#00FF00', '#0000FF'])
+        study.set_samples_color(by=['#FF0000', '#00FF00', '#0000FF'])
 
         # Reset to default Turbo256 sequential colors
-        study.sample_color()
+        study.set_samples_color()
     """
     if self.samples_df is None or len(self.samples_df) == 0:
         self.logger.warning("No samples found in study.")
@@ -3473,67 +3606,7 @@ def sample_color(self, by=None, palette="Turbo256"):
         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: uv add cmap",
-        )
-    except Exception as e:
-        self.logger.error(f"Failed to reset sample colors: {e}")
 
 
 def _get_color_palette(palette_name):
@@ -3634,7 +3707,7 @@ def _get_color_palette(palette_name):
 
 def _sample_colors_from_colormap(palette_name, n_colors):
     """
-    Sample colors evenly from the whole colormap range, similar to sample_color_reset.
+    Sample colors evenly from the whole colormap range, similar to set_samples_color(by=None).
 
     Parameters:
         palette_name (str): Name of the palette/colormap
@@ -3686,7 +3759,7 @@ def _sample_colors_from_colormap(palette_name, n_colors):
 
         colors = []
 
-        # Distribute samples evenly across the full colormap range (same approach as sample_color_reset)
+        # Distribute samples evenly across the full colormap range (same approach as set_samples_color(by=None))
         for i in range(n_colors):
             # Evenly distribute samples across colormap (avoiding endpoints to prevent white/black)
             normalized_value = (
@@ -3818,7 +3891,7 @@ def restore_ms2(self, samples=None, **kwargs):
         return
 
     # Get sample_uids to process
-    sample_uids = self._get_sample_uids(samples)
+    sample_uids = self._get_samples_uids(samples)
     if not sample_uids:
         self.logger.warning("No valid samples specified.")
         return
@@ -3888,7 +3961,7 @@ def decompress(self, features=True, ms2=True, chrom=True, samples=None, **kwargs
         return
 
     # Get sample_uids to process
-    sample_uids = self._get_sample_uids(samples)
+    sample_uids = self._get_samples_uids(samples)
     if not sample_uids:
         self.logger.warning("No valid samples specified.")
         return