Getting Started

Installation

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

Stable release

To install memote, run this command in your terminal:

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

From sources

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

You can either clone the public repository:

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

Or download the tarball or zip archive:

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

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

$ pip install .

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 cheat-sheet flowchart to refresh their memory.

Benchmark

Single Model

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

$ memote report snapshot path/to/model.xml

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.

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

While the html report is still a work in progress, we recommend relying on the verbose output of the command line tool above. Users can tweak the console output by passing additional arguments directly to pytest through the --pytest-args or simply -a option. This can be done by writing the pytest arguments as one continuous string.

For a more detailed traceback try:

$ memote report snapshot -a "--tb long" --filename "report.html" path/to/model.xml

For a full list of possible arguments please refer to the pytest documentation.

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.

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

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

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

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

$ memote run

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

$ memote report history

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.