Installation Instructions

Overview

MiModD runs under Linux and Mac OS X (10.9 - 10.11).

Software requirements are listed separately for the different installation schemes below. Hardware recommendations can be found here.

Standard Installation

This is the recommended and fastest way of installing MiModD. With all requirements in place, just run:

python3 -m pip install MiModD --user -v

to install the MiModD command line tool suite for the current user [1]. Standard installations are easy to integrate into, but do not require a local Galaxy installation. →Read more ...

[1]see our installation examples for system-wide and other installation modes

Galaxy Toolshed Installation

If you are administrator of an existing instance of Galaxy, you can add the MiModD tools to it through a simple Tool Shed install. This type of installation can be performed through the graphical web interface of Galaxy, is encapsulated in and managed by Galaxy and does not require changes to system directories. On the downside, there is no easy way to access the package from the command line. →Read more ...

Platform-specific bundles of MiModD and Galaxy

For users of selected platforms we are offering preconfigured ready-to-run bundles of MiModD and Galaxy that that do not require any installation at all - just download and extract a distribution and run a functional Galaxy with MiModD. While not recommended for production use (see also the disclaimer on the download page), these distributions offer a great way to get to know MiModD and to perform some first quick analyses. →Learn more about our Galaxy bundles and supported platforms at the bundle download site ...

Standard Installation

Instructions for OS X (10.9 - 10.11)

Requirements

  • Python 3.2+
  • optional: the pip installation tool for one-step installation

  1. Installing Python 3

    Download the latest release of Python 3 from https://www.python.org/downloads/ and run the installer. Make sure you choose to install pip if the install wizard offers you to do so.

  2. Installing MiModD

    1. with pip installed along with Python 3

      Open a terminal window and run:

      python3 -m pip install MiModD --user -v

      to install the latest version of MiModD for the current user [2].

      If you prefer a system-wide install visible for all users run:

      sudo python3 -m pip install MiModD -v

      and authenticate yourself as administrator when prompted to do so.

    or, alternatively (if you chose to or for some reason are not able to use pip):

    1. without pip (Note: supported only for Python 3.3 and above)

      • Visit https://sourceforge.net/projects/mimodd/files and navigate to the latest release folder.

      • Download the ...-cp##-cp##m-macosx... whl file for which ## matches the Python version you installed in step 1.

      • Open a terminal window and run:

        python3 <download_folder>/<whl_file_name> --user

        to install MiModD for the current user [2], or:

        sudo python3 <download_folder>/<whl_file_name>

        for a system-wide install.

        →see an example

You should now be ready to proceed to the next step Configuring MiModD for your system.

Instructions for Linux and other platforms

Requirements

  • a C/C++ compiler (tested with gcc/g++ and Clang)
  • the make utility
  • zlib library version 1.2.5+ including the developer header files
  • Python 3.2+ including the developer header files
  • optional: the pip installation tool for Python for one-step installation

  1. Installing requirements

    Different Linux distributions come with different subsets of the above requirements preinstalled and may offer others through there package management system. Please read Installation of required software for more details.

  2. Installing MiModD

    1. with pip installed for Python 3

      Open a terminal window and run:

      python3 -m pip install MiModD --user -v

      to install the latest version of MiModD for the current user [2].

      If you prefer a system-wide install visible for all users run:

      sudo python3 -m pip install MiModD -v

      and authenticate yourself as administrator when prompted to do so.

    or, alternatively (if you chose to or for some reason are not able to use pip):

    1. without pip (Note: supported only for Python 3.3 and above)

The installation may take a few minutes, but after it is finished, you can proceed to the next step Configuring MiModD for your system.

[2](1, 2, 3, 4) On OS X and some Linux distributions an inconvenience of installing MiModD for only the current user is that the mimodd executable will not be found automatically by the system. This can be fixed by manually adding the mimodd executable to the $PATH environment variable.

Galaxy Toolshed Installation

Requirements

None on OS X

