- Download or clone the repository.
- Install Julia and Jupyter.
- Run Jupyter and open one of the notebooks, for instance 3-09-full-analysis.ipynb.
If this material helps you in your research or your teaching activities, please cite:
Troupin et al., (2026). DIVAnd training: producing ocean climatologies with Jupyter notebooks. Journal of Open Source Education, 9(99), 278, https://doi.org/10.21105/jose.00278
BibTeX entry
bibtex @article{Troupin2026, doi = {10.21105/jose.00278}, url = {https://doi.org/10.21105/jose.00278}, year = {2026}, publisher = {The Open Journal}, volume = {9}, number = {99}, pages = {278}, author = {Charles Troupin and Alexander Barth and Jean-Marie Beckers}, title = {DIVAnd training: producing ocean climatologies with Jupyter notebooks}, journal = {Journal of Open Source Education} }
The goal of the training material module, made up of Jupyter notebooks, is twofold:
- provide the users with a basic knowledge of Julia, meaning they are capable of reading the code presented in the notebooks and installing new modules, writing functions for processing or creating plots.
- ensure that users are able to create their own products (i.e. climatologies) using the
DIVAndsoftware tool, by combining their own datasets with those from other sources (for instance the World Ocean Database) and setting the analysis parameters according to their region of interest.
The notebooks can be run on various OS, yet most of the tests were carried out on machine running under Linux.
Participants to the training sessions are generally advised to work with a laptop with:
- 16 GB RAM memory and
- sufficient free disk space to manage oceanographic datasets.
- Data files necessary to prepare products or climatologies.
Julia language can be installed using juliaup, as detailed in the Download section of Julia.
Jupyter has to be installed in order to have a notebook interface. It can be installed and launched (in Julia) with the following command in the Pkg REPL
(Enter the Pkg REPL by pressing ] from the Julia session):
(@v1.11) pkg> add IJuliaTo get the notebooks on your computer you can either:
- Download a zipped archive and uncompress it [for any user].
- Clone the whole directory:
git clone git@github.com:gher-uliege/Diva-Workshops.git(for git users).
Note
The notebooks will get dependencies via the file Project.toml. This is why all the notebooks start with the commands
import Pkg
Pkg.activate("../..")
Pkg.instantiate()The Jupyter session is started with:
using IJulia
notebook()Important
A notebook in Pluto, 3-09-full-analysis.jl, was recently added to the repository. To run it, you have to execute:
import Pluto
Pluto.run()then you have to open the file 3-09-full-analysis.jl in your browser.
The notebooks are organised into 4 categories, according to their main objectives and following the "Instructional design" described in the associated paper in the Journal of Open Source Education.
The different notebook folders can be covered independently, depending on the user expertise.
Suggestions for the number of sessions and time to be dedicated for each category are provided below.
| Folder | Content | Recommended duration |
|---|---|---|
| 1-Intro | Know the basics commands in Julia, read/write netCDF files and create different types of plots (scatter, histograms, maps, ...) | 2 hours |
| 2-Preprocessing | Learn about the input file preparation: observations (download and reading), bathymetry and mask, time periods, ... | 4 hours |
| 3-Analysis | Perform different types of analysis, optimise the analysis parameters and work with different coordinate systems | 2 sessions of 4 hours |
| 4-AdvancedTopics | Discover more complex types of analysis, using for instance advection or inequality constraints. | 4 hours |
Full list of notebooks
- 1-01-notebooks-basics.ipynb
- 1-02-Julia-introduction.ipynb
- 1-03-netCDF.ipynb
- 1-04-OI-variational-analysis-introduction.ipynb
- 1-05-plots-maps.ipynb
- 2-01-topography.ipynb
- 2-02-reading-data.ipynb
- 2-03-data-downloading.ipynb
- 2-04-ODV-data-import.ipynb
- 2-05-defining-time-periods.ipynb
- 3-01-L-and-epsilon-effect.ipynb
- 3-02-correlation-length.ipynb
- 3-03-processing-parameter-optimization.ipynb
- 3-04-processing-quality-check.ipynb
- 3-05-cpme-demo.ipynb
- 3-06-errormaps-demo.ipynb
- 3-07-example-analysis.ipynb
- 3-08-background-field.ipynb
- 3-09-full-analysis.ipynb
- 3-10-save_attributes_EMODnet.ipynb
- 3-11-generalized-vertical-coordinates.ipynb
- 3-12-sigma-layers.ipynb
- 3-13-polar-coordinates.ipynb
- 3-14-Sphericalcoordinates.ipynb
- 3-15-analysis-datapoints.ipynb
- 4-01-relative-correlation-length.ipynb
- 4-02-average-background.ipynb
- 4-03-heatmaps.ipynb
- 4-04-heatmapsCV.ipynb
- 4-05-turtles-tensity-map.ipynb
- 4-06-advection_constrain.ipynb
- 4-07-advection_constraint_Adriatic.ipynb
- 4-08-source-term.ipynb
- 4-09-open-boundary-conditions.ipynb
- 4-10-multivariate-EOF.ipynb
- 4-11-multivariate-Jacobian.ipynb
- 4-12-analysis-with-cycles.ipynb
- 4-13-BlackSea-detrend-geostrophic.ipynb
- 4-14-inequalities-constrains.ipynb
- 4-15-geostrophytest.ipynb
- 4-16-Lshape.ipynb
- 4-17-interp-section.ipynb
- 4-18-make-paper-figure.ipynb
- 4-19-optim-observations-locations-game.ipynb
Different paths can be taken, depending on your experience with Julia and with DIVAnd.
First follow the instructions for the installation, then decide from where to start according to your experience or your audience.
| Experience in Julia | Experience with DIVAnd | Recommendation |
|---|---|---|
| No | No | Start from the beginning! |
| Yes | No | Start with the 2-Preprocessing notebooks, then try an analysis (for instance 3-07-example-analysis.ipynb) |
| No | Yes | Check the 1-Intro notebooks to get familiar with Julia, then play with the analysis |
| Yes | Yes | Use the notebook 3-09-full-analysis.ipynb as a starting point for your analysis, then play with the 4-AdvancedTopics |
Please refer to the instructions in CONTRIBUTING.md.
Warning
After an update of the Julia version, one can face an error message related to the Kernel:
LoadError: ArgumentError: Package IJulia ... is required but does not seem to be installed
This can be solved with the command:
using IJulia
installkernel("Julia")