flippr 0.1.1__py3-none-any.whl

flippr/__about__.py

@@ -0,0 +1 @@
+__version__ = "0.1.1"

flippr/__init__.py

@@ -0,0 +1,172 @@
+from functools import cached_property
+from pathlib import Path
+
+import polars as pl
+
+from . import spr as _spr
+from . import validate as _validate
+from .parameters import rcParams
+from .uniprot import fasta as _fasta
+
+
+class Study:
+    """
+    A FLiPPR Study is used to coordinate Limited Proteolysis (LiP) data processing for a single experiment analyzed with FragPipe.
+    Studies can contain LiP data alone or LiP and TrP data; with the inclusion of a FASTA file for automatic metadata generation.
+    TrP data should result from the same experimental conditions as the LiP data, but without including a broad-spectrum protease like Proteinase K (PK).
+
+    Args:
+        lip (str | Path): Directory or path to the FragPipe LFQ output data for Limited Proteolysis (LiP) experiment data.
+        trp (str | Path, optional): Directory or path to the FragPipe LFQ output data for Trypsin Only (TrP) experiment data. Defaults to None.
+        fasta (str | Path, optional): Path to the FASTA file containing the same protein sequences used in the LiP/TrP experiments. Defaults to None.
+        method (str): Method used to quantify ion intensities in FragPipe. `lfq` - Label-Free Quantification, `silac` - Stable Isotope Labelling (currently not incorporated). Defaults to `lfq`.
+
+    Examples:
+        Analysis of a single dataset
+        >>> flippr.Study(lip = "PXD025926/FragPipe/LiP_LFQ")
+
+        Analysis of a single dataset with metadata integration
+        >>> flippr.Study(lip = "PXD025926/FragPipe/LiP_LFQ", fasta = "UP000000625.fasta")
+
+        Including protein-level normalization from trypsin-only data
+        >>> flippr.Study(lip = "PXD025926/FragPipe/LiP_LFQ", trp = "PXD025926/FragPipe/TrP_LFQ")
+
+    """
+
+    def __init__(self, lip: str | Path, trp: str | Path | None = None, fasta: str | Path | None = None, method: str = "lfq") -> None:
+
+        _lip, _trp, _fasta_path, _method = _validate._validate_study(lip, trp, fasta, method)
+
+        self.lip: Path = _lip
+        self.trp: Path | None = _trp
+        self._fasta_path: Path | None = _fasta_path
+        self.method: str = _method
+
+        self._pid: int = 0
+        self.processes: dict = dict()
+        self.results: dict = dict()
+
+    @property
+    def samples(self) -> dict:
+        """
+        Returns the names of the samples or experimental annotations found in the FragPipe outputs for LiP and TrP (if include) datasets.
+
+        Examples:
+            Including only LiP data
+            >>> e_coli_refolding = flippr.Study(lip = "PXD025926/FragPipe/LiP_LFQ")
+            >>> print(e_coli_refolding.samples)
+            {"LiP": ("Native", "Refolded_01_min", "Refolded_05_min", "Refolded_30_min")}
+
+            Including LiP and TrP data
+            >>> e_coli_refolding = flippr.Study(lip = "PXD025926/FragPipe/LiP_LFQ", trp = "PXD025926/FragPipe/TrP_LFQ")
+            >>> print(e_coli_refolding.samples)
+            {"LiP": ("Native", "Refolded_01_min", "Refolded_05_min", "Refolded_30_min"),
+             "TrP": ("Native", "Refolded")}
+
+        """
+
+        if self.trp is not None:
+            return {"LiP": self.lip_samples, "TrP": self.trp_samples}
+
+        return {"LiP": self.lip_samples}
+
+    @property
+    def lip_samples(self) -> set:
+        """
+        Returns the names of the samples or experimental annotations found in the FragPipe outputs for LiP datasets.
+
+        """
+
+        return self.__read_annotation(self.lip)
+
+    @property
+    def trp_samples(self) -> set:
+        """
+        Returns the names of the samples or experimental annotations found in the FragPipe outputs for TrP datasets.
+
+        """
+
+        return self.__read_annotation(self.trp)
+
+    @cached_property
+    def fasta(self) -> pl.DataFrame | None:
+        """
+        Returns a three column dataframe containing Protein IDs, Sequences, and Valid ID if the Protein ID is interpretable as an official Uniprot ID.
+
+        """
+        if self._fasta_path is not None:
+            return _fasta._read_fasta(self._fasta_path)
+
+        return None
+
+    def add_process(
+        self, pid: object | None, lip_ctrl: str, lip_test: str, n_rep: int, trp_ctrl: str | None = None, trp_test: str | None = None, trp_n_rep: int | None = None) -> None:
+        """
+        Adding a process to calculate the fold-change between test and control conditions.
+        Normalization is optional and must include a TrP experiment in the `Study` set-up.
+
+        Args:
+            pid (Any): Process ID used to index the `Study().results` dictionary after running `Study().run()`.
+            lip_ctrl (str): Control condition sample name from the LiP experiment.
+            lip_test (str): Test condition sample name from the LiP experiment.
+            n_rep (int): Number of replicates in the LiP experiment.
+            trp_ctrl (str, optional): Control condition sample name from the TrP experiment.
+            trp_test (str, optional): Test condition sample name from the TrP experiment.
+            trp_n_rep (int, optional): Number of replicates in the TrP experiment.
+
+        Examples:
+            Simple fold-change calculation between two conditions
+            >>> study.add_process("sample", "WT", "Drug", 3)
+
+            Fold-change calculation with normalization
+            >>> study.add_process("sample", "WT", "Drug", 3, "WT_TrP", "DMSO_TrP", 3)
+
+            Add multiple processes to the same study
+            >>> study.add_process("cond_1", "WT", "Cond1", 5)
+            >>> study.add_process("cond_2", "WT", "Cond2", 5, "WT_TrP", "DMSO_TrP", 5)
+        """
+
+        if pid is None:
+            pid = self._pid
+            self._pid += 1
+
+        self.processes.update(
+            {
+                pid: _spr.Process(
+                    self.fasta,
+                    self.lip,
+                    self.trp,
+                    pid,
+                    lip_ctrl,
+                    lip_test,
+                    n_rep,
+                    trp_ctrl,
+                    trp_test,
+                    trp_n_rep,
+                )
+            }
+        )
+
+    def run(self) -> dict[object: _spr.Result]:
+        """
+        Run the processes added to the study.
+        Study parameters can be changed by editing the `flippr.rcParams` dictionary.
+        """
+
+        self.results = {pid: proc.run(rcParams) for pid, proc in self.processes.items()}
+
+        return self.results
+
+    def __read_annotation(self, liptrp: Path) -> set:
+        def __strip_fragpipe_repilicate(sample: str) -> str:
+            return "_".join([_ for _ in sample.split("_")[:-1]])
+
+        annotation = liptrp.joinpath("experiment_annotation.tsv")
+
+        annotation_df = pl.read_csv(annotation, separator="\t")
+
+        annotation_dict = annotation_df.select(pl.col("sample")).to_dict(
+            as_series=False
+        )
+
+        return set(__strip_fragpipe_repilicate(sample) for sample in annotation_dict["sample"])

