# burdenR

![PyPI](https://img.shields.io/pypi/v/burdenr)
![Build](https://img.shields.io/badge/build-passing-brightgreen)


> **burdenR** is a fast and flexible Python command-line tool for calculating the **relative mutation burden (burden relative risk)** between populations from annotated VCF files or pre-computed genotype frequency tables. It helps identify excess burden of derived alleles and visualize differences between groups.

---

## Why burdenR?

- Quickly compute **burden relative risk** between populations
- Supports annotated VCF or frequency tables as input
- Bootstrap confidence intervals
- Handles large datasets (e.g. 100,000 variants in ~10 seconds)
- User-friendly command-line interface
- Generates both tabular results and publication-quality plots
- Automatically cleans malformed input lines

---

## Installation

Requires **Python ≥ 3.8**.

Install via [PyPI](https://pypi.org/project/burdenr/):

```bash
pip install burdenR
```
Or directly from GitHub
```
pip install git+https://github.com/ZhengCQ/burdenR.git
```

## Usage
### Basic Command
```bash
burdenr \
  -f <INPUT_FILE> \
  -w <WORK_DIR> \
  -A <POPULATION_A> \
  -B <POPULATION_B> \
  -G <GROUP_INFO_FILE>
```
### Example
Calculate burden relative risk for population `popA` vs. `popB` from a VCF file:
```
burdenr -f GATK_vcftoolsfilter.recode.anno.vcf.gz \
        -w work_dir -A popA -B popB \
        -G group_info.tsv  \
        --n-cores 4 \
        --boostrap_n 100 \
```
✅ Test data and example scripts are available in the `example` directory of the GitHub repository

### Command-line Options
| Option             | Description                                                                                                                              |
| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `-f, --infile`     | Input file path. Supports VCF (`.vcf`, `.vcf.gz`) or genotype frequency table (`gt_freq_info.tsv` or `.tsv.gz`).                         |
| `-w, --work-dir`   | Working directory where output files will be saved. Default: `./workdir`.                                                                |
| `-A`               | Name of population A (target population).                                                                                                |
| `-B`               | Name of population B (reference population).                                                                                             |
| `-C`               | Name of population C (outgroup population), optional.                                                                                    |
| `-G, --group-info` | Path to a tab-separated file specifying sample groups. Format: `Group<TAB>Sample`.                                                       |
| `--freq`           | Allele frequency threshold. Variants with frequencies above this threshold in either population will be excluded. Default: no filtering. |
| `--fix-sites`      | Number of fixed sites to use for jackknife resampling. Defaults to one-fifth of total sites if not specified.                            |
| `--boostrap_n`     | Number of bootstrap iterations to calculate risk. Default: 100.                                                                          |
| `--n-cores`        | Number of CPU cores to use for multiprocessing. Default: 4.                                                                              |

### Group Info File Format
Example `group_info.tsv`:
```tsv
Group   Sample
popA    Sample_1
popA    Sample_2
popB    Sample_3
popB    Sample_4
popC    Sample_5
```

### Supported Input Formats
* Annotated VCF files (e.g. `example.anno.vcf.gz`)generated by `snpEff`
* Pre-computed genotype frequency tables (e.g. `gt_freq_info.popA_vs_popB.tsv`)
  
### Output Files
The following files are produced in your specified `work-dir`:  
* `derived_info.<popA>_vs_<popB>.tsv`  
Derived allele information and population frequencies.

* `riskAB/results.<popA>_vs_<popB>.tsv`  
Table summarizing burden relative risk estimates.

* Visual plots:

* riskAB/Burden_risk.<popA>_vs_<popB>.pdf

* riskAB/Burden_risk.<popA>_vs_<popB>.png

If the `--freq` parameter is used, filenames will include frequency threshold information.

### Workflow

1. Read sample and group information from the group info file

2. Process the input file:

* If VCF, convert to genotype frequency table.

* If already a frequency table, read directly.

3. Compute derived allele frequencies for each population.

4. Estimate burden relative risk (AB method).

5. Generate result tables and plots.