scbamqc 0.1.0__tar.gz

scbamqc-0.1.0/LICENSE

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2026 Argenis Arriojas
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

scbamqc-0.1.0/PKG-INFO

@@ -0,0 +1,182 @@
+Metadata-Version: 2.4
+Name: scbamqc
+Version: 0.1.0
+Summary: Per-barcode BAM alignment QC and alignment-based cell filtering for single-cell RNA-seq
+Author-email: Argenis Arriojas <ArriojasMaldonado001@umb.edu>
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+License-File: LICENSE
+Requires-Dist: cyclopts>=3
+Requires-Dist: numpy
+Requires-Dist: pandas
+Requires-Dist: rich
+Requires-Dist: scikit-learn
+Requires-Dist: scipy
+Requires-Dist: scbamqc[anndata, bam, plot] ; extra == "all"
+Requires-Dist: anndata>=0.10 ; extra == "anndata"
+Requires-Dist: h5py ; extra == "anndata"
+Requires-Dist: pysam>=0.22 ; extra == "bam"
+Requires-Dist: matplotlib ; extra == "plot"
+Requires-Dist: pytest>=8.3.4 ; extra == "test"
+Project-URL: Bug Tracker, https://github.com/umbibio/scbamqc/issues
+Project-URL: Changelog, https://github.com/umbibio/scbamqc/blob/main/CHANGELOG.md
+Project-URL: Homepage, https://github.com/umbibio/scbamqc
+Project-URL: Repository, https://github.com/umbibio/scbamqc.git
+Provides-Extra: all
+Provides-Extra: anndata
+Provides-Extra: bam
+Provides-Extra: plot
+Provides-Extra: test
+
+# scbamqc
+
+Alignment QC for single-cell BAM files, and cell selection from that QC.
+
+- `scbamqc bam` writes one row of alignment statistics for each cell barcode.
+- `scbamqc.qc` calculates a quality score for each barcode and selects cells.
+- `scbamqc.pl` plots the statistics and the score.
+
+## Install
+
+```bash
+pip install scbamqc
+```
+
+Add extras for more functions:
+
+| Extra | Adds | Use it for |
+|---|---|---|
+| `bam` | pysam | `scbamqc bam` and `scbamqc tags` (Linux, macOS) |
+| `anndata` | anndata, h5py | `scbamqc.io.read_10x_h5` |
+| `plot` | matplotlib | `scbamqc.pl` and `scbamqc bam --plots` |
+| `all` | all of the above | |
+
+For example: `pip install "scbamqc[bam,plot]"`.
+
+## Command line
+
+The BAM file must be sorted by coordinate and indexed (`samtools index`).
+
+```bash
+# Cell Ranger
+scbamqc bam possorted_genome_bam.bam -j 16 --out-prefix S1
+
+# STARsolo SmartSeq: one read group for each cell
+scbamqc bam Aligned.sortedByCoord.out.bam --barcode-tag RG
+```
+
+The tool writes `S1_per_cell.csv.gz`, with one row for each barcode. To also
+write histograms to `S1_plots.png`, add `--plots`.
+
+For all options, run `scbamqc bam --help`.
+
+### Other pipelines
+
+Different pipelines write the barcode and the mismatch count in different BAM
+tags. Find the tags before you run `bam`:
+
+```bash
+scbamqc tags sample.bam
+scbamqc bam sample.bam --barcode-tag CB --nm-tag NM
+```
+
+`bam` shows a warning if most reads do not have the tags you set.
+
+> [!WARNING]
+> Without a mismatch tag, `mean_nm` is empty (`NaN`). Then no barcode gets a
+> quality score.
+
+## Python
+
+```python
+import scbamqc as sbq
+from scbamqc.io import read_10x_h5
+
+adata = read_10x_h5("raw_feature_bc_matrix.h5")
+adata = sbq.add_bam_qc(adata, "S1_per_cell.csv.gz")
+adata = sbq.basic_qc(adata)
+sbq.qc_score(adata, min_reads=150)
+sbq.select_cells(adata)
+
+sbq.pl.qc_score_scatter(adata, min_score=0, min_counts=100)
+sbq.pl.qc_score_hist(adata, threshold=0.9)
+
+cells = adata[adata.obs["selected"] & (adata.obs["qc_score"] > 0.9)].copy()
+```
+
+| Step | Result |
+|---|---|
+| `add_bam_qc` | Keeps the barcodes in the BAM table. Adds the table columns to `obs`. |
+| `basic_qc` | Removes barcodes with fewer than 5 genes and genes in fewer than 5 barcodes. Adds `total_counts`. |
+| `qc_score` | Adds `obs["qc_score"]`, from 0 to 1. |
+| `select_cells` | Adds `obs["gmm_label"]` and `obs["selected"]`. |
+
+### The quality score
+
+1. A barcode gets a score only if `n_reads > min_reads` and `mean_nm < 1`.
+   Other barcodes get `NaN`.
+2. A kernel density is fitted to three values of these barcodes:
+   `mean_clip_frac`, `std_clip_frac` and `mean_base_qual` divided by its
+   median.
+3. The score is `log10(density + 1)`, scaled from 0 to 1.
+
+A high score shows that the barcode aligns like most other barcodes.
+
+Set `min_reads` for each library. The paper used values from 50 to 3,000.
+
+`base_qual_scale` sets the divisor of `mean_base_qual`. The default is the
+median of the scored barcodes. The divisor does not change the order of the
+barcodes. It can change the score values only when the densities are near 1.
+
+To use the same settings as the TgRN paper:
+
+```python
+sbq.qc_score(adata, min_reads=150, base_qual_scale=sbq.PAPER_BASE_QUAL_SCALE)
+sbq.select_cells(adata, tol=sbq.PAPER_GMM_TOL)
+```
+
+### Cell selection
+
+`select_cells` fits a Gaussian mixture with two components to
+`log10(total_counts)` and `qc_score`. A barcode is selected if:
+
+- it is in the component with the higher counts,
+- `total_counts > min_counts` (default 100),
+- `qc_score > min_score` (default 0).
+
+The mixture fit runs until it converges. The paper stopped the fit early
+(`tol=PAPER_GMM_TOL`). On the paper sample, the converged fit selects 15,536
+cells and the paper fit selects 16,120. All cells of the converged fit are in
+the paper set.
+
+## R
+
+The R package in [`r/`](r/README.md) does the same steps for Seurat objects.
+It reads the table that `scbamqc bam` writes.
+
+```r
+remotes::install_github("umbibio/scbamqc", subdir = "r")
+```
+
+## Development
+
+```bash
+uv sync
+uv run pytest
+```
+
+The tests in `tests/test_paper.py` compare the results with the paper. They
+need the data in `../../data`, or in the folder set by `SCBAMQC_TEST_DATA`.
+Without the data, pytest skips them.
+
+## License
+
+BSD 3-Clause.
+

