The ember factory

The purpose of this application is to (re)produce burning ember diagrams of the style used in IPCC reports. The code is open-source. More information.

This page documents parameters which may be used in input files. The starting point to learn about the input format for the 'Ember Factory' is the Tutorial. This page provides more detailed information, including a comprehensive list of available parameters.

Spreadsheets in an Ember Factory input file

The Excel workbooks may include up to 3 spreadsheets, of which only the first is mandatory:

Parameters in the 'data' spreadsheet

The parameters which can be provided in the 'data' spreadsheet are

Parameters allowed in the 'data' sheet

Parameter Default value Description

General metadata

project_name - A project name which could be used to identify these embers within a larger ensemble
project_source - Where the data is from, e.g. IPCC supplementary material X.SM.Y
project_revision_date - When the last important edit was done
project_version - An optional version
project_data_verified - Whether you regard the data as fully verified; this may be important to track work on the file. You may use column C to provide detailed information on what is verified (or not).

'Hazard' (vertical) scale

haz_name Global mean temperature change Name of the hazard variable, used as axis name
haz_name_std - Experimental. A standard name for the variable defining hazard levels. The purpose is to allow for conversion of hazard data from different embers to a common unit/variable. Currently used are GMST and GM-SST - names are not fully settled. If you wish to use, please contact us.
haz_unit °C Hazard axis unit, such as °C, °C/yr or ocean pH. Note: the unit will not be included in the labels if is included in haz_name, to avoid duplication
haz_axis_bottom 0 The bottom of the hazard axis (number)
haz_axis_top 5 The top of the hazard axis (number)
haz_bottom_value Deprecated. Automatically converted to haz_axis_bottom (and haz_valid_bottom)
haz_top_value Deprecated. Automatically converted to haz_axis_top (and haz_valid_top)

haz_valid_*

The two parameters below define the 'valid' range of hazard values, i.e. range over which risks were assessed. These parameters are not actual file metadata: they are attributed to each ember provided in rows under the haz_valid_* indication. A similar process was used in Zommers et al. 2020 to show the 'valid ranges' associated to several reports. As those parameters are new in the basic format, if you use them it would be good to inform us.
haz_valid_bottom - The bottom of the range of valid hazard values (number)
haz_valid_top - The top of the range of valid hazard values (number)

haz_map_*

Used to 'map' the hazard coordinate from the ember data to another coordinate, such as SST to GMST. In the future, an alternative might be to use 'unit conversion rules' based on haz_name_std. A warning is issued and included as information in the resulting PDF to limit the potential for confusion (number). Rule: newhazard = haz_map_factor * oldhazard + haz_map_shift
haz_map_factor - Multiplies all hazard values from embers data by the provided value (number)
haz_map_shift - Shifts all hazard values by the provided value (number)

Miscellanea

software_version_min 1.2.0 The minimum version of the software which is needed to use all information from this file. We hope to keep compatibility of existing files with future software, but a newer file may include information which old software does not use; it is especially the case when a new version is available for testing: if an older software is used, it may at least ignore some of the information in the new file. Used to produce a warning.

Graph parameters sheet

The "Graph parameters" sheet is an optional spreadsheet (its name cannot be changed).

In this sheet, parameters are made of a name (key) in column A, and one or more columns providing information. Lines which start with an empty first column are comments.

In the Excel spreadsheets, a parameter has one of the two following structures:

name main value optional unit of length for the layout ('cm' or 'mm')
name main value additional data 1 additional data 2 ...

However, to facilitate the reading of the table of parameters provided below, the additional data is presented here between square brackets rather than in separate columns, i.e. main value [add data 1, add data 2... ].

The specialized parameters are explained below, and a summary table is provided at the bottom of this page.

Selecting and sorting embers

The purpose of these specific parameters is to generate different diagrams without changing the 'data' sheet. Instead of manually moving data or deleting lines from the data sheet, you may list the ember names. The easiest case is to sort embers by name without changing their groups. It is done like this:

