Skip to main content
This site and Lume package is currently under development and may not be stable.
Open Innovations
OI Lume Viz
0.16.5

Visualisation configuration

This page aims to be an overview of the configuration options available for each visualisation type.

Dashboard

Panels with big numbers.
  • data - Either a reference to a CSV file in the Lume site or an array of rows with named attributes.
  • columns - As with many of the visualisation types you can optionally add virtual columns.
  • colours - Define some visualisation-specific named colours.
  • width - An optional minimum width (e.g. 400px) for each panel. Panels may then be arranged by however many columns will fit in the page width.
  • title - The title of the column that will be used to get a title of the panel.
  • value - The title of the column that will be used to get the value of the panel.
  • note - The title of the column that will be used to get a footnote for the panel.
  • units - A structure to define prefix and prefix columns.
    • prefix - The column to use for any text that would go _before_ the value e.g. to add a currency sign before the value.
    • postfix - The column to use for any text that would go _after_ the value e.g. to add, say, "kWh" to a value.
  • panels - An array of which panels will be displayed. They are in order and each is of the form:
    • name - (required) References a specific title value.
    • precision - The level of precision to use for the number e.g. 0.1 would round the value to the nearest 0.1.
    • colour - The hex colour to use for the panel.
    • class - A CSS class to add to the panel (may be useful for consistent styling).
    • scale - A colour scale to use to set the panel's background colour based on the value.
    • min - Used with scale and max to define the colour scale.
    • max - Used with scale and min to define the colour scale.
    • compact-format0.16.3 - By default this will be set to true. It will show numbers to the nearest thousand, million, billion etc. So 1,500 will become 1.5k.
  • attribution - Add a line of attribution text under the visualisation.

Table

Merge rows, use colour scales and sort columns.
  • data - (required) Either a reference to a CSV file in the Lume site or an array of rows with named attributes
  • columns - An ordered array of columns to use to build the table. You could also create a virtual column here. Each is of the form:
    • name - (required) The title of the column in the data.
    • align - Set the text alignment of the column e.g. left, center, or right
    • mergerows - (boolean) if this column contains neighbouring rows with the same value, these will be merged into one cell.
    • sortable - (boolean) if this column will be made sortable by the viewer. Note that it isn't possible to make a column sortable if mergerows has been used on any column.
    • colour - A hex colour to use for the background colour of the cells in this column.
    • template - A virtual column can be created from other columns in the data.
    • scale - A colour scale to use to set a cell's background colour based on the cell value.
    • min - Used with scale and max to define the colour scale. If not included, the minimum value of the column will be used.
    • max - Used with scale and min to define the colour scale. If not included, the maximum value of the column will be used.
  • sort - the name of the column to sort by.
  • reverse - (boolean) By default the order is from low to high but you can order from high to low if this is set to true.
  • colours - Define some visualisation-specific named colours.
  • width - An optional minimum width (e.g. 100%) for the table.
  • where - Limit the rows to include
  • attribution - Add a line of attribution text under the visualisation.

Treemap

Display hierarchical data using nested rectangles.
  • data - Either a reference to a CSV file in the Lume site or an array of rows with named attributes
  • columns - As with many of the visualisation types you can optionally add virtual columns.
  • colours - Define some visualisation-specific named colours.
  • value - The title of the column that will be used to get the value of the panel.
  • grouping - An array of column headings by which to group the data. For instance, if you set the grouping to `level_1`, any rows in `level_1` will be grouped together. You can also use this to define a multi-level treemap.
  • colour - The title of the column to use to set the colour of the treemap cells.
  • scale - A colour scale to use to colour the cells based on the value.
  • min - Used with scale and max to define the colour scale.
  • max - Used with scale and min to define the colour scale.
  • tooltip - This is to add tooltips to cells. Either provide the name of an existing/virtual column in the data or construct one using string templates.
  • attribution - Add a line of attribution text under the visualisation.

Calendar chart

Show activity over the course of a long span of time, such as months or years.
  • data - Either a reference to a CSV file in the Lume site or an array of rows with named attributes
  • columns - As with many of the visualisation types you can optionally add virtual columns.
  • colours - Define some visualisation-specific named colours.
  • value - The title of the column that will be used to set the colour of the day. This can be a hex code or a number if used with scale.
  • key - The title of the column that contains the dates. These should be formatted in ISO8601 format e.g. "2024-02-06"
  • scale - A colour scale to use to colour the days based on the value.
  • min - Used with scale and max to define the colour scale.
  • max - Used with scale and min to define the colour scale.
  • tooltip - This is to add tooltips to days. Either provide the name of an existing/virtual column in the data or construct one using string templates.
  • order - Set the order of the years to either chronological (earliest year first) or reverse (latest year first).
  • startofweek - Set the first day of the week. Use 0 for Sunday, 1 for Monday etc.
  • attribution - Add a line of attribution text under the visualisation.

