Scripts to Create Conda Environments in JupyterHub

This resource contains the following Bash script which can be used by the user in any of the JupyterHub instances accessible via the \"Open with\" functionality of HydroShare to create a custom Conda environment to run AORC related notebooks. In order to run this Bash script files in JupyterHub, first make the file executable using the JupyterHub terminal as shown below:

chmod +x setup_aorc_jupyterhub_conda_env.sh

Then the above script can be executed from the command line as follows:

./setup_aorc_jupyterhub_conda_env.sh

NOTE: The notebook (CondaEnvironmentSetup.ipynb) available in this resource also can be used for creating the 'aorc' Conda environment if you prefer not to use the terminal.

After executing the script, it will create a new Conda environment called 'aorc'. It will also register this new Conda environment as a new Jupyter kernel. Though the script creates a new kernel and names it as 'Python3 (AORC)'', the conda environment by default also registers the 'aorc' environment as a new kernel with the name of 'Python [conda env:aorc]' or 'Python [conda env:.conda-aorc]'. In order for any of the AORC related notebooks to use this new kernel you have to first shut down all kernels and then use the option 'Change Kernel\" to select this new kernel. Depending on the JupyterHub instance that you are using, you have to select a specific kernel name as described below:

- 2i2c JupyterHub: Select kernel 'Python [conda env:.conda-aorc]'. In the list of kernels, you may see 'Python3 (AORC)'. Don't select this kernel!
- CyberGIS JupyterHub: Select kernel 'Python3 (AORC)'
- CUAHSI JupyterHub: Select kernel 'Python [conda env:aorc]'. In the list of kernels, you may see 'Python3 (AORC)'. Don't select this kernel!

This resource also contain this yml file:

- environment.yml (This file contains the python modules needed to run the AORC notebooks - similar to requirements.txt file used with pip install). The above Bash script file uses this yml file to install the python modules listed in that file.

- delete_aorc_jupyterhub_conda_env.sh (This script can be run to delete the 'aorc' Conda env. Note this file needs to be first set as an executable file - chmod +x delete_aorc_jupyterhub_conda_env.sh)

- sample_commands_to_create_conda_env_jh.md (This file contains example commands to create a new Conda environment - without using a bash script)

How to use the new kernel created by the script (see above)?
If you just created the new aorc Conda environment, shut down all kernels. Open the notebook that needs to use the aorc Conda environment. Change the kernel for the notebook to aorc kernel. (for the exact name of the kernel see above).

How to update the aorc Conda environment after it has been created?
Update here means installing additional python modules or upgrading to a newer version of any modules that is already installed in the aorc conda environment.

- Update the environment.yml file by adding new modules or updating the version of any modules in that file.

- In the JupyterHub instance, use a terminal and run the following 2 commands:

- conda activate aorc
- mamba env update -f environment.yml

If you just want to install few new modules or upgrade existing modules without updating environment, then run (after activating the aorc env):

conda install <module-1-name> <module-2-name>
OR
pip install <module-1-name> <module-2-name>

NOTE: It is better to update the environment yml file when there is a need to update the environment as it helps reproducibility.

本资源包含以下Bash脚本（Bash script），用户可在通过HydroShare（HydroShare）的"Open with"功能访问的任意JupyterHub（JupyterHub）实例中使用该脚本，以创建自定义Conda环境（Conda）来运行与AORC相关的Notebook（Notebook）。若需在JupyterHub中运行此Bash脚本，首先需通过JupyterHub终端将该文件设为可执行，命令如下：
chmod +x setup_aorc_jupyterhub_conda_env.sh
随后即可通过命令行执行上述脚本，命令如下：
./setup_aorc_jupyterhub_conda_env.sh

注意：若您不愿使用终端，本资源中附带的Notebook（CondaEnvironmentSetup.ipynb）也可用于创建名为"aorc"的Conda环境。

执行该脚本后，将创建一个名为"aorc"的全新Conda环境，同时会将该环境注册为新的Jupyter内核（Jupyter kernel）。尽管脚本会创建一个名为"Python3 (AORC)"的内核，但默认情况下，该Conda环境还会以"Python [conda env:aorc]"或"Python [conda env:.conda-aorc]"的名称注册为新内核。若要让任意与AORC相关的Notebook使用此新内核，需先关闭所有内核，再通过"Change Kernel"选项选择该新内核。根据您所使用的JupyterHub实例，需按以下说明选择特定的内核名称：
- 2i2c JupyterHub：选择内核"Python [conda env:.conda-aorc]"。在内核列表中可能会看到"Python3 (AORC)"，请勿选择该内核！
- CyberGIS JupyterHub：选择内核"Python3 (AORC)"
- CUAHSI JupyterHub：选择内核"Python [conda env:aorc]"。在内核列表中可能会看到"Python3 (AORC)"，请勿选择该内核！

本资源还包含以下文件：
1. environment.yml：该文件包含运行AORC相关Notebook所需的Python模块，类似pip安装流程中使用的requirements.txt文件。上述Bash脚本即通过该yml文件安装其中列出的Python模块。
2. delete_aorc_jupyterhub_conda_env.sh：运行该脚本可删除"aorc"Conda环境。请注意，需先通过`chmod +x delete_aorc_jupyterhub_conda_env.sh`命令将该文件设为可执行。
3. sample_commands_to_create_conda_env_jh.md：该文件包含无需使用Bash脚本即可创建新Conda环境的示例命令。

### 如何使用脚本创建的新内核？
若您刚完成新的aorc Conda环境创建，请先关闭所有内核，打开需要使用aorc Conda环境的Notebook，将该Notebook的内核切换为aorc内核（内核的准确名称请参见上文说明）。

### 如何在aorc Conda环境创建完成后对其进行更新？
此处的更新指安装额外的Python模块，或升级该环境中已安装的任意模块至更新版本。
- 编辑environment.yml文件，添加新模块或更新其中任意模块的版本。
- 在JupyterHub实例中，通过终端运行以下两条命令：
conda activate aorc
mamba env update -f environment.yml
若仅需安装少量新模块或升级现有模块，无需更新environment.yml文件，则可在激活aorc环境后运行以下命令：
conda install <模块1名称> <模块2名称>
或
pip install <模块1名称> <模块2名称>

注意：如需更新环境，建议通过修改environment.yml文件进行操作，这有助于保证实验的可复现性。