Installation by hand

Overview

This page describes how to install MARTi by hand, from the GitHub repository. If you would prefer a different installation method (e.g. bioconda), go back to Installation overview.

MARTi consists of two main components:

a back-end which performs the analysis and can be a single desktop/laptop or a high performance cluster.
a lightweight web-based front-end which allows users to view analysis results.

Make sure you’ve read the Introduction and know whether you are installing MARTi in a local configuration (analysis performed on a laptop/desktop) or an HPC configuration (analysis performed on an HPC Cluster).

Both components are contained within a single GitHub repository. You need to copy the MARTi software onto any computer that will be running the MARTi Engine (back-end) or the MARTi GUI (web server). If running in local mode, this will be the same computer. If running in an HPC mode, you will copy the software on to the cluster and also onto the computer where you will be running the web server for the GUI. For simplicity, it is not necessary to separate the Engine from the GUI for installation purposes.

Prerequisites

In order to run the MARTi Engine (back-end), you also need to install the following on the machine where it will be running:

BLAST (2.12.0 or greater) - download from NCBI or, optionally, install with homebrew on Mac. On Ubuntu, using apt-get may install an older version. In which case, it may be easiest to download executables from the NCBI link above.
BLAST databases - what you’ll need will depend on what you’re trying to do, but you might want to start with the nt database (See Blast database installation information here).
NCBI taxonomy - you can download this from the NCBI taxonomy FTP site. You need the taxdump files, specifically the nodes.dmp and names.dmp files.
Java Run Time Environment (OpenJDK 16.0.2 or greater) - the simplest option is to install OpenJDK. Note, on Macs, the documentation for OpenJDK isn’t great. Once you download the JDK, you need to move the directory into /Library/Java/VirtualMachines (as described here). Or install with homebrew (use brew install openjdk).

If you want to use Centrifuge or Kraken2 to classify reads, these will also need to be installed and available on the path. As with BLAST, you can use any database built for these tools (either by downloading one directly, or building your own following the tools’ instructions):

Centrifuge - prebuilt binaries are available here, or it can be built from source from GitHub.
Kraken2 - download here or on GitHub.

In order to run the MARTi GUI, you also need to install the following on the computer where it will be running:

Node.js (14.17.5 or greater) - you can download it from nodejs.org. NPM, a package manager for Node.js packages, is included with the Node.js installation and therefore doesn’t need to be installed separately. On Ubuntu, using apt-get may install an older version. In which case, see the Installation instructions here.

If you are only running the GUI on a particular computer, you do not need to install the Engine dependencies. If you are only running the engine on a particular computer, you do not need to install the GUI dependencies. If you are running both the Engine and the GUI on a single computer, then you need to install both sets of dependencies on that computer.

Downloading

The easiest way to keep up to date with MARTi is to clone the GitHub repository. To do this, go to the command line, change into a convenient directory and then type:

git clone https://github.com/richardmleggett/MARTi.git

Alternatively, you can visit GitHub and download a zip file with everything in it.

MARTi Engine (back-end) installation

Having copied the MARTi software onto the computer or cluster being used for the back-end, you need to perform a couple of additional actions.

First, you need to add the marti bin directory to the list of directories specified in the PATH environment variable. You can do this by adding an export command to your ~/.bashrc file. For example:

export PATH=/path/to/MARTi/bin:$PATH
The marti script inside the bin directory is used to launch MARTi Engine. Open this in a text editor and change line 6 to point to the location of the bin on your system, e.g.:

MARTI_DIR=/path/to/MARTi/bin

You can check the MARTi Engine is installed by typing:

marti -h

If you see the help text, all is ok.

MARTi GUI (front-end) installation

Having copied the MARTi software onto the computer or cluster being used for the back-end, you need to perform a couple of additional actions.

If you’re only installing the front-end and not the back-end, you still need to add the marti bin directory to your PATH environment variable - follow this step from the back-end installation if you haven’t already done so.
The marti_gui script inside the bin directory is used to launch MARTi GUI. Open this in a text editor and change line 4 to point to the location of the gui directory e.g.:

MARTI_DIR=/Users/leggettr/Documents/github/MARTi/gui
Then install the GUI server dependencies by running the following command from inside the gui/UI/ directory (e.g. cd gui/UI) :

npm install
To start the GUI server, type:

marti_gui --marti /path/to/marti_output

Or, if you want to specify an engine options file: marti_gui --options [/path/to/marti_engine_options.txt]

To view the GUI, open a browser and navigate to GUI’s port. For example, if using the default port enter the following into the address bar:

localhost:3000

marti_engine_options.txt

Both the engine and the GUI can make use of the optional marti_engine_options.txt file which can be placed in your home directory. This file contains the default locations of taxonomy directories and database definitions which are used in two ways:

By the Engine when using the -writeconfig option. The processes defined in the options file will then be written to the example config Gile.

By the GUI when the user is creating a new analysis. The options will be used to populate the New analysis webpage, but can be changed.

An example marti_engine_options file is provided in the bin directory and can be copied to your home directory:

cp bin/marti_engine_options.txt ~/

This file contains the locations of some important directories and you will need to update these for your system installation:

TaxonomyDirectory - the location of NCBI taxonomy data (i.e. the directory containing nodes.dmp and names.dmp).

MinKNOWRunDirectory - path to the directory containing sequencing runs to be analysed by MARTi. The data for each run directory within the MinKNOWRunDirectory should be in fastq format inside a directory called fastq_pass, pass, or fastq. For example, if your MinKNOWRunDirectory is set to the following: /Users/peeln/Documents/data and you want to analyse a run called Flongle_run_11102022 then the full path to the pass read data for that sample could look something like this: /Users/peeln/Documents/data/Flongle_run_11102022/20221011_1041_X2_AMT909_e26da2dd/fastq_pass or simply: /Users/peeln/Documents/data/Flongle_run_11102022/pass

MARTiSampleDirectory - the location of a directory that contains, or will contain, MARTi output data. The MARTi GUI will monitor this directory for results to display.

You can also modify the template BLAST processes for your configuration.

The following parameters are specific to the GUI:

Port: Specify the port number to be used. Ignore this if unsure. The default port number is 3000.

https: False by default. If true the path to Key: and Certificate: is required as well.

Possible macOS differences

On some versions of macOS, you may get an error about fsevents.node the first time you run it:

To get rid of this, you need to go the Security & Privacy preferences window and click “Allow Anyway” next to the fsevents.node error.

After this, you may get an additional error:

Click on “Open” and hopefully that will be macOS’s last warning!