Metadata-Version: 2.1
Name: mavis
Version: 2.2.3
Summary: A Structural Variant Post-Processing Package
Home-page: https://github.com/bcgsc/mavis.git
Author: Caralyn Reisle
Author-email: creisle@bcgsc.ca
License: UNKNOWN
Download-URL: https://github.com/bcgsc/mavis/archive/v2.2.3.tar.gz
Project-URL: mavis, http://mavis.bcgsc.ca
Platform: UNKNOWN
Requires-Python: >=3.2
Requires-Dist: Distance (>=0.1.3)
Requires-Dist: Shapely (>=1.6.4.post1)
Requires-Dist: biopython (>=1.70)
Requires-Dist: braceexpand (==0.1.2)
Requires-Dist: colour
Requires-Dist: networkx (==1.11.0)
Requires-Dist: numpy (>=1.13.1)
Requires-Dist: pysam (>=0.9)
Requires-Dist: pyvcf (==0.6.8)
Requires-Dist: shortuuid (>=0.5.0)
Requires-Dist: svgwrite
Provides-Extra: docs
Requires-Dist: docutils (>=0.14) ; extra == 'docs'
Requires-Dist: m2r (>=0.1.12) ; extra == 'docs'
Requires-Dist: sphinx-rtd-theme (>=0.4.2) ; extra == 'docs'
Requires-Dist: sphinx (>=1.8.1) ; extra == 'docs'
Provides-Extra: test
Requires-Dist: timeout-decorator (>=0.3.3) ; extra == 'test'
Requires-Dist: coverage (>=4.2) ; extra == 'test'
Requires-Dist: pycodestyle (>=2.3.1) ; extra == 'test'
Requires-Dist: pytest ; extra == 'test'
Requires-Dist: pytest-cov ; extra == 'test'

.. image:: http://mavis.bcgsc.ca/docs/latest/_static/acronym.svg

|



.. image:: https://img.shields.io/pypi/v/mavis.svg
   :target: https://img.shields.io/pypi/v/mavis.svg
   :alt: PyPi

.. image:: https://travis-ci.org/bcgsc/mavis.svg?branch=master
   :target: https://travis-ci.org/bcgsc/mavis.svg?branch=master
   :alt: Travis

.. image:: https://readthedocs.org/projects/pip/badge/
   :target: https://readthedocs.org/projects/pip/badge/
   :alt: ReadTheDocs


About
=====

`MAVIS <http://mavis.bcgsc.ca>`__ is python command-line tool for the post-processing of structural variant calls.
The general `MAVIS <http://mavis.bcgsc.ca>`__ pipeline consists of six main stages


* convert
* `cluster <http://mavis.bcgsc.ca/docs/latest/mavis.cluster.html#mavis-cluster>`_
* `validate <http://mavis.bcgsc.ca/docs/latest/mavis.validate.html#mavis-validate>`_
* `annotate <http://mavis.bcgsc.ca/docs/latest/mavis.annotate.html#mavis-annotate>`_
* `pairing <http://mavis.bcgsc.ca/docs/latest/mavis.pairing.html#mavis-pairing>`_
* `summary <http://mavis.bcgsc.ca/docs/latest/mavis.summary.html#mavis-summary>`_

Getting Help
------------

All steps in the MAVIS pipeline are called following the main mavis entry point. The usage menu can be viewed
by running without any arguments, or by giving the -h/--help option

.. code-block:: bash

   mavis -h

Help sub-menus can be found by giving the pipeline step followed by no arguments or the -h options

.. code-block:: bash

   mavis cluster -h

Common problems and questions are addressed on the `wiki <https://github.com/bcgsc/mavis/wiki/Help-and-Frequently-Asked-Questions>`_.
If you have a question or issue that is not answered there (or already a github issue) please submit
a github issue to our `github page <https://github.com/bcgsc/mavis/issues>`__ or contact us by email at `mavis@bcgsc.ca <mailto:mavis@bcgsc.ca>`_

Install Instructions
--------------------

There are 3 major steps to setting up and installing `MAVIS <http://mavis.bcgsc.ca>`_.

1. Install Aligner
^^^^^^^^^^^^^^^^^^

