Skip to content

Marimo Notebooks

This directory contains interactive Marimo notebooks for the Rhiza project.

Features

Marimo notebooks support a wide range of features, including:

  • Interactive UI Elements: Sliders, dropdowns, text inputs, checkboxes, and multiselect
  • Reactive Programming: Automatic cell updates when dependencies change
  • Data Visualisation: Interactive plots using Plotly
  • DataFrames: Working with Pandas data
  • Layout Components: Columns, tabs, and accordions for organised content
  • Forms: Dictionary-based forms for collecting user input
  • Rich Text: Markdown and LaTeX support for documentation
  • Advanced Features: Callouts, collapsible accordions, and more

Running the Notebooks

Using the Makefile

From the repository root:

make marimo

This will start the Marimo server and open all notebooks in the docs/notebooks directory.

Running a Specific Notebook

To run a single notebook:

marimo edit docs/notebooks/my_notebook.py

The notebooks include inline dependency metadata, making them self-contained:

uv run docs/notebooks/my_notebook.py

This will automatically install the required dependencies and run the notebook.

Notebook Structure

Marimo notebooks are pure Python files (.py), not JSON. This means:

  • ✅ Easy version control with Git
  • ✅ Standard code review workflows
  • ✅ No hidden metadata
  • ✅ Compatible with all Python tools

Each notebook includes inline metadata that specifies its dependencies:

# /// script
# requires-python = ">=3.11"
# dependencies = [
#     "marimo==0.18.4",
#     "numpy>=1.24.0",
# ]
# ///

Configuration

Marimo is configured in pyproject.toml to properly import the local package:

[tool.marimo.runtime]
pythonpath = ["src"]

CI/CD Integration

The .github/workflows/rhiza_marimo.yml workflow automatically:

  1. Discovers all .py files in this directory
  2. Runs each notebook in a fresh environment
  3. Verifies that notebooks can bootstrap themselves
  4. Ensures reproducibility

This guarantees that all notebooks remain functional and up-to-date.

Creating New Notebooks

To create a new Marimo notebook:

  1. Create a new .py file in this directory: 

    marimo edit docs/notebooks/my_notebook.py

  2. Add inline metadata at the top: 

    # /// script
# requires-python = ">=3.11"
# dependencies = [
#     "marimo==0.18.4",
#     # ... other dependencies
# ]
# ///

  3. Start building your notebook with cells

  4. Test it runs in a clean environment: 

    uv run docs/notebooks/my_notebook.py

  5. Commit and push - the CI will validate it automatically

Learn More

Tips

  • Reactivity: Remember that cells automatically re-run when their dependencies change
  • Pure Python: Edit notebooks in any text editor, not just Marimo's UI
  • Git-Friendly: Notebooks diff and merge like regular Python files
  • Self-Contained: Use inline metadata to make notebooks reproducible
  • Interactive: Take advantage of Marimo's rich UI components for better user experience

Happy exploring with Marimo! 🚀