scbamqc-0.1.0/README.md

@@ -0,0 +1,144 @@
+# scbamqc
+
+Alignment QC for single-cell BAM files, and cell selection from that QC.
+
+- `scbamqc bam` writes one row of alignment statistics for each cell barcode.
+- `scbamqc.qc` calculates a quality score for each barcode and selects cells.
+- `scbamqc.pl` plots the statistics and the score.
+
+## Install
+
+```bash
+pip install scbamqc
+```
+
+Add extras for more functions:
+
+| Extra | Adds | Use it for |
+|---|---|---|
+| `bam` | pysam | `scbamqc bam` and `scbamqc tags` (Linux, macOS) |
+| `anndata` | anndata, h5py | `scbamqc.io.read_10x_h5` |
+| `plot` | matplotlib | `scbamqc.pl` and `scbamqc bam --plots` |
+| `all` | all of the above | |
+
+For example: `pip install "scbamqc[bam,plot]"`.
+
+## Command line
+
+The BAM file must be sorted by coordinate and indexed (`samtools index`).
+
+```bash
+# Cell Ranger
+scbamqc bam possorted_genome_bam.bam -j 16 --out-prefix S1
+
+# STARsolo SmartSeq: one read group for each cell
+scbamqc bam Aligned.sortedByCoord.out.bam --barcode-tag RG
+```
+
+The tool writes `S1_per_cell.csv.gz`, with one row for each barcode. To also
+write histograms to `S1_plots.png`, add `--plots`.
+
+For all options, run `scbamqc bam --help`.
+
+### Other pipelines
+
+Different pipelines write the barcode and the mismatch count in different BAM
+tags. Find the tags before you run `bam`:
+
+```bash
+scbamqc tags sample.bam
+scbamqc bam sample.bam --barcode-tag CB --nm-tag NM
+```
+
+`bam` shows a warning if most reads do not have the tags you set.
+
+> [!WARNING]
+> Without a mismatch tag, `mean_nm` is empty (`NaN`). Then no barcode gets a
+> quality score.
+
+## Python
+
+```python
+import scbamqc as sbq
+from scbamqc.io import read_10x_h5
+
+adata = read_10x_h5("raw_feature_bc_matrix.h5")
+adata = sbq.add_bam_qc(adata, "S1_per_cell.csv.gz")
+adata = sbq.basic_qc(adata)
+sbq.qc_score(adata, min_reads=150)
+sbq.select_cells(adata)
+
+sbq.pl.qc_score_scatter(adata, min_score=0, min_counts=100)
+sbq.pl.qc_score_hist(adata, threshold=0.9)
+
+cells = adata[adata.obs["selected"] & (adata.obs["qc_score"] > 0.9)].copy()
+```
+
+| Step | Result |
+|---|---|
+| `add_bam_qc` | Keeps the barcodes in the BAM table. Adds the table columns to `obs`. |
+| `basic_qc` | Removes barcodes with fewer than 5 genes and genes in fewer than 5 barcodes. Adds `total_counts`. |
+| `qc_score` | Adds `obs["qc_score"]`, from 0 to 1. |
+| `select_cells` | Adds `obs["gmm_label"]` and `obs["selected"]`. |
+
+### The quality score
+
+1. A barcode gets a score only if `n_reads > min_reads` and `mean_nm < 1`.
+   Other barcodes get `NaN`.
+2. A kernel density is fitted to three values of these barcodes:
+   `mean_clip_frac`, `std_clip_frac` and `mean_base_qual` divided by its
+   median.
+3. The score is `log10(density + 1)`, scaled from 0 to 1.
+
+A high score shows that the barcode aligns like most other barcodes.
+
+Set `min_reads` for each library. The paper used values from 50 to 3,000.
+
+`base_qual_scale` sets the divisor of `mean_base_qual`. The default is the
+median of the scored barcodes. The divisor does not change the order of the
+barcodes. It can change the score values only when the densities are near 1.
+
+To use the same settings as the TgRN paper:
+
+```python
+sbq.qc_score(adata, min_reads=150, base_qual_scale=sbq.PAPER_BASE_QUAL_SCALE)
+sbq.select_cells(adata, tol=sbq.PAPER_GMM_TOL)
+```
+
+### Cell selection
+
+`select_cells` fits a Gaussian mixture with two components to
+`log10(total_counts)` and `qc_score`. A barcode is selected if:
+
+- it is in the component with the higher counts,
+- `total_counts > min_counts` (default 100),
+- `qc_score > min_score` (default 0).
+
+The mixture fit runs until it converges. The paper stopped the fit early
+(`tol=PAPER_GMM_TOL`). On the paper sample, the converged fit selects 15,536
+cells and the paper fit selects 16,120. All cells of the converged fit are in
+the paper set.
+
+## R
+
+The R package in [`r/`](r/README.md) does the same steps for Seurat objects.
+It reads the table that `scbamqc bam` writes.
+
+```r
+remotes::install_github("umbibio/scbamqc", subdir = "r")
+```
+
+## Development
+
+```bash
+uv sync
+uv run pytest
+```
+
+The tests in `tests/test_paper.py` compare the results with the paper. They
+need the data in `../../data`, or in the folder set by `SCBAMQC_TEST_DATA`.
+Without the data, pytest skips them.
+
+## License
+
+BSD 3-Clause.

