Update generate protein fasta and create peptide ordering form commands to use transcripts.fa

docs/pvacfuse/optional_downstream_analysis_tools.rst

@@ -7,23 +7,62 @@
 Optional Downstream Analysis Tools
 ==================================
 
+Generate Transcripts Fasta
+--------------------------
+
+.. program-output:: pvacfuse generate_transcripts_fasta -h
+
+This tool will extract matched wild type and fusion transcript protein sequences
+from fusion annotations from AGFusion or Arriba. The resulting file
+is also generated during a pVACfuse run (named ``<sample_name>.transcripts.fa``).
+
+For frameshift fusions, only the 5' fusion partner's wild type transcript sequence
+is included. For inframe fusions, both the 5' and 3' fusion partners' wild type
+transcript sequence is included as separate fasta entries.
+
+The ``--downstream-sequence-length`` controls how many amino acids in the mutated
+sequence following a frameshift fusion are retained. Setting the parameter to
+``full`` will retain the full downstream sequence.
+
 Generate Protein Fasta
 ----------------------
 
 .. program-output:: pvacfuse generate_protein_fasta -h
 
-This tool will extract protein sequences surrounding fusion variant in an by parsing Arriba or AGFusion
-output. One use case for this tool is to help select long peptides that contain short neoepitope 
-candidates. For example, if pVACfuse was run to predict nonamers (9-mers) that are good binders and
-the user wishes to select long peptide (e.g. 24-mer) sequences that contain the nonamer for synthesis
-or encoding in a DNA vector. The fusion position will be centered in the protein sequence returned (if possible).
-If the fusion causes a frameshift, the full downstream protein sequence will be returned unless the user specifies otherwise
-as described above. The ``flanking_sequence_length`` positional parameter
-controls how many amino acids will be included on either side of the mutation.
-
-The output can be limited to only certain variants by providing
-a pVACfuse filtered.tsv report file to the ``--input-tsv`` argument. Only the peptide sequences for the epitopes in the TSV
-will be used when creating the FASTA.
+This tool will extract trimmed wild type protein sequences and matched fusion
+protein sequences from a transcripts.fa file. This file is generated during each
+pVACfuse run or can be regenerated using the ``pvacfuse generate_transcripts_fasta``
+command.
+
+One use case for this tool is to help select long peptides that contain short
+neoepitope candidates. For example, if pVACfuse was run to predict nonamers (9-mers)
+that are good binders and the user wishes to select long peptide (e.g. 24-mer)
+sequences that contain the nonamer for synthesis or encoding in a DNA vector.
+
+The protein sequence extracted will be generated by trimming the sequences in the
+transcripts.fa input file so that the fusion will be centered in the protein sequence
+(if possible). The ``flanking_sequence_length`` positional parameter controls the
+number of amino acids retained around the fusion. If the fusion is near the beginning
+or end of the CDS, it will be as close to center as possible while maintaining the
+desired flanking sequence length. For frameshift fusions the downstream sequence is not
+trimmed. The same amino acids that are trimmed from the mutated protein sequences
+are also trimmed from the matched 5' and 3' (if present) fusion partners' wild type
+sequence. As a result, the starts of the trimmed 5' fusion partner sequence and the
+trimmed fusion sequence line up and - for inframe fusions - the ends of the trimmed 3'
+fusion partner sequence and the trimmed fusions sequence line up. The end of the 5'
+fusion partner sequence and the start of the 3' fusion partner sequence remain
+untrimmed.
+
+The output may be limited to only mutant sequences by setting the ``--mutant-only``
+flag.
+
+The output can be further limited to only certain fusions by providing a pVACfuse
+report file to the ``--input-tsv`` argument. Only the peptide sequences for the
+epitopes in the TSV will be used when creating the FASTA. If this argument is an
+aggregated TSV file, use the ``--aggregate-report-evaluation`` parameter to only
+include peptide sequences for epitopes matching the chosen Evaluation(s). This is
+useful when creating a peptide fasta for vaccine ordering after using pVACview
+to select vaccine candidates and exporting the results to a new TSV.
 
 Generate Aggregated Report
 --------------------------
