Usage (advanced)
============

## General Note

If working with extraordinarily large VCF files (>= 1Mb), the following processing steps are likely to be very slow. 
Before starting it might be a good idea to trim down your VCF files to only the region/chromosome of interest, using something like [bcftools](http://samtools.github.io/bcftools/bcftools-man.html#view). 

## Filtering germline variants

If you have access to germline or "normal" tissue, then `germline-filter` is a good place to start. 
All you have to do is provide a simple metadata file that links each tumor sample to its corresponding normal sample. 
For example: 
```
tumor_sample_id,normal_sample_id
sample1,gl_sample1
sample2,gl_sample1
sample3,gl_sample2
sample4,gl_sample2
sample5,gl_sample2
```
Once you have made this metadata file you're ready to run `germline-filter.` 
An example command line:   
```
cerebra germline-filter --processes 2 --normal_path /path/to/normal/vcfs --tumor_path /path/to/tumor/vcfs --metadata /path/to/metadata/file --outdir /path/to/filtered/vcfs
```

This will create a new directory (`/path/to/filtered/vcfs/`) that contains a set of entirely new VCFs. 

## Counting variants 

The module `count-variants` module can be run after `germline-filter`, on the new vcfs contained in `/path/to/filtered/vcfs/`.
However, `germline-filter` is entirely optional -- if you dont have access to germline or "normal" samples, `count-variants` is the place to start. 
An example command line:   
```
cerebra count-variants --processes 2 --cosmicdb /optional/path/to/cosmic/database --refgenome /path/to/genome/annotation --outfile /path/to/output/file /path/to/filtered/vcfs/*
```

NOTE that the cosmic database is also optional. If you'd like you can download one of the database files from [here](https://cancer.sanger.ac.uk/cosmic/download), however, you can also run `count-variants` without this option. 

## Finding peptide variants

Like `count-variants`, `find-peptide-variants` is a standalone module. 
You can run it on the VCFs generated by `germline-filter` or on unfiltered VCFs. 
Also like `count-variants`, this module gives you the option of filtering through a cosmic database. 
An example command line:   
```
cerebra find-peptide-variants --processes 2 --cosmicdb /optional/path/to/cosmic/database --annotation /path/to/genome/annotation --genomefa /path/to/genome/fasta --report_coverage 1 --output /path/to/output/file /path/to/filtered/vcfs/*
```

`report_coverage` is a BOOLEAN option will report counts for both variant and wildtype reads at all variant loci.
`--report_coverage 1` turns this option on, while `--report_coverage 0` turns it off.
We reasoned that variants with a high degree of read support are less likely to be false positives. 
This option is designed to give the user more confidence in individual variant calls.

For example, when run on the pre-packaged test VCF set (_cerebra/tests/data/test_find_peptide_variants/vcf_),    
`cerebra find-peptide-variants --report_coverage 1` should yield the following (partial) entry:

```
A1,['ENSP00000395243.3:p.(Leu813delinsArgTrp),[2:0]', 'ENSP00000415559.1:p.(Leu813delinsArgTrp),[2:0]'],
```
This tells us that the sample _A1_ contains likely variants in the Ensembl peptide IDs _ENSP00000395243.3_ and _ENSP00000415559.1_. 
Both variants are insertions of _ArgTrp_ in place of _Leu_ at the 813th amino acid.

The [_x_:_y_] string represents the absolute number of variant and wildtype reads at that loci. 
Thus [2:0] means 2 variant reads and 0 wildtype reads were found at each of these loci. 
A coverage string in the format of [_x_:_y_:_z_] would indicate there are two variant alleles at a given loci, _x_ and _y_, in addition to wildtype, _z_. 

## Testing

First install the packages specified in [test_requirements.txt](https://github.com/czbiohub/cerebra/blob/master/test_requirements.txt). 
Now you should be able to run:

` $ make test `

If you've installed `cerebra` in a virtual environment make sure the environment is active. 
Confirm that all tests have passed.
If otherwise, feel free to submit an [issue report](https://github.com/czbiohub/cerebra/blob/master/docs/CONTRIBUTING.md). 
