# <p align="center"><img src="resources/predictosaurus.svg" alt="predictosaurus" style="width: 50%;"></p>



[![codecov](https://codecov.io/gh/fxwiegand/predictosaurus/graph/badge.svg?token=OSD3PSBS4L)](https://codecov.io/gh/fxwiegand/predictosaurus)
![Conda Version](https://img.shields.io/conda/v/bioconda/predictosaurus?label=bioconda)
![Conda Downloads](https://img.shields.io/conda/d/bioconda/predictosaurus?label=downloads)

> [!CAUTION]
> **This tool is still experimental!**
> This means it may have bugs, and features are subject to change. Use it cautiously, and share feedback to help us improve. 🧪


**Predictosaurus** is a command-line tool designed for uncertainty-aware haplotype-based genomic variant effect prediction. It provides comprehensive functionality for building variant graphs, processing genomic features, and extracting peptide sequences. The tool integrates various bioinformatics processes to support efficient data analysis and visualization.

## Table of Contents

- [Installation](#installation)
- [Usage](#usage)
- [Commands](#commands)
    - [Build](#build)
    - [Process](#process)
    - [Peptides](#peptides)
    - [Plot](#plot)
- [Example](#example)
- [License](#license)

## Installation

To install **Predictosaurus**, you can install it via [Bioconda](https://bioconda.github.io/):

```bash
conda install -c bioconda predictosaurus
```

Alternatively, you can use `cargo`, the Rust package manager:

```bash
cargo install predictosaurus
```

## Usage

Run the tool from the command line using the following syntax:

```bash
predictosaurus <command> [options]
```

Use `predictosaurus --help` to view general help information, or `predictosaurus <command> --help` for specific command details.

## Commands

All commands provide a verbose output with logging information via the `--verbose`/`-v` flag. Additionally the `--threads`/`-t` flag allows for multi-threaded execution. If not specified or `0`, the number of threads is set to the number of available logical cores.

### Build

Builds a full variant graph from VCF files and stores it.

**Options:**

- `--calls <path>`: Path to the VCF calls file.
- `--observations <sample=observations.vcf>`: One or more observation files; ensure sample names match those in the calls file.
- `--min-prob-present <float>`: Minimum probability for a variant to be considered for the graph generation. Defaults to 0.8.
- `--min-vaf <float>`: Minimum VAF for a variant to be considered in the graph. Needs to be higher for at least one of all given samples. Defaults to 0.05.
- `--output <path>`: Path to store the generated variant graphs.

**Example:**

```bash
predictosaurus build --calls path/to/calls.vcf --observations sample1=path/to/observations1.vcf sample2=path/to/observations2.vcf --min-prob-present 0.65 --output path/to/output/graphs.duckdb
```

### Process

Retrieves subgraphs for individual features from the provided GFF file and calculates scores for all haplotypes of each transcript.

**Options:**

- `--features <path>`: Path to the GFF file containing the features of interest.
- `--reference <path>`: Path to the reference genome FASTA file.
- `--graph <path>`: Path to the graph file generated by the build command.
- `--haplotype-metric <string>`: Metric to use for haplotype quantification. Valid values: `product`, `geometric-mean`, `minimum`. Defaults to `geometric-mean`.
- `--output <path>`: Path to the output file storing the calculated scores.

**Example:**

```bash
predictosaurus process --features path/to/features.gff --reference path/to/reference.fasta --graph path/to/graph.duckdb --output path/to/output/scores.duckdb
```

### Peptides

Extracts peptide sequences using the graph generated by the build command. Peptides are extracted for each feature in the provided GFF file and written to a FASTA file.

**Options:**

- `--features <path>`: Path to the GFF file containing the features of interest.
- `--reference <path>`: Path to the reference genome FASTA file.
- `--graph <path>`: Path to the graph file generated by the build command.
- `--interval` <int-int>: An interval defining the length of peptides that will be calculated. Defaults to 8-11.
- `--sample <str>`: Name of the sample to extract peptides for.
- `--events <list of str>`: List of events of interest.
- `--min-event-prob <float>`: The probability of a peptide is calculated by first summing the probabilities of all events provided via --events for each variant that covers the peptide, as well as for any upstream variant that causes a frameshift. These summed probabilities are then multiplied together to determine the final probability of the peptide. The --min-event-prob <float> option specifies the minimum threshold that this probability must meet for the peptide to be considered.
- `--background-events <list of str>`: List of background events.
- `--max-background-event-prob <float>`: Maximum probability of background events. For probability calculations check the `--min-event-prob` option.
- `--output <path>`: Path to the output FASTA file storing the generated peptide sequences.

**Example:**

```bash
predictosaurus peptides --features path/to/features.gff --reference path/to/reference.fasta --graph path/to/graph.duckdb --interval 8-11 --sample sample1 --events event1 --events event2 --min-event-prob 0.8 --background-events event3 --max-background-event-prob 0.2 --output path/to/output/peptides.fasta
```

### Plot

Outputs the calculated scores in one TSV file with columns "transcript", "score", and per-sample likelihood columns (one column per sample).

**Options:**

- `--input <path>`: Path to the input data file generated with the process command.
- `--output <path>`: Path to the output TSV file.

**Example:**

```bash
predictosaurus plot --input path/to/scores.duckdb --output scores.tsv
```

## Example

This is an example of using **Predictosaurus** to build a graph, process it, and output the results:

```bash
# Step 1: Build the variant graph
predictosaurus build --calls calls.vcf --observations sample1=observations1.vcf sample2=observations2.vcf --output graphs.duckdb

# Step 2: Process the graph with a GFF file
predictosaurus process --features features.gff --reference reference.fasta --graph graphs.duckdb --output scores.duckdb

# Step 3: plot visualizations
predictosaurus plot --input scores.duckdb --output scores.tsv
```

## License

**Predictosaurus** is licensed under the [MIT License](LICENSE).
