ihaskell-notebook

A Community Jupyter Docker Stacks image. Provides the Jupyter IHaskell kernel in a Docker image which composes well with other Jupyter Docker Stacks. Images are published at DockerHub crosscompass/ihaskell-notebook.

docker run the latest image right now with the following shell command, then open http://localhost:8888?token=x to try out the Jupyter notebook. Your current working directory on your host computer will be mounted at Home / pwd in JupyterLab.

    docker run --rm \
      -p 8888:8888 \
      -v $PWD:/home/jovyan/pwd \
      --env JUPYTER_ENABLE_LAB=yes \
      --env JUPYTER_TOKEN=x \
      --name ihaskell_notebook \
      crosscompass/ihaskell-notebook:latest

This image includes:

• JupyterLab 2
• IHaskell Jupyter kernel
• ihaskell_labextension JupyterLab extension for Haskell syntax highlighting in notebooks
• Haskell libraries for instances of IHaskell.Display
  • ihaskell-aeson for Aeson JSON display
  • ihaskell-blaze for Blaze HTML display
  • ihaskell-gnuplot for gnuplot display
  • ihaskell-juicypixels for JuicyPixels image display
  • ihaskell-graphviz for Graphviz display
  • ihaskell-diagrams for diagrams
  • ihaskell-charts for Chart
  • ihaskell-hatex for HaTeX
  • DougBurke/ihaskell-hvega for Vega/Vega-Lite rendering, natively supported by JupyterLab
• Haskell Stack package manager, with Glasgow Haskell Compiler.

To ensure that this image composes well with any authentication and storage configuration (for example SystemUserSpawner) or notebook directory structure, we try to avoid installing anything in the Docker image in /home/jovyan.

This image is made with JupyterLab in mind, but it works well for classic notebooks.

Example notebooks are collected together in the container at /home/jovyan/ihaskell_examples.

IHaskell.Display

Some libraries for instances of IHaskell.Display are pre-installed in the JupyterLab container.

The installed libraries mostly come from mostly from IHaskell/ihaskell-display, and are installed if they appeared to be working at the time the JupyterLab Docker image was built. You can try to install the other IHaskell/ihaskell-display libraries, and they will be built from the /opt/IHaskell source in the container.

stack install ihaskell-diagrams

See the Stack global project /opt/stack/global-project/stack.yaml for information about the /opt/IHaskell source in the container.

You can see which libraries are installed by running ghc-pkg:

stack exec ghc-pkg -- list | grep ihaskell
    ihaskell-0.9.1.0
    ihaskell-aeson-0.3.0.1
    ihaskell-blaze-0.3.0.1
    ihaskell-gnuplot-0.1.0.1
    ihaskell-hvega-0.2.0.0
    ihaskell-juicypixels-1.1.0.1
    ...

Stack global project

The ihaskell executable, the ihaskell library, the ghc-parser library, and the ipython-kernel library are built and installed at the level of the Stack global project in /opt/stack/global-project.

This means that the ihaskell environment is available for all users anywhere for any PWD inside the Docker container. (The PWD of a notebook is the always the directory in which the notebook is saved.)

The Stack global project resolver is determined by the IHaskell project resolver, and all included Haskell libraries are built using that Stack resolver.

You can install libraries with stack install. For example, if you encounter a notebook error like:

<interactive>:1:1: error:
   Could not find module ‘Numeric.LinearAlgebra’
   Use -v to see a list of the files searched for.

Then you can install the missing package from the terminal in your container:

stack install hmatrix

Or, in a notebook, you can use the GHCi-style shell commands:

:!stack install hmatrix

And then ⭮ restart your IHaskell kernel.

You can use this technique to create a list of package dependencies at the top of a notebook:

:!stack install hmatrix
import Numeric.LinearAlgebra
ident 3

(3><3)
 [ 1.0, 0.0, 0.0
 , 0.0, 1.0, 0.0
 , 0.0, 0.0, 1.0 ]

Sadly, this doesn't work quite as frictionlessly as we would like. The first time you run the notebook, the packages will be installed, but then the kernel not load them. You must ⭮ restart the kernel to load the newly-installed packages.

Local Stack Projects

You can run a IHaskell .ipynb in a Stack project PWD which has a stack.yaml.

You should copy the entire contents of the container's Stack global project /opt/stack/global-project/stack.yaml into the local project's stack.yaml as a starting point. That will give you the same resolver as the global project IHaskell installation, and it will also allow you to install libraries from IHaskell and IHaskell/ihaskell-display. You can add extra-deps to your local project stack.yaml for packages which are not in the Stack resolver.

You probably shouldn't run a IHaskell .ipynb in a PWD with a stack.yaml that has a resolver different from the resolver in /opt/stack/global-project/stack.yaml.

After your stack.yaml is configured, run :! stack build and then ⭮ restart your IHaskell kernel.

System GHC

The GHC version specified by the IHaskell Stack resolver is also installed in the container at the system level, that is, on the executable PATH.

Composition with Docker Stacks

Rebase the IHaskell Dockerfile on top of another Jupyter Docker Stack image, for example the scipy-notebook:

docker build --build-arg BASE_CONTAINER=jupyter/scipy-notebook --rm --force-rm -t ihaskell_scipy_notebook:latest .

References, Links, Credits

IHaskell on Hackage

IHaskell on Stackage

IHaskell Wiki with Exemplary IHaskell Notebooks

When Is Haskell More Useful Than R Or Python In Data Science? by Tikhon Jelvis

datahaskell.org

This Docker image was made at Cross Compass in Tokyo.