`mixcr exportPlots`

A set of routines for graphical export of postanalysis results. MiXCR supports graphical export in PDF, SVG, EPS, PNG and JPEG formats.

Diversity and CDR3 metrics

mixcr exportPlots (diversity|cdr3metrics) [--metadata <path>] [--filter <meta(|>|>=|=|<=|<)value>[,<meta(|>|>=|=|<=|<)value>...]]... [--chains <chain>]... [--metric <metric>[,<metric>...]]... [--plot-type <plotType>] [--primary-group <meta>] [--primary-group-values <value>[,<value>...]]... [--secondary-group <meta>] [--secondary-group-values <value>[,<value>...]]... [--facet-by <meta>] [--hide-overall-p-value] [--pairwise-comparisons] [--ref-group <refGroup>] [--hide-non-significant] [--paired] [--method <method>] [--method-multiple-groups <method>] [--p-adjust-method <method>] [--show-significance] [--width <n>] [--height <n>] [--no-warnings] [--verbose] [--help] pa.json[.gz] output.(pdf|eps|svg|png|jpeg) Exports diversity or CDR3 metrics visualization plots from the individual postanalysis results. When exporting in PDF format the resulting file will contain multiple pages: one page per metric. For exaporint in other formats one need to specify --metrics <metric> option to export one particular metric.

Basic command line options are:

pa.json[.gz]

Input file with postanalysis results.

output.(pdf|eps|svg|png|jpeg)

Output PDF/EPS/PNG/JPEG file name.

--metadata <path>

Metadata file in a tab- (.tsv) or comma- (.csv) separated form. Must contain sample column which matches names of input files.

--filter <filter>[,<filter>...]

Filter samples to put on a plot by their metadata values. Filter allows equality (species=cat) or arithmetic comparison (age>=10) etc.

--chains <chain>

Export only for specified immunological chains.

--metric <metric>[,<metric>...]

Output only specified list of metrics:

for cdr3metrics possible values are: cdr3lenAA, cdr3lenNT, ndnLenNT, addedNNT, strength, hydrophobicity, surface, volume, charge
for diversity possible values are: observed, shannonWiener, chao1, normalizedShannonWienerIndex, inverseSimpsonIndex, giniIndex, d50, efronThisted

--plot-type <plotType>

Plot type. Possible values: boxplot, boxplot-bindot, boxplot-jitter, violin, violin-bindot, barplot, barplot-stacked, lineplot, lineplot-jitter, lineplot-bindot, scatter

-p, --primary-group <meta>

Specify metadata column used to group datasets.

-pv, --primary-group-values <value>[,<value>...]

List of comma separated primary group values.

-s, --secondary-group <meta>

Secondary group.

-sv, --secondary-group-values <value>[,<value>...]

List of comma separated secondary group values.

--facet-by <meta>

Facet by.

--hide-overall-p-value

Hide overall p-value.

--pairwise-comparisons

Show pairwise p-value comparisons.

--ref-group <refGroup>

Reference group for compare means statistics. Can be 'all' or some specific value.

--hide-non-significant

Hide non-significant observations.

--paired

Do paired analysis

--method <method>

Statistical test method. Available methods: Wilcoxon (default), ANOVA, TTest, KruskalWallis, KolmogorovSmirnov

--method-multiple-groups <method>

Test method for multiple groups comparison. Available methods: KruskalWallis (default), Wilcoxon, ANOVA, TTest, KolmogorovSmirnov

--p-adjust-method <method>

Method used to adjust p-values. Available methods: Available methods: Holm (default), BenjaminiHochberg, BenjaminiYekutieli, Bonferroni, Hochberg, Hommel, none

--show-significance

Show significance levels instead of p-values ( ns for p-value >= 0.05, *** for p-value < 0.0001, ** for p-value < 0.001, * in other case).

--width <n>

Plot width.

--height <n>

Plot height.

-nw, --no-warnings

Suppress all warning messages.

--verbose

Verbose messages.

-h, --help

Show this help message and exit.

Examples

Use primary grouping and facets:

```shell

mixcr exportPlots diversity -f \ --plot-type lineplot-bindot \ --primary-group Time \ --primary-group-values T0,M1,M2 \ --facet-by Marker \ pa/i.json.gz \ plots/diversity_facets.pdf ```

