File: index.html

package info (click to toggle)
igor 1.4.0%2Bdfsg-2
links: PTS, VCS
area: main
in suites: bullseye
size: 4,116 kB
sloc: cpp: 12,453; python: 1,047; sh: 124; makefile: 33
file content (2318 lines) | stat: -rw-r--r-- 106,908 bytes
parent folder | download | duplicates (3)
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<!--[if IE]><meta http-equiv="X-UA-Compatible" content="IE=edge"><![endif]-->
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="generator" content="Asciidoctor 1.5.5">
<meta name="author" content="Quentin Marcou">
<title>IGoR (Inference and Generation Of Repertoires) Documentation</title>
<style>
@import url(https://fonts.googleapis.com/css?family=Varela+Round|Open+Sans:400italic,600italic,400,600|Ubuntu+Mono:400);
/*! normalize.css v2.1.2 | MIT License | git.io/normalize */
/* ========================================================================== HTML5 display definitions ========================================================================== */
/** Correct `block` display not defined in IE 8/9. */
article, aside, details, figcaption, figure, footer, header, hgroup, main, nav, section, summary { display: block; }

/** Correct `inline-block` display not defined in IE 8/9. */
audio, canvas, video { display: inline-block; }

/** Prevent modern browsers from displaying `audio` without controls. Remove excess height in iOS 5 devices. */
audio:not([controls]) { display: none; height: 0; }

/** Address `[hidden]` styling not present in IE 8/9. Hide the `template` element in IE, Safari, and Firefox < 22. */
[hidden], template { display: none; }

script { display: none !important; }

/* ========================================================================== Base ========================================================================== */
/** 1. Set default font family to sans-serif. 2. Prevent iOS text size adjust after orientation change, without disabling user zoom. */
html { font-family: sans-serif; /* 1 */ -ms-text-size-adjust: 100%; /* 2 */ -webkit-text-size-adjust: 100%; /* 2 */ }

/** Remove default margin. */
body { margin: 0; }

/* ========================================================================== Links ========================================================================== */
/** Remove the gray background color from active links in IE 10. */
a { background: transparent; }

/** Address `outline` inconsistency between Chrome and other browsers. */
a:focus { outline: thin dotted; }

/** Improve readability when focused and also mouse hovered in all browsers. */
a:active, a:hover { outline: 0; }

/* ========================================================================== Typography ========================================================================== */
/** Address variable `h1` font-size and margin within `section` and `article` contexts in Firefox 4+, Safari 5, and Chrome. */
h1 { font-size: 2em; margin: 0.67em 0; }

/** Address styling not present in IE 8/9, Safari 5, and Chrome. */
abbr[title] { border-bottom: 1px dotted; }

/** Address style set to `bolder` in Firefox 4+, Safari 5, and Chrome. */
b, strong { font-weight: bold; }

/** Address styling not present in Safari 5 and Chrome. */
dfn { font-style: italic; }

/** Address differences between Firefox and other browsers. */
hr { -moz-box-sizing: content-box; box-sizing: content-box; height: 0; }

/** Address styling not present in IE 8/9. */
mark { background: #ff0; color: #000; }

/** Correct font family set oddly in Safari 5 and Chrome. */
code, kbd, pre, samp { font-family: monospace, serif; font-size: 1em; }

/** Improve readability of pre-formatted text in all browsers. */
pre { white-space: pre-wrap; }

/** Set consistent quote types. */
q { quotes: "\201C" "\201D" "\2018" "\2019"; }

/** Address inconsistent and variable font size in all browsers. */
small { font-size: 80%; }

/** Prevent `sub` and `sup` affecting `line-height` in all browsers. */
sub, sup { font-size: 75%; line-height: 0; position: relative; vertical-align: baseline; }

sup { top: -0.5em; }

sub { bottom: -0.25em; }

/* ========================================================================== Embedded content ========================================================================== */
/** Remove border when inside `a` element in IE 8/9. */
img { border: 0; }

/** Correct overflow displayed oddly in IE 9. */
svg:not(:root) { overflow: hidden; }

/* ========================================================================== Figures ========================================================================== */
/** Address margin not present in IE 8/9 and Safari 5. */
figure { margin: 0; }

/* ========================================================================== Forms ========================================================================== */
/** Define consistent border, margin, and padding. */
fieldset { border: 1px solid #c0c0c0; margin: 0 2px; padding: 0.35em 0.625em 0.75em; }

/** 1. Correct `color` not being inherited in IE 8/9. 2. Remove padding so people aren't caught out if they zero out fieldsets. */
legend { border: 0; /* 1 */ padding: 0; /* 2 */ }

/** 1. Correct font family not being inherited in all browsers. 2. Correct font size not being inherited in all browsers. 3. Address margins set differently in Firefox 4+, Safari 5, and Chrome. */
button, input, select, textarea { font-family: inherit; /* 1 */ font-size: 100%; /* 2 */ margin: 0; /* 3 */ }

/** Address Firefox 4+ setting `line-height` on `input` using `!important` in the UA stylesheet. */
button, input { line-height: normal; }

/** Address inconsistent `text-transform` inheritance for `button` and `select`. All other form control elements do not inherit `text-transform` values. Correct `button` style inheritance in Chrome, Safari 5+, and IE 8+. Correct `select` style inheritance in Firefox 4+ and Opera. */
button, select { text-transform: none; }

/** 1. Avoid the WebKit bug in Android 4.0.* where (2) destroys native `audio` and `video` controls. 2. Correct inability to style clickable `input` types in iOS. 3. Improve usability and consistency of cursor style between image-type `input` and others. */
button, html input[type="button"], input[type="reset"], input[type="submit"] { -webkit-appearance: button; /* 2 */ cursor: pointer; /* 3 */ }

/** Re-set default cursor for disabled elements. */
button[disabled], html input[disabled] { cursor: default; }

/** 1. Address box sizing set to `content-box` in IE 8/9. 2. Remove excess padding in IE 8/9. */
input[type="checkbox"], input[type="radio"] { box-sizing: border-box; /* 1 */ padding: 0; /* 2 */ }

/** 1. Address `appearance` set to `searchfield` in Safari 5 and Chrome. 2. Address `box-sizing` set to `border-box` in Safari 5 and Chrome (include `-moz` to future-proof). */
input[type="search"] { -webkit-appearance: textfield; /* 1 */ -moz-box-sizing: content-box; -webkit-box-sizing: content-box; /* 2 */ box-sizing: content-box; }

/** Remove inner padding and search cancel button in Safari 5 and Chrome on OS X. */
input[type="search"]::-webkit-search-cancel-button, input[type="search"]::-webkit-search-decoration { -webkit-appearance: none; }

/** Remove inner padding and border in Firefox 4+. */
button::-moz-focus-inner, input::-moz-focus-inner { border: 0; padding: 0; }

/** 1. Remove default vertical scrollbar in IE 8/9. 2. Improve readability and alignment in all browsers. */
textarea { overflow: auto; /* 1 */ vertical-align: top; /* 2 */ }

/* ========================================================================== Tables ========================================================================== */
/** Remove most spacing between table cells. */
table { border-collapse: collapse; border-spacing: 0; }

meta.foundation-mq-small { font-family: "only screen and (min-width: 768px)"; width: 768px; }

meta.foundation-mq-medium { font-family: "only screen and (min-width:1280px)"; width: 1280px; }

meta.foundation-mq-large { font-family: "only screen and (min-width:1440px)"; width: 1440px; }

*, *:before, *:after { -moz-box-sizing: border-box; -webkit-box-sizing: border-box; box-sizing: border-box; }

html, body { font-size: 100%; }

body { background: #fefdfd; color: rgba(0, 0, 0, 0.8); padding: 0; margin: 0; font-family: "Open Sans", sans-serif; font-weight: normal; font-style: normal; line-height: 1; position: relative; cursor: auto; }

a:hover { cursor: pointer; }

img, object, embed { max-width: 100%; height: auto; }

object, embed { height: 100%; }

img { -ms-interpolation-mode: bicubic; }

#map_canvas img, #map_canvas embed, #map_canvas object, .map_canvas img, .map_canvas embed, .map_canvas object { max-width: none !important; }

.left { float: left !important; }

.right { float: right !important; }

.text-left { text-align: left !important; }

.text-right { text-align: right !important; }

.text-center { text-align: center !important; }

.text-justify { text-align: justify !important; }

.hide { display: none; }

.antialiased { -webkit-font-smoothing: antialiased; }

img { display: inline-block; vertical-align: middle; }

textarea { height: auto; min-height: 50px; }

select { width: 100%; }

object, svg { display: inline-block; vertical-align: middle; }

.center { margin-left: auto; margin-right: auto; }

.stretch { width: 100%; }

p.lead { font-size: 1.21875em; line-height: 1.6; }

.subheader, .admonitionblock td.content > .title, .audioblock > .title, .exampleblock > .title, .imageblock > .title, .listingblock > .title, .literalblock > .title, .stemblock > .title, .openblock > .title, .paragraph > .title, .quoteblock > .title, table.tableblock > .title, .verseblock > .title, .videoblock > .title, .dlist > .title, .olist > .title, .ulist > .title, .qlist > .title, .hdlist > .title { line-height: 1.25; color: #002c5e; font-weight: 300; margin-top: 0.2em; margin-bottom: 0.5em; }

/* Typography resets */
div, dl, dt, dd, ul, ol, li, h1, h2, h3, #toctitle, .sidebarblock > .content > .title, h4, h5, h6, pre, form, p, blockquote, th, td { margin: 0; padding: 0; direction: ltr; }

/* Default Link Styles */
a { color: #005580; text-decoration: underline; line-height: inherit; }
a:hover, a:focus { color: #078d71; }
a img { border: none; }

/* Default paragraph styles */
p { font-family: inherit; font-weight: normal; font-size: 1em; line-height: 1.5; margin-bottom: 1.25em; text-rendering: optimizeLegibility; }
p aside { font-size: 0.875em; line-height: 1.35; font-style: italic; }

/* Default header styles */
h1, h2, h3, #toctitle, .sidebarblock > .content > .title, h4, h5, h6 { font-family: "Varela Round", sans-serif; font-weight: 400; font-style: normal; color: #00326b; text-rendering: optimizeLegibility; margin-top: 0.8em; margin-bottom: 0.5em; line-height: 1.0625em; }
h1 small, h2 small, h3 small, #toctitle small, .sidebarblock > .content > .title small, h4 small, h5 small, h6 small { font-size: 60%; color: #057aff; line-height: 0; }

h1 { font-size: 2.125em; }

h2 { font-size: 1.6875em; }

h3, #toctitle, .sidebarblock > .content > .title { font-size: 1.375em; }

h4 { font-size: 1.125em; }

h5 { font-size: 1.125em; }

h6 { font-size: 1em; }

hr { border: solid rgba(145, 135, 84, 0.15); border-width: 1px 0 0; clear: both; margin: 1.25em 0 1.1875em; height: 0; }

/* Helpful Typography Defaults */
em, i { font-style: italic; line-height: inherit; }

strong, b { font-weight: bold; line-height: inherit; }

small { font-size: 60%; line-height: inherit; }

code { font-family: "Ubuntu Mono", "Inconsolata", monospace; font-weight: 400; color: #331d00; }

/* Lists */
ul, ol, dl { font-size: 1em; line-height: 1.5; margin-bottom: 1.25em; list-style-position: outside; font-family: inherit; }

ul, ol { margin-left: 1.5em; }
ul.no-bullet, ol.no-bullet { margin-left: 1.5em; }

/* Unordered Lists */
ul li ul, ul li ol { margin-left: 1.25em; margin-bottom: 0; font-size: 1em; /* Override nested font-size change */ }
ul.square li ul, ul.circle li ul, ul.disc li ul { list-style: inherit; }
ul.square { list-style-type: square; }
ul.circle { list-style-type: circle; }
ul.disc { list-style-type: disc; }
ul.no-bullet { list-style: none; }

/* Ordered Lists */
ol li ul, ol li ol { margin-left: 1.25em; margin-bottom: 0; }

/* Definition Lists */
dl dt { margin-bottom: 0.3125em; font-weight: bold; }
dl dd { margin-bottom: 1.25em; }

/* Abbreviations */
abbr, acronym { text-transform: uppercase; font-size: 90%; color: rgba(0, 0, 0, 0.8); border-bottom: 1px dotted #dddddd; cursor: help; }

abbr { text-transform: none; }

/* Blockquotes */
blockquote { margin: 0 0 1.25em; padding: 0.5625em 1.25em 0 1.1875em; border-left: 1px solid #dddddd; }
blockquote cite { display: block; font-size: 0.8125em; color: #666666; }
blockquote cite:before { content: "\2014 \0020"; }
blockquote cite a, blockquote cite a:visited { color: #666666; }

blockquote, blockquote p { line-height: 1.5; color: #999999; }

/* Microformats */
.vcard { display: inline-block; margin: 0 0 1.25em 0; border: 1px solid #dddddd; padding: 0.625em 0.75em; }
.vcard li { margin: 0; display: block; }
.vcard .fn { font-weight: bold; font-size: 0.9375em; }

.vevent .summary { font-weight: bold; }
.vevent abbr { cursor: auto; text-decoration: none; font-weight: bold; border: none; padding: 0 0.0625em; }

@media only screen and (min-width: 768px) { h1, h2, h3, #toctitle, .sidebarblock > .content > .title, h4, h5, h6 { line-height: 1.25; }
  h1 { font-size: 2.75em; }
  h2 { font-size: 2.3125em; }
  h3, #toctitle, .sidebarblock > .content > .title { font-size: 1.6875em; }
  h4 { font-size: 1.4375em; } }
/* Tables */
table { background: white; margin-bottom: 1.25em; border: solid 1px rgba(145, 135, 84, 0.15); }
table thead, table tfoot { background: rgba(119, 84, 22, 0.1); font-weight: bold; }
table thead tr th, table thead tr td, table tfoot tr th, table tfoot tr td { padding: 0.5em 0.625em 0.625em; font-size: inherit; color: rgba(0, 0, 0, 0.8); text-align: left; }
table tr th, table tr td { padding: 0.5625em 0.625em; font-size: inherit; color: rgba(0, 0, 0, 0.8); }
table tr.even, table tr.alt, table tr:nth-of-type(even) { background: rgba(119, 84, 22, 0.025); }
table thead tr th, table tfoot tr th, table tbody tr td, table tr td, table tfoot tr td { display: table-cell; line-height: 1.5; }

body { -moz-osx-font-smoothing: grayscale; -webkit-font-smoothing: antialiased; tab-size: 4; }

h1, h2, h3, #toctitle, .sidebarblock > .content > .title, h4, h5, h6 { line-height: 1.25; }

.clearfix:before, .clearfix:after, .float-group:before, .float-group:after { content: " "; display: table; }
.clearfix:after, .float-group:after { clear: both; }

*:not(pre) > code { font-size: 1.0625em; font-style: normal !important; letter-spacing: 0; padding: 0; line-height: 1.25; word-wrap: break-word; }
*:not(pre) > code.nobreak { word-wrap: normal; }
*:not(pre) > code.nowrap { white-space: nowrap; }

pre, pre > code { line-height: 1.4; color: inherit; font-family: "Liberation Mono", "Consolas", monospace; font-weight: normal; }

em em { font-style: normal; }

strong strong { font-weight: normal; }

.keyseq { color: rgba(51, 51, 51, 0.8); }

kbd { font-family: "Ubuntu Mono", "Inconsolata", monospace; display: inline-block; color: rgba(0, 0, 0, 0.8); font-size: 0.65em; line-height: 1.45; background-color: #f7f7f7; border: 1px solid #ccc; -webkit-border-radius: 3px; border-radius: 3px; -webkit-box-shadow: 0 1px 0 rgba(0, 0, 0, 0.2), 0 0 0 0.1em white inset; box-shadow: 0 1px 0 rgba(0, 0, 0, 0.2), 0 0 0 0.1em white inset; margin: 0 0.15em; padding: 0.2em 0.5em; vertical-align: middle; position: relative; top: -0.1em; white-space: nowrap; }

.keyseq kbd:first-child { margin-left: 0; }

.keyseq kbd:last-child { margin-right: 0; }

.menuseq, .menuref { color: #000; }

.menuseq b:not(.caret), .menuref { font-weight: inherit; }

.menuseq { word-spacing: -0.02em; }
.menuseq b.caret { font-size: 1.25em; line-height: 0.8; }
.menuseq i.caret { font-weight: bold; text-align: center; width: 0.45em; }

b.button:before, b.button:after { position: relative; top: -1px; font-weight: normal; }

b.button:before { content: "["; padding: 0 3px 0 2px; }

b.button:after { content: "]"; padding: 0 2px 0 3px; }

p a > code:hover { color: #1a0f00; }

#header, #content, #footnotes, #footer { width: 100%; margin-left: auto; margin-right: auto; margin-top: 0; margin-bottom: 0; max-width: 62.5em; *zoom: 1; position: relative; padding-left: 0.9375em; padding-right: 0.9375em; }
#header:before, #header:after, #content:before, #content:after, #footnotes:before, #footnotes:after, #footer:before, #footer:after { content: " "; display: table; }
#header:after, #content:after, #footnotes:after, #footer:after { clear: both; }

#content { margin-top: 1.25em; }

#content:before { content: none; }

#header > h1:first-child { color: #703f1c; margin-top: 2.25rem; margin-bottom: 0; }
#header > h1:first-child + #toc { margin-top: 8px; border-top: 1px solid rgba(145, 135, 84, 0.15); }
#header > h1:only-child, body.toc2 #header > h1:nth-last-child(2) { border-bottom: 1px solid rgba(145, 135, 84, 0.15); padding-bottom: 8px; }
#header .details { border-bottom: 1px solid rgba(145, 135, 84, 0.15); line-height: 1.45; padding-top: 0.25em; padding-bottom: 0.25em; padding-left: 0.25em; color: #666666; display: -ms-flexbox; display: -webkit-flex; display: flex; -ms-flex-flow: row wrap; -webkit-flex-flow: row wrap; flex-flow: row wrap; }
#header .details span:first-child { margin-left: -0.125em; }
#header .details span.email a { color: #999999; }
#header .details br { display: none; }
#header .details br + span:before { content: "\00a0\2013\00a0"; }
#header .details br + span.author:before { content: "\00a0\22c5\00a0"; color: #999999; }
#header .details br + span#revremark:before { content: "\00a0|\00a0"; }
#header #revnumber { text-transform: capitalize; }
#header #revnumber:after { content: "\00a0"; }

#content > h1:first-child:not([class]) { color: #703f1c; border-bottom: 1px solid rgba(145, 135, 84, 0.15); padding-bottom: 8px; margin-top: 0; padding-top: 1rem; margin-bottom: 1.25rem; }

#toc { border-bottom: 0px solid #dddddd; padding-bottom: 0.5em; }
#toc > ul { margin-left: 0.125em; }
#toc ul.sectlevel0 > li > a { font-style: italic; }
#toc ul.sectlevel0 ul.sectlevel1 { margin: 0.5em 0; }
#toc ul { font-family: "Varela Round", sans-serif; list-style-type: none; }
#toc li { line-height: 1.3334; margin-top: 0.3334em; }
#toc a { text-decoration: none; }
#toc a:active { text-decoration: underline; }

#toctitle { color: #002c5e; font-size: 1.2em; }

@media only screen and (min-width: 768px) { #toctitle { font-size: 1.375em; }
  body.toc2 { padding-left: 15em; padding-right: 0; }
  #toc.toc2 { margin-top: 0 !important; background-color: #f2f2f4; position: fixed; width: 15em; left: 0; top: 0; border-right: 1px solid #dddddd; border-top-width: 0 !important; border-bottom-width: 0 !important; z-index: 1000; padding: 1.25em 1em; height: 100%; overflow: auto; }
  #toc.toc2 #toctitle { margin-top: 0; margin-bottom: 0.8rem; font-size: 1.2em; }
  #toc.toc2 > ul { font-size: 0.9em; margin-bottom: 0; }
  #toc.toc2 ul ul { margin-left: 0; padding-left: 1em; }
  #toc.toc2 ul.sectlevel0 ul.sectlevel1 { padding-left: 0; margin-top: 0.5em; margin-bottom: 0.5em; }
  body.toc2.toc-right { padding-left: 0; padding-right: 15em; }
  body.toc2.toc-right #toc.toc2 { border-right-width: 0; border-left: 1px solid #dddddd; left: auto; right: 0; } }
@media only screen and (min-width: 1280px) { body.toc2 { padding-left: 20em; padding-right: 0; }
  #toc.toc2 { width: 20em; }
  #toc.toc2 #toctitle { font-size: 1.375em; }
  #toc.toc2 > ul { font-size: 0.95em; }
  #toc.toc2 ul ul { padding-left: 1.25em; }
  body.toc2.toc-right { padding-left: 0; padding-right: 20em; } }
#content #toc { border-style: solid; border-width: 1px; border-color: #d6d6dd; margin-bottom: 1.25em; padding: 1.25em; background: #f2f2f4; -webkit-border-radius: 6px; border-radius: 6px; }
#content #toc > :first-child { margin-top: 0; }
#content #toc > :last-child { margin-bottom: 0; }

#footer { max-width: 100%; background-color: #0b445a; padding: 1.25em; }

#footer-text { color: #fefdfd; line-height: 1.35; }

#content { margin-bottom: 0.625em; }

.sect1 { padding-bottom: 0.625em; }

@media only screen and (min-width: 768px) { #content { margin-bottom: 1.25em; }
  .sect1 { padding-bottom: 1.25em; } }
.sect1:last-child { padding-bottom: 0; }

.sect1 + .sect1 { border-top: 0px solid #dddddd; }

#content h1 > a.anchor, h2 > a.anchor, h3 > a.anchor, #toctitle > a.anchor, .sidebarblock > .content > .title > a.anchor, h4 > a.anchor, h5 > a.anchor, h6 > a.anchor { position: absolute; z-index: 1001; width: 1.5ex; margin-left: -1.5ex; display: block; text-decoration: none !important; visibility: hidden; text-align: center; font-weight: normal; }
#content h1 > a.anchor:before, h2 > a.anchor:before, h3 > a.anchor:before, #toctitle > a.anchor:before, .sidebarblock > .content > .title > a.anchor:before, h4 > a.anchor:before, h5 > a.anchor:before, h6 > a.anchor:before { content: "\00A7"; font-size: 0.85em; display: block; padding-top: 0.1em; }
#content h1:hover > a.anchor, #content h1 > a.anchor:hover, h2:hover > a.anchor, h2 > a.anchor:hover, h3:hover > a.anchor, #toctitle:hover > a.anchor, .sidebarblock > .content > .title:hover > a.anchor, h3 > a.anchor:hover, #toctitle > a.anchor:hover, .sidebarblock > .content > .title > a.anchor:hover, h4:hover > a.anchor, h4 > a.anchor:hover, h5:hover > a.anchor, h5 > a.anchor:hover, h6:hover > a.anchor, h6 > a.anchor:hover { visibility: visible; }
#content h1 > a.link, h2 > a.link, h3 > a.link, #toctitle > a.link, .sidebarblock > .content > .title > a.link, h4 > a.link, h5 > a.link, h6 > a.link { color: #00326b; text-decoration: none; }
#content h1 > a.link:hover, h2 > a.link:hover, h3 > a.link:hover, #toctitle > a.link:hover, .sidebarblock > .content > .title > a.link:hover, h4 > a.link:hover, h5 > a.link:hover, h6 > a.link:hover { color: #002652; }

.audioblock, .imageblock, .literalblock, .listingblock, .stemblock, .videoblock { margin-bottom: 1.25em; }

.admonitionblock td.content > .title, .audioblock > .title, .exampleblock > .title, .imageblock > .title, .listingblock > .title, .literalblock > .title, .stemblock > .title, .openblock > .title, .paragraph > .title, .quoteblock > .title, table.tableblock > .title, .verseblock > .title, .videoblock > .title, .dlist > .title, .olist > .title, .ulist > .title, .qlist > .title, .hdlist > .title { text-rendering: optimizeLegibility; text-align: left; }

table.tableblock.fit-content > caption.title { white-space: nowrap; width: 0; }

.paragraph.lead > p, #preamble > .sectionbody > [class="paragraph"]:first-of-type p { font-size: 1.21875em; line-height: 1.6; color: #703f1c; }

table.tableblock #preamble > .sectionbody > [class="paragraph"]:first-of-type p { font-size: inherit; }

.admonitionblock > table { border-collapse: separate; border: 0; background: none; width: 100%; }
.admonitionblock > table td.icon { text-align: center; width: 80px; }
.admonitionblock > table td.icon img { max-width: none; }
.admonitionblock > table td.icon .title { font-weight: bold; font-family: "Varela Round", sans-serif; text-transform: uppercase; }
.admonitionblock > table td.content { padding-left: 1.125em; padding-right: 1.25em; border-left: 1px solid rgba(145, 135, 84, 0.15); color: #666666; }
.admonitionblock > table td.content > :last-child > :last-child { margin-bottom: 0; }

.exampleblock > .content { border-style: solid; border-width: 1px; border-color: #eddbdb; margin-bottom: 1.25em; padding: 1.25em; background: #fefdfd; -webkit-border-radius: 6px; border-radius: 6px; }
.exampleblock > .content > :first-child { margin-top: 0; }
.exampleblock > .content > :last-child { margin-bottom: 0; }

.sidebarblock { border-style: solid; border-width: 1px; border-color: #d6d6dd; margin-bottom: 1.25em; padding: 1.25em; background: #f2f2f4; -webkit-border-radius: 6px; border-radius: 6px; }
.sidebarblock > :first-child { margin-top: 0; }
.sidebarblock > :last-child { margin-bottom: 0; }
.sidebarblock > .content > .title { color: #002c5e; margin-top: 0; }

.exampleblock > .content > :last-child > :last-child, .exampleblock > .content .olist > ol > li:last-child > :last-child, .exampleblock > .content .ulist > ul > li:last-child > :last-child, .exampleblock > .content .qlist > ol > li:last-child > :last-child, .sidebarblock > .content > :last-child > :last-child, .sidebarblock > .content .olist > ol > li:last-child > :last-child, .sidebarblock > .content .ulist > ul > li:last-child > :last-child, .sidebarblock > .content .qlist > ol > li:last-child > :last-child { margin-bottom: 0; }

.literalblock pre, .listingblock pre:not(.highlight), .listingblock pre[class="highlight"], .listingblock pre[class^="highlight "], .listingblock pre.CodeRay, .listingblock pre.prettyprint { background: rgba(16, 195, 196, 0.05); }
.sidebarblock .literalblock pre, .sidebarblock .listingblock pre:not(.highlight), .sidebarblock .listingblock pre[class="highlight"], .sidebarblock .listingblock pre[class^="highlight "], .sidebarblock .listingblock pre.CodeRay, .sidebarblock .listingblock pre.prettyprint { background: #f2f1f1; }

.literalblock pre, .literalblock pre[class], .listingblock pre, .listingblock pre[class] { border: 1px solid rgba(16, 195, 196, 0.125); -webkit-border-radius: 6px; border-radius: 6px; word-wrap: break-word; padding: 1em; font-size: 0.8125em; }
.literalblock pre.nowrap, .literalblock pre[class].nowrap, .listingblock pre.nowrap, .listingblock pre[class].nowrap { overflow-x: auto; white-space: pre; word-wrap: normal; }
@media only screen and (min-width: 768px) { .literalblock pre, .literalblock pre[class], .listingblock pre, .listingblock pre[class] { font-size: 0.90625em; } }
@media only screen and (min-width: 1280px) { .literalblock pre, .literalblock pre[class], .listingblock pre, .listingblock pre[class] { font-size: 1em; } }

.literalblock.output pre { color: rgba(16, 195, 196, 0.05); background-color: inherit; }

.listingblock pre.highlightjs { padding: 0; }
.listingblock pre.highlightjs > code { padding: 1em; -webkit-border-radius: 6px; border-radius: 6px; }

.listingblock > .content { position: relative; }

.listingblock code[data-lang]:before { display: none; content: attr(data-lang); position: absolute; font-size: 0.75em; top: 0.425rem; right: 0.5rem; line-height: 1; text-transform: uppercase; color: #999; }

.listingblock:hover code[data-lang]:before { display: block; }

.listingblock.terminal pre .command:before { content: attr(data-prompt); padding-right: 0.5em; color: #999; }

.listingblock.terminal pre .command:not([data-prompt]):before { content: "$"; }

table.pyhltable { border-collapse: separate; border: 0; margin-bottom: 0; background: none; }

table.pyhltable td { vertical-align: top; padding-top: 0; padding-bottom: 0; line-height: 1.4; }

table.pyhltable td.code { padding-left: .75em; padding-right: 0; }

pre.pygments .lineno, table.pyhltable td:not(.code) { color: #999; padding-left: 0; padding-right: .5em; border-right: 1px solid rgba(145, 135, 84, 0.15); }

pre.pygments .lineno { display: inline-block; margin-right: .25em; }

table.pyhltable .linenodiv { background: none !important; padding-right: 0 !important; }

.quoteblock { margin: 0 1em 1.25em 1.5em; display: table; }
.quoteblock > .title { margin-left: -1.5em; margin-bottom: 0.75em; }
.quoteblock blockquote, .quoteblock blockquote p { color: #999999; font-size: 1.15rem; line-height: 1.75; word-spacing: 0.1em; letter-spacing: 0; font-style: italic; text-align: justify; }
.quoteblock blockquote { margin: 0; padding: 0; border: 0; }
.quoteblock blockquote:before { content: "\201c"; float: left; font-size: 2.75em; font-weight: bold; line-height: 0.6em; margin-left: -0.6em; color: #002c5e; text-shadow: 0 1px 2px rgba(0, 0, 0, 0.1); }
.quoteblock blockquote > .paragraph:last-child p { margin-bottom: 0; }
.quoteblock .attribution { margin-top: 0.5em; margin-right: 0.5ex; text-align: right; }
.quoteblock .quoteblock { margin-left: 0; margin-right: 0; padding: 0.5em 0; border-left: 3px solid #666666; }
.quoteblock .quoteblock blockquote { padding: 0 0 0 0.75em; }
.quoteblock .quoteblock blockquote:before { display: none; }

.verseblock { margin: 0 1em 1.25em 1em; }
.verseblock pre { font-family: "Open Sans", "DejaVu Sans", sans; font-size: 1.15rem; color: #999999; font-weight: 300; text-rendering: optimizeLegibility; }
.verseblock pre strong { font-weight: 400; }
.verseblock .attribution { margin-top: 1.25rem; margin-left: 0.5ex; }

.quoteblock .attribution, .verseblock .attribution { font-size: 0.8125em; line-height: 1.45; font-style: italic; }
.quoteblock .attribution br, .verseblock .attribution br { display: none; }
.quoteblock .attribution cite, .verseblock .attribution cite { display: block; letter-spacing: -0.025em; color: #666666; }

.quoteblock.abstract { margin: 0 1em 1.25em 1em; display: block; }
.quoteblock.abstract > .title { margin: 0 0 0.375em 0; font-size: 1.15em; text-align: center; }
.quoteblock.abstract blockquote, .quoteblock.abstract blockquote p { word-spacing: 0; line-height: 1.6; }
.quoteblock.abstract blockquote:before, .quoteblock.abstract p:before { display: none; }

table.tableblock { max-width: 100%; border-collapse: separate; }

p.tableblock:last-child { margin-bottom: 0; }

td.tableblock > .content { margin-bottom: -1.25em; }

table.tableblock, th.tableblock, td.tableblock { border: 0 solid rgba(145, 135, 84, 0.15); }

table.grid-all > thead > tr > .tableblock, table.grid-all > tbody > tr > .tableblock { border-width: 0 1px 1px 0; }

table.grid-all > tfoot > tr > .tableblock { border-width: 1px 1px 0 0; }

table.grid-cols > * > tr > .tableblock { border-width: 0 1px 0 0; }

table.grid-rows > thead > tr > .tableblock, table.grid-rows > tbody > tr > .tableblock { border-width: 0 0 1px 0; }

table.grid-rows > tfoot > tr > .tableblock { border-width: 1px 0 0 0; }

table.grid-all > * > tr > .tableblock:last-child, table.grid-cols > * > tr > .tableblock:last-child { border-right-width: 0; }

table.grid-all > tbody > tr:last-child > .tableblock, table.grid-all > thead:last-child > tr > .tableblock, table.grid-rows > tbody > tr:last-child > .tableblock, table.grid-rows > thead:last-child > tr > .tableblock { border-bottom-width: 0; }

table.frame-all { border-width: 1px; }

table.frame-sides { border-width: 0 1px; }

table.frame-topbot, table.frame-ends { border-width: 1px 0; }

table.stripes-all tr, table.stripes-odd tr:nth-of-type(odd) { background: rgba(119, 84, 22, 0.025); }

table.stripes-none tr, table.stripes-odd tr:nth-of-type(even) { background: none; }

th.halign-left, td.halign-left { text-align: left; }

th.halign-right, td.halign-right { text-align: right; }

th.halign-center, td.halign-center { text-align: center; }

th.valign-top, td.valign-top { vertical-align: top; }

th.valign-bottom, td.valign-bottom { vertical-align: bottom; }

th.valign-middle, td.valign-middle { vertical-align: middle; }

table thead th, table tfoot th { font-weight: bold; }

tbody tr th { display: table-cell; line-height: 1.5; background: rgba(119, 84, 22, 0.1); }

tbody tr th, tbody tr th p, tfoot tr th, tfoot tr th p { color: rgba(0, 0, 0, 0.8); font-weight: bold; }

p.tableblock > code:only-child { background: none; padding: 0; }

p.tableblock { font-size: 1em; }

td > div.verse { white-space: pre; }

ol { margin-left: 1.75em; }

ul li ol { margin-left: 1.5em; }

dl dd { margin-left: 1.125em; }

dl dd:last-child, dl dd:last-child > :last-child { margin-bottom: 0; }

ol > li p, ul > li p, ul dd, ol dd, .olist .olist, .ulist .ulist, .ulist .olist, .olist .ulist { margin-bottom: 0.625em; }

ul.checklist, ul.none, ol.none, ul.no-bullet, ol.no-bullet, ol.unnumbered, ul.unstyled, ol.unstyled { list-style-type: none; }

ul.no-bullet, ol.no-bullet, ol.unnumbered { margin-left: 0.625em; }

ul.unstyled, ol.unstyled { margin-left: 0; }

ul.checklist { margin-left: 0.625em; }

ul.checklist li > p:first-child > .fa-square-o:first-child, ul.checklist li > p:first-child > .fa-check-square-o:first-child { width: 1.25em; font-size: 0.8em; position: relative; bottom: 0.125em; }

ul.checklist li > p:first-child > input[type="checkbox"]:first-child { margin-right: 0.25em; }

ul.inline { display: -ms-flexbox; display: -webkit-box; display: flex; -ms-flex-flow: row wrap; -webkit-flex-flow: row wrap; flex-flow: row wrap; list-style: none; margin: 0 0 0.625em -1.25em; }

ul.inline > li { margin-left: 1.25em; }

.unstyled dl dt { font-weight: normal; font-style: normal; }

ol.arabic { list-style-type: decimal; }

ol.decimal { list-style-type: decimal-leading-zero; }

ol.loweralpha { list-style-type: lower-alpha; }

ol.upperalpha { list-style-type: upper-alpha; }

ol.lowerroman { list-style-type: lower-roman; }

ol.upperroman { list-style-type: upper-roman; }

ol.lowergreek { list-style-type: lower-greek; }

.hdlist > table, .colist > table { border: 0; background: none; }
.hdlist > table > tbody > tr, .colist > table > tbody > tr { background: none; }

td.hdlist1, td.hdlist2 { vertical-align: top; padding: 0 0.625em; }

td.hdlist1 { font-weight: bold; padding-bottom: 1.25em; }

.literalblock + .colist, .listingblock + .colist { margin-top: -0.5em; }

.colist td:not([class]):first-child { padding: 0.4em 0.75em 0 0.75em; line-height: 1; vertical-align: top; }
.colist td:not([class]):first-child img { max-width: none; }
.colist td:not([class]):last-child { padding: 0.25em 0; }

.thumb, .th { line-height: 0; display: inline-block; border: solid 4px white; -webkit-box-shadow: 0 0 0 1px #dddddd; box-shadow: 0 0 0 1px #dddddd; }

.imageblock.left { margin: 0.25em 0.625em 1.25em 0; }
.imageblock.right { margin: 0.25em 0 1.25em 0.625em; }
.imageblock > .title { margin-bottom: 0; }
.imageblock.thumb, .imageblock.th { border-width: 6px; }
.imageblock.thumb > .title, .imageblock.th > .title { padding: 0 0.125em; }

.image.left, .image.right { margin-top: 0.25em; margin-bottom: 0.25em; display: inline-block; line-height: 0; }
.image.left { margin-right: 0.625em; }
.image.right { margin-left: 0.625em; }

a.image { text-decoration: none; display: inline-block; }
a.image object { pointer-events: none; }

sup.footnote, sup.footnoteref { font-size: 0.875em; position: static; vertical-align: super; }
sup.footnote a, sup.footnoteref a { text-decoration: none; }
sup.footnote a:active, sup.footnoteref a:active { text-decoration: underline; }

#footnotes { padding-top: 0.75em; padding-bottom: 0.75em; margin-bottom: 0.625em; }
#footnotes hr { width: 20%; min-width: 6.25em; margin: -0.25em 0 0.75em 0; border-width: 1px 0 0 0; }
#footnotes .footnote { padding: 0 0.375em 0 0.225em; line-height: 1.3334; font-size: 0.875em; margin-left: 1.2em; margin-bottom: 0.2em; }
#footnotes .footnote a:first-of-type { font-weight: bold; text-decoration: none; margin-left: -1.05em; }
#footnotes .footnote:last-of-type { margin-bottom: 0; }
#content #footnotes { margin-top: -0.625em; margin-bottom: 0; padding: 0.75em 0; }

.gist .file-data > table { border: 0; background: #fff; width: 100%; margin-bottom: 0; }
.gist .file-data > table td.line-data { width: 99%; }

div.unbreakable { page-break-inside: avoid; }

.big { font-size: larger; }

.small { font-size: smaller; }

.underline { text-decoration: underline; }

.overline { text-decoration: overline; }

.line-through { text-decoration: line-through; }

.aqua { color: #00bfbf; }

.aqua-background { background-color: #00fafa; }

.black { color: black; }

.black-background { background-color: black; }

.blue { color: #0000bf; }

.blue-background { background-color: #0000fa; }

.fuchsia { color: #bf00bf; }

.fuchsia-background { background-color: #fa00fa; }

.gray { color: #606060; }

.gray-background { background-color: #7d7d7d; }

.green { color: #006000; }

.green-background { background-color: #007d00; }

.lime { color: #00bf00; }

.lime-background { background-color: #00fa00; }

.maroon { color: #600000; }

.maroon-background { background-color: #7d0000; }

.navy { color: #000060; }

.navy-background { background-color: #00007d; }

.olive { color: #606000; }

.olive-background { background-color: #7d7d00; }

.purple { color: #600060; }

.purple-background { background-color: #7d007d; }

.red { color: #bf0000; }

.red-background { background-color: #fa0000; }

.silver { color: #909090; }

.silver-background { background-color: #bcbcbc; }

.teal { color: #006060; }

.teal-background { background-color: #007d7d; }

.white { color: #bfbfbf; }

.white-background { background-color: #fafafa; }

.yellow { color: #bfbf00; }

.yellow-background { background-color: #fafa00; }

span.icon > .fa { cursor: default; }
a span.icon > .fa { cursor: inherit; }

.admonitionblock td.icon [class^="fa icon-"] { font-size: 2.5em; text-shadow: 1px 1px 2px rgba(0, 0, 0, 0.5); cursor: default; }
.admonitionblock td.icon .icon-note:before { content: "\f05a"; color: #004060; }
.admonitionblock td.icon .icon-tip:before { content: "\f0eb"; text-shadow: 1px 1px 2px rgba(155, 155, 0, 0.8); color: #111; }
.admonitionblock td.icon .icon-warning:before { content: "\f071"; color: #bf6900; }
.admonitionblock td.icon .icon-caution:before { content: "\f06d"; color: #bf3400; }
.admonitionblock td.icon .icon-important:before { content: "\f06a"; color: #bf0000; }

.conum[data-value] { display: inline-block; color: #fff !important; background-color: rgba(0, 0, 0, 0.8); -webkit-border-radius: 100px; border-radius: 100px; text-align: center; font-size: 0.75em; width: 1.67em; height: 1.67em; line-height: 1.67em; font-family: "Open Sans", "DejaVu Sans", sans-serif; font-style: normal; font-weight: bold; }
.conum[data-value] * { color: #fff !important; }
.conum[data-value] + b { display: none; }
.conum[data-value]:after { content: attr(data-value); }
pre .conum[data-value] { position: relative; top: -0.125em; }

b.conum * { color: inherit !important; }

.conum:not([data-value]):empty { display: none; }

#toc.toc2 ul ul { list-style-type: circle; padding-left: 2em; }

.sect1 { padding-bottom: 0 !important; margin-bottom: 2.5em; }

#header h1 { font-weight: bold; position: relative; left: -0.0625em; }

#content h2, #content h3, #content #toctitle, #content .sidebarblock > .content > .title, #content h4, #content h5, #content #toctitle { position: relative; left: -0.0625em; }
#content h2 { font-weight: bold; }

.paragraph.lead > p, #preamble > .sectionbody > .paragraph:first-of-type p { color: black; }

pre.pygments.highlight { background-color: rgba(16, 195, 196, 0.05); }

.pygments .tok-err { border: none !important; color: #800000 !important; }

.pygments .tok-c { color: #999 !important; }

</style>
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.6.3/css/font-awesome.min.css">
<style>
/* Pygments styles disabled. Pygments is not available. */
</style>
</head>
<body class="article toc2 toc-left">
<div id="header">
<h1>IGoR (<em>Inference and Generation Of Repertoires</em>) Documentation</h1>
<div class="details">
<span id="author" class="author">Quentin Marcou</span><br>
</div>
<div id="toc" class="toc2">
<div id="toctitle">Table of Contents</div>
<ul class="sectlevel1">
<li><a href="#version">Version</a></li>
<li><a href="#dependencies">Dependencies</a></li>
<li><a href="#install">Install</a>
<ul class="sectlevel2">
<li><a href="#linux">Linux</a></li>
<li><a href="#macos">MacOS</a></li>
<li><a href="#windows-not-tested">Windows (not tested)</a></li>
<li><a href="#troubleshoots">Troubleshoots</a></li>
</ul>
</li>
<li><a href="#workflow">Workflow</a>
<ul class="sectlevel2">
<li><a href="#using-predefined-genomic-templates-and-models">Predefined genomic templates and models</a></li>
<li><a href="#models-validity">Validity of the recombination and error models</a></li>
</ul>
</li>
<li><a href="#runtimes">Runtimes</a></li>
<li><a href="#command-line-tools">Command line tools</a>
<ul class="sectlevel2">
<li><a href="#general">General</a>
<ul class="sectlevel3">
<li><a href="#general-commands-summary">General commands summary</a></li>
<li><a href="#scripts">Bash scripts</a></li>
<li><a href="#working-directory">Working directory</a></li>
</ul>
</li>
<li><a href="#alignments">Alignments</a>
<ul class="sectlevel3">
<li><a href="#algorithm">Algorithm</a></li>
<li><a href="#alignment-commands-summary">Alignment commands summary</a></li>
<li><a href="#alignment-output-files-summary">Alignment output files summary</a></li>
</ul>
</li>
<li><a href="#inference-and-evaluation">Inference and evaluation</a>
<ul class="sectlevel3">
<li><a href="#inference-and-evaluation-commands">Inference and evaluation commands</a></li>
<li><a href="#inference-and-evaluation-output">Inference and evaluation output</a></li>
<li><a href="#inference-and-evaluation-troubleshoots">Inference and evaluation Troubleshoots</a></li>
</ul>
</li>
<li><a href="#outputs">Outputs</a>
<ul class="sectlevel3">
<li><a href="#best-scenarios">Best scenarios</a></li>
<li><a href="#generation-probability">Generation probability</a></li>
<li><a href="#coverage">Coverage</a></li>
</ul>
</li>
<li><a href="#sequence-generation">Sequence generation</a>
<ul class="sectlevel3">
<li><a href="#sequence-generation-commands">Sequence generation commands</a></li>
</ul>
</li>
<li><a href="#command-examples">Command examples</a></li>
</ul>
</li>
<li><a href="#advanced-usage">Advanced usage</a></li>
<li><a href="#c">C++</a></li>
<li><a href="#python">Python</a></li>
<li><a href="#contribute">Contribute</a></li>
<li><a href="#contact">Contact</a></li>
<li><a href="#_copying">Copying</a></li>
</ul>
</div>
</div>
<div id="content">
<div id="preamble">
<div class="sectionbody">
<div class="paragraph">
<p>IGoR is a C++ software designed to infer V(D)J recombination related
processes from sequencing data such as:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>Recombination model probability distribution</p>
</li>
<li>
<p>Hypermutation model</p>
</li>
<li>
<p>Best candidates recombination scenarios</p>
</li>
<li>
<p>Generation probabilities of sequences (even hypermutated)</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>The following article describes the methodology, performance tests and
some new biological results obtained with IGoR:</p>
</div>
<div class="paragraph">
<p><a href="https://www.nature.com/articles/s41467-018-02832-w"><em>High-throughput
immune repertoire analysis with IGoR</em></a>, <em>Nature Communications</em>, (2018)
Quentin Marcou, Thierry Mora, Aleksandra M. Walczak</p>
</div>
<div class="paragraph">
<p>Its heavily object oriented and modular style was designed to ensure
long term support and evolvability for new tasks in assessing TCR and
BCR receptors features using modern parallel architectures.</p>
</div>
<div class="paragraph">
<p>IGoR is a free (as in freedom) software released under the
<a href="https://www.gnu.org/licenses/quick-guide-gplv3.html">GNU-GPLv3</a> license.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="version">Version</h2>
<div class="sectionbody">
<div class="paragraph">
<p>Latest released version: 1.3.0</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="dependencies">Dependencies</h2>
<div class="sectionbody">
<div class="ulist">
<ul>
<li>
<p>a C++ compiler supporting OpenMP 3.8 or higher and POSIX Threads
(pthread) such as GCC (GNU C Compiler)</p>
</li>
<li>
<p><a href="https://www.gnu.org/software/gsl/">GSL library</a> : a subpart of the
library is shipped with IGoR and will be statically linked to IGoR&#8217;s
executable to avoid dependencies</p>
</li>
<li>
<p><a href="http://jemalloc.net/">jemalloc</a> (optional although recommended for full
parallel proficiency) memory allocation library: also shipped with IGoR
to avoid dependencies issues (requires a pthreads compatible compiler)</p>
</li>
<li>
<p>bash</p>
</li>
<li>
<p>autotools suite, asciidoctor, pygments (optional), doxygen and the latex
suite if building from unpackaged sources</p>
</li>
</ul>
</div>
</div>
</div>
<div class="sect1">
<h2 id="install">Install</h2>
<div class="sectionbody">
<div class="paragraph">
<p>IGoR uses the autotools suite for compilation and installation in order
to ensure portability to many systems.</p>
</div>
<div class="paragraph">
<p><em>Installing from packaged releases (recommended)</em></p>
</div>
<div class="paragraph">
<p>First download the latest released package on the
<a href="https://github.com/qmarcou/IGoR/releases">Release page</a>. Extract the
files from the archive.</p>
</div>
<div class="paragraph">
<p><em>Installing from unpackaged sources (by cloning or direct download of
the repository)</em></p>
</div>
<div class="paragraph">
<p>For this you will have to get git, and all other dependencies mentioned above.
 Note that this is the most convenient way to keep IGoR up-to-date but involves
 a few extra installation steps.
 Using <em>git</em>, clone the repository where you desire.
Go in the created directory and run the <em>autogen.sh</em> bash script. This
will create the <em>configure</em> script. Upon this stage the installation
rules are the same as for packaged developer sources. From <em>git</em> you can
chose among two branches: the <em>master</em> branch corresponds to the latest
stable (packaged) release, the dev branch is the most up to date branch
including current developpments until they are issued in the next
release. The <em>dev</em> branch is therefore more bug prone, however this is
the natural branch for people ready to help with developpment (even only
by functionality testing).</p>
</div>
<div class="paragraph">
<p>A (sadly) non exhaustive list of potential installation troubleshoots
follows in the next section. If your problem is not referenced there
please open a GitHub <a href="https://github.com/qmarcou/IGoR/issues">issue</a>. If you end
 up finding a solution by yourself please help us append it to the following
 list and help the user community.</p>
</div>
<div class="admonitionblock tip">
<table>
<tr>
<td class="icon">
<i class="fa icon-tip" title="Tip"></i>
</td>
<td class="content">
To upgrade IGoR uninstall your previously installed version and install
 the new one.
</td>
</tr>
</table>
</div>
<div class="sect2">
<h3 id="linux">Linux</h3>
<div class="paragraph">
<p>Widely tested on several Debian related distros. Install gcc/g++ if not
already installed (note that another compiler could be used). With the
command line go to IGoR&#8217;s root directory and simply type <code>./configure</code>.
This will make various check on your system and create makefiles
compatible with your system configuration. Many options can be appended
to ./configure such as <code>./configure CC=gcc CXX=g+ +</code> to enforce the use
of gcc as compiler. The full set of the configure script options can be found
<a href="https://www.gnu.org/software/autoconf/manual/autoconf.html#Running-configure-Scripts">here</a>.</p>
</div>
<div class="paragraph">
<p>Once over, type <code>make</code> to compile the sources (this
will take a few minutes). <em>IGoR&#8217;s executable will appear in the igor_src
folder</em></p>
</div>
<div class="paragraph">
<p>Finally in order to access all IGoR&#8217;s features, install IGoR by typing
<code>make install</code>. This will install IGoR&#8217;s executable, supplied models and
manual in your system&#8217;s default location (note that depending on this
location you might require administrator privileges and use the <code>sudo</code>
prefix). If you do not have administrator privileges, IGoR can be
installed locally in the folder of your choice by passing
<code>--prefix=/your/custom/path</code> upon calling the configure script (e.g
<code>./configure --prefix=$HOME</code>). Other configure options can be accessed
using ./configure -h.</p>
</div>
<div class="paragraph">
<p>As a brief summary for default installation use the following set of commands:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="pygments highlight"><code data-lang="shell">./configure  <i class="conum" data-value="1"></i><b>(1)</b>
make  <i class="conum" data-value="2"></i><b>(2)</b>
make install  <i class="conum" data-value="3"></i><b>(3)</b></code></pre>
</div>
</div>
<div class="colist arabic">
<table>
<tr>
<td><i class="conum" data-value="1"></i><b>1</b></td>
<td>Specify your custom installation options at this step.</td>
</tr>
<tr>
<td><i class="conum" data-value="2"></i><b>2</b></td>
<td>Compile the sources before installation.</td>
</tr>
<tr>
<td><i class="conum" data-value="3"></i><b>3</b></td>
<td>Install IGoR.</td>
</tr>
</table>
</div>
<div class="admonitionblock tip">
<table>
<tr>
<td class="icon">
<i class="fa icon-tip" title="Tip"></i>
</td>
<td class="content">
Clean uninstallation of IGoR (e.g before upgrading IGoR to a newer version)
is obtained via the <code>make uninstall</code> command.
</td>
</tr>
</table>
</div>
</div>
<div class="sect2">
<h3 id="macos">MacOS</h3>
<div class="paragraph">
<p>MacOS is shipped with another compiler (Clang) when installing Xcode
that is called upon calling gcc (through name aliasing) and is not
supporting OpenMP. In order to use gcc and compile with it an OpenMP
application you will first need to download Macports or Homebrew and
install gcc from there.</p>
</div>
<div class="paragraph">
<p>First if not already present on your system install XCode through the
application store.</p>
</div>
<div class="paragraph">
<p>Macports can be found <a href="https://www.macports.org/install.php">here</a>. Download and install the
version corresponding to your MacOS version.</p>
</div>
<div class="paragraph">
<p>Once installed, use Macports to install GCC:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="pygments highlight"><code data-lang="shell">sudo port selfupdate #Update macports database
sudo port install gcc6 #install gcc version 6</code></pre>
</div>
</div>
<div class="paragraph">
<p>The full list of available GCC versions is available
<a href="https://www.macports.org/ports.php?by=name&amp;substr=gcc">here</a>, select a sufficiently recent one to get C++11
standards enabled. In order to set GCC as your default compiler use the
following commands:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="pygments highlight"><code data-lang="shell">port select --list gcc #Will list the versions of gcc available on your system
sudo port select --set gcc mp-gcc6 #set the one you wish to have as default call upon using the gcc command</code></pre>
</div>
</div>
<div class="paragraph">
<p>If you prefer to use Homebrew over Macports, it can be downloaded and
installed <a href="https://brew.sh/">here</a>.</p>
</div>
<div class="paragraph">
<p>Then install GCC using the following command:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="pygments highlight"><code data-lang="shell">brew install gcc</code></pre>
</div>
</div>
<div class="paragraph">
<p><strong>Note: if you decide to use Homebrew you should apparently refrain
yourself from assigning the newly installed gcc to the <code>gcc</code> command(see
<a href="http://docs.brew.sh/Custom-GCC-and-cross-compilers.html">this page</a> for
more details). You will thus have to pass the correct compiler
instructions to the configure script with the <em>CC</em> and <em>CXX</em> flags.</strong></p>
</div>
<div class="paragraph">
<p>Alternatively you could also install GCC directly from sources as described by this <a href="https://solarianprogrammer.com/2017/05/21/compiling-gcc-macos/">guide</a>.</p>
</div>
<div class="paragraph">
<p>Once done, simply follow instructions from the <a href="#linux">Linux installation section</a> to complete IGoR&#8217;s installation.</p>
</div>
</div>
<div class="sect2">
<h3 id="windows-not-tested">Windows (not tested)</h3>
<div class="paragraph">
<p>The configure script relies on bash to work. A first step would be to
download a bash interpreter (such as Cygwin or MinGW) and a compiler.
Open the command line of the one of your choice and use
<code>./configure;make</code></p>
</div>
</div>
<div class="sect2">
<h3 id="troubleshoots">Troubleshoots</h3>
<div class="paragraph">
<p>Here is a list of some install troubleshoots that have been reported and
their corresponding solution</p>
</div>
<table class="tableblock frame-all grid-all" style="width: 99%;">
<colgroup>
<col style="width: 20%;">
<col style="width: 40%;">
<col style="width: 40%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Issue</th>
<th class="tableblock halign-left valign-top">Reason</th>
<th class="tableblock halign-left valign-top">Solution</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">In file included from Aligner.cpp:8: /n ./Aligner.h:19:10: fatal error:
'omp.h' file not found /n #include &lt;omp.h&gt;</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The compiler used is not
supporting OpenMP</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Make sure you have an OpenMP compatible compiler
installed (such as GCC). If such a compiler is installed make sure the
right compiler is called upon compiling. In order to specify a specific
compiler to use (such as mc-gcc6 for macport installed gcc under MacOS)
pass the following option upon executing the configure script:
`./configure CC=mc-gcc6 CXX=mc-g6`. The _CC_ option will specify the C
compiler to use to compile jemalloc and gsl, while _CXX_ specifies the
C compiler to use to compile IGoR sources.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><em>aclocal-1.15: command not found</em>; <em>WARNING: 'aclocal-1.15' is missing
on your system.</em>; _make: _** [aclocal.m4] Error 127*</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The <em>configure</em>
script relies on file timestamps to assess whether it is up to date.
These time stamps might be compromised when extracting files from the
archive.</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Run the following command in IGoR root directory:
<code>touch configure.ac aclocal.m4 configure Makefile.* <strong>/Makefile.</strong> <strong>/</strong>/Makefile.*</code></p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><em>.libs/sasum.o: No such file or directory</em> error at compile time</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Unknown</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Running <code>make clean;make</code> will fix this issue</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><em>undefined reference to symbol 'clock_gettime@@GLIBC_2.2.5'</em> at link
time</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Jemalloc used an extra library to extract system time</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Run the
last command printed to the screen (<em>g -std=gnu11
-I./../libs/jemalloc/include/jemalloc -I./../libs/gsl_sub -fopenmp
&#8230;&#8203;&#8230;&#8203; -lpthread -ldl -fopenmp</em>) and add -lrt after -ldl. This will be
automated and fixed soon</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><em>src/jemalloc.c:241:1: error: initializer element is not constant</em> ;
<em>static malloc_mutex_t init_lock = MALLOC_MUTEX_INITIALIZER;</em></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Might be
related to MacOS Sierra?</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Unknown</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Undefined symbols for architecture x86_64:
"comp_nt_int(int const&amp;, int const&amp;)", referenced from:
Deletion::iterate(double&amp;, Enum_fast_memory_map&lt;Seq_type, double&gt;&amp;,&#8230;&#8203;</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Unknown
 issue with GCC8, cf <a href="https://github.com/qmarcou/IGoR/issues/22">issue #22</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Downgrade your GCC version to a 7.X version.</p></td>
</tr>
</tbody>
</table>
</div>
</div>
</div>
<div class="sect1">
<h2 id="workflow">Workflow</h2>
<div class="sectionbody">
<div class="paragraph">
<p>As a preprocessing step IGoR first needs to align the genomic templates
to the read (<code>-align</code>, see detailed commands in the <a href="#alignments">Alignments commands section</a>) before exploring all putative recombination
scenarios for this read. After aligning IGoR can be used to infer a
recombination model (<code>-infer</code>, see the <a href="#inference-and-evaluation">Inference/Evaluation section</a>), evaluate sequences statistics
(<code>-evaluate</code>) using an already inferred model. Synthetic sequences can
be generated from a learned model (as one supplied by IGoR, or one
inferred de novo through the <code>-infer</code> command) with the <code>-generate</code> (see the <a href="#sequence-generation-commands">Sequence generation section</a>)
command.</p>
</div>
<div class="sect2">
<h3 id="using-predefined-genomic-templates-and-models">Predefined genomic templates and models</h3>
<div class="paragraph">
<p>IGoR is shipped with a set of genomic templates and already inferred
models from [<a href="https://www.nature.com/articles/s41467-018-02832-w">1</a>].</p>
</div>
<div class="paragraph">
<p><strong>In order to use the predefined models and demo IGoR must have been
installed on your system.</strong></p>
</div>
<div class="paragraph">
<p>Available options are listed below:</p>
</div>
<table class="tableblock frame-all grid-all spread">
<colgroup>
<col style="width: 50%;">
<col style="width: 50%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Species</th>
<th class="tableblock halign-left valign-top">Chains</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">human</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">TRA (or alpha), TRB (or beta), heavy, IGL (or lambda), IGK (or kappa)</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">mouse</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">TRB (or beta)</p></td>
</tr>
</tbody>
</table>
<div class="paragraph">
<p>If you are working on datasets not present in this list refer to the
<a href="#advanced-usage">Advanced Usage section</a> and/or <a href="#contact">contact</a> us for assistance. Help us
filling this database for other users and share the resulting models
with us!</p>
</div>
</div>
<div class="sect2">
<h3 id="models-validity">Validity of the recombination and error models</h3>
<div class="paragraph">
<p>Some text discussing the validity of error and recombination models</p>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="runtimes">Runtimes</h2>
<div class="sectionbody">
<div class="paragraph">
<p>As runtimes may evolve with IGoR&#8217;s maturation, below is a table
recapitulating the latest per sequence runtimes for different tasks on
different chains:</p>
</div>
<table class="tableblock frame-all grid-all" style="width: 99%;">
<colgroup>
<col style="width: 20%;">
<col style="width: 40%;">
<col style="width: 40%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Chain/Read</th>
<th class="tableblock halign-left valign-top">(Pre)Alignments time (seconds)</th>
<th class="tableblock halign-left valign-top">Probabilistic treatment
time (seconds)</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">TRA 100bp</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">0.3</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">10<sup>-4</sup></p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">TRB 60bp</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">0.1</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">0.1</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">IGH 130bp</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">0.2</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">0.2</p></td>
</tr>
</tbody>
</table>
</div>
</div>
<div class="sect1">
<h2 id="command-line-tools">Command line tools</h2>
<div class="sectionbody">
<div class="paragraph">
<p>Although the full flexibility of IGoR is reachable through C[]+ highlevel
functions (see the &lt;&lt;c,C+ section&gt;&gt;) we provide some command line options to
perform most frequent tasks on immune receptor sequences.</p>
</div>
<div class="paragraph">
<p>Command options are nested arguments, the general organization of the
commands follows <code>-arg1 --subarg1 ---subsubarg1</code> to reach the different
levels.</p>
</div>
<div class="sect2">
<h3 id="general">General</h3>
<div class="sect3">
<h4 id="general-commands-summary">General commands summary</h4>
<table class="tableblock frame-all grid-all" style="width: 99%;">
<colgroup>
<col style="width: 32%;">
<col style="width: 68%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Command line argument</th>
<th class="tableblock halign-left valign-top">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>-h</code> or <code>-help</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Displays IGoR&#8217;s manual. Alternatively one could use
<code>man igor</code>.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>-v</code> or <code>-version</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Displays IGoR&#8217;s installed version number.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>-set_wd /path/to/dir/</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Sets the working directory to <em>/path/to/dir/</em>,
default is <em>/tmp</em>. <strong> This should be an already existing directory and
will not be created by IGoR </strong></p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>-threads N</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Sets the number of OpenMP threads to <em>N</em> for alignments
and inference/evaluation. By default IGoR will use the maximum number of
threads.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>-stdout_f /path/to/file</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Redirects the standard output to the file
<em>/path/to/file</em></p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>-read_seqs /path/to/file</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Reads the input sequences file
<em>/path/to/file</em> and reformat it in the working directory. <strong>This step is
necessary for running any action on sequences using the command line</strong>.
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 <em>align</em> folder.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>-batch batchname</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Sets the batch name. This name will be used as a
prefix to alignment/indexed sequences files, output, infer, evaluate and
generate folders.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>-chain chainname</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Selects a model and a set of genomic template
according to the value. Possible values for <code>chainname</code> are: <code>alpha</code>,
<code>beta</code>, <code>light</code>, <code>heavy_naive</code>, and <code>heavy_memory</code>. <strong>This needs to be
set in order to use provided genomic templates/model</strong></p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>-species speciesname</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Selects a species from the set of predefined
species. Possible values are: <code>human</code>.<strong>This needs to be set in order to
use provided genomic templates/model</strong></p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>-set_genomic --<strong>gene</strong> /path/to/file.fasta</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Set a set of custom
genomic templates for gene <em>gene</em> (possible values are --V,--D and --J)
with a list of genomic templates contained in the file
<em>/path/to/file.fasta</em> 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. <strong>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.</strong></p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>-set_CDR3_anchors --<strong>gene</strong></code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Load a semicolon separated file containing the indices/offset of
the CDR3 anchors for the <em>gene</em>(--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.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>-set_custom_model /path/to/model_parms.txt /path/to/model_marginals.txt</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Use a custom model as a baseline for inference or evaluation. <strong>Note
that this will override custom genomic templates for inference and
evaluation</strong>. Alternatively, providing only the model parameters file
will lead IGoR to create model marginals initialized to a uniform
distribution.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>-load_last_inferred</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Using this command will load the last inferred
model (folder <em>inference/final_xx.txt</em>) as a basis for a new inference,
evaluation or generation of synthetic sequences</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>-run_demo</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Runs the demo code on 300 sequences of 60bp TCRs (mostly a
sanity run check)</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>-run_custom</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Runs the code inside the custom section of the main.cpp
file</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>-subsample N</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Perform actions on a random subsample of <em>N</em> sequences.
<strong>This flag will have different effects depending on the supplied
commands:</strong> if the <code>-read_seqs</code> command is used, the resulting indexed
sequence file will be a subsample of sequences contained in the original
file. Else, if the <code>-align</code> command is used the alignments will be
performed on a subsample of the indexed sequences. Else, if the
<code>-evaluate</code> or <code>-infer</code> command is used the inference will be run on a
subsample of the indexed sequences. <em>Obviously N should be &lt; to the
total number of sequences available. The <code>-subsample</code> flag should be
used in only one command of a pipeline, see the Command example section
for details.</em></p></td>
</tr>
</tbody>
</table>
</div>
<div class="sect3">
<h4 id="scripts">Bash scripts</h4>
<div class="paragraph">
<p>A set of bash scripts for common tasks using igor.
We can use igor-compute_pgen to calculate the Pgen of
a specific sequence.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="pygments highlight"><code data-lang="shell">igor-compute_pgen &lt;specie&gt; &lt;chain&gt; &lt;ntsequence&gt;</code></pre>
</div>
</div>
<div class="paragraph">
<p>Example</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="pygments highlight"><code data-lang="shell">igor-compute_pgen human beta actcagctttgtatttctgtgccagcagcgtagattgggacagggggcctcctacgagcagtacgtcgggccg</code></pre>
</div>
</div>
</div>
<div class="sect3">
<h4 id="working-directory">Working directory</h4>
<div class="paragraph">
<p>This is where all IGoR outputs will appear. Specific folders will be
created for alignments, inference, evaluation and outputs.</p>
</div>
</div>
</div>
<div class="sect2">
<h3 id="alignments">Alignments</h3>
<div class="sect3">
<h4 id="algorithm">Algorithm</h4>
<div class="paragraph">
<p>Performs Smith-Waterman alignments of the genomic templates. Using a
slight alteration of the Smith-Waterman score matrix, we enforce that V
can only be deleted on the 3' side and J on the 5' side (thus enforcing
the alignment on the other side until the end of the read or of the
genomic template). D is aligned using a classical Smith-Waterman local
alignment approach allowing gene deletions on both sides.</p>
</div>
<div class="admonitionblock warning">
<table>
<tr>
<td class="icon">
<i class="fa icon-warning" title="Warning"></i>
</td>
<td class="content">
Alignments represent a critical step for a precise probabilistic
characterization of your sequences. Make sure you use all the information you
have on your sequences (e.g use the knowledge of your primers positions to
provide template specific alignment offsets) for optimal result.
</td>
</tr>
</table>
</div>
</div>
<div class="sect3">
<h4 id="alignment-commands-summary">Alignment commands summary</h4>
<div class="paragraph">
<p>Alignment of the sequences is performed upon detection of the <code>-align</code>
switch in the command line. For each gene, alignment parameters can be
set using <code>--V</code>,<code>--D</code> or <code>--J</code>. <strong>Specifying any of those three argument
will cause to align only the specified genes</strong>. In order to specify a set
of parameters for all genes or force to align all genes the argument
<code>--all</code> should be passed.</p>
</div>
<div class="paragraph">
<p>The complementarity-determining region (CDR3) of the aligned sequences is
by default written on a file &lt;batchname&gt;_indexed_CDR3.csv in the aligns
directory when <code>--all</code> is used. In case of separated alignments the CDR3 file
can be generated by using the <code>--feature ---ntCDR3</code> option.</p>
</div>
<div class="paragraph">
<p>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 <code>--ntCDR3</code> alignments will
be performed using gene anchors information as offset bounds.</p>
</div>
<table class="tableblock frame-all grid-all" style="width: 99%;">
<colgroup>
<col style="width: 32%;">
<col style="width: 68%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Command line argument</th>
<th class="tableblock halign-left valign-top">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>---thresh X</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Sets the score threshold for the considered gene
alignments to <em>X</em>. Default is 50.0 for V, 15.0 for D and 15.0 for J</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>---matrix path/to/file</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Sets the substitution matrix to the one given
in the file. Must be <em>','</em> delimited. Default is a NUC44 matrix with
stronger penalty on errors (5,-14)</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>---gap_penalty X</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Sets the alignment gap penalty to X. Default is
50.0</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>---best_align_only</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">If <em>true</em> only keep the best alignment for each gene/allele.
If <em>false</em> outputs all alignments above the score threshold. Default is
<em>true</em> for V and J, and <em>false</em> for D.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>---best_gene_only</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">If <em>true</em> only keep alignments for best scoring gene candidate
 (or candidates if several genes have the same maximum score).
If <em>false</em> outputs alignments for every aligned gene/allele. Default is
<em>false</em> for V, D and J.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>---offset_bounds M N</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">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 <code>--ntCDR3</code> command has been given
provided offset bounds values will be used for genes with missing CDR3 anchors positions.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>---template_spec_offset_bounds path/to/file</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Constrains the possible positions of the
alignments differently for each genomic template. The file should be a semi colon separated
file formated as follows: <code>gene_name;min_offset;max_offset</code>.
If entries are missing for some genes, values given with the <code>---offset_bounds</code> command
will be used. If the <code>--ntCDR3</code> 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.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>---reversed_offsets</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">If <em>true</em> 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 &#8656;0 by construction.</p></td>
</tr>
</tbody>
</table>
</div>
<div class="sect3">
<h4 id="alignment-output-files-summary">Alignment output files summary</h4>
<div class="paragraph">
<p>Upon alignment the alignment parameters/dates/filenames will appended to
the <em>aligns/aligns_info.out</em> file for easy traceability.</p>
</div>
<div class="paragraph">
<p>Alignment files are semicolon separated files. For each alignment of a
genomic template to a sequence the following fields are given:</p>
</div>
<table class="tableblock frame-all grid-all" style="width: 99%;">
<colgroup>
<col style="width: 32%;">
<col style="width: 68%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Field</th>
<th class="tableblock halign-left valign-top">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">seq_index</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The sequence index the alignment corresponds to in the
<em>indexed_sequences.csv</em> file.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">gene_name</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The gene name as provided in the genomic template file</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">score</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">SW alignment score</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">offset</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The index of the first letter of the (undeleted) genomic
template on the read as described in the previous section. Indices are 0 based.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">insertions</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Indices of the alignment inserted nucleotides (relative to
the read)</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">deletions</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Indices of the alignment deleted nucleotides (relative to
the genomic template)</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">mismatches</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Indices of the alignment mismatches (relative to the read)</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">length</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Length of the SW alignment (including insertions and deletions)</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">5_p_align_offset</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Offset of the first nucleotide of the SW alignment
(relative to the read)</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">3_p_align_offset</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Offset of the last nucleotide of the SW alignemnt
(relative to the read)</p></td>
</tr>
</tbody>
</table>
<div class="paragraph">
<p>The CDR3 files are semicolon separated files. For each IGoR indexed
sequence the following fields are given:</p>
</div>
<table class="tableblock frame-all grid-all" style="width: 99%;">
<colgroup>
<col style="width: 32%;">
<col style="width: 68%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Field</th>
<th class="tableblock halign-left valign-top">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">seq_index</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The sequence index the alignment corresponds to in the
<em>indexed_sequences.csv</em> file.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">v_anchor</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Position of the V anchor (first nucleotide of 2nd-CYS codon) relative to the read sequence.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">j_anchor</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Position of the J anchor (last nucleotide of J-PHE or J-TRP codon) relative to the read sequence.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">CDR3nt</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Nucleotide CDR3 sequence of the indexed sequence.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">CDR3aa</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Amino acids CDR3 sequence of the indexed sequence.
</p><p class="tableblock">Anchors position are 0 based indices relative to the read sequence.</p></td>
</tr>
</tbody>
</table>
</div>
</div>
<div class="sect2">
<h3 id="inference-and-evaluation">Inference and evaluation</h3>
<div class="sect3">
<h4 id="inference-and-evaluation-commands">Inference and evaluation commands</h4>
<div class="paragraph">
<p>The inference is reached using the command <code>-infer</code>. Logs and models
parameters values for each iteration will be created in the folder
<em>inference</em> of the working directory (or <em>batchname_inference</em> if a
batchname was supplied).</p>
</div>
<div class="paragraph">
<p>Sequence evaluation is reached using the command <code>-evaluate</code>. This is
the same as performing an iteration of the Expectation-Maximization on
the whole dataset and thus accepts the same arguments as <code>-infer</code> for
arguments related to the precision of the algorithm. The logs of the
sequences evaluation are created in the folder <em>evaluate</em> (or
<em>batchname_evaluate</em> if a batchname was supplied).</p>
</div>
<div class="ulist">
<ul>
<li>
<p>Note that -infer and -evaluate are mutually exclusive in the same
command since it brings ambiguity reagarding which model should be used
for each **</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>Optional parameters are the following:</p>
</div>
<table class="tableblock frame-all grid-all" style="width: 99%;">
<colgroup>
<col style="width: 26%;">
<col style="width: 53%;">
<col style="width: 21%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Command line argument</th>
<th class="tableblock halign-left valign-top">Description</th>
<th class="tableblock halign-left valign-top">Available for</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>--N_iter N</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Sets the number of EM iterations for the inference to N</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">inference</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>--L_thresh X</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Sets the sequence likelihood threshold to X.</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">inference
&amp; evaluation</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>--P_ratio_thresh X</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">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&#8217;t change when
decreasing it further.</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">inference &amp; evaluation</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>--MLSO</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">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)</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">inference &amp; evaluation</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>--infer_only eventnickname1 eventnickname2</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">During the inference only
the parameters of the events with nicknames listed will be updated. <strong>
Note that not passing any event nickname will fix all events. </strong></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">inference</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>--not_infer eventnickname1 eventnickname2</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Opposite command to the
one above, will fix the parameters of the listed events</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">inference</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>--fix_err</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">In the same vein as the two commands above, this one will
fix the parameters related to the error rate.</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">inference</p></td>
</tr>
</tbody>
</table>
</div>
<div class="sect3">
<h4 id="inference-and-evaluation-output">Inference and evaluation output</h4>
<div class="paragraph">
<p>Upon inferring or evaluating several files will be created in the
corresponding folder.</p>
</div>
<div class="sect4">
<h5 id="model-parameters-files">Model parameters files</h5>
<div class="paragraph">
<p><strong>*_parms.txt</strong> files contain information to create Model_Parms C++
objects. It encapsulates information on the individual model events,
their possible realizations, the model&#8217;s graph structure encoding events
conditional dependences and the error model information. All fields are
semi colon separated. The different sections of the files are delimited
by an <code>@</code> symbol, each further subdivided as follows:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>@Event_list</code> introduces the section in which the recombination events
(i.e the Bayesian Network/graph nodes) are defined.</p>
<div class="ulist">
<ul>
<li>
<p><code>#</code> introduces a new recombination event (or node). The line contains
4 fields:</p>
<div class="ulist">
<ul>
<li>
<p>the event type (<em>GeneChoice</em>, <em>Deletion</em>, <em>Insertion</em>,
<em>DinucMarkov</em>)</p>
</li>
<li>
<p>the targeted genes (<em>V_gene</em>, <em>VD_genes</em>, <em>D_gene</em>, <em>DJ_genes</em>,
<em>J_gene</em>, <em>VJ_genes</em>)</p>
</li>
<li>
<p>the gene side (<em>Five_prime</em>, <em>Three_prime</em>, <em>Undefined_side</em>)</p>
</li>
<li>
<p>the event priority: an integer influencing the order in which events
are processed during the inference such that events with high priority
are preferentially processed earlier.</p>
</li>
<li>
<p>the event nickname</p>
</li>
</ul>
</div>
</li>
<li>
<p><code>%</code> introduces a new event realization. Depending on the
recombination event, the first fields will define the realization name
and/or values (e.g gene name and gene sequence for <em>GeneChoice</em> or
number of deletions for <em>Deletion</em>) while the final field always denotes
the realization&#8217;s index on the probability array. <strong>This index is
automatically assigned by IGoR upon addition of an event realization,
changing it will cause undefined behavior.</strong> See the <em>Advanced usage</em>
section of this README for more information on how to add/remove event
realizations.</p>
</li>
</ul>
</div>
</li>
<li>
<p><code>@Edges</code> introduces the section in which the conditional dependencies
(i.e graph directed edges) are defined.</p>
<div class="ulist">
<ul>
<li>
<p><code>%parent;child</code> introduces a new directed edge/conditional dependence
between the parent and child event.</p>
</li>
</ul>
</div>
</li>
<li>
<p><code>@ErrorRate</code> introduces the section in which the error model is
defined.</p>
<div class="ulist">
<ul>
<li>
<p><code>#</code> introduces a new error model, the first field defining the error
model type and subsequent fields other meta parameters of the error
model</p>
<div class="ulist">
<ul>
<li>
<p><code>%</code> introduces the parameters values linked to the actual
error/mutation rate.</p>
</li>
</ul>
</div>
</li>
</ul>
</div>
</li>
</ul>
</div>
</div>
<div class="sect4">
<h5 id="model-marginals-files">Model marginals files</h5>
<div class="paragraph">
<p><strong>*_marginals.txt</strong> files contain information to create Model_Marginals
C++ objects. It encapsulates the probabilities for each recombination
event&#8217;s realization. As for the model parameters files, the marginals
files are are sectioned by special characters as follows:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>@</code> introduces the recombination event&#8217;s nickname the following
probabilities are referring to.</p>
</li>
<li>
<p><code>$Dim</code> introduces the dimensions of the event and its conditional
dimensions probability array. By convention the last dimension refers to
the considered event dimension.</p>
</li>
<li>
<p><code>#</code> introduces the indices of the realizations of the parent events
and their nickname corresponding to the following 1D probability array</p>
</li>
<li>
<p><code>%</code> introduces the 1D probability array for all of the considered
event realizations for fixed realizations of the parents events whose
indices were given in the previous line.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>Python functions are provided to read such files along with the
corresponding model parameters file within the GenModel object.</p>
</div>
</div>
<div class="sect4">
<h5 id="inference-information-file">Inference information file</h5>
<div class="paragraph">
<p><em>inference_info.out</em> contains the inference parameters/date/time for
traceability and potential error messages.</p>
</div>
</div>
<div class="sect4">
<h5 id="inference-logs-file">Inference logs file</h5>
<div class="paragraph">
<p><em>inference_logs.txt</em> contains some information on each sequence for each
iteration. This is a useful tool to debug inference troubleshoots.</p>
</div>
</div>
<div class="sect4">
<h5 id="model-likelihood-file">Model likelihood file</h5>
<div class="paragraph">
<p><em>likelihoods.out</em> contains the likelihood information for a given
dataset.</p>
</div>
</div>
</div>
<div class="sect3">
<h4 id="inference-and-evaluation-troubleshoots">Inference and evaluation Troubleshoots</h4>
<div class="paragraph">
<p>Although the inference/evaluation generally run smoothly we try to list
out some possible troubleshoots and corresponding solutions.</p>
</div>
<table class="tableblock frame-all grid-all" style="width: 99%;">
<colgroup>
<col style="width: 32%;">
<col style="width: 68%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Issue</th>
<th class="tableblock halign-left valign-top">Putative solution</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">map_base::at() exception</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">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.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">All 0 output</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">All marginal files contains 0 parameters after one
iteration. All sequences have zero likelihood in the
<em>inference_logs.txt</em> file. Explanation: none of the scenarios had a
sufficiently high likelihood to reach the likelihood threshold.
Solution: use the <code>--L_thresh</code> argument to decrease the likelihood
threshold, if the code becomes utterly slow see below. <strong> 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 </strong></p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Extreme slowness</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Runtimes are very far from the ones given in the
<a href="#runtimes">Runtimes section</a>. Check the mean number of errors in the <em>inference_logs.txt</em>
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</p></td>
</tr>
</tbody>
</table>
</div>
</div>
<div class="sect2">
<h3 id="outputs">Outputs</h3>
<div class="paragraph">
<p>Outputs or Counters in the C++ interface are scenario/sequence
statistics, each individually presented below. They are all written in
the <em>output</em> folder (or <em>batchname_output</em> if a batchname was supplied).</p>
</div>
<div class="paragraph">
<p>In order to specify outputs use the <code>-output</code> argument, and detail the
desired list of outputs. Outputs are tied to the exploration of
scenarios and thus require to have <code>-infer</code> or <code>-evaluate</code> 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.</p>
</div>
<div class="paragraph">
<p>The different outputs are detailed in the next sections.</p>
</div>
<div class="paragraph">
<p>Python utility functions are provided to analyze these outputs in the
<code>pygor.counters</code> submodule.</p>
</div>
<div class="sect3">
<h4 id="best-scenarios">Best scenarios</h4>
<div class="paragraph">
<p><em>Output the N best scenarios for each sequence</em></p>
</div>
<div class="paragraph">
<p>Use command <code>--scenarios N</code></p>
</div>
<div class="paragraph">
<p>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 <code>pygor.counters.bestscenarios</code> submodule.</p>
</div>
</div>
<div class="sect3">
<h4 id="generation-probability">Generation probability</h4>
<div class="paragraph">
<p><em>Estimates the probability of generation of the error free/unmutated
ancestor sequence</em> By default only outputs an estimator of the
probability of generation of the ancestor sequence underlying each
sequencing read. See
<a href="https://www.nature.com/articles/s41467-018-02832-w">IGoR&#8217;s paper</a> for
details.</p>
</div>
<div class="paragraph">
<p>Use command <code>--Pgen</code></p>
</div>
</div>
<div class="sect3">
<h4 id="coverage">Coverage</h4>
<div class="paragraph">
<p><em>Counts for each genomic nucleotide how many times it has been seen and
how many times it was mutated/erroneous</em></p>
</div>
<div class="paragraph">
<p>Use command <code>--coverage</code></p>
</div>
</div>
</div>
<div class="sect2">
<h3 id="sequence-generation">Sequence generation</h3>
<div class="paragraph">
<p>Using a recombination model and its associated probabilities IGoR can
generate random sequences mimicking the raw product of the V(D)J
recombination process.</p>
</div>
<div class="sect3">
<h4 id="sequence-generation-commands">Sequence generation commands</h4>
<div class="paragraph">
<p>Reached using the command <code>-generate N</code> where <em>N</em> 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:</p>
</div>
<table class="tableblock frame-all grid-all" style="width: 99%;">
<colgroup>
<col style="width: 32%;">
<col style="width: 68%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Command line argument</th>
<th class="tableblock halign-left valign-top">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>--noerr</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Generate sequences without sequencing error (the rate and
the way those errors are generated is controlled by the model error
rate)</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"> <code>--CDR3</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">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 <code>-set_CDR3_anchors</code> to set them.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>--name myname</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Prefix for the generated sequences filenames. <strong>Note
that setting the <em>batchname</em> will change the generated sequences folder
name, while setting <em>--name</em> will change the file names.</strong></p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>--seed X</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Impose <em>X</em> as a seed for the random sequence generator. By
default a random seed is obtained from the system.</p></td>
</tr>
</tbody>
</table>
</div>
</div>
<div class="sect2">
<h3 id="command-examples">Command examples</h3>
<div class="paragraph">
<p>First as a sanity after installation check try and run the demo code
(this will run for a few minutes on all cores available):</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="pygments highlight"><code data-lang="shell">igor -run_demo</code></pre>
</div>
</div>
<div class="paragraph">
<p>Here we give an example with a few commands illustrating a typical
workflow. In this example we assume to be executing IGoR from the
directory containing the executable.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="pygments highlight"><code data-lang="shell">WDPATH=/path/to/your/working/directory #Let's define a shorthand for the working directory

#We first read the sequences contained in a text file inside the demo folder
#This will create the align folder in the working directory and the mydemo_indexed_seqs.csv file.
igor -set_wd $WDPATH -batch foo -read_seqs ../demo/murugan_naive1_noncoding_demo_seqs.txt

#Now let's align the sequences against the provided human beta chain genomic templates with default parameters
#This will create foo_V_alignments.csv, foo_D_alignments.csv and foo_J_alignments.csv files inside the align folder.
igor -set_wd $WDPATH -batch foo -species human -chain beta -align --all

#Now use the provided beta chain model to get the 10 best scenarios per sequence
#This will create the foo_output and foo_evaluate and the corresponding files inside
igor -set_wd $WDPATH -batch foo -species human -chain beta -evaluate -output --scenarios 10

#Now generate 100 synthetic sequences from the provided human beta chain model
#This will create the directory bar_generate with the corresponding files containing the generated sequences and their realizations
igor -set_wd $WDPATH -batch bar -species human -chain beta -generate 100</code></pre>
</div>
</div>
<div class="paragraph">
<p>Since all these commands use several time the same arguments here is
some syntactic sugar using more Bash syntax for the exact same workflow
with a lighter syntax:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="pygments highlight"><code data-lang="shell">WDPATH=/path/to/your/working/directory #Let's define a shorthand for the working directory
MYCOMMANDS=./igor -set_wd $WDPATH

$MYCOMMANDS -batch foo -read_seqs ../demo/murugan_naive1_noncoding_demo_seqs.txt #Read seqs
MYCOMMANDS=$MYCOMMANDS -species human -chain beta #Add chain and species commands
$MYCOMMANDS -batch foo -align --all #Align
$MYCOMMANDS -batch foo -evaluate -output --scenarios 10 #Evaluate
$MYCOMMANDS -batch bar -generate 100 #Generate</code></pre>
</div>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="advanced-usage">Advanced usage</h2>
<div class="sectionbody">
<div class="paragraph">
<p>The set of command lines above allows to use predefined models or their
topology to study a new dataset. Additionally the user can define new
models directly using the model parameters file interface. For instance,
in order to investigate a conditional dependence between two
recombination events, the user can simply add or remove an edge in the
graph following the syntax defined earlier.</p>
</div>
<div class="paragraph">
<p>In order to change the set of realizations associated with an event the
user can also directly modify a recombination parameters file. Adding or
removing realizations should be done with great care as IGoR will use
the associated indices to read the corresponding probabilities on the
probability array. These indices should be contiguous ranging from 0 to
the (total number of realizations -1).</p>
</div>
<div class="paragraph">
<p><em>Any change in these indices or to the graph structure will make the
corresponding model marginals file void, and a new one should be
automatically created by passing only the model parameters filename to
the <code>-set_custom_model</code> command.</em></p>
</div>
<div class="paragraph">
<p>Note that changing the GeneChoice realizations can be done automatically
(without manually editing the recombination parameter file) by supplying
the desired set of genomic templates to IGoR using the <code>-set_genomic</code>
command. This could be used e.g to define a model for a chain in a
species for which IGoR does not supply a model starting from of model
for this chain from another species.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="c">C++</h2>
<div class="sectionbody">
<div class="paragraph">
<p>Although a few command line options are supplied for basic use of IGoR,
its full modularity can be used through high level C++ functions on
which all previous command lines are built. A section of the <em>main.cpp</em>
file is dedicated to accept user supplied code and can be executed using
the <code>-run_custom</code> command line argument when launching IGoR from the
shell. An example of the high level workflow is given in the <em>run demo</em>
section and the full Doxygen generated documentation is available as
PDF. For any question please contact us.</p>
</div>
<div class="paragraph">
<p>Good practice would be to append the C++ code in the dedicated area of the
 <em>main.cpp</em> file:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="pygments highlight"><code data-lang="cpp">else{
	//Write your custom procedure here
       <i class="conum" data-value="1"></i><b>(1)</b>
}</code></pre>
</div>
</div>
<div class="colist arabic">
<table>
<tr>
<td><i class="conum" data-value="1"></i><b>1</b></td>
<td>Insert you custom code here.</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>This part of the code is reachable using the <code>-run_custom</code> command line argument.
This design aims at keeping the command line interface fully functional while
still appending some custom code.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="python">Python</h2>
<div class="sectionbody">
<div class="paragraph">
<p>A set of Python codes are shipped with Igor in order to parse IGoR&#8217;s
outputs (alignments,models etc) as the <strong>pygor</strong> module.
This module can be installed locally with pip using the included
<code>setup.py</code> file (use command <code>pip install ./pygor</code> from within the IGoR directory).</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="contribute">Contribute</h2>
<div class="sectionbody">
<div class="ulist">
<ul>
<li>
<p>Your feedbacks are valuable, please send your comments about
usability, bug reports and new features you would like to see</p>
</li>
<li>
<p>Code contribution: IGoR was designed to be modular and evolve, please
get in touch if you would like to do something new with your data and
would like some more guidance on the code structure</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>If you would like to share some improvements on IGoR&#8217;s code please file a pull
request according to this logic:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>If you&#8217;d like to propose a change in the documentation of existing functions
to provide clearer insights please file your pull request on the <code>master</code> branch.</p>
</li>
<li>
<p>If you&#8217;d like to propose a bug fix for a function already present in a release
file your pull request on the <code>master</code> branch.</p>
</li>
<li>
<p>If you&#8217;d like to propose a new functionality and its associated documentation
please file your pull request on the <code>dev</code> branch.</p>
</li>
</ul>
</div>
</div>
</div>
<div class="sect1">
<h2 id="contact">Contact</h2>
<div class="sectionbody">
<div class="paragraph">
<p>For any question or issue please open an
<a href="https://github.com/qmarcou/IGoR/issues">issue</a> or email <a href="mailto:quentin.marcou@lpt.ens.fr">us</a>.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_copying">Copying</h2>
<div class="sectionbody">
<div class="paragraph">
<p>Free use of IGoR is granted under the terms of the <a href="https://www.gnu.org/licenses/quick-guide-gplv3.html">GNU General Public License version 3</a>
(GPLv3).</p>
</div>
</div>
</div>
</div>
<div id="footer">
<div id="footer-text">
Last updated 2019-09-19 12:05:53 CEST
</div>
</div>
</body>
</html>