msreport 0.0.24__py3-none-any.whl

msreport/helper/temp.py

@@ -0,0 +1,99 @@
+def extract_modifications(
+    peptide: str,
+    tag_open: str,
+    tag_close: str,
+) -> list[tuple[int, str]]:
+    """Returns a list of modification positions and strings.
+
+    Args:
+        peptide: Peptide sequence containing modifications
+        tag_open: Symbol that indicates the beginning of a modification tag, e.g. "[".
+        tag_close: Symbol that indicates the end of a modification tag, e.g. "]".
+
+    Returns:
+        A sorted list of modification tuples, containing position and modification
+        string (excluding the tag_open and tag_close strings).
+    """
+    start_counter = 0
+    tags = []
+    for position, char in enumerate(peptide):
+        if char == tag_open:
+            start_counter += 1
+            if start_counter == 1:
+                start_position = position
+        elif char == tag_close:
+            start_counter -= 1
+            if start_counter == 0:
+                tags.append((start_position, position))
+
+    modifications = []
+    last_position = 0
+    for tag_start, tag_end in tags:
+        mod_position = tag_start - last_position
+        modification = peptide[tag_start + 1 : tag_end]
+        modifications.append((mod_position, modification))
+        last_position += tag_end - tag_start + 1
+    return sorted(modifications)
+
+
+def modify_peptide(
+    sequence: str,
+    modifications: list[tuple[int, str]],
+    tag_open: str = "[",
+    tag_close: str = "]",
+) -> str:
+    """Returns a string containing the modifications within the peptide sequence.
+
+    Returns:
+        Modified sequence. For example "PEPT[phospho]IDE", for sequence = "PEPTIDE" and
+        modifications = [(4, "phospho")]
+    """
+    last_pos = 0
+    modified_sequence = ""
+    for pos, mod in sorted(modifications):
+        tag = mod.join((tag_open, tag_close))
+        modified_sequence += sequence[last_pos:pos] + tag
+        last_pos = pos
+    modified_sequence += sequence[last_pos:]
+    return modified_sequence
+
+
+def extract_window_around_position(protein_sequence: str, position: int) -> str:
+    """Extracts a window around the specified position in the protein sequence.
+
+    Args:
+        protein_sequence: The input protein sequence string.
+        position: The position in the protein sequence to extract the window around.
+            Position is one-indexed, which means that the first amino acid position 1.
+
+    Returns:
+        A string containing the window +/- 5 characters around the specified position.
+        If the position is too close to the beginning or the end of the
+        'protein_sequence', the window is padded with '-' to ensure there are five
+        characters before and after the position.
+
+    Example:
+        >>> protein_sequence = "ABCDEFGHIJKLM"
+        >>> extract_window_around_position(protein_sequence, 7)
+        'BCDEFGHIJKL'
+        >>> extract_window_around_position(protein_sequence, 1)
+        '-----ABCDEF'
+        >>> extract_window_around_position(protein_sequence, 13)
+        'HIJKLM-----'
+    """
+    # TODO: Not tested
+    extension = 5
+    ond_index_correction = -1
+    _position = position + ond_index_correction
+    gap_filler = "-"
+
+    gap_to_end = len(protein_sequence) - (_position + 1)
+    gap_to_start = _position
+    left_pad = extension - gap_to_start if gap_to_start < extension else 0
+    left_right = extension - gap_to_end if gap_to_end < extension else 0
+
+    window_start = max(_position - extension, 0)
+    window_end = min(_position + extension, len(protein_sequence))
+    window = protein_sequence[window_start : window_end + 1]
+    window = "".join([gap_filler * left_pad, window, gap_filler * left_right])
+    return window

msreport/impute.py

