Metadata-Version: 2.4
Name: phospy
Version: 1.7.1
Summary: Python package for selected PhosR-inspired phosphoproteomics workflows
Author: PhosPy Contributors
Maintainer: falconsmilie (Shane)
License-Expression: GPL-3.0
Project-URL: Homepage, https://phospy.com
Project-URL: Repository, https://github.com/falconsmilie/phospy
Project-URL: Documentation, https://phospy.com/docs/
Project-URL: Issues, https://github.com/falconsmilie/phospy/issues
Project-URL: Changelog, https://github.com/falconsmilie/phospy/blob/main/CHANGELOG.md
Project-URL: Citation, https://github.com/falconsmilie/phospy/blob/main/CITATION.cff
Project-URL: Release Notes, https://phospy.com/docs/release-notes/
Keywords: phosphoproteomics,proteomics,bioinformatics,phosphorylation,phosphosite,kinase,ksea,mass-spectrometry,phosr
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Requires-Python: <3.13,>=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE.md
Requires-Dist: numpy>=1.24
Requires-Dist: pandas>=2.0
Requires-Dist: scipy>=1.10
Requires-Dist: scikit-learn>=1.6
Provides-Extra: parquet
Requires-Dist: pyarrow>=15.0; extra == "parquet"
Provides-Extra: test
Requires-Dist: hypothesis>=6; extra == "test"
Requires-Dist: pytest>=8.0; extra == "test"
Requires-Dist: setuptools>=77.0.3; extra == "test"
Requires-Dist: wheel>=0.45.1; extra == "test"
Provides-Extra: docs
Requires-Dist: mkdocs>=1.6; extra == "docs"
Requires-Dist: mkdocs-material>=9.5; extra == "docs"
Requires-Dist: pymdown-extensions>=10.0; extra == "docs"
Provides-Extra: dev
Requires-Dist: hypothesis>=6; extra == "dev"
Requires-Dist: pandas-stubs>=3.0.0.260204; extra == "dev"
Requires-Dist: scipy-stubs>=1.17.1.0; extra == "dev"
Requires-Dist: pre-commit>=4.0; extra == "dev"
Requires-Dist: pyright>=1.1.410; extra == "dev"
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: ruff>=0.15.7; extra == "dev"
Dynamic: license-file

# PhosPy

