Overview

This repository bootstraps a reproducible Jupyter kernel that includes a persistent Python environment with a core set of geospatial packages, and it's been specifically developed to work in most JupyterHub deployments.

Pre-Installed Packages:

• Python 3.11.9
• GDAL 3.9.2
• PROJ 9.4.1
• GEOS 3.12.2
• numpy 2.1.1py
• geopandas 1.0.1
• matplotlib 3.9.2
• ipyleaflet 0.19.2
• pandas 2.2.2
• pyproj 3.6.1
• rasterio 1.3.11
• rioxarray 0.17.0
• scipy 1.14.1
• shapely 2.0.6
• topojson 1.9
• xarray 2024.0.0

While this repo can be extraordinarily convenient for setting up a new geospatial Python environment, it comes with some significant drawbacks. Because the environment includes such an extensive set of dependencies, it can take anywhere from 2 (local machine) to 11 minutes (UBC Open Jupyter) to install. Additionally, the environment itself requires approximately 1.1 GB. Some JupyterHub deployments, like UBC Open Jupyter, only provide around 10 GB of storage space per user, meaning this environment will take about 11% of your total storage space. Other deployments, like UBC Syzygy, only provide 1 GB of storage, thus making it impossible to install this environment on that deployment.

To avoid some of the drawbacks noted above, identify the key packages needed for instruction or research. Create a new conda environment using only those packages and rely on pip as much as possible to avoid exceeding limits on memory usage. Then export the environment as an environment.yml file and pair it with the included Makefile to ensure your environment can be easily reproduced on other Jupyter servers.

Installation

Start a new terminal session in your JupyterHub environment and clone this repository.

git clone https://github.com/ubc-geography/jupyter-py-geog-env

Run the following command to bootstrap the Python environment and install it as a new kernel.

make -C ~/jupyter-py-geog-env create_kernel

Once the kernel has been installed, you may need to wait another minute or two for the kernel to appear on the Jupyter Lab launcher.

Installing New Packages

You can add even more packages to the bootstrap environment by using the following commands.

# Install packages from PyPI
mamba run -p ~/jupyter-py-geog-env/env python -m pip install <package_name>
# Or install packages from conda-forge
mamba install -p ~/jupyter-py-geog-env/env <package_name>
# Recommended: Update the mamba/conda environment file after installing new packages to ensure the environment is reproducible
mamba env export -p ~/jupyter-py-geog-env/env --no-build > environment.yml

To Remove the Environment and Kernel

make -C ~/jupyter-py-geog-env remove_kernel

Template for Instructional Use

As a template repository, this repo can be used to quickly setup new repositories, which can be customized around various geospatial computing lessons. This can ensure a consistent, reproducible environment is accessible from a JupyterHub deployment or other conda-based, Jupyter environment. To get started, select 'Use this template' and create a new repository in your GitHub account. Then add any data, scripts, and/or notebooks needed for your lesson before modifying the README.md file. Also consider modifying the PROJECT_NAME variable in the included Makefile to match the name of your lesson.

Sharing Access

Once your lesson repository is ready to share, you can either

• make your repository public

OR

• create a fine-grained personal access token

If you select the latter option, ensure that you restrict the token's permissions to only have read access to the content of your selected repository. Then share your GitHub username along with the generated token to enable your students to clone your private repository.

After cloning your repository, your students can then create the environment and install the kernel by opening a terminal in the cloned repository and running

make create_kernel