@@ -0,0 +1,275 @@
+from __future__ import annotations
+from typing import Optional
+
+import numpy as np
+import pandas as pd
+
+from msreport.errors import NotFittedError
+
+
+class FixedValueImputer:
+    """Imputer for completing missing values with a fixed value.
+
+    Replace missing values using a constant value or with an integer that is smaller
+    than the minimum value of each column or smaller than the minimum value of the whole
+    array.
+    """
+
+    def __init__(
+        self,
+        strategy: str,
+        fill_value: Optional[float] = None,
+        column_wise: bool = True,
+    ):
+        """Initializes the FixedValueImputer.
+
+        Args:
+            strategy: The imputation strategy.
+                - If "constant", replace missing values with 'fill_value'.
+                - If "below", replace missing values with an integer that is smaller
+                  than the minimal value of the fitted dataframe. Minimal values are
+                  calculated per column if 'column_wise' is True, otherwise the minimal
+                  value is calculated for all columns.
+            fill_value: When strategy is "constant", 'fill_value' is used to replace all
+                occurrences of missing_values.
+            column_wise: If True, imputation is performed independently for each column,
+                otherwise the whole dataframe is imputed togeter. Default True.
+
+        """
+        self.strategy = strategy
+        self.fill_value = fill_value
+        self.column_wise = column_wise
+        self._sample_fill_values: dict[str, float] = {}
+
+    def fit(self, table: pd.DataFrame) -> FixedValueImputer:
+        """Fits the FixedValueImputer.
+
+        Args:
+            table: Input Dataframe for generating fill values for each column.
+
+        Returns:
+            Returns the fitted FixedValueImputer instance.
+        """
+        if self.strategy == "constant":
+            # if not isinstance(self.fill_value, (float, int)):
+            #     raise Excpetion()
+            fill_values = {column: self.fill_value for column in table.columns}
+        elif self.strategy == "below":
+            if self.column_wise:
+                fill_values = {}
+                for column in table:
+                    fill_values[column] = _calculate_integer_below_min(table[column])
+            else:
+                int_below_min = _calculate_integer_below_min(table)
+                fill_values = {column: int_below_min for column in table.columns}
+        self._sample_fill_values = fill_values
+        return self
+
+    def is_fitted(self) -> bool:
+        """Returns True if the FixedValueImputer has been fitted."""
+        return len(self._sample_fill_values) != 0
+
+    def transform(self, table: pd.DataFrame) -> pd.DataFrame:
+        """Impute all missing values in 'table'.
+
+        Args:
+            table: A dataframe of numeric values that will be completed. Each column
+                name must correspond to a column name from the table that was used for
+                the fitting.
+
+        Returns:
+            'table' with imputed missing values.
+        """
+        confirm_is_fitted(self)
+
+        _table = table.copy()
+        for column in _table.columns:
+            column_data = np.array(_table[column], dtype=float)
+            mask = ~np.isfinite(column_data)
+            column_data[mask] = self._sample_fill_values[column]
+            _table[column] = column_data
+        return _table
+
+
+class GaussianImputer:
+    """Imputer for completing missing values by drawing from a gaussian distribution."""
+
+    def __init__(self, mu: float, sigma: float, seed: Optional[int] = None):
+        """Initializes the GaussianImputer.
+
+        Args:
+            mu: Mean of the gaussian distribution.
+            sigma: Standard deviation of the gaussian distribution, must be positive.
+            seed: Optional, allows specifying a number for initializing the random
+                number generator. Using the same seed for the same input table will
+                generate the same set of imputed values each time. Default is None,
+                which results in different imputed values being generated each time.
+        """
+        self.mu = mu
+        self.sigma = sigma
+        self.seed = seed
+
+    def fit(self, table: pd.DataFrame) -> GaussianImputer:
+        """Fits the GaussianImputer, altough this is not necessary.
+
+        Args:
+            table: Input Dataframe for fitting.
+
+        Returns:
+            Returns the fitted GaussianImputer instance.
+        """
+        return self
+
+    def is_fitted(self) -> bool:
+        """Returns always True, as the GaussianImputer does not need to be fitted."""
+        return True
+
+    def transform(self, table: pd.DataFrame) -> pd.DataFrame:
+        """Impute all missing values in 'table'.
+
+        Args:
+            table: A dataframe of numeric values that will be completed. Each column
+                name must correspond to a column name from the table that was used for
+                the fitting.
+
+        Returns:
+            'table' with imputed missing values.
+        """
+        confirm_is_fitted(self)
+        np.random.seed(self.seed)
+
+        _table = table.copy()
+        for column in _table.columns:
+            column_data = np.array(_table[column], dtype=float)
+            mask = ~np.isfinite(column_data)
+            column_data[mask] = np.random.normal(
+                loc=self.mu, scale=self.sigma, size=mask.sum()
+            )
+            _table[column] = column_data
+        return _table
+
+
+class PerseusImputer:
+    """Imputer for completing missing values as implemented in Perseus.
+
+    Perseus-style imputation replaces missing values by random numbers drawn from a
+    normal distribution. Sigma and mu of this distribution are calculated from the
+    standard deviation and median of the observed values.
+    """
+
+    def __init__(
+        self,
+        median_downshift: float = 1.8,
+        std_width: float = 0.3,
+        column_wise: bool = True,
+        seed: Optional[int] = None,
+    ):
+        """Initializes the GaussianImputer.
+
+        Args:
+            median_downshift: Times of standard deviations the observed median is
+                downshifted for calulating mu of the normal distribution. Default is 1.8
+            std_width: Factor for adjusting the standard deviation of the observed
+                values to obtain sigma of the normal distribution. Default is 0.3
+            column_wise: If True, imputation is performed independently for each column,
+                otherwise the whole dataframe is imputed togeter. Default True.
+            seed: Optional, allows specifying a number for initializing the random
+                number generator. Using the same seed for the same input table will
+                generate the same set of imputed values each time. Default is None,
+                which results in different imputed values being generated each time.
+
+        """
+        self.median_downshift = median_downshift
+        self.std_width = std_width
+        self.column_wise = column_wise
+        self.seed = seed
+        self._column_params: dict[str, dict] = {}
+
+    def fit(self, table: pd.DataFrame) -> PerseusImputer:
+        """Fits the PerseusImputer.
+
+        Args:
+            table: Input Dataframe for calculating mu and sigma of the gaussian
+                distribution.
+
+        Returns:
+            Returns the fitted PerseusImputer instance.
+        """
+        for column in table.columns:
+            if self.column_wise:
+                median = np.nanmedian(table[column])
+                std = np.nanstd(table[column])
+            else:
+                median = np.nanmedian(table)
+                std = np.nanstd(table)
+
+            mu = median - (std * self.median_downshift)
+            sigma = std * self.std_width
+
+            self._column_params[column] = {"mu": mu, "sigma": sigma}
+        return self
+
+    def is_fitted(self) -> bool:
+        """Returns True if the PerseusImputer has been fitted."""
+        return len(self._column_params) != 0
+
+    def transform(self, table: pd.DataFrame) -> pd.DataFrame:
+        """Impute all missing values in 'table'.
+
+        Args:
+            table: A dataframe of numeric values that will be completed. Each column
+                name must correspond to a column name from the table that was used for
+                the fitting.
+
+        Returns:
+            'table' with imputed missing values.
+        """
+        confirm_is_fitted(self)
+        np.random.seed(self.seed)
+
+        _table = table.copy()
+        for column in _table.columns:
+            column_data = np.array(_table[column], dtype=float)
+            mask = ~np.isfinite(column_data)
+            column_data[mask] = np.random.normal(
+                loc=self._column_params[column]["mu"],
+                scale=self._column_params[column]["sigma"],
+                size=mask.sum(),
+            )
+            _table[column] = column_data
+        return _table
+
+
+def confirm_is_fitted(imputer: any, msg: Optional[str] = None) -> None:
+    """Perform is_fitted validation for imputer instances.
+
+    Checks if the imputer is fitted by verifying the presence of fitted attributes
+    and otherwise raises a NotFittedError with the given message.
+
+    Args:
+        msg : str, default=None
+            The default error message is, "This %(name) instance is not fitted
+            yet. Call 'fit' with appropriate arguments before using this
+            normalizer."
+    """
+    if msg is None:
+        msg = (
+            "This %(name)s instance is not fitted yet. Call 'fit' with "
+            "appropriate arguments before using this imputer."
+        )
+
+    if not hasattr(imputer, "is_fitted"):
+        raise TypeError(f"{imputer} is not an imputer instance.")
+    else:
+        fitted = imputer.is_fitted()
+
+    if not fitted:
+        raise NotFittedError(msg % {"name": type(imputer).__name__})
+
+
+def _calculate_integer_below_min(table) -> int:
+    minimal_value = np.nanmin(table.to_numpy().flatten())
+    below_minimal = np.floor(minimal_value)
+    if minimal_value <= below_minimal:
+        below_minimal = below_minimal - 1
+    return int(below_minimal)

