Package: cerebra
cerebraWhat iscerebra?This tool allows you to quickly summarize and interpret VCF files.If you're interested in learning the full complement of genomic variants present in your DNA/RNA samples, a typical workflow might involve sequencing, followed by variant calling with a tool such as GATKHaplotypeCaller, which generatesvariant calling format(VCF) files.A VCF file looks like this:##source=HaplotypeCaller
#CHROM POS ID REF ALT QUAL FILTER INFO FORMAT
chr1 631391 . C T 72.28 . AC=2;AF=1.00;AN=2;DP=2;ExcessHet=3.0103;FS=0.000;MLEAC=1;MLEAF=0.500;MQ=NaN;QD=25.36;SOR=2.303 GT:AD:DP:GQ:PL 1/1:0,2:2:6:84,6,0Note that only a single VCF record is displayed here.
A sequencing run can generate on the order of 108unique VCF records.
Only a small portion of these VCF records are likely to be relevant to the researcher.
Thus drawing conclusions from VCF files remains a substantial challenge.cerebraprovides a fast and intuitive framework for summarizing VCF records across samples.
It comprises three modules that do the following:1) remove germline variants from samples of interest        
    2) count the total number of variants in a given sample, on a per-gene basis           
    3) report protein variants for each samplecerebragets its name from the eponymous X-mencharacter, who had the ability to detect mutant individuals among the general public.If you're working with tumor data, it might be a good idea to limit the variant search space to only known, and potentially actionable, cancer variants.
Thereforecerebraimplements an optional method for restricting to variants also found in theCOSMICdatabase.This tool was developed for, but is certainly not limited to, single-cell RNA sequencing data.cerebrais free software available under the MIT license.What makescerebradifferent from traditional VCF parsers?Python libraries exist (i.e.PyVCFandvcfpy) for extracting information from VCF files.
Another isGATK VariantsToTable, which produces a file that looks like this:CHROM    POS ID      QUAL    AC
 1        10  .       50      1
 1        20  rs10    99      10This table contains only genomic (i.e.DNA-level) coordinates.
Often the next questions are: what are the genes associated with these variants, and what are the peptide-level effects of these variants?cerebraqueries a reference genome (.fa) and annotation (.gtf) to match each DNA-level variant with its associated gene, and its probable protein variant.cerebraproduces the following outfile:$ python
> import json
> f = open(/path/to/cerebra/output.json)
> data = json.load(f)
> print(json.dumps(data, indent=4))