Use secondary grouping:

```shell

mixcr exportPlots diversity -f \ --primary-group Marker \ --secondary-group Time \ --secondary-group-values T0,M1,M2 \ pa/i.json.gz \ plots/pdf ```

[TODO more examples]

Gene segment usage

mixcr exportPlots (vUsage|jUsage|isotypeUsage|vjUsage) [-f] [--metadata <path>] [--filter <meta(|>|>=|=|<=|<)value>[,<meta(|>|>=|=|<=|<)value>...]]... [--chains <chain>]... [--family-usage] [--no-samples-dendro] [--no-genes-dendro] [--color-key <key>]... [--bar-plot] [--facet-by <s>] [--palette <s>] [--h-labels-size <d>] [--v-labels-size <d>] [--width <n>] [--height <n>] [--no-warnings] [--verbose] [--help] pa.json[.gz] output.(pdf|eps|svg|png|jpeg) Exports gene segment usage heatmap plots from the individual postanalysis results.

pa.json[.gz]: Input file with postanalysis results.
output.(pdf|eps|svg|png|jpeg): Output PDF/EPS/PNG/JPEG file name.
--metadata <path>: Metadata file in a tab- (.tsv) or comma- (.csv) separated form. Must contain sample column which matches names of input files.
--filter <meta(|>|>=|=|<=|<)value>[,<meta(|>|>=|=|<=|<)value>...]: Filter samples to put on a plot by their metadata values. Filter allows equality (species=cat) or arithmetic comparison (age>=10) etc.
--chains <chain>: Export only for specified immunological chains.
--family-usage: Show gene family usage instead.
--no-samples-dendro: Don't add samples dendrogram on heatmap.
--bar-plot: export bar plot instead of heatmap (groups samples by genes)
--bar-plot-by-sample: export bar plot instead of heatmap (groups genes by sample)
--family-usage: show gene family usage instead
--no-genes-dendro: Don't add genes dendrogram on heatmap.
--color-key <key>: Add color key layer to heatmap.
--bar-plot: Export bar plot instead of heatmap.
--facet-by <s>: Facet bar-plot.
--palette <s>: Color palette for heatmap. Available names: diverging, viridis2magma, lime2rose, blue2red, teal2red, softSpectral, sequential, viridis, magma, sunset, rainbow, salinity, density. Default: density
--h-labels-size <d>: Width of horizontal labels. One unit corresponds to the width of one tile.
--v-labels-size <d>: Height of vertical labels. One unit corresponds to the height of one tile.
--width <n>: Plot width.
--height <n>: Plot height.
-nw, --no-warnings: Suppress all warning messages.
--verbose: Verbose messages.
-h, --help: Show this help message and exit.

Examples

Export Variable gene segment usage plot and add color key: shell mixcr exportPlots vUsage -f \ --color-key Patient \ pa/i.json.gz \ plots/vUsage.svg vUsage.TRAD.svg

Export Joining gene segment usage plot and specify another palette: shell mixcr exportPlots jUsage -f \ --palette magma \ --color-key Marker \ pa/i.json.gz \ plots/jUsage.svg

vUsage.TRB.svg

Export Variable gene segment families usage plot as a bar-plot by samples :

```shell mixcr exportPlots vUsage -f --bar-plot-by-sample \ --family-usage \ pa/individual.json.gz \ plots/vUsage.svg

```

vUsage.IGH.svg

Export Variable gene segment families usage plot as a bar-plot by genes :

```shell mixcr exportPlots vUsage -f --bar-plot \ --family-usage \ pa/individual.json.gz \ plots/vUsage.svg

```

vUsage.IGH.svg

Overlap

mixcr exportPlots overlap [--metadata <path>] [--filter <meta(|>|>=|=|<=|<)value>[,<meta(|>|>=|=|<=|<)value>...]]... [--chains <chain>]... [--no-dendro] [--color-key <meta>]... [--fill-diagonal] [--metric <metric>]... [--palette <s>] [--h-labels-size <d>] [--v-labels-size <d>] [--width <n>] [--height <n>] [--no-warnings] [--verbose] [--help] pa.json[.gz] output.(pdf|eps|svg|png|jpeg) Exports pairwise distance metrics heatmap plots from the overlap postanalysis results.

