Metadata-Version: 2.1
Name: mitoviz
Version: 0.8.1
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
Description: =======
        mitoviz
        =======
        
        
        .. image:: https://img.shields.io/pypi/v/mitoviz.svg
                :target: https://pypi.python.org/pypi/mitoviz
        
        .. image:: https://www.repostatus.org/badges/latest/active.svg
           :alt: Project Status: Active – The project has reached a stable, usable state and is being actively developed.
           :target: https://www.repostatus.org/#active
        
        .. 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
        
        Polar and linear interactive plots can also be created by adding the ``--interactive`` option, and
        will be saved to an HTML file:
        
        .. code-block:: console
        
            $ 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:
        
        .. code-block:: console
        
            $ 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:
        
        .. 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)
        
        Interactive plots can be created with the ``interactive`` option, and can be either saved to an
        HTML file or inspected in a Jupyter notebook:
        
        .. code-block:: python
        
            # 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:
        
        .. 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)
        
        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.
        
        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.
        
        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.0 (2020-03-15)
        ==================
        
        * Add ``--interactive`` option to create interactive plots using plot.ly;
        * Implement interactive basic polar plots;
        * Implement interactive split polar plots.
        
        0.7.1 (2020-03-28)
        ------------------
        
        * Implement interactive basic linear plots;
        * Implement interactive split linear plots.
        
        0.8.0 (2020-04-05)
        ==================
        
        * Add ``mitoviz-base`` command to create base mitochondrial plots.
        
        0.8.1 (2020-04-12)
        ------------------
        
        * Move test images to separate subrepo.
        
Keywords: mitoviz
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
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