{
    "CCN1": {
        "A16_B000563": [],
        "A1_B001546": [],
        "A1_B002531": [
            "ENSP00000398736.2:p.(Glu189=)"
        ],
        "A1_B002570": [],
        "A2_B002558": [],
        "A3_B000561": [
            "ENSP00000398736.2:p.(Arg209Trp)",
            "ENSP00000398736.2:p.(Ile90Val)"
        ],
        "A3_B000568": [],
        "A3_B001544": [
            "ENSP00000398736.2:p.(Ala82Thr)"
        ],
        "A3_B002090": [],
        "A3_B002531": [
            "ENSP00000398736.2:p.(Pro217Ser)"
        ]
    }
}HereCCN1is a gene name whileA16_B000563,A1_B001546,A1_B002531,... are RNA-seq sample IDs.cerebrareports variants to every gene in the genome, for every sample in a given experiment.
TheENSP*numbers refer toEnsembltranslation IDs -- unique identifiers that correspond to exactly one polypeptide in the Ensembl database.
The strings enclosed in parentheses refer to the amino-acid level variants reported in that particular sample.
For example the stringArg209Trpindicates that position 209 of this particular polypeptide should contain anArg, but the experimental sample instead contains aTrp.cerebraadheres to HGVS sequence variantnomenclaturein reporting amino-acid variants.Featuresgermline-filterVariant calling is often applied to the study of cancer.
If the research project is centered around a “tumor vs. normal” question, thengermline-filteris the proper starting point.
This module removes germline variants that are common between tumor and normal samples, and thus excludes variants unlikely to be pathogenic for the cancer under study.
The user provides a very simple metadata file (seeUSAGE.md) that indicates which tumor samples correspond to which normal samples.
The output of germline-filter is a set of trimmed-down VCF files, which will be used for the next two steps.
If you do not have access to “normal” samples then proceed directly tocount-variantsorfind-peptide-variants.count-variantsThis module reports the raw variant counts for every gene across every sample.
The output is a CSV file that contains counts for each sample versus every gene in the genome.
If working with cancer variants, the user has the option of limiting the search space to variants also found in theCOSMICdatabase.find-peptide-variantsThis module reports the protein variations associated with each genomic variant.
VCF records are converted to peptide-level variants, and thenENSEMBLprotein IDs,
in accordance to theHGVSsequence variant nomenclature.
The output is a hierarchically ordered text file (CSV or JSON) that reports the Ensemble protein ID and the gene associated with each variant, for each experimental sample.
The user again has the option of limiting the search space to variants also found in theCOSMICdatabase.
This module also has an option to report the number of variant vs. wildtype reads found at each locus.Dependenciescerebradepends on some (fairly standard) packages and libraries.
Before installing, it might be a good idea to make sure all of the requisite packages are installed on your system (note:if installing with Docker you can skip this step).MacOS Dependencies:sudo pip install setuptools
brew update
brew install openssl
brew install zlibLinux Dependencies:sudo apt-get install autoconf automake make gcc perl zlib1g-dev libbz2-dev liblzma-dev libcurl4-gnutls-dev libssl-devAs of presentcerebrais not installable on Windows.cerebradepends on thepysamlibrary (or rather,pysamis a dependency-of-a-dependency) and currently this library is only available on Unix-like systems.
Windows solutions likeWSLexist for overcoming precisely this challenge, however,cerebrahas not been tested on WSL or any other Unix-like subsystem for Windows.Installation (for users)There are four different methods available to installcerebra.
Choose one of the following:WithDocker(recommended)docker pull lincolnharris/cerebra
docker run -it lincolnharris/cerebrawarning: this image will take up ~1Gb of space.With the python standard libraryvenvmodulepython3 -m venv cerebra
source cerebra/bin/activate
pip3 install cerebraWithcondaconda create -n cerebra python=3.7
conda activate cerebra
pip3 install cerebraFromPyPi(system-wide installation, NOT RECOMMENDED)For novice users, it's generally a better idea to install packages within virtual environments.
However,cerebracan be installed system-wide, if you so choose.pip3 install cerebra

# OR, if you dont have root privileges
pip3 install --user cerebraInstallation (for developers)Here's how to set up cerebra for local development.
After installing the requisitedependencies:Fork thecerebrarepo on GitHub:https://github.com/czbiohub/cerebraClone your fork locally:$ git clone https://github.com/your-name/cerebra.gitInstall your local copy into a virtualenv. Using the standard libraryvenvmodule:$ cd cerebra
$ python3 -m venv cerebra-dev
$ source cerebra-dev/bin/activate
$ pip3 install -r requirements.txt -r test_requirements.txt -e .Create a branch for local development:$ git checkout -b name-of-your-bugfix-or-featureNow you can make your changes locally.When you're done making changes, check that your changes passflake8andpytest:$ make test
$ make coverage
$ make lintCommit your changes and push your branch to GitHub:$ git add .
$ git commit -m "Your detailed description of your changes."
$ git push origin name-of-your-bugfix-or-featureSubmit a pull request through the GitHub website.
SeeCONTRIBUTING.mdfor more.(Quickstart) Usage$ cerebrashould return usage informationUsage: cerebra  <command>

  a tool for fast and accurate summarizing of variant calling format (VCF)
  files

Options:
  -h, --help  Show this message and exit.

Commands:
  germline-filter    filter out common SNPs/indels between tumor and normal samples
  count-variants    count total number of variants in each sample, and report on a per-gene basis
  find-peptide-variants  report peptide-level SNPs and indels in each sample, and associated coverageNote that the-hcommand will display usage information for each of the three commands.An example workflow might look like this:Step 1: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/vcfsStep 2: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/*Step 3: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/*For advanced usage information, seeUSAGE.md.AuthorsThis work was produced byLincoln Harris,Rohan Vanheusden,Olga BotvinnikandSpyros Darmanisof the Chan Zuckerberg Biohub.
For questions please contactljharris018@gmail.comContributingWe welcome any bug reports, feature requests or other contributions.
Please submit a well documented report on ourissue tracker.
For substantial changes please fork this repo and submit a pull request for review.SeeCONTRIBUTING.mdfor additional details.You can find official releaseshere.