Inventory of chart and map properties - GSS-Cogs/chart-builder GitHub Wiki
Chart and map properties
Charts and maps are generated dynamically within Chart Builder based on the following:
- user selected data sources and data series
- chart or map properties specified by the user (the publisher)
- chart or map properties specified by the designers/maintainers of Chart Builder
In the current implementation these various inputs come together to form a chart definition that is passed to Plotly as three objects: data, layout and config. These objects specify, respectively, 1) the data series to display 2) the layout of the chart/map, and 3) the Plotly configuration.
Places in the Chart Builder code where chart/map properties are configured and specified:
| File | Purpose | Notes |
|---|---|---|
src/context/ChartPropertiesSchema.ts |
Defines a set of chart/map properties that will be displayed to the user in the property configurator. The properties will be rendered dynamically into the side panel. Properties will be initialized with default values where required. | In the Volto connected Chart Builder, property values are persisted in the Volto block state and restored next time the block becomes active for editing. |
src/plotly/layout.ts |
Responsible for generating the layout properties for Plotly charts and maps. Examples are chart/map dimensions, margins, showing/hiding chart elements and setting text for chart elements. |
Separate functions exist for generating map and chart specific aspects of the layout. A function for common layout properties is also invoked and the objects are merged into the final Plotlylayout. |
src/plotly/chartDefinition.ts |
Generates Plotly data series for the charts or maps. Series (traces) are based on the user specified data, data-column to chart-axis allocations, series selection, series labels and formatting of series and legends. |
Separate functions exist to generate chart and map data series as there is little overlap in definition between them. |
src/plotly/config.ts |
The Plotly config specifies properties of the Plotly container, for example whether or not to show the mode bar. |
These properties don't have any influence on the appearance of the data visualisations themselves. |
src/components/chart-panel/chart-preview/chartPreview.ts |
The datarevision property of the Plotly layout is incremented each time the component renders which acts to force Plotly to re-render the chart or map. |
Required otherwise Plotly will not respond to changes in the chart configuration. |
Common layout properties
The common layout properties that apply to both charts and maps are defined in src/context/ChartPropertiesSchema and are mapped to the Plotly layout in src/plotly/layout.ts in the function getCommonLayout
| Name | Function | Set by | Input type | Default value | Comments |
|---|---|---|---|---|---|
| height | Sets the svg height in pixels | User | Text | "630" | |
| marginLeft | Sets the left margin in pixels | User | Text | "100" | |
| marginRight | Sets the right margin in pixels | User | Text | "50" | |
| marginTop | Sets the right margin in pixels | User | Text | "50" | |
| marginBottom | Sets the bottom margin in pixels | User | Text | "110" | |
| interactivity | Enables or disables hover info text for data series | User | Radio option | "x+y" | Possible values are "x+y" and "none" |
Chart layout properties
The chart layout properties are defined in src/context/ChartPropertiesSchema and are mapped to the Plotly layout in src/plotly/layout.ts in the function getChartLayout
| Name | Function | Set by | Input type | Default value | Comments |
|---|---|---|---|---|---|
| showLegend | Shows or hides the legend | User | Checkbox | true | |
| xAxisOffset | Sets the distance between the legend and the x axis | User | Text | -0.2 | Negative value moves the legend down. A value of -1 moves the legend down by the same height as the chart. Useful values are between 0 and - 0.3. |
| showGridLines | Shows or hides gridlines on the chart. | User | Checkbox | true | |
| xAxisTitle | Sets the title of the X axis | User | Text | "" | |
| xTickLabelMaxLength | Sets the maximum length of X axis tick labels | User | Text | 40 | Prevents long X axis tick labels (e.g. categorical labels) taking away space from the plot area. |
| xAxisTickAngle | Sets the X axis label rotation | User | Radio option | "-45" | Possible values are: "0", "45", "-45", "-90" |
| yAxisTitle | Sets the title of the Y axis | User | Text | "" | |
| orientation | Sets the orientation of the chart. | User | Radio option | "vertical" | Possible values are "vertical", or "horizontal". This property is useful for creating horizontal bar charts. |
Map layout properties
The map layout properties are defined in src/context/ChartPropertiesSchema and are mapped to the Plotly layout in src/plotly/layout.ts in the function getMapLayout
| Name | Function | Set by | Type | Default value | Comments |
|---|---|---|---|---|---|
| colorBarTitle | Sets the title for the map colorbar | User | Text | "" | To create new lines in the title the user needs to enter an html break element in the position where the newline should be. |
| colorBarWidth | Sets the width of the map colorbar in pixels | User | Text | "20" | |
| colorscale | Sets the colorscale for the choropleth map | User | Radio option | "Sequential" | Possible values are "Sequential" and "Diverging" |
| autocolorscale | Sets the map colorscale to be automatically assigned by Plotly | User | Checkbox | false | |
| hoverInfoUnit | Sets the unit text to display in the hoverinfo template that shows as the user hovers over geographical regions of the map. | User | Text | "" |
Chart data properties
Chart data properties are specified in two places src/context/ChartPropertiesSchema.ts and in src/plotly/chartDefinition.ts in the function getChartData.
| Name | Function | Set by | Type | Default value | Comments |
|---|---|---|---|---|---|
| barmode | Sets bar charts to display as either stacked or grouped where multiple series are available. Where only one series is available stacked and grouped are not relevant. | User | N/A | N/A | The barmode is inferred from the chart type. If the chart type is "Bar" then barmode is set as grouped. Otherwise it will be set as stacked. If another chart type is selected then barmode will be ignored. |
| x | Assigns the x series values for the chart | User | N/A | N/A | Values are defined by 1) the user's selection of a tidyData dataset 2) the user's assignment of a tidyData column to the category axis |
| y | Assigns the y series values for the chart | User | N/A | N/A | Values are defined by 1) the user's selection of a tidyData dataset 2) the user's assignment of a tidyData column to the dimension of interest 3) the user's selection of series to display from the set of available series |
| orientation | Sets the orientation of the chart as either vertical or horizontal. | User | Radio option | Horizontal | When the user changes the orientation to vertical chart builder will invert the x and y series assignments |
| name | Sets the name of a data series | User | Text | "" | The data series name(s) will be populated by default with the text from the dataset. The user can override this text in the UI. |
| hoverinfo | Enables or disables the hoverinfo (tooltip text) interactivity of the chart | User | Radio option | true | |
| type | Specifies the chart type to show | User | Radio option | Line | Stacked and Grouped subtypes of the bar chart type are defined by the barmode property. |
| color | Sets the color for the trace (data series) | Designer | N/A | N/A |
Map data properties
Map data properties are specified in two places 1) src/context/ChartPropertiesSchema.ts and 2) in the function getMapData of src/plotly/chartDefinition.ts .
| Name | Function | Set by | Type | Default value | Comments |
|---|---|---|---|---|---|
| type | Sets the map type | Designer | N/A | choropleth | Chart builder currently only supports the choropleth map type |
| locationmode | Sets the mechanism that Plotly uses to link GeoJson locations to values | Designer | N/A | geojson-id | |
| locations | Assigns an array of locations that Plotly uses to link choropleth map values to the specific location id in the GeoJson feature | User | N/A | N/A | The locations are determined by the dataset selected by the user |
| z | Assigns an array of choropleth values that Plotly links to the corresponding location (as above) based on index | User | N/A | N/A | The choropleth z values are determined by the dataset selected by the user. The values columns should be named values |
| text | Assigns an array of text values that Plotly links to the corresponding location (as above) based on index. The text values form the hoverinfo label for each location | User | N/A | N/A | The choropleth text values are determined by the dataset selected by the user |
| colorscale | Assigns an array of value - color arrays that form the colorscale definition. Plotly applies the colorscale to the colorbar which acts as a legend for the choropleth values | User and designer | Radio option | Sequential | The user choses from the options of sequential and diverging colorscales. The designer specifies the colors user in the colorscale |
| autocolorscale | Configures Plotly to automatically assign a colorscale to the colorbar | User | Checkbox | false | |
| featureidkey | Path to field in GeoJSON feature object with which to match the values passed in tolocations |
Designer | N/A | properties.geography_uri | Chart builder expects the provided GeoJson properties to include a property geography_uri that contains the GeoJson ids |
| marker>line | Formats the outline of the GeoJson feature on the map, e.g. outline of the polygon that draws the feature. We specify two sub-properties color and width | Designer | N/A | color: "rgb(123,123,123)" width: 0.25 | |
| colorbar>title | Sets the title of the colorbar | User | Text | "" | The user may enter a to create new lines in the title |
| colorbar>thickness | Sets the width of the colorbar in pixels | User | Text | "25" | |
| hovertemplate | Defines a custom hover template for the rollover tooltip that shows as the user hovers the mouse over different geographical features | Designer | N/A | N/A | The custom template shows the name of the region and the value. The geography_uri is hidden |
| hoverInfoUnit | Sets an optional unit of measure to include in the hovertemplate | User | Text | "" |