Skip to main content

Plot variants on the human mitochondrial genome.

Project description

mitoviz Project Status: WIP – Initial development is in progress, but there has not yet been a stable, usable release suitable for the public. Documentation Status Python 3

Plot variants on the human mitochondrial genome.


mitoviz is a simple python package to plot human mitochondrial variants on a graphical representation of the human mitochondrial genome. It currently supports plotting variants stored in VCF and tabular files, as well as from general pandas dataframes when using mitoviz from inside Python.

Variants are shown according to their heteroplasmic fraction (HF), plotting variants with HF = 1.0 on the outer border of the mitochondrial circle, those with HF = 0.0 on the inner border and all the others according to their actual HF value.

Mitochondrial plot with HF

If the HF information is not available, variants will all be shown in the middle of the mitochondrial circle.


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 only plot a specific sample, use the --sample option:

$ mitoviz multisample.vcf --sample SRR1777294

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"

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 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")

If the provided VCF file contains more than one sample, a separate plot will be created for each of them; if you want to only plot a specific sample, use the sample option:

plot_vcf("multisample.vcf", save=True, sample="SRR1777294")

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


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
# 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)

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


PLEASE NOTE: HmtNote only supports Python >= 3.6!

The preferred installation method for mitoviz is using pip:

$ pip install mitoviz

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


This package was created with Cookiecutter and the cc-pypackage project template.


0.1.0 (2019-12-27)

  • First release.

0.2.0 (2019-12-29)

  • Add functionality to plot multiple samples.

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.3.0 (2020-01-15)

  • Add plot_df function to plot variants from a pandas DataFrame.

0.4.0 (2020-01-26)

  • Add plot_table function to plot variants from tabular files;
  • add CLI functionality to plot variants from tabular files;
  • refactor code.

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.5.0 (2020-02-19)

  • Add split option to plot split strands on polar plots.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for mitoviz, version 0.5.0
Filename, size File type Python version Upload date Hashes
Filename, size mitoviz-0.5.0-py2.py3-none-any.whl (17.0 kB) File type Wheel Python version py2.py3 Upload date Hashes View hashes
Filename, size mitoviz-0.5.0.tar.gz (919.7 kB) File type Source Python version None Upload date Hashes View hashes

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page