In addition to the python package dependencies, `MAVIS <http://mavis.bcgsc.ca>`__ also requires an aligner to be installed.
Currently the only aligners supported are `blat <http://mavis.bcgsc.ca/docs/latest/glossary.html#term-blat>`__ and `bwa mem <http://mavis.bcgsc.ca/docs/latest/glossary.html#term-bwa>`_.
For MAVIS to run successfully the aligner must be installed and accessible on the path.
If you have a non-standard install you may find it useful to edit the PATH environment variable. For example

.. code-block:: bash

   export PATH=/path/to/directory/containing/blat/binary:$PATH

`blat <http://mavis.bcgsc.ca/docs/latest/glossary.html#term-blat>`__ is the default aligner. To configure MAVIS to use `bwa mem <http://mavis.bcgsc.ca/docs/latest/glossary.html#term-bwa>`__ as a default instead, use the
`MAVIS environment variables <http://mavis.bcgsc.ca/configuration.html#environment-variables>`_. Make sure to specify BOTH of the variables below to change the default aligner.

.. code-block:: bash

   export MAVIS_ALIGNER='bwa mem'
   export MAVIS_ALIGNER_REFERENCE=/path/to/mem/fasta/ref/file

After this has been installed MAVIS itself can be installed through `pip <https://pypi.org/project/mavis/>`_

2. Install MAVIS
^^^^^^^^^^^^^^^^

Install using pip
~~~~~~~~~~~~~~~~~

The easiest way to install `MAVIS <http://mavis.bcgsc.ca>`__ is through the python package manager, pip. If you do not have python3 installed it can be found `here <https://www.python.org/downloads>`_

Ensuring you have a recent version of pip and setuptools will improve the install experience. Older versions of pip and setuptools may have issues with obtaining some of the mavis python dependencies

.. code-block:: bash

   pip install --upgrade pip setuptools

or (for Anaconda users)

.. code-block:: bash

   conda update pip setuptools

If this is not a clean/new python install it may be useful to set up mavis in a `virtual python environment <https://docs.python.org/3/tutorial/venv.html>`_

Then install mavis itself

.. code-block:: bash

   pip install mavis

This will install mavis and its python dependencies.

Install using Buildout
~~~~~~~~~~~~~~~~~~~~~~

Alternatively you can use the `bootstrap/buildout <http://www.buildout.org/en/latest/>`__ to install mavis into bin/mavis

.. code-block:: bash

   git clone https://github.com/bcgsc/mavis.git
   cd mavis
   pip install zc.buildout
   python bootstrap.py
   bin/buildout

This will install mavis and its python dependencies into eggs inside the cloned mavis directory which can be used by simply running bin/mavis

3. Build or Download Reference Files
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

After `MAVIS <http://mavis.bcgsc.ca>`__ is installed the `reference files <http://mavis.bcgsc.ca/docs/latest/mavis_input.html#reference-input-files>`__ must be generated (or downloaded) before it can be run. A simple bash script to download the hg19 reference files and generate a MAVIS environment file is provided under mavis/tools for convenience.

.. code-block:: bash

   cd /path/to/where/you/want/to/put/the/files
   wget https://raw.githubusercontent.com/bcgsc/mavis/master/tools/get_hg19_reference_files.sh
   bash get_hg19_reference_files.sh
   source reference_inputs/hg19_env.sh

Once the above 3 steps are complete `MAVIS <http://mavis.bcgsc.ca>`__ is ready to be run.
See the MAVIS `tutorial <http://mavis.bcgsc.ca/docs/latest/pipeline.html#mavis-mini-tutorial>`__ to learn about running MAVIS.

Build the Sphinx Documentation
------------------------------

.. code-block:: bash

   pip install .[docs]
   sphinx-build docs/source/ html

Deploy to PyPi
--------------

Install m2r to ensure the README is converted nicely

.. code-block:: bash

   pip install m2r

Install to build the egg

.. code-block:: bash

   python setup.py install

Build the other distribution files

.. code-block:: bash

   python setup.py sdist

Use twine to upload

.. code-block:: bash

   twine upload -r pypi dist/*

Citation
--------

If you use MAVIS as a part of your project please cite

`Reisle,C. et al. (2018) MAVIS: Merging, Annotation, Validation, and Illustration of Structural variants. Bioinformatics. <https://doi.org/10.1093/bioinformatics/bty621>`_


