IGOR(1)

NAME
igor - Inference and Generation of Repertoires

SYNOPSIS

igor -arg --subarg ---subsubarg

DESCRIPTION

IGoR is a C++ software designed to infer V(D)J recombination related processes from sequencing data such as:

    • Recombination model probability distribution

    • Hypermutation model

    • Best candidates recombination scenarios

    • Generation probabilities of sequences (even hypermutated)

IGoR is a free (as in freedom) software released under the license.

This manpage gives a summary of available command lines. A more exhaustive description of the software capabilities can be found in the README document.

AUTHOR

IGoR was originally written by Quentin Marcou.

VERSION

Latest released version: 1.4.0

COMMANDS

  General commands summary
Command line argument | Description
-h or -help | Displays IGoR’s manual. Alternatively one could use man igor.
-v or -version | Displays IGoR’s installed version number.
-set_wd /path/to/dir/ | Sets the working directory to /path/to/dir/, default is /tmp. This should be an already existing directory and will not be created by IGoR
-threads N | Sets the number of OpenMP threads to N for alignments and inference/evaluation. By default IGoR will use the maximum number of threads.
-stdout_f /path/to/file | Redirects the standard output to the file /path/to/file
-read_seqs /path/to/file | Reads the input sequences file /path/to/file and reformat it in the working directory. This step is necessary for running any action on sequences using the command line. Can be a fasta file, a csv file (with the sequence index as first column and the sequence in the second separated by a semicolon ;) or a text file with one sequence per line (format recognition is based on the file extension). Providing this file will create a semicolon separated file with indexed sequences in the align folder.
-batch batchname | Sets the batch name. This name will be used as a prefix to alignment/indexed sequences files, output, infer, evaluate and generate folders.
-chain chainname | Selects a model and a set of genomic template according to the value. Possible values for chainname are: alpha, beta, light, heavy_naive, and heavy_memory. This needs to be set in order to use provided genomic templates/model
-species speciesname | Selects a species from the set of predefined species. Possible values are: human.This needs to be set in order to use provided genomic templates/model
-set_genomic --*gene* /path/to/file.fasta | Set a set of custom genomic templates for gene gene (possible values are --V,--D and --J) with a list of genomic templates contained in the file /path/to/file.fasta in fasta format. If the set of provided genomic templates is already fully contained (same name and same sequence) in the loaded model (default, custom, last_inferred), the missing ones will be set to zero probability keeping the ratios of the others. For instance providing only one already known genomic template will result in a model with the considered gene usage to be 1.0, all others set to 0.0. When using this option and introducing new/modified genomic templates, the user will need to re-infer a model since the genomic templates will no longer correspond to the ones contained in the reference models, the model parameters are thus automatically reset to a uniform distribution.
-set_CDR3_anchors --*gene* | Load a semicolon separated file containing the indices/offset of the CDR3 anchors for the gene(--V or --J). The index should correspond to the first letter of the cysteine (for V) or tryptophan/phenylalanin (for J) for the nucleotide sequence of the gene. Indices are 0 based.
-set_custom_model /path/to/model_parms.txt /path/to/model_marginals.txt | Use a custom model as a baseline for inference or evaluation. Note that this will override custom genomic templates for inference and evaluation. Alternatively, providing only the model parameters file will lead IGoR to create model marginals initialized to a uniform distribution.
-load_last_inferred | Using this command will load the last inferred model (folder inference/final_xx.txt) as a basis for a new inference, evaluation or generation of synthetic sequences
-run_demo | Runs the demo code on 300 sequences of 60bp TCRs (mostly a sanity run check)
-run_custom | Runs the code inside the custom section of the main.cpp file
-subsample N | Perform actions on a random subsample of N sequences. This flag will have different effects depending on the supplied commands: if the -read_seqs command is used, the resulting indexed sequence file will be a subsample of sequences contained in the original file. Else, if the -align command is used the alignments will be performed on a subsample of the indexed sequences. Else, if the -evaluate or -infer command is used the inference will be run on a subsample of the indexed sequences. Obviously N should be < to the total number of sequences available. The -subsample flag should be used in only one command of a pipeline, see the Command example section for details.

  Alignment commands summary

Alignment of the sequences is performed upon detection of the -align switch in the command line. For each gene, alignment parameters can be set using --V,--D or --J. Specifying any of those three argument will cause to align only the specified genes. In order to specify a set of parameters for all genes or force to align all genes the argument --all should be passed.

The complementarity-determining region (CDR3) of the aligned sequences is by default written on a file <batchname>_indexed_CDR3.csv in the aligns directory when --all is used. In case of separated alignments the CDR3 file can be generated by using the --feature ---ntCDR3 option.