@@ -46,7 +85,7 @@ TSV & reference_match file pair. It requires the input of a pVACfuse run's fasta
 peptide sequence the epitope was derived from. Any substring of that peptide
 sequence that matches against the reference proteome and is at least as long as the specified match length, will be
 considered a hit. This tool also requires the user to provide a filtered.tsv,
-all_epitopes.tsv or aggregated.tsv pVACseq report file as an input and any
+all_epitopes.tsv or aggregated.tsv pVACfuse report file as an input and any
 candidates in this input file will be searched for.
 
 This tool may be either run with BLASTp using either the ``refseq_select_prot`` or ``refseq_protein`` database.

docs/pvacseq/optional_downstream_analysis_tools.rst

@@ -7,43 +7,64 @@
 Optional Downstream Analysis Tools
 ==================================
 
-Generate Protein Fasta
-----------------------
+Generate Transcripts Fasta
+--------------------------
 
-.. program-output:: pvacseq generate_protein_fasta -h
+.. program-output:: pvacseq generate_transcripts_fasta -h
+
+This tool will extract matched wild type and mutated transcript protein sequences
+for protein altering variants in a VEP-annotated input VCF file. The resulting file
+is also generated during a pVACseq run (named ``<sample_name>.transcripts.fa``).
 
-.. .. argparse::
-    :module: lib.generate_protein_fasta
-    :func: define_parser
-    :prog: pvacseq generate_protein_fasta
-
-This tool will extract protein sequences surrounding supported protein altering variants in an
-input VCF file. One use case for this tool is to help select long peptides that contain short neoepitope 
-candidates. For example, if pvacseq was run to predict nonamers (9-mers) that are good binders and
-the user wishes to select long peptide (e.g. 24-mer) sequences that contain the nonamer for synthesis
-or encoding in a DNA vector. The protein sequence extracted will correspond to the transcript sequence 
-used in the annotated VCF. The alteration in the VCF (e.g. a somatic missense SNV) will be centered in the 
-protein sequence returned (if possible). If the variant is near the beginning or end of the CDS, it will
-be as close to center as possible while returning the desired protein sequence length. If the variant
-causes a frameshift, the full downstream protein sequence will be returned unless the user specifies otherwise 
-as described above. The ``flanking_sequence_length`` positional parameter
-controls how many amino acids will be included on either side of the mutation.
-
-To incorporate proximal variants in the final sequence, use the
+To incorporate proximal variants in the mutated sequence, use the
 ``--phased-proximal-variants-vcf`` argument. Please see the :ref:`phased_vcf`
 section of the documentation on how to create this VCF.
 
 The output may be limited to PASS variants only by setting the ``--pass`` only
