.. 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 `_ or `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 ` 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 `_. .. 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