prosig 0.5.1

Protein signature discovery and function inference

ProSig

ProSig: Protein Signature Discovery and Function Inference

Installation

Install ProSig from PyPI:

pip install prosig

Verify the command-line entry point:

prosig version

The packaged installation includes the default runtime library needed by prosig scan and runtime prosig inspect commands. To build or refresh the library yourself, run prosig setup-data followed by prosig build-library in a working directory containing the downloaded data.

Command Plan

ProSig will expose a small command set that separates setup workflows from routine analysis workflows:

• prosig setup-data: download and cache external data for offline use.
• prosig build-library: build the minimized GO graph, adjustable Leiden function clusters, and customizable motif library.
• prosig scan: scan a sequence or FASTA file against the motif library and infer motif-supported GO sets from the score board.
• prosig inspect: inspect ProSig artifacts and diagnostic calculations, including GO terms and Lin similarity scores.
• prosig discover: discover discriminative motifs from grouped function clusters and background sequences.

setup-data and build-library are expected to be run less often than discover and annotate. Clustering is treated as part of library construction rather than a separate top-level command, because function clusters are a prerequisite for the motif library. Function prediction is treated as part of annotation, because predictions should be reported together with the motif scan hits that justify them.

prosig scan accepts --seq or --fasta. It reports inferred GO sets with raw motif-cluster weight, defaulting to the top 5 predictions with weight at least 2.0, and shows the strongest contributing motif signature for each prediction. Use --top-n 0 to show all predictions. When score board calibration metadata is available, the observed set accuracy at the nearest lower calibration weight threshold is shown as a calibrated confidence reference.

Runtime prediction and inspection commands load a complete core library rather than independently configurable artifact paths. Use --library-dir DIR to select a specific library. If omitted, ProSig uses the current working directory when any core library file is detected there; otherwise it falls back to the packaged default library. A detected directory must contain all core files: prosig_motifs.tsv, motif_cluster_scoreboard.pkl, motif_cluster_scoreboard_meta.json, clusters_meta.tsv, go_graph.pkl, and accession_mf_go.tsv.

GO evidence-code filtering in build-library is intended to be used with the reviewed Swiss-Prot accession file uniprot_sprot.dat.gz. The excluded GO assignment evidence codes are maintained in src/prosig/go/build.py; applying the same exclusion rule to unreviewed annotation sources requires a separate review.

build-library also writes accession_mf_go.tsv, a headerless two-column TSV mapping primary Swiss-Prot accessions to semicolon-separated high-quality direct MF GO terms for later diagnostics and GO set similarity.

build-library skips derived artifacts that are newer than their dependencies. Use --force or -f to rebuild them anyway. Maintainers can add --package to copy those core runtime artifacts from the working directory into the package default library folder. --package-dir is available for an explicit target directory during packaging or tests.

GO accession clustering builds a sparse GO-set similarity k-nearest-neighbor graph, writes freshness-managed Leiden artifacts (leiden_clusters.tsv and leiden_clusters_meta.tsv), then freshness-manages complete-linkage refinement of those communities. Final outputs are clusters.tsv and clusters_meta.tsv. Use --min-cluster-similarity to set the required all-pairs similarity floor; the default is 0.25.

After final clustering, build-library also synthesizes cluster-level GO MF signatures from clusters.tsv, accession_mf_go.tsv, and go_graph.pkl. The clusters_meta.tsv output includes a composed_go column with up to 10 semicolon-separated representative GO terms per cluster. Terms are selected by support × IC, but only GO IDs are written. Each accession contributes one equal vote per propagated GO term; no additional evidence-code weighting is applied because the retained Swiss-Prot annotations have already been filtered during library construction.

build-library scans prosig_motifs.tsv against accession.fasta for final cluster members and writes the sparse motif hit table motif_features.tsv. The scan uses 8 worker processes by default; override with --motif-scan-processes. It then builds a pickled motif-cluster prediction score board. The score board ignores clusters with fewer than 10 members, ignores motif-cluster pairs with support below 5, and stores only positive motif-cluster weights. Weights are log2 enrichment scores computed with a Jeffreys prior pseudocount of 0.5, so zero-background hits remain finite and support-sensitive. Metadata is written alongside the pickle with counts for ignored combinations, stored weights, and internal calibration at motif-weight thresholds 2.0 through 8.0 in 0.5 increments, including top-1, top-3, set accuracy, average prediction count, and coverage.

Diagnostic Inspection

prosig inspect is a diagnostic command group for checking intermediate artifacts before clustering, motif discovery, or prediction work depends on them. The initial GO commands use only the Molecular Function namespace and only the Lin semantic similarity score:

prosig inspect go-summary
prosig inspect go-term GO:0005524 --ancestors
prosig inspect go-sim GO:0005524 GO:0004672
prosig inspect go-sim GO:0005524 GO:0004672 --verbose
prosig inspect go-sim GO:0005524 GO:0004672 -v --tree-style ascii
prosig inspect go-set-sim "(GO:0005524;GO:0004672)" Q9SVY5 --library-dir .
prosig inspect go-set-sim "GO:0005524;GO:0004672" Q9SVY5 --library-dir .
prosig inspect function cluster_0008 --library-dir .

The GO inspection commands use the resolved runtime library by default. Use --go-graph PATH only when you want to inspect a specific GO graph pickle outside the selected runtime library.

build-library also derives accession.fasta and accession.fasta.idx from the configured uniprot_sprot.dat.gz. FASTA labels are primary Swiss-Prot accessions, and the index stores byte offsets for fast internal sequence lookup. The pair is rebuilt when either artifact is missing or older than the Swiss-Prot source. The index records FASTA size and modification time so edited FASTA files are rejected until the pair is rebuilt.

The inspect surface is intended to grow with artifact diagnostics for accessions, motifs, clustering inputs, and standalone similarity calculations.

Project Structure

• AGENT.md: working instructions for coding agents.
• docs/todos/: project TODOs and backlog.
• docs/prosig_motifs.md: user guide for ProSig motif syntax and motif libraries.
• docs/specs/: implementation specs for motif discovery, ProSig motif handling, function prediction, and related workflows.
• docs/decisions/: durable technical and scientific decision records.
• src/prosig/: package source code.
• tests/: test notes and future test suite.
• data/: local data workspace; large datasets should remain untracked.
• notebooks/: exploratory analysis.
• scripts/: operational helper scripts.

To do:

• prosig discover is not implemented yet.