Chart Configuration

jwildfire edited this page Sep 26, 2017 · 24 revisions

Overview

The most straightforward way to customize a chart is by using a configuration object whose properties describe the chart's behavior and appearance. The object is passed to the Webcharts.createChart() factory function and is attached to the returned chart object.

Example

A fairly simple config object might look like this one for a grouped bar chart:

var config = {
  "max_width":"500",
  "x":{
    "label":"Medal Count",
    "type":"linear",
    "column":"count",
    domain: [0]
  },
  "y":{
    "type":"ordinal",
    "column":"Country",
    "sort":"total-descending"
  },
  "marks":[
    {
       "arrange":"grouped",
      "split":"type",
      "type":"bar",
      "per":["Country"],
      "attributes": {"fill-opacity": 0.8}
    }
  ],
  "gridlines":"x",
  "color_by":"type",
  colors: ["#8c7853", "#c0c0c0", "#e5c100"],
  legend: {
    label: 'Medal Type',
    order: ['Bronze', 'Silver', 'Gold']
  }
};

Data Mapping

A major role of the config object is to specify the visual encodings for the various columns in the data set specified in the chart.init(data) function. The following settings (described in detail below) all expect column names from the raw data:

Additional data mappings are possible using built in functions such as controls, tables, and webcharts.multiply and via custom callbacks

Detailed descriptions of the object's properties are found below.

config

object

an object whose properties describe the chart in its entirety, including axes, labels, marks to be drawn, etc.

config.x

object

an object whose properties describe the chart's x-axis: what type of scale it should represent, what values inform that scale, and the general appearance of the resulting axis

x.type

string

the type of scale to use; possible values are:

"linear" defines a straightforward numeric scale

"ordinal" defines a non-numeric scale, such as the one used for the x-axis on traditional bar charts

"time" defines a scale based on dates that are treated similarly to a linear numeric scale

"log" (experimental) defines a logarithmic numeric scale

default: "linear"

x.column

string required

a field from the chart's dataset whose values are used to define the x-scale

default: none

x.bin

number

applies only when x.type is set to "linear"
the number of bins into which to divide the values along the axis; useful for creating histograms or otherwise breaking continuous data into regular categories

default: none

x.domain

array

a manually-defined domain that overwrites the domain derived from the extent of the data supplied by x.column; defined as a two-member array where domain[0] is the lower extent of the domain and domain[1] is the upper extent; either one or both values can be provided

default: automatic

x.ticks

array

a manually-defined array of points for which to draw tick marks on the x axis (overwriting the default values from d3 scales and axis objects)

default: automatic

x.sort

string

applies only when x.type is set to "ordinal"
describes how the values in an ordinal scale should be sorted; can be 'alphabetical-ascending', 'alphabetical-descending', 'total-ascending', or 'total-descending'

"alphabetical-ascending" values are sorted alphanumerically

"alphabetical-descending" values are sorted reverse-alphanumerically

"total-ascending" values are sorted in increasing order based on the total corresponding y-value

"total-descending" values are sorted in decreasing order based on the total corresponding y-value

default: "alphabetical-ascending"

x.order

array

applies only when x.type is set to "ordinal"**
takes precedence over** x.sort; an explicit ordering of values in an ordinal scale, defined as an array of all possible axis values whose members are in the exact desired order

default: none

x.behavior

string

determines how the axis should behave when the chart's data is filtered; possible values are:

"raw" the axis represents the full range of values in the raw dataset

"flex" the axis represents only those values found in the current (filtered) dataset

"firstfilter" given the possible values in the first member of the chart's filters array, the axis will fit itself to the maximum extent of any possible value for that filter

default: "raw"

x.label

string or function

text that labels the axis, appearing between the tick marks and the outer margin of the chart; if a function is passed here, the this context is set to the current chart object; using a function is useful when controls are used to dynamically change the axis column (see this example)

default: none

x.format

string

a string specifier for d3.format that determines how numeric tick values on the axis should be formatted

default: ".1f"

config.y

object

an object whose properties describe the chart's y-axis; the same options apply to the y-axis as to the x-axis; see config.x above for specifics

config.marks

array

an array of objects, each of which defines a set of marks to be plotted on the chart; many charts will only need one object in this array, but more complicated charts may have many objects here - there is no limit!

mark.type

string required

determines what type of mark should be drawn; possible values are:

"circle" you guessed it! these marks will be circles, typically used to plot points in scatter plots

"line" marks are lines (rendered as <path> elements), used for line charts of all types

"bar" marks are bars (rendered as <rect> elements), used for bar charts and histograms

"text" marks are <text> nodes; useful for labeling values for other marks

default: none

mark.per

array required

an array of strings that map to columns in the chart's dataset, which determines how data should be grouped to be represented by the set of marks

default: none

mark.summarizeX

string

applies only when x.type is set to "linear" or "log"
An operation that summarizes the values plotted on the x-axis; possible values are:

"mean"

"median"

"min"

"max"

"sum"

"count"

"cumulative"

"percent"

default: "mean"

mark.summarizeY

string

applies only when y.type is set to "linear" or "log"
an operation that summarizes the values plotted on the y-axis; see mark.summarizeX for possible values

mark.values

object

an object that limits the data represented by the given set of marks; keys in the object point to dataset columns and are paired with arrays of possible values in that column. For instance:

{type: 'circle', per: ['subjectId'], values: {site: ['Boston', 'Chicago'] } }

will yield circles for each individual person, but only those in the Boston and Chicago sites.

mark.tooltip

string

a string defining text that should appear in the tooltip that appears when a user hovers their mouse over a mark; any text can be combined with some special identifiers that serve as placeholders for data tied to the mark:

$x will insert the mark's x-value

