Update conda.md

book/resources/conda.md

@@ -9,9 +9,13 @@ Friedrich Knuth and David Shean
   * https://docs.conda.io/projects/conda/en/latest/user-guide/index.html
   * https://docs.conda.io/projects/conda/en/latest/user-guide/concepts/
 
+### What is mamba?
+* https://mamba.readthedocs.io/en/latest/
+>a Python-based CLI conceived as a drop-in replacement for conda, offering higher speed and more reliable environment solutions
+
 ## Basic terminology
 #### package manager 
-_helps you download and organize open-source software on your machine (conda is cross-platform, which is one of the reasons it is so great. There are also OS-specific package managers, like homebrew (MacOS), apt-get (Linux), chocolatey (Windows) etc...)_
+_helps you download and organize open-source software on your machine (conda is cross-platform, which is one of the reasons it is so great. There are also OS-specific package managers, like homebrew (MacOS), apt-get (Linux), chocolatey (Windows) etc...). The package manager installs/manages packages (Python, command-line utilities, etc.), resolves their dependencies, and creates a functional custom Python environment._
 
 #### package
 _includes Python module(s), binary executable machine instructions (e.g., libraries compiled from NumPy C/C++ source code), metadata, etc._  
@@ -38,10 +42,8 @@ But I already have Python installed on my computer, why do I need this?
 *Note: If you have an existing conda install, you can skip this section and go straight to 'Create the GDA environment' section.  You may want to `conda update conda` if it's been a while since you installed.*
 
 Downloand and install the Python 3 version of [Miniconda](https://docs.conda.io/en/latest/miniconda.html) or [Anaconda](https://www.anaconda.com/distribution/). 
-
-Miniconda gives you just the conda package manager, while Anaconda provides the same package manager along with a large set of common packages.  While Anaconda may be easiest for beginners, we recommend miniconda for a more a lighter, faster, more customizable installation that requires less disk space.
-
-The package manager is what enables you to pull together various Python packages, resolve their dependencies, and create a functional custom Python environment. 
+* Miniconda gives you just the conda package manager, while Anaconda provides the same package manager along with a large set of common Python packages.
+* While Anaconda may be easiest for beginners, we recommend miniconda for a more a lighter, faster, more customizable installation that requires less disk space.
 
 Follow the instructions for installation: https://conda.io/projects/conda/en/latest/user-guide/install/index.html
 
@@ -53,34 +55,40 @@ Run the following to see various useful info about your install:
 Update to latest version of conda:
 `conda update conda`
 
+Install mamba:
+`conda install mamba`
+
 ## Create the GDA environment
 
-The environment used for the GDA course is in `uwgda-image-2021` repo in the UW-GDA Github organization:  
-https://github.com/UW-GDA/uwgda-image-2021/blob/main/environment.yml
+The environment used for the GDA course is in [uwgda-image-2022 repo](https://github.com/UW-GDA/uwgda-image-2022) in the UW-GDA Github organization:  
+https://github.com/UW-GDA/uwgda-image-2022/blob/main/environment.yml
 
 This configuration file contains all of the packages/versions we used on the Jupyterhub this quarter.
 
 1. Download (or copy the content of) this text file to your computer. On Github, you can right-click on the "RAW" button in your browser, and "save link as" to save locally.
     * View it with a text editor and note that it is basically just a list of package names (many you will recognize from this course).
-    * The first line `uwgda2021` defines the conda environment name.
-    * Note that we may have "pinned" version numbers for some packages (e.g., `- python=3.8`). This is not necessary, but is a best practice for our classroom situation.  Because many of these projects are under active development, new versions of many these packages would likely be released during the quarter, potentially changing/breaking some functionality. For your personal setup, you may want to remove the version numbers, so conda will automatically fetch the latest version of each package, and you can access latest features (but no guarantee that the GDA notebooks will run out of the box).
-1. Create the `uwgda2021` conda environment on your local machine
+    * The first line `uwgda2022` defines the conda environment name.
+    * Note that we may have "pinned" version numbers for some packages (e.g., `- python=3.9`).
+      * This is not necessary, but is a best practice for our classroom situation. Because many of these projects are under active development, new versions are released during the quarter, potentially changing/breaking some functionality. 
+      * For your personal setup, you can remove the version numbers, so conda will automatically fetch the latest version of each package, and you can access latest features (but no guarantee that the existing GDA notebooks will run out of the box).
+1. Create the `uwgda2022` conda environment on your local machine
     * Open a terminal on your machine, and run the following: `conda env create -f environment.yml`
     * This will take a few minutes to download and unzip all of the packages.
-1. Activate the `uwgda2021` environment, 
-    * `conda activate uwgda2021`
-    * You should see a slightly different terminal prompt display with `(uwgda2021)`
+    * If this fails, please post the error message to the #it_help Slack channel
+    * You can try installing with mamba: `mamba env create -f environment.yml`
+1. Activate the `uwgda2022` environment, 
+    * `conda activate uwgda2022`
+    * You should see a slightly different terminal prompt display with `(uwgda2022)`
     * Now when you type `python` it should run the python executable in the new conda environment, and all of the GDA packages will be available!  Try it, run `python`, then `import geopandas` (shouldn't see any errors), then `exit()`
 1. Configure the Jupyterlab extensions
-    * Copy the multi-line `jupyter labextension` command here: https://github.com/UW-GDA/uwgda-image-2021/blob/main/postBuild
-    * Paste in your terminal and run (will take few minutes)
-    * Can verify install was successful with `jupyter labextension list` (should see "enabled OK" for at least 6 extensions)
+    * Latest version of these extentions don't require additional configuration after install.
+    * Can verify everything with `jupyter labextension list` (should see "enabled OK" for at least 6 extensions)
 
-Note that once this setup is complete, you only need to `conda activate uwgda2021` when you start a new terminal (including after you restart your computer).
+Note that once this setup is complete, you will need to `conda activate uwgda2022` when you start a new terminal (including after you restart your computer), but you don't need to recreate the environment.  You can consider adding `conda activate uwgda2022` to your `~/.bashrc` or '~/.bash_profile` files.
 
 ## Starting Jupyter lab
 
-Once you have created the environment, activated the environment, and installed Jupyter lab extensions, open a terminal and navigate to the local directory where you store your notebooks/code (either lab/project repos from class that you `git clone` to local directory, or location where you will create new notebooks locally).  This could be something like `~/Documents/gda_course_2021/`.
+Once you have created the environment, activated the environment, and installed Jupyter lab extensions, open a terminal and navigate to the local directory where you store your notebooks/code (either lab/project repos from class that you `git clone` to local directory, or location where you will create new notebooks locally).  This could be something like `~/Documents/gda_course_2022/`.
 
 Then from the terminal, start Jupyter lab with the command: `jupyter lab`
 
@@ -92,6 +100,8 @@ To end your jupyter lab session, you can close the tab, but the Jupyter lab serv
 
 ## Removing or starting over
 
+See https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html
+
 Most of the time, you should be able to `conda update`, or manage environments to add/remove packages.
 
 One of the best things about conda is the fact that it creates isolated environments, separate from your system Python. So if you no longer need it, or you have unresolvable issues, you can always just delete and start over with a fresh install.