Setup

Quickstart with Google Colab¶

You can begin with the course without a local Python installation using online services like Google Colab (colab.google) which provide an online Python version in a Jupyter Notebook environment. This requires a Google account.

Navigate to the other pages. You will find a download button at the top of each page. Download the .ipynb file and import it in Google Colab.

Getting the Code¶

To get the code and material for this course, you can download the full GitHub repository or parts of it. There are several ways to do this:

Individual File Download (beginner friendly):¶

You can download individual files directly from website by clicking on the download button at the top-right corner of each page.

ZIP Option (easy, but static):¶

Download the ZIP file from GitHub and extract it to your computer in a directory of your choice.

Git Option (more advanced):¶

Git is a version control system that allows you to manage and track changes to your code. If you don’t have Git installed, you can install it from git-scm.com. Once installed, you can navigate to a directory where you want to store the course materials and clone the repository using Git. Cloning means you create a local copy of the repository on your computer. It can be done by running the following commands:

# navigate to your desired directory
cd path/to/your/directory

# clone the repository
git clone https://github.com/fneum/data-science-for-esm.git

# enter the cloned repository
cd data-science-for-esm

# update the repository to get the latest changes
git pull

The # symbol indicates comments and should not be typed.

Recommended Setup with conda¶

Installing conda¶

Python and nearly all of the software packages in the scientific python ecosystem are open-source. Coordinating the compatibility between these different packages and their multiple versions can be difficult! Fortunately, the problem is solved by using package managers.

The easiest way to set up a full-stack scientific Python deployment without prior experience is to use a Python distribution, such as Anaconda. The instructions differ for Windows, MacOS, and Linux. Closely, follow the instructions (and videos) at

https://www.anaconda.com/docs/getting-started/getting-started

Watch the introduction videos and follow the instructions there.

Once Anaconda is installed, you can access conda in the command line using the Anaconda Prompt application on Windows, or the terminal application on Linux and MacOS.

Installing conda environments¶

Python coupled with a package manager like conda provides a way to make isolated, reproducible environments where you have control over all installed packages and configurations. To work through the course materials, you need to install a specific set of packages within such a dedicated conda environment.

Downloading specification files¶

Among several other ways to do this, this can be done by creating a new environment from a provided environment.yaml file. This file lists all required packages and their versions in the YAML format. These files can list exact package versions (pinned versions) or just version constraints (e.g., minimum versions).

In this course, we provide pinned versions to ensure everyone has the same environment, but they depend on the operating system you are using.

• For Windows, use the win-64.lock.yaml file.

• For MacOS (Intel/AMD), use the osx-64.lock.yaml file.

• For MacOS (Apple Silicon), use the osx-arm64.lock.yaml file.

• For Linux, use the linux-64.lock.yaml file.

There is a download button at the top-right corner.

Option 1: Anaconda user interface¶

1. Open the Anaconda Navigator application

2. Go to the “Environments” tab on the left

3. Click “Import” at the bottom

4. In the dialog, provide a name for the new environment (e.g. esm-ws-25-26) and select the downloaded environment.yaml file

5. Click “Import” to create the environment and install all required packages

Option 2: Command line¶

First, check that you have access to conda in your terminal (or Anaconda Prompt on Windows) by typing:

conda --version

For Windows:

conda env create -f envs/win-64.lock.yaml

For MacOS (Intel/AMD):

conda env create -f envs/osx-64.lock.yaml

For MacOS (Apple Silicon):

conda env create -f envs/osx-arm64.lock.yaml

For Linux:

conda env create -f envs/linux-64.lock.yaml

Using conda environments¶

To use the course environment, it must be activated by executing in the terminal (or Anaconda Prompt on Windows):

conda activate esm-ws-25-26

This can be done anywhere; you do not need to be in the course repository folder.

You should now see the string (esm-ws-25-26) prepended to your prompt.

Now, any execution of Python will use the packages installed in your environment esm-ws-25-26.

To install additional packages into your environment, such as pandas, you can use:

conda install pandas

Sometimes you may want to install specific versions of packages. For example, to install version 2.1.0 of pandas, you can use:

conda install "pandas=2.1.0"

You can deactivate your environment again by running (you will rarely need to do this):

conda deactivate

To see all the environments on your system:

conda env list

To get a complete summary of all the packages installed in your activated environment, run

conda list

If you want to permanently remove an environment, run:

conda env remove -n esm-ws-25-26

Running Jupyter Lab¶

With the environment activated, you can start Jupyter Lab, a web-based interactive development environment, by typing:

jupyter lab

This should open a new tab in your web browser with the Jupyter Lab interface.

Alternative Setup Options¶

Using pip¶

For using pip as package manager, first ensure you have a working Python installation (version 3.13 is recommended). You can download Python from python.org for your operating system.

Once Python is installed, you can open the command prompt / terminal and verify the installation by typing:

python --version
python -m pip --version
# or
pip --version

Now, you can upgrade pip to the latest version by running:

pip install --upgrade pip

Similar to the conda environment setup, you can install all required packages using a requirements.txt file. This is the same for all operating systems.

For our course, you can find it here. There is a download button at the top-right corner.

After navigating to the folder where the requirements.txt file is stored (i.e. using cd path/to/your/directory), you can install the required packages with

pip install -r requirements.txt

You can add more packages later using pip install package_name, e.g.

pip install pandas

Once this is done, you can start a new Jupyter Lab session in your browser:

jupyter lab

Unlike with conda, pip does not provide isolated environments by default.

Using uv¶

For using uv as package manager, first follow the installation instructions. These differ depending on your operating system.

Once uv is installed, navigate to your local copy of the course repository and verify that it’s working:

uv --version

Now, install all required packages and set up the environment by running:

uv sync

It is important that you run this command in the root folder of the course repository, where the pyproject.toml and uv.lock files are located.

You can also add more packages later using uv pip install package_name, e.g.

uv pip install pandas

Once this is done, you can start a new Jupyter Lab session in your browser with this environment by running:

uv run jupyter lab

VS Code¶

An alternative to using Jupyter Lab is to use Visual Studio Code (VS Code) as your development environment. You still need to manage your Python installation and packages using either conda, pip, or uv as described above.

To work with Jupyter Notebooks in VS Code, you need to install the Jupyter extension. You can install it directly from the Extensions view in VS Code by searching for “Jupyter” and clicking “Install”. You also need to install the Python extension.

Now, whenever you open a Jupyter Notebook file (.ipynb), VS Code will automatically provide you with an interactive interface to run and edit your notebooks. To link the notebook to the correct Python environment, click on the kernel name in the top-right corner of the notebook interface and select the appropriate environment (i.e., esm-ws-25-26).

This setup is a lot more powerful than Jupyter Lab alone, as it provides many additional features such as code completion and AI-assisted coding.

Github Codespaces¶

Github Codespaces provides a cloud-based development environment that can be configured to run all code examples for this course. It is an alternative to Google Colab (described above) or local development on your computer. A Github account is required. To use it, simply click the button below to create your own copy of the course repository on Github.

This will create a fork of the repository in your own Github account; the link will look like this: https://github.com/YOUR_USERNAME/data-science-for-esm.

Then, click on the green “Code” button and select “Open with Codespaces” and “New codespace”. This will create a new Codespace for you. It may take a few minutes to set up the environment for the first time. You get an online VS Code environment with all required packages installed.

If you want to sync your forked repository with the original repository without using the command line, you can use the “Sync fork” button in your forked repository on Github.