This repository contains documentation, resources, and code for the Scientific Visualisation with matplotlib session designed and delivered by Jack Atkinson (@jatkinson1000)
and James Emberton (@j-emberton) of ICCS.
This material was originally prepared for the ICCS 2024 summer school.
All materials, including slides and workbooks, are available such that individuals can cover the course in their own time.
- Learning Objectives
- Teaching material
- Preparation and prerequisites
- Installation and setup
- License information
- Contribution Guidelines and Support
The key learning objective from this workshop is to build skills in scientific visualisation through python and its libraries.
However, more specifically we aim to:
- summarise key considerations when visualising scientific data,
- provide an understanding of the Matplotlib package and how to use it effectively,
- introduce the Cartopy package and show how it extends Matplotlib functionality for geospatial plotting,
- introduce common climate data formats and show how these can be parsed to generate plottable data, and
- encourage good research software engineering (RSE) practice while using code to generate scientific visualisations.
The course material is supplied as Quarto markdown slides with an accompanying jupyter lab notebook.
Slides can be found in the presentation directory.
Notebook can be found in the notebook directory.
To get the most out of the session we assume a basic understanding in a few areas and for you to do some preparation in advance. Expected knowledge is outlined below, along with resources for reading if you are unfamiliar.
The course will be taught in python using netCDF4, Matplotlib and Cartopy python packages. Whilst no prior knowledge of these python packages is expected we assume users are familiar with the basics of Python3. This includes:
- Basic mathematical operations
- Writing and running scripts/programs
- Writing and using functions
- The concept of object orientation
i.e. that an object, e.g. a dataset, can have associated functions/methods associated with it. - Familiarity with the concept of a jupyter notebook
You will be expected to know how to
- clone and/or fork a repository
The workshop from the 2022 ICCS Summer School should provide the necessary knowledge.
In preparation for the course please ensure that your computer contains the following:
- A text editor - e.g. vim/neovim, gedit, vscode, sublimetext etc. to open and edit code files
- A terminal emulator - e.g. GNOME Terminal, wezterm, Windows Terminal (windows only), iTerm (mac only)
- python virtual environment (see Installation and setup)
Note for Windows users: We have linked suitable applications for windows in the above lists. However, you may wish to refer to Windows' getting-started with python information for a complete guide to getting set up on a Windows system.
If you require assistance or further information with any of these please reach out to us before a training session.
The slides are written using quarto. To build them run:
quarto render Scientific_Vis.qmd
from the presentation/ directory and inspect the output .html file (assuming you have Quarto installed on your machine ).
Local install is the current preferred approach to access these teaching materials, however Google CoLab and Binder options may follow in future updates.
Navigate to the location you want to install this repository on your system and clone via https by running:
git clone https://github.com/Cambridge-ICCS/summer-school-scientific-vis.git
This will create a directory summer-school-scientific-vis/ with the contents of this repository.
Please note that if you have a GitHub account and want to preserve any work you do we suggest you first fork the repository and then clone your fork. This will allow you to push your changes and progress from the workshop back up to your fork for future reference.
Before installing any Python packages it is important to first create a Python virtual environment. This provides an insulated environment inside which we can install Python packages without polluting the operating system's Python environment.
If you have never done this before don't worry: it is very good practise, especially when you are working on multiple projects, and easy to do.
python3 -m venv SVvenv
This will create a directory called SVvenv containing software for the virtual environment.
To activate the environment run:
source SVvenv/bin/activate
You can now work on python from within this isolated environment, installing packages as you wish without disturbing your base system environment.
When you have finished working on this project run:
deactivate
to deactivate the venv and return to the system python environment.
You can always boot back into the venv as you left it by running the activate command again.
It is now time to install the dependencies for our code, for example PyTorch.
The project has been packaged with a pyproject.toml so can be installed in one go.
From within the root directory in a active virtual environment run:
pip install .
This will download the relevant dependencies into the venv as well as setting up the datasets that we will be using in the course.\
From the current directory, launch the jupyter notebook server:
jupyter notebook
This command should then point you to the right location within your browser to use the notebook, typically http://localhost:8888/.
The code materials in this project are licensed under the MIT License.
The teaching materials are licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.
If you spot an issue with the materials please let us know by opening an issue here on GitHub clearly describing the problem.
If you are able to fix an issue that you spot, or an existing open issue please get in touch by commenting on the issue thread.
Contributions from the community are welcome. To contribute back to the repository please first fork it, make the neccessary changes to fix the problem, and then open a pull request back to this repository clerly describing the changes you have made. We will then preform a review and merge once ready.
If you would like support using these materials, adapting them to your needs, or delivering them please get in touch either via GitHub or via ICCS.