Merge branch '9-make-the-documentation-executable' into gsod-rtd

.gitignore

@@ -101,3 +101,6 @@ img/
 
 # vim backup files
 .*.sw?
+
+vp-analysis/
+docs/documentation/quick_install.sh 

docs/_config.yml

@@ -10,6 +10,7 @@ logo: assets/images/logo-vpipe.svg
 # See https://jupyterbook.org/content/execute.html
 execute:
   execute_notebooks: force
+  timeout: -1
 
 # Define the name of the latex output file for PDF builds
 latex:

docs/documentation/installation.ipynb

@@ -0,0 +1,214 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Installation\n",
+    "\n",
+    "The present tutorial will show you how to install V-pipe and the dependencies required to start using it - bioconda, conda-froge mamba and snakemake - before continuing with other tutorials and analysing virus data.\n",
+    "\n",
+    "## For the impatient\n",
+    "\n",
+    "Download the install script and run it with the following parameters:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "tags": [
+     "hide-output"
+    ],
+    "vscode": {
+     "languageId": "shellscript"
+    }
+   },
+   "outputs": [],
+   "source": [
+    "%%bash\n",
+    "curl -O 'https://raw.githubusercontent.com/cbg-ethz/V-pipe/master/utils/quick_install.sh'\n",
+    "bash quick_install.sh -p vp-analysis -w work"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "\n",
+    "## Requirements\n",
+    "\n",
+    "V-pipe is optimized for Linux or Mac OS systems, and we heavily rely on bioconda, which isn't supported on Windows. Therefore, we recommend users with a Windows system to [install WSL2](https://learn.microsoft.com/en-us/windows/wsl/install).\n",
+    "\n",
+    "(quick-install-v-pipe-and-conda)=\n",
+    "## Quick install V-pipe and conda\n",
+    "\n",
+    "V-pipe uses the [Bioconda](https://bioconda.github.io/) bioinformatics software repository for all its pipeline components. The pipeline itself is implemented using [Snakemake](https://snakemake.readthedocs.io/en/stable/). Although you can install all the dependencies manually, we recommend using our install quick install script:\n",
+    "\n",
+    "```bash\n",
+    "curl -O 'https://raw.githubusercontent.com/cbg-ethz/V-pipe/master/utils/quick_install.sh'\n",
+    "bash quick_install.sh -p vp-analysis -w work\n",
+    "```\n",
+    "The script `quick_install.sh` has the following options:\n",
+    "\n",
+    "* using `-p` specifies the subdirectory where to download and install snakemake and V-pipe\n",
+    "* using `-w` will create a working directory and populate it. It will create a boilerplate `config/config.yaml`, and create a handy `vpipe` short-cut script to invoke `snakemake`.\n",
+    "* an additional option `-b` (not demonstrated above) allows to install a spefic branch or tagged version. If nothing is specified, the master branch will be installed.\n",
+    "\n",
+    "After running the `quick_install.sh` script, you should have a directory structure like this:\n",
+    "\n",
+    "```text\n",
+    "vp-analysis\n",
+    "├── Mambaforge-Darwin-x86_64.sh\n",
+    "├── V-pipe # cloned from https://github.com/cbg-ethz/V-pipe\n",
+    "│   ├── CONTRIBUTING.md\n",
+    "│   └── ..\n",
+    "├── mambaforge # installation of dependencies including snakemake\n",
+    "│   ├── LICENSE.txt\n",
+    "│   └── ..\n",
+    "└── work # working directory\n",
+    "    ├── config.yaml\n",
+    "    └── vpipe\n",
+    "```\n",
+    "\n",
+    "- `vp-analysis` is the main directory where we will store everything.\n",
+    "- `mambaforge` is the directory where conda will be installed including the dependencies to start using V-pipe.\n",
+    "- `V-pipe` is the directory where V-pipe's code will be downloaded from GitHub\n",
+    "- `work` finally, each analysis of virus data will be performed in a directory like `work…`. If you start a new analysis of a dataset, you can create a new directory, run `init_project.sh` inside the directory and get started.\n",
+    "\n",
+    "Now you can check your installation with a small test dataset:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "tags": [
+     "hide-output"
+    ],
+    "vscode": {
+     "languageId": "shellscript"
+    }
+   },
+   "outputs": [],
+   "source": [
+    "%%bash\n",
+    "cd vp-analysis/work\n",
+    "\n",
+    "# clone a specific branch of the V-pipe repository\n",
+    "# the two lines below can be deleted when this branch is merged into the main branch\n",
+    "rm -rf ../V-pipe\n",
+    "git clone -b gsod-rtd https://github.com/GeertvanGeest/V-pipe.git ../V-pipe\n",
+    "\n",
+    "# copy the example data from the repository to your working directory\n",
+    "cp -r ../V-pipe/docs/example_HIV_data/* .\n",
+    "# check what will be run with a dry run\n",
+    "./vpipe -n\n",
+    "# run vpipe on a small HIV test dataset\n",
+    "# this will install all dependencies and run the pipeline\n",
+    "./vpipe --cores 2"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "```{tip}\n",
+    "To create and populate other new working directories, you can call `init_project.sh` from within the new directory:\n",
+    "\n",
+    "```bash\n",
+    "cd vp-analysis/\n",
+    "\n",
+    "mkdir -p working_2\n",
+    "cd working_2\n",
+    "../V-pipe/init_project.sh\n",
+    "\n",
+    "```\n",
+    "\n",
+    "## Other installation options\n",
+    "\n",
+    "### Cloning the repository \n",
+    "\n",
+    "The V-pipe repository contains a snakemake pipeline. In order to run it directly with snakemake, clone the repository with:\n",
+    "\n",
+    "```sh\n",
+    "git clone https://github.com/cbg-ethz/V-pipe.git\n",
+    "```\n",
+    "\n",
+    "If you haven't already done so, install snakemake by using the [official instructions](https://github.com/cbg-ethz/V-pipe.git), and you can run the pipeline with `snakemake --use-conda`. \n",
+    "\n",
+    "Test the installation with a small dataset: \n",
+    "\n",
+    "```bash\n",
+    "mkdir work\n",
+    "cd work\n",
+    "cp -r ../V-pipe/docs/example_HIV_data/* .\n",
+    "snakemake -s ../V-pipe/workflow/Snakefile --use-conda --dry-run\n",
+    "snakemake -s ../V-pipe/workflow/Snakefile --use-conda --cores 4\n",
+    "```\n",
+    "\n",
+    "### Using Docker\n",
+    "\n",
+    "```{note}\n",
+    "Note: the [docker image](https://github.com/cbg-ethz/V-pipe/pkgs/container/v-pipe) is only setup with components to run the workflow for HIV and SARS-CoV-2 virus base configurations.\n",
+    "Using V-pipe with other viruses or configurations might require internet connectivity for additional software components.\n",
+    "```\n",
+    "\n",
+    "Create `config.yaml` and then populate the directory containing raw reads, typically `samples/`.\n",
+    "For example, the following config file could be used:\n",
+    "\n",
+    "```yaml\n",
+    "general:\n",
+    "  virus_base_config: hiv\n",
+    "\n",
+    "output:\n",
+    "  snv: true\n",
+    "  local: true\n",
+    "  global: false\n",
+    "  visualization: true\n",
+    "  QA: true\n",
+    "```\n",
+    "\n",
+    "Then execute:\n",
+    "\n",
+    "```bash\n",
+    "docker run --rm -it -v $PWD:/work ghcr.io/cbg-ethz/v-pipe:master --jobs 4 --printshellcmds --dry-run\n",
+    "```\n",
+    "\n",
+    "### Using Snakedeploy\n",
+    "\n",
+    "Install snakedeploy according to the [official instructions](https://snakedeploy.readthedocs.io/en/latest/getting_started/installation.html).\n",
+    "\n",
+    "Snakemake's [official workflow installer Snakedeploy](https://snakemake.github.io/snakemake-workflow-catalog/?usage=cbg-ethz/V-pipe) can now be used:\n",
+    "\n",
+    "```bash\n",
+    "snakedeploy deploy-workflow https://github.com/cbg-ethz/V-pipe --tag master .\n",
+    "# edit config/config.yaml and provide samples/ directory\n",
+    "snakemake --use-conda --jobs 4 --printshellcmds --dry-run\n",
+    "```\n",
+    "\n"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": ".env",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.8.5"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}