IEDB Next-Generation Tools Mutated Peptide Generator - version 0.7-beta
=======================================================================

Introduction
------------
The Mutant Peptide Generator tool will take a two-sample, SNPEff-annotated VCF as
input and generate predicted neo-peptides and the reference / WT peptides
with which they pair.


Release Notes
-------------
v0.7
  - Complex variants with '?' in hgvs annotation fixed.
v0.6.1
  - Updated Docker image to harbor.lji.org/cedar-peptide-generation
  - Changed table name from 'snp' to 'variant'

v0.6-beta
  - Fixed erroneous hgvs protein decoding

v0.5-beta
  - hgvs_protein column and protein position columns have different positions. Hence always use position from hgvs_protein and add warning when they are different from each other.
  - stop lost: stop lost peptides were not generated previously. Fixed that.
  - Minor issue: In all_variant output file only warnings from one reference-mutant peptide pair were written in the peptide warnings column. Now fixed that so that it has warnings from all peptides.
  - When reference/mutated peptide length increased for ins/dels within the acceptable scale, warnings are updated to be more specific.

v0.4-beta
  - Fix an issue with the input VCF of only one mutation

v0.3-beta
  - Fixed build script version handling
  - Improved error handling and warnings

v0.2.1-beta
  - Added peptide_mutation_position parameter
  - Added annotate option for VCF annotation with SNPEff
  - Added input validation

v0.1-beta
  - Initial public beta release

Prerequisites
-------------
The following prerequisites must be met before installing this tool:

+ Linux or MacOS 64-bit environment

+ Python 3.10 or higher
  * http://www.python.org/

+ Docker
  * https://docs.docker.com/engine/install/

+ User with permission to execute docker commands

Installation
------------
Below, we will use the example of installing an 'iedb_tools' folder inside
your home directory.  Replace '~/iedb_tools' with your desired target directory.

1. Extract the code and change directory: 
  $ mkdir ~/iedb_tools
  $ tar -xvzf IEDB_NG_MPG-0.7-beta.tar.gz -C ~/iedb_tools
  $ cd ~/iedb_tools/ng_mpg-0.7-beta

2. Optionally, create and activate a Python 3.10+ virtual environment using your
favorite virtual environment manager.  Here, we will assume the virtualenv is at
~/virtualenvs/ng_mpg:
  $ python3 -m venv ~/venvs/ng_mpg
  $ source ~/venvs/ng_mpg/bin/activate

3. Install python requirements:
  $ python3 -m pip install --upgrade pip
  $ pip install -r requirements.txt


Usage
-----
python3 src/run_mutgen.py -j <input_json_file> --output-directory <output_directory>

The format of the input JSON file is described below.

The result will saved to result.json file inside output_directory

Run the following command, or see the 'example_commands.txt' file in the 'src'
directory for typical usage examples:

> python3 src/run_mutgen.py -h

Input formats
-------------
Currently, only JSON input is supported.

*NOTE*: 

-This tool only accepts JSON inputs, formatted as described below:  
{
  "peptide_length": 21,
  "reference_genome": "GRCh38",
  "frameshift_overlap": 9,
  "maximum_peptide_length": 23,
  "peptide_mutation_position1": 11,
  "input_vcf": "examples/syntheticX.speedseq.ann.vcf",
  "annotate": true
}

- The available reference genomes (GRCh38 (default), GRCh37, GRCm38)

- we provide the option to run SNPEff annotation on unannoated VCFs. To enable it, please change annotate to true (default=false) from the JSON parameters.

More information on the individual parameters can be found at:
https://nextgen-tools.iedb.org/docs/tools/mpg/index.html

Output format
-------------
The output file is also in JSON format.  The 'results' section contains
3 output tables 'unique_peptide', 'peptide', and 'variant'.  The tables are
divided into a section of column headers, called 'table_columns' and the
actual data, called 'table_data'.

More information on these outputs can be found
at: https://nextgen-tools.iedb.org/docs/tools/mpg/index.html

Additional output formats and information on usage with 'pandas' will be
included in a future release.

In addition to the main output file, a log file is also included that may
be useful for debugging.


Caveats
-------
All IEDB next-generation standalones have been developed with the primary
focus of supporting the website.  Some user-facing features may be lacking,
but will be improved as these tools mature.


Contact
-------
Please contact us with any issues encountered or questions about the software
through any of the channels listed below.

IEDB Help Desk: https://help.iedb.org/
Email: help@iedb.org