flippr/combine.py

@@ -0,0 +1,107 @@
+import numpy as np
+import polars as pl
+import scipy as sp
+
+from .functions import _log2, _log10
+from .parameters import _FLIPPR_COMBINE_KEY
+
+COMB_NAME_COLUMN = {
+    "CUT SITE": "Cut Site ID",
+    "PEPTIDE": "Peptide Sequence",
+    "MODIFIED PEPTIDE": "Modified Sequence",
+}
+
+def combine_by(df: pl.DataFrame, by: str, fc: str) -> pl.DataFrame:
+
+    combined = (
+        df.group_by(by=["Protein ID", COMB_NAME_COLUMN[by]], maintain_order=True)
+        .agg(
+            pl.col(_FLIPPR_COMBINE_KEY[by]).first(),
+            pl.col(["P-value", "Adj. P-value", "CV", fc])
+            .filter(
+                pl.col("T-test").sign() == pl.col("T-test").sign().sum().sign()
+            )
+        )
+        .with_columns(
+            pl.when(pl.col("P-value").list.len() > 0)
+            .then(pl.col("P-value"))
+            .otherwise([1.0])
+            .alias("P-value"),
+            pl.when(pl.col("Adj. P-value").list.len() > 0)
+            .then(pl.col("Adj. P-value"))
+            .otherwise([1.0])
+            .alias("Adj. P-value"),
+            pl.when(pl.col("CV").list.len() > 0)
+            .then(pl.col("CV"))
+            .otherwise([0.0])
+            .alias("CV"),
+            pl.when(pl.col(fc).list.len() > 0)
+            .then(pl.col(fc))
+            .otherwise([0.0])
+            .alias(fc)
+        )
+        .with_columns(
+            pl.col("P-value")
+            .map_elements(lambda x: sp.stats.combine_pvalues(x)[1], return_dtype=pl.Float64)
+            .alias("P-value"),
+            pl.col("Adj. P-value")
+            .map_elements(lambda x: sp.stats.combine_pvalues(x)[1], return_dtype=pl.Float64)
+            .alias("Adj. P-value"),
+            pl.col("CV")
+            .map_elements(lambda x: np.nanmax(x), return_dtype=pl.Float64)
+            .alias("CV"),
+            pl.col(fc)
+            .map_elements(lambda x: np.nanmedian(x), return_dtype=pl.Float64)
+            .alias(fc)
+        )
+    )
+
+    combined = _log2(combined, fc)
+    combined = _log10(combined, "P-value")
+    combined = _log10(combined, "Adj. P-value")
+
+    return combined
+
+
+def summary_by(df: pl.DataFrame, by: str, fc: str) -> pl.DataFrame:
+    val = (
+        df.group_by(by="Protein ID", maintain_order=True)
+        .agg(pl.col("CV").filter(pl.col("-Log10 P-value") > 0).len())
+        .rename({"CV": f"No. of Valid {by}"})
+    )
+
+    sig = (
+        df.group_by(by="Protein ID", maintain_order=True)
+        .agg(
+            pl.col("CV")
+            .filter(
+                (
+                    (pl.col(f"Log2 {fc}").abs() >= 1)
+                    & (pl.col("-Log10 P-value") >= -np.log10(0.01))
+                )
+                | (
+                    (pl.col(f"Log2 {fc}").abs() >= 6)
+                    & (pl.col("-Log10 P-value") >= 1.8)
+                )
+            )
+            .len()
+        )
+        .rename({"CV": f"No. of Significant {by} (P-value)"})
+    )
+
+    sigsig = (
+        df.group_by(by="Protein ID", maintain_order=True)
+        .agg(
+            pl.col("CV")
+            .filter(
+
+                    (pl.col(f"Log2 {fc}").abs() >= 1)
+                    & (pl.col("-Log10 Adj. P-value") >= -np.log10(0.05))
+
+            )
+            .len()
+        )
+        .rename({"CV": f"No. of Significant {by} (Adj. P-value)"})
+    )
+
+    return val.join(sig, on="Protein ID").join(sigsig, on="Protein ID")