[![PyPI version](https://img.shields.io/pypi/v/phospy.svg)](https://pypi.org/project/phospy/)
[![Python versions](https://img.shields.io/pypi/pyversions/phospy.svg)](https://pypi.org/project/phospy/)
[![Tests](https://github.com/falconsmilie/phospy/actions/workflows/ci.yml/badge.svg)](https://github.com/falconsmilie/phospy/actions/workflows/ci.yml)
[![License](https://img.shields.io/pypi/l/phospy.svg)](https://github.com/falconsmilie/phospy/blob/main/LICENSE)

PhosPy helps you turn phosphosite intensity tables into analysis-ready datasets
and run focused phosphoproteomics workflows from Python.

Use PhosPy to prepare and validate phosphosite data, test differential
phosphorylation, run offline enrichment, explore kinase-substrate support, and
build signalome summaries. The supported user interface is the Python API.

## Project Status and API Stability

PhosPy is currently beta software for Python 3.11 and 3.12. APIs may evolve
during beta: `phospy.api` is the stable user-facing route, `phospy.advanced` is
the supported route for advanced configuration and publishing helpers, and
internal modules are unsupported import targets. See the
[API stability guide](docs/api/guide.md) and the
[maintainer release process](docs/maintenance.md).

## Install PhosPy

```bash
pip install phospy
```

Add Parquet support when you need it:

```bash
pip install "phospy[parquet]"
```

## Try a Kinase Analysis

The public workflow follows a simple pattern: prepare a dataset, create a
request, and run the workflow. The complete example below uses a small rat
dataset and bundled rat references.

<details>
<summary><strong>View the Complete Kinase Example</strong></summary>

```python
import pandas as pd

from phospy import AnalysisReadyDatasetBuilder, KinaseWorkflow
from phospy.advanced import (
    KinaseReliabilityProfile,
    KinaseScoringConfig,
    ReferenceContextCompatibilityPolicy,
)
from phospy.api import (
    DatasetBuildRequest,
    DatasetLocalisationConfig,
    DatasetPreprocessingConfig,
    IntensityScaleKind,
    KinaseWorkflowRequest,
    Organism,
    ReferencePreset,
)

phospho = pd.DataFrame(
    {
        "control_1": [8200.0, 9100.0, 6000.0],
        "control_2": [8000.0, 9000.0, 5900.0],
        "treated_1": [16200.0, 9150.0, 13000.0],
    },
    index=["MAPK14;Y182;", "GSK3A;S21;", "TSC2;S939;"],
)

site_metadata = pd.DataFrame(
    {
        "gene_symbol": ["MAPK14", "GSK3A", "TSC2"],
        "site": ["Y182", "S21", "S939"],
        "site_sequence": [
            "LDFGLARHTDDEMTGYVATRWYRAPEIMLNW",
            "PSGGGPGGSGRARTSSFAEPGGGGGGGGGGP",
            "FDDTPEKDSFRARSTSLNERPKSLRIARAPK",
        ],
        "protein_identifier": ["MAPK14", "GSK3A", "TSC2"],
        "protein_namespace": ["protein_id"] * phospho.shape[0],
        "protein_group_id": ["MAPK14", "GSK3A", "TSC2"],
        "localisation_confidence": [0.95, 0.94, 0.96],
    },
    index=phospho.index,
)

dataset = AnalysisReadyDatasetBuilder().run(
    DatasetBuildRequest(
        phospho=phospho,
        site_metadata=site_metadata,
        organism=Organism.RAT,
        input_intensity_scale=IntensityScaleKind.LINEAR,
        preprocessing_config=DatasetPreprocessingConfig(
            localisation=DatasetLocalisationConfig(
                mode="require_threshold",
                confidence_column="localisation_confidence",
                min_confidence=0.75,
            )
        ),
    )
)

result = KinaseWorkflow().run(
    KinaseWorkflowRequest(
        dataset=dataset,
        references=ReferencePreset.AUTO,
        scoring_config=KinaseScoringConfig(
            reliability_profile=KinaseReliabilityProfile.CUSTOM,
            reference_context_compatibility_policy=(
                ReferenceContextCompatibilityPolicy.ALLOW_UNKNOWN_WITH_CAVEAT
            ),
        ),
        activity_config=None,
    )
)

print(result.prediction_result.pred_mat.head())
```

The values are illustrative. Use study-specific references, biological
replicates, and thresholds for real analyses.

</details>

The main dataset and workflow entry points are available from `phospy`:

```python
from phospy import AnalysisReadyDatasetBuilder
from phospy import DifferentialAnalysisWorkflow, KinaseWorkflow, SignalomeWorkflow
```

Enrichment is available from `phospy.api`:

```python
from phospy.api import EnrichmentConfig, EnrichmentWorkflow, EnrichmentWorkflowRequest
```

## Read the Guides

- [Prepare a dataset](docs/api/dataset-build-workflow.md)
- [Run differential analysis](docs/api/differential-analysis.md)
- [Run enrichment](docs/api/enrichment.md)
- [Run kinase analysis](docs/api/kinase.md)
- [Run signalome analysis](docs/api/signalome.md)

The full documentation is available at [PhosPy Docs](https://phospy.com/docs/).
See the [contributing guide](docs/contributing.md), [license](LICENSE), and
[`CITATION.cff`](CITATION.cff) for project and citation details.

## Scientific Scope

PhosPy is careful about what each result can support. Read the
[interpretation guide](docs/scientific-interpretation.md) before drawing
biological conclusions from an analysis.

<details>
<summary><strong>Review the Current Scientific Boundaries</strong></summary>

PhosPy is inspired by PhosR, but differential analysis is limited to tested
design and contrast envelopes; it is not full limma or PhosR parity.

Bundled runtime references are rat-only. `ReferencePreset.AUTO` is therefore
for rat datasets; human, mouse, and custom analyses must pass an explicit
`ReferenceBundle`. Kinase scores show relative support within a run. They are
not calibrated probabilities, and activity outputs are not direct proof of
kinase activation or causal pathway activity.

Enrichment provides offline over-representation analysis (ORA) with
caller-supplied identifier sets and an explicit background. ORA does not imply
GSEA or PTM-SEA support.

`linear_residualize_batch`, a limited fixed-effect residualisation, rejects
confounded batch/condition designs. It is not ComBat, not RUV, not limma
`removeBatchEffect` parity, and not mixed-effects modelling. Native
SPS/RUV-style correction through `SpsRuvBatchCorrectionConfig` is a separate,
explicit preprocessing method. It is not PhosR-equivalent SPS/RUV-III parity
and not PhosR-equivalent batch correction. Replicate metadata is checked and
recorded but is not used for numerical unwanted-factor estimation.
`ruv_readiness` values are report-only readiness signals and do not apply
correction; use native correction only after those prerequisites are
implemented in the request.

</details>
