Metadata-Version: 2.1
Name: mitoviz
Version: 0.6.2
Summary: Plot variants on the human mitochondrial genome.
Home-page: https://github.com/robertopreste/mitoviz
Author: Roberto Preste
Author-email: robertopreste@gmail.com
License: MIT license
Keywords: mitoviz
Platform: UNKNOWN
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Description-Content-Type: text/x-rst
Requires-Dist: Click (>=7.0)
Requires-Dist: numpy
Requires-Dist: pandas
Requires-Dist: matplotlib
Requires-Dist: pysam
Requires-Dist: vcfpy

=======
mitoviz
=======


.. image:: https://img.shields.io/pypi/v/mitoviz.svg
        :target: https://pypi.python.org/pypi/mitoviz

.. image:: https://www.repostatus.org/badges/latest/wip.svg
    :alt: Project Status: WIP – Initial development is in progress, but there has not yet been a stable, usable release suitable for the public.
    :target: https://www.repostatus.org/#wip

.. image:: https://travis-ci.com/robertopreste/mitoviz.svg?branch=master
        :target: https://travis-ci.com/robertopreste/mitoviz

.. image:: https://codecov.io/gh/robertopreste/mitoviz/branch/master/graph/badge.svg
    :target: https://codecov.io/gh/robertopreste/mitoviz

.. image:: https://readthedocs.org/projects/mitoviz/badge/?version=latest
        :target: https://mitoviz.readthedocs.io/en/latest/?badge=latest
        :alt: Documentation Status


Plot variants on the human mitochondrial genome.


* Free software: MIT license
* Documentation: https://mitoviz.readthedocs.io
* GitHub repo: https://github.com/robertopreste/mitoviz


Features
========

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 importing
mitoviz in 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 in between, according to their actual HF value.

.. image:: https://github.com/robertopreste/mitoviz/raw/master/mitoviz/tests/images/sample_hf.png
  :alt: Mitochondrial plot with HF

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

A linear representation of the mitochondrial genome can also be plotted; in this case,
variants are shown using a *lollipop plot* style, with the height of the marker reflecting
their HF.

.. image:: https://github.com/robertopreste/mitoviz/raw/master/mitoviz/tests/images/sample_linear_hf.png
  :alt: Mitochondrial linear plot with HF

Variants with no HF information will be shown as if their HF was 0.5.

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:

.. code-block:: console

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

.. code-block:: console

    $ mitoviz sample.vcf --output my_mt_plot.png

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

.. code-block:: console

    $ mitoviz sample.vcf --linear

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:

.. code-block:: console

    $ mitoviz sample.tsv --sep "\t"

Python Module
-------------

Import mitoviz and use its ``plot_vcf`` function to use it in your own script:

.. code-block:: python

    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:

.. code-block:: python

    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:

.. code-block:: python

    plot_vcf("sample.vcf", save=True, linear=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:

.. code-block:: python

    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:

.. code-block:: python

    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:

.. code-block:: python

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

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

Installation
============

**PLEASE NOTE: HmtNote only supports Python >= 3.6!**

The preferred installation method for mitoviz is using ``pip``:

.. code-block:: console

    $ pip install mitoviz

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

Credits
=======

This package was created with Cookiecutter_ and the `cc-pypackage`_ project template.

.. _Cookiecutter: https://github.com/audreyr/cookiecutter
.. _`cc-pypackage`: https://github.com/robertopreste/cc-pypackage
.. _Usage: https://mitoviz.readthedocs.io/en/latest/usage.html
.. _Installation: https://mitoviz.readthedocs.io/en/latest/installation.html


=======
History
=======

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.

0.6.0 (2020-02-29)
==================

* ``_PolarVariant`` is deprecated and replaced by ``_Variant``;
* Add ``linear`` option to create linear 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.