Linux:

  • a C/C++ compiler (tested with gcc/g++ and Clang)
  • the make utility

MiModD is available from the main Galaxy Tool Shed. Use the mimodd repository for one-click installation of the latest version.

The installation process is the same as for any other Tool Shed tool, and is described here.

Note

After the installation, the complete Galaxy interface for all MiModD tools will be added to your Galaxy’s Tools bar, but the order of the tools will be more or less random. This is one of the disadvantages of the Tool Shed installation scheme and you will have to manually edit your Galaxy’s integrated_tool_panel.xml file to sort the items on the Tool bar.

Like for the standard installation, you should configure MiModD before using the package. However, for a Tool Shed installation of MiModD we recommend the environment variable-based configuration.

Configuring MiModD for your system

The simplest way to configure MiModD is from the command line using the config tool, and if you have installed MiModD according to the standard installation scheme, you MUST run the tool once before you can start using the freshly installed package.

If you have installed MiModD from the Galaxy Tool Shed, you can, alternatively, configure the package through an environmental variable recognized by MiModD.

In addition, all MiModD settings can be re-configured at any later time, using either approach.

The config tool

General usage:

python3 -m MiModD.config [--parameter VALUE] ...

Note

Depending on your installation of MiModD, changes to the configuration file may require superuser rights, in which case you will have to prepend sudo to the invocation of the tool.

Initial configuration

For a fresh standard installation of MiModD use:

python3 -m MiModD.config

from the command line to bring up a dialog that will ask you for a setting for each configurable parameter. Here is an example run of the tool:

% python3 -m MiModD.config

Which folder should MiModD use to store temporary data? [/var/tmp]:
In which folder should MiModD look for SnpEff? [/not configured]:
Up to how many threads do you want to allow MiModD to use at a time? [4]:3
Up to how much memory in GB do you want to allow MiModD to use? [2]:6

All necessary information has been collected.
Hit <Enter> to store your settings and start using MiModD.

To change settings later, you can rerun this tool with new settings
provided as command line options.


Settings for package MiModD in: /home/example/lib/python3.4/site-packages/MiModD

-----------------------
    PARAMETER : VALUE
    .......................
    TMPFILES_PATH : /var/tmp
    MAX_MEMORY : 6
    SNPEFF_PATH : /not configured
    MULTITHREADING_LEVEL : 3

For each setting a default value is suggested in brackets, which you can accept by hitting <ENTER> or overwrite by providing a different value. Finally, the new settings are displayed as confirmation.

If the reported settings look ok, you are ready to start using MiModD, otherwise read on how to change settings once they have been configured.

Inspect settings

If you run the tool without options and MiModD has already been configured, it will simply report the current settings as in the lower half of the above output.

Change settings

Running the config tool is also the standard way to change settings. Its invocation pattern for this purpose is:

python3 -m MiModD.config [--tmpfiles PATH] [--snpeff PATH] [-t THREADS] [-m MEMORY]

So to set a new TMPFILES_PATH and to set MAX_MEM to 8 GB, you could use:

python3 -m MiModD.config --tmpfiles /var/tmp/mimodd_tmp -m 8

Proceed to Configuration parameters to learn more about the settings that can be changed by the different options.

Configuration through an environment variable

As an alternative to command line configuration, you can provide new settings for the Configuration parameters also through the MiModD-specific environment variable $MIMODD_CONFIG_UPDATE.

The value of this variable has to be set to a :-separated list of parameter=value entries, for example:

export MIMODD_CONFIG_UPDATE=MAX_MEMORY=8:MULTITHREADING_LEVEL=4

The presence of the environment variable will be detected by MiModD at its next run from the same terminal, and will be used to update the package settings accordingly.

You can also pass the variable exclusively to Galaxy by prepending it to the start script and this is the recommended approach to configure a Galaxy Tool Shed installation of MiModD:

MIMODD_CONFIG_UPDATE=MULTITHREADING_LEVEL=3:TMPFILES_PATH=home/galaxy/tmp/ sh run.sh