msreport/isobar.py

@@ -0,0 +1,161 @@
+from __future__ import annotations
+import functools
+from typing import Protocol
+
+import numpy as np
+import pandas as pd
+import scipy
+
+import msreport.helper
+from msreport.errors import NotFittedError
+
+
+class Transformer(Protocol):
+    def fit(self, table: pd.DataFrame) -> Transformer:
+        """Fits the Transformer and returns a fitted Transformer instance."""
+
+    def is_fitted(self) -> bool:
+        """Returns True if the Transformer has been fitted."""
+
+    def transform(self, table: pd.DataFrame) -> pd.DataFrame:
+        """Transform values in 'table'."""
+
+
+class IsotopeImpurityCorrecter:
+    """Corrects isotope impurity interference in isobaric reporter expression values."""
+
+    def __init__(self):
+        self._impurity_matrix = None
+
+    def fit(self, impurity_matrix: np.array) -> IsotopeImpurityCorrecter:
+        """Fits the isotope impurity correcter to a given impurity matrix.
+
+        Args:
+            impurity_matrix: A reporter isotope impurity matrix in a diagonal format,
+                where columns describe the isotope impurity of a specific channel, and
+                the values in each row indicate the percentage of signal from the
+                reporter that is present in each channel. Both dimensions of the
+                impurity matrix must have the same length.
+
+        Returns:
+            Returns the fitted class IsotopeImpurityCorrecter instance.
+        """
+        if impurity_matrix.shape[0] != impurity_matrix.shape[1]:
+            raise ValueError("The impurity matrix must be square.")
+        if np.isnan(impurity_matrix).any():
+            raise ValueError("The impurity matrix contains NaN values.")
+        self._impurity_matrix = impurity_matrix
+        return self
+
+    def is_fitted(self) -> bool:
+        """Returns True if the IsotopeImpurityCorrecter has been fitted."""
+        return self._impurity_matrix is not None
+
+    def get_fits(self) -> np.array:
+        """Returns a copy of the fitted impurity matrix.
+
+        returns:
+            A numpy array representing a diagonal impurity matrix.
+        """
+        if not self.is_fitted():
+            raise NotFittedError("The IsotopeImpurityCorrecter has not been fitted.")
+        return self._impurity_matrix.copy()
+
+    def transform(self, table: pd.DataFrame) -> pd.DataFrame:
+        """Applies isotope impurity correction to the values of the table.
+
+        Args:
+            table: The data to normalize. The columns of the table must correspond to
+                the channels of the impurity matrix used for fitting.
+
+        Returns:
+            A copy of the table with isotope impurity corrected values.
+        """
+        if not self.is_fitted():
+            raise NotFittedError("The IsotopeImpurityCorrecter has not been fitted.")
+        if table.shape[1] != self.get_fits().shape[1]:
+            raise ValueError(
+                "The number of columns in the table does not match the number "
+                "of channels in the impurity matrix."
+            )
+
+        corrected_values = correct_isobaric_reporter_impurities(
+            intensity_table=table.to_numpy(),
+            diagonal_impurity_matrix=self._impurity_matrix,
+        )
+        corrected_table = table.copy()
+        corrected_table[:] = corrected_values
+        return corrected_table
+
+
+def correct_isobaric_reporter_impurities(
+    intensity_table: np.array,
+    diagonal_impurity_matrix: np.array,
+) -> np.array:
+    """Performs isotope impurity correction on isobaric reporter expression values.
+
+    Args:
+        intensity_table: A two-dimenstional array with columns corresponding to isobaric
+            reporter channels and rows to measured units such as PSMs, peptides or
+            proteins.
+        diagonal_impurity_matrix: A reporter isotope impurity matrix in a diagonal
+            format, where columns describe the isotope impurity of a specific channel,
+            and the values in each row indicate the percentage of signal from the
+            reporter that is present in each channel.
+    """
+    apply_impurity_correction = functools.partial(
+        _correct_impurity_contamination,
+        impurity_matrix=diagonal_impurity_matrix,
+    )
+
+    data_was_in_logpsace = msreport.helper.intensities_in_logspace(intensity_table)
+
+    if data_was_in_logpsace:
+        intensity_table = np.power(2, intensity_table)
+    intensity_table[np.isnan(intensity_table)] = 0
+    corrected_table = np.apply_along_axis(apply_impurity_correction, 1, intensity_table)
+    corrected_table[corrected_table <= 0] = 0
+    if data_was_in_logpsace:
+        corrected_table = np.log2(corrected_table)
+
+    return corrected_table
+
+
+def _apply_impurity_contamination(
+    intensities: np.array, impurity_matrix: np.array
+) -> np.array:
+    """Applies reporter isotope impurity interference to an intensity array.
+
+    Args:
+        intensities: An array containing non-contaminated isobaric reporter intensities.
+        impurity_matrix: A reporter isotope impurity matrix in a diagonal format, where
+            columns describe the isotope impurity of a specific channel, and the values
+            in each row indicate the percentage of signal from the reporter that is
+            present in each channel. Both dimensions of the impurity matrix must have
+            the same length as the intensity array.
+
+    Returns:
+        An array containing contaminated intensities.
+    """
+    return np.sum(impurity_matrix * intensities, axis=1)
+
+
+def _correct_impurity_contamination(
+    intensities: np.array, impurity_matrix: np.array
+) -> np.array:
+    """Applies reporter isotope impurity interference correction to an intensity array.
+
+    Args:
+        intensities: An array containing isobaric reporter intensities affected by
+            isotope impurity interference.
+        impurity_matrix: A reporter isotope impurity matrix in a diagonal format, where
+            columns describe the isotope impurity of a specific channel, and the values
+            in each row indicate the percentage of signal from the reporter that is
+            present in each channel. Both dimensions of the impurity matrix must have
+            the same length as the intensity array.
+
+    Returns:
+        An array containing impurity corrected intensities.
+    """
+    corrected_intensities, _ = scipy.optimize.nnls(impurity_matrix, intensities)
+    return corrected_intensities