qcatch 0.2.10
QCatch: Automated quality control of single-cell quantifications from `alevin-fry` and `simpleaf`.
Requires Python: >=3.11

# QCatch

[![PyPI version](https://img.shields.io/pypi/v/qcatch?cacheSeconds=3600&logo=pypi&label=PyPI)](https://pypi.org/project/qcatch/)
[![Tests][badge-tests]][tests]
[![Documentation][badge-docs]][documentation]

[badge-pypi]: https://img.shields.io/pypi/v/qcatch
[pypi]: https://pypi.org/project/qcatch/

[badge-tests]: https://img.shields.io/github/actions/workflow/status/COMBINE-lab/QCatch/test.yaml?branch=main
[tests]: https://github.com/COMBINE-lab/QCatch/actions/workflows/test.yaml

[badge-docs]: https://img.shields.io/badge/docs-online-blue
[documentation]: https://COMBINE-lab.github.io/QCatch

QCatch: Automated quality control of single-cell quantifications from `alevin-fry` and `simpleaf`.

View the complete [QCatch documentation](https://COMBINE-lab.github.io/QCatch) with interactive examples, FAQs, and detailed usage guides.

## Installation

You need to have Python 3.11, 3.12, or 3.13 installed on your system.

There are several alternative options to install QCatch:


#### 1. Bioconda
You can install using [Conda](http://anaconda.org/)
from [Bioconda](https://bioconda.github.io/).

```bash
conda install -c bioconda qcatch
```

#### 2. PyPI

You can also install from [PyPI](https://pypi.org/project/qcatch/) using `pip`:

```bash
pip install qcatch
```

> Tips: If you run into environment issues, you can also use the provided Conda .yml file, which specifies the exact versions of all dependencies to ensure consistency.

```bash
conda env create -f qcatch_conda_env.yml
```


## Basic Usage
Provide the path to the parent folder for quantification results, or the direct path to a .h5ad file generated by `alevin-fry` or `simpleaf`. **QCatch** will automatically scan the input path, assess data quality, and generate an interactive HTML report that can be viewed directly in your browser.

```bash
qcatch \
    --input path/to/your/quantification/result \
    --output path/to/desired/QC/output/folder \ # if you want another folder for output
    --chemistry 10X_3p_v3
    --save_filtered_h5ad
```
For details on how to configure chemistries,
See [chemistry section](#3--chemistry).

## Tutorial: Run QCatch on Example data
### Step 1 — Download Dataset
```bash
#!/bin/bash
set -e  # Exit immediately if a command exits with a non-zero status

echo "📦 Downloading QCatch example dataset..."

# Define where to run the tutorial (you can change this path if desired)
CWD=$(pwd)  # Current working directory
TUTORIAL_DIR="${CWD}/qcatch_tutorial"

# Clean any existing tutorial directory to ensure a fresh download
rm -rf "$TUTORIAL_DIR" && mkdir -p "$TUTORIAL_DIR"
ZIP_FILE="data.zip"

# Download from Box
wget -O "$ZIP_FILE" "https://umd.box.com/shared/static/zd4sai70uw9fs24e1qx6r41ec50pf45g.zip?dl=1"

# Unzip and clean up
unzip "$ZIP_FILE" -d "$TUTORIAL_DIR"
rm "$ZIP_FILE"

echo "✅ Test data downloaded to $TUTORIAL_DIR"
```
### Step 2 - Run the qcatch
🎉 All set! Now let’s run QCatch:
```bash
#Set up output directory
OUT_DIR="${TUTORIAL_DIR}/output"
mkdir -p "$OUT_DIR"

# Step2 - Run QCatch
qcatch --input ${TUTORIAL_DIR}/test_data/simpleaf_with_map/quants.h5ad \
       --output ${OUT_DIR} \
```
### Tips
#### 1- Input path:

Provide either:

- the **path to the parent directory** containing quantification results, or
- the **direct path to a .h5ad file** generated by those tools.

QCatch will automatically detect the input type:
- If a **.h5ad file** is provided, QCatch will process it directly.
- If a **directory** is provided, QCatch will first look for an existing .h5ad file inside. If not found, it will fall back to processing the mtx-based quantification results.

See the example directory structures at the end of the Tips section for reference:

#### 2- Output path:

If you do not want any modifications in your input folder/files, speaficy the output path, we will save any new results and QC HTML report there.

**_By default_**, QCatch saves the QC report and all output files in the input directory by default. If you prefer a different output location, you may specify an output path; however, this is optional.

Specifically:
- If QCatch detects an existing `quants.h5ad` file in the input directory and the output path is the same as the input path, QCatch will modify the original .h5ad file _in place_ by appending cell-filtering results to `anndata.obs`. In addition, it will generate a separate HTML QC report in the input directory.
- For **MTX-based** inputs (i.e., when not using simpleaf v0.19.5 or newer), QCatch will generate a new `.h5ad` file containing metadata produced during QCatch processing. This file does **NOT** include metadata from the original alevin-fry quantification, which remains stored in the original files.

#### 3- Chemistry:
The `--chemistry` information is used to estimate `--n_partitions`, which represents the total partition capacity (i.e., the total number of physical droplets or wells generated in an experiment, regardless of whether they contain a cell). This value is critical for accurately defining the "ambient pool" used to model empty droplets. (_NOTE_: this is distinct from the --chemistry argument in alevin-fry, which refers to the barcode/UMI geometry.)

If you used a **standard 10X** chemistry, QCatch will first attempt to infer the chemistry from the metadata and use the internal database to get the corresponding number of partitions; If this inference fails, QCatch will stop and prompt you to explicitly provide the chemistry version using the `--chemistry` argument before rerunning the command. **Supported chemistries currently include: '10X_3p_v2', '10X_3p_v3', '10X_3p_v4', '10X_3p_LT', '10X_5p_v3', or '10X_HT'**.

For **non-10x or custom** assays (e.g., sci-RNA-seq3, Drop-seq), users can manually specify the capacity using `--n_partitions`. We recommend setting this value by rounding the number of processed barcodes (found in the _alevin-fry/simpleaf_ log or the number of rows in the `.h5ad` file) up to the next 10% increment of the current order of magnitude. For example, If 79,000 barcodes are detected, n_partitions should be set to 80,000; If 144,000 barcodes are detected, n_partitions should be set to 150,000. This option will override any chemistry-based setting for cell-calling.

#### 4- Gene gene mapping file:

If you are using simpleaf v0.19.3 or later, the generated .h5ad file already includes gene names. In this case, you do not need to specify the --gene_id2name_file option.

To provide a 'gene id to name mapping' info, the file should be a **TSV** containing two columns—‘gene_id’ (e.g., ENSG00000284733) and ‘gene_name’ (e.g., OR4F29)— **without** header row. If not provided, the program will attempt to retrieve the mapping from a remote registry. If that lookup fails, mitochondria plots will not be displayed, but will not affect the QC report.

#### 5- Save filtered h5ad file:

If you want to save filtered h5ad file separately, you can specify `--save_filtered_h5ad`, which is only applicable when QCatch detects the h5ad file as the input.

#### 6- Specify your desired cell list:

If you want to use a specified list of valid cell barcodes, you can provide the file path with `--valid_cell_list`. QCatch will then skip the default cell calling step and use the supplied list instead. The updated .h5ad file will include only one additional column, 'is_retained_cells', containing boolean values based on the specified list.

#### 7- Skip clustering plots:

To reduce runtime, you may enable the `--skip_umap_tsne` option to bypass dimensionality reduction and visualization steps.

#### 8- Export the summary metrics

To export the summary metrics, enable the `--export_summary_table` flag. The summary table will be saved as a separate CSV file in the output directory.

#### 9- Visualize doublets

To visualize doublets alongside singlets in UMAP and t-SNE plots, use both `--remove_doublets` and `--visualize_doublets` flags together. This generates two plot views:
- **Retained Cells Only**: Shows singlets colored by Leiden clusters (default view)
- **With Doublets**: Shows both singlets and doublets colored by doublet status (red for doublets, blue for singlets)

Toggle buttons in the HTML report allow switching between these views. Both views use the same coordinate space, so singlets appear at identical positions in both plots for easy comparison.

```bash
qcatch --input path/to/quants.h5ad \
       --remove_doublets \
       --visualize_doublets
```

#### 10- Debug-level message

To get debug-level messages and more intermediate computation in cell calling step, you can specify `--verbose`

#### 11- Re-run QCatch on modified h5ad file
If you re-run QCatch analysis on a modified `.h5ad` file (i.e., an `.h5ad` file with additional columns added for cell calling results), the existing cell calling-related columns will be removed and then replaced with new results. The new cell calling can be generated either through QCatch's internal method or based on a user-specified list of valid cell barcodes.

#### Example directory structures:

```bash
# simpleaf
parent_quant_dir/
├── af_map/
├── af_quant/
│   ├── alevin/
│   │   ├── quants_mat_cols.txt
│   │   ├── quants_mat_rows.txt
│   │   ├── quants_mat.mtx
│   │   └── quants.h5ad (available if you use simpleaf after v0.19.3)
│   │   ...
│   ├── featureDump.txt
│   └── quant.json
└── simpleaf_quant_log.json

# alevin-fry
parent_quant_dir/
├── alevin/
│   ├── quants_mat_cols.txt
│   ├── quants_mat_rows.txt
│   └── quants_mat.mtx
├── featureDump.txt
└── quant.json

```
For more advanced options and usage details, see the sections below.

## Command-Line Arguments

| Flag | Short | Type | Description |
|------|-------|------|-------------|
| `--input`  | `-i` | `str` (Required) | Path to the input directory containing the quantification output files or to the H5AD file itself. |
| `--output` | `-o` | `str`(Required)  | Path to the output directory.|
| `--chemistry` | `-c` | `str`(Recommended) | Specifies the chemistry used in the experiment, which determines the partition range for the empty_drops step. **Supported options**: '10X_3p_v2', '10X_3p_v3', '10X_3p_v4', '10X_5p_v3', '10X_3p_LT', '10X_HT'. If you used a standard 10X chemistry (e.g., '10X_3p_v2', '10X_3p_v3') and performed quantification with `simpleaf`(v0.19.5 or later), QCatch will try to **infer** the correct chemistry from the metadata. If inference fails, QCatch will stop and prompt you to provide the chemistry explicitly via this flag.|
| `--save_filtered_h5ad` | `-s` | `flag` (Optional) |If enabled, `qcatch` will save a separate `.h5ad` file containing only the final retained cells.|
| `--gene_id2name_file` | `-g` | `str` (Optional) |File provides a mapping from gene IDs to gene names. The file must be a TSV containing two columns—‘gene_id’ (e.g., ENSG00000284733) and ‘gene_name’ (e.g., OR4F29)—without a header row. If not provided, the program will attempt to retrieve the mapping from a remote registry. If that lookup fails, mitochondria plots will not be displayed.|
| `--valid_cell_list` | `-l` | `str` (Optional) |File provides a user-specified list of valid cell barcode. The file must be a TSV containing one column with cell barcodes without a header row. If provided, qcatch will skip the internal cell calling steps and and use the supplied list instead|
| `--n_partitions` | `-n` | `int` (Optional) | Number of partitions (max number of barcodes to consider for ambient estimation). Use `--n_partitions` only when working with a custom or unsupported chemistry. When provided, this value will override the chemistry-based configuration during the cell-calling step.|
| `--remove_doublets` | `-d` | `flag` (Optional) | If enabled, QCatch will perform doublet detection(use `Scrublet` tool) and remove detected doublets from the cells retained after cell calling. |
| `--visualize_doublets` | `-vd` | `flag` (Optional) | If enabled (requires `--remove_doublets`), generates additional UMAP and t-SNE plots showing both singlets and doublets. Toggle buttons allow switching between "Retained Cells Only" (singlets) and "With Doublets" views. |
| `--skip_umap_tsne` | `-u` | `flag` (Optional) | If provided, skips generation of UMAP and t-SNE plots. |
| `--export_summary_table` | `-x` | `flag` (Optional) | If enabled, QCatch will export the summary metrics as a separate CSV file. |
| `--verbose` | `-b` | `flag` (Optional) | Enable verbose logging with debug-level messages. |
| `--version` | `-v` | `flag` (Optional) | Display the installed version of qcatch. |

<!-- ## Contact

For questions and help requests, you can reach out in the [scverse discourse][].
If you found a bug, please use the [issue tracker][]. -->

<!-- ## Citation

> t.b.a

[uv]: https://github.com/astral-sh/uv
[scverse discourse]: https://discourse.scverse.org/
[issue tracker]: https://github.com/ygao61/QCatch/issues
[tests]: https://github.com/ygao61/QCatch/actions/workflows/test.yaml
[documentation]: https://QCatch.readthedocs.io
[changelog]: https://QCatch.readthedocs.io/en/latest/changelog.html
[api documentation]: https://QCatch.readthedocs.io/en/latest/api.html
[pypi]: https://pypi.org/project/QCatch -->