Installation
We recommend Mamba for installation handling. Conda can be used as an alternative, but Conda can take a long time to resolve dependencies, thus rendering installation via Conda significantly slower than installation via Mamba. Mamba/Conda will both manage dependencies and versioning, which simplifies the process of installation.
If you already have Conda but wish to use Mamba for installation, you can install Mamba by running the following:
conda install -c conda-forge mamba
Install Snekmer via Mamba/Conda
The simplest method for installation is via the included YML file, which will create a new environment containing Snekmer and all of its dependencies. Users may either directly download the YML file directly, or clone/fork the repository to obtain a local copy of the repository and all included files.
mamba env create -f environment.yml
Note that if you want to use the optional Blazing Signature Filter (BSF) to speed up clustering you must follow the BSF installation instructions below and then you can use the alternate conda environment.
mamba env create -f environment_BSF.yml
After the install completes activate the conda environment
conda activate snekmer
The package should now be ready to use!
Note that the instructions above can be replicated, substituting mamba
for conda
, for users who wish to use Conda to manage installation.
Troubleshooting Notes
The full version of Snakemake is incompatible with Windows. Thus, you will need to install the environment specifications that include only the minimal version of Snakemake:
mamba env create -f environment_Windows.yml
Install Snekmer via pip
Warning: Installation of Snekmer using pip
is not recommended due to the complexity
of dependencies associated with Snakemake. Mamba/Conda will handle these automatically,
whereas pip
will not.
The pip
implementation has not been fully tested, but users may attempt installation
using the included specifications:
pip install -r requirements.txt
pip install -e git+https://github.com/PNNL-CompBio/Snekmer#egg=snekmer
Install Snekmer via Docker
Snekmer has been installed into a public docker image hosted on Dockerhub. Usage requires the of installation of Docker Desktop. This container is intended to be used via an interactive shell. Here, we provide the simplest method of usage.
To download and run a container:
docker pull jjacobson95/snekmer_env:v1.0
docker run jjacobson95/snekmer_env:v1.0
To use the command line interface within the container:
docker ps # This will display <container ID>
docker exec -it <container ID> /bin/bash
Additional docker
commands can be used to copy data into the container or to mount it to a local directory.
The current version of the Docker image requires the --configfile
flag
to be called explicitly (see All Options).
Note: This container is designed to run indefinitely and should be stopped after use.
Notes on Using Snekmer Docker Image with Apple Silicon (M1/M2 Mac) Systems
The current Docker image of Snekmer has not been built for compatibility with ARM64 systems (e.g. Apple silicon systems with the Apple M1/M2 chip). To use the Docker image on an Apple silicon system, Rosetta 2 is required. See the relevant Docker documentation page for more information.
Rosetta 2 can be installed on the command line using softwareupdate
:
softwareupdate --install-rosetta
(optional) Install GCC for BSF
The Blazing Signature Filter is a pairwise similarity algorithm that can optionally be used to efficiently compute a distance matrix for Snekmer’s clustering mode.
Note that BSF is not required to run Snekmer. For users that do not want to use BSF for clustering, these instructions can be ignored.
In order for BSF to install correctly, GCC 4.9+ must be installed on your system using the following instructions for the listed operating systems. Once GCC is installed successfully, follow the remaining setup steps.
Mac
Install GCC and the relevant dependencies using Homebrew.
brew install gcc llvm libomp
After installing llvm
, some flags and your PATH
variable may need to
be updated. Homebrew will output a “Caveats” message that may resemble the one
shown below:
To use the bundled libc++ please add the following LDFLAGS:
LDFLAGS="-L/usr/local/opt/llvm/lib -Wl,-rpath,/usr/local/opt/llvm/lib"
llvm is keg-only, which means it was not symlinked into /usr/local,
because macOS already provides this software and installing another version in
parallel can cause all kinds of trouble.
If you need to have llvm first in your PATH, run:
echo 'export PATH="/usr/local/opt/llvm/bin:$PATH"' >> ~/.zshrc
For compilers to find llvm you may need to set:
export LDFLAGS="-L/usr/local/opt/llvm/lib"
export CPPFLAGS="-I/usr/local/opt/llvm/include"
You may follow these instructions to ensure GCC is correctly pulled as needed.
Note: BSF is not compatible with Apple silicon systems; see the ongoing log of known Apple silicon issues.
Windows or Linux/Unix
Please refer to the BSF documentation for Linux/Unix or Windows instructions for installing GCC.
BSF Install for Snekmer Use
In the snekmer conda environment use the command
pip install git+https://github.com/PNNL-CompBio/bsf-jaccard-py#egg=bsf