Scientific Coverage

PhosPy implements selected PhosR-style phosphoproteomics workflows. "PhosR-style" and "PhosR-inspired" in this repository always mean feature-scoped, evidence-scoped comparison lanes. They do not mean full PhosR package equivalence.

Current Supported Public Lanes

PhosPy currently supports these public analysis lanes:

1. build an AnalysisReadyPhosphoDataset
2. run differential phosphorylation analysis
3. run kinase scoring and prediction
4. optionally run signalome analysis from the kinase result

Differential analysis requires analysis-ready numeric inputs plus valid ExperimentalDesign and Contrast metadata. It does not infer design from sample names and does not replace upstream preprocessing requirements.

Differential Parity Envelope (Current Release)

DifferentialAnalysisWorkflow parity claims are currently scoped to:

• two-condition unpaired designs with biological-replicate rows
• simple condition-vs-condition contrasts with one +1 and one -1 term
• empirical-Bayes modes: method="standard" and method="robust" with optional trend=True
• Benjamini-Hochberg multiple-testing adjustment (adj.P.Val)

Explicitly unsupported in this release:

• batch-aware differential modelling (batch)
• block/paired/repeated-measure differential modelling (block)

Contract difference vs limma/PhosR surface:

• analysis-ready inputs must be complete at boundary; missing values are rejected before differential execution instead of being handled inside differential model fitting.

Bundled runtime references in the current release are rat-only. Human and mouse analysis can be run by passing an explicit ReferenceBundle in Python.

Scope Categories

Every scientific scope claim in public docs must map to one category:

Category	Meaning
parity-gated	Executable lane with active fixture-backed parity checks in release gates
validated PhosPy implementation	Executable lane validated by PhosPy contract/unit/integration tests; not a PhosR-equivalence claim by itself
experimental	Executable but intentionally provisional/approximate behavior with explicit caveats
open gap	Not currently executable in the supported public workflow lane
deliberate scope difference	Intentionally different from PhosR surface or intentionally narrowed contract
not planned	Intentionally outside supported scope

Scientific Scope Matrix (Single Source Of Truth)

This matrix is the maintained user-facing scope source for PhosPy. Parity is feature-specific and evidence-scoped. Full PhosR package equivalence is not claimed.

