Metadata-Version: 2.4
Name: prosig
Version: 0.5.1
Summary: Protein signature discovery and function inference
Author-email: Junjun Mao <junjun.mao@gmail.com>
License: MIT License
        
        Copyright (c) 2026 Junjun Mao
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Keywords: bioinformatics,protein-sequences,motif-discovery,function-prediction
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: igraph>=0.11
Requires-Dist: leidenalg>=0.10
Requires-Dist: numpy>=1.26
Requires-Dist: scipy>=1.11
Requires-Dist: typer>=0.12
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: ruff>=0.5; extra == "dev"
Dynamic: license-file

# ProSig

ProSig: Protein Signature Discovery and Function Inference

## Installation

Install ProSig from PyPI:

```bash
pip install prosig
```

Verify the command-line entry point:

```bash
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:

```text
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.