Ranking chart

A chart which shows how the rank of something varies.
  • data - Either a reference to a CSV file in the Lume site or an array of rows with named attributes
  • columns - An ordered array of columns to use to build the ranking chart. Each must have a name but these can also be virtual columns. This allows you to use fewer columns than exist in the data. There can also be an optional fillna which will be used in the tooltip in place of null or NaN values.
  • colours - Define some visualisation-specific named colours.
  • width - Set a specific width for the visualisation.
  • height - Set a specific height for the visualisation.
  • key - The title of the column that contains the things to be ranked.
  • circles - Add rank values on the lines by setting this in the range 0-1. The default is 0.
  • curvature - This sets the amount of curvature (between 0 and 1) for the line. The default is 1.
  • stroke-width - This can be in the range 0 and 1. The default is 0.5.
  • font-size - Sets the size of the font to use.
  • colour - The title of the column to use to set the colour of each line. The value can either be a hex colour value or use a colour scale.
  • scale - A colour scale to use to set a line's stroke colour.
  • min - Used with scale and max to define the colour scale.
  • max - Used with scale and min to define the colour scale.
  • legend - Define the legend
  • top - Limit the visualisation to the top x. Note that because things can move in and out of the top 10 the chart will also show those as a compressed group underneath.
  • gap - (number) The size of the gap between any top x and the compressed group below. The default is 1.
  • divider - (object) The SVG properties of the dividing line.
  • tooltip - This is to add tooltips to days. Either provide the name of an existing/virtual column in the data or construct one using string templates.
  • reverse - (boolean) By default the ranking is by the lowest value. However you can set it to use the highest value as the ranking by setting this to true.
  • attribution - Add a line of attribution text under the visualisation.

Bar chart

Series arranged in categories but with data displayed as bars.
  • data - Either a reference to a CSV file in the Lume site or an array of rows with named attributes
  • columns - As with many of the visualisation types you can optionally add virtual columns.
  • colours - Define some visualisation-specific named colours.
  • width - Set a specific width for the visualisation.
  • height - Set a specific height for the visualisation.
  • axis - Define the x (horizontal) axis.
  • legend - Define the legend.
  • category - The title of the column that contains the categories (vertical groups).
  • series - An ordered array of series. Each one is of the form:
    • title - The display name of the series.
    • value - The title of the column to use for the value of the bar.
    • colour - The hex code to use to colour this series.
    • tooltip - Either a string, template string, or the column heading to use to build a tooltip.
  • gap - Add spacing between the bars as a fraction of the bar width. The default is 0.
  • stacked - (boolean) This lets us stack the series within each category. The default is false.
  • percent - (boolean) Used with stacked to build 100% width stacked bar charts. This creates virtual columns in your data with the same name as the original columns but with _percent appended. Note that the normalised columns will be created before any virtual columns that you have created. The default is false.
  • attribution - Add a line of attribution text under the visualisation.

Scatter chart

Multiple series shown as a scatter plot. Similar to a line chart.
  • data - Either a reference to a CSV file in the Lume site or an array of rows with named attributes
  • columns - As with many of the visualisation types you can optionally add virtual columns.
  • colours - Define some visualisation-specific named colours.
  • width - Set a specific width for the visualisation.
  • height - Set a specific height for the visualisation.
  • axis - Define the x (horizontal) axis.
  • legend - Define the legend.
  • series - An ordered array of series. Each one is of the form:
    • title - The display name of the series.
    • x - The title of the column to use for the horizontal axis value.
    • y - The title of the column to use for the vertical axis value.
    • colour - The hex code to use to colour this series.
    • tooltip - Either a string, template string, or the column heading to use to build a tooltip.
    • points - Properties of the points:
      • size - The size of the point.
      • marker - One of circle, triangle, square, diamond, pentagon, hexagon, octagon, line, or cross.
      • rotate - How much to rotate the marker around its centre by, in degrees.
    • where - Limit the rows to include
  • attribution - Add a line of attribution text under the visualisation.

Line chart

