fix: finalizing notebooks for relaunch

.gitignore

@@ -183,4 +183,5 @@ _site/
 tmp/
 example.db
 example.db.wal
-log_data_filtered*.*
+log_data_filtered/*
+log_data_filtered.*

altair/01_introduction.py

@@ -4,7 +4,6 @@
 #     "altair==6.0.0",
 #     "marimo",
 #     "pandas==3.0.1",
-#     "vega_datasets==0.9.0",
 # ]
 # ///
 
@@ -76,23 +75,23 @@ def _(mo):
 
     When using Altair, datasets are commonly provided as data frames. Alternatively, Altair can also accept a URL to load a network-accessible dataset. As we will see, the named columns of the data frame are an essential piece of plotting with Altair.
 
-    We will often use datasets from the [vega-datasets](https://github.com/vega/vega-datasets) repository. Some of these datasets are directly available as Pandas data frames:
+    We will often use datasets from Altair's `datasets` sub-package. Some of these datasets are directly available as Pandas data frames:
     """)
     return
 
 
 @app.cell
 def _():
-    from vega_datasets import data  # import vega_datasets
-    cars = data.cars()              # load cars data as a Pandas data frame
-    cars.head()                     # display the first five rows
+    from altair.datasets import data  # import vega_datasets
+    cars = data.cars()                # load cars data as a Pandas data frame
+    cars.head()                       # display the first five rows
     return cars, data
 
 
 @app.cell(hide_code=True)
 def _(mo):
     mo.md(r"""
-    Datasets in the vega-datasets collection can also be accessed via URLs:
+    Altair's datasets can also be accessed via URLs:
     """)
     return
 

altair/02_marks_encoding.py

@@ -4,7 +4,6 @@
 #     "altair==6.0.0",
 #     "marimo",
 #     "pandas==3.0.1",
-#     "vega_datasets==0.9.0",
 # ]
 # ///
 
@@ -62,15 +61,15 @@ def _(mo):
     mo.md(r"""
     We will be visualizing global health and population data for a number of countries, over the time period of 1955 to 2005. The data was collected by the [Gapminder Foundation](https://www.gapminder.org/) and shared in [Hans Rosling's popular TED talk](https://www.youtube.com/watch?v=hVimVzgtD6w). If you haven't seen the talk, we encourage you to watch it first!
 
-    Let's first load the dataset from the [vega-datasets](https://github.com/vega/vega-datasets) collection into a Pandas data frame.
+    Let's first load the dataset into a Pandas data frame.
     """)
     return
 
 
 @app.cell
 def _():
-    from vega_datasets import data as vega_data
-    data = vega_data.gapminder()
+    from altair.datasets import data as altair_data
+    data = altair_data.gapminder()
     return (data,)
 
 

altair/03_data_transformation.py

@@ -55,7 +55,7 @@ def _(mo):
     mo.md(r"""
     We will be working with a table of data about motion pictures, taken from the [vega-datasets](https://vega.github.io/vega-datasets/) collection. The data includes variables such as the film name, director, genre, release date, ratings, and gross revenues. However, _be careful when working with this data_: the films are from unevenly sampled years, using data combined from multiple sources. If you dig in you will find issues with missing values and even some subtle errors! Nevertheless, the data should prove interesting to explore...
 
-    Let's retrieve the URL for the JSON data file from the vega_datasets package, and then read the data into a Pandas data frame so that we can inspect its contents.
+    Let's retrieve the URL for the JSON data file from the datasets package, and then read the data into a Pandas data frame so that we can inspect its contents.
     """)
     return
 

altair/05_view_composition.py

@@ -542,7 +542,7 @@ def _(mo):
 
     Finally, note that horizontal and vertical concatenation can be combined. _What happens if you write something like `(temp | precip) & wind`?_
 
-    _Aside_: Note the importance of those parentheses... what happens if you remove them? Keep in mind that these overloaded operators are still subject to [Python's operator precendence rules](https://docs.python.org/3/reference/expressions.html#operator-precedence), and so vertical concatenation with `&` will take precedence over horizontal concatenation with `|`!
+    _Aside_: Note the importance of those parentheses... what happens if you remove them? Keep in mind that these overloaded operators are still subject to [Python's operator precedence rules](https://docs.python.org/3/reference/expressions.html#operator-precedence), and so vertical concatenation with `&` will take precedence over horizontal concatenation with `|`!
 
     As we will revisit later, concatenation operators let you combine any and all charts into a multi-view dashboard!
     """)

altair/07_cartographic.py

@@ -4,7 +4,6 @@
 #     "altair==6.0.0",
 #     "marimo",
 #     "pandas==3.0.1",
-#     "vega_datasets==0.9.0",
 # ]
 # ///
 
@@ -51,7 +50,9 @@ def _(mo):
 def _():
     import pandas as pd
     import altair as alt
-    from vega_datasets import data
+    from altair.datasets import data
+    import json
+    import urllib.request
 
     return alt, data
 
@@ -131,7 +132,8 @@ def _(data):
 
 @app.cell
 def _(data):
-    world_topo = data.world_110m()
+    with urllib.request.urlopen(world) as response:
+        world_topo = json.load(response)
     return (world_topo,)
 
 
@@ -160,7 +162,7 @@ def _(mo):
 
     In the data above, the `objects` property indicates the named elements we can extract from the data: geometries for all `countries`, or a single polygon representing all `land` on Earth. Either of these can be unpacked to GeoJSON data we can then visualize.
 
-    As TopoJSON is a specialized format, we need to instruct Altair to parse the TopoJSON format, indicating which named faeture object we wish to extract from the topology. The following code indicates that we want to extract GeoJSON features from the `world` dataset for the `countries` object:
+    As TopoJSON is a specialized format, we need to instruct Altair to parse the TopoJSON format, indicating which named feature object we wish to extract from the topology. The following code indicates that we want to extract GeoJSON features from the `world` dataset for the `countries` object:
 
     ~~~ js
     alt.topo_feature(world, 'countries')
@@ -563,7 +565,7 @@ def _(mo):
     mo.md(r"""
     _Which U.S. airports have the highest number of outgoing routes?_
 
-    Now that we can see the airports, which may wish to interact with them to better understand the structure of the air traffic network. We can add a `rule` mark layer to represent paths from `origin` airports to `destination` airports, which requires two `lookup` transforms to retreive coordinates for each end point. In addition, we can use a `single` selection to filter these routes, such that only the routes originating at the currently selected airport are shown.
+    Now that we can see the airports, which may wish to interact with them to better understand the structure of the air traffic network. We can add a `rule` mark layer to represent paths from `origin` airports to `destination` airports, which requires two `lookup` transforms to retrieve coordinates for each end point. In addition, we can use a `single` selection to filter these routes, such that only the routes originating at the currently selected airport are shown.
 
     _Starting from the static map above, can you build an interactive version? Feel free to skip the code below to engage with the interactive map first, and think through how you might build it on your own!_
     """)

altair/08_debugging.py

@@ -4,7 +4,6 @@
 #     "altair==6.0.0",
 #     "marimo",
 #     "pandas==3.0.1",
-#     "vega_datasets==0.9.0",
 # ]
 # ///
 
@@ -57,18 +56,18 @@ def _(mo):
     mo.md(r"""
     These instructions follow [the Altair documentation](https://altair-viz.github.io/getting_started/installation.html) but focus on some specifics for this series of notebooks.
 
-    In every notebook, we will import the [Altair](https://github.com/altair-viz/altair) and [Vega Datasets](https://github.com/altair-viz/vega_datasets) packages. If you are running this notebook on [Colab](https://colab.research.google.com), Altair and Vega Datasets should be preinstalled and ready to go. The notebooks in this series are designed for Colab but should also work in Jupyter Lab or the Jupyter Notebook (the notebook requires a bit more setup [described below](#Special-Setup-for-the-Jupyter-Notebook)) but additional packages are required.
+    In every notebook, we will import the [Altair](https://github.com/altair-viz/altair) package. If you are running this notebook on [Colab](https://colab.research.google.com), Altair should be preinstalled and ready to go. The notebooks in this series are designed for Colab but should also work in Jupyter Lab or the Jupyter Notebook (the notebook requires a bit more setup [described below](#Special-Setup-for-the-Jupyter-Notebook)) but additional packages are required.
 
     If you are running in Jupyter Lab or Jupyter Notebooks, you have to install the necessary packages by running the following command in your terminal.
 
     ```bash
-    pip install altair vega_datasets
+    pip install altair
     ```
 
     Or if you use [Conda](https://conda.io)
 
     ```bash
-    conda install -c conda-forge altair vega_datasets
+    conda install -c conda-forge altair
     ```
 
     You can run command line commands from a code cell by prefixing it with `!`. For example, to install Altair and Vega Datasets with [Pip](https://pip.pypa.io/), you can run the following cell.
@@ -78,14 +77,14 @@ def _(mo):
 
 @app.cell
 def _():
-    # packages added via marimo's package management: altair vega_datasets !pip install altair vega_datasets
+    # packages added via marimo's package management: altair !pip install altair
     return
 
 
 @app.cell
 def _():
     import altair as alt
-    from vega_datasets import data
+    from altair.datasets import data
 
     return alt, data
 
@@ -134,7 +133,7 @@ def _(mo):
     If you are not running the latest version, you can update it with `pip`. You can update Altair and Vega Datasets by running this command in your terminal.
 
     ```
-    pip install -U altair vega_datasets
+    pip install -U altair
     ```
     """)
     return
@@ -247,7 +246,7 @@ def _(alt):
 @app.cell(hide_code=True)
 def _(mo):
     mo.md(r"""
-    Check the spelling of your files and print the data source to confirm that the data and fields exist. For instance, here you see that `color` is not a vaid field.
+    Check the spelling of your files and print the data source to confirm that the data and fields exist. For instance, here you see that `color` is not a valid field.
     """)
     return
 

optimization/01_least_squares.py

@@ -1,7 +1,8 @@
 # /// script
 # requires-python = ">=3.11"
 # dependencies = [
-#     "cvxpy-base",
+#     "clarabel>=0.11.1",
+#     "cvxpy-base>=1.8.2",
 #     "marimo",
 #     "numpy==2.4.3",
 # ]

optimization/04_quadratic_program.py

@@ -1,7 +1,8 @@
 # /// script
 # requires-python = ">=3.13"
 # dependencies = [
-#     "cvxpy-base",
+#     "clarabel>=0.11.1",
+#     "cvxpy-base>=1.8.2",
 #     "marimo",
 #     "matplotlib==3.10.8",
 #     "numpy==2.4.3",

optimization/05_portfolio_optimization.py

@@ -1,7 +1,8 @@
 # /// script
 # requires-python = ">=3.13"
 # dependencies = [
-#     "cvxpy-base",
+#     "clarabel>=0.11.1",
+#     "cvxpy-base>=1.8.2",
 #     "marimo",
 #     "matplotlib==3.10.8",
 #     "numpy==2.4.3",

optimization/06_convex_optimization.py

@@ -1,7 +1,8 @@
 # /// script
 # requires-python = ">=3.13"
 # dependencies = [
-#     "cvxpy-base",
+#     "clarabel>=0.11.1",
+#     "cvxpy-base>=1.8.2",
 #     "marimo",
 #     "numpy==2.4.3",
 # ]

optimization/07_sdp.py

@@ -1,7 +1,8 @@
 # /// script
 # requires-python = ">=3.13"
 # dependencies = [
-#     "cvxpy-base",
+#     "clarabel>=0.11.1",
+#     "cvxpy>=1.8.2",
 #     "marimo",
 #     "numpy==2.4.3",
 #     "wigglystuff==0.2.37",

pages/educators.md

@@ -1,362 +1,208 @@
----
-title: marimo for Educators
----
+marimo for Educators
 
 ## Introduction
 
-- what *is* a notebook?
-    - *literate programming* mixes prose and software in a single "runnable paper"
-    - each *cell* is prose or software
-    - prose typically written in Markdown
-    - software written in whatever programming languages the notebook supports
-    - software's output displayed in the notebook as well
-- why notebooks for everyday work?
-    - easier to understand (think about the way textbooks present material)
-    - improves reproducibility
-    - [GVW: if we emphasize embedded AI] keep track of what you asked for as well as what you did
-- why notebooks for learning?
-    - more engaging than static material: learners are active users of material, not passive consumers, can experiment with settings, alter code, etc.
-    - no installation required: notebooks can be hosted so learners don't have to struggle with the hard bits first (i.e., focus on learning rather than on the tool)
-    - reproducibility helps collaboration as well [GVW: but we don’t support concurrent editing a la Google Docs, which some people will regard as table stakes]
-    - less intimidating than jumping straight into scripting
-    - introduces a real-world tool
-    - [if we emphasize embedded AI] a natural way to bring LLMs into the classroom
-- why notebooks for teaching?
-    - all of the above…
-    - create interactive lecture material in a single place
-- why the marimo notebook?
-    - open source
-    - more than Notebook but not as intimidating as VS Code
-    - reactivity allows for (encourages) dynamic, interactive elements
-        - marimo is both a notebook and a library of UI elements
-        - and [AnyWidget](https://anywidget.dev/) makes it relatively easy to extend [GVW: point at [faw](https://github.com/gvwilson/faw)]
-    - doesn't allow out-of-order execution of cells, which reduces “worked for me” complaints
-    - plays nicely with other Python tools (because a notebook is a Python file)
-    - plays nicely with version control (same reason)
-    - helps instructors keep their prose and examples in sync
-    - configurable interaction with AI tools
-    - [if we emphasize embedded AI] natural way to teaching prompting and review
-- why *not* marimo?
-    - not yet as widely known as Jupyter (i.e., your IT department may not already support it)
-    - not yet integrated with auto-grading tools ([faw](https://github.com/gvwilson/faw) is a start, but we're waiting to see what you want)
-    - doesn't yet support multi-notebook books
-    - some quirks that might not make it the right tool for a CS-101 course (see below)
+A computational notebook is a form of *literate programming* that mixes prose and software in a single runnable document. Each *cell* contains either prose written in Markdown or code written in a supported programming language, and the output of any code cell is displayed directly in the notebook alongside the source.
 
-## Ways to Teach With marimo
-
-- high level
-    - follow along with lesson (code already present)
-    - workbooks for assignments ("fill in these cells")
-    - notebooks as apps (play with data rather than write code)
-    - notebooks as lab reports (models real-world use)
-- micro
-    - scroll through a pre-executed notebook
-    - step through a notebook by executing the cells in order
-    - fill out details or values into a mostly complete notebook
-    - tweak or fill in a notebook with some content
-    - add content to a completely blank notebook
-    - ask learners what to add *or* what's going to happen
-    - ask AI to do something and then explore/correct/improve its output
-
-## Things to Watch Out For
-
-- Variable names
-    - Underscored variable names are different from common usage, and require some understanding of scope
-    - Solution is functions-early teaching methodology, which has a sound pedagogical basis
-- Image files
-    - For security reasons, marimo requires local image files to be in a folder called `public` below the directory the notebook is run from, and to be accessed in Markdown as `[alt text](/public/image.ext)`
-    - Which means it’s important to launch the notebook from the right place
-    - Can get around this using `mo.image` but that can’t be embedded in Markdown
-- [Using pytest in marimo](https://docs.marimo.io/guides/testing/pytest/#testing-in-notebook) is straightforward as long as the cell *only* contains tests
-- marimo uses [KaTeX](https://katex.org/) rather than [MathJax](https://www.mathjax.org/) for rendering math - see the appendix to this document for notes
-
-## Pedagogical Patterns
-
-### Shift-Enter
-
-**Description:** Learner starts with complete notebook, re-executes cells; (possibly) fills in prose cells with analysis/description
-
-**Use For:** Introduce new topics; check understanding (e.g., warmup exercise)
-
-**Works For:** Any audience
-
-**Format:** Synchronous
-
-**Pro:** Gives learners a complete working example
-
-**Con:** Low engagement
-
-### Fill in the blanks
-
-**Description:** Some code cells filled in, learner must complete
-
-**Use For:** Reducing cognitive load
+Notebooks make everyday work easier to understand because they present explanation and evidence together, just like people do in conversation. This format also improves reproducibility, since the code that produced a result lives beside the result itself.
 
-**Works For:** Any audience
+For learning, notebooks offer several advantages over static material. Learners become active participants rather than passive readers: they can experiment with settings, alter code, and see immediate results. Because notebooks can be hosted, learners do not need to install anything before they start, which means the first session can focus on the subject itself rather than on tooling. The format is less intimidating than jumping straight into a script editor, and it introduces learners to a real-world tool used in research and industry.
 
-**Format:** Assignments and labs
+For teaching, notebooks serve all those purposes while also letting instructors keep interactive lecture material in one place.
 
-**Pro:** Focus attention on a specific concept (e.g., filtering data)
+### Why marimo?
 
-**Con:** “Just get AI to do it”; required work can be too easy or too hard
+marimo is open source and occupies a useful middle ground: richer than a plain text editor but less overwhelming than a full IDE such as VS Code. Its reactivity encourages dynamic, interactive elements, because marimo is both a notebook environment and a library of UI components. The [AnyWidget](https://anywidget.dev/) protocol makes it relatively straightforward to extend marimo with custom widgets.
 
-### Tweak and twiddle
+marimo does not allow out-of-order cell execution, which eliminates a common class of "it worked on my machine" complaints. And since a marimo notebook is a valid Python file, it integrates naturally with other Python tools and with version control. Instructors benefit from having prose and code examples in the same file, which helps keep explanations in sync with the code they describe. marimo also offers configurable integration with AI tools.
 
-**Description:** Learner starts with complete working notebook, is asked to alter parameters to achieve some goal
+### Why *Not* marimo?
 
-**Use For:** Compare and contrast; acquiring domain knowledge
+marimo is not yet as widely known as Jupyter, so your institution's IT department may not already support it. Auto-grading integration is not yet available in a mature form (but we're working on it), and multi-chapter books are not yet supported. Some quirks in how marimo handles scope may make it a less natural fit for an introductory CS course; see "Things to Watch Out For" below.
 
-**Works For:** Learners without programming experience (but requires some domain knowledge)
+## molab
 
-**Format:** Fixed-time workshop exercise; pair programming
+molab is marimo's free cloud-hosted notebook service, available at [molab.marimo.io](https://molab.marimo.io/notebooks). It is the easiest way for students to get started because it requires no local installation: marimo is accessible as a self-contained web application, comparable in experience to Google Colab. Notebooks created on molab are public but not discoverable by default, and can be shared with others by URL. Students can download their notebooks as `.py`, `.ipynb`, or PDF files, which makes submission to grading systems such as Gradescope straightforward.
 
-**Pro:** Helps learners overcome code anxiety
+molab can also preview notebooks hosted on GitHub. The service provides a stable URL for a notebook that stays current as the notebook changes, so students always see the latest version. From the preview page, students can fork the notebook into their own workspace.
 
-**Con:** “Where do I start?” and going down rabbit holes
+Existing Jupyter notebooks can be converted to marimo notebooks automatically with `uvx marimo convert my_notebook.ipynb -o my_notebook.py`.
 
-### Notebook as app
-
-**Description:** Use notebook as interactive dashboard (note: usually keep prose in a separate document to make the dashboard look like an app)
-
-**Use For:** Exploring datasets
-
-**Works For:** Non-programmers
-
-**Format:** Use instead of slides (but must know where you’re going); have learners suggest alternatives to explore; data analysis after (physical) lab experiment
-
-**Pro:** Less effort to build than custom UI
-
-**Con:** Requires testing; does not develop programming skills
+## Ways to Teach With marimo
 
-### Top-down delivery
+At a high level, there are (at least) four ways to teach with marimo notebooks:
 
-**Description:** Give learners just enough control to get to a motivating result quickly (“day one”)
+1.  Learners can follow along with the lesson when the code already present in the notebook.
 
-**Use For:** Follow-along lectures
+1.  Notebooks can be used as assignments (i.e., "fill in these cells").
 
-**Works For:** Any audience (but most engaging for people with low programming skills)
+1.  Notebooks be used as apps so that learners can explore data rather than, or as well as, writing code.
 
-**Format:** Tutorials and workshops (synchronous)
+1.  Learners can create notebooks from scratch as lab reports, which most closely models real-world use.
 
-**Pro:** Student engagement
+## Things to Watch Out For
 
-**Con:** Hard to get the right level of detail for a mixed-ability audience
+Variable names
+:   Underscore-prefixed variable names in marimo have a meaning different from their common usage in Python and require some understanding of lexical scope. The recommended remedy is a functions-early teaching methodology, which has a sound pedagogical basis and prepares learners for idiomatic Python.
 
-### Coding as translation
+Image files
+:   For security reasons, marimo requires local image files to be placed in a folder named `public` directly below the directory from which the notebook is launched, and to be referenced in Markdown as `/public/image.ext`. This means it matters where the notebook is started. The `mo.image` function works around this restriction but cannot be embedded inside a Markdown string.
 
-**Description:** Convert prose to code (or vice versa)
+Testing
+:   [Using pytest in marimo](https://docs.marimo.io/guides/testing/pytest/#testing-in-notebook) is straightforward, provided that each test cell contains only tests and nothing else.
 
-**Use For:** Connect concepts to implementation (and implementation to concepts)
+Math rendering
+:   marimo uses [KaTeX](https://katex.org/) rather than [MathJax](https://www.mathjax.org/) for rendering mathematics. The two systems are largely compatible but differ in some commands and environments. See the appendix for details.
 
-**Works For:** Learners who understand theory but struggle with coding (or vice versa)
+## Pedagogical Patterns
 
-**Format:** Notebook with scaffolding text and possibly some (scaffolded) code
+Much of this section is inspired by or taken from
+[*Teaching and Learning with Jupyter*](https://jupyter4edu.github.io/jupyter-edu-book/).
+We are grateful to its authors for making their work available under an open license.
 
-**Pro:** Low barrier to entry for learners with limited programming knowledge
+### Shift-Enter
 
-**Con:** Hard to get the level right for mixed-ability audience
+Learners start with a complete notebook and re-execute the cells in order, optionally filling in prose cells with analysis or description. This pattern is well suited to introducing new topics or checking understanding through warmup exercises, and works with any audience in a synchronous setting. It gives learners a working example immediately, though engagement tends to be low because learners are not yet making decisions.
 
-### Symbolic math
+### Fill in the Blanks
 
-**Description:** Use SymPy for symbolic math in notebook
+Some code cells are provided complete; learners must complete the rest. This reduces cognitive load by directing attention to a single concept, such as filtering a dataset, and works for any audience in assignments and lab sessions. The risk is that learners delegate the task to an AI tool, and the difficulty of the blanks can be hard to calibrate for a mixed-ability group.
 
-**Use For:** Extension of previous exercise: convert math to code or code to math
+### Tweak and Twiddle
 
-**Works For:** STEM students interested in theory
+Learners start with a complete, working notebook and are asked to alter parameters in order to achieve a specified goal. This pattern supports compare-and-contrast exercises and the acquisition of domain knowledge. It is particularly effective for learners who have domain knowledge but little programming experience, in fixed-time workshop exercises or pair programming sessions. It helps learners overcome anxiety about code. The main difficulties are that learners may not know where to start, or may spend time following unproductive tangents.
 
-**Format:** Any
+### Notebook as App
 
-**Pro:** Introduce another real-world tool
+The notebook is presented as an interactive dashboard, with prose kept in a separate document so the interface looks like a standalone application. This pattern is designed for non-programmers exploring datasets. It can replace slides in a lecture if the instructor knows the material well enough to navigate live, or it can be used after a physical lab experiment for data analysis. It requires less effort to build than a custom UI, but it demands thorough testing and does not develop learners' programming skills.
 
-**Con:** Math in SymPy is yet another thing to learn
+### Top-Down Delivery
 
-### Numerical methods / simulation
+Learners are given just enough control to reach a motivating result quickly. The goal is engagement on the first day of a course or workshop. This pattern works for any audience but is most effective with learners who have limited programming experience, in tutorials and synchronous workshops. Student engagement is the main advantage; the main challenge is finding the right level of detail for a group with mixed abilities.
 
-**Description:** Use calculation or simulation instead of formulaic analysis
+### Coding as Translation
 
-**Use For:** Make concepts tangible before introducing mathematical abstraction
+Learners convert prose to code, or code to prose. The purpose is to connect concepts to implementations and implementations to concepts. It is well suited to learners who understand theory but struggle with coding, or the reverse. A notebook with scaffolding text and possibly some pre-written code works well as the format. The barrier to entry is low for learners with limited programming background; the challenge, again, is calibrating difficulty for a mixed-ability group.
 
-**Works For:** Learners with some programming skill
+### Symbolic Math
 
-**Format:** Any
+Learners use SymPy to do symbolic mathematics inside the notebook, extending the coding-as-translation pattern to include converting mathematical expressions to code or code to mathematical expressions. This works well for STEM students interested in theory and fits any format. It introduces another real-world tool, but SymPy's syntax is yet another thing to learn on top of the mathematics itself.
 
-**Pro:** Going from specific to general is often more engaging and approachable
+### Numerical Methods and Simulation
 
-**Con:** Requires programming skill; can be hard to debug
+Learners use calculation or simulation rather than closed-form analysis to make a concept tangible before the mathematical abstraction is introduced. This requires some programming skill and fits any format. Going from specific to general is often more engaging and approachable than the reverse, but debugging numerical code can be difficult.
 
 ### Learn an API
 
-**Description:** Introduce a key API example by example
-
-**Use For:** Put focus on tools to be used in other places / lessons
-
-**Works For:** Learners with some programming skill (and patience)
-
-**Format:** Examples in order of increasing complexity or decreasing frequency of use
-
-**Pro:** Guide learning in a sensible order (which AI sometimes struggles with)
-
-**Con:** “Can’t see the forest for the trees”; learners may prefer just asking AI as needed
-
-### Choose your data
-
-**Description:** Replace the dataset used in a notebook with another one (which may require some modifications to code)
+A key library or API is introduced example by example, in order of increasing complexity or decreasing frequency of use. The purpose is to direct learner attention toward tools they will use in other parts of the course. This works for learners with some programming skill and patience. It guides learning in a sensible order, which AI tools sometimes struggle to provide on their own. The risk is that learners lose sight of the larger goal, or prefer to ask an AI for help as needed rather than building systematic knowledge.
 
-**Use For:** Engagement
+### Choose Your Data
 
-**Works For:** Learners with specific domain interest (e.g., sports analytics)
+Learners replace the dataset in a provided notebook with one of their own choosing, possibly making some modifications to the code. The goal is engagement through personal relevance, and it works well for learners with a specific domain interest such as sports analytics. A common structure is a shared first half followed by independent exploration, sometimes leading to presentations. It improves self-efficacy, but learners may struggle to find suitable data, encounter data that is too messy to work with, or have interests that do not overlap enough for a shared debrief.
 
-**Format:** Common first half, learners explore on their own for second half; learners create presentations to share with others
+### Test-Driven Learning
 
-**Pro:** Improves self-efficacy; leverages engagement with personal interests
+The instructor provides a notebook full of tests; learners must write code that makes those tests pass. This teaches learners to think in terms of a specification. It works for learners who want firm goalposts and fits homework exercises well. The task is well-defined and easy to stay focused on, but it is very easy for learners to have an AI generate the code without understanding it.
 
-**Con:** Can’t find data, data is too messy, learners’ interest don’t overlap
+A useful pattern is to place a stub function in one cell and pytest tests in a separate cell. Because of marimo's reactive execution, every time the learner edits their implementation the tests rerun automatically, giving immediate feedback on correctness without giving away the answer. For example, the stub cell might contain:
 
-### Test-driven learning
-
-**Description:** Instructor provides notebook full of tests; learners must write code to make those tests pass (e.g., handle messy data)
-
-**Use For:** Think in terms of a spec
-
-**Works For:** Learners who want firm goalposts
-
-**Format:** Notebook full of test cases with empty cells (and function stubs) for code; works well for homework exercises
-
-**Pro:** Helps learners stay focused on well-defined task
-
-**Con:** Very easy to have AI generate the code without understanding it
-
-### Bug hunt
-
-**Description:** Give learners a notebook with one or more bugs (which can include misleading prose)
-
-**Use For:** Developing critical reading skills (especially important for learners using AI)
-
-**Works For:** Learners with enough programming experience to be able to debug systematically
-
-**Format:** Works well as homework exercise
-
-**Pro:** Some learners enjoy playing detective; extremely useful skill to learn
-
-**Con:** Hard to calibrate bug difficulty to learner level; hard for learners to know when they’re done
-
-### Adversarial programming
-
-**Description:** Given a notebook full of code, write tests that break it (reverse of bug hunt)
+```python
+def add(x, y):
+    """Return the sum of x and y."""
+    # your code here
+    pass
+```
 
-**Use For:** Learning critical thinking
+and the test cell:
 
-**Works For:** Learners with enough programming experience to be able to debug systematically
+```python
+def test_add_integers():
+    assert add(5, 6) == 11
 
-**Format:** Works well as homework exercise
+def test_add_floats():
+    assert isinstance(add(4, 2.1), float)
+```
 
-**Pro:** Helps learners appreciate how hard it is to write robust code; improves their debugging skills
+### Bug Hunt
 
-**Con:** Learners can break code in repetitive ways (e.g., provide several inputs that trigger the same flaw)
+Learners are given a notebook with one or more bugs, which may include misleading prose. The purpose is to develop critical reading skills, which is especially important for learners who regularly use AI tools. It requires enough programming experience to debug systematically and works well as a homework exercise. Some learners find the detective aspect genuinely engaging, and the skill is extremely valuable. The main challenges are calibrating bug difficulty and helping learners know when they are done.
 
-## Acknowledgments
+### Adversarial Programming
 
-Much of this is inspired by or taken from
-[*Teaching and Learning with Jupyter*](https://jupyter4edu.github.io/jupyter-edu-book/).
+Given a notebook full of code, learners write tests designed to break it. This is the reverse of the bug hunt. The purpose is to develop critical thinking, and it requires the same level of programming experience. It works well as a homework exercise. It helps learners appreciate the difficulty of writing robust code and sharpens their debugging skills, but learners sometimes find repetitive ways to break the code rather than probing for distinct failure modes.
 
 ## Appendix: Learner Personas
 
-### Anya Academic
-
-**Background:** Biology professor at mid-sized state university; teaches undergrad microbiology and biostatistics classes, both of which emphasize data management and visualization.
-
-**Relevant Experience:** Used R for 15 years, switched to Python three years ago, mostly self-taught. Frequently remixes teaching material she finds online, particularly examples.
+The three profiles below outlines who we're trying to help and how.
 
-**Goals**
-
-1. Wants to equip her students with modern skills, especially AI-related, both because she thinks they’re important and to increase student engagement.
-
-2. Wants more recognition at her university for her teaching work, which she believes is more likely to come from publishable innovation than from high student evaluations.
-
-3. Would like to get student engagement back to pre-COVID levels; she feels that today’s cohorts don’t know each other as well and aren’t as excited about material because of the shift to online education.
+### Anya Academic
 
-**Complications**
+Anya is a biology professor at a mid-sized state university who teaches undergraduate microbiology and biostatistics, both of which emphasize data management and visualization. She used R for fifteen years before switching to Python three years ago, largely through self-teaching, and she routinely remixes teaching material she finds online.
 
-1. Is concerned about tool setup and maintenance overheads. Doesn't have time to completely rewrite courses, so will only move over if there's an incremental migration path that allows her to back out if thing don't appear to be working.
+She wants to equip her students with modern skills, including AI-related tools, both because she sees them as important and because she hopes they will increase student engagement. She is also looking for more recognition at her university for her teaching work, which she believes is more likely to come from publishable innovation than from high student evaluations. She would like to restore the level of student engagement she saw before the pandemic, which she attributes in part to the shift toward online education reducing social cohesion in her cohorts.
 
-2. Anya's department has two overworked IT staff, and nothing at her university is allowed to go beyond the pilot phase if it doesn't integrate with the LMS somehow.
+Her main concern is tool setup and maintenance overhead. She does not have time to rewrite courses wholesale, so she will only migrate to a new tool if there is an incremental path that allows her to back out if things are not working. Her department has only two IT staff, and nothing at her university can move beyond a pilot without integrating with the institution's learning management system.
 
 ### Ellis Engineer
 
-**Background:** Senior undergraduate in mechanical engineering who just returned to school from their third and final co-op placement. They are very excited about drones.
+Ellis is a senior undergraduate in mechanical engineering who has just returned from their third co-op placement and is very interested in drones. They used Jupyter notebooks with Google Colab in their second semester and are comfortable with NumPy and Altair, though they have done roughly as many courses in MATLAB and AutoCAD as in Python.
 
-**Relevant Experience:** Used Jupyter notebooks with Colab in their second semester. They are comfortable with NumPy and Altair and has bumped into Pandas, but has done as many classes with MATLAB and AutoCAD as with Python.
+Ellis wants to build an impressive senior project to strengthen their graduate school application. They have seen custom widgets in notebooks and are willing to invest time in learning to build one with AI support. They also want to explore small-craft aerodynamics, particularly feedback stability problems, both as a personal interest and as a way to become known in the drone community.
 
-**Goals**
-
-1. Ellis wants to create an impressive senior project to secure themself a place in a good graduate program (which they think is essential to doing interesting work with drones). They have seen custom widgets in notebooks, and are willing to invest some time to learn how to build one with AI support.
-
-2. They also want to explore small-craft aerodynamics, particularly feedback stability problems, out of personal interest and as a way to become part of the “serious” drone community.
-
-**Complications**
-
-Having spent several months convinced that Lisp was the language of the future, Ellis is leery of investing too much in new technologies just because they’re cool.
+Having spent a period convinced that Lisp was the language of the future, Ellis is now cautious about investing heavily in new technologies purely because they seem exciting.
 
 ### Nang Newbie
 
-**Background:** Undergraduate business student; decided not to minor in CS because "AI is going to eat all those jobs". Nang chooses courses, tools, and interests based primarily on what the web tells him potential future employers are going to look for. He routinely uses ChatGPT for help with homework.
-
-**Relevant Experience:** Used Scratch in middle school and did one CS class in high school that covered HTML and a bit of Python. He just finished an intro stats class that used Pandas, which to his surprise he enjoyed enough to sign up for the sequel.
-
-**Goals**
-
-1. Nang wants to be able to do homework assignments more quickly and with less effort (hence his interest in ChatGPT).
-
-2. He wants to learn how to explore and analyze sports statistics for fun (he's a keen basketball fan), and to share what he finds with like-minded fans through online forums.
+Nang is an undergraduate business student who decided against minoring in computer science because he believes AI will take most programming jobs. He chooses courses, tools, and interests largely based on what he reads about future employer demand, and he routinely uses ChatGPT for help with homework. He used Scratch in middle school and covered HTML and basic Python in a high school CS course. He just finished an introductory statistics course that used Pandas, which he enjoyed enough to sign up for the follow-on course.
 
-**Complications**
+He wants to complete assignments more quickly and with less effort. He also wants to learn how to explore and analyze sports statistics for fun, as a keen basketball fan, and to share findings with other fans through online forums.
 
-Nang is taking five courses and volunteering with two campus clubs (one for the sake of his CV, and one because of his passion for basketball), so he is chronically over-committed.
+Nang is taking five courses and volunteering with two campus clubs, one for his CV and one out of genuine passion for basketball, so he is chronically over-committed.
 
 ## Appendix: KaTeX vs. MathJax
 
-marimo uses [KaTeX](https://katex.org/) for rendering math (faster, slightly narrower coverage, silent errors) rather than [MathJax](https://www.mathjax.org/).
+marimo uses [KaTeX](https://katex.org/) for rendering math rather than [MathJax](https://www.mathjax.org/). KaTeX is faster and has slightly narrower coverage, and it fails silently when it encounters an unsupported command.
 
-### Use raw strings
+### Use Raw Strings
 
 LaTeX lives in Python strings in marimo, so use `r"..."` to preserve backslashes:
 
 ```python
-mo.md(r"$\\frac{1}{2}$")   # ✅
-mo.md("$\\frac{1}{2}$")    # ❌ — \\f is a form-feed character
+mo.md(r"$\frac{1}{2}$")   # correct
+mo.md("$\frac{1}{2}$")    # wrong: \f is a form-feed character
 ```
 
-### MathJax → KaTeX
+### MathJax to KaTeX
 
 | Category | MathJax | KaTeX |
 | --- | --- | --- |
-| Text | `\\mbox`, `\\bbox` | `\\text{}` |
-| Text style | `\\textsc`, `\\textsl` | `\\text{}` |
-| Environments | `\\begin{eqnarray}` | `\\begin{align}` |
-|  | `\\begin{multline}` | `\\begin{gather}` |
-| References | `\\label`, `\\eqref`, `\\ref` | `\\tag{}` for manual numbering |
-| Arrays | `\\cline`, `\\multicolumn`, `\\hfill`, `\\vline` | — |
-| Macros | `\\DeclareMathOperator` | `\\operatorname{}` inline |
-|  | `\\newenvironment` | — |
-| Spacing | `\\mspace`, `\\setlength`, `\\strut`, `\\rotatebox` | — |
-| Conditionals | `\\if`, `\\else`, `\\fi`, `\\ifx` | — |
+| Text | `\mbox`, `\bbox` | `\text{}` |
+| Text style | `\textsc`, `\textsl` | `\text{}` |
+| Environments | `\begin{eqnarray}` | `\begin{align}` |
+|  | `\begin{multline}` | `\begin{gather}` |
+| References | `\label`, `\eqref`, `\ref` | `\tag{}` for manual numbering |
+| Arrays | `\cline`, `\multicolumn`, `\hfill`, `\vline` | not supported |
+| Macros | `\DeclareMathOperator` | `\operatorname{}` inline |
+|  | `\newenvironment` | not supported |
+| Spacing | `\mspace`, `\setlength`, `\strut`, `\rotatebox` | not supported |
+| Conditionals | `\if`, `\else`, `\fi`, `\ifx` | not supported |
 
-These *do* work in KaTeX (despite outdated claims): `\\newcommand`, `\\def`, `\\hbox`, `\\hskip`, `\\cal`, `\\pmb`, `\\begin{equation}`, `\\begin{split}`, `\\operatorname*`.
+The following commands do work in KaTeX despite claims to the contrary in some older references: `\newcommand`, `\def`, `\hbox`, `\hskip`, `\cal`, `\pmb`, `\begin{equation}`, `\begin{split}`, `\operatorname*`.
 
-### Shared macros across cells
+### Shared Macros Across Cells
 
-`\\newcommand` works inline. For cross-cell reuse, use `mo.latex(filename="macros.tex")` in the same cell as `import marimo`.
+`\newcommand` works inline within a single cell. For macros that need to be available across multiple cells, use `mo.latex(filename="macros.tex")` in the same cell as your `import marimo` statement.
 
-### Migration checklist
+### Migration Checklist
 
-1. Find-replace `\\mbox{` → `\\text{`
-2. Use raw strings (`r"..."`)
-3. Replace `\\begin{eqnarray}` → `\\begin{align}`
-4. Replace `\\DeclareMathOperator` → `\\operatorname{}`
-5. Remove `\\label`/`\\eqref` → use `\\tag{}` if needed
-6. Visually verify — KaTeX fails silently
+1. Find and replace `\mbox{` with `\text{`.
+2. Wrap all LaTeX strings in raw string literals (`r"..."`).
+3. Replace `\begin{eqnarray}` with `\begin{align}`.
+4. Replace `\DeclareMathOperator` with `\operatorname{}`.
+5. Remove `\label` and `\eqref`; use `\tag{}` where manual numbering is needed.
+6. Verify the output visually, since KaTeX fails silently.
 
 ### References
 
 - [KaTeX Support Table](https://katex.org/docs/support_table) — definitive command lookup
-- [KaTeX Unsupported Features](https://github.com/KaTeX/KaTeX/wiki/Things-that-KaTeX-does-not-(yet)-support)
+- [KaTeX Unsupported Features](https://github.com/KaTeX/KaTeX/wiki/Things-that-KaTeX-does-not-(yet)-support)

polars/03_loading_data.py

@@ -493,12 +493,11 @@ def _(folder, lz, pl):
     _df, _df2, _df3 = pl.collect_all([lz, lz2, lz3])
 
     # Sinking multiple LazyFrames into different destinations
-    sinks = [
-        lz.sink_csv(folder / "data_1.csv", lazy=True),
-        lz2.sink_csv(folder / "data_2.csv", lazy=True),
-        lz3.sink_csv(folder / "data_3.csv", lazy=True),
-    ]
-    _ = pl.collect_all(sinks)
+    # (polars 1.23+ removed lazy=True from sink methods; each sink now executes immediately)
+    lz.sink_csv(folder / "data_1.csv")
+    lz2.sink_csv(folder / "data_2.csv")
+    lz3.sink_csv(folder / "data_3.csv")
+    sinks = []
     return (sinks,)
 
 
@@ -520,9 +519,10 @@ async def _(lz):
 
 @app.cell
 async def _(folder, lz, pl, sinks):
-    # If you want to write to a file, use `lz.sink_format(lazy=True)` followed by `...collect_async()` or `pl.collect_all_async(...)`
-    _ = await lz.sink_csv(folder / "data_from_async.csv", lazy=True).collect_async()
-    _ = await pl.collect_all_async(sinks)
+    # polars 1.23+ removed lazy=True from sink methods; sinks now execute immediately
+    lz.sink_csv(folder / "data_from_async.csv")
+    if sinks:
+        _ = await pl.collect_all_async(sinks)
     return
 
 

polars/05_reactive_plots.py

@@ -61,22 +61,25 @@ def _(mo):
 
 
 @app.cell
-def _(lz, pl):
-    df = (
-        lz
-        # Filter data we consider relevant (somewhat arbitrary in this example)
-        .filter(pl.col("explicit") == False)
-        .drop("Unnamed: 0", "track_id", "explicit")
-        .with_columns(
-            # Perform whichever transformations you want  (again somewhat arbitrary in this example)
-            # Convert the duration from milliseconds to seconds (int)
-            pl.col("duration_ms").floordiv(1_000).alias("duration_seconds"),
-            # Convert the popularity from an integer 0 ~ 100 to a percentage 0 ~ 1.0
-            pl.col("popularity").truediv(100),
+def _(lz, mo, pl):
+    try:
+        df = (
+            lz
+            # Filter data we consider relevant (somewhat arbitrary in this example)
+            .filter(pl.col("explicit") == False)
+            .drop("Unnamed: 0", "track_id", "explicit")
+            .with_columns(
+                # Perform whichever transformations you want  (again somewhat arbitrary in this example)
+                # Convert the duration from milliseconds to seconds (int)
+                pl.col("duration_ms").floordiv(1_000).alias("duration_seconds"),
+                # Convert the popularity from an integer 0 ~ 100 to a percentage 0 ~ 1.0
+                pl.col("popularity").truediv(100),
+            )
+            # lastly, download (if needed) and collect into memory
+            .collect()
         )
-        # lastly, download (if needed) and collect into memory
-        .collect()
-    )
+    except Exception as e:
+        mo.stop(True, mo.md(f"**Failed to load data from HuggingFace:** {e}"))
     df
     return (df,)
 

polars/07_querying_with_sql.py

@@ -2,7 +2,7 @@
 # requires-python = ">=3.12"
 # dependencies = [
 #     "duckdb==1.4.4",
-#     "kagglehub==0.3.13",
+#     "kagglehub==1.0.0",
 #     "marimo",
 #     "polars==1.24.0",
 #     "pyarrow==22.0.0",

polars/11_missing_data.py

@@ -743,28 +743,34 @@ def _(pl):
 
 
 @app.cell
-def _(pl, raw_stations):
-    dirty_stations = raw_stations.select(
-        pl.col("id_estacao").alias("station"),
-        pl.col("estacao").alias("name"),
-        pl.col("latitude").alias("lat"),
-        pl.col("longitude").alias("lon"),
-        pl.col("cota").alias("altitude"),
-        pl.col("situacao").alias("situation"),
-        pl.col("endereco").alias("address"),
-        pl.col("data_inicio_operacao").alias("operation_start_date"),
-        pl.col("data_fim_operacao").alias("operation_end_date"),
-    ).collect()
+def _(mo, pl, raw_stations):
+    try:
+        dirty_stations = raw_stations.select(
+            pl.col("id_estacao").alias("station"),
+            pl.col("estacao").alias("name"),
+            pl.col("latitude").alias("lat"),
+            pl.col("longitude").alias("lon"),
+            pl.col("cota").alias("altitude"),
+            pl.col("situacao").alias("situation"),
+            pl.col("endereco").alias("address"),
+            pl.col("data_inicio_operacao").alias("operation_start_date"),
+            pl.col("data_fim_operacao").alias("operation_end_date"),
+        ).collect()
+    except Exception as e:
+        mo.stop(True, mo.md(f"**Failed to load stations data from HuggingFace:** {e}"))
     return (dirty_stations,)
 
 
 @app.cell
-def _(pl, raw_weather):
-    dirty_weather_naive = raw_weather.select(
-        pl.col("id_estacao").alias("station"),
-        pl.col("acumulado_chuva_15_min").alias("accumulated_rain_15_minutes"),
-        pl.concat_str("data_particao", pl.lit("T"), "horario").str.to_datetime(time_zone=None).alias("datetime"),
-    ).collect()
+def _(mo, pl, raw_weather):
+    try:
+        dirty_weather_naive = raw_weather.select(
+            pl.col("id_estacao").alias("station"),
+            pl.col("acumulado_chuva_15_min").alias("accumulated_rain_15_minutes"),
+            pl.concat_str("data_particao", pl.lit("T"), "horario").str.to_datetime(time_zone=None).alias("datetime"),
+        ).collect()
+    except Exception as e:
+        mo.stop(True, mo.md(f"**Failed to load weather data from HuggingFace:** {e}"))
     return (dirty_weather_naive,)
 
 

polars/16_lazy_execution.py

@@ -291,7 +291,10 @@ def _(log_data, pl):
 
 @app.cell
 def _(log_data_erroneous):
-    log_data_erroneous.collect()
+    try:
+        log_data_erroneous.collect()
+    except Exception as e:
+        print(f"{type(e).__name__}: {e}")
     return
 
 
@@ -307,12 +310,15 @@ def _(mo):
 
 @app.cell
 def _(log_data, pl):
-    (
-        log_data.pivot(index="time", on="request_code", 
-                   values="status", aggregate_function="len")
-                .filter(pl.col("POST").is_null())
-                .collect()
-    )
+    try:
+        (
+            log_data.pivot(index="time", on="request_code",
+                       values="status", aggregate_function="len")
+                    .filter(pl.col("POST").is_null())
+                    .collect()
+        )
+    except Exception as e:
+        print(f"{type(e).__name__}: {e}")
     return
 
 
@@ -438,7 +444,10 @@ def _(mo):
 
 @app.cell
 def _(a_query):
-    a_query.collect(engine="streaming")
+    try:
+        a_query.collect(engine="streaming")
+    except Exception as e:
+        print(f"{type(e).__name__}: {e}")
     return
 
 
@@ -491,21 +500,16 @@ def _(mo):
 @app.cell(hide_code=True)
 def _(mo):
     mo.md(r"""
-    The results of a query from a lazyframe can be saved in streaming mode using `sink_*` (e.g. `sink_parquet`) functions. Sinks support saving data to disk or cloud, and are especially helpful with large datasets. The data being sunk can also be partitioned into multiple files if needed, after specifying a suitable partitioning strategy, as shown below.
+    The results of a query from a lazyframe can be saved in streaming mode using `sink_*` (e.g. `sink_parquet`) functions. Sinks support saving data to disk or cloud, and are especially helpful with large datasets. To write output partitioned into multiple files by a column key, collect the LazyFrame first and use `DataFrame.write_parquet` with the `partition_by` parameter, as shown below.
     """)
     return
 
 
 @app.cell
-def _(a_query, pl):
-    (
-        a_query
-            .sink_parquet(
-                pl.PartitionMaxSize(
-                    "log_data_filtered_{part}.parquet",
-                    max_size=1_000
-                )
-            )
+def _(a_query):
+    a_query.collect().write_parquet(
+        "log_data_filtered/",
+        partition_by="request_code",
     )
     return
 
@@ -520,9 +524,9 @@ def _(mo):
 
 @app.cell
 def _(a_query, pl):
-    _q1 = a_query.sink_parquet("log_data_filtered.parquet", lazy=True)
-    _q2 = a_query.sink_ipc("log_data_filtered.ipc", lazy=True)
-    pl.collect_all([_q1, _q2])
+    # polars 1.23+ removed lazy=True from sink methods; each sink executes immediately
+    a_query.sink_parquet("log_data_filtered.parquet")
+    a_query.sink_ipc("log_data_filtered.ipc")
     return
 
 

queueing/07_late_merge.py

@@ -240,9 +240,9 @@ def _(ArrivalStream, Environment, MergeServer, Queue, SEED, SIM_TIME, random):
         blocked = []
 
         if zipper:
-            lanes = [Queue(env, max_capacity=k), Queue(env, max_capacity=k)]
+            lanes = [Queue(env, capacity=k), Queue(env, capacity=k)]
         else:
-            lanes = [Queue(env, max_capacity=k)]
+            lanes = [Queue(env, capacity=k)]
         ArrivalStream(env, lanes, sojourn_times, blocked, zipper)
         MergeServer(env, lanes, zipper)
         env.run(until=SIM_TIME)

queueing/11_tandem_queue.py

@@ -189,7 +189,7 @@ def _(Environment, Queue, SIM_TIME, Source, Stage1, Stage2):
     def simulate(buffer_capacity):
         env = Environment()
         input_q = Queue(env)
-        middle_q = Queue(env, max_capacity=buffer_capacity)
+        middle_q = Queue(env, capacity=buffer_capacity)
         s2_idle = []
         completions = []
         Source(env, input_q)

tools/01_widgets.py

@@ -0,0 +1,471 @@
+# /// script
+# requires-python = "==3.12"
+# dependencies = [
+#     "anywidget",
+#     "marimo",
+#     "marimo-learn",
+# ]
+# ///
+
+"""
+Example Marimo Notebook: Education Widgets Demo
+
+This notebook demonstrates all formative assessment widgets.
+Run with: marimo edit demo.py
+"""
+
+import marimo
+
+__generated_with = "0.20.4"
+app = marimo.App()
+
+
+@app.cell
+def _():
+    import marimo as mo
+    from marimo_learn import (
+        Color,
+        ConceptMapWidget,
+        FlashcardWidget,
+        LabelingWidget,
+        MatchingWidget,
+        MultipleChoiceWidget,
+        NumericEntryWidget,
+        OrderingWidget,
+        PredictThenCheckWidget,
+        World,
+    )
+
+    return (
+        Color,
+        ConceptMapWidget,
+        FlashcardWidget,
+        LabelingWidget,
+        MatchingWidget,
+        MultipleChoiceWidget,
+        NumericEntryWidget,
+        OrderingWidget,
+        PredictThenCheckWidget,
+        World,
+    )
+
+
+@app.cell
+def _(mo):
+    mo.md("""
+    # Educational Widgets Demo
+
+    This notebook demonstrates widgets in marimo_learn.
+    """)
+    return
+
+
+# Spiral
+@app.cell
+def _(Color, World, mo):
+    _world = World()
+
+    async def _spiral(world, turtle):
+        colors = list(Color)
+        for i in range(70):
+            if i % 10 == 0:
+                turtle.set_color(colors[(i // 10) % len(colors)])
+            await turtle.forward(i * 2.8)
+            turtle.right(91)
+
+    _world.set_coroutine(_spiral)
+    mo.ui.anywidget(_world)
+
+
+@app.cell
+def _(mo):
+    mo.md("""
+    ## Concept Map
+    """)
+    return
+
+
+@app.cell
+def _(ConceptMapWidget, mo):
+    concept_map = mo.ui.anywidget(
+        ConceptMapWidget(
+            question="Map the relationships between these Python concepts:",
+            concepts=["function", "parameter", "argument", "return value", "call site"],
+            terms=["defines", "accepts", "supplies", "produces", "invokes"],
+            correct_edges=[
+                {"from": "function", "to": "parameter", "label": "accepts"},
+                {"from": "function", "to": "return value", "label": "produces"},
+                {"from": "call site", "to": "argument", "label": "supplies"},
+                {"from": "argument", "to": "parameter", "label": "defines"},
+                {"from": "call site", "to": "function", "label": "invokes"},
+            ],
+        )
+    )
+    concept_map
+    return (concept_map,)
+
+
+@app.cell
+def _(concept_map, mo):
+    def concept_map_msg(widget):
+        val = widget.value.get("value") or {}
+        score = val.get("score")
+        total = val.get("total", 5)
+        if score is None:
+            return "Draw connections between concepts to see your score."
+        msg = f"**{score}/{total}** correct connection{'s' if total != 1 else ''}"
+        if val.get("correct"):
+            msg += " — complete!"
+        return msg
+
+    mo.md(concept_map_msg(concept_map))
+    return
+
+
+@app.cell
+def _(mo):
+    mo.md("""
+    ## Flashcard Deck
+    """)
+    return
+
+
+@app.cell
+def _(FlashcardWidget, mo):
+    flashcard_deck = mo.ui.anywidget(
+        FlashcardWidget(
+            question="Python Concepts — rate yourself on each card:",
+            cards=[
+                {
+                    "front": "What does a list comprehension look like?",
+                    "back": "[expr for item in iterable if condition] — e.g., [x**2 for x in range(10) if x % 2 == 0]",
+                },
+                {
+                    "front": "What is the difference between a list and a tuple?",
+                    "back": "Lists are mutable (can be changed after creation); tuples are immutable (cannot be changed).",
+                },
+                {
+                    "front": "What does the `*args` parameter do in a function definition?",
+                    "back": "It collects any number of positional arguments into a tuple named `args`.",
+                },
+                {
+                    "front": "What is a Python generator?",
+                    "back": "A function that uses `yield` to produce values one at a time, pausing between each, without building the full sequence in memory.",
+                },
+                {
+                    "front": "What does `if __name__ == '__main__':` do?",
+                    "back": "It runs the indented code only when the file is executed directly, not when it is imported as a module.",
+                },
+                {
+                    "front": "What is the difference between `is` and `==` in Python?",
+                    "back": "`==` tests value equality; `is` tests identity (whether two names refer to the exact same object in memory).",
+                },
+            ],
+            shuffle=True,
+        )
+    )
+    flashcard_deck
+    return (flashcard_deck,)
+
+
+@app.cell
+def _(flashcard_deck, mo):
+    def flashcard_progress(widget):
+        val = widget.value.get("value") or {}
+        results = val.get("results", {})
+        counts = {"got_it": 0, "almost": 0, "no": 0}
+        for r in results.values():
+            counts[r["rating"]] = counts.get(r["rating"], 0) + 1
+        return len(results), counts, val.get("complete", False)
+
+    _rated, _counts, _complete = flashcard_progress(flashcard_deck)
+    mo.md(f"""
+    **Progress:** {_rated} card(s) rated —
+    ✓ Got it: {_counts["got_it"]}  
+    ~ Almost: {_counts["almost"]}  
+    ✗ No: {_counts["no"]}
+    {"  🎉 Deck complete!" if _complete else ""}
+    """)
+    return
+
+
+@app.cell
+def _(mo):
+    mo.md("""
+    ## Labeling Question
+    """)
+    return
+
+
+@app.cell
+def _(LabelingWidget, mo):
+    labeling_question = mo.ui.anywidget(
+        LabelingWidget(
+            question="Label the parts of this Python code:",
+            labels=[
+                "Variable declaration",
+                "Function call",
+                "String literal",
+                "Arithmetic operation",
+            ],
+            text_lines=[
+                "name = 'Alice'",
+                "age = 25",
+                "result = age + 5",
+                "print(name)",
+            ],
+            correct_labels={
+                0: [0, 2],  # Line 0: labels 0 and 2
+                1: [0],  # Line 1: label 0
+                2: [0, 3],  # Line 2: labels 0 and 3
+                3: [1],  # Line 3: label 1
+            },
+        )
+    )
+    labeling_question
+    return (labeling_question,)
+
+
+@app.cell
+def _(labeling_question, mo):
+    _val = labeling_question.value.get("value") or {}
+    _total = _val.get("total", 0)
+    _msg = f"Score: {_val['score']}/{_total}" if _total > 0 else "Not submitted yet"
+    mo.md(f"**{_msg}**")
+    return
+
+
+@app.cell
+def _(mo):
+    mo.md("""
+    ## Matching Question
+    """)
+    return
+
+
+@app.cell
+def _(MatchingWidget, mo):
+    matching_question = mo.ui.anywidget(
+        MatchingWidget(
+            question="Match the programming languages to their primary paradigms:",
+            left=["Python", "Haskell", "C", "SQL"],
+            right=["Functional", "Procedural", "Multi-paradigm", "Declarative"],
+            correct_matches={0: 2, 1: 0, 2: 1, 3: 3},
+        )
+    )
+    matching_question
+    return (matching_question,)
+
+
+@app.cell
+def _(matching_question, mo):
+    _val = matching_question.value.get("value") or {}
+    _msg = f"Score: {_val['score']}/{_val['total']}" if _val else "Not answered yet"
+    mo.md(f"**{_msg}**")
+    return
+
+
+@app.cell
+def _(mo):
+    mo.md("""
+    ## Multiple Choice Question
+    """)
+    return
+
+
+@app.cell
+def _(MultipleChoiceWidget, mo):
+    multiple_choice_question = mo.ui.anywidget(
+        MultipleChoiceWidget(
+            question="What is the capital of France?",
+            options=["London", "Berlin", "Paris", "Madrid"],
+            correct_answer=2,
+            explanation="Paris has been the capital of France since the 12th century.",
+        )
+    )
+    multiple_choice_question
+    return (multiple_choice_question,)
+
+
+@app.cell
+def _(multiple_choice_question, mo):
+    _val = multiple_choice_question.value.get("value") or {}
+    if _val.get("answered"):
+        _msg = "Score: 1/1" if _val.get("correct") else "Score: 0/1"
+    else:
+        _msg = "Not answered yet"
+    mo.md(f"**{_msg}**")
+    return
+
+
+@app.cell
+def _(mo):
+    mo.md("""
+    ## Ordering Question
+    """)
+    return
+
+
+@app.cell
+def _(OrderingWidget, mo):
+    ordering_question = mo.ui.anywidget(
+        OrderingWidget(
+            question="Arrange these steps of the scientific method in the correct order:",
+            items=[
+                "Ask a question",
+                "Do background research",
+                "Construct a hypothesis",
+                "Test with an experiment",
+                "Analyze data",
+                "Draw conclusions",
+            ],
+            shuffle=True,
+        )
+    )
+    ordering_question
+    return (ordering_question,)
+
+
+@app.cell
+def _(mo, ordering_question):
+    _val = ordering_question.value.get("value") or {}
+    if _val.get("correct") is not None and _val.get("order"):
+        _msg = "Score: 1/1" if _val.get("correct") else "Score: 0/1"
+    else:
+        _msg = "Not answered yet"
+    mo.md(f"**{_msg}**")
+    return
+
+
+@app.cell
+def _(mo):
+    mo.md("""
+    ## Numeric Entry Question
+    """)
+    return
+
+
+@app.cell
+def _(NumericEntryWidget, mo):
+    numeric_entry_question = mo.ui.anywidget(
+        NumericEntryWidget(
+            question="How many bits are in one byte?",
+            correct_answer=8,
+            tolerance=0.5,
+            explanation="A byte consists of exactly 8 bits.",
+        )
+    )
+    numeric_entry_question
+    return (numeric_entry_question,)
+
+
+@app.cell
+def _(mo, numeric_entry_question):
+    _val = numeric_entry_question.value.get("value") or {}
+    if _val.get("answered"):
+        _msg = "Score: 1/1" if _val.get("ok") else "Score: 0/1"
+    else:
+        _msg = "Not answered yet"
+    mo.md(f"**{_msg}**")
+    return
+
+
+@app.cell
+def _(mo):
+    mo.md("""
+    ## Predict-Then-Check Question
+    """)
+    return
+
+
+@app.cell
+def _(PredictThenCheckWidget, mo):
+    predict_then_check_question = mo.ui.anywidget(
+        PredictThenCheckWidget(
+            question="What does this Python code print?",
+            code='words = ["one", "two", "three"]\nprint(len(words))',
+            output="3",
+            options=["2", "3", "['one', 'two', 'three']", "None"],
+            correct_answer=1,
+            explanations=[
+                "Wrong: len() counts all items; the list has three elements.",
+                "Correct: len() returns the number of items, which is 3.",
+                "Wrong: len() returns an integer count, not the list itself.",
+                "Wrong: len() always returns an integer, never None.",
+            ],
+        )
+    )
+    predict_then_check_question
+    return (predict_then_check_question,)
+
+
+@app.cell
+def _(mo, predict_then_check_question):
+    _val = predict_then_check_question.value.get("value") or {}
+    if _val.get("answered"):
+        _msg = "Score: 1/1" if _val.get("correct") else "Score: 0/1"
+    else:
+        _msg = "Not answered yet"
+    mo.md(f"**{_msg}**")
+    return
+
+
+@app.cell
+def _(mo):
+    mo.md("""
+    ---
+
+    ## Quiz Results Summary
+
+    You can access the values from all widgets to create a summary or scoring system.
+    """)
+    return
+
+
+@app.cell
+def _(
+    concept_map,
+    flashcard_deck,
+    matching_question,
+    multiple_choice_question,
+    mo,
+    numeric_entry_question,
+    ordering_question,
+    predict_then_check_question,
+):
+    def widget_val(widget):
+        return widget.value.get("value") or {}
+
+    def calculate_score():
+        score = 0
+        total = 0
+        for val, answered_key, correct_key in [
+            (widget_val(concept_map), "score", "correct"),
+            (widget_val(matching_question), "score", "correct"),
+            (widget_val(multiple_choice_question), "answered", "correct"),
+            (widget_val(ordering_question), "order", "correct"),
+            (widget_val(numeric_entry_question), "answered", "ok"),
+            (widget_val(predict_then_check_question), "answered", "correct"),
+        ]:
+            if val.get(answered_key) is not None and val.get(answered_key) is not False:
+                total += 1
+                if val.get(correct_key):
+                    score += 1
+        fc = widget_val(flashcard_deck)
+        if fc.get("results"):
+            total += 1
+            if fc.get("complete"):
+                score += 1
+        return score, total
+
+    score, total = calculate_score()
+    mo.md(f"""
+    ### Current Score: {score}/{total}
+
+    {"🎉 Perfect score!" if score == total and total > 0 else "Keep going!" if total > 0 else "Answer the questions above to see your score."}
+    """)
+    return
+
+
+if __name__ == "__main__":
+    app.run()

tools/02_turtles.py

@@ -0,0 +1,63 @@
+# /// script
+# requires-python = "==3.12"
+# dependencies = [
+#     "anywidget",
+#     "marimo",
+#     "marimo-learn",
+# ]
+# ///
+
+"""
+Example Marimo Notebook: Turtle Graphics
+"""
+
+import marimo
+
+__generated_with = "0.20.4"
+app = marimo.App()
+
+
+@app.cell
+def _():
+    import marimo as mo
+    from marimo_learn import (
+        Color,
+        World,
+    )
+
+    return (
+        Color,
+        World,
+    )
+
+
+@app.cell
+def _(mo):
+    mo.md("""
+    # Turtle Graphics Demo
+
+    This notebook demonstrates turtle graphics in marimo_learn.
+    See [the documentation](https://github.com/gvwilson/marimo_learn) for details.
+    """)
+    return
+
+
+# Spiral
+@app.cell
+def _(Color, World, mo):
+    _world = World()
+
+    async def _spiral(world, turtle):
+        colors = list(Color)
+        for i in range(70):
+            if i % 10 == 0:
+                turtle.set_color(colors[(i // 10) % len(colors)])
+            await turtle.forward(i * 2.8)
+            turtle.right(91)
+
+    _world.set_coroutine(_spiral)
+    mo.ui.anywidget(_world)
+
+
+if __name__ == "__main__":
+    app.run()

tools/index.md

@@ -0,0 +1,6 @@
+---
+title: Tools
+description: >
+    These notebooks show how to integrate educational widgets
+    and other tools into your notebooks.
+---

tools/wiggly.py

@@ -0,0 +1,201 @@
+# /// script
+# requires-python = ">=3.14"
+# dependencies = [
+#     "altair",
+#     "marimo",
+#     "matplotlib",
+#     "numpy",
+#     "pandas",
+#     "wigglystuff==0.3.1",
+# ]
+# ///
+import marimo
+
+__generated_with = "0.20.4"
+app = marimo.App(width="full")
+
+
+@app.cell(hide_code=True)
+def _(mo):
+    mo.md(r"""
+    # wigglystuff Widgets
+
+    This notebook demonstrates four widgets from the [wigglystuff](https://github.com/koaning/wigglystuff) package:
+    `Slider2D`, `Matrix`, `HoverZoom`, and `TextCompare`.
+    """)
+    return
+
+
+@app.cell
+def _():
+    import marimo as mo
+    import numpy as np
+    import pandas as pd
+    import altair as alt
+    import matplotlib
+    matplotlib.use("Agg")
+    import matplotlib.pyplot as plt
+    from wigglystuff import Slider2D, Matrix, HoverZoom, TextCompare
+    return HoverZoom, Matrix, Slider2D, TextCompare, alt, mo, np, pd, plt
+
+
+# ---------------------------------------------------------------------------
+# Slider2D
+# ---------------------------------------------------------------------------
+
+
+@app.cell(hide_code=True)
+def _(mo):
+    mo.md(r"""
+    ## Slider2D
+
+    A two-dimensional slider that lets you pick an (x, y) point inside a bounded region.
+    """)
+    return
+
+
+@app.cell
+def _(Slider2D, mo):
+    slider2d = mo.ui.anywidget(
+        Slider2D(
+            width=320,
+            height=320,
+            x_bounds=(-2.0, 2.0),
+            y_bounds=(-1.0, 1.5),
+        )
+    )
+    slider2d
+    return (slider2d,)
+
+
+@app.cell
+def _(mo, slider2d):
+    mo.callout(
+        f"x = {slider2d.x:.3f}, y = {slider2d.y:.3f};  bounds {slider2d.x_bounds} / {slider2d.y_bounds}"
+    )
+    return
+
+
+# ---------------------------------------------------------------------------
+# Matrix
+# ---------------------------------------------------------------------------
+
+
+@app.cell(hide_code=True)
+def _(mo):
+    mo.md(r"""
+    ## Matrix
+
+    An editable matrix widget. The demo below applies a 3x2 transformation matrix to
+    1000 random RGB colours and plots the result in 2D — a manual PCA explorer.
+    """)
+    return
+
+
+@app.cell
+def _(Matrix, mo, np, pd):
+    pca_mat = mo.ui.anywidget(Matrix(np.random.normal(0, 1, size=(3, 2)), step=0.1))
+    rgb_mat = np.random.randint(0, 255, size=(1000, 3))
+    color = ["#{0:02x}{1:02x}{2:02x}".format(r, g, b) for r, g, b in rgb_mat]
+    rgb_df = pd.DataFrame(
+        {"r": rgb_mat[:, 0], "g": rgb_mat[:, 1], "b": rgb_mat[:, 2], "color": color}
+    )
+    return color, pca_mat, rgb_df, rgb_mat
+
+
+@app.cell
+def _(alt, color, mo, pca_mat, pd, rgb_mat):
+    X_tfm = rgb_mat @ pca_mat.matrix
+    df_pca = pd.DataFrame({"x": X_tfm[:, 0], "y": X_tfm[:, 1], "c": color})
+    pca_chart = (
+        alt.Chart(df_pca)
+        .mark_point()
+        .encode(x="x", y="y", color=alt.Color("c:N", scale=None))
+        .properties(width=400, height=400)
+    )
+    mo.hstack([pca_mat, pca_chart])
+    return
+
+
+# ---------------------------------------------------------------------------
+# HoverZoom
+# ---------------------------------------------------------------------------
+
+
+@app.cell(hide_code=True)
+def _(mo):
+    mo.md(r"""
+    ## HoverZoom
+
+    A magnifying-glass overlay for any image or matplotlib figure.
+    Hover over the chart to read labels on densely packed points.
+    """)
+    return
+
+
+@app.cell
+def _(np, plt):
+    rng = np.random.default_rng(42)
+    N_POINTS = 200
+    hz_x = rng.normal(0, 1, N_POINTS)
+    hz_y = rng.normal(0, 1, N_POINTS)
+    labels = [f"p{i}" for i in range(N_POINTS)]
+
+    fig, ax = plt.subplots(figsize=(8, 6), dpi=200)
+    ax.scatter(hz_x, hz_y, s=12, alpha=0.6)
+    for xi, yi, label in zip(hz_x, hz_y, labels):
+        ax.annotate(label, (xi, yi), fontsize=4, alpha=0.7, ha="center", va="bottom")
+    ax.set_title(f"{N_POINTS} labeled points — hover to read the labels")
+    fig.tight_layout()
+    return (fig,)
+
+
+@app.cell
+def _(HoverZoom, fig, mo):
+    chart_widget = mo.ui.anywidget(HoverZoom(fig, zoom_factor=4.0, width=500))
+    chart_widget
+    return
+
+
+# ---------------------------------------------------------------------------
+# TextCompare
+# ---------------------------------------------------------------------------
+
+
+@app.cell(hide_code=True)
+def _(mo):
+    mo.md(r"""
+    ## TextCompare
+
+    A side-by-side text comparison widget that highlights matching passages between two texts.
+    Useful for plagiarism detection, finding shared passages, or comparing document versions.
+    Hover over a highlighted match in one panel to see the corresponding match in the other.
+    """)
+    return
+
+
+@app.cell
+def _(TextCompare, mo):
+    text_a = """The quick brown fox jumps over the lazy dog.
+    This is a unique sentence in text A.
+    Both texts share this common passage here.
+    Another unique line for the first text."""
+
+    text_b = """A quick brown fox leaps over a lazy dog.
+    This is different content in text B.
+    Both texts share this common passage here.
+    Some other unique content for text B."""
+
+    compare = mo.ui.anywidget(TextCompare(text_a=text_a, text_b=text_b, min_match_words=3))
+    compare
+    return compare, text_a, text_b
+
+
+@app.cell
+def _(compare, mo):
+    mo.md(f"**Found {len(compare.matches)} matching passages**")
+    return
+
+
+if __name__ == "__main__":
+    app.run()