-flag and to mutant sequences by setting the ``--mutant-only`` flag.
-Additionally, variants can be limited to specific transcript biotypes
-using the ``--biotypes`` parameters, which is set to only include ``protein_coding``
-transcripts by default.
-
-The output can be further limited to only certain variants by providing
-a pVACseq report file to the ``--input-tsv`` argument. Only the peptide sequences for the epitopes in the TSV
-will be used when creating the FASTA. If this argument is an aggregated TSV
-file, use the ``--aggregate-report-evaluation`` parameter to only include
-peptide sequences for epitopes matching the chosen Evaluation(s). This is
+flag. Variants can be limited to specific transcript biotypes using the
+``--biotypes`` parameters, which is set to only include ``protein_coding``
+transcripts by default. Additionally, the ``--allow-incomplete-transcripts`` flag
+will include transcripts with incomplete or unconfirmed coding sequencees,
+i.e. where the VEP FLAGS field includes ``cds_start_nf`` or ``cds_end_nf``.
+
+The ``--downstream-sequence-length`` controls how many amino acids in the mutated
+sequence following a frameshift variant are retained. Setting the parameter to
+``full`` will retain the full downstream sequence.
+
+Generate Protein Fasta
+----------------------
+
+.. program-output:: pvacseq generate_protein_fasta -h
+
+This tool will extract trimmed wild type protein sequences and matched mutated
+protein sequences surrounding protein altering variants from a transcripts.fa file.
+This file is generated during each pVACseq run or can be regenerated using the
+``pvacseq generate_transcripts_fasta`` command.
+
+One use case for this tool is to help select long peptides that contain short
+neoepitope candidates. For example, if pVACseq was run to predict nonamers (9-mers)
+that are good binders and the user wishes to select long peptide (e.g. 24-mer)
+sequences that contain the nonamer for synthesis or encoding in a DNA vector.
+
+The protein sequence extracted will be generated by trimming the sequences in the
+transcripts.fa input file so that the alteration (e.g. a somatic missense SNV)
+will be centered in the protein sequence (if possible). The
+``flanking_sequence_length`` positional parameter controls the number of amino acids
+retained around the alteration. If the variant is near the beginning or end of the
+CDS, it will be as close to center as possible while maintaining the desired
+flanking sequence length. For frameshift variants the downstream sequence is not
+trimmed. The same amino acids that are trimmed from the mutated protein sequences
+are also trimmed from the matched wild type sequence so the mutant and wild type long
+peptides line up on both ends.
+
+The output may be limited to only mutant sequences by setting the ``--mutant-only``
+flag.
+
+The output can be further limited to only certain variants by providing a pVACseq
+report file to the ``--input-tsv`` argument. Only the peptide sequences for the
+epitopes in the TSV will be used when creating the FASTA. If this argument is an
+aggregated TSV file, use the ``--aggregate-report-evaluation`` parameter to only
+include peptide sequences for epitopes matching the chosen Evaluation(s). This is
 useful when creating a peptide fasta for vaccine ordering after using pVACview
 to select vaccine candidates and exporting the results to a new TSV.
 

docs/pvacsplice/optional_downstream_analysis_tools.rst

@@ -8,28 +8,61 @@
 Optional Downstream Analysis Tools
 ==================================
 
-Generate Protein Fasta
-----------------------
+Generate Transcripts Fasta
+--------------------------
 
-.. program-output:: pvacsplice generate_protein_fasta -h
+.. program-output:: pvacsplice generate_transcripts_fasta -h
 
-This tool will extract protein sequences surrounding splice sites predicted by RegTools.
-One use case for this tool is to help select long peptides that contain short neoepitope 
-candidates. For example, if pVACsplice was run to predict nonamers (9-mers) that are good binders and
-the user wishes to select long peptide (e.g. 24-mer) sequences that contain the nonamer for synthesis
-or encoding in a DNA vector. The splice site junction will be centered in the
-protein sequence returned (if possible).
+This tool will extract matched wild type and altered transcript protein sequences
+for cis-splicing variants prediction by RegTools. The resulting file
+is also generated during a pVACsplice run (named ``<sample_name>.transcripts.fa``).
 
 The output may be limited to PASS variants only by setting the ``--pass`` only
-flag. Additionally, variants can be limited to specific transcript biotypes
-using the ``--biotypes`` parameters, which is set to only include ``protein_coding``
-transcripts by default.
+flag. Variants can be limited to specific transcript biotypes using the
+``--biotypes`` parameters, which is set to only include ``protein_coding``
+transcripts by default. Additionally, the ``--allow-incomplete-transcripts`` flag
+will include transcripts with incomplete or unconfirmed coding sequencees,
+i.e. where the VEP FLAGS field includes ``cds_start_nf`` or ``cds_end_nf``.
+
+The ``--downstream-sequence-length`` controls how many amino acids in the mutated
+sequence following a frameshift splice site are retained. Setting the parameter to
+``full`` will retain the full downstream sequence.
+
+Generate Protein Fasta
+----------------------
+
+.. program-output:: pvacsplice generate_protein_fasta -h
 