Multiple series shown as a line graph.
  • data - Either a reference to a CSV file in the Lume site or an array of rows with named attributes.
  • columns - As with many of the visualisation types you can optionally add virtual columns.
  • colours - Define some visualisation-specific named colours.
  • width - Set a specific width for the visualisation.
  • height - Set a specific height for the visualisation.
  • axis - Define the x (horizontal) axis.
  • legend - Define the legend.
  • series - An ordered array of series. Each one is of the form:
    • title - The display name of the series.
    • x - The title of the column to use for the horizontal axis value.
    • y - The title of the column to use for the vertical axis value.
    • colour - The hex code to use to colour this series.
    • tooltip - Either a string, template string, or the column heading to use to build a tooltip.
    • points - Properties of the points:
      • size - The size of the point.
      • marker - One of circle, triangle, square, diamond, pentagon, hexagon, octagon, line, or cross.
      • rotate - How much to rotate the marker around its centre by, in degrees.
    • line - Properties of the line that joins the points:
      • curvature - The amount of curvature to apply to the line (1 = maximum, 0 = none.
      • stroke-dasharray - Define a stroke-dasharray for the stroke e.g. "6 2".
      • stroke-width - Define a width for the stroke.
      • stroke-linecap - The stroke-linecap
    • where - Limit the rows to include
  • attribution - Add a line of attribution text under the visualisation.

Ridgeline chart

Multiple series shown as a ridgeline chart/Joyplot.
  • data - Either a reference to a CSV file in the Lume site or an array of rows with named attributes
  • columns - As with many of the visualisation types you can optionally add virtual columns.
  • colours - Define some visualisation-specific named colours.
  • width - Set a specific width for the visualisation.
  • height - Set a specific height for the visualisation.
  • axis - Define the x (horizontal) axis.
  • legend - Define the legend.
  • series - An ordered array of series. Each one is of the form:
    • title - The display name of the series.
    • x - The title of the column to use for the horizontal axis value.
    • y - The title of the column to use for the vertical axis value.
    • colour - The hex code to use to colour this series.
    • tooltip - Either a string, template string, or the column heading to use to build a tooltip.
    • fill - The hex code to use as a fill colour. Could also reference a gradient using e.g. url(#gradientName).
    • fillOpacity - (0-1) The value to use for the opacity of the fill. Default 0.8.
    • line - Properties of the series line:
      • stroke-width - The stroke-width.
  • gradient - Define some gradients:
    • name - The name of the gradient that we will use elsewhere.
    • stops - A list of colour stops e.g. #053061 0%, #2166ac 10%, #4393c3 20%, #92c5de 30%, #d1e5f0 40%, #f7f7f7 50%, #fddbc7 60%, #f4a582 70%, #d6604d 80%, #b2182b 90%, #67001f 100%.
    • stroke-linecap. - The stroke-linecap
  • ridgeline - Properties of the ridgeline:
    • height - The maximum vertical extent of the data as a multiple of the series spacing. A value closer to 0 will make shallower ridges. Default is 2.
    • curvature - You can apply a curvature (0 = none, 1 = maximum) to all the lines. Default is 0.
  • attribution - Add a line of attribution text under the visualisation.

Waffle chart

Display values as a percentage of a whole in an aesthetically pleasing way. A nicer alternative to pie charts.
  • data - Either a reference to a CSV file in the Lume site or an array of rows with named attributes
  • columns - As with many of the visualisation types you can optionally add virtual columns.
  • colours - Define some visualisation-specific named colours.
  • width - Set a specific width for the visualisation.
  • height - Set a specific height for the visualisation.
  • series - An ordered array of series. Each one is of the form:
    • value - The title of the column to use for the value.
    • colour - The hex code to use to colour this series.
    • tooltip - Either a string, template string, or the column heading to use to build a tooltip.
    • points - Properties of the points:
      • size - The size of the point.
      • marker - One of circle, triangle, square, diamond, pentagon, hexagon, octagon, line, or cross. Alternatively you could set a sub-property svg that is an SVG image as a string.
      • rotate - How much to rotate the marker around its centre by, in degrees.
  • total - The name of the column that contains a total value. If not provided it will be guessed from the sum of the series values.
  • padding - Set the padding between cells of the waffle.
  • size - Set the grid size of the waffle. The default is 10 which gives a 10x10 waffle. You can also specify an array with two values e.g. [20,5] to set waffle grid horizontally and vertically
  • rounding - By default the values are rounded using Math.round() but we can choose to use Math.floor() by setting rounding to floor (you could also use ceil).
  • direction - By default, the direction is set to l2r which means that values fill in from the left. If we set direction to r2l it will fill values from the right.
  • gravity - By default, the gravity is set to bottom which means that values start at the bottom and build upwards. We can also set gravity to top, left or right.
  • attribution - Add a line of attribution text under the visualisation.

Hex cartogram

We love hex cartograms and this lets you make them.
  • data - (optional) Either a reference to a CSV file in the Lume site or an array of rows with named attributes. If used you will need to match this to the HexJSON IDs using matchKey.
  • columns - As with many of the visualisation types you can optionally add virtual columns.
  • hexjson - (required) Either a reference to a HexJSON file in the Lume site or inline HexJSON.
  • colours - Define some visualisation-specific named colours.
  • width - An optional minimum width (e.g. 400px) for each panel. Panels may then be arranged by however many columns will fit in the page width.
  • label - The title of the column that will be used to get a label for the hexagon. Leave empty if you don't want labels on the hexes.
  • value - The title of the column that will be used to get the value of the panel. Alternatively it could be a named colour.
  • matchKey - The title of the column in the data that contains unique keys that match those used in the HexJSON.
  • scale - A colour scale to use to colour the hexes based on the value.
  • min - Used with scale and max to define the colour scale.
  • max - Used with scale and min to define the colour scale.
  • legend - Define the legend.
  • tooltip - Either a string, template string, or the column heading to use to build a tooltip.
  • tools - Add some useful interactive tools:
    • filter - A search tool to filter hexes:
      • label - The title of the column to use as the displayed name for a hex in the search results.
      • max - The maximum number of results to show.
    • slider - A slider tool that will change the colouring of the hexes:
      • columns - An array of column titles to use to change the colouring of the hexes.
  • attribution - Add a line of attribution text under the visualisation.

SVG map

A simple map to show GeoJSON. It can have place labels and markers.
  • data - (optional) Either a reference to a CSV file in the Lume site or an array of rows with named attributes. If used you will need to match this to the GeoJSON properties using key.
  • columns - As with many of the visualisation types you can optionally add virtual columns.
  • geojson - (required):
    • key - The GeoJSON property to use to match with the data.
    • data - Either a reference to a GeoJSON file in the Lume site or inline GeoJSON.
  • colours - Define some visualisation-specific named colours.
  • width - An optional minimum width (e.g. 400px) for each panel. Panels may then be arranged by however many columns will fit in the page width.
  • projection - Set the map projection:
    • name - One of aitoff, equirectangular, gall-peters, orthographic (for orthographic you can also set the lat/lon for the projection centre), web-mercator (default), or osgb.
  • bounds - Set a longitude/latitude bounds of the map:
    • lat - The latitude bounds:
      • min - The minimum latitude
      • max - The maximum latitude
    • lon - The longitude bounds:
      • min - The minimum longitude
      • max - The maximum longitude
  • layers - An array of map layers in the order they will be layered. Each layer has a property type which can be one of:
    • background - Set a GeoJSON background:
      • geojson - Either a reference to a GeoJSON file in the Lume site or inline GeoJSON
      • colour - The colour for the background polygons.
    • data - Add the data layer to the map:
      • key - The title of the column to use to match IDs with the GeoJSON.
      • value - The title of the column that will be used to get the colour of a polygon. If the value is a number you should also set the scale.
      • tooltip - Either a string, template string, or the column heading to use to build a tooltip.
      • scale - A colour scale to use to colour the polygons based on the value.
      • min - Used with scale and max to define the colour scale.
      • max - Used with scale and min to define the colour scale.
    • graticule - Add a graticule:
      • step - An array defining the latitude and longitude spacing of the graticule in degrees.
    • labels - Add a place label layer:
      • places - An array of place markers that sit above the interactive layer. A place can be defined with the following properties:
        • name - the label to use for the place label
        • latitude - set the latitude of the label (can be omitted if it is a UK place we know about)
        • longitude - set the longitude of the label (can be omitted if it is a UK place we know about)
        • text-anchor - set to either start, middle, or end to anchor the text
        • colour - the colour of the label (default is black)
        • border - the colour of the label border (default is white)
        • font-size - manually set the font size (if omitted it will be scaled to the population where known)
        • font-weight - manually set the font weight (e.g. to "bold")
        • font-family - manually set the font family
    • markers - An array of markers
      • markers - A marker can be defined with the following properties:
        • icon - Can be either be a string (one of default, geo, geo-alt, asterisk, pin, balloon, balloon-heart, chat-square) or an object with the form:
          • svg - The SVG string to use
          • size - e.g. [40,40]
          • anchor - e.g. [20,0]
        • latitude - set the latitude of the marker
        • longitude - set the longitude of the marker
        • colour - the colour of the label (default is black)
        • tooltip - the content of an optional tooltip
  • padding - Set the padding between the data layer and the map edges. The value is given in the pixel scale of the generated map (which may not be the same as the pixels the map takes up on screen).
  • legend - Define the legend.
  • options - Set some options:
    • fillOpacity - The fill-opacity of the polygons
  • tools - Add some useful interactive tools:
    • filter - A search tool to filter hexes:
      • label - The title of the column to use as the displayed name for a hex in the search results.
      • max - The maximum number of results to show.
    • sliderSince 0.16.2 - A slider tool that will change the colouring of the hexes:
      • columns - An array of column titles to use to change the colouring of the hexes.
  • attribution - Add a line of attribution text under the visualisation.

Zoomable map

A simple, zoomable, slippy map.
  • data - (optional) Either a reference to a CSV file in the Lume site or an array of rows with named attributes. If used you will need to match this to the GeoJSON properties using key.
  • columns - As with many of the visualisation types you can optionally add virtual columns.
  • geojson - (required):
    • key - The GeoJSON property to use to match with the data.
    • data - Either a reference to a GeoJSON file in the Lume site or inline GeoJSON.
  • colours - Define some visualisation-specific named colours.
  • width - An optional minimum width (e.g. 400px) for each panel. Panels may then be arranged by however many columns will fit in the page width.
  • bounds - Set a longitude/latitude bounds of the map:
    • lat - The latitude bounds:
      • min - The minimum latitude
      • max - The maximum latitude
    • lon - The longitude bounds:
      • min - The minimum longitude
      • max - The maximum longitude
  • layers - An array of map layers in the order they will be layered. Each layer has a property type which can be one of:
    • tile - Set a tile layer. If your tile layer is on top of other layers it may hide them (unless it consists of transparent label tiles):
      • props - One of CartoDB.Positron, CartoDB.PositronOnlyLabels, CartoDB.DarkMatter, CartoDB.DarkMatterNoLabels, CartoDB.DarkMatterOnlyLabels, CartoDB.Voyager, CartoDB.VoyagerNoLabels, CartoDB.VoyagerOnlyLabels, ESRI.WorldImagery, OpenStreetMap.Mapnik, Stadia.OSMBright but you can also define your own site-wide tileLayer defaults.
    • background - Set a GeoJSON background:
      • geojson - Either a reference to a GeoJSON file in the Lume site or inline GeoJSON
      • colour - The colour for the background polygons.
    • data - Add the data layer to the map:
      • key - The title of the column to use to match IDs with the GeoJSON.
      • value - The title of the column that will be used to get the colour of a polygon. If the value is a number you should also set the scale.
      • tooltip - Either a string, template string, or the column heading to use to build a tooltip.
      • scale - A colour scale to use to colour the polygons based on the value.
      • min - Used with scale and max to define the colour scale.
      • max - Used with scale and min to define the colour scale.
    • labels - Add a place label layer:
      • places - An array of place markers that sit above the interactive layer. A place can be defined with the following properties:
        • name - the label to use for the place label
        • latitude - set the latitude of the label (can be omitted if it is a UK place we know about)
        • longitude - set the longitude of the label (can be omitted if it is a UK place we know about)
        • text-anchor - set to either start, middle, or end to anchor the text
        • colour - the colour of the label (default is black)
        • border - the colour of the label border (default is white)
        • font-size - manually set the font size (if omitted it will be scaled to the population where known)
        • font-weight - manually set the font weight (e.g. to "bold")
        • font-family - manually set the font family
    • markers - An array of markers
      • markers - A marker can be defined with the following properties:
        • icon - Can be either be a string (one of default, geo, geo-alt, asterisk, pin, balloon, balloon-heart, chat-square) or an object with the form:
          • svg - The SVG string to use
          • size - e.g. [40,40]
          • anchor - e.g. [20,0]
        • latitude - set the latitude of the marker
        • longitude - set the longitude of the marker
        • colour - the colour of the label (default is black)
        • tooltip - the content of an optional tooltip
  • padding - Set the padding between the data layer and the map edges. The value is given in the pixel scale of the generated map (which may not be the same as the pixels the map takes up on screen).
  • legend - Define the legend.
  • mapAttribution - Add some text before the tileset credit.
  • attribution - Add a line of attribution text under the visualisation.