pipeconcord 0.2.0__tar.gz

pipeconcord-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 JunhaoQiu
+
+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.

pipeconcord-0.2.0/PKG-INFO

@@ -0,0 +1,232 @@
+Metadata-Version: 2.4
+Name: pipeconcord
+Version: 0.2.0
+Summary: Format-aware concordance reports for bioinformatics pipeline outputs.
+Author: PipeConcord contributors
+License-Expression: MIT
+Project-URL: Homepage, https://qchiujunhao.github.io/pipeconcord/
+Project-URL: Repository, https://github.com/qchiujunhao/pipeconcord
+Project-URL: Issues, https://github.com/qchiujunhao/pipeconcord/issues
+Project-URL: Documentation, https://qchiujunhao.github.io/pipeconcord/
+Keywords: bioinformatics,testing,concordance,pipeline,comparison
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+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
+Provides-Extra: dev
+Requires-Dist: coverage[toml]>=7.0; extra == "dev"
+Requires-Dist: mkdocs>=1.6; extra == "dev"
+Requires-Dist: ruff>=0.4; extra == "dev"
+Dynamic: license-file
+
+# PipeConcord
+
+`pipeconcord` is a Python toolkit for comparing bioinformatics pipeline outputs
+with semantic, format-aware metrics. Instead of only checking whether files are
+byte-for-byte identical, it measures whether two runs agree in biologically or
+analytically meaningful ways.
+
+Project website: <https://qchiujunhao.github.io/pipeconcord/>
+
+Status: alpha. The core comparison model and initial comparators are usable, but
+APIs and metrics may change as more bioinformatics formats and workflows are
+validated.
+
+Rename note: the first alpha release used the package name `biocompare`. Current
+and future releases use `pipeconcord` to avoid confusion with an unrelated
+life-science product directory.
+
+This repository currently implements the Phase 1 vertical slice:
+
+- a shared `ConcordanceReport` model
+- comparator registry with plugin entry point support
+- file type detection for common bioinformatics and tabular formats
+- a differential expression result comparator
+- a count/expression matrix comparator
+- a normalized expression matrix comparator
+- a BED interval comparator
+- a FASTA/FASTQ sequence comparator
+- a lightweight VCF comparator with ALT splitting and minimal allele trimming
+- a `samtools flagstat`/`samtools stats` comparator
+- a generic CSV/TSV table comparator
+- JSON/text report writers
+- a command-line interface
+- automated tests with `unittest`
+
+## Quickstart
+
+Install from PyPI:
+
+```bash
+python3 -m pip install pipeconcord
+```
+
+The package is published at <https://pypi.org/project/pipeconcord/>.
+PipeConcord requires Python 3.10 or newer.
+
+To test unreleased changes from the default branch, install from GitHub:
+
+```bash
+python3 -m pip install git+https://github.com/qchiujunhao/pipeconcord.git
+```
+
+Create two small TSV files:
+
+```bash
+cat > old.tsv <<'EOF'
+gene_id	value
+A	1.0
+B	2.0
+EOF
+
+cat > new.tsv <<'EOF'
+gene_id	value
+A	1.1
+B	2.0
+EOF
+```
+
+Compare them by `gene_id`:
+
+```bash
+pipeconcord compare old.tsv new.tsv --key gene_id
+```
+
+Write a report to disk:
+
+```bash
+pipeconcord compare old.tsv new.tsv \
+  --key gene_id \
+  --output report.json
+```
+
+Compare differential expression tables:
+
+```bash
+pipeconcord compare old_de.tsv new_de.tsv \
+  --type deg \
+  --alpha 0.05
+```
+
+Compare count matrices:
+
+```bash
+pipeconcord compare old_counts.tsv new_counts.tsv \
+  --type counts
+```
+
+Compare normalized expression matrices:
+
+```bash
+pipeconcord compare old_tpm.tsv new_tpm.tsv \
+  --type expression
+```
+
+Compare BED intervals:
+
+```bash
+pipeconcord compare old_peaks.bed new_peaks.bed \
+  --type bed \
+  --min-reciprocal-overlap 0.5
+```
+
+Compare FASTA sequences:
+
+```bash
+pipeconcord compare old_sequences.fa new_sequences.fa \
+  --type fasta
+```
+
+Compare VCF calls:
+
+```bash
+pipeconcord compare old_calls.vcf new_calls.vcf \
+  --type vcf
+```
+
+Optionally provide a reference FASTA for simple repeated-indel left alignment:
+
+```bash
+pipeconcord compare calls_a.vcf calls_b.vcf \
+  --type vcf \
+  --reference-fasta reference.fa
+```
+
+Compare alignment summary statistics:
+
+```bash
+pipeconcord compare old_flagstat.txt new_flagstat.txt \
+  --type bam_stats
+```
+
+Run a batch comparison from a manifest:
+
+```bash
+pipeconcord batch manifest.tsv --format text
+```
+
+The manifest must contain `file_a` and `file_b` columns. Optional columns are
+`label` and `type`.
+
+Use `--min-concordance` in CI to fail when any comparison falls below a chosen
+threshold:
+
+```bash
+pipeconcord batch manifest.tsv --min-concordance 0.95
+```
+
+Write an HTML report:
+
+```bash
+pipeconcord compare old_peaks.bed new_peaks.bed \
+  --type bed \
+  --format html \
+  --output report.html
+```
+
+Batch reports also support `--format html`.
+
+## Development
+
+Install the repository in editable mode with development tools:
+
+```bash
+python3 -m pip install -e ".[dev]"
+```
+
+Run the tests:
+
+```bash
+python3 -m unittest discover -s tests
+```
+
+Run lint and coverage:
+
+```bash
+python3 -m ruff check .
+python3 -m coverage run -m unittest discover -s tests
+python3 -m coverage report
+```
+
+## Plugin Model
+
+Comparators subclass `pipeconcord.comparators.base.Comparator` and return a
+`pipeconcord.core.report.ConcordanceReport`. Third-party packages can register
+comparators with the `pipeconcord.comparators` entry point group.
+
+## Documentation
+
+Additional documentation is available on the project website and in `docs/`,
+including API notes, design rationale, and tutorials for regression testing,
+RNA-seq outputs, variant calls, and BED peak comparisons.
+
+## Citation and Paper Draft
+
+Citation metadata is available in `CITATION.cff`. A draft JOSS-style paper is
+available under `paper/`.

