Installation instructions¶
MetaWards is a Python package, but it does come with R wrappers. This means that you can choose to install MetaWards either via Python or via R.
Installation via Python¶
MetaWards is compiled and tested on Windows, Linux and OS X, but should be able to compile and install on any operating system with a working Python >= 3.7 and a C compiler.
To install MetaWards, you first need to install Python >= 3.7. To check if you have Python 3.7 installed type;
python -V
This should print out the version number of the Python you have available.
If the version number is 2.??? then you have a very old Python 2. If
this is the case, try;
python3 -V
and see if you have a Python 3 that has a version number >= 3.7. If so,
please use python3 instead of python.
If you don’t have Python >=3.7 installed, then you can install Python either via your package manager, or more simply, by using anaconda.
Once you have a working Python >= 3.7, the easiest way to install MetaWards is using pip.
pip install metawards
(if this doesn’t work, then you may need to use the command pip3,
or you may have to install pip.
If you have trouble installing pip then we recommend that you download
and install anaconda, which has pip included)
To install a specific version, e.g. 1.4.0, type
pip install metawards==1.4.0
This will install a binary version of metawards if it is avaiable for your
operating system / processor / version of python. If not, then
the metawards pyx code that was compiled into C using
cython,
will be compiled into an executable using your system C compiler
(e.g. gcc or clang).
You can control which C compiler to use by setting the CC environment
variable, e.g.
CC=gcc pip install metawards
MetaWards is written in standard C, using OpenMP for parallelisation, and it has no external dependencies, so it should compile without issue. Note that the system C compiler on OS X (Mac) does not support OpenMP. In this case you the code will compile with OpenMP disabled. If you want to use all of the cores of your computer than you will need to install a different compiler, e.g. installing clang via homebrew. If you have any problems then please post an issue on GitHub.
Installation via R¶
MetaWards can be used within R via the reticulate package. We have built a MetaWards R package that simplifies this use.
First, open R or RStudio and install the MetaWards R package from GitHub;
> library(devtools)
> install_github("metawards/rpkg")
Next, load the metawards package and use the py_install_metawards
function to install metawards into the Python that is supplied
with reticulate.
> metawards::py_install_metawards()
This may take a few minutes. If it works, then you can check that
metawards is available by calling the py_metawards_available function,
e.g.
> metawards::py_metawards_available()
[1] TRUE
Note
If you want to use a different Python environment, then this can be
set using reticulate::use_python("/path/to/python", required = TRUE)
before you call any of the metawards functions.
This will install the latest version of metawards. You can check if there are any updates available via;
> metawards::py_metawards_update_available()
and you can update to the lastest version using;
> metawards::py_update_metawards()
Source install¶
You can download a source release of MetaWards from the project release page.
Once you have downloaded the file you can unpack it and change into that directory using;
tar -zxvf MetaWards-X.Y.Z.tar.gz
cd MetaWards-X.Y.Z
where X.Y.Z is the version you downloaded. For the 1.4.0 release
this would be;
tar -zxvf MetaWards-1.4.0.tar.gz
cd MetaWards-X.Y.Z
Next you need to install the dependencies of MetaWards. Do this by typing;
pip install -r requirements.txt
Now you are ready to compile and install MetaWards itself;
make
make install
You can choose the C compiler to use by setting the CC environment
variable, e.g.
CC=clang make
CC=clang make install
MetaWards is written in standard C, using OpenMP for parallelisation, and it has no external dependencies, so it should compile without issue. Note that the system C compiler on OS X (Mac) does not support OpenMP. In this case you the code will compile with OpenMP disabled. If you want to use all of the cores of your computer than you will need to install a different compiler, e.g. installing clang via homebrew. If you have any problems then please post an issue on GitHub.
For developers¶
You can clone the MetaWards repository to your computer and install from there;
git clone https://github.com/metawards/MetaWards
cd MetaWards
pip install -r requirements-dev.txt
From this point you can compile as if you have downloaded from source. As a developer you may want to run the tests and create the website. To do this type;
pytest tests
make doc
There are shortcuts for running the quick or slow tests, e.g.
make test
make quicktest
Note that the tests assume that you have already downloaded the model data from MetaWardsData and configured this as described here.