Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Add installation instructions for conda installation #20

Merged
merged 1 commit into from
May 18, 2023
Merged

Add installation instructions for conda installation #20

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
87 changes: 52 additions & 35 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,52 +6,33 @@ More about mGEMS in the article [Bacterial genomic epidemiology with mixed
samples](https://www.microbiologyresearch.org/content/journal/mgen/10.1099/mgen.0.000691)
in Microbial Genomics.

If you use mGEMS, please cite us as "Mäklin T, Kallonen T, Alanko J et
al. Bacterial genomic epidemiology with mixed samples. Microb Genom
2021, 7:11 (https://doi.org/10.1099/mgen.0.000691)"

You should also cite the method that you used to estimate the input
probability matrix to mGEMS, which is likely to be
[mSWEEP](https://github.com/PROBIC/mSWEEP).

To cite a specific version of mGEMS, visit the [releases
page](https://github.com/PROBIC/mGEMS/releases) and find the doi for
the version of the program that you used. Then, cite the version
(v1.1.0 in the example) as "Tommi Mäklin. (2021). PROBIC/mGEMS:
mGEMS-v1.1.0 (20 October 2021)
(v1.1.0). Zenodo. (https://doi.org/10.5281/zenodo.5583245)". Citing
the source code properly helps ensure that your analyses are
reproducible. Please also cite [the
article](https://www.microbiologyresearch.org/content/journal/mgen/10.1099/mgen.0.000691)
if you use mGEMS.

## Installation
### Dependencies
To run the binning + assembly pipeline, you will need a program that
does pseudoalignment and another program that estimates an assignment
probability matrix for the reads to the alignment targets.
In addition to mGEMS, to run the binning pipeline, you will likely
need a program that pseudoalignment and another program that estimates
an assignment probability matrix for the reads to the alignment
targets. Please see the Dependencies subsection for more details.

We recommend to use [Themisto](https://github.com/algbio/themisto)
(v2.0.0 or newer) for pseudoalignment and
[mSWEEP](https://github.com/probic/mSWEEP) (v1.3.2 or newer) for
estimating the probability matrix. For assembling the bins output by
mGEMS, we recommend [shovill](https://github.com/tseemann/shovill) for
typical use-cases but metagenomic assemblers like
[MEGAHIT](https://github.com/voutcn/megahit) may perform better when
the differences between the bins are especially small (see
Supplementary Figure 2 of the mGEMS preprint).
### Conda
Install mGEMS from bioconda with
```
conda install -y -c bioconda -c conda-forge -c defaults mgems
```

check that the installation succeeded by running
```
mGEMS
```

### mGEMS binaries
mGEMS can be obtained in the form of a precompiled binary
Precompiled binaries are available for
* [Linux 64-bit binary](https://github.com/PROBIC/mGEMS/releases/download/v1.2.0/mGEMS_linux-v1.2.0.tar.gz)
* [macOS 64-bit binary](https://github.com/PROBIC/mGEMS/releases/download/v1.2.0/mGEMS_macOS-v1.2.0.tar.gz)

or by following the instructions below for compiling mGEMS from source.

### Compiling from source
#### Requirements
- C++17 compliant compiler.
- cmake
- git

#### Compilation
Clone the repository
Expand All @@ -67,6 +48,22 @@ make
```
This will compile the mGEMS executable in the build/bin/ directory.

### Dependencies
We recommend to use [Themisto](https://github.com/algbio/themisto)
(v2.0.0 or newer) for pseudoalignment and
[mSWEEP](https://github.com/probic/mSWEEP) (v1.3.2 or newer) for
estimating the probability matrix.

For assembling the bins output by mGEMS, we recommend
[shovill](https://github.com/tseemann/shovill) for typical use-cases
but metagenomic assemblers like
[MEGAHIT](https://github.com/voutcn/megahit) may perform better when
the differences between the bins are especially small (see
Supplementary Figure 2 of the mGEMS preprint). Shovill comes with an
option to use different assemblers as the backend (default is SPAdes).

mSWEEP and shovill can be easily installed from bioconda.

## Usage
### mGEMS
The mGEMS executable provides three commands: mGEMS, mGEMS bin, and
Expand Down Expand Up @@ -168,6 +165,26 @@ mGEMS accepts the following input flags
--unique-only (Optional) Write only the reads that are assigned to a single group.
```

## Citation
If you use mGEMS, please cite us as "Mäklin T, Kallonen T, Alanko J et
al. Bacterial genomic epidemiology with mixed samples. Microb Genom
2021, 7:11 (https://doi.org/10.1099/mgen.0.000691)"

You should also cite the method that you used to estimate the input
probability matrix to mGEMS, which is likely to be
[mSWEEP](https://github.com/PROBIC/mSWEEP).

To cite a specific version of mGEMS, visit the [releases
page](https://github.com/PROBIC/mGEMS/releases) and find the doi for
the version of the program that you used. Then, cite the version
(v1.1.0 in the example) as "Tommi Mäklin. (2021). PROBIC/mGEMS:
mGEMS-v1.1.0 (20 October 2021)
(v1.1.0). Zenodo. (https://doi.org/10.5281/zenodo.5583245)". Citing
the source code properly helps ensure that your analyses are
reproducible. Please also cite [the
article](https://www.microbiologyresearch.org/content/journal/mgen/10.1099/mgen.0.000691)
if you use mGEMS.

## License
The source code from this project is subject to the terms of the MIT
license. A copy of the MIT license is supplied with the project, or
Expand Down