Scripts to Create Conda Environments in JupyterHub

This resource contains the following bash scripts which can be used by the user in any of the JupterHub instances accessible via the \"Open with\" functionality of HydroShare to create conda environment to run AORC related notebooks. In order to run any of the listed bash script files in JupyterHub, first make the file executable using the JupyterHub terminal. Here is an example:

chmod +x setup_aorc_conda_env_cuahsi_jh.sh

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

./setup_aorc_conda_env_cuahsi_jh.sh

After executing the script as above, it will create a new conda environment called 'aorc'. It will also register this new conda environment as a new Jupyter kernel with name 'Python [conda env:.conda-aorc]'. In order for any of the AORC related notebooks to use this kernel you have to first shut down all kernels and then use the option 'Change Kernel\" to select this new kernel.

- setup_aorc_conda_env_cuahsi_jh.sh (This script should be used in CUAHSI JupyterHub to create a new conda environment called 'aorc')

- setup_aorc_conda_env_cybergis_jh.sh (This script should be used in CyberGIS Jupyter for Water) to create a new conda environment called 'aorc')

- 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 script files use this file to install the python modules specified in this yml file.

- delete_aorc_conda_env_cuahsi_jh,sh (This script can be run to delete the conda env 'aorc' in CUAHSI JupyterHub)

- delete_aorc_conda_env_cybergis_jh,sh (This script can be run to delete the conda env 'aorc' in CyberGIS Jupyter for Water)

- setup_aorc_conda_env_2i2c_jh_uv.sh (This script should be used in 2i2c JupyterHub to create a new conda environment called 'aorc')

- environment-2i2c.yml (This file is used in the above script that creates the aorc conda env in 2i2c. This environment file has few python modules for conda installation)

- requirements-2i2c.txt (This file is used in the above script that creates the aorc conda env in 2i2c to pip install most of the python modules needed for AORC notebooks.

- delete_aorc_conda_env_2i2c_jh,sh (This script can be run to delete the conda env 'aorc' in 2i2c JupyterHub)

- 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 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. The following commands are applicable to CUAHSI and CyberGIS JH instances.

- 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

Update aorc environment in 2i2c:
If you have updated the environments-2i2c.yml, run
- conda env update -f environment-2i2c.yml

If you have updated the requirements-2i2c.txt file, run
- pip install -r requirements-2i2c.txt

If you just want to install fe new modules or upgrade existing modules without updating environment or requirements file, then run
conda install <module-1-name> <module-2-name>
OR
pip install <module-1-name> <module-2-name>

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

本资源包含以下Bash脚本，用户可通过HydroShare的"Open with"功能访问的任意JupyterHub实例中使用，以创建可运行AORC相关Notebook的Conda环境。若需在JupyterHub中运行所列Bash脚本，需先通过JupyterHub终端将脚本设为可执行文件，示例如下：
bash
chmod +x setup_aorc_conda_env_cuahsi_jh.sh

随后即可通过命令行执行上述脚本：
bash
./setup_aorc_conda_env_cuahsi_jh.sh

执行该脚本后，将创建名为`aorc`的全新Conda环境，并将该环境注册为名为`Python [conda env:.conda-aorc]`的Jupyter内核。若需让AORC相关Notebook使用此内核，需先关闭所有内核，再通过「更改内核」选项选择该新内核。

### 资源文件说明
1. `setup_aorc_conda_env_cuahsi_jh.sh`：该脚本适用于CUAHSI JupyterHub，用于创建名为`aorc`的Conda环境。
2. `setup_aorc_conda_env_cybergis_jh.sh`：该脚本适用于CyberGIS Water Jupyter，用于创建名为`aorc`的Conda环境。
3. `environment.yml`：该文件包含运行AORC Notebook所需的Python模块，功能类似配合`pip install`使用的`requirements.txt`文件。前述Bash脚本将通过该文件安装指定的Python模块。
4. `delete_aorc_conda_env_cuahsi_jh.sh`：该脚本可用于在CUAHSI JupyterHub中删除名为`aorc`的Conda环境。
5. `delete_aorc_conda_env_cybergis_jh.sh`：该脚本可用于在CyberGIS Water Jupyter中删除名为`aorc`的Conda环境。
6. `setup_aorc_conda_env_2i2c_jh_uv.sh`：该脚本适用于2i2c JupyterHub，用于创建名为`aorc`的Conda环境。
7. `environment-2i2c.yml`：该文件用于2i2c平台上创建`aorc`Conda环境的脚本中，该环境文件包含少量用于Conda安装的Python模块。
8. `requirements-2i2c.txt`：该文件用于2i2c平台上创建`aorc`Conda环境的脚本中，通过`pip install`安装AORC Notebook所需的绝大多数Python模块。
9. `delete_aorc_conda_env_2i2c_jh.sh`：该脚本可用于在2i2c JupyterHub中删除名为`aorc`的Conda环境。
10. `sample_commands_to_create_conda_env_jh.md`：该文件包含无需借助Bash脚本即可创建全新Conda环境的示例命令。

### 环境更新指南
#### 常规更新（适用于CUAHSI与CyberGIS JupyterHub实例）
此处的更新指安装额外Python模块，或升级`aorc`Conda环境中已安装模块的版本。操作步骤如下：
1. 修改`environment.yml`文件，添加新模块或更新其中现有模块的版本。
2. 在JupyterHub实例中打开终端，执行以下两条命令：
bash
conda activate aorc
mamba env update -f environment.yml

#### 2i2c平台专属更新方法
- 若已修改`environment-2i2c.yml`，执行命令：`conda env update -f environment-2i2c.yml`
- 若已修改`requirements-2i2c.txt`，执行命令：`pip install -r requirements-2i2c.txt`
- 若仅需安装新模块或升级现有模块，无需修改环境或需求文件，可直接执行：
bash
conda install <模块1名称> <模块2名称>

或
bash
pip install <模块1名称> <模块2名称>

> 注意：如需更新环境，优先通过修改环境或需求文件进行操作，这有助于提升实验的可复现性。