Metadata-Version: 2.3
Name: pxaudit
Version: 0.6.0
Summary: Proteomics Exchange metadata audit tool
Author: eneskemalergin
Author-email: eneskemalergin <eneskemalergin@gmail.com>
License: MIT License
         
         Copyright (c) 2026 LangeLab
         
         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.
Requires-Dist: click>=8.3.3
Requires-Dist: pandas>=3.0.5
Requires-Dist: requests>=2.33.0
Requires-Dist: tqdm>=4.70.0
Requires-Dist: jinja2>=3.1 ; extra == 'report'
Requires-Dist: matplotlib>=3.11.1 ; extra == 'report'
Requires-Python: >=3.12
Project-URL: Homepage, https://github.com/LangeLab/PXAudit
Project-URL: Repository, https://github.com/LangeLab/PXAudit
Project-URL: Issues, https://github.com/LangeLab/PXAudit/issues
Project-URL: Changelog, https://github.com/LangeLab/PXAudit/blob/main/CHANGELOG.md
Provides-Extra: report
Description-Content-Type: text/markdown

<!-- markdownlint-disable MD010 MD033 MD036 MD041 -->
<p align="center">
  <img src="https://raw.githubusercontent.com/LangeLab/PXAudit/main/assets/banner.svg" alt="PXAudit" width="180">
</p>

<p align="center">
  Audit Proteomics Exchange (PRIDE) study metadata from the command line.
</p>

<p align="center">
  <img src="https://img.shields.io/badge/python-3.12--3.14-2D7D46?style=flat-square&logo=python&logoColor=white" alt="Python 3.12-3.14">
  <img src="https://img.shields.io/badge/version-0.6.0-8B5CF6?style=flat-square" alt="v0.6.0">
  <img src="https://img.shields.io/badge/status-beta-C17D10?style=flat-square" alt="Beta">
  <a href="https://github.com/LangeLab/PXAudit/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/LangeLab/PXAudit/ci.yml?branch=main&style=flat-square&logo=github&label=CI" alt="CI"></a>
  <a href="https://codecov.io/gh/LangeLab/PXAudit"><img src="https://img.shields.io/codecov/c/github/LangeLab/PXAudit?branch=main&style=flat-square&logo=codecov&logoColor=white" alt="Coverage"></a>
  <img src="https://img.shields.io/badge/license-MIT-4B9D6E?style=flat-square" alt="MIT">
</p>

<p align="center">
  <a href="CHANGELOG.md"><img src="https://img.shields.io/badge/changelog-CHANGELOG-E05D44?style=flat-square" alt="Changelog"></a>
  <a href="CITATION.cff"><img src="https://img.shields.io/badge/cite-CITATION.cff-0066CC?style=flat-square" alt="Citation"></a>
  <a href="https://github.com/LangeLab/PXAudit/wiki"><img src="https://img.shields.io/badge/docs-Wiki-0F766E?style=flat-square" alt="Docs"></a>
</p>

I made PXAudit because I was checking PRIDE submissions by hand and got tired of repeating the same steps.

