.. highlight:: shell

===============
Getting Started
===============

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

We highly recommend creating a Python `virtualenv`_ for your model testing
purposes.

.. _virtualenv: http://docs.python-guide.org/en/latest/dev/virtualenvs/

Stable release
--------------

To install memote, run this command in your terminal:

.. code-block:: console

    $ pip install memote

This is the preferred method to install memote, as it will always install the most recent stable release.

If you don't have `pip`_ installed, this `Python installation guide`_ can guide
you through the process.

.. _pip: https://pip.pypa.io/en/stable/
.. _Python installation guide: http://docs.python-guide.org/en/latest/starting/installation/

From sources
------------

The sources for memote can be downloaded from the `Github repo`_.

You can either clone the public repository:

.. code-block:: console

    $ git clone https://github.com/opencobra/memote.git

Or download the `tarball
<https://github.com/opencobra/memote/archive/master.tar.gz>`_ or
`zip <https://github.com/opencobra/memote/archive/master.zip>`_ archive:

.. code-block:: console

    $ curl  -OL https://github.com/opencobra/memote/archive/master.zip

Once you have a copy of the source files, you can install it with:

.. code-block:: console

    $ pip install .


.. _Github repo: https://github.com/opencobra/memote


After installation, memote can be employed in two different ways: As a
benchmarking tool for ad hoc model assessment and as an automated testing
suite to aid
with the reconstruction of metabolic models. When using memote to benchmark a
model, the tests are run once and a report is generated which describes the
status-quo.
As an automated testing suite, memote facilitates tracking incremental model
changes in a version controlled repository and can enable continuous testing and
reporting if desired.

Here, we explain step-by-step the necessary commands to pursue either workflow.
Users that have already followed this tutorial once may want to refer to the
:doc:`cheat-sheet flowchart <flowchart>` to refresh their memory.

Benchmark
=========

Single Model
------------

To benchmark the performance of a single model, run this command in your
terminal:

.. code-block:: console

    $ memote --model path/to/model.xml report --one-time

This will generate the performance report as ``index.html``.

The output filename can be changed by adding the following option.
To illustrate here it is changed to ``report.html``.

.. code-block:: console

    $ memote --model path/to/model.xml --filename "report.html" report --one-time

Comparative
-----------

**This functionality is coming soon.**

Comparing two models against each other and quickly identify the differences.

Reconstruction
==============

When starting a memote repository, users need to provide an SBMLv3-FBC formatted
file. Automatic draft reconstruction tools such as `Pathway Tools`_,
`Model SEED`_, `The RAVEN Toolbox`_ and `others`_ are able to output files in
this format. Model repositories such as `BiGG`_ or `BioModels`_ further serve
as a great resource for models in the correct format.

.. _Pathway Tools: http://bioinformatics.ai.sri.com/ptools/
.. _Model SEED: http://modelseed.org
.. _The RAVEN Toolbox: https://github.com/SysBioChalmers/RAVEN
.. _others: http://www.secondarymetabolites.org/sysbio/
.. _BiGG: http://bigg.ucsd.edu
.. _BioModels: https://www.ebi.ac.uk/biomodels-main/

With this in mind, starting a local, version-controlled model repository is as
simple as running the following command:

.. code-block:: console

    $ memote new

CI tested, online and public workflow:
--------------------------------------

After this, the user will be prompted with a few questions regarding details of
the project. If the project is to be kept strictly locally, the user does
not need to supply `GitHub`_ (or `GitLab`_ - not implemented yet) credentials.
However, these are a requirement if the project is to use the full benefits of
distributed version control such as cloud-based development, remote
collaboration and community feedback. It is important to note that furthermore
a public repository is needed to set up automatic testing through continuous
integration, one of the key features of memote.

Once all the questions following ``memote new`` have been answered, a public
repository has been created under either the user's GitHub or GitLab account.
To enable continuous integration via Travis CI the following command is
executed:

**This functionality is coming soon.** A manual workaround is outlined in the
`cookiecutter-memote readme <https://github.com/opencobra/cookiecutter-memote/blob/master/%7B%7Bcookiecutter.project_slug%7D%7D/README.md>`_.

.. code-block:: console

    $ memote online

Now, after each edit to the model in the repository, the user can generate
an update to the continuous model report shown at the project's gh-pages
branch by saving the changes with the following command:

**This functionality is coming soon, for now please utilize the steps outlined for advanced users.**

.. code-block:: console

    $ memote save

For advanced users: ``memote save`` is the equivalent of executing ``git add .``,
``git commit`` and ``git push`` in sequence.

Offline, local or private workflow:
-----------------------------------

Users that have decided to not to use `GitHub`_ (or `GitLab`_ **Not implemented yet**) or those that
have decided to set the model repository to private, will need to execute:

.. code-block:: console

    $ memote

to run the testing suite on their commit history followed by:

.. code-block:: console

    $ memote report

to generate the same type of report that would be shown automatically with
continuous integration. After this it is crucial to save the generated test
results by running ``memote save`` again.

We recommend the public workflow not only to promote open, collaborative
science but also to benefit from the full functionality of memote.

.. _GitHub: https://github.com
.. _GitLab: https://gitlab.com
