smack-app 0.1.2

Single-cell Mitochondrial Analysis CLI Kit

SMACK (Single-cell Mitochondrial Analysis CLI Kit)

Welcome! See https://github.com/jonlevi/smack for more

Installation

Pipx (Strongly Recommended)

If you don't have pipx:

pip install --user pipx
pipx ensurepath

pipx install smack-app

Pip User-Level (Not As Recommended)

pip install --user smack-app

Pip Env Level (Not recommended but technically possible)

You can install smack at the env level, but there may be conflicts between SMACKs python dependencies and your env's dependencies. The --user is important, that ensures you install it in your user's directory and not in the global system.

If you installed it in the global system (e.g. with sudo) you could install a version of a library (e.g. a sub-dependency) that is incompatible with your system.

pip install smack-app

Auto-Completion

If you want bash auto-completion for smack commands

smack --install-completion

and then restart the terminal.

How to Use

Typer

SMACK is built on top of the python Typer library, https://typer.tiangolo.com/ (MIT License) and is a CLI app with "commands", "options", and "args":

Usage:

$ setup [OPTIONS] COMMAND [ARGS]...

Options:

• -v, --verbose, --debug / -nv, --no-verbose: Provides detailed logging about all processess [default: no-verbose]
• --version: Prints app version
• --keep-temp-files / --no-keep-temp-files: Keep temp files used throughout the process. If False, only final outputs will be kept and other files will be deleted. [default: no-keep-temp-files]
• --dry-run / --no-dry-run: Verify input data and arguments without executing downstream commands [default: no-dry-run]
• -wd, --working-directory TEXT: Set working directory for temp and final output files [default: smack_working_directory]
• --install-completion: Install completion for the current shell.
• --show-completion: Show completion for the current shell, to copy it or customize the installation.
• --help: Show this message and exit.

Commands:

• genotype: Go from a single BAM --> Directory of H5...
• get-supported-genomes: Prints which genomes have built-in support
• get-supported-filter-sets: Prints the preset filter sets for...
• filter-variants: Collect All Possible Variants from the...

setup genotype

Go from a single BAM --> Directory of H5 Files With Variant Calls

Usage:

$ setup genotype [OPTIONS] INPUT_BAM H5_DIRECTORY

Arguments:

• INPUT_BAM: Path to input BAM file [required]
• H5_DIRECTORY: Directory to store output H5 files [required]

Options:

• -bf, --barcodes-file TEXT: Path to input barcodes file
• -id, --sample-id TEXT: Sample ID for metadata. Defaults to path of input BAM
• -g, --genome [GRCh37|GRCh38|GRCm38|GRCz10|hg19_chrM|hg19|hg38|mm10|mm9|NC_012920|rCRS|CUSTOM]: Name of genome or 'CUSTOM', along with --custom-genome-path <path>. Run get-supported-genomes to see list of built-in genomes. [default: rCRS]
• --custom-genome-path TEXT: Path to valid genome FASTA
• -bc, --barcode-tag TEXT: Tag for cell barcodes in BAM file (usually 'BC' or 'CB') [default: BC]
• -um, --umi-mode [eUMI|UMI]: Group molecules based on eUMI (endogenous) or UMI (literal) [default: eUMI]
• -ub, --umi-barcode-tag TEXT: Tag for UMI barcode in BAM file. Ignored if umi-mode='eUMI'
• -s, --consensus-call-strategy [CONSENSUS|MEAN_QUALITY]: Strategy for collapsing groups of molecules based on eUMI (endogenous) or UMI (literal) [default: CONSENSUS]
• -c, --ncores TEXT: Number of cores to use. Either integer or 'detect' for auto-detecting based on system hardware. [default: detect]
• -bq, --base-quality INTEGER: Minimum per base quality score at position X to be considered a valid read at X [default: 10]
• -mapq, --map-quality INTEGER: Minimum map quality for a read pair to be considered valid [default: 30]
• -es, --max-eUMI-size INTEGER: Maximum eUMI size. eUMIs that are too large are likely artifacts from misalignments [default: 1000]
• -et, --eUMI-trim INTEGER: Number of bp to trim off each side of eUMI for position edge bias [default: 0]
• --help: Show this message and exit.

setup get-supported-genomes

Prints which genomes have built-in support

Usage:

$ setup get-supported-genomes [OPTIONS]

Options:

• --help: Show this message and exit.

setup get-supported-filter-sets

Prints the preset filter sets for variants, and which technology it is recommended for

Usage:

$ setup get-supported-filter-sets [OPTIONS]

Options:

• --help: Show this message and exit.

setup filter-variants

Collect All Possible Variants from the split H5 files. Filter variants based on parameters. H5 directory --> Heteroplasmy, Variants, and Coverage CSVs

Usage:

$ setup filter-variants [OPTIONS] H5_DIRECTORY FILTER_SET:{mtscATAC|REDEEM|MAESTER|DLP|SMART_SEQ|CUSTOM}

Arguments:

• H5_DIRECTORY: String path to h5 directory or comma-separated string list of h5 directories. Should usually be the same path(s) output by genotype command. [required]
• FILTER_SET:{mtscATAC|REDEEM|MAESTER|DLP|SMART_SEQ|CUSTOM}: Name of filter set to use (or 'CUSTOM', along with all parameters set as kwargs). Run get-supported-filter-sets to see list of built-in filter sets. [required]

Options:

• -um, --umi-mode [eUMI|UMI]: Group molecules based on eUMI (endogenous) or UMI (literal) [default: eUMI]
• --min-barcode-depth INTEGER: Minimum depth for a cell/barcode to be kept [default: 10]
• --help: Show this message and exit.

Pytest Tests

poetry shell python -m pytest test_app.py -s Note: Since printed statements are a key part of the CLI app, the tests rely on stdout and thus will faily if you don't include the "-s" command. You should also run the tests in a poetry venv, by running poetry shell or poetry run. Note: These tests are not traditional "unit" tests as not all functionality is mocked out, but are also not "integration" tests. They are not run as part of any CI or pre-commit. They are just to make sure that the app does what it is supposed to do, and should be run manually as part of a check for any new releases of the package. While there are no database or web calls (like in integration tests), there are calls to subprocess/multiprocessing threads that do actual processing and return actual return codes. As a result, some of the tests can take up to 5 minutes to run, but are more representative of real runtime conditions. Also If you only have access to < 4 threads the tests may fail