From 977068ca2e6a51a42344c55f06b1aac37c33d773 Mon Sep 17 00:00:00 2001 From: Gemy George Kaithakottil Date: Tue, 1 Oct 2024 10:27:39 +0100 Subject: [PATCH] Update README.md with Docker/Singularity/Conda/Mamba/Manual installation steps --- README.md | 120 +++++++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 96 insertions(+), 24 deletions(-) diff --git a/README.md b/README.md index ac016ad9..2aa95bed 100644 --- a/README.md +++ b/README.md @@ -13,52 +13,124 @@ Our approach is amenable to include sequences generated by *de novo* Illumina as Extended documentation is hosted on ReadTheDocs: http://mikado.readthedocs.org/ +## Contents +- [Installation](#installation) + - [Docker Installation](#docker-installation) + - [Singularity Installation](#singularity-installation) + - [Conda Installation](#condamambamanual-installation) + ## Installation -Using mamba +### Docker Installation +Mikado can be installed with docker. If you don't have docker, please install [docker](https://docs.docker.com/get-docker/) first. Then you can pull the docker image with mikado installed +```console +VERSION=2.3.5rc2 +docker run gemygk/mikado:v${VERSION} mikado -h +``` + +### Singularity Installation +Mikado can be installed with singularity. If you don't have singularity, please install [singularity](https://docs.sylabs.io/guides/3.9/user-guide/quick_start.html#quick-installation-steps) first. Then you can pull the singularity image with mikado installed. +```console +VERSION=2.3.5rc2 +singularity exec docker://gemygk/mikado:v${VERSION} mikado -h +``` + +### Conda/Mamba/Manual Installation +Mikado can be installed with conda. If you don't have conda, please install [mamba](https://github.com/conda-forge/miniforge?tab=readme-ov-file#miniforge-pypy3) first. Then you can create a new environment with mikado installed. + +Install mamba with PyPy 3.9 in the base environment (https://github.com/conda-forge/miniforge?tab=readme-ov-file#miniforge-pypy3) -download mamba using pip +Replace `/path/to` with your installation directory when following the steps below: -```bash -pip install mamba=0.27.0 +```console +/path/to/src +[src]$ wget -c https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge-pypy3-Linux-x86_64.sh +[src]$ bash Miniforge-pypy3-Linux-x86_64.sh ``` -Create a mamba environment using the environment.yml file +I have installed the base to `/path/to/x86_64/` location -```bash -mamba env create -f environment.yml -conda activate mikado2 +If you have chosen to not have conda modify your shell scripts at all, to activate conda's base environment in your current shell session, please do: + +```console +/path/to/src +[src]$ eval "$(/path/to/x86_64/bin/conda shell.bash hook)" ``` -Check and run mikado +Install Git -```bash -mikado --help +```console +/path/to/src +(base) [src]$ mamba install -y git ``` +Clone mikado +```console +/path/to/src +(base) [src]$ git clone git@github.com:EI-CoreBioinformatics/mikado.git +(base) [src]$ cd mikado +``` +Install Mikado dependencies +```console +/path/to/src/mikado +(base) [mikado]$ mamba env create -f environment.yml --prefix /path/to/x86_64/envs/mikado_env +``` -Mikado can also be be installed from PyPI with pip (**deprecated**): +Activate mikado_env +```console +/path/to/src/mikado +(base) [mikado]$ conda activate mikado_env +(mikado_env) [mikado]$ +``` -``pip3 install mikado`` +Do checks if all dependencies are installed. A full list of library dependencies can be found in the file ``requirements.txt`` +```console +/path/to/src/mikado +(mikado_env) [mikado]$ pip3 install wheel +(mikado_env) [mikado]$ pip3 install -r requirements.txt +(mikado_env) [mikado]$ pip3 install Cython +``` +- For the above commands - wheel, requirements.txt, Cython should all have the status 'Requirement already satisfied' -Alternatively, you can clone the repository from source and install with: - pip wheel -w dist . - pip install dist/*whl +We need gcc for bdist_wheel (tested on gcc v5.2.0, v9.4.0) + +```console +/path/to/src/mikado +(mikado_env) [mikado]$ python3 setup.py bdist_wheel +(mikado_env) [mikado]$ pip3 install dist/*.whl +``` +Now that installation is complete, run Mikado help +```console +/path/to/src/mikado +(mikado_env) [mikado]$ mikado -h +usage: Mikado [-h] [--version] {configure,prepare,serialise,pick,compare,util} ... + +Mikado is a program to analyse RNA-Seq data and determine the best transcript for each locus in accordance to user-specified criteria. + +optional arguments: + -h, --help show this help message and exit + --version Print Mikado current version and exit. + +Components: + {configure,prepare,serialise,pick,compare,util} + These are the various components of Mikado: + configure This utility guides the user through the process of creating a configuration file for Mikado. + prepare Mikado prepare analyses an input GTF file and prepares it for the picking analysis by sorting its transcripts and performing some simple consistency checks. + serialise Mikado serialise creates the database used by the pick program. It handles Junction and ORF BED12 files as well as BLAST XML results. + pick Mikado pick analyses a sorted GTF/GFF files in order to identify its loci and choose the best transcripts according to user-specified criteria. It is dependent on files produced by the "prepare" and "serialise" + components. + compare Mikado compare produces a detailed comparison of reference and prediction files. It has been directly inspired by Cufflinks's cuffcompare and ParsEval. + util Miscellaneous utilities +``` -You can verify the correctness of the installation with the unit tests (*outside of the source folder*, as otherwise Python will get confused and try to use the `Mikado` source folder instead of the system installation): - python -c "import Mikado; Mikado.test(); Mikado.test(label='slow')" -An alternative way of installing using `setuptools`: +You can verify the correctness of the installation with the unit tests (*outside of the source folder*, as otherwise Python will get confused and try to use the `Mikado` source folder instead of the system installation): - pip install -r requirements.txt - pip install Cython - python setup.py bdist_wheel - pip install dist/*whl + python -c "import Mikado; Mikado.test(); Mikado.test(label='slow')" -The steps above will ensure that any additional python dependencies will be installed correctly. A full list of library dependencies can be found in the file ``requirements.txt`` ### Additional dependencies