Skip to content
almond-shPublic

About

A collection of Jupyter notebooks showing what you can do with the almond Scala kernel.

Topics

Resources

Stars

45 stars

Watchers

4 watching

Forks

Latest commit

 

History

100 Commits

Folders and files

Repository files navigation

Almond Examples Binder nbviewer Deepnote

A collection of Jupyter notebooks showing what you can do with the Almond Scala kernel.

The notebooks use almond 0.15.0 with Scala 2.13, except the dedav4s one, that uses Scala 3.9.

Run interactively on Binder

The easiest way to get started is to run the examples on Binder. All you need is a browser!

Binder is an amazing service that allows you to create an executable environment out of a Git repository containing Jupyter notebooks. That way, you can play with the examples and try new things without having to install anything locally. Binder builds its environment from the Dockerfile of this repository.

See Notebook Output in nbviewer

You can view the notebooks directly on GitHub, as it has a basic renderer for Jupyter notebooks. It doesn't execute any JavaScript though, which severely limits its ability to show dynamically generated plots, e.g. from plotly.

A much better option is to render them through nbviewer. nbviewer supports loading notebooks directly from a repo on GitHub.

List of all notebooks in this project in nbviewer

Run interactively in Deepnote

You can also try Almond very quickly by cloning this Deepnote project with Almond kernel and examples. Deepnote offers hosted notebooks with real-time collaboration capabilities for free.

Running locally

An even better way to learn about Jupyter and Almond is to run it locally so you can try things out for yourself.

Via docker

The Dockerfile of this repository builds an image with the notebooks, based on the almond docker image (whose images are only available for x86-64 as of almond 0.15.0). Build and run it with

docker build -t almond-examples .
docker run -it --rm -p 8888:8888 almond-examples

Then copy the URL shown in the Docker output into your browser.

The image has the same JupyterLab setup as the dev.jupyter* Mill commands of almond: the variable inspector (open it with "Open Variable Inspector", from the context menu of a notebook), Jupyter AI, and the same default settings. Jupyter AI can chat with Claude and Codex, provided their credentials are passed to the container, like

docker run -it --rm -p 8888:8888 -e ANTHROPIC_API_KEY -e OPENAI_API_KEY almond-examples

These come from the jupyter directory, that scripts/update-jupyter-setup.sh updates from the almond repository.

The image sets JDK_JAVA_OPTIONS, so that the kernels can run Spark (see the Spark notebook). To pass Java options of your own to the kernels, like -Xmx8g, use JAVA_TOOL_OPTIONS rather than JDK_JAVA_OPTIONS (which would override the options of the image), like

docker run -it --rm -p 8888:8888 -e JAVA_TOOL_OPTIONS=-Xmx8g almond-examples

Locally on your machine

To run these notebooks locally:

  1. Install JupyterLab (along with the plotly Python package, for plotly charts to be shown in JupyterLab, and the numpy, pandas and matplotlib ones, for the ScalaPy notebook). pip install -r jupyter/requirements.txt installs the JupyterLab version and extensions of the Docker image.
  2. Install an Almond kernel for Scala 2.13, with the id scala213, like
    cs launch --use-bootstrap almond:0.15.0 --scala 2.13.18 -- \
      --install --id scala213 --display-name "Scala 2.13" --use-notebook-coursier-logger
    and, for the dedav4s notebook, one for Scala 3.9, with the id scala39, like
    cs launch --use-bootstrap almond:0.15.0 --scala 3.9.0 -- \
      --install --id scala39 --display-name "Scala 3.9" --use-notebook-coursier-logger
    (--use-notebook-coursier-logger makes the kernels show the progress of dependency downloads in the notebooks, like the Docker image does)
  3. Clone the project and run jupyter lab in the notebooks directory
  4. Open one of the example notebooks and play with it!

Checking the notebooks

CI runs all the notebooks in the Docker image, on each change and weekly, with the Scala CLI script scripts/run-notebooks.sc. Cells showing code that doesn't compile or throws on purpose are tagged raises-exception: they must fail, and no other cell may. To run some notebooks the same way locally, with the kernels installed as above:

scala-cli scripts/run-notebooks.sc -- notebooks/scala-tour notebooks/spark.ipynb

or with Mill, like

./mill 'notebook[scala-tour].check'  # notebooks/scala-tour
./mill 'notebook[spark].check'       # notebooks/spark.ipynb
./mill __.check                      # all of them

On PRs, CI only runs the notebooks affected by the PR, using Mill selective execution: each module of build.mill depends on the files its notebooks use, and on those all notebook runs use (build.mill, the Dockerfile, jupyter/, scripts/run-notebooks.sc and the CI workflow).

About

A collection of Jupyter notebooks showing what you can do with the almond Scala kernel.

Topics

Resources

Stars

45 stars

Watchers

4 watching

Forks

Releases

Packages

Used by

Contributors

Languages