Class pvc.options.charts.MetricPointChart

Extends CartesianChart.

Class Summary
Constructor Attributes	Constructor Name and Description
<abstract>	MetricPointChart The common options documentation class for the Metric Line/Dot family charts.

Field Summary
Field Attributes	Field Name and Description
Axes
	baseAxis The base cartesian axis panel options.
	color The first color axis options.
	color2Axis The second color axis options.
	orthoAxis The orthogonal cartesian axis panel options.
<deprecated>	showXScale Indicates whether the `x` axis panel is shown.
<deprecated>	showYScale Indicates whether the `y` axis panel is shown.
	sizeAxis The size axis options.
Chart
	extensionPoints The extension points object contains style definitions for the marks of the chart.
	preserveLayout Indicates if the layout should be preserved between renders.
Chart - Multi > Layout
	multiChartColumnsMax The maximum number of small charts that should be displayed in a row.
	multiChartMax The maximum number of small charts that should be displayed.
	multiChartOverflow The strategy to follow when the resulting multi-chart layout does not fit entirely in the initial chart size.
	multiChartSingleColFillsHeight Indicates that, when the layout results in a single column and the value of #smallHeight is still to be determined, it should be set to all the initially available content height, instead of determining the height from the #smallAspectRatio and the #smallWidth.
	multiChartSingleRowFillsHeight Indicates that, when the layout results in a single row and the value of #smallHeight is still to be determined, it should be set to all the initially available content height, instead of determining the height from the #smallAspectRatio and the #smallWidth.
	smallAspectRatio The ratio of the width over the height of a small chart.
	smallContentMargins The margins of the content panel of a small chart.
	smallContentPaddings The paddings of the content panel of a small chart.
	smallHeight Fixates the height of each small chart, in pixel units or as a percentage.
	smallMargins The margins of a small chart.
	smallPaddings The paddings of a small chart.
	smallWidth Fixates the width of each small chart, in pixel units or as a percentage.
Chart > Data
	calculations An array of dimensions calculations.
	dimensionGroups A map whose keys are the dimension type group names and whose values are the default dimension type group options.
	dimensions A map whose keys are the dimension type names and whose values are the dimension type options.
	format The chart's format provider.
	groupedLabelSep The separator used to join the labels of the values of a multi-dimensional visual role.
	ignoreNulls Indicates if datums whose value in every measure dimension is null are ignored.
	slidingWindow Indicates the existence of the sliding window.
	timeSeries Indicates that dimensions whose name is "category1", "category2", etc, have a `Date` value type, by default.
	timeSeriesFormat The format string used to parse dimensions of the `Date` value type, by default.
Chart > Data Source
	crosstabMode Indicates if the data source is in the crosstab format, or, when `false`, the relational format.
	dataCategoriesCount The number of columns of the "categories" physical group that the data source contains.
	dataIgnoreMetadataLabels Indicates if the data source translation should ignore the column labels present in the data source's metadata as defaults for the labels of dimensions that are directly loaded from those columns.
	dataMeasuresInColumns Indicates if multiple measures "are in" columns or in rows (applies to crosstab data format).
	dataSeparator The separator character used to join multiple values in the crosstab format, and to build composite keys for multiple level groupings.
	dataTypeCheckingMode The confirmation mode of the column types declared in a dataset's metadata.
	isMultiValued Indicates if the data source contains multiple columns of the "measures" physical group.
	measuresIndexes The indexes of columns of the "measures" physical group (applies to relational data format).
	multiChartIndexes The indexes of columns of the logical table that are to feed the default `multiChart`, `multiChart2`, .
	readers A list of dimension names to load from corresponding logical table columns.
	seriesInRows Swaps the columns of the "series" and "categories" physical groups.
Chart > General
	canvas The identifier of the HTML element, or the element itself, where the chart is to be created in.
	compatFlags The set of compatibility flags.
	compatVersion The CCC version that the chart should run in.