The arguments for setting the different parameters are given in the table below. If the considered sequences are nucleotide CDR3 sequences (delimited by its anchors on 3' and 5' sides) using the command --ntCDR3 alignments will be performed using gene anchors information as offset bounds.
Command line argument | Description
---thresh X | Sets the score threshold for the considered gene alignments to X. Default is 50.0 for V, 15.0 for D and 15.0 for J
---matrix path/to/file | Sets the substitution matrix to the one given in the file. Must be ',' delimited. Default is a NUC44 matrix with stronger penalty on errors (5,-14)
---gap_penalty X | Sets the alignment gap penalty to X. Default is 50.0
---best_align_only | If true only keep the best alignment for each gene/allele. If false outputs all alignments above the score threshold. Default is true for V and J, and false for D.
---best_gene_only | If true only keep alignments for best scoring gene candidate (or candidates if several genes have the same maximum score). If false outputs alignments for every aligned gene/allele. Default is false for V, D and J.
---offset_bounds M N | Constrains the possible positions of the alignments. The offset is defined as the position on the read to which the first nucleotide of the genomic template aligns (can be negative, e.g for V for which most of the V is on the 5' of the read and cannot be seen). Default values are -inf and +inf. If the --ntCDR3 command has been given provided offset bounds values will be used for genes with missing CDR3 anchors positions.
---template_spec_offset_bounds path/to/file | Constrains the possible positions of the alignments differently for each genomic template. The file should be a semi colon separated file formated as follows: gene_name;min_offset;max_offset. If entries are missing for some genes, values given with the ---offset_bounds command will be used. If the --ntCDR3 command has been given provided template specific offset bounds values will be used for genes with missing CDR3 anchors positions. If non template specific entry is given for the considered gene, general offset bounds values will be used.
---reversed_offsets | If true provided offsets are accounted for reversed offsets. Reversed offsets are defined relative to the last nucleotide of the read instead of the first. Reversed offsets must be ⇐0 by construction.

  Inference and evaluation commands

The inference is reached using the command -infer. Logs and models parameters values for each iteration will be created in the folder inference of the working directory (or batchname_inference if a batchname was supplied).

Sequence evaluation is reached using the command -evaluate. This is the same as performing an iteration of the Expectation-Maximization on the whole dataset and thus accepts the same arguments as -infer for arguments related to the precision of the algorithm. The logs of the sequences evaluation are created in the folder evaluate (or batchname_evaluate if a batchname was supplied).

    • Note that -infer and -evaluate are mutually exclusive in the same command since it brings ambiguity reagarding which model should be used for each **

Optional parameters are the following:
Command line argument | Description | Available for
--N_iter N | Sets the number of EM iterations for the inference to N | inference
--L_thresh X | Sets the sequence likelihood threshold to X. | inference & evaluation
--P_ratio_thresh X | Sets the probability ratio threshold to X. This influences how much the tree of scenarios is pruned. Setting it 0.0 means exploring every possible scenario (exact but very slow), while setting it to 1.0 only explores scenarios that are more likely than the best scenario explored so far (very fast but inaccurate). This sets a trade off between speed and accuracy, the best value is the largest one for which the likelihood of the sequences almost doesn’t change when decreasing it further. | inference & evaluation
--MLSO | Runs the algorithm in a Viterbi like fashion. Accounts for the Most Likely Scenario Only (as fast as using a probability ratio threshold of 1.0) | inference & evaluation
--infer_only eventnickname1 eventnickname2 | During the inference only the parameters of the events with nicknames listed will be updated. Note that not passing any event nickname will fix all events. | inference
--not_infer eventnickname1 eventnickname2 | Opposite command to the one above, will fix the parameters of the listed events | inference
--fix_err | In the same vein as the two commands above, this one will fix the parameters related to the error rate. | inference

  Outputs

Outputs or Counters in the C++ interface are scenario/sequence statistics, each individually presented below. They are all written in the output folder (or batchname_output if a batchname was supplied).

In order to specify outputs use the -output argument, and detail the desired list of outputs. Outputs are tied to the exploration of scenarios and thus require to have -infer or -evaluate in the same command. Note that although it might be interesting to track some outputs during the inference for debugging purposes, best practice would be to use it along with evaluation.

The different outputs are detailed in the next sections.

Python utility functions are provided to analyze these outputs in the pygor.counters submodule.

  Best scenarios

Output the N best scenarios for each sequence

Use command --scenarios N

The output of this Counter is a semicolon separated values file with one field for each event realization, associated mismatches/errors/mutations indices on the read, the scenario rank, its associated probability and the sequence index. Python functions to parse the output of the Best scenario counter can be found in the pygor.counters.bestscenarios submodule.

  Generation probability

Estimates the probability of generation of the error free/unmutated ancestor sequence By default only outputs an estimator of the probability of generation of the ancestor sequence underlying each sequencing read. See for details.

Use command --Pgen

  Coverage

Counts for each genomic nucleotide how many times it has been seen and how many times it was mutated/erroneous

Use command --coverage

  Sequence generation commands

Reached using the command -generate N where N is the number of sequences to be generated. The number of sequences to generate must be passed before optional arguments. Optional parameters are the following:
Command line argument | Description
--noerr | Generate sequences without sequencing error (the rate and the way those errors are generated is controlled by the model error rate)
--CDR3 | Outputs nucleotide CDR3 from generated sequences. The file contains three fields: CDR3 nucleotide sequence, whether the CDR3 anchors were found (if erroneous/mutated) and whether the sequence is inframe or not. Gene anchors are not yet defined for all the default models shipped with IGoR, use -set_CDR3_anchors to set them.
--name myname | Prefix for the generated sequences filenames. Note that setting the batchname will change the generated sequences folder name, while setting --name will change the file names.
--seed X | Impose X as a seed for the random sequence generator. By default a random seed is obtained from the system.

CONTACT

For any question or issue please open an or email

COPYING

Free use of IGoR is granted under the terms of the (GPLv3).