Class pvc.options.charts.BasicChart
| Constructor Attributes | Constructor Name and Description |
|---|---|
| <abstract> |
The options documentation class of the basic chart facet.
|
| Field Attributes | Field Name and Description |
|---|---|
| Chart > Data | |
|
An array of dimensions calculations.
|
|
|
A map whose keys are
the dimension type group names and whose values are
the default dimension type group options.
|
|
|
A map whose keys are
the dimension type names and whose values are
the dimension type options.
|
|
|
The chart's format provider.
|
|
|
The separator used to join the labels of the values of
a multi-dimensional visual role.
|
|
|
Indicates if datums
whose value in every measure dimension is null
are ignored.
|
|
| Chart > Data Source | |
|
Indicates if the data source is in the
crosstab format, or, when
false, the
relational format.
|
|
|
The number of columns of the "categories"
physical group that the data source contains.
|
|
|
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.
|
|
|
Indicates if multiple measures "are in" columns or in rows (applies to crosstab data format).
|
|
|
The separator character
used to join multiple values in the crosstab format,
and to build composite keys for multiple level groupings.
|
|
|
The confirmation mode of the column types declared in a dataset's metadata.
|
|
|
Indicates if the data source contains multiple columns of the "measures"
physical group.
|
|
|
The indexes of columns of the "measures"
physical group (applies to relational data format).
|
|
|
A list of dimension names to load from corresponding
logical table columns.
|
|
|
Swaps the columns of the "series" and "categories"
physical groups.
|
|
| Chart > General | |
|
The identifier of the HTML element,
or the element itself,
where the chart is to be created in.
|
|
|
The set of compatibility flags.
|
|
|
The CCC version that the chart should run in.
|
|
| Chart > Interaction | |
|
Indicates if the chart is clickable by the user.
|
|
| <deprecated> |
Indicates if tooltips are enabled
and contains additional tooltip presentation options.
|
| <deprecated> |
Contains additional tooltip presentation options.
|
|
Indicates if tooltips are enabled
and contains additional tooltip presentation options.
|
|
| Chart > Layout | |
|
The margins of the
root content panel, in pixel units or as a percentage.
|
|
|
The paddings of the
root content panel, in pixel units or as a percentage.
|
|
|
The height of the
root chart, in pixels.
|
|
|
The margins of the
root chart.
|
|
|
The chart orientation indicates if
its main direction is vertical or horizontal.
|
|
|
The paddings of the
root chart.
|
|
|
The width of the
root chart, in pixels.
|
|
| Chart > Visual Roles | |
|
The
dataPart visual role is a chart-level visual role that
allows partitioning of the data into several datum subsets.
|
|
|
The chart's visual roles map.
|
|
| Layout | |
|
The minimum size of the plot panel, in pixel units.
|
|
| Panels | |
|
The title panel of the root chart.
|
|
| Plots | |
|
An array of plots.
|
|
| Method Attributes | Method Name and Description |
|---|---|
| Chart > Actions | |
|
clickAction(scene)
A callback function that is called
when the user 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.
|
|
| Chart > Data | |
|
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.
|
|
Default Data Format
This section describes, in general, the data format accepted by CCC charts. Most of what is here presented applies to all chart types.
The option #crosstabMode is by far the most important, as it makes the top-level choice between the two data formats: relational and crosstab.
Each of this formats has its own variants and, also, both have some configuration options in common.
Relational Format
This format is a regular tabular format where each column of the data source corresponds to a different property of the described entity.
Each entity is described in a single row. Although not required, usually, one or more of the columns together identify the entity.
Example relational dataset
{
"metadata": [
{"colName": "city", "colType": "String", "colLabel": "City"},
{"colName": "date", "colType": "String", "colLabel": "Date"},
{"colName": "quant", "colType": "Numeric", "colLabel": "Quantity"}
],
"resultset": [
["London", "2011-06-05", 72],
["London", "2011-06-06", 50],
["Paris", "2011-06-05", 27],
["Paris", "2011-06-06", 5],
["Lisbon", "2011-06-05", 30],
["Lisbon", "2011-06-12", 60]
]
}
Crosstab Format
The cross-tabular format goes away from the one-to-one correspondence between row and entity, and column and property.
Instead, it provides a grouped and aggregated view of the entities and their properties:
- One row is spawned per distinct combination of the values of the "rows" properties
- One column is spawned per distinct combination of the values of the "columns" properties
- One cell contains a single somehow aggregated value, or null, corresponding to its row and column's value
The way in which a cross-tabular form is encoded in a single-tabular structure is, in kind words, sui generis. The first N columns are "rows" properties, and maintain the column-property correspondence. The following columns, however, each correspond to a distinct combination of the values of the "columns" properties. This leads to the values of the "columns" properties being placed in a column's colName attribute (see example, below).
Downsides
This form of encoding is nice and concise, but achieves that at the cost of occupying the space intended for metadata and, thus, resulting in absent metadata for the underlying entities "columns" and "measures" properties.
Because of this reason, unfortunately, CCC could never really rely on the values of the "colName" and "colLabel" metadata attributes. We do try to use these, when they actually contain metadata, to default dimensions' labels (see #dataIgnoreMetadataLabels).
Example crosstab dataset with one property per group
This is a crosstab dataset with one "rows", one "columns" and one "measures" property.
{
"metadata": [
{"colName": "date", "colType": "String", "colLabel": "Date" },
{"colName": "London", "colType": "Numeric", "colLabel": "London"},
{"colName": "Paris", "colType": "Numeric", "colLabel": "Paris" },
{"colName": "Lisbon", "colType": "Numeric", "colLabel": "Lisbon"}
],
"resultset": [
["2011-06-05", 72, 27, 30],
["2011-06-06", 50, 5, null],
["2011-06-12", null, null, 60]
]
}
Example crosstab dataset with two properties per discrete group
This is a crosstab dataset with two "rows" properties, two "columns" properties and one "measures" property.
{
"metadata": [
{"colName": "date", "colType": "String", "colLabel": "Date" },
{"colName": "family", "colType": "String", "colLabel": "Product Family"},
{"colName": "London~Ready", "colType": "Numeric", "colLabel": "London~Ready" },
{"colName": "London~InProgress", "colType": "Numeric", "colLabel": "London~In Progress"},
{"colName": "Paris~Ready", "colType": "Numeric", "colLabel": "Paris~Ready" },
{"colName": "Paris~InProgress", "colType": "Numeric", "colLabel": "Paris~In Progress" },
{"colName": "Lisbon~InProgress", "colType": "Numeric", "colLabel": "Lisbon~In Progress"}
],
"resultset": [
["2011-06-05", "Cars", 52, 0, 15, 2, 15],
["2011-06-05", "Planes", 10, 10 10, 0, 15],
["2011-06-06", "Cars", 10, 10, 1, 3, null],
["2011-06-06", "Planes", 10, 20, 0, 1, null],
["2011-06-12", "Cars", null, null, null, null, 58],
["2011-06-12", "Planes", null, null, null, null, 2]
]
}
Example crosstab dataset with two properties in every group
This is a crosstab dataset with two "rows" properties, two "columns" properties and two "measures" property. Yep. Sales are just ten times the quantity...For this example to work, both options #isMultiValued and #dataMeasuresInColumns must be set to true.
{
"metadata": [
{"colName": "date", "colType": "String", "colLabel": "Date" },
{"colName": "family", "colType": "String", "colLabel": "Product Family"},
{"colName": "London~Ready~quant", "colType": "Numeric", "colLabel": "London~Ready~Quantity" },
{"colName": "London~Ready~sales", "colType": "Numeric", "colLabel": "London~Ready~Sales" },
{"colName": "London~InProgress~quant", "colType": "Numeric", "colLabel": "London~In Progress~Quantity"},
{"colName": "London~InProgress~sales", "colType": "Numeric", "colLabel": "London~In Progress~Sales" },
{"colName": "Paris~Ready~quant", "colType": "Numeric", "colLabel": "Paris~Ready~Quantity" },
{"colName": "Paris~Ready~sales", "colType": "Numeric", "colLabel": "Paris~Ready~Sales" },
{"colName": "Paris~InProgress~quant", "colType": "Numeric", "colLabel": "Paris~In Progress~Quantity" },
{"colName": "Paris~InProgress~sales", "colType": "Numeric", "colLabel": "Paris~In Progress~Sales" },
{"colName": "Lisbon~InProgress~quant", "colType": "Numeric", "colLabel": "Lisbon~In Progress~Quantity"},
{"colName": "Lisbon~InProgress~sales", "colType": "Numeric", "colLabel": "Lisbon~In Progress~Sales" }
],
"resultset": [
["2011-06-05", "Cars", 52, 520, 0, 0, 15, 150, 2, 20, 15, 150],
["2011-06-05", "Planes", 10, 100, 10 100, 10, 100, 0, 0, 15, 150],
["2011-06-06", "Cars", 10, 100, 10, 100, 1, 10, 3, 30, null, null],
["2011-06-06", "Planes", 10, 100, 20, 200, 0, 0, 1, 10, null, null],
["2011-06-12", "Cars", null, null, null, null, null, null, null, null, 58, 580],
["2011-06-12", "Planes", null, null, null, null, null, null, null, null, 2, 200]
]
}
Physical Column Groups
Traditionally, cross-tabular data contains "categories" in "rows" and "series" in "columns". Because of this, when in the context of the crosstab format, these terms end up being used interchangeably.The separation of columns, at the data format layer, results in (what is referred to in this text as) physical column groups. Three physical groups are identified: "series", "categories" and "measures".
Crosstab Format
As explained, in the crosstab format, the separation is physical, structural, unchangeable.Remember, however, that the the "categories" physical group is defined above as "the first N columns are rows properties". By default, N is determined as the number of initial, consecutive columns with a "string" type. If that is not the case, option #dataCategoriesCount allows stating otherwise.
Relational Format
In the relational format, however, the separation between "series" and "categories" is not physical, but, simply, convenient. As you'll see below, the separation helps in automatically loading data into common CCC's dimensions.By default, when a data source contains a single discrete column, it is a considered a column of the "categories" physical group. Otherwise, if it contains more discrete columns, the first is considered of the "series" physical group, and all the remaining of the "categories" physical group. This division is arbitrary. If you want more control, the option #dataCategoriesCount allows limiting the number of columns globbed by the "categories" physical group.
Series in Rows, please
It is common enough to want to swap the columns of the "series" and "categories" physical groups. The option #seriesInRows exists for just that.Logical Table
The logical table, or, in some contexts, the logical row, is a reorganization of the source data into a logical format in which columns are properties of the underlying described entity and each entity is described in a single row. This is true, independently of the data source format being crosstab or relational.In the relational format, this is already the case. In the crosstab format, however, a logical row contains information from one of the source rows and one of the source "columns" columns.
Apart from this restructuring, the columns of a logical row are also organized according to their source physical group:
| series | categories | measures |
Because of this reordering, in the relational format, the logical row can differ from the source row, when, in the latter, the columns of type "string" are not all before the columns of type "number".
Default Dimension Mapping
Many chart types, like the pie, bar and point family, heat grid and box plot, automatically define and load dimensions — CCC's data column concept — for each of the logical table's physical groups, with names from the corresponding dimension groups: "series", "category" and "value". For example, if there are two columns of the "series" physical group, two of the "categories" physical group and one of the "measures" physical group, the logical row would have its columns mapped to dimensions in the following way:| series | series2 | category | category2 | value |
Other chart types, like the metric-point, bullet, sunburst, treemap charts, only rely on the discrete/continuous separation of the logical table columns and automatically generate dimensions, from available columns, in other custom ways. See each chart type's options documentation page for information on its data format.
Explicit Dimension Mapping
Whenever the default dimension mapping does not satisfy your needs, the #readers option allows mapping each position of the logical row explicitly and independently.For example, one could obtain the mapping:
| category | series | series2 | value | category2 |
{
readers: ["category", "series", "series2", "value", "category2"]
}
Another use of the
readers option is to be able to
specify business names for the names of dimensions.
For example, for the last crosstab format example,
"crosstab dataset with two properties in every group",
one would achieve the same effect, but using business dimension names,
with the mapping:
| city | orderState | date | family | quantity | sales |
{
readers: ["city", "orderState", "date", "family", "quantity", "sales"],
visualRoles: {
series: "city, orderState",
category: "date, family",
value: "quantity"
}
}
Can be specified to calculate the values of certain dimensions.
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.
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.
For example, if a visual role, has the dimensions "Territory" and "ProductType", a compound value could be shown as "EMEA ~ Classic Cars".
See also #dataSeparator.
- Default Value:
- ' ~ '
A dimension is considered a measure dimension if there is at least one measure visual role currently bound to it.
- Default Value:
- true
- Default Value:
- true
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.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
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.
See also #groupedLabelSep.
- Default Value:
- '~'
The default value depends on the chart type. The bullet chart type has a default of pvc.options.varia.DataTypeCheckingMode#Extended. All other chart types have a default of pvc.options.varia.DataTypeCheckingMode#Minimum.
Data type checking can be disabled by specifying the value pvc.options.varia.DataTypeCheckingMode#None.
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
This option only applies when #isMultiValued is true.
By default, these are the indexes of continuous columns.
Can be a string containing a comma separated list of dimension names.
More generally, this option accepts an array of dimensions readers.
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
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.
See also BasicChart#compatVersion.
The value 1 emulates version 1 of CCC.
See also BasicChart#compatFlags.
- Default Value:
- Infinity
If this option is false, any click-related actions will not be executed (ex: #clickAction, Chart#doubleClickAction, or pvc.options.axes.DiscreteCartesianAxis#clickAction).
- Default Value:
- false
- Deprecated:
- Use #tooltip instead.
- Deprecated:
- Use #tooltip instead.
In a small multiples chart, the margins of the content panel of a small chart can be set with the property smallContentMargins.
See pvc.options.varia.Sides for information about the different supported data types.
- Default Value:
- 0
In a small multiples chart, the paddings of the content panel of a small chart can be set with the property smallContentPaddings.
See pvc.options.varia.Sides for information about the different supported data types.
- Default Value:
- 0
- Default Value:
- 300
In a small multiples chart, the margins of the small charts can be set with the property smallMargins.
See pvc.options.varia.Sides for information about the different supported data types.
- Default Value:
- 3
This property is supported by most chart types.
- Default Value:
- 'vertical'
In a small multiples chart, the paddings of a small chart can be set with the property smallPaddings.
See pvc.options.varia.Sides for information about the different supported data types.
- Default Value:
- 0
- Default Value:
- 400
This is a shortcut property for pvc.options.visualRoles.BasicChartVisualRoles#dataPart.
Besides the existing visual role properties - named after the visual role's name followed by the word Role - the visual roles map can be used, in code, to specify the visual roles information. The visual role name is the map's key, and the value, its options.
To determine the actual minimum size of the plot panel, the chart takes into account other restrictions imposed by options such as: pvc.options.axes.DiscreteCartesianAxis#bandSize, pvc.options.axes.DiscreteCartesianAxis#bandSizeMin, pvc.options.axes.DiscreteCartesianAxis#bandSpacing and pvc.options.axes.DiscreteCartesianAxis#bandSpacingMin.
In a small multiples chart, this option is ignored.
See pvc.options.varia.Size for information about the different supported data types.
When a value of type string is specified, it is the title text.
Can be specified to configure the options of the chart's internal plots (like main and plot2 and trend, when supported by the chart type), or to define and configure extra plots, of compatible types.
The types of plots that can be used together in a chart depend on:
- each plot's chart base class requirement, and
- further axes compatibility requirements; the visual roles being encoded by an axis must be compatible: they must have the same value type (number, date, or discrete) and, for discrete visual roles, they must also be bound to the same dimension list.
For additional information, specific of each chart type, see its documentation for property plots.
- Context:
- {pvc.visual.Context}
- Arguments:
- {pvc.visual.Scene} scene
- The scene associated with the visual item.
- Returns:
- {undefined}
You can use this action to:
- use the mark events API on time-series categorical charts
- extend in special ways the already created protovis marks.
- Context:
- {pvc.visual.Context}
- Arguments:
- {pvc.visual.Scene} scene
- The scene associated with the visual item.
- Returns:
- {undefined}
- Context:
- {pvc.visual.Context}
- Arguments:
- {pvc.visual.Scene} scene
- The scene associated with the visual item.
- Returns:
- {undefined}
When this property is specified, it sets also the pvc.options.format.FormatProvider#number format of the chart's format provider, BasicChart#format. Consequently, its value is inherited by the number dimension types' pvc.options.DimensionType#format.
Conversely, if the chart's format provider pvc.options.format.FormatProvider#number format is specified, its value sets this property, BasicChart#valueFormat.
When both are specified, the one in the chart's format provider has precedence.
Note: in a previous CCC version this property applied only to dimensions named value, value2, etc. It now applies to any numeric dimensions.
- Context:
- {null}
- Arguments:
- {number!} value
- The non-null number to format.
- Returns:
- {string!} The number formatted as a non-empty string.
- Context:
- {null}
- Arguments:
- {pvc.data.Datum} datum
- The datum being loaded.
- Returns:
- {boolean} true if the datum should be included, false if it should be excluded.