mitoviz 0.9.0

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

Linear plots can be created using the --linear option:

$ mitoviz sample.vcf --linear

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"

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.

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:

plot_vcf("sample.vcf", save=True, output="my_mt_plot.png")

By default, a polar plot is returned; linear plots are easily created using the linear option:

plot_vcf("sample.vcf", save=True, linear=True)

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)

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)

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:

plot_table("sample.tsv", sep="\t", comment="#", skiprows=0)

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.

Please refer to the Usage section of the documentation for further information.

0.2.1 (2020-01-06)

• Add legend to plots and update colors.

0.2.2 (2020-01-08)

• Add option to plot variant labels.

0.2.3 (2020-01-11)

• Make legend plotting optional.

0.4.1 (2020-02-13)

• Refactor to use abstract classes;

• Rename internal classes to _PolarLocus and _PolarVariant.

0.4.2 (2020-02-14)

• Fix bug with non coding loci not being shown in plots.

0.6.1 (2020-03-02)

• Refactor and clean code;

• Add CI module for internal management.

0.6.2 (2020-03-03)

• Fix borders on linear plots.

0.6.3 (2020-03-04)

• Fix stemlines on split linear plots.

0.6.4 (2020-03-10)

• Fix loci label positions on polar plots.

0.7.1 (2020-03-28)

• Implement interactive basic linear plots;

• Implement interactive split linear plots.

0.8.1 (2020-04-12)

• Move test images to separate subrepo.

0.8.2 (2020-04-20)

• Add --labels-hf (labels-hf=True in Python) options to include the HF value in plot labels.