pa.json[.gz]: Input file with postanalysis results.
output.(pdf|eps|svg|png|jpeg): Output PDF/EPS/PNG/JPEG file name.
--metadata <path>: Metadata file in a tab- (.tsv) or comma- (.csv) separated form. Must contain sample column which matches names of input files.
--filter <meta(|>|>=|=|<=|<)value>[,<meta(|>|>=|=|<=|<)value>...]: Filter samples to put on a plot by their metadata values. Filter allows equality (species=cat) or arithmetic comparison (age>=10) etc.
--chains <chain>: Export only for specified immunological chains.
--no-dendro: Don't add dendrograms
--color-key <meta>: Add color key layer to the heatmap. One may write --color-key x_meta to draw color key horizontally (default) or --color-key y_meta to draw vertically.
--fill-diagonal: Fill diagonal line
--metric <metric>: Select specific metrics to export. Possible values are: SharedClonotypes, RelativeDiversity, F1Index, F2Index, JaccardIndex, Pearson, PearsonAll
--palette <s>: Color palette for heatmap. Available names: diverging, viridis2magma, lime2rose, blue2red, teal2red, softSpectral, sequential, viridis, magma, sunset, rainbow, salinity, density. Default: density
--h-labels-size <d>: Width of horizontal labels. One unit corresponds to the width of one tile.
--v-labels-size <d>: Height of vertical labels. One unit corresponds to the height of one tile.
--width <n>: Plot width.
--height <n>: Plot height.
-nw, --no-warnings: Suppress all warning messages.
--verbose: Verbose messages.
-h, --help: Show this help message and exit.

Examples

Export overlap with color key:

```

mixcr exportPlots overlap \ --metric pearsonAll \ --color-key Patient \ pa/o.json.gz \ plots/overlap.pdf ```

SHM trees

mixcr exportPlots shmTrees [--metadata <path.(tsv|csv)>] [--node-color <meta>] [--line-color <meta>] [--node-size <meta>] [--node-label <meta>] [--alignment-nt <gene_feature>] [--alignment-aa <gene_feature>] [--alignment-no-fill] [--filter-min-nodes <n>] [--filter-min-height <n>] [--ids <id>[,<id>...]]... [--chains <chains>] [--force-overwrite] [--no-warnings] [--verbose] [--help] [[--filter-in-feature <gene_feature>] [--pattern-max-errors <n>] (--filter-aa-pattern <pattern> | --filter-nt-pattern <pattern>)] trees.shmt plots.pdf Visualize SHM tree and save in PDF format

trees.shmt: Input file produced by 'findShmTrees' command.
plots.pdf: Path where to write PDF file with plots.
-m, --metadata <path.(tsv|csv)>: Path to metadata file Metadata should be a .tsv or .csv file with a column named 'sample' with filenames of .clns files used in findShmTrees
--node-color <meta>: Color nodes with given metadata column
--line-color <meta>: Color lines with given metadata column
--node-size <meta>: Size nodes with given metadata column. Predefined columns: "Abundance". Default: Abundance
--node-label <meta>: Label nodes with given metadata column. Predefined columns: "Isotype"
--alignment-nt <gene_feature>: Show tree nucleotide alignments using specified gene feature
--alignment-aa <gene_feature>: Show tree amino acid alignments using specified gene feature
--alignment-no-fill: Do not highlight alignments with color
--filter-min-nodes <n>: Minimal number of nodes in tree
--filter-min-height <n>: Minimal height of the tree
--ids <id>[,<id>...]: Filter specific trees by id
--chains <chains>: Export only trees that contains clones with specific chain (e.g. TRA or IGH).
-f, --force-overwrite: Force overwrite of output file(s).
-nw, --no-warnings: Suppress all warning messages.
--verbose: Verbose messages.
-h, --help: Show this help message and exit.

Filter by pattern options:

--filter-in-feature <gene_feature>: Match pattern inside specified gene feature. Default: CDR3
--pattern-max-errors <n>: Max allowed subs & indels. Default: 0
--filter-aa-pattern <pattern>: Filter specific trees by aa pattern.
--filter-nt-pattern <pattern>: Filter specific trees by nt pattern.