sort_2nd_by Name name of ember wanted at 1st place name of ember wanted at 2nd place ...

The name of the parameter, sort_2nd_by, may look odd. The reason for that is that embers are first arranged in groups (generating a panel of several embers with a common title and axis), then by name. For most cases, you just need to know that sort_2nd_by is the right parameter and that it needs to be followed by "Name" (it means that embers within a group are sorted by name). If an ember which is in the data does not have its name in the list in columns C, D, E... then it will be omitted. If there is nothing in column B, i.e. Name is deleted, no sorting will occur: it is a way to come back to the order in your data without deleting the optional sorting list.

The other paramter, sort_first_by, is meant to control the ordering of groups. This handles more complex cases where the role of ember group names and embers names can be swapped. An example is provided in the workbook from Zommers et al. 2020, where the data is provided for RFC1 in all reports, then RFC2 etc. The sorting parameters make it possible to re-arrange all embers by report: all RFCs in TAR, all RFCs in Smith et al. 2009, etc. For more information, please e-mail philippe.marbaix@uclouvain.be.

Positioning elements in the layout

The following diagram explains how ember figures are designed, using various parameters for setting the width and length of its components or the distance between these. As shown in the example files, those parameters generally have a unit (such as 'cm'), to be provided in column C.

Schematic illustration of graphic parameters

Legend (colour bar)

This parameter controls how the whole "colour legend block" is positioned around the embers.

Parameter Default Description
leg_pos under There are 5 permitted values for leg_pos: under, right, in-grid-horizontal, in-grid-vertical, and none (which results in the absence of legend); in-grid-... is specific to more complex figures in which there are at least two lines of "ember" groups, which form a "grid".

Grid lines and related hazard-level indications

The parameters starting with haz_grid_lines control de axis tick marks and related horizontal grid lines. haz_grid_lines controls the approximate number of main lines, which is software-adjusted. Other parameters enable additional grid lines at user selected levels and even shaded areas, as illustrated in SROCC example.

Indicating confidence levels and highlighting transitions

The parameter show_confidence indicates whether confidence levels regarding the transitions must be drawn, and where (as usual, on the right of the ember, or on the top of the embers). The symbols can be selected. For more information, see "Confidence levels" in the table below.

Highlighting changes from one ember to the next trough lines

show_changes connects the given risk levels from each ember by a line (within a group of embers); to use, type True in the first columns. The levels that needs to be connected are then provided in the next columns (see details in the table below).

List of graph parameters

Parameter Default value Description

Main axis grid-lines (horizontal lines) and tick marks

haz_grid_lines 6 [] The main value is an approximate indication of the desired axis tick-marks / grid lines, which will be rounded to a graph-adapted value by the software. The additional data provides a way to add custom grid-lines, such as for 1.5°C or the temperature at the start of a given time period. (number)
haz_grid_lines_ends - [] The additional data provides a way to define shaded areas instead of grid lines, such as to illustrate temperatures during a certain time period ('recent', etc.). The previous parameter and this one jointly provide a way to define this range: haz_grid_lines provides the lower limit, haz_grid_lines_ends provides the upper limit; the second must be in the cell just below the first. Note: the main value is not used. (number)
haz_grid_lines_labels - [] The additional data defines labels (name) for the custom grid-lines or shaded areas provided by the above parameters. The label must be indicated in a cell under the one providing the hazard level (i.e. in the same column as haz_grid_lines). (number)
haz_grid_lines_labels_off - [] The additional data defines an offset for the position of the label on the axis, expressed as fraction of the height of fonts (e.g. to lower the label by its own size, type -1.0). Used to manually ajust labels so that they do not overlap. (number)
haz_grid_lines_colors - [] The additional data defines colors for the grid-lines or shaded areas provided above
haz_grid_show All Whether full grid-lines should be shown (All), or just tick marks except for lines defined by the user (User) or no lines, just ticks (None, but this is not implemented yet). A vertical line will be drawn for the axis when haz_grid_show is not All or there are minor ticks.
haz_axis_minorticks - If defined, add minor ticks. 0 means 'auto define', x means x minor ticks between two main ticks. (number)

