Metadata-Version: 2.1
Name: decoil
Version: 2.0.2
Summary: EcDNA reconstruction from long-read nanopore data
Author: Madalina Giurgiu
Author-email: giurgiumadalina25@gmail.com
License: MIT
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: biopython==1.85
Requires-Dist: intervaltree==3.1.0
Requires-Dist: matplotlib==3.5.0
Requires-Dist: mosek==10.1.21
Requires-Dist: nanomath==1.3.0
Requires-Dist: networkx==2.5.1
Requires-Dist: numpy==1.26.4
Requires-Dist: overrides==7.4.0
Requires-Dist: pandas==1.4.2
Requires-Dist: pulp==2.7.0
Requires-Dist: pyBigWig==0.3.22
Requires-Dist: pybedtools==0.9.0
Requires-Dist: pysam==0.21.0
Requires-Dist: scikit-learn==1.2.2
Requires-Dist: scipy==1.12.0
Requires-Dist: seaborn==0.13.0
Requires-Dist: setuptools==68.2.2
Requires-Dist: snakemake==7.32.4
Requires-Dist: vcfpy==0.13.8
Requires-Dist: bionumpy==1.0.12
Requires-Dist: nanomonsv==0.7.2
Requires-Dist: configparser==7.1.0
Requires-Dist: cython==3.0.11
Requires-Dist: parasail==1.3.4
Requires-Dist: deeptools==3.5.5

