{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Adding environments in Jupyter Hub\n",
    "\n",
    "To run the cells in this Jupyter Notebook, just click on the cell you want to run and press **shift-enter**."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Context for this notebook\n",
    "\n",
    "If you connected to VCDAT via NERSC, ACME1, Crunchy or a local area network, your *JupyterLab* experience is actually a *JupyterHub* experience though the two interfaces look almost the same. (JupyterHub is for multi-user situations, JupyterLab is for single-user situations like running from your own computer.) The environments available to you by default via JupyterHub are more limited than the environments you can set up on your own computer. This notebook shows you how to add an environment via JupyterHub since you might want to use an environment that is not automatically provided. \n",
    "\n",
    "If you launched JupyterLab from your own computer, JupyterLab can see and use any environments you've created on your computer. If you need a different environment than what already exists, just create that environment in a command line window, relaunch JupyterLab and those environments should be available. (Note: you can launch JupyterLab using one enviornment, like jupyter-vcdat which has the code to run JupyterLab, and then use a different environment within JupyterLab as the notebook below describes.)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Adding and Using Conda Environments\n",
    "You have access to conda as a software management tool.\n",
    "\n",
    "**NOTE: Anything installed in the [base] conda environment will not persist between sessions.**\n",
    "\n",
    "As an example, let's create a new environment called \"test\" based on python 3.6.\n",
    "\n",
    "**NOTE: For a new conda environment to be available in a Jupyter Lab you must install the \"ipykernel\" package.**"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {
    "scrolled": true
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Collecting package metadata: done\n",
      "Solving environment: done\n",
      "\n",
      "## Package Plan ##\n",
      "\n",
      "  environment location: /Users/davis278/miniconda3/envs/test\n",
      "\n",
      "  added / updated specs:\n",
      "    - ipykernel\n",
      "    - python=3.6\n",
      "\n",
      "\n",
      "The following NEW packages will be INSTALLED:\n",
      "\n",
      "  appnope            conda-forge/osx-64::appnope-0.1.0-py36_1000\n",
      "  backcall           conda-forge/noarch::backcall-0.1.0-py_0\n",
      "  ca-certificates    conda-forge/osx-64::ca-certificates-2019.3.9-hecc5488_0\n",
      "  certifi            conda-forge/osx-64::certifi-2019.3.9-py36_0\n",
      "  decorator          conda-forge/noarch::decorator-4.4.0-py_0\n",
      "  ipykernel          conda-forge/osx-64::ipykernel-5.1.1-py36h24bf2e0_0\n",
      "  ipython            conda-forge/osx-64::ipython-7.5.0-py36h24bf2e0_0\n",
      "  ipython_genutils   conda-forge/noarch::ipython_genutils-0.2.0-py_1\n",
      "  jedi               conda-forge/osx-64::jedi-0.13.3-py36_0\n",
      "  jupyter_client     conda-forge/noarch::jupyter_client-5.2.4-py_3\n",
      "  jupyter_core       conda-forge/noarch::jupyter_core-4.4.0-py_0\n",
      "  libcxx             conda-forge/osx-64::libcxx-8.0.0-2\n",
      "  libcxxabi          conda-forge/osx-64::libcxxabi-8.0.0-2\n",
      "  libffi             conda-forge/osx-64::libffi-3.2.1-h6de7cb9_1006\n",
      "  libsodium          conda-forge/osx-64::libsodium-1.0.16-h1de35cc_1001\n",
      "  ncurses            conda-forge/osx-64::ncurses-6.1-h0a44026_1002\n",
      "  openssl            conda-forge/osx-64::openssl-1.1.1b-h01d97ff_2\n",
      "  parso              conda-forge/noarch::parso-0.4.0-py_0\n",
      "  pexpect            conda-forge/osx-64::pexpect-4.7.0-py36_0\n",
      "  pickleshare        conda-forge/osx-64::pickleshare-0.7.5-py36_1000\n",
      "  pip                conda-forge/osx-64::pip-19.1.1-py36_0\n",
      "  prompt_toolkit     conda-forge/noarch::prompt_toolkit-2.0.9-py_0\n",
      "  ptyprocess         conda-forge/noarch::ptyprocess-0.6.0-py_1001\n",
      "  pygments           conda-forge/noarch::pygments-2.4.2-py_0\n",
      "  python             conda-forge/osx-64::python-3.6.7-h8dc6b48_1004\n",
      "  python-dateutil    conda-forge/noarch::python-dateutil-2.8.0-py_0\n",
      "  pyzmq              conda-forge/osx-64::pyzmq-18.0.1-py36h2d07e9b_1\n",
      "  readline           conda-forge/osx-64::readline-7.0-hcfe32e1_1001\n",
      "  setuptools         conda-forge/osx-64::setuptools-41.0.1-py36_0\n",
      "  six                conda-forge/osx-64::six-1.12.0-py36_1000\n",
      "  sqlite             conda-forge/osx-64::sqlite-3.28.0-h9721f7c_0\n",
      "  tk                 conda-forge/osx-64::tk-8.6.9-h2573ce8_1002\n",
      "  tornado            conda-forge/osx-64::tornado-6.0.2-py36h01d97ff_0\n",
      "  traitlets          conda-forge/osx-64::traitlets-4.3.2-py36_1000\n",
      "  wcwidth            conda-forge/noarch::wcwidth-0.1.7-py_1\n",
      "  wheel              conda-forge/osx-64::wheel-0.33.4-py36_0\n",
      "  xz                 conda-forge/osx-64::xz-5.2.4-h1de35cc_1001\n",
      "  zeromq             conda-forge/osx-64::zeromq-4.3.1-h0a44026_1000\n",
      "  zlib               conda-forge/osx-64::zlib-1.2.11-h1de35cc_1004\n",
      "\n",
      "\n",
      "Preparing transaction: done\n",
      "Verifying transaction: done\n",
      "Executing transaction: done\n",
      "#\n",
      "# To activate this environment, use\n",
      "#\n",
      "#     $ conda activate test\n",
      "#\n",
      "# To deactivate an active environment, use\n",
      "#\n",
      "#     $ conda deactivate\n",
      "\n"
     ]
    }
   ],
   "source": [
    "!conda create -n test -c conda-forge -y python=3.6 ipykernel"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**NOTE: You will need to activate the conda environment through a terminal instance.**\n",
    "\n",
    "To use the new conda environment in a Jupyter Notebook you have two options:\n",
    "1. Choose the Hub menu at the top of this page (assuming you have connected to a multi-user computer like ACME1, Crunchy or NERSC's Cori computer - the single-user JupyterLab interface does not have the \"Hub\" menu) and click \"Control Panel\". On the new page you'll need to click \"Stop My Server\" and then \"Start My Server\" OR,\n",
    "2. Run the following python script to load the new environment. (This line of code works regardless of whether you are accessing VCDAT via JupyterHub or JupyterLab, i.e. it will work on your computer as well as on multi-user computers.)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [],
   "source": [
    "!python -c \"from nb_conda_kernels import CondaKernelSpecManager; m = CondaKernelSpecManager(); m.find_kernel_specs()\""
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In the upper right-hand corner, you can click the button similar to the one shown below to select the new \"test\" kernel."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![kernel](https://raw.githubusercontent.com/esgf-nimbus/getting_started/master/img/kernel.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now select the \"conda env:test\" kernel."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![selection](https://raw.githubusercontent.com/esgf-nimbus/getting_started/master/img/kernel_selection.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Using the Jupyter Lab terminal you can activate the conda environment and install additional software.\n",
    "\n",
    "```bash\n",
    "conda activate test\n",
    "\n",
    "conda install -c conda-forge vcs\n",
    "```\n",
    "\n",
    "You can also do this from within a Notebook.\n",
    "\n",
    "**NOTE: This will run everytime the cell runs.**"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Collecting package metadata: done\n",
      "Solving environment: done\n",
      "\n",
      "## Package Plan ##\n",
      "\n",
      "  environment location: /Users/davis278/miniconda3/envs/test\n",
      "\n",
      "  added / updated specs:\n",
      "    - vcs\n",
      "\n",
      "\n",
      "The following NEW packages will be INSTALLED:\n",
      "\n",
      "  asn1crypto         conda-forge/osx-64::asn1crypto-0.24.0-py36_1003\n",
      "  attrs              conda-forge/noarch::attrs-19.1.0-py_0\n",
      "  blas               conda-forge/osx-64::blas-1.1-openblas\n",
      "  bzip2              conda-forge/osx-64::bzip2-1.0.6-h1de35cc_1002\n",
      "  cdat_info          cdat/label/v81/noarch::cdat_info-8.1.1-py_0\n",
      "  cdms2              cdat/label/v81/osx-64::cdms2-3.1.2-py36hcfef303_7\n",
      "  cdtime             conda-forge/osx-64::cdtime-3.1.2-py36hcfef303_1\n",
      "  cdutil             cdat/label/v81/noarch::cdutil-8.1-py_1\n",
      "  cffi               conda-forge/osx-64::cffi-1.12.3-py36hccf1714_0\n",
      "  chardet            conda-forge/osx-64::chardet-3.0.4-py36_1003\n",
      "  cryptography       conda-forge/osx-64::cryptography-2.7-py36h212c5bf_0\n",
      "  curl               conda-forge/osx-64::curl-7.64.1-h22ea746_0\n",
      "  distarray          conda-forge/noarch::distarray-2.12.2-py_1\n",
      "  dv3d               cdat/label/v81/noarch::dv3d-8.1-py_0\n",
      "  esmf               conda-forge/osx-64::esmf-7.1.0-h5f93626_1004\n",
      "  esmpy              conda-forge/osx-64::esmpy-7.1.0-py36h24bf2e0_3\n",
      "  expat              conda-forge/osx-64::expat-2.2.5-h0a44026_1002\n",
      "  ffmpeg             conda-forge/osx-64::ffmpeg-4.1.3-h5c2b479_0\n",
      "  freetype           conda-forge/osx-64::freetype-2.10.0-h24853df_0\n",
      "  future             conda-forge/osx-64::future-0.17.1-py36_1000\n",
      "  g2clib             conda-forge/osx-64::g2clib-1.6.0-h4e57d6e_9\n",
      "  genutil            conda-forge/osx-64::genutil-8.1.1-py36h917ab60_0\n",
      "  gettext            conda-forge/osx-64::gettext-0.19.8.1-h46ab8bc_1002\n",
      "  ghostscript        conda-forge/osx-64::ghostscript-9.22-h0a44026_1001\n",
      "  gmp                conda-forge/osx-64::gmp-6.1.2-h0a44026_1000\n",
      "  gnutls             conda-forge/osx-64::gnutls-3.6.5-h53004b3_1002\n",
      "  hdf4               conda-forge/osx-64::hdf4-4.2.13-hf3c6af0_1002\n",
      "  hdf5               conda-forge/osx-64::hdf5-1.10.4-nompi_h0cbb7df_1106\n",
      "  idna               conda-forge/osx-64::idna-2.8-py36_1000\n",
      "  jasper             conda-forge/osx-64::jasper-1.900.1-h636a363_1006\n",
      "  jpeg               conda-forge/osx-64::jpeg-9c-h1de35cc_1001\n",
      "  jsonschema         conda-forge/osx-64::jsonschema-3.0.1-py36_0\n",
      "  krb5               conda-forge/osx-64::krb5-1.16.3-hcfa6398_1001\n",
      "  lame               conda-forge/osx-64::lame-3.100-h1de35cc_1001\n",
      "  libcdms            cdat/label/v81/osx-64::libcdms-3.1.2-hba43199_1000\n",
      "  libcf              conda-forge/osx-64::libcf-1.0.2-py36h5af8170_1007\n",
      "  libcurl            conda-forge/osx-64::libcurl-7.64.1-h16faf7d_0\n",
      "  libdrs             conda-forge/osx-64::libdrs-3.1.2-h4160185_2\n",
      "  libdrs_f           conda-forge/osx-64::libdrs_f-3.1.2-hcc6f5f9_2\n",
      "  libedit            conda-forge/osx-64::libedit-3.1.20170329-hcfe32e1_1001\n",
      "  libgfortran        conda-forge/osx-64::libgfortran-3.0.1-0\n",
      "  libiconv           conda-forge/osx-64::libiconv-1.15-h01d97ff_1005\n",
      "  libnetcdf          conda-forge/osx-64::libnetcdf-4.6.2-h6b88ef6_1001\n",
      "  libpng             conda-forge/osx-64::libpng-1.6.37-h2573ce8_0\n",
      "  libssh2            conda-forge/osx-64::libssh2-1.8.2-hcdc9a53_2\n",
      "  libtiff            conda-forge/osx-64::libtiff-4.0.10-hd08fb8f_1003\n",
      "  libuuid            conda-forge/osx-64::libuuid-2.32.1-h1de35cc_1000\n",
      "  lz4-c              conda-forge/osx-64::lz4-c-1.8.3-h6de7cb9_1001\n",
      "  mpi                conda-forge/osx-64::mpi-1.0-mpich\n",
      "  mpich              conda-forge/osx-64::mpich-3.2.1-ha90c164_1009\n",
      "  nbformat           conda-forge/noarch::nbformat-4.4.0-py_1\n",
      "  netcdf-fortran     conda-forge/osx-64::netcdf-fortran-4.4.5-h5ce9b53_1000\n",
      "  nettle             conda-forge/osx-64::nettle-3.4.1-h3efe00b_1002\n",
      "  numpy              conda-forge/osx-64::numpy-1.16.2-py36_blas_openblash486cb9f_0\n",
      "  openblas           conda-forge/osx-64::openblas-0.3.3-hdc02c5d_1001\n",
      "  openh264           conda-forge/osx-64::openh264-1.8.0-hd9629dc_1000\n",
      "  pycparser          conda-forge/osx-64::pycparser-2.19-py36_1\n",
      "  pyopenssl          conda-forge/osx-64::pyopenssl-19.0.0-py36_0\n",
      "  pyrsistent         conda-forge/osx-64::pyrsistent-0.15.2-py36h01d97ff_0\n",
      "  pysocks            conda-forge/osx-64::pysocks-1.7.0-py36_0\n",
      "  requests           conda-forge/osx-64::requests-2.22.0-py36_0\n",
      "  udunits2           conda-forge/osx-64::udunits2-2.2.27.6-h776b7f1_1001\n",
      "  urllib3            conda-forge/osx-64::urllib3-1.24.3-py36_0\n",
      "  vcs                cdat/label/v81/noarch::vcs-8.1-py_0\n",
      "  vtk-cdat           cdat/label/v81/osx-64::vtk-cdat-8.2.0rc2.8.1-py36h258435d_0\n",
      "  x264               conda-forge/osx-64::x264-1!152.20180806-h1de35cc_0\n",
      "  zstd               conda-forge/osx-64::zstd-1.4.0-ha9f0a20_0\n",
      "\n",
      "\n",
      "Preparing transaction: done\n",
      "Verifying transaction: done\n",
      "Executing transaction: done\n"
     ]
    }
   ],
   "source": [
    "!conda install -n test -c cdat/label/v81 -c conda-forge -y vcs"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "As a comparision for the next step, let's list all the environments available using the following command. We can see that the \"test\" environment exists."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "# conda environments:\n",
      "#\n",
      "base                     /Users/davis278/miniconda3\n",
      "cdat81                   /Users/davis278/miniconda3/envs/cdat81\n",
      "cdat_nightly             /Users/davis278/miniconda3/envs/cdat_nightly\n",
      "e3sm                     /Users/davis278/miniconda3/envs/e3sm\n",
      "globus                   /Users/davis278/miniconda3/envs/globus\n",
      "jekyll                   /Users/davis278/miniconda3/envs/jekyll\n",
      "jupyter-vcdat            /Users/davis278/miniconda3/envs/jupyter-vcdat\n",
      "rtd                      /Users/davis278/miniconda3/envs/rtd\n",
      "test                  *  /Users/davis278/miniconda3/envs/test\n",
      "vcdat                    /Users/davis278/miniconda3/envs/vcdat\n",
      "\n"
     ]
    }
   ],
   "source": [
    "!conda env list"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "\n",
    "Finally you can remove the environment but first **if you activated the environment in this notebook you must choose another environment**, e.g. \"root\", by changing the kernel either as you did before using the button in the upper right-hand corner or by clicking on the \"Kernel\" menu / tab in the upper left and choosing \"Change Kernel\".\n",
    "\n",
    "After you have changed the kernel to something other than \"test\" you can delete the \"test\" environment with the following line of code."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "\n",
      "Remove all packages in environment /Users/davis278/miniconda3/envs/test:\n",
      "\n"
     ]
    }
   ],
   "source": [
    "!conda env remove -n test -y"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To verify that the \"test\" environment was removed, run the following bash command again. (The ! is needed for all but the most common bash commands to run within a Jupyter notebook)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "# conda environments:\n",
      "#\n",
      "base                     /Users/davis278/miniconda3\n",
      "cdat81                   /Users/davis278/miniconda3/envs/cdat81\n",
      "cdat_nightly             /Users/davis278/miniconda3/envs/cdat_nightly\n",
      "e3sm                     /Users/davis278/miniconda3/envs/e3sm\n",
      "globus                   /Users/davis278/miniconda3/envs/globus\n",
      "jekyll                   /Users/davis278/miniconda3/envs/jekyll\n",
      "jupyter-vcdat         *  /Users/davis278/miniconda3/envs/jupyter-vcdat\n",
      "rtd                      /Users/davis278/miniconda3/envs/rtd\n",
      "vcdat                    /Users/davis278/miniconda3/envs/vcdat\n",
      "\n"
     ]
    }
   ],
   "source": [
    "!conda env list"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The \"test\" environment has been removed."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python [conda env:jupyter-vcdat] *",
   "language": "python",
   "name": "conda-env-jupyter-vcdat-py"
  },
  "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.6.7"
  },
  "selected_variables": [],
  "toc": {
   "base_numbering": 1,
   "nav_menu": {},
   "number_sections": false,
   "sideBar": false,
   "skip_h1_title": true,
   "title_cell": "Table of Contents",
   "title_sidebar": "Contents",
   "toc_cell": false,
   "toc_position": {},
   "toc_section_display": true,
   "toc_window_display": false
  },
  "vcdat_file_path": "",
  "vcdat_loaded_variables": [],
  "vcdat_variable_info": {
   "soil_moisture": {
    "name": "sm",
    "source": "soil_moisture/1983/ESACCI-SOILMOISTURE-L3S-SSMV-COMBINED-19830106000000-fv04.4.nc"
   }
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}