{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Getting started\n",
    "\n",
    "The notebooks can be downloaded from a [tutorials folder on\n",
    "GitHub](https://github.com/nismod/snail/tree/main/docs/source/tutorials)\n",
    "\n",
    "This note will cover the technical setup that allows to locally run the\n",
    "notebooks and reproduce the results. It is recommended to use a micromamba\n",
    "environment and this section will be using it to setup a jupyter notebook or\n",
    "VScode workflows. \n",
    "\n",
    "### Setup\n",
    "\n",
    "The two cases either use the Jupyter notebook interface, or Visual Studio Code\n",
    "to run the tutorials. \n",
    "\n",
    "Once you have downloaded the repo or copied the tutorials notebooks into a\n",
    "folder, navigate to it via the terminal. Once inside, run the following: "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "vscode": {
     "languageId": "shellscript"
    }
   },
   "outputs": [],
   "source": [
    "# with conda\n",
    "conda env create -n snail_env \\\n",
    "    python=3.11 geopandas shapely rasterio python-igraph\n",
    "conda activate snail_env\n",
    "\n",
    "# with micromamba\n",
    "micromamba create -n snail-env \\\n",
    "    python=3.11 geopandas shapely rasterio python-igraph -c conda-forge\n",
    "micromamba activate snail-env"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The previous step will setup a conda or micromamba virtual environment with some packages and activate it.\n",
    "Next, install the *snail* package, it will bring with intself a bunch of dependencies to run the tutorials. \n",
    "\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "vscode": {
     "languageId": "shellscript"
    }
   },
   "outputs": [],
   "source": [
    "pip install nismod-snail"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Running the tutorials\n",
    "\n",
    "At this point, if you type `jupyter notebook` in the terminal and execute, a jupyter server will start and open a browser window with the repository containing the tutorials.\n",
    "\n",
    "#### Using VSCode\n",
    "\n",
    "If you are using VSCode, you might run into issues with micromamba as it does not recognise it by default, it will look for `venv` and `conda` virtual environments only. \n",
    "Open VSCode from inside the tutorials folder and open the first tutorial.\n",
    "<!-- In the searchbar that opens once you do this, you will  -->\n",
    "Now back to the terminal, execute the following command: "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "vscode": {
     "languageId": "shellscript"
    }
   },
   "outputs": [],
   "source": [
    "# on MAC\n",
    "which python\n",
    "\n",
    "# on Windows\n",
    "where python"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    " Now on the upper right corner of VSCode choose *Select Kernel*. When the options show up, go for *Select another kernel*.\n",
    " In the searchbar, paste the output of the terminal command, it should be something like: `USERNAME/micromamba/envs/snail-env/bin/python`"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "After that, VSCode will connect to the virtual environment you created earlier and you will be all set up !"
   ]
  }
 ],
 "metadata": {
  "language_info": {
   "name": "python"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}