Metadata-Version: 2.4
Name: varseek
Version: 0.2.0
Summary: Efficient variant screening of RNA-seq and DNA-seq data using k-mer-based alignment against a reference of known variants.
Author-email: Joseph Rich <josephrich98@gmail.com>
Maintainer-email: Joseph Rich <josephrich98@gmail.com>
License: BSD 2-Clause License
        
        Copyright (c) 2024, Pachter Lab
        
        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.
        
        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.
        
Project-URL: Homepage, https://github.com/pachterlab/varseek
Keywords: varseek,bioinformatics,variant-analysis,k-mer,RNA-seq,DNA-seq
Classifier: Environment :: Console
Classifier: Framework :: Jupyter
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Topic :: Utilities
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy<2.0.0,>=1.26.4
Requires-Dist: pandas<2.0.0,>=1.5.3
Requires-Dist: matplotlib>=3.9.0
Requires-Dist: tqdm>=4.66.4
Requires-Dist: anndata>=0.8.0
Requires-Dist: kb-python>=0.29.3
Requires-Dist: gget>=0.30.0
Requires-Dist: scipy>=1.13.1
Requires-Dist: pyfastx>=2.1.0
Requires-Dist: pysam>=0.22.1
Requires-Dist: pyarrow>=19.0.1
Requires-Dist: pydantic>=2.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: black[jupyter]>=22.0.0; extra == "dev"
Requires-Dist: isort>=6.0.0; extra == "dev"
Requires-Dist: toml>=0.10.2; extra == "dev"
Requires-Dist: flake8>=7.0.0; extra == "dev"
Requires-Dist: bandit>=1.8.2; extra == "dev"
Requires-Dist: pympler>=1.1; extra == "dev"
Provides-Extra: analysis
Requires-Dist: nbval>=0.10.0; extra == "analysis"
Requires-Dist: nbdime>=4.0.2; extra == "analysis"
Requires-Dist: matplotlib-venn>=1.0.0; extra == "analysis"
Requires-Dist: ipython>=8.0.0; extra == "analysis"
Requires-Dist: goatools>=1.4.9; extra == "analysis"
Requires-Dist: multiqc>=1.25.1; extra == "analysis"
Requires-Dist: rich>=11.0.0; extra == "analysis"
Requires-Dist: kneed>=0.8.0; extra == "analysis"
Requires-Dist: scanpy>=1.10.4; extra == "analysis"
Requires-Dist: upsetplot>=0.9.0; extra == "analysis"
Requires-Dist: pykegg>=0.1.7; extra == "analysis"
Requires-Dist: cyvcf2>=0.31.1; extra == "analysis"
Requires-Dist: seaborn>=0.13.2; extra == "analysis"
Requires-Dist: adjustText>=1.3.0; extra == "analysis"
Requires-Dist: ipython-autotime>=0.3.0; extra == "analysis"
Dynamic: license-file

