Usage¶
mitoviz can be used both from the command line and as a python module.
Command Line¶
Given a VCF file with human mitochondrial variants (sample.vcf
), plotting them is fairly
simple:
$ mitoviz sample.vcf
An image named mitoviz.png
will be created in the current directory.
If you want to provide a specific filename where the plot will be saved, just add the --output
option with the desired path:
$ mitoviz sample.vcf --output my_mt_plot.png
If the provided VCF file contains more than one sample, a separate plot will be created for each
of them; if you want to plot only a specific sample, use the --sample
option:
$ mitoviz multisample.vcf --sample SRR1777294
It is possible to show labels above each variant using the --labels
flag:
$ mitoviz sample.vcf --labels
If you want to include the HF value of variants in the labels, add the --labels-hf
flag:
$ mitoviz sample.vcf --labels --labels-hf
Mitochondrial loci on mitoviz plots are drawn using a green color for protein-coding, blue for
tRNAs, red for rRNAs, orange for regulatory (D-Loop and L-strand origin) and grey for non-coding
loci. It is possible to include a legend in the
resulting plot, using the --legend
option:
$ mitoviz sample.vcf --legend
The plot can draw loci located on H and L strands on two different levels, using the --split
option:
$ mitoviz sample.vcf --split
mitoviz can create linear plots as well, where variants are shown using a lollipop plot style,
using the --linear
option:
$ mitoviz sample.vcf --linear
Linear plots can be managed and customised using the --output
, --sample
, --labels
,
--legend
and --split
options.
Polar and linear interactive plots can also be created by adding the --interactive
option, and
will be saved to an HTML file:
$ mitoviz sample.vcf --interactive
It is also possible to plot variants stored in a tabular file, such as CSV or TSV formats; mitoviz
will automatically recognise them, treating the file as comma-separated by default. If a different
separator is used (as in the case of TSV files), just specify it with the --sep
option:
$ mitoviz sample.tsv --sep "\t"
Additional keyword options can be specified in the format option=value
, and will be passed to
pandas.read_table
when processing the given input file:
$ mitoviz sample.tsv --sep "\t" comment=#
If you just need to create an empty mitochondrial plot, we’ve got you covered: use the
mitoviz-base
command and provide one or more options like --linear
, --interactive
,
--legend
, --split
, --output
, based on your needs:
# Create a base polar plot
$ mitoviz-base
# Create a base linear plot and save it as "base_linear.png"
$ mitoviz-base --linear --output "base_linear.png"
# Create an interactive linear plot with split loci
$ mitoviz-base --linear --interactive --split
Comprehensive help about the mitoviz CLI can be found with mitoviz --help
and
mitoviz-base --help
.
Python Module¶
Import mitoviz and use its plot_vcf
function to use it in your own script:
from mitoviz import plot_vcf
my_plot = plot_vcf("sample.vcf")
In this case, no plot will be shown until a call to plt.show()
is made. It is possible to
save the resulting plot using the save
option and to provide a specific file where the plot will be
saved using the output
option:
from mitoviz import plot_vcf
plot_vcf("sample.vcf", save=True, output="my_mt_plot.png")
If the provided VCF file contains more than one sample, a separate plot will be created for each
of them; if you want to plot only a specific sample, use the sample
option:
from mitoviz import plot_vcf
plot_vcf("multisample.vcf", save=True, sample="SRR1777294")
If you want to show labels for each variant plotted, add the labels=True
option:
from mitoviz import plot_vcf
plot_vcf("sample.vcf", labels=True)
If you also want HF values in the labels, add the labels_hf=True
option:
from mitoviz import plot_vcf
plot_vcf("sample.vcf", labels=True, labels_hf=True)
It is possible to include a legend for loci colors in the output plot, using the legend=True
option:
from mitoviz import plot_vcf
plot_vcf("sample.vcf", legend=True)
Loci located on the H and L strands can be shown on two separate levels, using the split=True
option:
from mitoviz import plot_vcf
plot_vcf("sample.vcf", split=True)
Linear plots can be also created (instead of the default polar plot), using the linear=True
option:
from mitoviz import plot_vcf
plot_vcf("sample.vcf", linear=True)
The linear=True
option can be combined with previously described options as well.
Interactive plots can be created with the interactive
option, and can be either saved to an
HTML file or inspected in a Jupyter notebook:
# Show the interactive plot (works in a Jupyter notebook)
plot_vcf("sample.vcf", interactive=True)
# Save the interactive plot to an HTML file
plot_vcf("sample.vcf", interactive=True, save=True)
Comprehensive help about the plot_vcf
function can be found with help(mitoviz.plot_vcf)
.
A similar function to plot variants contained in a pandas DataFrame is available as plot_df
.
Supposing you have a pandas DataFrame with human mitochondrial variants named variants_df
, it
is possible to plot them as follows:
from mitoviz import plot_df
plot_df(variants_df)
This function expects a DataFrame with at least a reference allele, position and alternate allele columns; these are respectively called “REF”, “POS” and “ALT” by default, but it is possible to use custom column names:
from mitoviz import plot_df
plot_df(variants_df, ref_col="position", ref_col="reference", alt_col="alternate")
It is possible to provide optional sample and hf (heteroplasmic fraction) columns, which are called
“SAMPLE” and “HF” by default but can be customised using the sample_col
and hf_col
options.
Apart from this, plot_df
accepts the same set of options available for plot_vcf
.
Comprehensive help about the plot_df
function can be found with help(mitoviz.plot_df)
.
Variants stored in tabular files can be plotted using plot_table
, which accepts the same
options available for plot_vcf
and plot_df
, with the addition of sep
, which is used to
specify the column separator. By default, the comma is used as column delimiter:
from mitoviz import plot_table
# plotting a CSV file
plot_table("sample.csv")
# plotting a TSV (tab-separated) file
plot_table("sample.tsv", sep="\t")
plot_table
also accept additional keyword options, which will be passed to pandas.read_table
when processing the given input file:
from mitoviz import plot_table
plot_table("sample.tsv", sep="\t", comment="#", skiprows=0)
Comprehensive help about the plot_table
function can be found with help(mitoviz.plot_table)
.
If you just need to create an empty mitochondrial plot, the plot_base
function allows to do so,
and accepts the linear
, interactive
, legend
, split
, output
and save
arguments to further tweak its behaviour:
from mitoviz import plot_base
# Create a base polar plot
plot_base()
# Create a base linear plot and save it as "base_linear.png"
plot_base(linear=True, save=True, output="base_linear.png)
# Create an interactive linear plot with split loci
plot_base(linear=True, interactive=True, split=True)