Area	Scope category	Current executable support	Evidence and release checks	Limits and non-claims
Differential analysis	parity-gated	DifferentialAnalysisWorkflow for two-condition unpaired simple contrasts with empirical-Bayes standard/robust and optional trend	tests/parity/test_differential_analysis_parity.py, tests/parity/test_differential_limma_parity.py, plus unit/integration design and result-contract tests	Batch-aware, block/paired, and repeated-measure designs are rejected in this release. Missing values are rejected at analysis-ready boundary before model fitting.
Kinase scoring	parity-gated	KinaseWorkflow profile/motif scoring and rank-weighted fusion	tests/parity/test_kinase_workflow_parity.py, tests/parity/test_prediction_science_parity.py, tests/parity/test_l6_prediction_parity.py	Relative support scoring only; not calibrated causal inference.
Kinase prediction	parity-gated	Deterministic and adaptive kinase prediction in KinaseWorkflow	tests/parity/test_public_predmat_parity.py, tests/parity/test_l6_prediction_parity.py, tests/parity/test_adaptive_prediction_parity.py, tests/parity/test_adaptive_replay_parity.py	Prediction scores are ranking support, not probabilities.
Kinase activity scoring	validated PhosPy implementation	Supported activity methods: simplified_weighted_substrate_activity_v1 and ksea_zscore_activity_v1	Unit activity tests (tests/unit/test_activity_science.py) and parity activity gate (tests/parity/test_activity_stage_parity.py)	KSEA-style activity is not a claim of full PhosR kinase activity equivalence.
Signalome analysis	parity-gated	SignalomeWorkflow module assignment, network outputs, and protein-site context	tests/parity/test_signalome_workflow_parity.py, tests/parity/test_signalome_clustering_backend_parity.py	Derived summaries, not causal proof. Requires explicit protein_id.
Signalome sampled candidate scoring policy	experimental	SignalomeConfig.sampled_candidate_scoring() approximates candidate module-count scoring	Parity/contract coverage through signalome parity tests and workflow contract checks	Approximation applies to candidate scoring only; tree generation remains exact-policy governed.
Sequence context	parity-gated	site_sequence required at analysis-ready boundary and used in kinase scoring/prediction	tests/parity/test_l6_prediction_parity.py, tests/parity/test_prediction_science_parity.py	Sequence quality remains an upstream dependency.
Localisation handling	validated PhosPy implementation	Localisation confidence validation and fail-fast threshold policies are supported	tests/unit/test_localisation_policy_preprocessing.py, tests/unit/test_validator_boundaries.py	No full localisation-filter workflow parity claim in this release.
Missing values	parity-gated	Missing-data policy execution in preprocessing and downstream score preconditioning	tests/parity/test_preprocessing_science_parity.py, unit missing-data tests	Policy choice changes retained rows and downstream behavior.
Imputation	validated PhosPy implementation	Supported policies include row_median, minprob, knn	Unit preprocessing/scientific invariant tests	Policy-dependent behavior; not blanket PhosR-equivalent imputation.
Normalisation	parity-gated	Supported methods: none, median_center, quantile with stage-order provenance	tests/parity/test_preprocessing_science_parity.py, unit preprocessing tests	Method-specific claims only; no blanket normalisation equivalence claim.
Batch correction / RUV	open gap	No executable SPS/RUV correction lane in current public workflow	N/A for execution; readiness diagnostics documented in workflow contracts	ruv_readiness is diagnostic/report-only and must not be interpreted as correction support.
Enrichment	deliberate scope difference	KSEA-style substrate-set enrichment exists within kinase activity lane	Unit activity tests and scientific policy provenance	Broader pathway/gene-set enrichment lane is not part of current core workflow contract.
Visualisation	deliberate scope difference	No first-class visualization workflow/API in core PhosPy	N/A	Visualization is intentionally out of current scientific parity scope.
Supported bundled organisms and references	deliberate scope difference	Bundled runtime references are rat-only for ReferencePreset.AUTO in this release	Runtime behavior, reference compatibility tests, and workflow docs	Human/mouse are valid organisms but require explicit caller-supplied ReferenceBundle.
Full PhosR package equivalence claim	not planned	Not claimed	Guardrail documentation in this matrix and docs/parity.md	Any implication of global PhosR parity is out of scope.

Release-Gated Scientific Checks

Release-bearing scientific checks are documented and executable with these exact commands/workflows:

• Local release gate command: make test-release-gate
• make test-release-gate executes:
• pytest tests/unit tests/integration -m "not parity and not performance and not release_gate"
• pytest tests/unit/test_provenance_regressions.py tests/integration/test_kinase_workflow_integration.py::test_kinase_public_predmat_provenance_matches_golden_contract tests/integration/test_signalome_workflow_integration.py::test_signalome_l6_provenance_matches_golden_contract -m "release_gate and (reproducibility or golden)"
• pytest tests/parity -m "parity and not parity_diagnostic" -s
• pytest tests/performance -m "performance or release_gate" -q
• Publish pipeline release gate workflow:
• .github/workflows/publish.yml job release-gate runs make test-release-gate
• CI parity workflows:
• .github/workflows/ci.yml job activity-parity-gate runs pytest tests/parity/test_activity_stage_parity.py -m "parity and activity_parity" -s
• .github/workflows/ci.yml job parity-tests runs pytest tests/parity -m parity -s

Interpretation Limits