PXAudit reads project metadata and file listings from the [PRIDE Archive](https://www.ebi.ac.uk/pride/), classifies the deposited files, assigns a seven-level [FAIR](https://doi.org/10.1038/sdata.2016.18) tier and a separate quantification-readiness tier, then saves the audit to SQLite. It does not download deposited data files.

## Quick start

PXAudit supports Python 3.12 through 3.14. The source checkout uses [uv](https://docs.astral.sh/uv/):

```bash
git clone https://github.com/LangeLab/PXAudit.git
cd PXAudit
uv sync
uv run pxaudit check PXD000001
```

The first audit queries PRIDE and creates `pxaudit_results.db` in the current directory. API responses are cached under `~/.pxaudit_cache/`, so a fresh repeat audit does not need another request.

PXAudit currently audits PRIDE `PXD` accessions. Safe identifiers from other ProteomeXchange repositories are accepted as `Unverifiable`; repository adapters are not implemented yet. The unreleased v0.6.0 package is PRIDE-only. Partner adapters are planned after publication.

Audit evidence uses the v3 outcomes `passed`, `failed`, and `unknown`. Unknown evidence is shown as `?`, does not block tier progression, and is counted in `ambiguity_count`; export consumers should treat `has_*` columns as strings rather than integer booleans.

Interactive terminal output uses restrained color for flags and tiers when standard output is a TTY. Meaning stays in the glyphs and labels, so `--no-color`, `NO_COLOR`, quiet mode, and redirected output are plain by default. An explicit `color = true` setting is the opt-in override.

## Common tasks

```bash
# Audit a list containing one accession per line
uv run pxaudit bulk-audit --input accessions.txt --format tsv --output results.tsv
# For large local runs, add --batch-size N to commit after each N accessions.

# Inspect the stored file inventory
uv run pxaudit manifest PXD000001

# Review effective settings and cache state
uv run pxaudit config show
uv run pxaudit cache info

# Review aggregate counts from a stored database
uv run pxaudit summary --db pxaudit_results.db

# Generate a self-contained HTML report
uv sync --extra report
uv run pxaudit report --db pxaudit_results.db --output report/
```

The default batch size is `1`, preserving per-accession durability. A stop-on-error or interrupted run rolls back its active batch; `--continue-on-error` commits pending successes before skipping the failed accession.

Run `uv run pxaudit --help` or `uv run pxaudit COMMAND --help` for command-line help.

## Use as a Python library

The public Python API provides the same single-accession audit used by the CLI and persists the completed result to SQLite:

```python
from pxaudit import audit_accessions, check_accession

one = check_accession("PXD000001", db_path="audits.db")
print(one.tier, one.quant_tier)

cohort = audit_accessions(["PXD000001", "PXD004683"], db_path="audits.db")
print(len(cohort))
```

`db_path` may be a string or `pathlib.Path`. The helpers use the local JSON cache, normalize accessions, and stop on the first error. Use the CLI `bulk-audit --continue-on-error` command when a batch must continue after an individual failure. Lower-level callers can import `compute_audit` and `FileClass` for deterministic scoring and filename classification.

## Documentation

The [wiki](https://github.com/LangeLab/PXAudit/wiki) contains the detailed contracts and examples:

- [Home](https://github.com/LangeLab/PXAudit/wiki/Home): workflow overview and report preview
- [CLI Reference](https://github.com/LangeLab/PXAudit/wiki/CLI-Reference): commands, flags, configuration, caching, errors, and exit codes
- [Tier System](https://github.com/LangeLab/PXAudit/wiki/Tier-System): FAIR and quantification tiers, evidence flags, and scoring rules
- [Database Schema](https://github.com/LangeLab/PXAudit/wiki/Database-Schema): tables, columns, migrations, and example queries
- [FAQ](https://github.com/LangeLab/PXAudit/wiki/FAQ): supported accessions, file classification, offline use, and common scoring questions
- [Development](https://github.com/LangeLab/PXAudit/wiki/Development): setup, architecture, testing, style, and CI

Contributions and issue reports are much appreciated. The development guide explains the local checks and documentation workflow.

---

## Citation

If you use PXAudit in your research, please cite it as:

```bibtex
@software{ergin_pxaudit_2026,
  author   = {Ergin, Enes Kemal},
  title    = {{PXAudit}: A command-line tool for auditing {Proteomics Exchange} study metadata},
  year     = {2026},
  version  = {0.6.0},
  url      = {https://github.com/LangeLab/PXAudit},
  license  = {MIT},
}
```

A `CITATION.cff` file is included in the repository root for tools that parse it automatically (e.g. GitHub's _Cite this repository_ button, Zenodo).

---

## License

MIT License. See [LICENSE](LICENSE) for details.
