diff --git a/docs/additional_commands.rst b/docs/additional_commands.rst index de4dc05..282e5e6 100644 --- a/docs/additional_commands.rst +++ b/docs/additional_commands.rst @@ -8,7 +8,11 @@ To make using pVAC-Seq easier several convenience methods are included in the pa Download Example Data --------------------- -.. argparse:: +.. topic:: For usage instructions run + + ``pvacseq download_example_data --help`` + +.. .. argparse:: :module: lib.download_example_data :func: define_parser :prog: pvacseq download_example_data @@ -18,15 +22,25 @@ Download Example Data Install VEP Plugin ------------------ -.. argparse:: +.. topic:: For usage instructions run + + ``pvacseq install_vep_plugin --help`` + +.. .. argparse:: :module: lib.install_vep_plugin :func: define_parser :prog: pvacseq install_vep_plugin +.. _valid_alleles: + List Valid Alleles ------------------ -.. argparse:: +.. topic:: For usage instructions run + + ``pvacseq valid_alleles --help`` + +.. .. argparse:: :module: lib.valid_alleles :func: define_parser :prog: pvacseq valid_alleles @@ -34,7 +48,11 @@ List Valid Alleles Documentation For Configuration Files ------------------------------------- -.. argparse:: +.. topic:: For usage instructions run + + ``pvacseq config_files --help`` + +.. .. argparse:: :module: lib.config_files :func: define_parser :prog: pvacseq config_files diff --git a/docs/conf.py b/docs/conf.py index dd97a19..6ad8eb6 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -33,7 +33,7 @@ extensions = [ 'sphinx.ext.autodoc', 'sphinx.ext.coverage', - 'sphinxarg.ext', + #'sphinxarg.ext', ] # Add any paths that contain templates here, relative to this directory. diff --git a/docs/filter_commands.rst b/docs/filter_commands.rst index 014cab6..3f84f5a 100644 --- a/docs/filter_commands.rst +++ b/docs/filter_commands.rst @@ -10,23 +10,31 @@ Both filters can also be run manually to narrow the final results down further. Binding Filter -------------- -.. argparse:: +.. topic:: For usage instructions run + + ``pvacseq binding_filter --help`` + +.. .. argparse:: :module: lib.binding_filter :func: define_parser :prog: pvacseq binding_filter - The binding filter filters out variants that don't pass the chosen binding threshold. The user can chose whether to apply this filter to the "lowest" or the "median" binding affinity score. The "lowest" binding affinity score is recorded in the "Best MT Score" column and represents the lowest ic50 score of all prediction algorithms that were picked during the previous pVAC-Seq run. The "median" binding affinity score is recorded in the "Median MT Score" column and corresponds to the median ic50 score of all prediction algorithms used to create the report. +The binding filter filters out variants that don't pass the chosen binding threshold. The user can chose whether to apply this filter to the "lowest" or the "median" binding affinity score. The "lowest" binding affinity score is recorded in the "Best MT Score" column and represents the lowest ic50 score of all prediction algorithms that were picked during the previous pVAC-Seq run. The "median" binding affinity score is recorded in the "Median MT Score" column and corresponds to the median ic50 score of all prediction algorithms used to create the report. - The binding filter also offers the option to filter on Fold Change columns, which contain the ratio of the MT score to the WT Score. If the binding filter is set to "best", the "Corresponding Fold Change" column will be used. ("Corresponding WT Score"/"Best MT Score"). If the binding filter is set to "median", the "Median Fold Change" column will be used ("Median WT Score"/"Median MT Score"). +The binding filter also offers the option to filter on Fold Change columns, which contain the ratio of the MT score to the WT Score. If the binding filter is set to "best", the "Corresponding Fold Change" column will be used. ("Corresponding WT Score"/"Best MT Score"). If the binding filter is set to "median", the "Median Fold Change" column will be used ("Median WT Score"/"Median MT Score"). Coverage Filter --------------- -.. argparse:: +.. topic:: For usage instructions run + + ``pvacseq coverage_filter --help`` + +.. .. argparse:: :module: lib.coverage_filter :func: define_parser :prog: pvacseq coverage_filter - If a pVAC-Seq process has been run with bam-readcount or Cufflinks input files then the coverage_filter can be run again on the final report file to narrow down the results even further. +If a pVAC-Seq process has been run with bam-readcount or Cufflinks input files then the coverage_filter can be run again on the final report file to narrow down the results even further. - If no additional coverage input files have been provided to the main pVAC-Seq run then this information would need to be manually added to the report in order to run this filter. +If no additional coverage input files have been provided to the main pVAC-Seq run then this information would need to be manually added to the report in order to run this filter. diff --git a/docs/frequently_asked_questions.rst b/docs/frequently_asked_questions.rst new file mode 100644 index 0000000..80e72b3 --- /dev/null +++ b/docs/frequently_asked_questions.rst @@ -0,0 +1,167 @@ +.. raw:: html + + + + + +Frequently Asked Questions +========================== + +.. role:: large +.. role:: large-code + +:large:`My pVAC-Seq command has been running for a long time. Why is +that?` + +The rate-limiting factor in running pVAC-Seq is the number of calls that are +made to the IEDB software for binding score predictions. + +.. note:: + + It is generally faster to make IEDB calls using a local install of IEDB than + using the IEDB web API. It is, therefore, recommended to use a local IEDB + install for any in-depth analysis. + +There are a number of factors that determine the number of IEDB calls to be made: + +- Number of variants in your VCF + + pVAC-Seq will make predictions for each missense, inframe indel, and + frameshift variant in your VCF. + + **Speedup suggestion**: Split the VCF into smaller subsets and process each one + individually, in parallel. + +- Number of transcripts for each variant + + pVAC-Seq will make predictions for each transcript of a supported variant + individually. The number of transcripts for each variant depends on how VEP was + run when the VCF was annotated. + + **Speedup suggestion**: Use the ``--pick`` option when running VEP to + annotate each variant with the top transcript only. + +- The ``--fasta-size`` parameter value + + pVAC-Seq takes an input VCF and creates a wildtype and a mutant + fasta for each transcript. The number of fasta entries that get submitted + to IEDB at a time is limited by the ``--fasta-size`` parameter in order + to reduce the load on the IEDB servers. The smaller the fasta-size, the + more calls have to be made to IEDB. + + **Speedup suggestion**: When using a local IEDB install, increase the size + of this parameter. + +- Number of prediction algorithms, epitope lengths, and HLA-alleles + + One call to IEDB is made for each combination of these parameters for each chunk + of fasta sequences. That means, for example, when 7 prediction + algorithms, 4 epitope lengths, and 6 HLA-alleles are chosen, 7*4*6=168 calls to + IEDB have to be made for each chunk of fastas. + + **Speedup suggestion**: Reduce the number of prediction algorithms, + epitope lengths, and/or HLA-alleles to the ones that will be the most + meaningful for your analysis. For example, the NetMHCcons method is + already a consensus method between NetMHC, NetMHCpan, and PickPocket. + If NetMHCcons is chosen, you may want to omit the underlying prediction + methods. Likewise, if you want to run NetMHC, NetMHCpan, and PickPocket + individually, you may want to skip NetMHCcons. + +- ``--downstream-sequence-length`` parameter value + + This parameter determines how many amino acids of the downstream sequence after a + frameshift mutation will be included in the wildtype fasta sequence. The + shorter the downstream sequence length, the lower the number of epitopes + that IEDB needs to make binding predictions for. + + **Speedup suggestion**: Reduce the value of this parameter. + +:large:`My pVAC-Seq output file does not contain entries for all of the +alleles I chose. Why is that?` + +There could be a few reasoans why the pVAC-Seq output does not contain +predictions for alleles: + +- The alleles you picked might've not been compatible with the prediction algorithm and/or epitope lengths chosen. In that case no calls for that allele would've been made and a status message would've printed to the screen. + +- It could be that all epitope predictions for some alleles got filtered out. You can check the ``.combined.parsed.tsv`` file to see all called epitopes before filtering. + +:large:`Why are some values in the` :large-code:`WT Epitope Seq` :large:`column` :large-code:`NA` :large:`?` + +Not all mutant epitope sequences will have a corresponding wildtype epitope sequence. This +occurs when the mutant epitope sequence is novel and a comparison is therefore not +meaningful: + +- An epitope in the downstream portion of a frameshift might not have a corresponding wildtype epitope at the same position at all. The epitope is completely novel. + +- An epitope that overlaps an inframe indel or multinucleotide polymorphism (MNP) might have a large number of amino acids that are different from the wildtype epitope at the corresponding position. If less than half of the amino acids between the mutant epitope sequence and the corresponding wildtype sequence match, the corresponding wildtype sequence in the report is set to ``NA``. + +:large:`What filters are applied during a pVAC-Seq run?` + +By default we filter the neoepitopes on their binding score. If bam-readcount +files and/or cufflinks files are provided we also filter on the depth, VAF, +and FPKM. In addition, candidates where the mutant epitope sequence is the +same as the wildtype epitope sequence will also be filtered out. + +:large:`How can I see all of the candidate epitopes without any filters +applied?` + +The ``.combined.parsed.tsv`` will contain all of the epitopes predicted +before filters are applied. + +:large:`Why have some of my epitopes been filtered out even though the` :large-code:`Best MT Score` :large:`is below 500?` + +By default, the binding filter will be applied to the ``Median MT Score`` +column. This is the median score value among all chosen prediction algorithms. +The ``Best MT Score`` column shows the lowest score among all +chosen prediction algorithms. To change this behavior and apply the binding +filter to the ``Best MT Score`` column you may set the ``--top-score-metric`` +parameter to ``lowest``. + +:large:`Why are entries with` :large-code:`NA` :large:`in the` +:large-code:`VAF` :large:`and` :large-code:`depth` :large:`columns not +filtered?` + +We do not filter out ``NA`` entries for depth and VAF since there is not +enough information to determine whether the cutoff has been met one way or another. + +:large:`Why don't some of my epitopes have score predictions for certain prediction methods?` + +Not all prediction methods support all epitope lengths or all alleles. To see +a list of supported alleles for a prediction method you may use the +``pvacseq valid_alleles`` :ref:`command `. For more details on +each algorithm refer to the IEDB MHC `Class I `_ +and `Class II `_ documentation. + + +:large:`How do I use StringTie instead of Cufflinks for transcript/gene abundance +estimates?` + +You may also provide FPKM values from other sources, including StringTie, by creating +`cufflinks-formatted input files +`_. + +**For transcript FPKM**: a tab-separated file with a ``tracking_id`` column +containing Ensembl transcript IDs and a ``FPKM`` column containing +FPKM values. + +**For gene FPKM**: a tab-separated file with a ``tracking_id`` column +containing Ensembl gene IDs, a ``locus`` column describing the +region within the gene, and a ``FPKM`` column containing FPKM values. In the +pVAC-Seq pipeline the FPKM values will be summed for all loci of a gene. You +may also provide already summed FPKM values. In that case you will still need +to provide a ``locus`` column but the values in that column can be empty. + +:large:`How is pVAC-Seq licensed?` + +pVAC-Seq is licensed under `NPOSL-3.0 +`_. + +:large:`How do I cite pVAC-Seq?` + +Jasreet Hundal, Beatriz M. Carreno, Allegra A. Petti, Gerald P. Linette, Obi +L. Griffith, Elaine R. Mardis, and Malachi Griffith. `pVAC-Seq: A genome-guided +in silico approach to identifying tumor neoantigens `_. Genome Medicine. 2016, +8:11, DOI: 10.1186/s13073-016-0264-5. PMID: `26825632 +`_. + diff --git a/docs/index.rst b/docs/index.rst index cc841cd..13ab162 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -9,7 +9,7 @@ pVAC-Seq pVAC-Seq is a cancer immunotherapy pipeline for the identification of **p**\ ersonalized **V**\ ariant **A**\ ntigens by **C**\ ancer **Seq**\ uencing (pVAC-Seq) that integrates tumor mutation and expression data (DNA- and RNA-Seq). It enables cancer immunotherapy research by using massively parallel sequence data to predicting tumor-specific mutant peptides (neoantigens) that can elicit anti-tumor T cell immunity. It is being used in studies of checkpoint therapy response and to identify targets for cancer vaccines and adoptive T cell therapies. For more general information, see the `manuscript published in Genome Medicine `_. .. toctree:: - :maxdepth: 3 + :maxdepth: 2 features install @@ -18,6 +18,7 @@ pVAC-Seq is a cancer immunotherapy pipeline for the identification of **p**\ ers filter_commands additional_commands optional_downstream_analysis_tools + frequently_asked_questions contact New in version |version| diff --git a/docs/install.rst b/docs/install.rst index 593e7dc..591c3e3 100644 --- a/docs/install.rst +++ b/docs/install.rst @@ -84,7 +84,14 @@ ____________ tar -zxvf IEDB_MHC_II-2.16.tar.gz cd mhc_ii ./configure.py - + +Open the ``configure.py`` file and update the lines that set the ``smm`` and ``nn`` variables to use relative paths like so: + +.. code-block:: none + + smm = re.compile(curDir + "/netMHCII-1.1") + nn = re.compile(curDir + "/netMHCII-2.2") + .. note:: Running the ``configure`` script requires a Python 2 environment. If you are currently emulating a Python 3 environment with Conda you will need to run ``source deactivate`` before executing the ``configure`` script. diff --git a/docs/optional_downstream_analysis_tools.rst b/docs/optional_downstream_analysis_tools.rst index 59be6f0..ada2a1b 100644 --- a/docs/optional_downstream_analysis_tools.rst +++ b/docs/optional_downstream_analysis_tools.rst @@ -6,7 +6,11 @@ Optional Downstream Analysis Tools Generate Protein Fasta ---------------------- -.. argparse:: +.. topic:: For usage instructions run + + ``pvacseq generate_protein_fasta --help`` + +.. .. argparse:: :module: lib.generate_protein_fasta :func: define_parser :prog: pvacseq generate_protein_fasta diff --git a/docs/prerequisites.rst b/docs/prerequisites.rst index 35e9eea..6ca166d 100644 --- a/docs/prerequisites.rst +++ b/docs/prerequisites.rst @@ -31,6 +31,12 @@ To create a VCF for use with pVAC-Seq follow these steps: The ``--dir_plugins `` option may need to be set depending on where the VEP_plugins were installed to. +The ``--pick`` option might be useful to limit the annotation to the top +transcripts. Otherwise, VEP will annotate each variant with all possible +transcripts. pVAC-Seq will provide predictions for all transcripts in the VEP +CSQ field. Running VEP without the ``--pick`` option can therefor drasticly +increase the runtime of pVAC-Seq. + Additional VEP options that might be desired can be found `here `_. **Example VEP Command** @@ -45,6 +51,9 @@ Additional VEP options that might be desired can be found `here + +You may also provide FPKM values from other sources by creating +cufflinks-formatted input files. + +**For transcript FPKM**: a tab-separated file with a ``tracking_id`` column +containing Ensembl transcript IDs and a ``FPKM`` column containing +FPKM values. + +**For gene FPKM**: a tab-separated file with a ``tracking_id`` column +containing Ensembl gene IDs, a ``locus`` column describing the +region within the gene, and a ``FPKM`` column containing FPKM values. In the +pVAC-Seq pipeline the FPKM values will be summed for all loci of a gene. You +may also provide already summed FPKM values. In that case you will still need +to provide a ``locus`` column but the values in that column can be empty. diff --git a/docs/run.rst b/docs/run.rst index 91901c6..2637e0a 100644 --- a/docs/run.rst +++ b/docs/run.rst @@ -9,7 +9,11 @@ Usage prediction algorithms. More information on how to install IEDB locally can be found on the :ref:`Installation ` page. -.. argparse:: - :module: lib.main - :func: define_parser - :prog: pvacseq run +.. topic:: For usage instructions run + + ``pvacseq run --help`` + +.. .. argparse:: + :module: lib.main + :func: define_parser + :prog: pvacseq run diff --git a/pvacseq/pvacseq.py b/pvacseq/pvacseq.py index 0c2d965..068ba90 100644 --- a/pvacseq/pvacseq.py +++ b/pvacseq/pvacseq.py @@ -5,7 +5,7 @@ import pkg_resources try: from . import lib -except SystemError: +except (SystemError, ImportError): import lib def main():