• Weighted activity output (simplified_weighted_substrate_activity_v1) is a heuristic summary over predicted substrates above threshold/top-N support.
• KSEA-style activity output (ksea_zscore_activity_v1) applies unweighted substrate-set enrichment z-scores after evidence thresholding and reports p-values (and q-values when enabled).
• KSEA-style activity is not equivalent to full PhosR kinase activity inference.
• Rank-weighted fusion scores combine profile-correlation and motif-frequency evidence using rank-derived weights.
• Signalome module/network scores are derived summaries, not probabilities, calibrated confidence values, or causal proof.
• Missing kinase correlations stay missing. 0.0 means a finite near-zero correlation was estimated.
• Differential phosphorylation results depend on valid design matrices, contrast definitions, replicate structure, and upstream preprocessing quality.
• Differential analysis does not resolve peptide/site ambiguity, localisation confidence, imputation, normalisation, or batch correction unless those steps were already performed or explicitly configured in the route.
• Adjusted p-values control false discovery rate according to the implemented correction method; they do not validate biological causality.

Scientific Policy Records

Workflow provenance includes machine-readable scientific_policies records. Each record carries:

• stable policy ID
• name and version
• plain-language description
• active parameters
• scientific assumptions
• output scale/meaning

Ownership of scientific policy modules is domain-scoped:

• shared models: phospy.provenance.scientific_policy_models
• prediction: phospy.science.prediction.scientific_policies
• activities: phospy.science.activities.scientific_policies
• preprocessing: phospy.science.datasets.preprocessing.scientific_policies
• signalome workflow: phospy.workflows.signalome.scientific_policies
• signalome clustering: phospy.science.signalomes.clustering.scientific_policies
• differential aggregation: phospy.science.differential.aggregation.scientific_policies

Differential outputs now expose structured policy provenance through DifferentialAnalysisResult.policy_provenance, including:

• design formula and design-matrix summary
• explicit contrast definitions
• replicate/group requirements and technical-replicate lineage
• empirical-Bayes moderation settings
• p-value and adjusted p-value methods
• missing-value handling policy
• intentionally rejected unsupported design features (batch/block/paired)

profile_correlation_shifted_unit_v1

• What it does: transforms profile correlations from [-1, 1] to [0, 1] using (r + 1) / 2.
• Assumptions: positive correlation increases support.
• Parameters: transform formula, clipping to [0, 1], preserve undefined values as missing.
• Output meaning: relative support score; larger means stronger positive agreement.
• Output does not mean: calibrated probability or direct evidence of inhibition/activation. Negative correlations are treated as lower support, not explicit inhibitory evidence.

kinase_profile_scoring_v1

• What it does: records kinase profile-construction and scoring behavior, including self-inclusion vs leave-one-out semantics.
• Assumptions: profile rows can include the same substrate site later scored unless a leave-one-out policy is explicitly enabled.
• Parameters: profile missing-value strategy, self-inclusion behavior, leave-one-out flag, and scoring substrate floors.
• Output meaning: explicit provenance of the profile-scoring policy context used for downstream support scores.

motif_profile_rank_fusion_v1

• What it does: fuses motif-frequency and profile-correlation evidence using rank-derived logarithmic weights.
• Assumptions: motif-library size and quantified-substrate count proxy evidence strength.
• Parameters: motif/profile weight formulas and fallback/diagnostic flags.
• Output meaning: relative downstream support for kinase-site ranking.
• Output does not mean: statistical enrichment p-value or calibrated confidence.

simplified_weighted_substrate_activity_v1

• What it does: computes prediction-weighted activity and thresholded substrate-mean activity.
• Assumptions: predicted substrate support can summarize relative kinase activity in-run.
• Parameters: threshold, min_substrates, top_n_substrates, and explicit scoring rules.
• Output meaning: relative sample-by-kinase activity summaries.
• Output does not mean: full KSEA-style enrichment statistics.

ksea_zscore_activity_v1