$y will insert the mark's y-value

[COLUMN] will insert the value of that dataset field associated with the current mark; if the mark represents grouped data, the value of [COLUMN] is the first value encountered in that group (and may therefore may be misleading if the value differs within the grouped data)

default: none

mark.text

string

applies only when mark.type is set to "text" a string defining text that should appear in the text node

$x will insert the mark's x-value

$y will insert the mark's y-value

[COLUMN] will insert the value of that dataset field associated with the current mark; if the mark represents grouped data, the value of [COLUMN] is the first value encountered in that group (and may therefore may be misleading if the value differs within the grouped data)

default: none

mark.radius

number

sets the post-transition radius of marks with type="circle". Note that mark.attributes.r sets the radius before transition, but is rarely used.

default: 4

mark.attributes

object

a set of attributes that will be assigned to each mark using standard d3.attr functionality; useful for tweaking specific element attributes like "fill-opacity", "stroke-width", "dx", etc.

default: none

mark.split

string

applies only when mark.type is set to "bar" a column in the chart's dataset which splits a set of marks into chunks, opposite to the way data is grouped by per; in conjunction with mark.arrange this allows for more complex bar charts

default: none

mark.arrange

string

applies only when mark.type is set to "bar" determines how the chunks of a bar should appear; possible values are:

"stacked" chunks are stacked one on top of the other to create a stacked bar chart

"grouped" chunks share the same baseline and their width is scaled to fit into the space occupied by a single, unsplit bar

"nested" (experimental) chunks share the same baseline and their width is scaled progressively so that each chunk appears "inside" another chunk; this is only sensible for certain types of data where certain categories are always inclusive of others

default: "grouped"

config.date_format

string

A standard format used by d3.format() used to convert date variables from string (the expected input type) to date objects before plotting. applies only when x.type or y.type is set to "time"

default: "%x"

config.transitions

boolean

a boolean value that determines whether the chart should animate changes, such as when marks or axes are adjusted by a configuration option or a browser window resize; useful to set to false when rendering charts on the server

default: true

config.resizable

boolean

a boolean value that determines whether the chart should adjust its dimensions based on its container; if set to false, the chart will conform to a rigid rectangle based on its width and aspect ratio or, if height is set, its width and height

default: true

config.max_width

number

a number that defines the maximum width of the chart, in pixels; works in conjunction with resizable so that, no matter how wide the chart's container element gets, the chart itself will not grow wider than this value; by default, this is set to the width of the chart's container element whenever the chart is initialized

default: automatic

config.margin

object

following the d3 convention, this is an object with top, bottom, left, and right properties that represent the padding around the outside of the chart's plotting area; these values represent the space (in pixels) between a chart's y-axis and the left side of the SVG canvas, a chart's x-axis and the bottom of the SVG canvas, etc.; by default, margins are automatically determined based on axis tick values, labels, text size, etc.

default: automatic

config.width

number

applies only when resizable is set to false
defines the absolute width of the chart (in pixels)

default: none

config.height

number

applies only when resizable is set to false
defines the absolute height of the chart (in pixels)

default: none

config.aspect

number

a number that defines the aspect ratio of the chart; works in conjunction with max_width or width to automatically decide the height of the chart
Is ignored if height is set explicitly

default: 1.33

config.range_band

number

yet another way of determining a chart's dimensions; manually sets the rangeBand of an ordinal scale used in an x- or y-axis so that the chart's width or height (depending on which axis is ordinal) is adjusted to accommodate the necessary number of ordinal values

default: automatic

config.scale_text

boolean

a boolean value that determines whether the text in the chart should automatically scale according to the chart's dimension; if true, text in the chart will be smaller in smaller charts and bigger in bigger charts; if false, the text will be a static size based on whatever style rules are applied to parent elements

default: true

config.color_by

string

a column from the chart's dataset whose unique values are used to define a color scale for the marks in the chart (i.e., these values are used in the input domain of an ordinal scale used to assign colors)

default: none

config.colors

array

an array listing the color values used to color marks in the chart (i.e., these values are used in the output range of an ordinal scale used to assign colors); the default palette comes from Color Brewer

default:

['rgb(102,194,165)','rgb(252,141,98)','rgb(141,160,203)','rgb(231,138,195)',
'rgb(166,216,84)','rgb(255,217,47)','rgb(229,196,148)','rgb(179,179,179)']

config.color_dom

array

an array listing the unique values of config.color_by; useful when not all values are represented in the data

default: unique values of config.color_by

config.interpolate

character

applies only when mark.type is set to "line"

interpolation method to be used by d3.svg.line

default: "linear"

legend.mark

string

determines what type of mark should be used in the legend; defaults to whatever type of mark is plotted in the chart itself, but can be overridden by setting this option to "square", "circle", or "line"

default: automatic

legend.label

string

a label for the legend; defaults to the dataset column provided to color_by, which is overridden by any value set here, including an empty string "" (if no label is desired)

default: automatic

legend.order

array

an array of color_by values whose members are in the exact desired order; this order determines the assignments of its values to the colors in the colors array

default: none

legend.location

string

a string that determines where the legend will be draw in relation to the chart; possible values are:

"top" legend will appear above the chart; legend items are listed horizontally

"bottom" legend will appear below the chart; legend items are listed horizontally

"right" legend will appear to the right of the chart, if there is sufficient room; legend items are stacked vertically

"left" legend will appear to the left of the chart, if there is sufficient room; legend items are stacked vertically

default: "bottom"

legend.behavior

string

determines how the legend should behave when the chart's data is filtered; possible values are:

"raw" the axis represents the full range of values in the raw dataset

"flex" the axis represents only those values found in the current (filtered) dataset

default: "raw"

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.