Chart > Interaction
	animate Indicates if a chart should show an entry animation, every time it is fully rendered.
	clearSelectionMode Controls if and how the selection can be cleared by the user.
	clickable Indicates if the chart is clickable by the user.
	ctrlSelectMode When `true`, indicates that a selection made by the user replaces the current selection, if any.
	doubleClickMaxDelay The maximum number of milliseconds, between two consecutive clicks, for them to be considered a double-click.
	hoverable Indicates if the chart's visual elements are automatically highlighted when the user hovers over them with the mouse.
	interactive Indicates if chart interaction is enabled.
	pointing Contains options related to the way the pointing events are handled (ex: over, out).
	pointingMode The pointing mode used by the chart.
	selectable Indicates if the chart's visual elements can be selected by the user, by clicking on them or using the rubber-band.
<deprecated>	showTooltips Indicates if tooltips are enabled and contains additional tooltip presentation options.
<deprecated>	tipsySettings Contains additional tooltip presentation options.
	tooltip Indicates if tooltips are enabled and contains additional tooltip presentation options.
Chart > Layout
	contentMargins The margins of the root content panel, in pixel units or as a percentage.
	contentPaddings The paddings of the root content panel, in pixel units or as a percentage.
	height The height of the root chart, in pixels.
	leafContentOverflow Indicates what is to be done with content that overflows in leaf charts.
	margins The margins of the root chart.
	orientation The chart orientation indicates if its main direction is vertical or horizontal.
	paddings The paddings of the root chart.
	width The width of the root chart, in pixels.
Chart > Style
	plotFrameVisible Indicates whether the plot frame is drawn in leaf charts.
Chart > Visual Roles
	colorRole The `color` visual role is a plot-level visual role that is visually encoded by the color of visual elements.
	dataPartRole The `dataPart` visual role is a chart-level visual role that allows partitioning of the data into several datum subsets.
	multiChartRole The `multiChart` visual role is a chart-level visual role that allows turning a chart into a small multiples chart, http://en.wikipedia.org/wiki/Small_multiple.
	seriesRole The `series` visual role is a plot-level visual role that represents a series of connected data points.
	sizeRole The `size` visual role is a plot-level visual role that is visually encoded by the size of visual elements.
	visualRoles The chart's visual roles map.
	xRole The `x` visual role is a plot-level visual role that is visually encoded by the base position of the "point" visual element.
	yRole The `y` visual role is a plot-level visual role that is visually encoded by the orthogonal position of the "point" visual element.
Layout
	plotSizeMin The minimum size of the plot panel, in pixel units.
Panels
	legend The legend panel of the root chart.
	legendAreaVisible Indicates if the legend panel is visible.
	title The title panel of the root chart.
Panels - Multi
	smallTitle The title panel of the small chart.
Plots
	plots An array of cartesian plots.
	trend The trend plot is activated when the other chart plots indicate that their data should be trended.

Method Summary
Method Attributes	Method Name and Description
Chart > Actions
	clickAction(scene) A callback function that is called when the user clicks on a visual element.
	doubleClickAction(scene) A callback function that is called when the user double-clicks on a visual element.
	renderCallback(scene) A callback function that is called before the chart is rendered, but after if has been pre-rendered.
	renderedCallback(scene) A callback function that is called after the chart has finished rendering, including any animations.
	selectionChangedAction(selectedDatums, selectedChangedDatums) A callback function that is called when, after selection has changed, the chart is updated to reflect the change.
	userSelectionAction(selectingDatums, selectingGroup) A callback function that is called when the user performs a selection, but before the corresponding datums' selected state is actually changed.
Chart > Data
	percentValueFormat(value) A function used to format non-null numeric values as percentages.
	valueFormat(value) A function that formats the non-null values of numeric dimensions.
Chart > Data Source
	dataWhere(datum) A function that filters datums as they are being loading.

Class Detail

<abstract> pvc.options.charts.MetricPointChart

The common options documentation class for the Metric Line/Dot family charts.

Default Data Format

For general information on the supported data formats see BasicChart.

The metric-point chart family employs a non-default logical row to dimensions mapping:

All of the free discrete columns of the logical table generate and load free dimensions of the "series" dimension group: "series", "series2", "series4", ...
Free continuous columns of the logical table generate and load, in order, skipping the dimension when not-free, the following numeric dimensions:
1. x
2. y
3. color
4. size

