metadamageprofiler 21.6.1
Metadamage Profiler — Profiling (Meta)Genomic Ancient Damage
License: MIT
Requires Python: >=3.8,<4.0
Keywords: metadamageprofiler,metadamage,metagenomics,ancient damage,DNA damage

# metadamageprofiler — Profiling (Meta)Genomic Ancient Damage

---

#### Work in progress. Please contact christianmichelsen@gmail.com for further information.

---

## Workflow:


Create `config.yaml` file:
```console
$ ./metadamageprofiler.sh config ./raw_data/example.bam \
    --names raw_data/names.dmp.gz \
    --nodes raw_data/nodes.dmp.gz \
    --acc2tax raw_data/combined_taxid_accssionNO_20200425.gz
```
Run actual program:
```console
$ ./metadamageprofiler.sh compute
```
See the results in the dashboard:
```console
$ ./metadamageprofiler.sh dashboard
```

---

Dependencies:

- [Mamba](https://github.com/conda-forge/miniforge#mambaforge).

See below for more information regarding installation of Mamba.

---

## Installation:

To install __metadamageprofiler__, you just have to make a new directory for your project, `cd` into it and run:

```console
$ wget -O - https://raw.githubusercontent.com/ChristianMichelsen/metadamageprofiler-conda/main/init.sh | bash
```

Now you can run metadamageprofiler by just running:
```console
$ ./metadamageprofiler.sh
```

---

## Usage:

__metadamageprofiler__ works by first creating a config file using the `config` command. This file contains all of the information related to __metadamageprofiler__ such that you only have to type this once. The config file is saved in the current directory as `config.yaml` and can subsequently be edited in any text editor of your like.

After the config has been created, we run the actual programme using the `compute` command. This can take a while depending on the number (and size) of the files.

Finally the results are saved in `{storage-path}/results` directory (`data/results` by default). These can be viewed with the interactivet dashboard using the `dashboard` command.


---

## `config` CLI options:

__metadamageprofiler__ takes a single argument, `samples`, and a bunch of additional options. The `samples` refer to a single or multiple alignment-files (or a directory containing them), all with the file extensions: `.bam`, `.sam`, and `.sam.gz`.

The options are listed below:


- Input files:
  - `--names`: Path to the (NCBI) `names.dmp.gz`. Mandatory.
  - `--nodes`: Path to the (NCBI) `nodes.dmp.gz`. Mandatory.
  - `--acc2tax`: Path to the (NCBI) `acc2tax.gz`. Mandatory.

- ngsLCA parameters:
  - `--simscorelow`: Normalized edit distance (read to reference similarity) minimum. Number between 0-1 (default is 0.95).
  - `--simscorehigh`: Normalized edit distance (read to reference similarity) maximum. Number between 0-1 (default is 1.0).
  - `--editdistmin`: Minimum edit distance (read to reference similarity). Number between 0-10 (default is 0).
  - `--editdistmax`: Maximum edit distance (read to reference similarity). Number between 0-10 (default is 10).
  - `--minmapq`: Minimum mapping quality.
  - `--max-position`: Maximum position in the sequence to include. Default is +/- 15 (forward/reverse).
  - `--lca-rank`: The LCA rank used in ngsLCA. Can be either `family`, `genus`, `species` or `""` (everything). Default is `""`.

- General parameters:
  - `--storage_path`: Path where the generated output files and folders are stored.
  - `--cores`: The maximum number of cores to use.

- Boolean flags (does not take any values, only the flag). Default is false.
  - `--bayesian`: Include a fully Bayesian model (probably better, but also _a lot_ slower, about a factor of 100).

<!-- - Other:
  - `--help`: Print the help documentation and exit.
  - `--version`: Print the current version of the program and exit. -->


### `config` Examples:

The __metadamageprofiler__ configs can be created e.g. as:

```console
$ ./metadamageprofiler.sh config ./raw_data/example.bam \
    --names raw_data/names.dmp.gz \
    --nodes raw_data/nodes.dmp.gz \
    --acc2tax raw_data/combined_taxid_accssionNO_20200425.gz
```

__metadamageprofiler__ is pretty versatile regarding it's input argument and accepts also multiple alignment files:
```console
$ ./metadamageprofiler.sh config ./raw_data/*.bam [...]
```
or even an entire directory containing alignment files (`.bam`, `.sam`, and `.sam.gz`):
```console
$ ./metadamageprofiler.sh config ./raw_data/ [...]
```

---


## `compute` CLI options:

Any normal snakemake commands.
By defualt is running with `-p` and the number of cores specified in the config.

### `compute` Examples:

```console
$ ./metadamageprofiler.sh compute
```

---

## `dashboard` CLI options:


### `dashboard` Examples:

```console
$ ./metadamageprofiler.sh dashboard
```

---

## Installations Guides:

If you already have [conda](https://docs.conda.io/en/latest/) installed, you can just install mamba into the base environment:

```console
$ conda install mamba -n base -c conda-forge
```

If you do not have conda installed, fear not, you just have to run the following two commands:
```console
$ wget https://github.com/conda-forge/miniforge/releases/latest/download/Mambaforge-$(uname)-$(uname -m).sh
$ bash Mambaforge-$(uname)-$(uname -m).sh
```

while remembering to answer `yes` when the question arises:

```
Do you wish the installer to initialize Mambaforge
by running conda init?
```