flippr/functions.py

@@ -0,0 +1,289 @@
+import numpy as np
+import polars as pl
+import scipy as sp
+
+
+def _cull_intensities(df: pl.DataFrame,
+                      ctrl_name: str,  test_name: str,
+                      ctrl_ints: list[str],  test_ints: list[str],
+                      n_rep: int,
+                      rcParams: dict, **kwargs) -> pl.DataFrame:
+
+    max_missing = rcParams.get("ion.missing_intensity_thresh", 1)
+
+    df = \
+    df.with_columns(# Count the number of zeros intensity replicates
+        pl.concat_list(ctrl_ints).list.count_matches(0).alias(f"{ctrl_name} ZC"),
+        pl.concat_list(test_ints).list.count_matches(0).alias(f"{test_name} ZC"),
+    ).filter(# Cull based on zero count (ZC)
+        (pl.col(f"{ctrl_name} ZC").le(max_missing) & pl.col(f"{test_name} ZC").eq(0))
+        | (pl.col(f"{ctrl_name} ZC").eq(0)           & pl.col(f"{test_name} ZC").le(max_missing))
+        | (pl.col(f"{ctrl_name} ZC").eq(n_rep)       & pl.col(f"{test_name} ZC").eq(0))
+        | (pl.col(f"{ctrl_name} ZC").eq(0)           & pl.col(f"{test_name} ZC").eq(n_rep))
+    ).with_columns(# Replace zero values remaining with NaN
+        pl.col(ctrl_ints).replace(0.0, float("nan")),
+        pl.col(test_ints).replace(0.0, float("nan"))
+    )
+
+    return df
+
+
+def _add_alt_hypothesis(df: pl.DataFrame,
+                        ctrl_name: str,  test_name: str,
+                        n_rep: int,
+                        rcParams: dict, **kwargs) -> pl.DataFrame:
+
+    df = \
+    df.with_columns(# Add alternative hypothesis
+        pl.when(pl.col(f"{ctrl_name} ZC").eq(n_rep) & pl.col(f"{test_name} ZC").eq(0))
+        .then(pl.lit("greater"))
+        .when(pl.col(f"{ctrl_name} ZC").eq(0) & pl.col(f"{test_name} ZC").eq(n_rep))
+        .then(pl.lit("less"))
+        .otherwise(pl.lit("two-sided"))
+        .alias("Alternative Hypothesis")
+    )
+
+    return df
+
+
+def _impute_aon_intensities(df: pl.DataFrame,
+                            ctrl_name: str,  test_name: str,
+                            ctrl_ints: list[str],  test_ints: list[str],
+                            n_rep: int,
+                            rcParams: dict, **kwargs) -> pl.DataFrame:
+
+
+    # Add imputation variables
+    loc = rcParams.get("ion.aon_impute_loc", 1e4)
+    scale = rcParams.get("ion.aon_impute_scale", 1e4)
+    imp_df = pl.from_numpy(np.random.normal(loc=loc, scale=scale, size=(df.height, n_rep)), schema=["IMP"])
+    df = df.hstack(imp_df)
+
+    df = \
+    df.with_columns(# Impute only on AON ions in control conditions
+        pl.when(pl.col(f"{ctrl_name} ZC").eq(n_rep) & pl.col(f"{test_name} ZC").eq(0))
+        .then(pl.concat_list("IMP"))
+        .otherwise(pl.concat_list(ctrl_ints))
+        .alias(f"{ctrl_name} Intensity"),
+        # Impute only on AON ions in test conditions
+        pl.when(pl.col(f"{ctrl_name} ZC").eq(0) & pl.col(f"{test_name} ZC").eq(n_rep))
+        .then(pl.concat_list("IMP"))
+        .otherwise(pl.concat_list(test_ints))
+        .alias(f"{test_name} Intensity")
+    ).with_columns(# Seperate out imputation (if perfromed) vars for control conditions
+        pl.col(f"{ctrl_name} Intensity").list.get(i).alias(col) for i, col in enumerate(ctrl_ints)
+    ).with_columns(# Seperate out imputation (if perfromed) vars for test conditions
+        pl.col(f"{test_name} Intensity").list.get(i).alias(col) for i, col in enumerate(test_ints)
+    ).with_columns(# Drop NaNs for further computations, this column will be droped down-stream
+        pl.col(f"{ctrl_name} Intensity").list.eval(pl.element().drop_nans()).alias(f"{ctrl_name} Intensity"),
+        pl.col(f"{test_name} Intensity").list.eval(pl.element().drop_nans()).alias(f"{test_name} Intensity")
+    ).drop(["IMP", f"{ctrl_name} ZC", f"{test_name} ZC"])
+
+    return df
+
+
+def _add_ttest(df: pl.DataFrame,
+               ctrl_name: str,  test_name: str,
+               n_rep: int,
+               rcParams: dict, **kwargs) -> pl.DataFrame:
+
+    df = \
+    df.with_columns(# Prepare the descriptive stats for `.ttest_ind_from_stats()`
+        pl.col(f"{ctrl_name} Intensity").list.mean().alias(f"{ctrl_name} Mean"),
+        pl.col(f"{ctrl_name} Intensity").list.std().alias(f"{ctrl_name} Std"),
+
+        pl.col(f"{test_name} Intensity").list.mean().alias(f"{test_name} Mean"),
+        pl.col(f"{test_name} Intensity").list.std().alias(f"{test_name} Std"),
+    ).with_columns(
+        pl.struct(# Create struct with `.ttest_ind_from_stats()` var names
+            mean1=pl.col(f"{ctrl_name} Mean"),
+            std1=pl.col(f"{ctrl_name} Std"),
+            nobs1=n_rep,
+
+            mean2=pl.col(f"{test_name} Mean"),
+            std2=pl.col(f"{test_name} Std"),
+            nobs2=n_rep,
+            alternative=pl.col("Alternative Hypothesis")
+        ).map_elements(# Perform T-test, slow step
+            lambda x: sp.stats.ttest_ind_from_stats(**x, equal_var=False),
+            return_dtype=pl.List(pl.Float64)
+        ).alias("Stats")
+    ).with_columns(# Seperate out T-test vars
+        pl.col("Stats").list.first().alias("T-test"),
+        pl.col("Stats").list.last().alias("P-value"),
+    ).drop(["Stats", f"{ctrl_name} Intensity", f"{test_name} Intensity"])
+
+    return df
+
+
+def _add_fdr(df: pl.DataFrame, rcParams: dict, **kwargs) -> pl.DataFrame:
+
+    # Sort on P-value
+    df = df.sort(by=["Protein ID", "P-value"], descending=[False, False])
+
+    df = \
+    df.hstack(
+        df.group_by(by="Protein ID", maintain_order=True)
+        .agg(# Calculate Adj. P-value
+            pl.map_groups(
+                exprs="P-value",
+                function=lambda x: sp.stats.false_discovery_control(x[0]),
+                return_dtype=pl.List(pl.Float64)
+            ).alias("Adj. P-value"),
+        )# Add Adj. P-value to the original `DataFrame`
+        .explode(pl.col("Adj. P-value"))
+        .select(pl.col("Adj. P-value"))
+    )
+
+    return df
+
+
+def _add_ratio(df: pl.DataFrame,
+               ctrl_name: str,  test_name: str,
+               rcParams: dict, **kwargs) -> pl.DataFrame:
+
+    df = \
+    df.with_columns(# Calculate FC and CV
+        (pl.col(f"{test_name} Mean").mean() / pl.col(f"{ctrl_name} Mean")).alias("FC"),
+        (pl.col(f"{test_name} Std").mean() / pl.col(f"{test_name} Mean")).alias("CV")
+    ).drop([f"{ctrl_name} Mean", f"{ctrl_name} Std", f"{test_name} Mean", f"{test_name} Std"])
+
+    return df
+
+
+def _normalize_ratios(df: pl.DataFrame, trp_norm: pl.DataFrame, rcParams: dict, **kwargs) -> pl.DataFrame:
+
+    trp_prot_fc = rcParams.get("trp_protein.fc_sig_tresh", 1.0)
+    trp_prot_pval = rcParams.get("trp_protein.pval_sig_tresh", 0.01)
+
+    trp_norm = trp_norm.select(pl.col("Protein ID", "P-value", "FC"))
+    trp_norm = trp_norm.select(# Select only the significantly different proteins
+        pl.col("Protein ID"),
+        pl.when(pl.col("P-value").le(trp_prot_pval) & pl.col("FC").log(base=2).abs().ge(trp_prot_fc))
+        .then(pl.col("FC"))
+        .otherwise(pl.lit(0.0))
+        .alias("Normalization Factor")
+    )
+
+    df = df.join(trp_norm, on="Protein ID", how="left")
+
+    df = df.with_columns(# Apply normalization
+        pl.col("Normalization Factor").fill_null(strategy="zero"),
+        pl.when(pl.col("Normalization Factor").gt(0))
+        .then(pl.col("FC") / pl.col("Normalization Factor"))
+        .otherwise(pl.col("FC"))
+        .alias("Normalized FC")
+    )
+
+    return df
+
+
+def _add_start_end_aa(df: pl.DataFrame, rcParams: dict, **kwargs) -> pl.DataFrame:
+
+    df = \
+    df.with_columns(# Parse the Starting and Ending AA of the peptide
+        pl.col("Peptide Sequence").str.head(1).alias("Start AA"),
+        pl.col("Peptide Sequence").str.tail(1).alias("End AA"),
+    )
+
+    return df
+
+
+def _add_half_trpytic(df: pl.DataFrame, rcParams: dict, **kwargs) -> pl.DataFrame:
+
+    df = \
+    df.with_columns(
+        pl.when(# [K/R/-].~~~~~(K/R).[X]
+            pl.col("Prev AA").is_in(["K", "R", "-"])
+            & pl.col("End AA").is_in(["K", "R"])
+            & ~pl.col("Next AA").is_in(["-"]))
+        .then(pl.lit("FULL_TRP"))
+        .when(# [K/R/-].~~~~~(X).[-]
+            pl.col("Prev AA").is_in(["K", "R"])
+            & pl.col("Next AA").is_in(["-"]))
+        .then(pl.lit("FULL_TRP"))
+        .when(# [M].2~~~~~(K/R).[X]
+            pl.col("Prev AA").is_in(["M"])
+            & pl.col("Start").eq(2)
+            & pl.col("End AA").is_in(["K", "R"]))
+        .then(pl.lit("FULL_TRP"))
+        .when(# [K/R/-].~~~~~(X).[X]
+            pl.col("Prev AA").is_in(["K", "R", "-"])
+            & ~pl.col("End AA").is_in(["K", "R"])
+            & ~pl.col("Next AA").is_in(["-"]))
+        .then(pl.lit("C_SEMI"))
+        .when(# [M].2~~~~~(X).[X]
+            pl.col("Prev AA").is_in(["M"])
+            & pl.col("Start").eq(2)
+            & ~pl.col("End AA").is_in(["K", "R"]))
+        .then(pl.lit("C_SEMI"))
+        .when(# [X].~~~~~(K/R).[X]
+            ~pl.col("Prev AA").is_in(["K", "R", "-"])
+            & pl.col("End AA").is_in(["K", "R"])
+            & ~pl.col("Next AA").is_in(["-"]))
+        .then(pl.lit("N_SEMI"))
+        .when(# [X].~~~~~(X).[-]
+            ~pl.col("Prev AA").is_in(["K", "R", "-"])
+            & pl.col("Next AA").is_in(["-"]))
+        .then(pl.lit("N_SEMI"))
+        .otherwise(pl.lit(None))
+        .alias("Cleavage Type")
+    ).filter(# Filter out over-digested peptides
+        ~pl.col("Cleavage Type").is_null()
+    ).with_columns(# Fill in `Half Tryptic`
+        pl.col("Cleavage Type").ne("FULL_TRP").alias("Half Tryptic")
+    )
+
+    return df
+
+
+def _add_cut_sites(df: pl.DataFrame, rcParams: dict, **kwargs) -> pl.DataFrame:
+
+    df = \
+    df.with_columns(# Adding unique identifier for all `Cleavage Type`
+        pl.when(pl.col("Cleavage Type").eq("C_SEMI"))
+        .then(pl.format("{}{}", pl.col("Next AA"), pl.col("End") + 1))
+        .when(pl.col("Cleavage Type").eq("N_SEMI"))
+        .then(pl.format("{}{}", pl.col("Start AA"), pl.col("Start")))
+        .when((pl.col("Cleavage Type").eq("FULL_TRP")) & (pl.col("Prev AA").ne("-")))
+        .then(
+            pl.format(
+                "{}{}-{}{}",
+                pl.col("Prev AA"),
+                pl.col("Start") - 1,
+                pl.col("End AA"),
+                pl.col("End"),
+            )
+        )
+        .when((pl.col("Cleavage Type").eq("FULL_TRP")) & (pl.col("Prev AA").eq("-")))
+        .then(
+            pl.format(
+                "{}{}-{}{}",
+                pl.col("Start AA"),
+                pl.col("Start"),
+                pl.col("End AA"),
+                pl.col("End"),
+            )
+        )
+        .alias("Cut Site")
+    ).with_columns(
+        pl.format("{}_{}", pl.col("Protein ID"), pl.col("Cut Site")).alias("Cut Site ID")
+    )
+
+    return df
+
+
+def _log2(df: pl.DataFrame, col: str) -> pl.DataFrame:
+
+    df = df.with_columns(
+        pl.when(pl.col(col).eq(0))
+        .then(0.0)
+        .otherwise(pl.col(col).log(base=2))
+        .alias(f"Log2 {col}")
+    )
+
+    return df
+
+
+def _log10(df: pl.DataFrame, col: str) -> pl.DataFrame:
+    return df.with_columns(-pl.col(col).log10().alias(f"-Log10 {col}"))