-The output can be further limited to only certain variants by providing
-a pVACsplice report file to the ``--input-tsv`` argument. Only the peptide sequences for the epitopes in the TSV
-will be used when creating the FASTA. If this argument is an aggregated TSV
-file, use the ``--aggregate-report-evaluation`` parameter to only include
-peptide sequences for epitopes matching the chosen Evaluation(s).
+This tool will extract trimmed wild type protein sequences and matched altered
+protein sequences surrounding splice sites from a transcripts.fa file.
+This file is generated during each pVACsplice run or can be regenerated using the
+``pvacsplice generate_transcripts_fasta`` command.
+
+One use case for this tool is to help select long peptides that contain short
+neoepitope candidates. For example, if pVACsplice was run to predict nonamers (9-mers)
+that are good binders and the user wishes to select long peptide (e.g. 24-mer)
+sequences that contain the nonamer for synthesis or encoding in a DNA vector.
+
+The protein sequence extracted will be generated by trimming the sequences in the
+transcripts.fa input file so that the splice site will be centered in the protein
+sequence (if possible). The ``flanking_sequence_length`` positional parameter
+controls the number of amino acids retained around the alteration. If the splice site
+is near the beginning or end of the CDS, it will be as close to center as possible
+while maintaining the desired flanking sequence length. For frameshift splice sites
+the downstream sequence is not trimmed. The same amino acids that are trimmed from
+the altered protein sequences are also trimmed from the matched wild type sequence
+so the altered and wild type long peptides line up on both ends.
+
+The output may be limited to only mutant sequences by setting the ``--mutant-only``
+flag.
+
+The output can be further limited to only certain splice sites by providing a pVACsplice
+report file to the ``--input-tsv`` argument. Only the peptide sequences for the
+epitopes in the TSV will be used when creating the FASTA. If this argument is an
+aggregated TSV file, use the ``--aggregate-report-evaluation`` parameter to only
+include peptide sequences for epitopes matching the chosen Evaluation(s). This is
+useful when creating a peptide fasta for vaccine ordering after using pVACview
+to select vaccine candidates and exporting the results to a new TSV.
 
 Generate Aggregated Report
 --------------------------
@@ -78,7 +111,7 @@ NetChop Predict Cleavage Sites
 This tool uses NetChop to predict cleavage sites for neoepitopes from a pVACsplice run's filtered/all_epitopes
 TSV.  In its output, it adds to the TSV 3 columns: Best Cleavage Position, Best Cleavage Score, and a
 Cleavage Sites list.  Typically this step is done in the pVACsplice run pipeline for the filtered output TSV
-when specified. This tool provides a way to manually run this on pVACseq's generated filtered/all_epitopes
+when specified. This tool provides a way to manually run this on pVACsplice's generated filtered/all_epitopes
 TSV files so that you can add this information when not present, if desired.
 
 You can view more information about these columns for pVACsplice in the :ref:`output file documentation <all_ep_and_filtered>`.
@@ -91,7 +124,7 @@ NetMHCStab Predict Stability
 This tool uses NetMHCstabpan to add stability predictions for neoepitopes from a pVACsplice run's
 filtered/all_epitopes TSV.  In its output, it adds to the TSV 4 columns: Predicted Stability, Half Life,
 Stability Rank, and NetMHCStab Allele.  Typically this step is done in the pVACsplice run pipeline for the
-filtered output TSV when specified.  This tool provides a way to manually run this on pVACseq's generated
+filtered output TSV when specified.  This tool provides a way to manually run this on pVACsplice's generated
 filtered/all_epitopes TSV files so that you can add this information when not present if desired.
 
 You can view more informatnion about these columns for pVACsplice in