pipeconcord-0.2.0/README.md

@@ -0,0 +1,205 @@
+# PipeConcord
+
+`pipeconcord` is a Python toolkit for comparing bioinformatics pipeline outputs
+with semantic, format-aware metrics. Instead of only checking whether files are
+byte-for-byte identical, it measures whether two runs agree in biologically or
+analytically meaningful ways.
+
+Project website: <https://qchiujunhao.github.io/pipeconcord/>
+
+Status: alpha. The core comparison model and initial comparators are usable, but
+APIs and metrics may change as more bioinformatics formats and workflows are
+validated.
+
+Rename note: the first alpha release used the package name `biocompare`. Current
+and future releases use `pipeconcord` to avoid confusion with an unrelated
+life-science product directory.
+
+This repository currently implements the Phase 1 vertical slice:
+
+- a shared `ConcordanceReport` model
+- comparator registry with plugin entry point support
+- file type detection for common bioinformatics and tabular formats
+- a differential expression result comparator
+- a count/expression matrix comparator
+- a normalized expression matrix comparator
+- a BED interval comparator
+- a FASTA/FASTQ sequence comparator
+- a lightweight VCF comparator with ALT splitting and minimal allele trimming
+- a `samtools flagstat`/`samtools stats` comparator
+- a generic CSV/TSV table comparator
+- JSON/text report writers
+- a command-line interface
+- automated tests with `unittest`
+
+## Quickstart
+
+Install from PyPI:
+
+```bash
+python3 -m pip install pipeconcord
+```
+
+The package is published at <https://pypi.org/project/pipeconcord/>.
+PipeConcord requires Python 3.10 or newer.
+
+To test unreleased changes from the default branch, install from GitHub:
+
+```bash
+python3 -m pip install git+https://github.com/qchiujunhao/pipeconcord.git
+```
+
+Create two small TSV files:
+
+```bash
+cat > old.tsv <<'EOF'
+gene_id	value
+A	1.0
+B	2.0
+EOF
+
+cat > new.tsv <<'EOF'
+gene_id	value
+A	1.1
+B	2.0
+EOF
+```
+
+Compare them by `gene_id`:
+
+```bash
+pipeconcord compare old.tsv new.tsv --key gene_id
+```
+
+Write a report to disk:
+
+```bash
+pipeconcord compare old.tsv new.tsv \
+  --key gene_id \
+  --output report.json
+```
+
+Compare differential expression tables:
+
+```bash
+pipeconcord compare old_de.tsv new_de.tsv \
+  --type deg \
+  --alpha 0.05
+```
+
+Compare count matrices:
+
+```bash
+pipeconcord compare old_counts.tsv new_counts.tsv \
+  --type counts
+```
+
+Compare normalized expression matrices:
+
+```bash
+pipeconcord compare old_tpm.tsv new_tpm.tsv \
+  --type expression
+```
+
+Compare BED intervals:
+
+```bash
+pipeconcord compare old_peaks.bed new_peaks.bed \
+  --type bed \
+  --min-reciprocal-overlap 0.5
+```
+
+Compare FASTA sequences:
+
+```bash
+pipeconcord compare old_sequences.fa new_sequences.fa \
+  --type fasta
+```
+
+Compare VCF calls:
+
+```bash
+pipeconcord compare old_calls.vcf new_calls.vcf \
+  --type vcf
+```
+
+Optionally provide a reference FASTA for simple repeated-indel left alignment:
+
+```bash
+pipeconcord compare calls_a.vcf calls_b.vcf \
+  --type vcf \
+  --reference-fasta reference.fa
+```
+
+Compare alignment summary statistics:
+
+```bash
+pipeconcord compare old_flagstat.txt new_flagstat.txt \
+  --type bam_stats
+```
+
+Run a batch comparison from a manifest:
+
+```bash
+pipeconcord batch manifest.tsv --format text
+```
+
+The manifest must contain `file_a` and `file_b` columns. Optional columns are
+`label` and `type`.
+
+Use `--min-concordance` in CI to fail when any comparison falls below a chosen
+threshold:
+
+```bash
+pipeconcord batch manifest.tsv --min-concordance 0.95
+```
+
+Write an HTML report:
+
+```bash
+pipeconcord compare old_peaks.bed new_peaks.bed \
+  --type bed \
+  --format html \
+  --output report.html
+```
+
+Batch reports also support `--format html`.
+
+## Development
+
+Install the repository in editable mode with development tools:
+
+```bash
+python3 -m pip install -e ".[dev]"
+```
+
+Run the tests:
+
+```bash
+python3 -m unittest discover -s tests
+```
+
+Run lint and coverage:
+
+```bash
+python3 -m ruff check .
+python3 -m coverage run -m unittest discover -s tests
+python3 -m coverage report
+```
+
+## Plugin Model
+
+Comparators subclass `pipeconcord.comparators.base.Comparator` and return a
+`pipeconcord.core.report.ConcordanceReport`. Third-party packages can register
+comparators with the `pipeconcord.comparators` entry point group.
+
+## Documentation
+
+Additional documentation is available on the project website and in `docs/`,
+including API notes, design rationale, and tutorials for regression testing,
+RNA-seq outputs, variant calls, and BED peak comparisons.
+
+## Citation and Paper Draft
+
+Citation metadata is available in `CITATION.cff`. A draft JOSS-style paper is
+available under `paper/`.

