RAVEN (MATLAB)#

The RAVEN Toolbox runs in MATLAB and works independently. It does not require the COBRA Toolbox and can interoperate with it.

Requirements#

MATLAB. No minimum release is stated, and the code has no check that rejects an older release. readYAMLmodel has a fallback for releases before R2020b, parseTaskList calls readcell (R2019a) for Excel task lists, and addIdentifierPrefix calls regexpPattern (R2020b). Continuous integration tests R2024b, and older releases are not tested. No additional MathWorks toolboxes are required.
A linear-programming solver: Gurobi (free academic licence, recommended) or GLPK, which is bundled with RAVEN and needs no separate installation. See Choosing and configuring a solver.
RAVEN bundles libSBML and the GLPK mex files for Windows, macOS and Linux. BLAST+, DIAMOND and HMMER are not bundled. RAVEN fetches the build for the platform on first use, so the reconstruction functions need internet access the first time they run. downloadRavenBinaries fetches them in advance. Download data and binaries lists the full set, the cache location and the preparation of an offline machine.

Choosing and configuring a solver#

Solver	LP	MILP	Relative speed	Licence
GLPK	yes	yes (RAVEN warns; slow on large problems)	1x (baseline)	open source, bundled with RAVEN
SCIP	yes	yes	0.33x	open source; `setRavenSolver('scip')` downloads the MEX file on Windows (from the RAVEN v2.8.6 GitHub release), and macOS and Linux need a separate installation
Gurobi	yes	yes	4.2x	free academic licence
COBRA Toolbox	yes	depends on the COBRA solver configured	depends on the COBRA solver configured	depends on the COBRA solver configured

The functions that solve MILPs (getMinimalMedium, ftINIT and some gap-filling algorithms) also run on the bundled GLPK and give a warning that recommends Gurobi. On genome-scale models GLPK can be slower than Gurobi, which runs at 4.2 times the speed of GLPK in the table.

setRavenSolver sets the active solver and takes 'gurobi', 'glpk', 'scip' or 'cobra':

setRavenSolver('gurobi');

Gurobi#

Install Gurobi 7.5 or later.
Request and download a licence. A free academic licence covers most research use.
Place the licence file where the installer of Gurobi says.
Follow the MATLAB integration instructions of Gurobi, then run savepath to keep the change after a restart.
Run setRavenSolver('gurobi').

Solving through the COBRA Toolbox#

RAVEN can solve with the solver that the COBRA Toolbox has configured, in place of the bundled solvers:

changeCobraSolver('glpk');   % or any solver the COBRA Toolbox supports
setRavenSolver('cobra');

ravenCobraWrapper converts a model between the RAVEN struct and the COBRA Toolbox structure (COBRA Toolbox conversion).

Installation#

Installing 3.0.0b1

This site documents RAVEN 3.0.0b1, a pre-release. The Add-Ons manager and the normal releases page of the release download offer the latest stable release (RAVEN 2.x), so neither installs 3.0.0b1. The Clone with git tab or the archive link of the Release download tab installs it.

Add-Ons manager

The installation runs from within MATLAB and needs no separate download. The installed version is the latest stable release (RAVEN 2.x), which is older than 3.0.0b1, as the warning at the start of the Installation section states.

Open the Home tab and select Add-Ons, then Get Add-Ons.
Search for RAVEN Toolbox and select Add, then Add to MATLAB.
Verify the installation.

When MATLAB does not pick up the toolbox after step 2, matlab.addons.enableAddon("RAVEN") enables it.

Release download

This method suits offline and managed environments. The RAVEN releases page lists stable releases, and 3.0.0b1 is a git tag without a packaged release, so the archive is downloaded directly:

Download the 3.0.0b1 archive, which works without git.
Extract it to any location.
In MATLAB, add the RAVEN folder to the path (pathtool) and verify.

Clone with git

The commands clone the repository and check out the 3.0.0b1 tag. A plain git clone follows the develop branch, which can contain changes made after the pre-release documented on this site.

git clone --depth=1 https://github.com/CompMetEng/RAVEN.git
cd RAVEN
git fetch --depth=1 origin tag 3.0.0b1
git checkout 3.0.0b1

Afterwards, add the RAVEN folder to the MATLAB path and verify.

Verification#

In the MATLAB command window:

checkRaven

A successful run prints output of this form:

*** THE RAVEN TOOLBOX ***

 > Installation type                    Advanced (via git)
 > Checking RAVEN release               3.0.0
 > Checking MATLAB release              R2024b
 > Set RAVEN in MATLAB path             Pass
 > Save MATLAB path                     Pass

=== Model import and export ===
 > Checking libSBML version             5.20.0
 > Checking model import and export
   > Import SBML format                Pass
   > Export SBML format                Pass
   > Import YAML format                Pass
   > Export YAML format                Pass
   > Export Excel format               Pass

=== Model solvers ===
 > Checking for LP solvers
   > glpk                               Pass
   > gurobi                             Pass
 > Set RAVEN solver                     gurobi

=== Essential binary executables ===
 > Checking BLAST+                      Pass
 > Checking DIAMOND                     Pass
 > Checking HMMER                       Pass

=== Compatibility ===
 > Checking function uniqueness

*** checkRaven complete ***

MATLAB can report that it could not save the path, which is common on shared or managed installations without write access to the pathdef.m of MATLAB. addRavenToUserPath then writes a startup.m that adds RAVEN to the path on every MATLAB start and leaves the shared path file unchanged. addRavenToUserPath('overwrite', false) appends to an existing startup.m, which is replaced otherwise.

Upgrading#

Add-Ons manager

In MATLAB, open Help, then Check for Updates, select Update for RAVEN and run checkRaven again.

Release download

MATLAB should be closed, the old RAVEN folder deleted, the new release downloaded and extracted, and checkRaven run.

Clone with git

The 3.0.0b1 tag does not move, so a checkout of it has nothing to pull. The development branch is followed with:

git checkout develop
git pull origin develop

develop can contain unreleased changes. checkRaven should be run afterwards.

Removal#

Add-Ons manager

RAVEN is removed from the list under Add-Ons, then Manage Add-Ons. A following call of removeRavenFromPath should report an unrecognised-function error, which confirms that RAVEN is off the path.

Release download

which removeRavenFromPath   % locate the installation
removeRavenFromPath         % clear RAVEN from the MATLAB path

The RAVEN folder is then deleted from disk.

Clone with git

which removeRavenFromPath   % locate the installation
removeRavenFromPath         % clear RAVEN from the MATLAB path

The cloned RAVEN folder is then deleted from disk.

Getting help#

Installation problems are reported as an issue on GitHub.