Inspired by PhosR

Python API workflows

From Phosphosites to Signalomes

PhosPy is a focused Python package for phosphoproteomics. It helps you build validated analysis-ready datasets, run differential analysis, enrichment, and kinase workflows, and continue into optional signalome analysis. A clear Python workflow with explicit validation, provenance, and scientific boundaries.

View on GitHub Read the docs

Install pip install phospy

Build

Prepare an AnalysisReadyPhosphoDataset with explicit site metadata, preprocessing, and provenance.

Compare

Run DifferentialAnalysisWorkflow with explicit designs and contrasts, or use EnrichmentWorkflow with supplied sets and background.

Interpret

Use KinaseWorkflow and SignalomeWorkflow to move from kinase evidence to protein-site context when the required identifiers are present.

Why PhosPy

Focused. Reproducible. Readable.

PhosPy keeps phosphoproteomics analysis clear and approachable. It supports focused workflows for dataset preparation, differential analysis, caller-supplied enrichment, kinase scoring and prediction, activity scoring, and optional signalome exploration, while keeping each step easy to inspect and reproduce. The result is a package that helps labs work consistently without hiding scientific assumptions.

Research use

Built for work.

For laboratories

Build repeatable phospy workflows around strict dataset validation, explicit configuration, provenance, importer hand-offs, and output helpers that fit naturally into shared analysis environments.

For scientists

Move from quantified phosphosites to differential, enrichment, kinase, activity, and signalome outputs with validation, reference handling, and downstream assumptions kept explicit.

For teams

Share a small public API, documented workflow contracts, and reproducible outputs without hiding assumptions in ad hoc scripts or undocumented preprocessing.

Interface

Small surface. Strong control.

Use the top level package

The curated phospy surface exposes the main convenience entry points: AnalysisReadyDatasetBuilder, DifferentialAnalysisWorkflow, KinaseWorkflow, and SignalomeWorkflow.

Drop into `phospy.api`

When you want typed requests, configs, results, experimental design records, contrasts, enrichment objects, references, and public exceptions, the full public contract lives in phospy.api.

Stay explicit

Use the Python API for DataFrame or file-backed inputs, explicit ReferenceBundle wiring, preprocessing policy, workflow configuration, and provenance-aware outputs. PhosPy does not expose HTTP endpoints.

First run

Start on the supported lane.

The smoothest first success is the one documented in the quickstart: build with organism=Organism.RAT, run kinase with ReferencePreset.AUTO, and add signalome only when protein_id is present. Add differential analysis when you have an explicit design, contrasts, and enough biological replication. Use enrichment when you can supply the tested IDs, gene or PTM sets, and background universe. Bundled runtime references are currently rat-only, while human and mouse lanes use an explicit ReferenceBundle.

import pandas as pd

from phospy import AnalysisReadyDatasetBuilder, KinaseWorkflow, SignalomeWorkflow
from phospy.api import (
    DatasetBuildRequest,
    DatasetPreprocessingConfig,
    KinasePredictionConfig,
    KinaseScoringConfig,
    KinaseWorkflowRequest,
    Organism,
    ReferencePreset,
    SignalomeConfig,
    SignalomeWorkflowRequest,
)

phospho = pd.DataFrame(
    {
        "sample_a": [1.00, 0.70],
        "sample_b": [1.10, 0.80],
        "sample_c": [0.95, 0.75],
    },
    index=["TSC2;S939;", "GSK3B;S9;"],
)
site_metadata = pd.DataFrame(
    {
        "gene_symbol": ["TSC2", "GSK3B"],
        "site": ["S939", "S9"],
        "site_sequence": [
            "FDDTPEKDSFRARSTSLNERPKSLRIARAPK",
            "ATMSGRPRTTSFAESSSPVQQPSAFGQAAAL",
        ],
        "display_id": ["TSC2;S939;", "GSK3B;S9;"],
        "organism": ["rat", "rat"],
        "protein_namespace": ["protein_id", "protein_id"],
        "protein_identifier": ["TSC2", "GSK3B"],
        "protein_id": ["TSC2", "GSK3B"],
        "localisation_confidence": [0.96, 0.93],
    },
    index=phospho.index.copy(),
)

dataset = AnalysisReadyDatasetBuilder().run(
    DatasetBuildRequest(
        phospho=phospho,
        site_metadata=site_metadata,
        organism=Organism.RAT,
        preprocessing_config=DatasetPreprocessingConfig.from_raw_phosphosite_table(),
    )
)

kinase_result = KinaseWorkflow().run(
    KinaseWorkflowRequest(
        dataset=dataset,
        references=ReferencePreset.AUTO,
        scoring_config=KinaseScoringConfig.default(),
        prediction_config=KinasePredictionConfig.deterministic(),
        activity_config=None,
        site_sequence_conflict_policy="prefer_reference",
    )
)

signalome_result = SignalomeWorkflow().run(
    SignalomeWorkflowRequest(
        kinase_result=kinase_result,
        config=SignalomeConfig.sampled_candidate_scoring(),
    )
)

Input

A numeric site-by-sample phospho matrix plus aligned site_metadata with gene_symbol, site, site_sequence, localisation confidence, and protein context. Add protein_id for signalome.

Formats

Use DataFrames directly, load supported .csv, .tsv, .txt, and optional .parquet tables, or start from MaxQuant and FragPipe/PTMProphet importer outputs.

Outputs

Publisher helpers and bundle services can write dataset, kinase, and signalome outputs with manifests, config snapshots, references, and provenance-aware tables.

Scientific posture

Clear about scope.

PhosPy is explicit about validation, reference compatibility, differential scope, enrichment inputs, batch-correction limits, and parity posture. It does not claim blanket equivalence with every historical PhosR lane. Instead, it documents what is supported, what is bundled, and where stricter workflow boundaries apply. That honesty is valuable in methods work and shared lab software alike.

FAQ

Questions, answered.

Is PhosPy a replacement for PhosR?

PhosPy is inspired by PhosR, but it presents a more focused Python package. The workflow surface, bundled reference scope, and support boundaries are intentionally narrower and more explicit.

How do differential analysis and enrichment fit in?

Run DifferentialAnalysisWorkflow after building an analysis-ready dataset and providing explicit experimental design and contrast records. Run EnrichmentWorkflow separately when you can supply the tested identifiers, enrichment sets, and background universe; PhosPy does not fetch online enrichment resources for you.

When do I need protein_id?

Signalome requires explicit, non-empty site_metadata.protein_id values. Gene-symbol site identifiers are not treated as a protein-identity fallback.

Where do I go when a first run fails?

Start with the troubleshooting guide. It is organised by symptom and helps you check import issues, table format errors, design and contrast mismatches, reference resolution, and common signalome prerequisites before you need the full validation guide.

Get started

Bring PhosPy into your next project.

Start with the README, follow the quickstart, and use the supported rat plus ReferencePreset.AUTO lane for your first run. Then move deeper into the API, differential, enrichment, kinase, signalome, validation, importer, and output-bundle guides as your analysis grows.

Open repository Open quickstart