msreport 0.0.29__py3-none-any.whl → 0.0.31__py3-none-any.whl

msreport/peptidoform.py

@@ -1,5 +1,14 @@
+"""Defines the `Peptide` class and associated utilities for handling peptidoforms.
+
+This module provides a `Peptide` class for representing modified peptide sequences,
+and their site localization probabilities. It offers methods to access and manipulate
+peptide information, summarize isoform probabilities, and retrieve modification sites.
+Additionally, it includes utility functions for parsing modified sequence strings and
+converting site localization probabilities to and from a standardized string format.
+"""
+
 from collections import defaultdict as ddict
-from typing import Optional, Union
+from typing import Optional
 
 import numpy as np
 
@@ -10,7 +19,7 @@ class Peptide:
     def __init__(
         self,
         modified_sequence: str,
-        localization_probabilities: Optional[dict] = None,
+        localization_probabilities: Optional[dict[str, dict[int, float]]] = None,
         protein_position: Optional[int] = None,
     ):
         plain_sequence, modifications = parse_modified_sequence(
@@ -28,7 +37,7 @@ class Peptide:
             self.modification_positions[mod_tag].append(position)
             self.modified_residues[position] = mod_tag
 
-    def make_modified_sequence(self, include: Optional[list] = None) -> str:
+    def make_modified_sequence(self, include: Optional[list[str]] = None) -> str:
         """Returns a modified sequence string.
 
         Args:
@@ -55,7 +64,7 @@ class Peptide:
             return 0
         return len(self.modification_positions[modification])
 
-    def isoform_probability(self, modification: str) -> Union[float, None]:
+    def isoform_probability(self, modification: str) -> float | None:
         """Calculates the isoform probability for a given modification.
 
         Returns:
@@ -66,12 +75,13 @@ class Peptide:
         """
         probabilities = []
         for site in self.list_modified_peptide_sites(modification):
-            probabilities.append(self.get_peptide_site_probability(site))
-        if None in probabilities:
-            return None
+            probability = self.get_peptide_site_probability(site)
+            if probability is None:
+                return None
+            probabilities.append(probability)
         return float(np.prod(probabilities))
 
-    def get_peptide_site_probability(self, position: int) -> Optional[float]:
+    def get_peptide_site_probability(self, position: int) -> float | None:
         """Return the modification localization probability of the peptide position.
 
         Args:
@@ -85,7 +95,7 @@ class Peptide:
         """
         return self._get_site_probability(position, is_protein_position=False)
 
-    def get_protein_site_probability(self, position: int) -> Optional[float]:
+    def get_protein_site_probability(self, position: int) -> float | None:
         """Return the modification localization probability of the protein position.
 
         Args:
@@ -109,7 +119,7 @@ class Peptide:
 
     def _get_site_probability(
         self, position: int, is_protein_position: bool
-    ) -> Optional[float]:
+    ) -> float | None:
         """Return the modification localization probability of the peptide position.
 
         Args:
@@ -224,7 +234,7 @@ def modify_peptide(
 
 
 def make_localization_string(
-    localization_probabilities: dict, decimal_places: int = 3
+    localization_probabilities: dict[str, dict[int, float]], decimal_places: int = 3
 ) -> str:
     """Generates a site localization probability string.
 

msreport/plot/__init__.py

@@ -1,4 +1,4 @@
-"""This module provides various plotting functions for visualizing data within a Qtable.
+"""Plotting functions for visualizing proteomics data from `Qtable`.
 
 The functions in this module generate a wide range of plots, including heatmaps, PCA
 plots, volcano plots, and histograms, to analyze and compare expression values,
@@ -6,8 +6,8 @@ missingness, contaminants, and other features in proteomics datasets. The plots
 designed to work with the Qtable class as input, which provides structured access to
 proteomics data and experimental design information.
 
-The style of the plots can be customized using the `set_active_style` function, which
-allows applying style sheets from the msreport library or those available in matplotlib.
+Users can customize plot styles via the `set_active_style` function, which allows
+applying style sheets from the msreport library or those available in matplotlib.
 """
 
 from .comparison import expression_comparison, pvalue_histogram, volcano_ma

msreport/plot/distribution.py

@@ -204,7 +204,8 @@ def experiment_ratios(
     mask = np.all([(qtable.data[f"Events {exp}"] > 0) for exp in experiments], axis=0)
     if exclude_invalid:
         mask = mask & qtable["Valid"]
-    experiment_data = experiment_data[mask]
+    # Use `mask.to_numpy` to solve issue with different indices of mask and dataframe
+    experiment_data = experiment_data[mask.to_numpy()]
     pseudo_reference = np.nanmean(experiment_data, axis=1)
     ratio_data = experiment_data.subtract(pseudo_reference, axis=0)
 

msreport/plot/quality.py

@@ -314,7 +314,7 @@ def sample_intensities(
 
 @with_active_style
 def sample_correlation(
-    qtable, exclude_invalid: bool = True, labels: bool = False
+    qtable: Qtable, exclude_invalid: bool = True, labels: bool = False
 ) -> tuple[plt.Figure, list[plt.Axes]]:
     """Generates a pair-wise correlation matrix of samples 'Expression' values.
 

msreport/qtable.py

@@ -1,14 +1,28 @@
-from __future__ import annotations
+"""Defines the `Qtable` class, the central container for quantitative proteomics data.
+
+The `Qtable` class serves as the standardized data structure for `msreport`,
+storing a main table with quantitative values and associated metadata for its entries;
+it also maintains the name of the unique ID column for the main table. Additionally,
+it stores an experimental design table that links sample names to experimental
+conditions and replicate information.
+
+`Qtable` provides convenience methods for creating subtables and accessing design
+related information (e.g., samples per experiment), and instances of `Qtable` can be
+easily saved to disk and loaded back. As the central data container, the `Qtable`
+facilitates seamless integration with the high-level modules `analyze`, `plot` and
+`export`, which all directly operate on `Qtable` instances.
+"""
 
 import copy
 import os
 import warnings
 from contextlib import contextmanager
