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:
- the 'data' spreadsheet contains metadata and embers data, describing the transitions. The first spreadsheet is always used for data input, and may have any name. The format of this sheet can be "Basic" or "Fullflex" (see tutorial).
- the "Graph parameters" sheet is recognised by its name. It is optional and provides as many (and as little) parameters as desired, among those defined below. Those parameters are mostly related to how the embers needs to be drawn - layout, ordering, additional information on the axis...
- the "Color definitions" sheet is recognised by its name. It is also optional, and describes sets of colours to be used in ember gradients (see example in Tutorial / Colour Palettes). For the "Fullflex" format, it also defines the risk index values for which colors are defined.
Parameters in the 'data' spreadsheet
The parameters which can be provided in the 'data' spreadsheet are
- metadata about the content of the file
- general information about how to plot the data in the embers, such as the name of the 'hazard' variable (e.g. 'mean surface temperature change') and the range of the 'hazard' (vertical) axis. By contrast to the parameters in the other sheets, those are simple parameters almost always made of a single value, and they must be 'data related' (layout-related parameters can only be in the Graph parameters sheet).
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) |
| Deprecated. Automatically converted to haz_axis_bottom (and haz_valid_bottom) | ||
| 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.
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) |
Embers names |
||
| be_name_rotate | 0 | If > 0, rotates the name label anticlockwise by the provided angle, in degrees. New feature 2021/09, may still evolve (number). |
Legend |
||
| leg_top_y | 1 cm | (length) |
| leg_y | 1 cm | (length) |
| leg_bot_y | 0.9 cm | (length) |
| leg_x | 7 cm | (length) |