Skip to content

Tutorials

Interactive Jupyter notebook tutorials that walk you through Hera's core workflows step by step with real code and output.

These notebooks complement the User Guide — they show the same concepts in a hands-on, executable format.

Beginner Tutorials

Start here if you're new to Hera. These notebooks cover the fundamentals in order:

Notebook What you'll learn Related docs Download
Project Creating projects (CLI + Python), caseConfiguration.json, loading documents manually Projects :material-download: .ipynb
DataSource Adding data sources, versioning, listing, querying, getting data, deleting Working with Data > Data Sources :material-download: .ipynb
Repository Repository management (add, list, remove, show), JSON structure, DataSource vs Measurements items Key Concepts > Repositories, CLI Reference :material-download: .ipynb

Toolkit Tutorials

Notebook What you'll learn Related docs Download
Tile Toolkit Map images from tile servers, WGS84 and ITM coordinates, custom tile servers Measurements > Tiles :material-download: .ipynb

How to run the tutorials

  1. Activate the Hera environment: 

    source activate_hera.sh

  2. Make sure MongoDB is running: 

    make mongo-up

  3. Start Jupyter: 

    jupyter lab docs/tutorials/

  4. Run the notebooks in order: Project → DataSource → Repository.

Known differences from master

  • Project: the CLI snippets in the text pass values to flag options (--noRepositories 1, --overwrite <ANY_CHAR>); in master these flags take no value — use hera-project project create MY_FIRST_PROJECT --noRepositories. hera-project repository remove takes the repository name, and project updateRepositories without --projectName reads the project from caseConfiguration.json (it does not update all projects; use project populate for that). See the CLI Reference.
  • Toolkit and DataSource (Toolkit_and_DataSource.ipynb) is not listed above because its last cell calls addDataSource() with a repository-style dict as the datasource name, which is not a valid call in master. Use the DataSource tutorial and the Repository Schema instead.

More notebooks

The full collection of Jupyter notebooks (including advanced topics) is in the repository under hera/doc/jupyter/:

Directory Content
hera/doc/jupyter/User/datalayer/ Data layer deep dives: low-level access, caching, version management
hera/doc/jupyter/User/toolkits/measurments/GIS/ GIS toolkits: topography, buildings, demography, land cover, tiles
hera/doc/jupyter/User/toolkits/measurments/experiment/ Experiment creation and usage
hera/doc/jupyter/User/toolkits/measurments/low_frequency/ Meteorology low-frequency data
hera/doc/jupyter/User/toolkits/simulations/ OpenFOAM, Gaussian dispersion, wind profile, Hermes workflows
hera/doc/jupyter/User/toolkits/risskassessment/ Risk assessment
hera/doc/jupyter/User/utils/ Utilities: JSON, units (Unum), queries, DataFrames, contours, Slurm
hera/doc/jupyter/Developer/ Developer-focused notebooks with additional low-level details