pipeconcord-0.2.0/pipeconcord/__init__.py

@@ -0,0 +1,8 @@
+"""Semantic comparison of bioinformatics pipeline outputs."""
+
+from pipeconcord._version import __version__
+from pipeconcord.core.engine import ComparisonEngine
+from pipeconcord.core.report import ConcordanceReport
+
+__all__ = ["ComparisonEngine", "ConcordanceReport", "__version__"]
+

pipeconcord-0.2.0/pipeconcord/__main__.py

@@ -0,0 +1,5 @@
+from pipeconcord.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())
+

pipeconcord-0.2.0/pipeconcord/_version.py

@@ -0,0 +1 @@
+__version__ = "0.2.0"

pipeconcord-0.2.0/pipeconcord/cli.py

@@ -0,0 +1,147 @@
+from __future__ import annotations
+
+import argparse
+import sys
+
+from pipeconcord.core.batch import run_batch
+from pipeconcord.core.engine import ComparisonEngine
+from pipeconcord.io.report_writers import (
+    batch_to_html,
+    batch_to_json,
+    batch_to_text,
+    batch_to_tsv,
+    report_to_html,
+    report_to_json,
+    report_to_text,
+    write_batch,
+    write_report,
+)
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="pipeconcord",
+        description="Generate semantic concordance reports for bioinformatics outputs.",
+    )
+    subparsers = parser.add_subparsers(dest="command")
+
+    compare_parser = subparsers.add_parser("compare", help="Compare one pair of files.")
+    add_common_options(compare_parser)
+    compare_parser.add_argument("file_a", help="First output file to compare.")
+    compare_parser.add_argument("file_b", help="Second output file to compare.")
+    compare_parser.add_argument("-o", "--output", help="Write the report to a file instead of stdout.")
+    compare_parser.add_argument("--format", choices=["html", "json", "text"], default="json", help="Output format.")
+
+    batch_parser = subparsers.add_parser("batch", help="Compare file pairs listed in a CSV/TSV manifest.")
+    add_common_options(batch_parser)
+    batch_parser.add_argument("manifest", help="CSV/TSV manifest with file_a and file_b columns.")
+    batch_parser.add_argument("--min-concordance", type=float, help="Fail if any successful comparison is below this threshold.")
+    batch_parser.add_argument("--stop-on-error", action="store_true", help="Stop on the first failed comparison.")
+    batch_parser.add_argument("-o", "--output", help="Write the batch report to a file instead of stdout.")
+    batch_parser.add_argument("--format", choices=["html", "json", "tsv", "text"], default="tsv", help="Batch output format.")
+
+    return parser
+
+
+def add_common_options(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("-t", "--type", dest="file_type", help="Force a comparator/file type such as bam_stats, bed, counts, deg, expression, fasta, fastq, table, csv, tsv, or vcf.")
+    parser.add_argument("--key", dest="key_column", help="Column to use for row alignment.")
+    parser.add_argument("--delimiter", help="Force a delimiter for tabular files.")
+    parser.add_argument("--alpha", type=float, help="DEG adjusted p-value threshold. Default: 0.05.")
+    parser.add_argument("--lfc-threshold", type=float, help="DEG absolute log-fold-change threshold. Default: 0.0.")
+    parser.add_argument("--top-n", type=int, help="Number of top-ranked DEG genes to compare. Default: 50.")
+    parser.add_argument("--gene-column", help="Gene identifier column override for DEG/count matrices.")
+    parser.add_argument("--sample-columns", help="Counts comparator sample columns as a comma-separated list.")
+    parser.add_argument("--min-reciprocal-overlap", type=float, help="BED interval match threshold. Default: 0.0 for any overlap.")
+    parser.add_argument("--reference-fasta", help="Reference FASTA for optional VCF indel left-alignment.")
+    parser.add_argument("--logfc-column", help="DEG log-fold-change column override.")
+    parser.add_argument("--padj-column", help="DEG adjusted p-value column override.")
+    parser.add_argument("--pvalue-column", help="DEG raw p-value column override when adjusted p-values are absent.")
+
+
+def main(argv: list[str] | None = None) -> int:
+    args_list = list(sys.argv[1:] if argv is None else argv)
+    if args_list and args_list[0] not in {"compare", "batch", "-h", "--help"}:
+        args_list = ["compare", *args_list]
+    parser = build_parser()
+    args = parser.parse_args(args_list)
+    if args.command is None:
+        parser.print_help()
+        return 2
+
+    try:
+        if args.command == "batch":
+            return run_batch_command(args)
+        return run_compare_command(args)
+    except Exception as exc:
+        parser.exit(2, f"pipeconcord: error: {exc}\n")
+    return 0
+
+
+def run_compare_command(args: argparse.Namespace) -> int:
+    engine = ComparisonEngine()
+    report = engine.compare(
+        args.file_a,
+        args.file_b,
+        **comparison_kwargs(args),
+    )
+    if args.output:
+        write_report(report, args.output, fmt=args.format)
+    elif args.format == "html":
+        print(report_to_html(report))
+    elif args.format == "text":
+        print(report_to_text(report))
+    else:
+        print(report_to_json(report))
+    return 0
+
+
+def run_batch_command(args: argparse.Namespace) -> int:
+    results = run_batch(
+        args.manifest,
+        stop_on_error=args.stop_on_error,
+        default_file_type=args.file_type,
+        **comparison_kwargs(args, include_file_type=False),
+    )
+    if args.output:
+        write_batch(results, args.output, fmt=args.format)
+    elif args.format == "html":
+        print(batch_to_html(results))
+    elif args.format == "json":
+        print(batch_to_json(results))
+    elif args.format == "text":
+        print(batch_to_text(results))
+    else:
+        print(batch_to_tsv(results))
+    if args.min_concordance is not None and not 0.0 <= args.min_concordance <= 1.0:
+        raise ValueError("min-concordance must be between 0.0 and 1.0")
+    below_threshold = [
+        result
+        for result in results
+        if result.report is not None and args.min_concordance is not None and result.report.overall_concordance < args.min_concordance
+    ]
+    return 1 if any(result.error for result in results) or below_threshold else 0
+
+
+def comparison_kwargs(args: argparse.Namespace, *, include_file_type: bool = True) -> dict[str, object]:
+    kwargs: dict[str, object] = {
+        "key_column": args.key_column,
+        "delimiter": args.delimiter,
+        "alpha": args.alpha,
+        "lfc_threshold": args.lfc_threshold,
+        "top_n": args.top_n,
+        "gene_column": args.gene_column,
+        "sample_columns": args.sample_columns,
+        "min_reciprocal_overlap": args.min_reciprocal_overlap,
+        "reference_fasta": args.reference_fasta,
+        "logfc_column": args.logfc_column,
+        "padj_column": args.padj_column,
+        "pvalue_column": args.pvalue_column,
+    }
+    if include_file_type:
+        kwargs["file_type"] = args.file_type
+    return kwargs
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

pipeconcord-0.2.0/pipeconcord/comparators/__init__.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+from pipeconcord.comparators.bam_stats import BAMStatsComparator
+from pipeconcord.comparators.bed import BEDComparator
+from pipeconcord.comparators.counts import CountsComparator
+from pipeconcord.comparators.deg import DEGComparator
+from pipeconcord.comparators.expression import ExpressionComparator
+from pipeconcord.comparators.fasta import FASTAComparator
+from pipeconcord.comparators.table import TableComparator
+from pipeconcord.comparators.vcf import VCFComparator
+from pipeconcord.core.registry import ComparatorRegistry
+
+
+def register_builtin_comparators(registry: type[ComparatorRegistry] = ComparatorRegistry) -> None:
+    registry.register(DEGComparator)
+    registry.register(ExpressionComparator)
+    registry.register(CountsComparator)
+    registry.register(BEDComparator)
+    registry.register(FASTAComparator)
+    registry.register(VCFComparator)
+    registry.register(BAMStatsComparator)
+    registry.register(TableComparator)
+
+
+__all__ = ["BAMStatsComparator", "BEDComparator", "CountsComparator", "DEGComparator", "ExpressionComparator", "FASTAComparator", "TableComparator", "VCFComparator", "register_builtin_comparators"]