• What it does: computes KSEA-style z-score substrate-set enrichment activity.
• Assumptions: kinase substrate membership is unweighted after evidence thresholding.
• Parameters: evidence threshold, minimum substrates, z-score formula, p-value method, and optional q-value adjustment.
• Output meaning: statistically interpretable substrate-set enrichment activity z-scores with accompanying p-values.
• Output does not mean: PhosR-equivalent kinase activity inference.

candidate_substrate_selection_v1

• What it does: records candidate substrate filtering for kinase prediction.
• Assumptions: top-k ranking, score-threshold filtering, and inclusion floor jointly define usable candidate support.
• Parameters: top_k, threshold rule, threshold value, inclusion floor, and site restriction behavior.
• Output meaning: explicit provenance of the candidate-selection rule that gates kinase ranking and prediction outputs.

signalome_module_candidate_score_v1

• What it does: ranks candidate module counts using within-cluster correlation summaries.
• Assumptions: stronger within-cluster profile coherence indicates better candidate module structure.
• Parameters: requested/resolved candidate-scoring policies, mode, guards, and skip/evaluated diagnostics.
• Output meaning: candidate module-count support score used for ranking/selection.
• Output does not mean: biological certainty or causal regulation evidence.

signalome_missing_value_clustering_v1

• What it does: records missing-value handling for clustering distance/tree inputs.
• Assumptions: non-finite values are normalized to missing; missing values are imputed for clustering internals.
• Parameters: missing-value policy name, applicability scope, and whether imputed values appear in output tables.
• Output meaning: explicit provenance for clustering-matrix preparation rules.

signalome_score_preconditioning_v1

• What it does: records row-retention policy for downstream score preconditioning before signalome execution.
• Assumptions: all-missing rows are unsupported and can be dropped or treated as boundary errors depending on policy.
• Parameters: preconditioning policy, row-retention rule, and input/dropped/retained row counts.
• Output meaning: explicit provenance for score-row retention behavior that can change site coverage and assignments.

protein_module_from_site_membership_v1

• What it does: derives protein module IDs from site-cluster membership incidence patterns.
• Assumptions: shared site-cluster membership reflects shared protein-level module context.
• Parameters: membership-vector representation and module ID assignment rule.
• Output meaning: integer protein module IDs for grouping.
• Output does not mean: direct mechanistic proof of shared regulation.

preprocessing_stage_order_v1

• What it does: records explicit preprocessing stage order used to construct analysis-ready dataset inputs.
• Assumptions: stage order is scientifically meaningful and can change transformed values, row retention, and derived comparison outputs.
• Parameters: configured stage order, default order, and supported stage order metadata.
• Output meaning: explicit provenance for preprocessing execution order.

peptide_to_site_aggregation_v1

• What it does: records how peptide-level differential statistics are aggregated to site-level summaries.
• Assumptions: aggregation strategy and variance rules change site-level uncertainty and significance behavior.
• Parameters: aggregation strategy, minimum peptides per site, missing-variance policy, and weighting mode.
• Output meaning: explicit provenance for site-level differential summary construction.

Where Details Live

• Scientific Coverage is the maintained scope and coverage matrix.
• Parity tracks PhosR comparison evidence, fixture locations, and parity test references.
• Performance Contracts covers scale limits.
• ADR Index stores maintainer decision records.

References

Yang, P., Patrick, E., Humphrey, S. J., Ghazanfar, S., James, D. E., Jothi, R., & Yang, J. Y. H. (2019). Kinase activity inference from quantitative phosphoproteomics data using multiple linear models. Bioinformatics, 35(14), i349-i356.

Xiao, D., Yang, P., & Kim, H. J. (2026). PhosR (R package manual). Bioconductor. https://bioconductor.org/packages/release/bioc/manuals/PhosR/man/PhosR.pdf

Xiao, D., Yang, P., & Kim, H. J. (2026). An introduction to PhosR package (Bioconductor vignette). https://bioconductor.org/packages/release/bioc/vignettes/PhosR/inst/doc/PhosR.html