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

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

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

mixcr exportPlots vUsage -f \
    --color-key Patient \
    pa/i.json.gz \
    plots/vUsage.svg

Export Joining gene segment usage plot and specify another palette:

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 :

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 :

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.