Package: immunopepper
ImmunoPepperImmunoPepper is a software tool that takes a splicing graph (possibly derived from an RNA-Seq
samples) as input and generates the set of all theoretically peptide sequences (or kmers) through
direct translation of all walks along the graph. This peptide set can be personalized with germline
and somatic variants and takes all exon-exon junctions present in the splicing graph (even ones not
part of the reference annotation but present in the given RNA-Seq sample) into account. The
comprehensive set of peptides can be used subsequently for further downstream analyses such as
domain annotation or computational immunology.Get StartedInstallationIt is recommended to setup a separate virtual or conda environment.
The basic ImmunoPepper package can be installed viapip:pip install immunopepperAlternatively, ImmunoPepper can also be installed from source using:pip install -r requirements.txt -r requirements_dev.txt
make installAfter installation, please consult the help screen for further usage options:immunopepper -hPrerequisitesImmunoPepper takes a splicing graph as input. This splicing graph has to be generated using the
SplAdder pipeline. Further information about SplAdder is available on itsGitHub
pageor theOnline
documentation.Basic workflowThe software has four basic working modes:build: Core part of ImmunoPepper. Traverses the input splice graph and generates all possible
peptides/kmers.make_bg: Integrates multiple kmer files (produced viabuild) and generates one background kmer file.diff: Takes as input the foreground kmer file and a background kmer file. The output is
contrasting foreground and background, indicating all foreground kmers not present in the
background.filter: Apply different filter mechanisms to a given kmer file.ModebuildThe following parameters aremandatory:--samples: input sample names; can specify more than one sample. (Example: 'sample1 sample2')--output-dir: output directory--ann-path:annotation file, accepted file formats:.gtf,.gffand.gff3--splice-path: path of the input SplAdder splice graph--ref-path: reference genome file in FASTA formatThe following parameters areoptional:--mutation-mode: mutation mode; choose from {ref,germline,somaticandsomatic_germline}, default moderef.--kmer: length of the kmers for kmer ouput. Default value is0, which will output full peptides instead of kmers. A recommended kmer length is 9.--disable-concat: Turns off the generation of kmers from combinations of more than 2 exons (kmers generated from combinations of short exons might be missed)--germline: germline mutation file path. Mandatory argument if the mutation mode isgermlineorsomatic_and_germline.--somatic: somatic mutation file path. Mandatory argument if the mutation mode issomaticorsomatic_and_germline.--use-mut-pickle: Summarize mutation information in a pickle file and re-use if existing (saves the time processing the original mutation files).--count-path: path to splice graph count file--compressed: compress the output files using gzipExample command line (replacerefwithgermlineto consider mutation information)immunopepper build \
--output-dir tests/test1/current_output_pos \
--ann-path tests/test1/data/test1pos.gtf \
--ref-path tests/test1/data/test1pos.fa \
--splice-path tests/test1/data/posgraph/spladder/genes_graph_conf3.merge_graphs.pickle \
--somatic tests/test1/data/test1pos.maf \
--germline tests/test1/data/test1pos.vcf \
--samples test1pos test1neg \
--mutation-mode ref \
--kmer 4 \
--disable-concat \
--count-path  tests/test1/data/posgraph/spladder/genes_graph_conf3.merge_graphs.count.hdf5Modemake_bgThe following parameters aremandatory:--kmer-files: The list of kmer files output by build mode, e.g., 'ref_back_kmer.txt somatic_back_kmer.txt'.--output-file-path: Output integrated background kmer file path.--output-dir: Directory to store the log file.The following parameters areoptional:--verbose: Specify the level of output. 0 means zero debug information, 2 means the most detailed information.--compressed: Compress the output files with gzip.Example command line:immunopepper make_bg \
--kmer-files-list tests/test1/current_output_pos/test1pos/ref_back_kmer.txt tests/test1/current_output_pos/test1pos/germline_back_kmer.txt \
--output-dir tests/test1/current_output_pos/ \
--output-file_path tests/test1/current_output_pos/test1pos/uniq_back_kmer.txt \
--verbose 2ModediffThe following parameters aremandatory:--junction-kmer-file: foreground junction file path generated bybuildmode, e.g.,ref_junction_kmer.txt--bg-file-path: background kmer file path. Can be the output ofmake_bgmode or external file. One kmer per line.--output-file-path: output tsv file path.--output-dir: directory to store the log file.The following parameters areoptional:--verbose: Specify the verbosity level of output. 0 means zero debug information, 2 means the most detailed information.--compressed: compress the output files with gzip.Example command lineimmunopepper  diff \
--junction-kmer-file tests/test1/current_output_pos/test1pos/ref_junction_kmer.txt \
--bg-file-path tests/test1/current_output_pos/test1pos/uniq_back_kmer.txt \
--verbose 1 \
--output-file-path tests/test1/current_output_pos/test1pos/kmer_result.tsv \
--output-dir tests/test1/current_output_pos \
--remove-bgModefilterThe following parameters aremandatory:--junction-kmer-tsv-file: The original kmer tsv files. Generated bybuildmode
or bydiffmode. It should contain fieldcross-junction,seg-exprandjunc_expr.The following parameters areoptional:--cross-junction: Only output the cross-junction kmers.--seg-expr: Only output kmers that have segment expression greater than threshold.--seg-expr-thresh: Segment expression threshold. Default 0.--junc-expr: Only output kmers that have junction expression greater than threshold.--junc-expr-thresh: Junction expression threshold. Default 0.--output-file-path: Mandatoray argument. Specify the output tsv file path.--output-dir: Mandatoray argument. Specify the directory to store the log file.--verbose: Specify the level of output. 0 means zero debug information, 2 means the most detailed information.--compressed: Compress the output files with gzip.Example command lineimmunopepper filter \
--junction-kmer-tsv_path tests/test1/current_output_pos/test1pos/kmer_result.tsv \
--output-dir tests/test1/current_output_pos/ \
--output-file-path tests/test1/current_output_pos/test1pos/kmer_result_filtered.tsv \
--cross-junction \
--junc-expr \
--verbose 2post-processing guidlinesFor further filtering, the user can use the predicted kmers as input for MHC-binding prediction or
use MS databases for further confirmation.MHC-BindingOne option for MHC binding prediction isNetMHC. Using the
predicted kmers as input,NetMHCpredicts a peptide-MHC class 1 binding score for each sequence
using a neural network.Mass spectrometryMass spectrometry data can provide further evidence for the presence of a predicted peptide. There
exist several tools for searching a peptide sequence against a MS database, for instanceOpenMS.Output filesThere are 5 files for thebuildmode.mut_moderefers toref,somatic,germlineandsomatic_and_germline.[mut_mode]_back_peptides.fa: Peptides translated from annotation transcripts. Two lines for one output. The first
line is the transcript ID and the second line is the result peptide.[mut_mode]_back_kmer.txt: kmers generated from[mut_mode]_back_peptides.fa. There are four columns: [kmer,gene_name,seg_expr,is_crossjunction]. The first column is
the result kmer, the second column is the transcript ID, the third column is the average segment expression and the final column is the
flag indicating if the kmer is junction kmer. The final column is False forallrows in this file.[mut_mode]_peptides.fa: Peptides translated from traversing splicegraph. Two lines for one output. The first
line is the output ID and the second line is the result peptide.[mut_mode]_junction_kmer.txt: kmers generated from[mut_mode]_peptides.fa. In addition to the same four columns in[mut_mode]_back_kmer.txt, there is one more
column in this file.junction_expr, refers to the junction counts for those kmers that span over
exon junction. For those withjunction_expr> 0, the flagis_crossjunctionis True.[mut_mode]_metadata.tsv.gz: Contain details for every junction pairs.Detail explanation for columns in[mut_mode]_metadata.tsv.gzoutput_id: In the format of [gene_nama]:[first vertex]_[second vertex]:[somatic variant combination id]:[read frame]. LikeGENE1:0_2:0:1.GENE1is the gene name,0_2means this junction consists of vertex 0 and vertex 2.0means there is no
somatic mutation or it is the first case of all somatic mutation combination cases.2means the read frame is 2.read_frame: int (0,1,2). The number of base left to the next junction pair.gene_name: str. The name of Gene.gene_chr: str. The Chromosome id where the gene is located.gene_strand: str ('+', '_'). The strand of gene.mutation_mode: str ('ref', 'somatic', 'germline', 'somatic_and_germline'). Mutation modepeptide_annotated: Boolean. Indicate if the junction peptide also appears in the background peptide.junction_peptided: Boolean. Indicate if the junction also appear in the input annotation file.has_stop_codon: Boolean. Indicate if there is stop codon in the junction pair.is_in_junction_list: Boolean. Indicate if the junction pair appear in the given junction whitelist.is_isolated: Boolean. Indicate if the output peptide is actually translated from a single exon instead of two.variant_comb: shows the somatic variantion combination used in this line of output. seperate by ';'
eg. 5;25 means the somatic mutation of position 5 and 25 take effect in this output.variant_seg-expr: shows the corresponding expression of segments where the corresponding somatic mutation is in.
eg. 257.0;123.2 means the segment where the somatic mutation in position 5 is in has counts 257.0modified_exons_coor: Shows exon coordination. Usually we have 4 number start_v1;stop_v1;start_v2;stop_v2. They
have already absorb reading frame so you can use the coord directly to generate the same output peptide.original_exons_coord: Shows the original exon coordination.vertex_idx: shows the vertex id of the given junction. eg 5,6 means this junction pair consists of the fifth and
sixth vertex.junction_expr: float. The expression of the junction.segment_expr: float. The weighted sum of segment expression. We split the junction into segments and compute the segment
expression with the length-weighted-sum expression.The.metafile is compressed by default in all time. The user can add--compressedoption
in the input argument to have other files compressed. It is recommended to output in compressed format because
it can save a lot of storage.The output file formake_bgmode is a text file. Each line is a unique kmer.The output file fordiffmode is a text file. There is a header line like[mut_mode]_junction_kmerbut
with one more columnis_neo_flagto indicate if the kmer also exist in the background kmer file. We can also
remove those kmers that exist in the background files with the option--remove-bg.The output file forfiltermode is a text file also with header line.Example use case on experimetal dataUsing real DNA-sequencing data from mouse, we will show how to apply ImmunoPepper to generate all
candidate kmers. In this example, we consider two samples:ENCSR000BZGandERR2130621. We chooseENCSR000BZGas the background sample andERR2130621as the foreground sample. They use the same
splicegraph but have different expression values and individual (personalized) mutations. Our goal
is to generate all kmers unique toERR2130621.Step 1: Use thebuildmode to generate kmers of the two samples in all four mutation modes:# reference (ref) mode
immunopepper build --mutation-mode ref --samples ENCSR000BZG ERR2130621 --output-dir ImmunoPepper_usecase_out --splice-path ImmunoPepper_usecase.pickle --ann-path ImmunoPepper_usecase.gtf --ref-path genome1.fa --kmer 9 --count-path ImmunoPepper_usecase.count.hdf5
# germline mode
immunopepper build --mutation-mode germline --samples ENCSR000BZG ERR2130621 --output-dir ImmunoPepper_usecase_out --splice-path ImmunoPepper_usecase.pickle --ann-path ImmunoPepper_usecase.gtf --ref-path genome1.fa --kmer 9 --count-path ImmunoPepper_usecase.count.hdf5 --germline ImmunoPepper_usecase.vcf --somatic ImmunoPepper_usecase.maf
# somatic mode
immunopepper build --mutation_mode somatic --samples ENCSR000BZG ERR2130621 --output-dir ImmunoPepper_usecase_out --splice-path ImmunoPepper_usecase.pickle --ann-path ImmunoPepper_usecase.gtf --ref-path genome1.fa --kmer 9 --count-path ImmunoPepper_usecase.count.hdf5 --germline ImmunoPepper_usecase.vcf --somatic ImmunoPepper_usecase.maf
# germline and somatic mode
immunopepper build --mutation_mode somatic_and_germline --samples ENCSR000BZG ERR2130621 --output-dir ImmunoPepper_usecase_out --splice-path ImmunoPepper_usecase.pickle --ann-path ImmunoPepper_usecase.gtf --ref-path genome1.fa --kmer 9 --count-path ImmunoPepper_usecase.count.hdf5 --germline ImmunoPepper_usecase.vcf --somatic ImmunoPepper_usecase.mafStep 2: Create background kmer set from the output of sampleENCSR000BZG.
Since there exist no mutations in sampleENCSR000BZG, we only consider its output in reference. In addition,
we only consider kmers that have junction expression larger than 0. We can achieve this using thefiltermode and
get the fileref_mode_background_kmer.tsv. We then use themake_bgmode to create the background kmer file. Since
the input is just one file,make_bgsimply takes the first column and outputs all unique kmers.immunopepper filter --output-dir ImmunoPepper_usecase_out --output-file-path ImmunoPepper_usecase_out/ENCSR000BZG/ref_mode_background_kmer.tsv --junction-kmer-tsv-path ImmunoPepper_usecase_out/ENCSR000BZG/ref_junction_kmer.txt --junc_expr
immunopepper make_bg --kmer_files_list ImmunoPepper_usecase_out/ENCSR000BZG/ref_mode_background_kmer.tsv --output-dir ImmunoPepper_usecase_out --output-file-path ImmunoPepper_usecase_out/background_kmer.txtStep 3: Remove the background kmers
After generating the background kmers in Step 2, we can now subtract those kmers from the kmer sets of sampleERR2130621. We
can usedifffor this operation:# contrast ref kmers against background
immunopepper diff --junction-kmer-file  ImmunoPepper_usecase_out/ERR2130621/ref_junction_kmer.txt --bg-file-path ImmunoPepper_usecase_out/background_kmer.txt --output-dir ImmunoPepper_usecase_out --output-file-path ImmunoPepper_usecase_out/ERR2130621/ref_junction_kmer_remove-bg.tsv --remove-bg
# contrast germline kmers against background
immunopepper diff --junction-kmer-file  ImmunoPepper_usecase_out/ERR2130621/germline_junction_kmer.txt --bg-file-path ImmunoPepper_usecase_out/background_kmer.txt --output-dir ImmunoPepper_usecase_out --output-file-path ImmunoPepper_usecase_out/ERR2130621/germline_junction_kmer_remove-bg.tsv --remove-bg
# contrast somatic kmers against background
immunopepper diff --junction-kmer-file  ImmunoPepper_usecase_out/ERR2130621/somatic_junction_kmer.txt --bg-file-path ImmunoPepper_usecase_out/background_kmer.txt --output-dir ImmunoPepper_usecase_out --output-file-path ImmunoPepper_usecase_out/ERR2130621/somatic_junction_kmer_remove-bg.tsv --remove-bg
# contrast somatic/germline kmers against background
immunopepper diff --junction-kmer-file  ImmunoPepper_usecase_out/ERR2130621/somatic_and_germline_junction_kmer.txt --bg-file-path ImmunoPepper_usecase_out/background_kmer.txt --output-dir ImmunoPepper_usecase_out --output-file-path ImmunoPepper_usecase_out/ERR2130621/somatic_and_germline_junction_kmer_remove-bg.tsv --remove-bgStep 4: Filter
After removing the background kmers in Step 3, we can add more filters to further reduce the number of candidate kmers.
For example, we only consider the kmers that have junction expression larger than 0 as well as a
segment expression value larger than 2.filtermode provides filters based on segment expression
and junction expression, based on a user-provided threshold.# filter ref kmers
immunopepper filter --output-dir ImmunoPepper_usecase_out --output-file-path ImmunoPepper_usecase_out/ERR2130621/ref_junction_kmer_remove-bg_filter.tsv --junction-kmer-tsv-path ImmunoPepper_usecase_out/ERR2130621/ref_junction_kmer_remove-bg.tsv --cross-junction --seg-expr --seg-expr-thresh 2
# filter germline kmers
immunopepper filter --output-dir ImmunoPepper_usecase_out --output-file-path ImmunoPepper_usecase_out/ERR2130621/germline_junction_kmer_remove-bg_filter.tsv --junction-kmer-tsv-path ImmunoPepper_usecase_out/ERR2130621/germline_junction_kmer_remove-bg.tsv --cross-junction --seg-expr --seg-expr-thresh 2
# filter somatic kmers
immunopepper filter --output-dir ImmunoPepper_usecase_out --output-file-path ImmunoPepper_usecase_out/ERR2130621/somatic_junction_kmer_remove-bg_filter.tsv --junction-kmer-tsv-path ImmunoPepper_usecase_out/ERR2130621/somatic_junction_kmer_remove-bg.tsv --cross-junction --seg-expr --seg-expr-thresh 2
# filter germline/somatic kmers
immunopepper filter --output-dir ImmunoPepper_usecase_out --output-file-path ImmunoPepper_usecase_out/ERR2130621/somatic_and_germline_junction_kmer_remove-bg_filter.tsv --junction-kmer-tsv-path ImmunoPepper_usecase_out/ERR2130621/somatic_and_germline_junction_kmer_remove-bg.tsv --cross-junction --seg-expr --seg-expr-thresh 2Step 5: Aggregate
We get the unique kmers of sampleERR2130621in four modes. Now we can aggregate all those kmers.tail -n +2 ImmunoPepper_usecase_out/ERR2130621/*_junction_kmer_remove-bg_filter.tsv | cat | grep -v "==>" | cut -f1 | sort |uniq | grep . > neo_kmer.txtPratical TipsImmunoPepper requires the sample name areexactlythe same in thesplice count fileandmutation fileand the
given option--samplesshould be those samples. Please make necessary changes to the input files so that ImmunoPepper can work as expected.make_bg,diffandfiltermode accept the output files of ImmunoPepper. However, the user
can also add other external input files.make_bgassumes the input file has
a header line, separated with\tand kmers are in the first column.diffassumes
the foreground kmer file has a header line and that the background kmer file has the
format as the output file ofmake_bg.filterassumes the input file has a header
line and with three columnsseg-expr,junction_exprandis_crossjunction. It's acceptable if some columns
are missing but the user should not use corresponding filter rules. Otherwise error will happen.LicensePlease see the LICENSE file for more information about license and copyright.