With this, the MiModD settings will get updated when the first MiModD tool gets executed from within the Galaxy instance.

Note

Changes made through $MIMODD_CONFIG_UPDATE are persistent so the variable has to be found only once.

To store the change mimodd needs to be executed with write privileges for the MiModD package directory. This should not be an issue with Tool Shed installations of MiModD, but can make this configuration scheme problematic in combination with Standard Installations in system directories.

Configuration parameters

listed as pairs of

PARAMETER : config options
where PARAMETER can be used in the $MIMODD_CONFIG_UPDATE variable and the config options are used to set the same parameter using the python3 -m MiModD.config command.
TMPFILES_PATH : --tmpfiles, --tmpfiles-path

the directory in which MiModD will store temporary files [default: /var/tmp]

In a typical analysis pipeline, MiModD may produce several GB of data in this directory and remove them automatically again when the data is not any longer needed. Under exceptional circumstances, however, MiModD might fail to delete data files, so this directory is the first place you should look at if you notice reduced disk space. Also, any users of MiModD will require write permission in this directory.

MULTITHREADING_LEVEL : -t, --threads

the maximum number of cores that a single MiModD command is supposed to use at any time [default: 4]

Many MiModD commands take advantage of multiprocessing to speed up analyses. These commands try to respect this setting if possible although some may use slightly more than their allocated CPU share.

MAX_MEMORY : -m, --memory

the maximum memory in GB that any single MiModD command should use [default: 2]

WGS data files are often very large and some MiModD tools can operate on them more efficiently when allowed to hold a larger portion of such files in memory at once. Most of the time MiModD will consume less than 1 GB though. The setting is adhered to relatively strictly by most tools with the exception of the SNAP aligner-based tools mimodd snap index, mimodd snap, mimodd snap_batch and the Galaxy SNAP Read Alignment tool. Due to the nature of their underlying alignment algorithm these tools will require a fixed amount of memory that depends on the size of the reference genome and which may be significantly more than the configured setting.

Tip

MULTITHREADING_LEVEL and MAX_MEMORY will have a big effect on the performance of MiModD, but also on the responsiveness of your system during execution of MiModD commannds. As a rule of thumb, if you do not have special requirements, we recommend to set both parameters to between 50 and 75 % of the available resources on your system, i.e., if you have 8 threads and 16 GB of RAM on your system, you might set MULTITHREADING_LEVEL to 4-6 and MAX_MEM to 8-12.

See also the section MiModD Hardware Requirements for more notes on performance.

SNPEFF_PATH : --snpeff, --snpeff-path

the path to the optional SnpEff variant annotation tool

This parameter should be set to the directory that you installed SnpEff into (e.g., ~/snpEff if you followed the recommended installation steps). If you do not have SnpEff installed, keep the default setting, to have all SnpEff-dependent functionality of MiModD deactivated.

Running MiModD

To start using MiModD from the command line, after successful configuration, execute:

mimodd help

This should display an overview of available tools and help topics.

You can use mimodd help <tool name> to get more detailed help on a specific tool, e.g.:

mimodd help annotate

Note

If, instead of the expected output, you are getting a command not found or a similar error message, you should read our recipe for adding the mimodd executable to the $PATH environment variable.

See also

Extending MiModD

You can extend the functionality of MiModD by integrating it with additional free software. The following sections should get you started.

Keeping MiModD updated

We are always trying to improve MiModD and release new package versions with enhancements and bug-fixes regularly.

In order to keep you informed about available new versions and facilitate upgrades, MiModD features (since version 0.1.6) a dedicated upgrade tool. You can run (possibly with a prepended sudo):

python3 -m MiModD.upgrade install

anytime to upgrade to the latest available version.

Warning

Due to changes in the tool upgrades from versions prior to v0.1.7 need to be done sequentially by first upgrading to v0.1.7.0, then to the latest version. This can be done by running:

python3 -m MiModD.upgrade install -v 0.1.7.0

before the standard upgrade command above.