Optional secondary axis (haz_axis2_*)

Rule: hazardonaxis2 = haz_axis2_factor * hazardonaxis + haz_axis2_shift
haz_axis2_factor 1.0 Defines axis2, see above. (number)
haz_axis2_shift 0.0 Defines axis2, see above. (number)
haz_axis2 - Set it to True or Right to show the secondary axis (axis2).
haz_axis2_name - A name for the secondary axis (axis2).
haz_axis2_unit - A unit for the secondary axis (axis2); default is to take the unit of the main axis.
haz_grid2_show - Whether full grid-lines should be shown (All), or just tick marks. Default is to do as for the main axis.
haz_axis2_minorticks - If defined, add minor ticks to axis2. 0 means 'auto define', x means x minor ticks between two main ticks. (number)

Colour palette selection

be_palette The name of the desired colour palette. Available palettes include: RGB-SRCCL-C7, CMYK-SRCCL, CMYK-SR15, BW (black and white), RGB-TAR+VH (as in Zommers 2015). Palettes can also be entirely customized through an additional spreadsheet.

Legend (colour bar)

leg_title Level of additional impact/risk due to climate change The title to be written on top of the legend.
leg_pos Under Defines the position of the legend. Allowed values are under, right, in-grid-horizontal, in-grid-vertical (more details are provided above)
leg_conf - Whether a legend is to be provided for the confidence levels. EXPERIMENTAL. (logical)

Special parameters

show_changes False [1.5] When set to True, results in a dashed line connecting one ember to the next at a certain risk level. In the basic format, risk levels are defined as follows: undetectable=0, moderate=1, high=2, very high=3 (thus a value of 1.5 would connect the midpoints between moderate and high risk)
sort_first_by - [] Requests a sorting of embers which will produce new 'groups of embers'. Rarely used, but an example is RFCs-data-2020_01_26-Z2020_rev1_byPubli.xlsx
sort_2nd_by - [] Requests a sorting of embers which within groups. Commonly used with the main value set to "Name", then listing embers names in the desired order. This also selects embers: embers which are not included in this list will be ignored in the graphic.
max_gr_line 3 The maximum number of ember groups on a "line of embers" in the graphic. After that number of groups, the next line starts (number)

Confidence levels

show_confidence True True or Right provides the traditional IPCC confidence marks. On top will draw confidence mark on top of the ember colours. Also provides the vertical lines used in recent IPCC reports to highlight the ranges of risk (colour) transitions. If False or empty, confidence levels are not shown.
conf_levels_file - [Low;Medium;High;Very high] The confidence level names used in defining your embers.
conf_levels_graph 1.9 [•;••;•••;••••] The size of the confidence level marks (number) and the symbols for the confidence levels, corresponding to the names in the previous line. For text labels, use e.g. 1.0 [L, M, H, VH]
conf_fnt_name Helvetica Name of the font used for the confidence level marks

Fonts

fnt_size 10 The main font size, used e.g. for the ember names? (number)
fnt_name Helvetica The main font name; font names are currently limited to standard PDF fonts
gr_fnt_size 12 The font size used for the ember goup names, which is indicated on top of the embers. (number)

Layout positions

Embers - y axis (vertical)

be_top_y 1.8 cm Description: see above diagram (length)
be_y 8.4 cm (length)
be_bot_y 1.6 cm (length)

Embers - x axis (horizontal)

be_int_x 1.3 cm (length)
be_x 1.0 cm (length)
gr_int_x 1 cm (length)
scale_x 1 cm (length)
haz_name_x 1 cm (length)

Legend

leg_top_y 1 cm (length)
leg_y 1 cm (length)
leg_bot_y 0.9 cm (length)
leg_x 7 cm (length)