Metadata-Version: 2.4
Name: ipnpa
Version: 0.3.2
Author: Luka PAVAGEAU
Keywords: bioinformatics,NGS,next generation sequencing,variant calling,CNV,copy number alterations,copy number variations
Description-Content-Type: text/markdown
License-File: COPYING
Dynamic: author
Dynamic: license-file

# infer purity for NGS panel

This tool takes 2 files to infer the purity and ploidy of a sample : 
- a segmented copy ratio file (.cns) that is the output of `cnvkit.py segment`
- a vcf file with SNPs

It outputs 2 files : 
- a json file with the inferred purity for each ploidy option as well as the best guess
- a png plot showing how the purity was chosen 

## Usage
```
usage: ipnpa [-h] cns vcf json png

positional arguments:
  cns         A segmented copy ratios (.cns) file
  vcf         A vcf file with sample's SNPs
  json        Path to the output json file
  png         Path to the output png file

```
### additional scripts
```

usage: expected_BAFs [-h] [-n N_ALLELES] [-p PURITY]

Given a ploidy and a purity, returns the expected BAFs

options:
  -h, --help            show this help message and exit
  -n N_ALLELES, --n-alleles N_ALLELES
                        The number of alleles (eg the copy number)
  -p PURITY, --purity PURITY
                        Sample purity, given as a float between 0 and 1
```
```
usage: expected_logRs [-h] [-b BASE_PLOIDY] [-p PURITY]

Given a ploidy and a purity, returns the expected log ratios matching several CN options

options:
  -h, --help            show this help message and exit
  -b BASE_PLOIDY, --base_ploidy BASE_PLOIDY
                        The overall ploidy of the sample
  -p PURITY, --purity PURITY
                        Sample purity, given as a float between 0 and 1

```
```
usage: log2cn [-h] [-p PURITY] [-b BASE_PLOIDY] log

Given a log ratio and an optional ploidy/purity, returns the copy number corresponding to the logR

positional arguments:
  log                   Log ratio

options:
  -h, --help            show this help message and exit
  -p PURITY, --purity PURITY
                        Sample purity, given as a float between 0 and 1
  -b BASE_PLOIDY, --base_ploidy BASE_PLOIDY
                        The overall ploidy of the sample
```

This program is inspired by [ascatNgs](http://dx.doi.org/10.1002/cpbi.17)

## example output plot

![](doc/example.png)

## algorithm

For purity values between 0.35 and 1, and ploidy values in between 1 and 4.5, a "cost" is computed as the combinations of two values : 
- the distance between the expected logR and the observed logR given in the cns file
- the distance between the expected BAFs and the observed AFs given in the VCF file. 
    - This value takes into account the integer copy number (CN) that is expected with the given logR, and tries to minimize the cost acording to the different possible combinations of minor/major alleles. 
    - It also tests if the observed BAFs are more coherent with CN+/-1 and increasess the cost if it's the case  

These values are summed for each segment and this cost is what is reported on the different plots.

## interpretation of the "call" plots

The upper subplot represents the segmented copy numbers, and the call made for each segment as a minor/major allele in blue/pink. The black line gives the "true" logR, whereas the pink line give the total called CN.

In the cases where the BAF distribution is incoherent with the CN call, an additional orange line appears on the segment at the CN value that matches best with it. The width of this line is proportional to the probability of error : large lines are symptomatic of incompatibilities between the call and the observed data.

The lower subplot represents the BAFs, with the observed values as grey points and the call as blue/pink lines. It highlights the cohrence between the data and the model.

## installation

```sh
python -m pip install git+ssh://git@gitlab.com/ugm-bioinfo/ipnpa.git
```

## generating the SNPs vcf

To properly estimate the purity, this file must contain only snips. This is achieved by either : 
- calling the germline and somatic variants, and retaining only the germline variants
- using a SNP database such as gnomad and filtering the calls based on the known snips : 
```sh
# gnomad database is available here : 
wget https://storage.googleapis.com/gatk-best-practices/somatic-hg38/af-only-gnomad.hg38.vcf.gz 
wget https://storage.googleapis.com/gatk-best-practices/somatic-hg38/af-only-gnomad.hg38.vcf.gz.tbi 
```

## advanced usage

For common use, the output plots and json are self-sufficient, but sometimes the call will be wrong due to various reasons (mainly subclones messing with the purity).

In these cases, it can be interesting to manually inspect the data and plot the models for other values of ploidy/purity. This is achievable in a jupyter notebook : 

```py
import ipnpa
import numpy as np

data, base_infos, size_by_chro, filtered = ipnpa.segmented_vars("sample.segments.cns", "sample.vcf")
result = ipnpa.analyse_purity(data, base_infos, size_by_chro, filtered, "sample name", tested_ploidy = [round(x, 2) for x in np.linspace(1.5, 4.5, 40)])

# show the main plot
main_plot = result.global_plot()

# plot another model
base_ploidy = 2.59
purity = 0.45
model_figure = result.plot_model(base_ploidy, purity)
```