# varseek
[![pypi version](https://img.shields.io/pypi/v/varseek)](https://pypi.org/project/varseek)
![Downloads](https://static.pepy.tech/personalized-badge/varseek?period=total&units=international_system&left_color=grey&right_color=brightgreen&left_text=downloads)
[![license](https://img.shields.io/pypi/l/varseek)](LICENSE)
![status](https://github.com/pachterlab/varseek/actions/workflows/ci.yml/badge.svg)
![Code Coverage](https://img.shields.io/badge/Coverage-83%25-green.svg)

<!--[![image](https://anaconda.org/bioconda/varseek/badges/version.svg)](https://anaconda.org/bioconda/varseek)-->
<!--[![Conda](https://img.shields.io/conda/dn/bioconda/varseek?logo=Anaconda)](https://anaconda.org/bioconda/varseek)-->

![alt text](https://github.com/pachterlab/varseek/blob/main/figures/logo.png?raw=true)

`varseek` is a free, open-source command-line tool and Python package that enables variant calling and genotyping of DNA-seq, bulk RNA-seq, and single-cell RNA-seq data using k-mer-based alignment against a reference of variant sequences.

![alt text](https://github.com/pachterlab/varseek/blob/main/figures/varseek_overview_simple.png?raw=true)

Why is k-mer-based alignment advantageous?
- It's way faster than traditional alignment-based variant calling methods, especially for large datasets - varseek runs in minutes, while traditional methods can take hours or days.
- It's more sensitive than traditional alignment-based methods, especially for low-frequency variants and variants in repetitive regions.
- It can be used for both DNA-seq and RNA-seq data, including single-cell RNA-seq data.
- It allows for fast and easy screening against established variant databases (e.g., COSMIC, ClinVar, dbSNP) or custom variant sets.

# Installation
PyPI installation is sufficient for the basic pipeline (screening against a variant database).

PyPI:
```bash
pip install varseek
```

For additional use cases involving FASTQ preprocessing or the de novo variant calling workflow, we recommend using a conda environment.

<!-- Conda:
```bash
conda install -c bioconda varseek
``` -->

GitHub:
```bash
pip install git+https://github.com/pachterlab/varseek.git
cd varseek
conda env create -f environment.yml  # includes pip install .
```


# 🪄 Quick start guide
## 1. Acquire a Reference

Follow one of the below options:

### a. Download a pre-built variant reference
- (optional) View all downloadable references: `vk ref --list_downloadable_references`
- `vk ref --download --variants VARIANTS --sequences SEQUENCES`  # downloads INDEX, T2G

### b. Make custom variant reference from a VARIANTS database
- `vk ref --variants VARIANTS --sequences SEQUENCES ...`  # creates INDEX, T2G

### c. Make custom variant reference for de novo variant calling
- `vk denovo --sequences SEQUENCES ... FASTQ1 FASTQ2 ...`  # creates VARIANTS
- `vk ref --variants VARIANTS --sequences SEQUENCES ...`  # creates INDEX, T2G


## 2. Screen for variants

- `vk count --index INDEX --t2g T2G ... --fastqs FASTQ1 FASTQ2 ...`


# Workflow Overview

The two commands used in a standard workflow are `varseek ref` and `varseek count`. `varseek ref` takes as input (1) a database of variants (e.g., COSMIC, ClinVar, dbSNP, custom) and (2) the reference genome/transcriptome upon which the variants are annotated. `varseek ref` outputs a variant-containing reference sequence (VCRS) index that serves as the basis for variant calling in `varseek count`. `varseek count` takes as input (1) the VCRS index generated by `varseek ref` and (2) sequencing read data in FASTQ format. `varseek count` outputs a variant count matrix in Anndata format with samples/cells (rows) x variants (columns).

`varseek` utilizes the pseudoalignment algorithm implement by the kb-python package. `varseek ref` creates the VCRS index by taking short sequences flanking each variant, in which each k-mer of the VCRS contains the variant nucleotide(s). `varseek ref` wraps `kb ref` to create the VCRS index. `varseek count` uses the VCRS index to pseudoalign sequencing reads and count the number of reads that map to each variant. The variant count matrix can be used for downstream analysis, such as clustering, differential expression, and pathway analysis. `varseek count` wraps `varseek fastqpp`, `kb count`, `varseek clean`, and `varseek summarize` to generate the variant count matrix.

![alt text](https://github.com/pachterlab/varseek/blob/main/figures/varseek_overview.png?raw=true)

The functions of `varseek` are described in the table below.

| Description                                                       | Bash              | Python (with `import varseek as vk`) |
|-------------------------------------------------------------------|-------------------|--------------------------------------|
| Build a variant-containing reference sequence (VCRS) index        | `vk ref ...`      | `vk.ref(...)`                        |
| Preprocess the FASTQ files before pseudoalignment                 | `vk fastqpp ...`  | `vk.fastqpp(...)`                    |
| Process the variant count matrix                                  | `vk clean ...`    | `vk.clean(...)`                      |
| Analyze the variant count matrix results                          | `vk summarize ...`| `vk.summarize(...)`                  |
| Wrap vk fastqpp, kb count, vk clean, and vk summarize             | `vk count ...`    | `vk.count(...)`                      |


# Additional examples and citation

**Examples for getting started:** [GitHub - pachterlab/varseek-examples](https://github.com/pachterlab/varseek-examples.git)

**Repository for manuscript figures**: [GitHub - pachterlab/RLSRP_2025](https://github.com/pachterlab/RLSRP_2025.git)

If you use `varseek` in a publication, please cite the following study:    
```
Rich JM, Luebbert L, Sullivan DK, Rosa R, Pachter L. Reference-based variant detection with varseek. bioRxiv. 2025 September 3. Available from: https://doi.org/10.1101/2025.09.03.674039
```
  