-from typing import Any, Iterable, Optional
+from typing import Any, Generator, Iterable, Optional
 
 import numpy as np
 import pandas as pd
 import yaml
+from typing_extensions import Self
 
 import msreport.helper as helper
 
@@ -27,13 +41,11 @@ class Qtable:
         design: A pandas.DataFrame describing the experimental design.
     """
 
-    _default_id_column = "Representative protein"
-
     def __init__(
         self,
         data: pd.DataFrame,
-        design: Optional[pd.DataFrame] = None,
-        id_column: str = "Representative protein",
+        design: pd.DataFrame,
+        id_column: str,
     ):
         """Initializes the Qtable.
 
@@ -42,12 +54,13 @@ class Qtable:
 
         Args:
             data: A dataframe containing quantitative proteomics data in a wide format.
+                The index of the dataframe must contain unique values.
             design: A dataframe describing the experimental design that must at least
                 contain the columns "Sample" and "Experiment". The "Sample" entries
                 should correspond to the Sample names present in the quantitative
                 columns of the data.
             id_column: The name of the column that contains the unique identifiers for
-                the entries in the data table. Default is "Representative protein".
+                the entries in the data table.
 
         Raises:
             KeyError: If the specified id_column is not found in data.
@@ -76,8 +89,7 @@ class Qtable:
         self._id_column = id_column
         if "Valid" not in self.data.columns:
             self.data["Valid"] = True
-        if design is not None:
-            self.add_design(design)
+        self.add_design(design)
 
         self._expression_columns: list[str] = []
         self._expression_features: list[str] = []
@@ -361,7 +373,7 @@ class Qtable:
         keep_experiments: Optional[Iterable[str]] = None,
         exclude_samples: Optional[Iterable[str]] = None,
         keep_samples: Optional[Iterable[str]] = None,
-    ):
+    ) -> Generator[None, None, None]:
         """Context manager to temporarily modify the design table.
 
         Args:
@@ -424,7 +436,7 @@ class Qtable:
         self.design.to_csv(filepaths["design"], sep="\t", index=True)
 
     @classmethod
-    def load(cls, directory: str, basename: str) -> Qtable:
+    def load(cls, directory: str, basename: str) -> Self:
         """Load a qtable from disk by reading a data, design, and config file.
 
         Loading a qtable will first import the three files generated during saving, then
@@ -438,6 +450,11 @@ class Qtable:
 
         Returns:
             An instance of Qtable loaded from the specified files.
+
+        Raises:
+            ValueError: If the loaded config file does not contain the
+                "Unique ID column" key. This is due to the qtable being saved with a
+                version of msreport <= 0.0.27.
         """
         filepaths = _get_qtable_export_filepaths(directory, basename)
         with open(filepaths["config"]) as openfile:
@@ -458,13 +475,20 @@ class Qtable:
                 filepaths["design"], sep="\t", index_col=0, keep_default_na=True
             )
 
-        qtable = Qtable(data, design)
+        if "Unique ID column" not in config_data:
+            # Mention that the qtable was likely saved with a version of msreport <= 0.0.27
+            raise ValueError(
+                "The qtable config file does not contain the 'Unique ID column' key. "
+                "This is likely due to the qtable being saved with a version of "
+                "msreport <= 0.0.27."
+            )
+        id_column = config_data["Unique ID column"]
+
+        qtable = cls(data, design, id_column)
         qtable._expression_columns = config_data["Expression columns"]
         qtable._expression_features = config_data["Expression features"]
         qtable._expression_sample_mapping = config_data["Expression sample mapping"]
         # This check is required for backwards compatibility with msreport <= 0.0.27
-        if "Unique ID column" in config_data:
-            qtable._id_column = config_data["Unique ID column"]
         return qtable
 
     def to_tsv(self, path: str, index: bool = False):
@@ -476,11 +500,11 @@ class Qtable:
         )
         self.data.to_csv(path, sep="\t", index=index)
 
-    def to_clipboard(self, index: bool = False):
+    def to_clipboard(self, index: bool = False) -> None:
         """Writes the data table to the system clipboard."""
         self.data.to_clipboard(sep="\t", index=index)
 
-    def copy(self) -> Qtable:
+    def copy(self) -> Self:
         """Returns a copy of this Qtable instance."""
         return self.__copy__()
 
@@ -569,8 +593,8 @@ class Qtable:
         self._expression_features = []
         self._expression_sample_mapping = {}
 
-    def __copy__(self) -> Qtable:
-        new_instance = Qtable(self.data, self.design)
+    def __copy__(self) -> Self:
+        new_instance = type(self)(self.data, self.design, self.id_column)
         # Copy all private attributes
         for attr in dir(self):
             if (
@@ -599,7 +623,7 @@ def _match_samples_to_tag_columns(
     samples: Iterable[str],
     columns: Iterable[str],
     tag: str,
-) -> dict:
+) -> dict[str, str]:
     """Mapping of samples to columns which contain the sample and the tag.
 
     Args:
@@ -622,7 +646,7 @@ def _match_samples_to_tag_columns(
     return mapping
 
 
-def _get_qtable_export_filepaths(directory: str, name: str):
+def _get_qtable_export_filepaths(directory: str, name: str) -> dict[str, str]:
     """Returns a dictionary of standard filepaths for loading and saving a qtable."""
     filenames = {
         "data": f"{name}.data.tsv",