All the following are possible default layouts and dimension assignments:

Index	0	1	2
Dimension	series	x	y
DataType	string	number	number

Index	0	1	2	3	4
Dimension	series	series2	x	y	color
DataType	string	string	number	number	number

Index	0	1	2	3	4
Dimension	series	x	y	color	size
DataType	string	number	number	number	number

How To Bind The Color Visual Role

The Metric Point's color visual role can be bound to either continuous or discrete dimensions.

In the default table layout, when enough free continuous columns exist, a dimension named "color" is generated and loaded — the name of the color role's default dimension —, resulting in a continuous color scale.

Otherwise, by default, the color visual role ends up being bound the dimensions of the series role — its default source role —, resulting in a discrete color scale.

The color role can also be bound to other discrete dimension(s), explicitly.

Solution 1

One possibility is to switch one of the automatically fed "series" dimensions to the color visual role. For example:

seriesRole: "series", // steal one here
colorRole:  "series2" // and assign it here

Solution 2

A second possibility is to simply match colors to "series":

seriesRole: {from: "series"} // same dimensions as the series visual role

Solution 3

Another possibility is to configure the BasicChart#readers with the actual layout, using the default dimension names of the desired visual roles. For example:

readers: "color, series, x, y, size"

Solution 4

Of course, you can (and probably should) use actual business names for the names of dimensions. To that end, both the readers and the visual roles' mappings need to be specified:

readers:      "orderType, productFamily, productType, expectedSales, actualSales, profit"
colorRole:    "orderType",
seriesRole:   "orderType", // controls drawing layer only
xRole:        "expectedSales",
yRole:        "actualSales",
sizeRole:     "profit"

Note that in this plot type, the series visual role only controls the layer of the dot cloud. Also, the dimensions "productFamily" and "productType" were not mapped to any visual role, and will only be presented in the tooltip.

Field Detail

{pvc.options.axes.AnyContinuousCartesianAxis} baseAxis

The base cartesian axis panel options.

When the chart BasicChart#orientation is vertical the base axis is laid out horizontally.

See pvc.options.axes.CartesianAxis to know the additional names by which a cartesian axis can be referred to.

{pvc.options.axes.AnyColorAxis} color

The first color axis options.

This axis can also be accessed by the property name color.

See pvc.options.axes.ColorAxis for more information on the way that the color axes' properties may be accessed.

{pvc.options.axes.DiscreteColorAxis} color2Axis

The second color axis options.

By default, the second plot, and the trend plot, use the second color axis.

See pvc.options.axes.ColorAxis for more information on the way that the color axes' properties may be accessed.

{pvc.options.axes.AnyContinuousCartesianAxis} orthoAxis

The orthogonal cartesian axis panel options.

When the chart BasicChart#orientation is vertical the orthogonal axis is laid out vertically.

See pvc.options.axes.CartesianAxis to know the additional names by which a cartesian axis can be referred to.

<deprecated> {boolean} showXScale

Indicates whether the x axis panel is shown.

Deprecated:
Use pvc.options.axes.CartesianAxis#visible, of the x axis, instead.

Default Value:: true

Borrowed from:: CartesianChart

<deprecated> {boolean} showYScale

Indicates whether the y axis panel is shown.

Deprecated:
Use pvc.options.axes.CartesianAxis#visible, of the y axis, instead.

Default Value:: true

Borrowed from:: CartesianChart

{pvc.options.axes.SizeAxis} sizeAxis

The size axis options.

{pvc.options.ext.MetricPointChartExtensionPoints} extensionPoints

The extension points object contains style definitions for the marks of the chart.

{boolean} preserveLayout

Indicates if the layout should be preserved between renders.

Default Value:: false

Borrowed from:: Chart

{number} multiChartColumnsMax

The maximum number of small charts that should be displayed in a row.

This property can receive a value of Infinity to indicate that all charts should be laid out in a single row.

Default Value:: 3

{number} multiChartMax

The maximum number of small charts that should be displayed.

The first small charts are chosen.

Default Value:: Infinity

{pvc.options.varia.MultiChartOverflow} multiChartOverflow

