Merge pull request #71 from rajewsky-lab/add_mln_example

Add mln example

docs/examples/human_metastatic/0_environment.ipynb

@@ -0,0 +1,199 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Preparing the environment"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "First, we will walk you through the basics of using the command line interface (CLI), which is essential for running tools like `spacemake` and `Open-ST`. We assume you are running Linux (e.g., Ubuntu 22.04). A computer with at least 128 GB of RAM is recommended for `spacemake` and `openst`. Future optimizations to `spacemake` will reduce memory requirements."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Installing dependencies\n",
+    "\n",
+    "We will install two dependencies: `spacemake` and `openst`.\n",
+    "\n",
+    "For this, we assume that you have installed `mamba` or any similar (e.g., `micromamba`), and you have opened a terminal (local or remote machine).\n",
+    "\n",
+    "Create a new directory for this tutorial."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "vscode": {
+     "languageId": "plaintext"
+    }
+   },
+   "source": [
+    "```bash\n",
+    "WORKDIR=\"~/openst_demo\" # change this to any folder you want\n",
+    "mkdir -p $WORKDIR\n",
+    "cd $WORKDIR\n",
+    "```"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "During the rest of the tutorial, the root working directory will be\n",
+    "```bash\n",
+    "~/openst_demo\n",
+    "```\n",
+    "\n",
+    "Which we store in the environment variable `$WORKDIR`. You can change this to anything else."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Installing `spacemake`"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Then, create a new environment for `spacemake`:"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "vscode": {
+     "languageId": "plaintext"
+    }
+   },
+   "source": [
+    "```bash\n",
+    "wget \"https://raw.githubusercontent.com/rajewsky-lab/spacemake/master/environment.yaml\"\n",
+    "mamba env create -n openst -f environment.yaml\n",
+    "mamba activate openst\n",
+    "pip install spacemake\n",
+    "```"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Check that your `spacemake` version matches the one that will be used for this tutorial (0.7.9)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "vscode": {
+     "languageId": "plaintext"
+    }
+   },
+   "source": [
+    "```bash\n",
+    "spacemake --version\n",
+    "# make sure it is 0.7.9 or greater\n",
+    "```"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Installing `openst`"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Now, create another environment for `openst`. We have developed `openst` separately from `spacemake`, because `spacemake` is tech-agnostic (can run on scRNA-seq, Visium, Open-ST), while `openst` provides tools that are specific to the Open-ST technology (for segmenting, aligning, visualizing, image pre-processing...)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "vscode": {
+     "languageId": "plaintext"
+    }
+   },
+   "source": [
+    "```bash\n",
+    "# make sure the environment is still active!\n",
+    "# mamba activate openst\n",
+    "pip install openst\n",
+    "```"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Check that your `openst` version matches the one that will be used for this tutorial (0.2.3)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "vscode": {
+     "languageId": "plaintext"
+    }
+   },
+   "source": [
+    "```bash\n",
+    "openst --version\n",
+    "# make sure it is 0.2.3 or greater\n",
+    "```"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "!!! note\n",
+    "    You might need to leave things running in the background (some things take hours to finish). We recommend using tmux; from the RedHat Sysadmin article:\n",
+    "\n",
+    "    >Tmux is a terminal multiplexer; it allows you to create several **\"pseudo terminals\"** from a single terminal. \n",
+    "\n",
+    "    >This is very useful for running multiple programs with a single connection, \n",
+    "\n",
+    "    >such as when you're remotely connecting to a machine using Secure Shell (SSH).\n",
+    "\n",
+    "    Open your `~/.bashrc` (or `~/.zshrc`) file with a text editor, or VIM, or anything else, and add the following lines:\n",
+    "\n",
+    "    ```bash\n",
+    "    alias ta='tmux attach -t'\n",
+    "    alias tl='tmux ls'\n",
+    "    alias tn='tmux new -s'\n",
+    "    ```\n",
+    "\n",
+    "    The next time you open a terminal, these aliases will be available:\n",
+    "\n",
+    "    - `tn pepa`: create a new *pseudo-terminal* with name \"pepa\"\n",
+    "    - `ta pepa`: attaches to the *pseudo-terminal* called \"pepa\"\n",
+    "    - `tl`: lists all *pseudo-terminals* that are available\n",
+    "\n",
+    "    To deattach a *pseudo-terminal*, you have the keyboard shortcut `Ctrl`+`b`+`d`\n",
+    "\n",
+    "    To close a *pseudo-terminal*, you close all panels type `exit` and press `Enter`, or to close all at once you can use `Ctrl`+`b`+`&`"
+   ]
+  }
+ ],
+ "metadata": {
+  "language_info": {
+   "name": "python"
+  },
+  "orig_nbformat": 4
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}