tutorials

Computer labs for the water course.

The labs are written as percent-format Python files in this directory and converted to notebooks by the Makefile. Each source builds two notebooks into ready/: an exercise version with the worked code stripped out (# + tags=["solution"] cells removed) and a solution version that is executed with its outputs baked in (# + tags=["empty-cell"] cells removed). Run make all to build everything, or make solution-lab02_shapefiles_and_masks.py for one.

ready/ is build output and is not committed here. This repository tracks only the .py sources, the Makefile, and image/.

How the notebooks reach students

Three repositories are involved, and it is worth knowing which one does what.

Pushing to main here triggers .github/workflows/jupytext-conversion.yml, which runs make all on a clean runner and uploads the whole of ready/ as an artifact named ready. Note that the solution notebooks are executed during that build, so the workflow needs the network: lab02 and lab03 stream rainfall from NCI's THREDDS server, and lab04 downloads a 107 MB GRACE mascon file. If any of them is unreachable the run fails and no artifact is produced.

water-course/colab-tutorials is what students actually open in Colab. It has a manually triggered workflow, "Grab latest tutorials", that finds the most recent successful run here, downloads the ready artifact, and commits the exercise notebooks and image/. It filters out anything matching *_solution.ipynb, so solutions never appear in the Colab picker. Because the trigger is manual, that repository lags behind this one until someone dispatches it — do that after pushing, or the students keep seeing the previous version.

water-course/water-course.github.io carries the solution notebooks under docs/computer-lab/, where mkdocs-jupyter renders the stored outputs. The site does not re-execute anything, so a notebook copied across without its outputs renders as a blank page. Those files are currently untracked in that repository and are copied over by hand.

source	site name	topic
lab01_python_basics.py	Lab 1	Python basics: maths, loops, formatted output, a Cartopy map
lab02_shapefiles_and_masks.py	Lab 2	shapefiles, point-in-polygon, OPeNDAP NetCDF, basin masking
lab03_xarray_gridded_data.py	Lab 3	xarray: lazy OPeNDAP access, sel/isel, the latitude trap, resample
lab04_grid_cell_areas.py	Lab 4	latitude-dependent grid-cell areas
lab05_rain_gauge_interpolation.py	Lab 5	interpolating missing rain-gauge values

lab03, the xarray lab

lab03_xarray_gridded_data.py fills the gap between lab02 and Assignment I. lab02 reads NetCDF through netCDF4 at the index level, which is what makes the descending-latitude trap comprehensible, and lab04 uses xarray only incidentally without explaining it. Assignment I hands students an xr.open_dataset line and assumes the rest.

What it covers, pitched at the same level of hand-holding as lab01:

• open_dataset against an OPeNDAP URL, and why that is lazy (metadata only) until you slice
• .sel and .isel, and the difference between label- and position-based indexing
• the descending-latitude trap, with both slice orders printed so the silent failure is visible
• .plot for quick maps and time series, and what happens when long_name lies
• one contiguous .load() of a 3-D subset, and reduction by dimension name
• .weighted, framed as a numerical check that lab04's area formula and cos-weighting agree
• .resample(time="YE") with a .count() == 12 completeness check, which is what Assignment I needs for annual totals

.groupby is deliberately left out; it is the same idea as resample with different bins and the summary points at it in one line.

A note on rain_day_2025.nc

https://data.gadopt.org/water-course/rain_day_2025.nc is not rainfall in millimetres. It is the Australian Water Outlook decile product: values are percentile ranks in [0, 1] with units: relative, and roughly half the grid is NaN. It is byte-for-byte identical to the file under AWRALv7/processed/deciles/day/. lab02_shapefiles_and_masks.py used to download it and plot it as "Rainfall (mm)"; it now streams the monthly values product over OPeNDAP instead. Do not reintroduce that file as a rainfall source.