scbamqc-0.1.0/pyproject.toml

@@ -0,0 +1,67 @@
+[project]
+name = "scbamqc"
+version = "0.1.0"
+description = "Per-barcode BAM alignment QC and alignment-based cell filtering for single-cell RNA-seq"
+readme = "README.md"
+license = { file = "LICENSE" }
+authors = [
+    { name = "Argenis Arriojas", email = "ArriojasMaldonado001@umb.edu" },
+]
+requires-python = ">=3.11"
+classifiers = [
+    "License :: OSI Approved :: BSD License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Scientific/Engineering :: Bio-Informatics",
+]
+dependencies = [
+    "cyclopts>=3",
+    "numpy",
+    "pandas",
+    "rich",
+    "scikit-learn",
+    "scipy",
+]
+
+[project.optional-dependencies]
+anndata = ["anndata>=0.10", "h5py"]
+bam = ["pysam>=0.22"]
+plot = ["matplotlib"]
+all = ["scbamqc[anndata,bam,plot]"]
+test = ["pytest>=8.3.4"]
+
+[project.scripts]
+scbamqc = "scbamqc.cli:main"
+
+[project.urls]
+"Homepage" = "https://github.com/umbibio/scbamqc"
+"Repository" = "https://github.com/umbibio/scbamqc.git"
+"Bug Tracker" = "https://github.com/umbibio/scbamqc/issues"
+"Changelog" = "https://github.com/umbibio/scbamqc/blob/main/CHANGELOG.md"
+
+[build-system]
+requires = ["flit_core>=3.2,<4"]
+build-backend = "flit_core.buildapi"
+
+[tool.flit.module]
+name = "scbamqc"
+
+[tool.flit.sdist]
+exclude = ["r/"]
+
+[dependency-groups]
+dev = [
+    "bump-my-version>=0.31.1",
+    "pre-commit>=4.1.0",
+    "ruff>=0.9.4",
+    "scbamqc[test,all]",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+markers = [
+    "paper: regression tests against the paper's local data (skipped when absent)",
+]

scbamqc-0.1.0/src/scbamqc/__init__.py

@@ -0,0 +1,30 @@
+"""Per-barcode BAM alignment QC and alignment-based cell filtering."""
+
+__version__ = "0.1.0"
+
+from . import pl, qc
+from .qc import (
+    DEFAULT_FEATURES,
+    PAPER_BASE_QUAL_SCALE,
+    PAPER_GMM_TOL,
+    add_bam_qc,
+    basic_qc,
+    gmm_labels,
+    qc_score,
+    read_bam_qc,
+    select_cells,
+)
+
+__all__ = [
+    "DEFAULT_FEATURES",
+    "PAPER_BASE_QUAL_SCALE",
+    "PAPER_GMM_TOL",
+    "add_bam_qc",
+    "basic_qc",
+    "gmm_labels",
+    "pl",
+    "qc",
+    "qc_score",
+    "read_bam_qc",
+    "select_cells",
+]

scbamqc-0.1.0/src/scbamqc/_report.py

@@ -0,0 +1,79 @@
+"""Terminal summary of a BAM-QC run (``rich``)."""
+
+from __future__ import annotations
+
+import pandas as pd
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+
+from .bam import NO_BARCODE, CellStats, StatsKey
+from .pl import _id_label
+
+
+def _pct(part: int, total: int) -> str:
+    return f"{100 * part / total:.1f}%" if total else "n/a"
+
+
+def print_summary(
+    console: Console,
+    df: pd.DataFrame,
+    stats: dict[StatsKey, CellStats],
+    barcode_tag: str = "CB",
+    group_by: str = "cell",
+) -> None:
+    total_reads = sum(cs.n_reads for cs in stats.values())
+    no_cb_reads = sum(cs.n_reads for (cb, _), cs in stats.items() if cb == NO_BARCODE)
+    cb_reads = total_reads - no_cb_reads
+
+    hdr = Table.grid(padding=(0, 2))
+    hdr.add_column(style="bold cyan")
+    hdr.add_column()
+    hdr.add_row("total mapped reads", f"{total_reads:>14,}")
+    hdr.add_row(
+        f"reads with {barcode_tag} tag",
+        f"{cb_reads:>14,}  ({_pct(cb_reads, total_reads)})",
+    )
+    hdr.add_row(
+        f"reads without {barcode_tag} tag",
+        f"{no_cb_reads:>14,}  ({_pct(no_cb_reads, total_reads)})",
+    )
+    hdr.add_row(f"unique {_id_label(barcode_tag)}", f"{df['cb'].nunique():>14,}")
+    if group_by == "cell-contig":
+        hdr.add_row("contigs with reads", f"{df['contig'].nunique():>14,}")
+        hdr.add_row("rows (cell × contig)", f"{len(df):>14,}")
+    else:
+        hdr.add_row("rows (per cell)", f"{len(df):>14,}")
+
+    console.print(
+        Panel(
+            hdr,
+            title="[bold]BAM QC summary[/bold]",
+            border_style="cyan",
+            padding=(1, 2),
+        )
+    )
+    if df.empty:
+        return
+
+    def _metric_table(title: str, col: str, digits: int) -> Table:
+        t = Table(
+            title=title,
+            title_style="bold",
+            header_style="bold cyan",
+            border_style="dim",
+            padding=(0, 1),
+        )
+        t.add_column("metric", style="cyan", no_wrap=True)
+        t.add_column("value", justify="right")
+        for k, v in df[col].describe().round(digits).items():
+            t.add_row(str(k), str(v))
+        return t
+
+    console.print()
+    console.print(
+        _metric_table("MAPQ (per-cell means)", "mean_mapq", 2),
+        _metric_table("Base quality (per-cell means)", "mean_base_qual", 2),
+        _metric_table("Clip fraction (per-cell means)", "mean_clip_frac", 4),
+    )
+    console.print()