IGoR (Inference and Generation Of Repertoires) Documentation

-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.

---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.

seq_index

The sequence index the alignment corresponds to in the indexed_sequences.csv file.

gene_name

The gene name as provided in the genomic template file

score

SW alignment score

offset

The index of the first letter of the (undeleted) genomic template on the read as described in the previous section. Indices are 0 based.

insertions

Indices of the alignment inserted nucleotides (relative to the read)

deletions

Indices of the alignment deleted nucleotides (relative to the genomic template)

mismatches

Indices of the alignment mismatches (relative to the read)

length

Length of the SW alignment (including insertions and deletions)

5_p_align_offset

Offset of the first nucleotide of the SW alignment (relative to the read)

3_p_align_offset

Offset of the last nucleotide of the SW alignemnt (relative to the read)

seq_index

The sequence index the alignment corresponds to in the indexed_sequences.csv file.

v_anchor

Position of the V anchor (first nucleotide of 2nd-CYS codon) relative to the read sequence.

j_anchor

Position of the J anchor (last nucleotide of J-PHE or J-TRP codon) relative to the read sequence.

CDR3nt

Nucleotide CDR3 sequence of the indexed sequence.

CDR3aa

Amino acids CDR3 sequence of the indexed sequence.

--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

map_base::at() exception

This exception is most likely thrown by a Gene_Choice event in the inference. Try/Catch handling is runtime costly thus some checks are not performed on the fly. Explanation: This is most likely the inference receiving a genomic template whose name does not exist in the model realizations. Solution: make sure the genomic templates (and their names) used for alignments correspond to those contained in your model file.

All 0 output

All marginal files contains 0 parameters after one iteration. All sequences have zero likelihood in the inference_logs.txt file. Explanation: none of the scenarios had a sufficiently high likelihood to reach the likelihood threshold. Solution: use the --L_thresh argument to decrease the likelihood threshold, if the code becomes utterly slow see below. In general while inferring one should make sure not too many sequences are assigned a zero likelihood since it would introduce a systematic bias in the learned distribution

Extreme slowness

Runtimes are very far from the ones given in the Runtimes section. Check the mean number of errors in the inference_logs.txt file. If these numbers are higher than you would expect from your data (e.g if you are not studying hypermutated data) check your alignments statistics. A possible explanation would be an incorrect setting of the alignment offsets bounds

--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.