The strategy to follow when the resulting multi-chart layout does not fit entirely in the initial chart size.

Default Value:: 'grow'

{boolean} multiChartSingleColFillsHeight

Indicates that, when the layout results in a single column and the value of #smallHeight is still to be determined, it should be set to all the initially available content height, instead of determining the height from the #smallAspectRatio and the #smallWidth.

Default Value:: true

{boolean} multiChartSingleRowFillsHeight

Indicates that, when the layout results in a single row and the value of #smallHeight is still to be determined, it should be set to all the initially available content height, instead of determining the height from the #smallAspectRatio and the #smallWidth.

Default Value:: true

{number} smallAspectRatio

The ratio of the width over the height of a small chart.

It is used when the set of properties #smallWidth, #smallHeight, #multiChartColumnsMax, #multiChartSingleRowFillsHeight and #multiChartSingleColFillsHeight, is under-specified and is not enough to determine the value of both #smallWidth and #smallHeight.

The default value of the aspect ratio depends on the chart type, but is something around 4/3.

{number|string|pvc.options.varia.Sides} smallContentMargins

The margins of the content panel of a small chart.

See pvc.options.varia.Sides for information about the different supported data types.

Default Value:: 0

{number|string|pvc.options.varia.Sides} smallContentPaddings

The paddings of the content panel of a small chart.

See pvc.options.varia.Sides for information about the different supported data types.

Default Value:: 0

{number|string} smallHeight

Fixates the height of each small chart, in pixel units or as a percentage.

A value of type number, or of type string, but with numeric content, is interpreted as being in pixel units.

A value of type string, with numeric content that is suffixed by a "%" character, is interpreted as a percentage of the initially available content height.

This property may cause the small multiples chart to take up a greater width than the one specified in #height.

When this property is unspecified, its value depends on the evaluation of the #smallWidth property, which may impose it a value. If after the evaluation of #smallWidth this property remains unspecified, it is determined as follows.

If the layout will have a single column and the property #multiChartSingleColFillsHeight is true (it is by default) then the height will be the initially available content height.

If the layout will have a single row and the property #multiChartSingleRowFillsHeight is true (it is by default) then the height will be the initially available content height.

Otherwise, the property #smallAspectRatio is used to determine the height of the small chart from its determined width.

The aspect ratio is defaulted to a value that depends on the chart type, but is something around 4/3.

{number|string|pvc.options.varia.Sides} smallMargins

The margins of a small chart.

See pvc.options.varia.Sides for information about the different supported data types.

Default Value:: '2%'

{number|string|pvc.options.varia.Sides} smallPaddings

The paddings of a small chart.

See pvc.options.varia.Sides for information about the different supported data types.

Default Value:: 0

{number|string} smallWidth

Fixates the width of each small chart, in pixel units or as a percentage.

A value of type number, or of type string, but with numeric content, is interpreted as being in pixel units.

A value of type string, with numeric content that is suffixed by a "%" character, is interpreted as a percentage of the initially available content width.

This property may cause the small multiples chart to take up a greater width than the one specified in #width.

When this property is unspecified, a specified finite value, or a defaulted value, of the property #multiChartColumnsMax is used to determine it: by dividing the initially available content width by the maximum number of charts in a row that actually occur (so that if there are less small charts than the maximum that can be placed in a row, these, nevertheless, take up the whole width).

When an infinite value is specified for #multiChartColumnsMax, the small charts are laid out in a single row, and so the width is calculated from the height #smallHeight, using the aspect ratio #smallAspectRatio. The height is defaulted to the initially available content height. The aspect ratio is defaulted to a value that depends on the chart type, but is something around 4/3. The width is then calculated.

{list(pvc.options.DimensionsCalculation)} calculations

An array of dimensions calculations.

Can be specified to calculate the values of certain dimensions.

Borrowed from:: BasicChart

{map(string : pvc.options.DimensionType)} dimensionGroups

A map whose keys are the dimension type group names and whose values are the default dimension type group options.

A dimension type group is a group of dimension types that have a common non-numeric prefix in its name.

