# :icon-tag: deconvolve

===  :icon-checklist: You will need
- paired-end reads from an Illumina sequencer in FASTQ format [!badge variant="secondary" icon=":heart:" text="gzipped recommended"]
    - **sample name**: [!badge variant="success" text="a-z"] [!badge variant="success" text="0-9"] [!badge variant="success" text="."] [!badge variant="success" text="_"] [!badge variant="success" text="-"] [!badge variant="secondary" text="case insensitive"]
    - **forward**: [!badge variant="success" text="_F"] [!badge variant="success" text=".F"] [!badge variant="success" text=".1"] [!badge variant="success" text="_1"] [!badge variant="success" text="_R1_001"] [!badge variant="success" text=".R1_001"] [!badge variant="success" text="_R1"] [!badge variant="success" text=".R1"] 
    - **reverse**: [!badge variant="success" text="_R"] [!badge variant="success" text=".R"] [!badge variant="success" text=".2"] [!badge variant="success" text="_2"] [!badge variant="success" text="_R2_001"] [!badge variant="success" text=".R2_001"] [!badge variant="success" text="_R2"] [!badge variant="success" text=".R2"] 
    - **fastq extension**: [!badge variant="success" text=".fq"] [!badge variant="success" text=".fastq"] [!badge variant="secondary" text="case insensitive"]
    - **barcode**: must be the terminal comment in the FASTQ header
==- ⁉️ Is deconvoluting necessary?
The importance of doing barcode deconvolution at the FASTQ stage varies based on your goals. This table, by no means
exhaustive, outlines if you should invest in it:

{.compact .clean}
| goal  {.whitespace-nowrap} | necessary?                       |
| :------------------------- | :------------------------------- |
| alignment                  | no, barcode information not used |
| assembly                   | yes                              |
| imputation                 | no, performs  internally         |
| metassembly                | yes                              |
| phasing                    | no, performs  internally         |
| preprocess                 | no, barcodes not yet identified  |
| qc                         | no, barcode information not used |
| SNP calling                | no, barcode information not used |
| SV calling                 | no, performs  internally         |
===

This workflow uses a reference-free method, [QuickDeconvolution](https://github.com/RolandFaure/QuickDeconvolution), 
which uses k-mers to look at "read clouds" (all reads with the same linked-read barcode) and decide which ones likely originate
from different molecules. Being a reference-free method, QuickDeconvolution reads all the sequences into memory, so it
can require quite a bit of RAM. More threads will increase RAM demand.

```bash usage
harpy deconvolve OPTIONS... INPUTS...
```

```bash example | deconvolve with default parameters
harpy deconvolve path/to/data/*.fq
```

## :icon-terminal: Running Options
{.compact .clean}
| argument  {.whitespace-nowrap} | default | description                                                                                                                                     |
| :----------------------------- | :-----: | :---------------------------------------------------------------------------------------------------------------------------------------------- |
| `INPUTS`                       |         | [!badge variant="info" text="required"] Files or directories containing [input FASTQ files](/Getting_Started/common_options.md#input-arguments) |
| `--density` `-d`               |   `3`   | On average, $\frac{1}{2^d}$ kmers are indexed                                                                                                   |
| `--dropout` `-a`               |   `0`   | Minimum cloud size to deconvolve                                                                                                                |
| `--kmer-length` `-k`           |  `21`   | Size of k-mers to search for similarities                                                                                                       |
| `--window-size` `-w`           |  `40`   | Size of window guaranteed to contain at least one kmer                                                                                          |

## Resulting Barcodes
After deconvolution, some barcodes may have a hyphenated suffix like `-1` or `-2` (e.g. `A01C33B41D93-1`).
This is how deconvolution methods create unique variants of barcodes to denote that identical barcodes
do not come from the same original molecules. QuickDeconvolution adds the `-0` suffix to barcodes it was unable
to deconvolve.