Automappa: An interactive interface for exploration of metagenomes

Image Name	Image Tag	Status
`evanrees/automappa`	`main`,`latest`
`evanrees/automappa`	`develop`

Automappa 🌳

Follow this link to get started using the fully-featured Automappa application: https://github.com/WiscEvan/Automappa/tree/develop#getting-started

Test Data

Test data to try out Automappa may be downloaded from here: https://drive.google.com/drive/folders/1nBk0AZC3EJV4t-9KdJBShGCfWbdP2kOp?usp=sharing

This data is not yet binned, so you can easily try out different settings and perform your own refinements on some example data.

Happy binning!

Automappa-lite 🌱

NOTE: The following section is a lightweight version of Automappa that may be slow and is not constructed for larger datasets. If you would like to use all of Automappa's features see the Automappa section above or navigate to the getting started page for the full-featured app.

Install with conda
Run automappa using docker
Install from source
Advanced Usage

Install Automappa-lite with conda

If you are using conda (or mamba) as a package manager, you can simply install automappa using one of the following one-liners.

with `conda`

conda install -c bioconda automappa

with `mamba`

mamba install -c bioconda automappa

After you have installed automappa, you can simply run automappa -h to see a list of available arguments.

To start the automappa app, you must specify your main binning results and respective kingdom's single-copy marker annotations generated from an Autometa analysis. If you do not yet have these annotations and are not sure where to start, I would recommend checking out Autometa's documentation

Example `automappa` command

automappa --binning-main </path/to/bacteria.binning.main.tsv> --markers </path/to/bacteria.markers.tsv>

Automappa-lite Quickstart using Docker (No installation required)

To quickly start exploring your data, run the app using a wrapper script that will run the docker image, evanrees/automappa:latest, (available from Dockerhub). Now you can skip installation and start binning, examining and describing! Let the microbial exegesis begin!

Running with a docker container using `run_automappa.sh`

A docker wrapper is available to run a docker container of Automappa. The only required input for this script is the autometa main binning output table and the respective markers table.

# First retrieve the script:
curl -o run_automappa.sh https://raw.githubusercontent.com/WiscEvan/Automappa/main/docker/run_automappa.sh
# (make it executable)
chmod a+x run_automappa.sh

Now run automappa on autometa binning results using the downloaded script: run_automappa.sh.

Start automappa docker container

NOTE: This will pull the automappa docker image if it is not already available

./run_automappa.sh --binning binning.main.tsv --markers binning.markers.tsv

Install Automappa-lite from source

Installation from source (using `make`)

You can install all of Automappa's dependencies using the Makefile found within the repository.

Clone the Automappa repository

cd $HOME
git clone https://github.com/WiscEvan/Automappa.git
cd $HOME/Automappa

First create environment

make create_environment

Activate environment

source activate automappa

The following will install the automappa entrypoint

make install

Now that all of the dependencies are installed, you may run the Automappa-lite app on your local machine or on a server.

Listing available `make` commands

You may also list other available make commands by simply typing make with no other arguments.

make

A few examples:

pull docker image

make docker

build docker image

make image

Usage

Simply provide the automappa entrypoint with the main binning file output by Autometa as well as the respective markers file.

automappa \
    --binning-main <path to binning.main.tsv> \
    --markers <path to binning.markers.tsv>

Advanced Usage

Full `docker run` command example

# Set automappa parameters (required)
binning="$HOME/test/binning.main.tsv"
markers="$HOME/test/binning.markers.tsv"

# Set docker image/container parameters (optional)
localport=8050
containerport=8886
imagetag="latest"

#NOTE: Some necessary path handling here for binding docker volumes
binning_dirname="$( cd -- "$(dirname "$binning")" >/dev/null 2>&1 ; pwd -P )"
binning_filename=$(basename $binning)
markers_dirname="$( cd -- "$(dirname "$markers")" >/dev/null 2>&1 ; pwd -P )"
markers_filename=$(basename $markers)

# Run with provided parameters
docker run \
    --publish $localport:$containerport \
    --detach=false \
    -v $binning_dirname:/binning:rw \
    -v $markers_dirname:/markers:ro \
    --rm \
    evanrees/automappa:$imagetag \
      --binning-main /binning/$binning_filename \
      --markers /markers/$markers_filename \
      --port $containerport \
      --host 0.0.0.0

Using a remote Automappa server

If you'd like to run Automappa on a remote server but view the output on your local machine,

Example remote server login with ssh tunnel

you first need to login to the remote server with a tunnel, e.g. ssh -L localport:localhost:serverport user@hostaddress.

#ssh -L localport:127.0.0.1:serverport user@kwan-bioinformatics.pharmacy.wisc.edu
#example
ssh -L 8888:127.0.0.1:8050 sam@kwan-bioinformatics.pharmacy.wisc.edu

Once you are on the server, simply start the Automappa server (with the appropriate port from the ssh tunnel).

automappa \
    --binning-main <path to binning.main.tsv> \
    --markers <path to binning.markers.tsv> \
    --port 8050

Navigate to the app view in your browser.

This will correspond to the localport that was passed in upon login to the remote server. In the previous example above we would navigate to localhost:8888.

I've numbered the ports here to help illustrate the network communication.

Bridge	Port Bridge	Communication Context
`localport:remoteport`	`8888:8050`	`local:remote`

Using a remote docker container Automappa server

To access Automappa through a docker container that is on a remote machine, one additional bridge must be constructed.

First we need to forward a port from the server back to our local machine.

#ssh -L localport:localhost:serverport user@kwan-bioinformatics.pharmacy.wisc.edu
ssh -L 8888:localhost:8887 sam@kwan-bioinformatics.pharmacy.wisc.edu

Now run automappa using the docker wrapper script: run_automappa.sh

NOTE: A wrapper is available for download to run docker with port-forwarding.

curl -o $HOME/run_automappa.sh https://raw.githubusercontent.com/WiscEvan/Automappa/main/docker/run_automappa.sh
chmod a+x $HOME/run_automappa.sh

Now start automappa while setting --localport to match the serverport (8887 from above).

# NOTE: This will pull the automappa docker image if it is not already available.
$HOME/run_automappa.sh \
    --imagetag main \
    # NOTE: The 'localport' here is referring to the port on the remote
    --localport 8887 \
    --containerport 8050 \
    --binning binning.main.tsv \
    --markers binning.markers.tsv

Now navigate to http://localhost:8888 and you will see the loaded data.