msreport 0.0.24__py3-none-any.whl

msreport/helper/maxlfq.py

@@ -0,0 +1,339 @@
+import itertools
+from typing import Callable
+import warnings
+
+import numpy as np
+
+import msreport.helper
+
+
+def calculate_pairwise_log_ratio_matrix(
+    array: np.ndarray, log_transformed: bool = False
+) -> np.ndarray:
+    """Calculates a pairwise log ratio matrix from an intensity array.
+
+    Args:
+        array: A two-dimensional numpy array, with the first dimension corresponding to
+            rows and the second dimension to columns.
+        log_transformed: If True, the 'array' is expected to contain log transformed
+            intensity values. If False, the array is expected to contain non-transformed
+            intensity values, which are log2 transformed for the calculation of ratios.
+
+    Returns:
+        A 3-dimensional numpy array, containing pair-wise log ratios. The shape of the
+        output array is (n, i, i), where n is the number of rows of the input array and
+        i is the number of columns.
+
+    Example:
+        >>> array = np.array(
+        ...     [
+        ...         [4.0, 4.0, 8.0],
+        ...         [8.0, 9.0, np.nan],
+        ...     ]
+        ... )
+        >>> calculate_pairwise_log_ratio_matrix(array)
+        array([[[ 0.      ,  0.      , -1.      ],
+                [ 0.      ,  0.      , -1.      ],
+                [ 1.      ,  1.      ,  0.      ]],
+        <BLANKLINE>
+               [[ 0.      , -0.169925,       nan],
+                [ 0.169925,  0.      ,       nan],
+                [      nan,       nan,       nan]]])
+    """
+    if np.issubdtype(array.dtype, np.integer):
+        log_array = array.astype(float)
+    else:
+        log_array = array.copy()
+
+    if not log_transformed:
+        log_array[log_array == 0] = np.nan
+        log_array = np.log2(log_array)
+
+    ratio_matrix = log_array[:, :, None] - log_array[:, None, :]
+    ratio_matrix[~np.isfinite(ratio_matrix)] = np.nan
+    return ratio_matrix
+
+
+def calculate_pairwise_median_log_ratio_matrix(
+    array: np.ndarray, log_transformed: bool = False
+) -> np.ndarray:
+    """Calculates a pairwise median log ratio matrix from an intensity array.
+
+    Args:
+        array: A two-dimensional numpy array, with the first dimension corresponding to
+            rows and the second dimension to columns.
+        log_transformed: If True, the 'array' is expected to contain log transformed
+            intensity values. If False, the array is expected to contain non-transformed
+            intensity values, which are log2 transformed for the calculation of ratios.
+
+    Returns:
+        A square 2-dimensional numpy array, containing pair-wise log ratios. The shape
+        of the output array is (i, i), where i is the number of columns of the input
+        array.
+
+    Example:
+        >>> array = np.array(
+        ...     [
+        ...         [4.0, 4.0, 8.0],
+        ...         [8.0, 9.0, np.nan],
+        ...     ]
+        ... )
+        >>> calculate_pairwise_median_log_ratio_matrix(array)
+        array([[ 0.       , -0.0849625, -1.       ],
+               [ 0.0849625,  0.       , -1.       ],
+               [ 1.       ,  1.       ,  0.       ]])
+    """
+    ratio_marix = _calculate_pairwise_centered_log_ratio_matrix(
+        array, np.median, log_transformed=log_transformed
+    )
+    return ratio_marix
+
+
+def calculate_pairwise_mode_log_ratio_matrix(
+    array: np.ndarray, log_transformed: bool = False
+) -> np.ndarray:
+    """Calculates a pairwise mode ratio matrix from an intensity array.
+
+    Args:
+        array: A two-dimensional numpy array, with the first dimension corresponding to
+            rows and the second dimension to columns.
+        log_transformed: If True, the 'array' is expected to contain log transformed
+            intensity values. If False, the array is expected to contain non-transformed
+            intensity values, which are log2 transformed for the calculation of ratios.
+
+    Returns:
+        A square 2-dimensional numpy array, containing pair-wise ratios. The shape of
+        the output array is (i, i), where i is the number of columns of the input array.
+
+    Example:
+        >>> array = np.array(
+        ...     [
+        ...         [4.0, 4.0, 8.0],
+        ...         [8.0, 9.0, np.nan],
+        ...     ]
+        ... )
+        >>> calculate_pairwise_mode_log_ratio_matrix(array)
+        array([[ 0.       , -0.0849625, -1.       ],
+               [ 0.0849625,  0.       , -1.       ],
+               [ 1.       ,  1.       ,  0.       ]])
+    """
+    ratio_marix = _calculate_pairwise_centered_log_ratio_matrix(
+        array, msreport.helper.mode, log_transformed=log_transformed
+    )
+    return ratio_marix
+
+
+def prepare_coefficient_matrix(
+    ratio_matrix: np.ndarray,
+) -> (np.ndarray, np.ndarray, np.ndarray):
+    """Prepares coefficients, ratios, and initial row indices from a log ratio matrix.
+
+    Args:
+        ratio_matrix: A numpy array containing one or multiple pair-wise ratio matrices.
+            Each ratio matrix must be a square array, with a ratio at position (i, j)
+            being calculated from an abundance table as 'column i - column j'. Ratios
+            should have been calculated by row index Only the upper triangular part of
+            the ratio matrix is used to generate the coefficient matrix. If the
+            'ratio_matrix' contains multiple ratio matrices, the shape of the array
+            has to be (n, i, i), where n is the number of ratio matrices and i is the
+            number of rows and columns per ratio matrix. If only one ratio matrix is
+            provided, the shape of the array has to be (i, i).
+
+    Returns:
+        A tuple containing the following three elements:
+        - A coefficent matrix. 2d array with the number of rows corresponding to the
+          first dimension of the 'ratio_matrix' and the number of columns to the second
+          dimension.
+        - Ratios: 1d array containing the ratios from the ratio matrix, each entry
+          corresponds to a row in the coefficent matrix.
+        - Ratio matrix row indices: 1d array containing row indicies that refer to the
+          index of the first dimenstion from the 'ratio_matrix', and thus to row indices
+          from the original table that was used to generate 'the ratio_matrix'. If
+          the 'ratio_matrix' has only 2 dimensions all values are zero.
+
+    Example:
+        >>> ratio_matrix = np.array(
+        ...     [
+        ...         [0.0, -0.1, -1.0],
+        ...         [0.1, 0.0, -1.0],
+        ...         [1.0, 1.0, 0.0],
+        ...     ]
+        ... )
+        >>> prepare_coefficient_matrix(ratio_matrix)
+        (array([[ 1, -1,  0],
+                [ 1,  0, -1],
+                [ 0,  1, -1]]),
+         array([-0.1, -1. , -1. ]),
+         array([0, 0, 0]))
+
+    """
+    if len(ratio_matrix.shape) == 2:
+        result = _coefficients_from_single_row_matrix(ratio_matrix)
+    else:
+        result = _coefficients_from_multi_row_matrix(ratio_matrix)
+    coef_matrix, ratio_array, initial_rows = result
+
+    return coef_matrix, ratio_array, initial_rows
+
+
+def log_profiles_by_lstsq(coef_matrix: np.ndarray, ratio_array: np.ndarray):
+    """Calculates estimated log abundance profiles by least-squares fitting.
+
+    Args:
+        coef_matrix: Two-dimensional numpy array representing the coefficients.
+        ratio_array: One-dimensional numpy array representing the ratios, each entry
+            corresponds to a row in the coefficent matrix.
+
+    Returns:
+        One-dimensional numpy array containing the estimated least-squares profile.
+
+    Example:
+        >>> coef_matrix = np.array(
+        ...     [
+        ...         [1, -1, 0],
+        ...         [1, 0, -1],
+        ...         [0, 1, -1],
+        ...     ]
+        ... )
+        >>> ratio_array = np.array([-0.1, -1.0, -1.0])
+        >>> log_profiles_by_lstsq(coef_matrix, ratio_array)
+        array([-0.36666667, -0.3       ,  0.66666667])
+    """
+    finite_rows = np.isfinite(ratio_array)
+    coef_matrix = coef_matrix[finite_rows]
+    ratio_array = ratio_array[finite_rows]
+
+    absent_coef = np.abs(coef_matrix).sum(axis=0) == 0
+    coef_estimates, resid, rank, s = np.linalg.lstsq(
+        coef_matrix[:, ~absent_coef], ratio_array, rcond=None
+    )
+    log_profile = np.zeros(coef_matrix.shape[1])
+    log_profile[absent_coef] = np.nan
+    log_profile[~absent_coef] = coef_estimates
+    return log_profile
+
+
+def _calculate_pairwise_centered_log_ratio_matrix(
+    array: np.ndarray, center_function: Callable, log_transformed: bool = False
+) -> np.ndarray:
+    """Calculates a pairwise, centered log2 ratio matrix from an intensity array.
+
+    Args:
+        array: A two-dimensional numpy array, with the first dimension corresponding to
+            rows and the second dimension to columns.
+        center_function: Function that is applied to the ratios of each pair-wise
+            comparison of columns in the input array to calculate the centered ratio.
+        log_transformed: If True, the 'array' is expected to contain log transformed
+            intensity values. If False, the array is expected to contain non-transformed
+            intensity values, which are log2 transformed for the calculation of ratios.
+
+    Returns:
+        A square 2-dimensional numpy array, containing pair-wise ratios. The shape of
+        the output array is (i, i), where i is the number of columns of the input array.
+    """
+    # Note: Is currently tested only via the calculate_pairwise_median_log_ratio_matrix
+    #       and calculate_pairwise_mode_log_ratio_matrix functions.
+    if np.issubdtype(array.dtype, np.integer):
+        log_array = array.astype(float)
+    else:
+        log_array = array.copy()
+
+    if not log_transformed:
+        log_array[log_array == 0] = np.nan
+        log_array = np.log2(log_array)
+
+    num_cols = log_array.shape[1]
+    ratio_marix = np.full((num_cols, num_cols), fill_value=np.nan)
+    ratio_marix = np.zeros((num_cols, num_cols))
+    for i, j in itertools.combinations(range(num_cols), 2):
+        ratios = log_array[:, i] - log_array[:, j]
+        with warnings.catch_warnings():
+            warnings.simplefilter("ignore", category=RuntimeWarning)
+            median_ratio = center_function(ratios[np.isfinite(ratios)])
+        ratio_marix[i, j] = median_ratio
+
+    # Generate a full, mirrowed matrix where the lower triangle is upper triangle * -1
+    ratio_marix = ratio_marix - ratio_marix.T - np.diag(np.diag(ratio_marix))
+    return ratio_marix
+
+
+def _coefficients_from_single_row_matrix(ratio_matrix):
+    """Calculates coefficients, ratios, and initial row indices for a single row matrix.
+
+    Args:
+        ratio_matrix: A numpy array containing one single pair-wise ratio matrix. The
+            ratio matrix must be a square array, with a ratio at position (i, j) being
+            calculated from an abundance table as 'column i - column j'. Only the upper
+            triangular part of the ratio matrix is used to generate the coefficient
+            matrix.
+
+    Returns:
+        A tuple containing the following three elements:
+        - A coefficent matrix. 2d array with the number of rows corresponding to the
+          first dimension of the 'ratio_matrix' and the number of columns to the second
+          dimension.
+        - Ratios: 1d array containing the ratios from the ratio matrix, each entry
+          corresponds to a row in the coefficent matrix.
+        - Ratio matrix row indices: 1d array with equal length as the ratios array,
+          containing all zero values. is returned for consistency with the function
+          `_coefficients_from_multi_row_matrix`.
+    """
+    num_coef = ratio_matrix.shape[1]
+    coef_combinations = list(itertools.combinations(range(num_coef), 2))
+    num_coef_combinations = len(coef_combinations)
+
+    coef_matrix = np.zeros((num_coef_combinations, num_coef), dtype=int)
+    ratio_array = np.zeros(num_coef_combinations)
+    idx_ratio_matrix_first_dimension = np.zeros(num_coef_combinations, dtype=int)
+
+    for variable_position, (i, j) in enumerate(coef_combinations):
+        ratio_ij = ratio_matrix[i, j]
+        coef_matrix[variable_position, i] = 1
+        coef_matrix[variable_position, j] = -1
+        ratio_array[variable_position] = ratio_ij
+    return coef_matrix, ratio_array, idx_ratio_matrix_first_dimension
+
+
+def _coefficients_from_multi_row_matrix(ratio_matrix):
+    """Calculates coefficients, ratios, and initial row indices for a multi row matrix.
+
+    Args:
+        ratio_matrix: A numpy array containing multiple pair-wise ratio matrices. Each
+            ratio matrix must be a square array, with a ratio at position (i, j) being
+            calculated from an abundance table as 'column i - column j'. Only the upper
+            triangular part of the ratio matrix is used to generate the coefficient
+            matrix. The shape of 'ratio_matrix' must be(n, i, i), where n is the number
+            of ratio matrices and i is the number of rows and columns per ratio
+            matrix.
+
+    Returns:
+        A tuple containing the following three elements:
+        - A coefficent matrix. 2d array with the number of rows corresponding to the
+          first dimension of the 'ratio_matrix' and the number of columns to the second
+          and third dimension.
+        - Ratios: 1d array containing the ratios from the ratio matrix, each entry
+          corresponds to a row in the coefficent matrix.
+        - Ratio matrix row indices: 1d array containing row indicies that refer to the
+          index of the first dimenstion from the 'ratio_matrix', and thus to row indices
+          from the original table that was used to generate 'the ratio_matrix'.
+    """
+    num_coef = ratio_matrix.shape[1]
+    coef_combinations = list(itertools.combinations(range(num_coef), 2))
+    num_coef_combinations = len(coef_combinations)
+    num_matrices = ratio_matrix.shape[0]
+    coef_matrix_rows = num_coef_combinations * num_matrices
+
+    coef_matrix = np.zeros((coef_matrix_rows, num_coef), dtype=int)
+    ratio_array = np.zeros(coef_matrix_rows)
+    idx_ratio_matrix_first_dimension = np.zeros(coef_matrix_rows, dtype=int)
+
+    for matrix_position, matrix in enumerate(ratio_matrix):
+        for variable_position, (i, j) in enumerate(coef_combinations):
+            position = (matrix_position * num_coef_combinations) + variable_position
+            ratio_ij = matrix[i, j]
+            coef_matrix[position, i] = 1
+            coef_matrix[position, j] = -1
+            ratio_array[position] = ratio_ij
+            idx_ratio_matrix_first_dimension[position] = matrix_position
+
+    return coef_matrix, ratio_array, idx_ratio_matrix_first_dimension