![Coverage](./coverage-badge.svg)
[![GitHub license](https://img.shields.io/badge/License-BSD%203--Clause-blue.svg)](https://github.com/madagiurgiu25/decoil-pre/blob/main/LICENSE)

# Decoil

Decoil (deconvolve extrachromosomal circular DNA isoforms from long-read data) is a software package for reconstruction
circular DNA.

- [Getting started using conda and pip](#gettingstartedpip)
- [Getting started using docker](#gettingstarteddocker)
- [Getting started using singularity](#gettingstartedsingularity)
- [Test example for docker or singularity](#testexample)
- [Install Decoil from source (latest features, unstable)](#installsource)
- [Decoil run configuration](#decoil-config)
- [File formats](#decoil-file)
- [FAQ](#decoil-faq)
- [Citation](#citation)
- [License](#license)

<a name="gettingstartedpip"></a> 

## Getting started using conda and pip

Assumes you have conda installed.

```bash
# install conda dependencies
CONDAENV="envdecoil"
# linux
conda create -n $CONDAENV --override-channels -c bioconda -c conda-forge python==3.9 survivor==1.0.7 sniffles==1.0.12 ngmlr==0.2.7 samtools datrie
# macos
conda create -n $CONDAENV --override-channels -c bioconda -c conda-forge python==3.9 survivor==1.0.7 sniffles==1.0.7 ngmlr==0.2.7 samtools datrie --platform osx-64

conda activate $CONDAENV

# install decoil via pip
python -m pip install decoil==2.0.2

# optional
export PATH=~/miniconda3/envs/$CONDAENV/bin:$PATH

# check if decoil in path
which decoil
# check version
decoil --version
```

<a name="gettingstarteddocker"></a>

## Getting started using docker

As a prerequisite you need to have installed `docker` (you can install this from the official website or using `conda`).

### Download as docker image

Download `decoil` docker image from `docker-hub`. This contains all the dependencies needed to run the software. No additional installation needed. All the environment, packages, dependencies are all specified in the docker/singularity image. 

```bash
# docker
docker pull madagiurgiu25/decoil:2.0.2
```

###  Run example using docker (optional)

Test docker installation using [example](docs/example.md).

### Run Decoil reconstruction using docker

To run Decoil on your data you need to configure the following parameters:

```bash
# run decoil with your input with standard parameters
BAM_INPUT="<absolute path to your BAM file>"
OUTPUT_FOLDER="<absolute path to your output folder>"
NAME="<sample name>"
GENOME="<absolute path to your reference genome file>"
ANNO="<absolute path to your gtf annotation file>"
```

and then run the following command:

```bash
# docker
docker run -it --platform=linux/amd64 \
    -v ${BAM_INPUT}:/data/input.bam \
    -v ${BAM_INPUT}.bai:/data/input.bam.bai \
    -v ${GENOME}:/annotation/reference.fa \
    -v ${ANNO}:/annotation/anno.gtf \
    -v ${OUTPUT_FOLDER}:/mnt \
    -t madagiurgiu25/decoil:2.0.2 \
    decoil-pipeline sv-reconstruct \
            -b /data/input.bam \
            -r /annotation/reference.fa \
            -g /annotation/anno.gtf \
            -o /mnt --name ${NAME}
```
To test your installation using [example](docs/example.md).

## Getting started using singularity

As a prerequisite you need to have installed `singularity` (you can install this from the official website or using `conda`).

### Download as singularity image

```bash
# singularity
singularity pull decoil.sif  docker://madagiurgiu25/decoil:2.0.2
```

### Run example using singularity (optional)

Test singularity installation using [example](docs/example.md).

### Run Decoil reconstruction using singularity

To run Decoil on your data you need to configure the following parameters:

```bash
# run decoil with your input with standard parameters
BAM_INPUT="<absolute path to your BAM file>"
OUTPUT_FOLDER="<absolute path to your output folder>"
NAME="<sample name>"
GENOME="<absolute path to your reference genome file>"
ANNO="<absolute path to your gtf annotation file>"
```

and then run the following command:

```bash
# singularity
mkdir -p ${OUTPUT_FOLDER}
mkdir -p ${OUTPUT_FOLDER}/logs
mkdir -p ${OUTPUT_FOLDER}/tmp
singularity run \
    --bind ${OUTPUT_FOLDER}/logs:/mnt/logs \
    --bind ${OUTPUT_FOLDER}/tmp:/tmp \
    --bind ${BAM_INPUT}:/data/input.bam \
    --bind ${BAM_INPUT}.bai:/data/input.bam.bai \
    --bind ${GENOME}:/annotation/reference.fa \
    --bind ${ANNO}:/annotation/anno.gtf \
    --bind ${OUTPUT_FOLDER}:/mnt \
    decoil.sif \
    decoil-pipeline sv-reconstruct \
            -b /data/input.bam \
            -r /annotation/reference.fa \
            -g /annotation/anno.gtf \
            -o /mnt --name ${NAME}
```

<br/>

<a name="testexample"></a> 

## Test example for docker or singularity 

To test docker and singularity installation use the [example](docs/example.md).


<br/>

<a name="installsource"></a> 

## Install Decoil from source (latest features, unstable)

You can install the latest version of Decoil repository. Note this is an unstable version and contains bugs.
`git` and `conda/mamba` are prerequisites.

### Linux

```
# create conda environment
conda create -n envdecoil -c bioconda -c conda-forge python==3.10 survivor==1.0.7 sniffles==1.0.12 ngmlr==0.2.7 samtools==1.15.1 deeptools==3.5.5
conda activate envdecoil

# install decoil
git clone https://github.com/madagiurgiu25/decoil-pre.git
cd decoil-pre
python -m pip install -r requirements.txt
python setup.py install
```

And check if the installation worked:

```
# might take a while
decoil-pipeline --version
decoil --version
```

### MacOS

```
# create conda environment
conda create -n envdecoil -c bioconda -c conda-forge python==3.10 survivor==1.0.7 sniffles==1.0.7 ngmlr==0.2.7 samtools==1.15.1 --platform osx-64
conda activate envdecoil

# install decoil
git clone https://github.com/madagiurgiu25/decoil-pre.git
cd decoil-pre
python -m pip install -r requirements.txt
python setup.py install
```

And check if the installation worked:

```
# might take a while
decoil-pipeline --version
decoil --version
```

<a name="decoil-config"></a><br/>

## Decoil run configurations 

An overview about the available functionalities:

|                	| [decoil-pipeline](#decoil-pipeline)	| [decoil](#decoil-docs) | [decoil-viz](#decoil-viz) |
|----------------	|--------	|-----------------	|------------	|
|                	|  (recommended)	                    |  (advanced users)	     | (recommended)	           |
| SV calling     	| x       |                	 |            	|
| coverage track 	| x      	|                 	|            	|
| reconstruction 	| x      	| x               	|            	|
| visualization  	|        	|                 	| x          	|
| docker         	| x      	| x               	| x          	|
| singularity    	| x      	| x               	| x          	|


<a name="decoil-pipeline"></a> <br/>

### 1. Reconstruct ecDNA using `decoil-pipeline` (recommended)

To reconstruct ecDNA we recommend to use `decoil-pipeline` using the `sv-reconstruct` mode.<br/>
This requires only a `.bam` file as input and generates internally all the files required for the reconstruction.


```bash
# call help
docker run -it --platform=linux/amd64 -t madagiurgiu25/decoil:2.0.2 decoil-pipeline --help

usage: decoil-pipeline <workflow> <parameters> [<target>]
Example: 
    # run decoil including the processing and visualization steps
    decoil-pipeline -f sv-recontruct --bam <input> --outputdir <outputdir> --name <sample> --sv-caller <sniffles> -r <reference-genome> -g <annotation-gtf>
        

Decoil 1.1.2: reconstruct ecDNA from long-read data

positional arguments:
  {sv-only,sv-reconstruct,reconstruct-only}
                        sub-command help
    sv-only             Perform preprocessing
    sv-reconstruct      Perform preprocessing and reconstruction

optional arguments:
  -h, --help            show this help message and exit
  --version             show program's version number and exit
  -n, --dry-run
  -f, --force
  -c, --use-conda
```

You can run `decoil-pipeline` using following modes:

- `sv-only`
- `sv-reconstruct`
- `reconstruct-only`

Check the description in [running modes.](docs/decoil_pipeline_modes.md)

<a name="decoil-docs"></a><br/>

### 2. Reconstruct ecDNA using `decoil` (advanced users only)

This configuration is the most flexible and allows users to use their own SV calls. For details go [here](docs/decoil_reconstruct.md).

<a name="decoil-viz"></a><br/>

### 3. Visualization of ecDNA threads using `decoil-viz` (recommended)

To interpret and visualize the results of the ecDNA reconstruction threads, use [decoil-viz](https://github.com/madagiurgiu25/decoil-viz).

<a name="decoil-faq"></a><br/>

## FAQ 

Check recommendations for filtering or debugging in the [FAQ](docs/FAQ.md) section.

<a name="decoil-file"></a><br/>

## File formats

The relevant output files for the users are:

- `reconstruct.bed` - contains all genomic fragments **in order** composing for all reconstructions
- `reconstruct.ecDNA.bed` - contains all genomic fragments  **in order** composing reconstructions labeled as ecDNA
- `reconstruct.ecDNA.filtered.bed` - contains all genomic fragments **in order** composing the reconstructios labeled as ecDNA and passing the `--filter-score`
- `summary.txt` - summarize all the circular reconstructions

<br/>Example `reconstruct.bed`:

```bash
cat reconstruct.bed

#chr    start   end     circ_id fragment_id     strand  coverage        estimated_proportions
chr2    15585356        15633376        0       5       +       149     75
chr3    11150000        11160001        0       41      -       103     75
chr3    11049997        11060001        0       33      +       117     75
chr2    15585356        15633376        3       5       +       149     36
chr3    11150000        11160001        3       41      -       103     36
chr3    11049997        11060001        3       33      +       117     36
chr2    15585356        15633376        3       5       +       149     36
chr2    16521052        16628305        3       13      +       37      36
chr3    10981202        11028470        3       25      -       31      36
chr12   68807722        68970910        2       53      +       252     252
```

| Column | Description |
|--------|-------------|
| `chr` | Chromosome containing the genomic fragment. |
| `start` | Start coordinate of the fragment. |
| `end` | End coordinate of the fragment. |
| `circ_id` | Identifier of the reconstructed circular DNA molecule. Fragments with the same `circ_id` belong to the same reconstruction. |
| `fragment_id` | Unique identifier of the genomic fragment used in the reconstruction. |
| `strand` | Orientation (`+` or `-`) of the fragment within the reconstructed cycle. |
| `coverage` | Sequencing coverage (read depth) supporting this genomic fragment. |
| `estimated_proportions` | Estimated abundance of the reconstructed cycle. This value is identical for all fragments belonging to the same `circ_id`. |

<br/>Example `summary.txt`:

```bash
cat summary.txt

circ_id chr_origin      size(MB)        label   topology_idx    topology_name   estimated_proportions
0       chr3,chr2       0.068025                4       multi_region_inter_chr  75
3       chr3,chr2       0.270566        ecDNA   5       simple_duplications     36
2       chr12           0.163188        ecDNA   0       simple_circle           252
```

| Column | Description |
|--------|-------------|
| `circ_id` | Identifier of predicted cycle. |
| `chr_origin` | Chromosome(s) contributing fragments to the reconstructed cycle. Multiple chromosomes are comma-separated. |
| `size(MB)` | Total size of the reconstructed cycle in megabases (Mb). |
| `label` | Classification assigned to the reconstruction (e.g. `ecDNA`). May be empty if no label is assigned. |
| `topology_idx` | Numeric identifier of the inferred structural topology. |
| `topology_name` | Human-readable name of the inferred topology (e.g. `simple_circle`, `multi_region_inter_chr`, `simple_duplications`). |
| `estimated_proportions` | Estimated abundance of the reconstructed structure. |


<a name="citation"></a>

## Citation

If you use Decoil for your work please cite our paper:

Madalina Giurgiu, Nadine Wittstruck, Elias Rodriguez-Fos, Rocio Chamorro Gonzalez, Lotte Bruckner, Annabell Krienelke-Szymansky, Konstantin Helmsauer, Anne Hartebrodt, Philipp Euskirchen, Richard P. Koche, Kerstin Haase*, Knut Reinert*, Anton G. Henssen*.
**Reconstructing extrachromosomal DNA structural heterogeneity from long-read sequencing data using Decoil**. _Genome Research 2024_, DOI: [https://doi.org/10.1101/gr.279123.124](https://doi.org/10.1101/gr.279123.124)


```
@article{Giurgiu2024ReconstructingDecoil,
    title = {{Reconstructing extrachromosomal DNA structural heterogeneity from long-read sequencing data using Decoil}},
    year = {2024},
    journal = {Genome Research},
    author = {Giurgiu, Madalina and Wittstruck, Nadine and Rodriguez-Fos, Elias and Chamorro Gonzalez, Rocio and Brueckner, Lotte and Krienelke-Szymansky, Annabell and Helmsauer, Konstantin and Hartebrodt, Anne and Euskirchen, Philipp and Koche, Richard P. and Haase, Kerstin and Reinert, Knut and Henssen, Anton G.},
    month = {8},
    pages = {gr.279123.124},
    doi = {10.1101/gr.279123.124},
    issn = {1088-9051}
}
```

Paper repository: [https://github.com/henssen-lab/decoil-paper](https://github.com/henssen-lab/decoil-paper)

## License <a name="license"></a> 

Decoil is distributed under the BSD 3-Clause license.  Consult the accompanying [LICENSE](LICENSE) file for more details.

## Disclaimer

Decoil and the content of this research-repository (i) is not suitable for a medical device; and (ii) is not intended
for clinical use of any kind, including but not limited to diagnosis or prognosis.