This property does not define any dimension types, per si, but allows specifying default values for dimension types of a group, that apply in case they are effectively used.

Borrowed from:: BasicChart

{map(string : pvc.options.DimensionType)} dimensions

A map whose keys are the dimension type names and whose values are the dimension type options.

You don't need to define dimensions unless you want to change their name or properties. Charts automatically define default dimensions to satisfy their visual roles' requirements.

Dimension options can be partial, so that it is possible to override only certain options.

Borrowed from:: BasicChart

{pvc.options.format.FormatProvider} format

The chart's format provider.

Borrowed from:: BasicChart

{string} groupedLabelSep

The separator used to join the labels of the values of a multi-dimensional visual role.

For example, if a visual role, has the dimensions "Territory" and "ProductType", a compound value could be shown as "EMEA ~ Classic Cars".

Relational format

Allows splitting the discrete columns between the "series" and "category" physical groups, in a custom way.

By default, if only a single discrete column exists, it is a "category". Otherwise, the first column is a "series" column and all the remaining are "category" columns.

Crosstab format

This is taken to be the number of consecutive discrete columns, from the first, or 1, if there are none.

Borrowed from:: BasicChart

{boolean} dataIgnoreMetadataLabels

Indicates if the data source translation should ignore the column labels present in the data source's metadata as defaults for the labels of dimensions that are directly loaded from those columns.

The capability to use the data source's provided metadata labels is most useful in the relational format, i.e., when #crosstabMode is false. The crosstab format does not provide metadata information for the series/columns data. Also, only when both #isMultiValued and #dataMeasuresInColumns are true, is there label information for the measures metadata.

Default Value:: false

Borrowed from:: BasicChart

{boolean} dataMeasuresInColumns

Indicates if multiple measures "are in" columns or in rows (applies to crosstab data format).

This option only applies when #isMultiValued is true.

When true, the data source contains columns for each combination of "series" columns' values and measure dimension.

When false, the data source contains rows for each combination of "categories" columns' values and measure dimension.

Borrowed from:: BasicChart

{string} dataSeparator

The separator character used to join multiple values in the crosstab format, and to build composite keys for multiple level groupings.

Relational format

Controls whether the option #measuresIndexes applies.

Crosstab format

Depending on the value of #dataMeasuresInColumns, measures are either in columns or in rows.

Default Value:: false

Borrowed from:: BasicChart

{number|string|list(number|string)} measuresIndexes

The indexes of columns of the "measures" physical group (applies to relational data format).

This option only applies when #isMultiValued is true.

By default, these are the indexes of continuous columns.

Borrowed from:: BasicChart

{number|string|list(number|string)} multiChartIndexes

The indexes of columns of the logical table that are to feed the default multiChart, multiChart2, ... dimensions.

See BasicChart#readers for related information.

{string|list(pvc.options.DimensionsReader)} readers

A list of dimension names to load from corresponding logical table columns.

Can be a string containing a comma separated list of dimension names.

More generally, this option accepts an array of dimensions readers.

Borrowed from:: BasicChart

{boolean} seriesInRows

Swaps the columns of the "series" and "categories" physical groups.

The name of this option is inspired in the crosstab/ matrix format, where the "series" values are placed in the first row, and "category" values are placed in the first column (corner cell is empty).

Default Value:: false

Borrowed from:: BasicChart

{string|object} canvas

The identifier of the HTML element, or the element itself, where the chart is to be created in.

The chart element will be a child of the canvas element.

When unspecified, the chart element will be added as the last child of the HTML document body.

Borrowed from:: BasicChart

{pvc.options.varia.CompatibilityFlags} compatFlags

The set of compatibility flags.

Types By Namespace

cdo

def

pvc

pvc.data

pvc.options

pvc.options.axes

pvc.options.charts

pvc.options.ext

pvc.options.format

pvc.options.marks

pvc.options.panels

pvc.options.plots

pvc.options.varia

pvc.options.visualRoles

pvc.visual

Class pvc.options.charts.MetricPointChart

Default Data Format

How To Bind The Color Visual Role

Solution 1

Solution 2

Solution 3

Solution 4

Relational format

Crosstab format

Relational format

Crosstab format