EmberMaker

Purpose

EmberMaker is a scientific graphic library aimed at (re)producing "burning ember" diagrams of the style used in IPCC (Intergovernmental Panel on Climate Change) reports. All graphics elements are in vector form, including color gradients (this implies specific drawing code).

EmberMaker was formerly a part of the EmberFactory project: https://pypi.org/project/EmberFactory/. If you need to produce ember diagrams from your data, first consider using the online EmberFactory. This package is intended to meet more specific needs, by drawing embers from your own code.

In addition to 'burning embers', EmberMaker can also draw common x-y plots which share the same vertical axis as a set of embers.

While EmberMaker is a Python package, it is quite easy to use within R, as shown in the last example below.

Installation

pip install embermaker

Only Python >= 3.10 is supported.

Basic usage

Creating embers only needs calling a few functions, as in this basic example:

from embermaker.embergraph import EmberGraph
from embermaker.ember import Ember

# Create ember
be = Ember(name='What this ember is about', haz_valid=[0, 5])

# Add two transitions to this ember
be.trans_create(name='undetectable to moderate', min=0.6, median=1.1, max=1.4, confidence='very high')
be.trans_create(name='moderate to high', min=1.7, median=2.2, max=2.5, confidence='high')

# Create an ember graph (available native image formats are PDF and SVG)
egr = EmberGraph("output_file_name", grformat="PDF")

# Change a parameter (list of parameters: https://climrisk.org/emberfactory/doc/parameters )
egr.gp['haz_axis_top'] = 5.0  # max value on axis 

# Add ember to graph (a list would work as well; more advanced uses define ember groups)
egr.add(be)

# Actually produce the diagram
outfile = egr.draw()

Usage examples

Examples are provided on FramaGit (a GitLab instance)

Access within python (/examples/python):

• 'create_and_draw_embers.py' is the shorter and simpler. It illustrates a few functions constructing embers from data.
• 'draw_embers_from_file.py' reads 'traditional' ember Excel sheets and shows how an x-y plot can be added.
• 'test_error_reporting.py' illustrates a few cases which produce warning or error messages and how to access these.

Access from R (/examples/R):

• 'create_and_draw_embers.R' illustrates functions constructing embers, within an R script and using data produced in R.

As this is the first "standalone" version, the API functions may be improved in the future, as well as more documented. We are interested in learning how you use this and any difficult you might face, to steer future development - thanks!

Use on web pages

Dark mode

When preparing SVGs for online use, it is possible to add supports for a 'dark mode' by selecting grformat="SVG-C". Then a colour scheme adapted to dark background can be activated in two ways:

• by adding the "dark" class at the root of the svg (https://climrisk.org/cree is following this approach);
• by 'activating' @media(prefers-color-scheme: dark) (caveat: in the Safari browser, embedded SVGs do not inherit the color-scheme, see https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-color-scheme) This does not change the colour code used to define risk levels. To get an SVG without this feature, use grformat="SVG".

Descriptive content / interactivity

When provided, the description of Embers and Transitions is available within SVG files and can be used to provide information interactively as shown in for example https://climrisk.org/cree/emberfigure?figure=14

Development history

The EmberFactory software was created by philippe.marbaix -at- uclouvain.be at the end of 2019. The first objective was to produce figure 3 of Zommers et al. 2020 (doi.org/10/gg985p).