msreport/helper/table.py

@@ -0,0 +1,267 @@
+import re
+from typing import Iterable, Union
+
+import numpy as np
+import pandas as pd
+
+
+def guess_design(table: pd.DataFrame, tag: str) -> pd.DataFrame:
+    """Extracts sample name, experiment, and replicate from specified sample columns.
+
+    "Total" and "Combined", and their lower case variants, are not allowed as sample
+    names and will be ignored.
+
+    First a subset of columns containing a column tag are identified. Then sample names
+    are extracted by removing the column tag from each column name. And finally, sample
+    names are split into experiment and replicate at the last underscore.
+
+    This requires that the naming of samples follows a specific convention. Sample names
+    must begin with the experiment name, followed by an underscore and a unique
+    identifier of the sample, for example the replicate number. The experiment name can
+    also contain underscores, as it is split only by the last underscore.
+
+    For example "ExpA_r1" would be split into experiment "ExpA" and replicate "r1",
+    "Exp_A_1" would be experiment "Exp_A" and replicate "1".
+
+    Args:
+        table: Dataframe which columns are used for extracting sample names.
+        tag: Column names containing the 'tag' are selected for sample extraction.
+
+    Returns:
+        A dataframe containing the columns "Sample", "Experiment", and "Replicate"
+    """
+    sample_entries = []
+    for column in find_columns(table, tag, must_be_substring=True):
+        sample = column.replace(tag, "").strip()
+        if sample.lower() in ["total", "combined"]:
+            continue
+        experiment = "_".join(sample.split("_")[:-1])
+        experiment = experiment if experiment else sample
+        replicate = sample.split("_")[-1]
+        replicate = replicate if replicate is not sample else "-1"
+        sample_entries.append([sample, experiment, replicate])
+    design = pd.DataFrame(sample_entries, columns=["Sample", "Experiment", "Replicate"])
+    return design
+
+
+def intensities_in_logspace(data: Union[pd.DataFrame, np.ndarray, Iterable]) -> bool:
+    """Evaluates whether intensities are likely to be log transformed.
+
+    Assumes that intensities are log transformed if all values are smaller or equal to
+    64. Intensities values (and intensity peak areas) reported by tandem mass
+    spectrometry typically range from 10^3 to 10^12. To reach log2 transformed values
+    greater than 64, intensities would need to be higher than 10^19, which seems to be
+    very unlikely to be ever encountered.
+
+    Args:
+        data: Dataset that contains only intensity values, can be any iterable,
+            a numpy.array or a pandas.DataFrame, multiple dimensions or columns
+            are allowed.
+
+    Returns:
+        True if intensity values in 'data' appear to be log transformed.
+    """
+    data = np.array(data, dtype=float)
+    mask = np.isfinite(data)
+    return np.all(data[mask].flatten() <= 64)
+
+
+def rename_sample_columns(table: pd.DataFrame, mapping: dict[str, str]) -> pd.DataFrame:
+    """Renames sample names according to the mapping in a cautious manner.
+
+    In general, this function allows the use of 'mapping' with keys that are substrings
+    of any other keys, as well as values that are substrings of any of the keys.
+
+    Importantly, if the mapping keys (sample names) are substrings of other column names
+    within the table, unintended renaming of those columns will occur. For instance,
+    when renaming columns ["Abundance", "Intensity A"] with the mapping
+    {"A": "Sample Alpha"}, the columns will be renamed to ["Sample Alphabundance",
+    "Intensity Sample Alpha"].
+
+    Args:
+        table: Dataframe which columns will be renamed.
+        mapping: A mapping of old to new sample names that will be used to replace
+            matching substrings in the columns from table.
+
+    Returns:
+        A copy of the table with renamed columns.
+    """
+    sorted_mapping_keys = sorted(mapping, key=len, reverse=True)
+
+    renamed_columns = []
+    for column in table.columns:
+        for sample_name in sorted_mapping_keys:
+            if sample_name in column:
+                column = column.replace(sample_name, mapping[sample_name])
+                break
+        renamed_columns.append(column)
+
+    renamed_table = table.copy()
+    renamed_table.columns = renamed_columns
+    return renamed_table
+
+
+def rename_mq_reporter_channels(
+    table: pd.DataFrame, channel_names: Iterable[str]
+) -> None:
+    """Renames reporter channel numbers with sample names.
+
+    MaxQuant writes reporter channel names either in the format "Reporter intensity 1"
+    or "Reporter intensity 1 Experiment Name", dependent on whether an experiment name
+    was specified. Renames "Reporter intensity", "Reporter intensity count", and
+    "Reporter intensity corrected" columns.
+
+    NOTE: This might not work for the peptides.txt table, as there are columns present
+    with the experiment name and also without it.
+    """
+    pattern = re.compile("Reporter intensity [0-9]+")
+    reporter_columns = list(filter(pattern.match, table.columns.tolist()))
+    assert len(reporter_columns) == len(channel_names)
+
+    column_mapping = {}
+    base_name = "Reporter intensity "
+    for column, channel_name in zip(reporter_columns, channel_names):
+        for tag in ["", "count ", "corrected "]:
+            old_column = column.replace(f"{base_name}", f"{base_name}{tag}")
+            new_column = f"{base_name}{tag}{channel_name}"
+            column_mapping[old_column] = new_column
+    table.rename(columns=column_mapping, inplace=True)
+
+
+def apply_intensity_cutoff(
+    table: pd.DataFrame, column_tag: str, threshold: float
+) -> None:
+    """Sets values below the threshold to NA.
+
+    Args:
+        table: Dataframe to which the protein annotations are added.
+        column_tag: Substring used to identify intensity columns from the 'table' to
+            which the intensity cutoff is applied.
+        threshold: Values below the treshold will be set to NA.
+    """
+    for column in find_columns(table, column_tag):
+        table.loc[table[column] < threshold, column] = np.nan
+
+
+def find_columns(
+    table: pd.DataFrame, substring: str, must_be_substring: bool = False
+) -> list[str]:
+    """Returns a list column names containing the substring.
+
+    Args:
+        table: Columns of this datafram are queried.
+        substring: String that must be part of column names.
+        must_be_substring: If true than column names are not reported if they
+            are exactly equal to the substring.
+
+    Returns:
+        A list of column names.
+    """
+    matches = [substring in col for col in table.columns]
+    matched_columns = np.array(table.columns)[matches].tolist()
+    if must_be_substring:
+        matched_columns = [col for col in matched_columns if col != substring]
+    return matched_columns
+
+
+def find_sample_columns(
+    table: pd.DataFrame, substring: str, samples: Iterable[str]
+) -> list[str]:
+    """Returns column names that contain the substring and any entry of 'samples'.
+
+    Args:
+        table: Columns of this dataframe are queried.
+        substring: String that must be part of column names.
+        samples: List of strings from which at least one must be present in matched
+            columns.
+
+    Returns:
+        A list of sample column names.
+    """
+    matched_columns = []
+    for column in find_columns(table, substring):
+        if any([sample in column for sample in samples]):
+            matched_columns.append(column)
+    return matched_columns
+
+
+def keep_rows_by_partial_match(
+    table: pd.DataFrame, column: str, values: Iterable[str]
+) -> pd.DataFrame:
+    """Filter a table to keep only rows partially matching any of the specified values.
+
+    Args:
+        table: The input table that will be filtered.
+        column: The name of the column in the 'table' which entries are checked for
+            partial matches to the values. This column must have the datatype 'str'.
+        modifications: An iterable of strings that are used to filter the table. Any of
+            the specified values must have at least a partial match to an entry from the
+            specified 'column' for a row to be kept in the filtered table.
+
+    Returns:
+        A new DataFrame containing only the rows that have a partial or complete match
+        with any of the specified 'values'.
+
+    Example:
+        >>> df = pd.DataFrame({"Modifications": ["phos", "acetyl;phos", "acetyl"]})
+        >>> keep_rows_by_partial_match(df, "Modifications", ["phos"])
+          Modifications
+        0          phos
+        1   acetyl;phos
+    """
+    value_masks = [table[column].str.contains(value, regex=False) for value in values]
+    target_mask = np.any(value_masks, axis=0)
+    filtered_table = table[target_mask].copy()
+    return filtered_table
+
+
+def remove_rows_by_partial_match(
+    table: pd.DataFrame, column: str, values: Iterable[str]
+) -> pd.DataFrame:
+    """Filter a table to remove rows partially matching any of the specified values.
+
+    Args:
+        table: The input table that will be filtered.
+        column: The name of the column in the 'table' which entries are checked for
+            partial matches to the values. This column must have the datatype 'str'.
+        modifications: An iterable of strings that are used to filter the table. Any of
+            the specified values must have at least a partial match to an entry from the
+            specified 'column' for a row to be removed in the filtered table.
+
+    Returns:
+        A new DataFrame containing no rows that have a partial or complete match with
+        any of the specified 'values'.
+
+    Example:
+        >>> df = pd.DataFrame({"Modifications": ["phos", "acetyl;phos", "acetyl"]})
+        >>> remove_rows_by_partial_match(df, "Modifications", ["phos"])
+          Modifications
+        2        acetyl
+    """
+    value_masks = [table[column].str.contains(value, regex=False) for value in values]
+    target_mask = ~np.any(value_masks, axis=0)
+    filtered_table = table[target_mask].copy()
+    return filtered_table
+
+
+def join_tables(
+    tables: Iterable[pd.DataFrame], reset_index: bool = False
+) -> pd.DataFrame:
+    """Returns a joined dataframe.
+
+    Dataframes are merged iteratively on their index using an outer join, beginning with
+    the first entry from 'tables'. Can only join dataframes with different columns.
+
+    Args:
+        tables: Dataframes that will be merged together.
+        reset_index: If True, the index of the joined dataframe is reset.
+
+    Returns:
+        A merged dataframe.
+    """
+    merged_table = tables[0]
+    for table in tables[1:]:
+        merged_table = merged_table.join(table, how="outer")
+    if reset_index:
+        merged_table.reset_index(inplace=True)
+    return merged_table