Get the Books

Enjoying these notebooks and want to support the work? Check out the practical books on Data Science, Visualisation, and Evolutionary Algorithms.

Get the books

Block Diagrams with Blockdiag


In [1]:
# used to create block diagrams
%reload_ext xdiag_magic
%xdiag_output_format svg


You may have noticed that I programmatically generate block diagrams in many of my notebooks, such as the one below.

In [2]:
    orientation = portrait
    Initialisation -> Evaluation -> "Terminate?" -> Selection -> Variation -> Evaluation
    Initialisation [color = '#ffffcc']
blockdiag { orientation = portrait Initialisation -> Evaluation -> "Terminate?" -> Selection -> Variation -> Evaluation Initialisation [color = '#ffffcc'] } InitialisationEvaluationTerminate?SelectionVariation

I achieve this using what appears to be a relatively unknown Jupyter extension called xdiag_magic (by GitHub user kaibaesler) which provides custom magic functions for generating diagrams with blockdiag. Unfortunately, it wasn't a straight-forward conda install ... to get it up and running, but it's still quite easy.


These instructions assume you already have Jupyter Lab up and running, perhaps through Anaconda.

  1. Clone or Download this mirrored repository to your your machine. Make sure to extract it if you download it as a ZIP archive.
  2. Using the command line, navigate to the xidag_magic_extension directory, e.g. using cd.
  3. Once you're inside the directory, make sure you are within the desired environment, e.g. if you're using conda make sure you type conda activate <environment_name>.
  4. Type pip install -r requirements.txt.
  5. Type pip install -e ..


To test it, launch Jupyter Lab and open or create a notebook. You need to run the following code before generating any diagrams.

In [3]:
%reload_ext xdiag_magic
%xdiag_output_format svg

Then you can visit blockdiag's examples and try running some of their example diagrams to see the output. Your diagram code must appear in a Jupyter Lab Code cell, and be surrounded with the following.

In [4]:
blockdiag { }

For example:

In [5]:
    orientation = portrait
    A -> B -> C

Support this work

You can support this work by getting the e-books. This notebook will always be available for free in its online format.

Plotapi, beautiful by default.

Let plotapi do the heavy lifting – enabling beautiful interactive visualisations with a single line of code (instead of hundreds).

Get Plotapi