From b0dcaa158fcb2bd595a258a4faa8d83647855ec9 Mon Sep 17 00:00:00 2001 From: "Kanit \"Ham\" Wongsuphasawat" Date: Thu, 21 Jul 2016 13:23:44 +0200 Subject: [PATCH] Add docs & examples for ordinal `fit`, top-level `width` and `height`. Fix #1356 --- examples/specs/bar_size_default.json | 15 ++++++++++++ examples/specs/bar_size_explicit.json | 17 ++++++++++++++ examples/specs/bar_size_fit.json | 16 +++++++++++++ site/docs/config.md | 4 ++-- site/docs/scale.md | 2 +- site/docs/size.md | 34 ++++++++++++++++++++------- site/docs/spec.md | 4 +++- 7 files changed, 80 insertions(+), 12 deletions(-) create mode 100644 examples/specs/bar_size_default.json create mode 100644 examples/specs/bar_size_explicit.json create mode 100644 examples/specs/bar_size_fit.json diff --git a/examples/specs/bar_size_default.json b/examples/specs/bar_size_default.json new file mode 100644 index 00000000000..2542749f952 --- /dev/null +++ b/examples/specs/bar_size_default.json @@ -0,0 +1,15 @@ +{ + "data": {"url": "data/cars.json"}, + "mark": "bar", + "encoding": { + "x": { + "field": "Origin", + "type": "nominal" + }, + "y": { + "aggregate": "count", + "field": "*", + "type": "quantitative" + } + } +} diff --git a/examples/specs/bar_size_explicit.json b/examples/specs/bar_size_explicit.json new file mode 100644 index 00000000000..d072269b28d --- /dev/null +++ b/examples/specs/bar_size_explicit.json @@ -0,0 +1,17 @@ +{ + "width": 120, + "height": 120, + "data": {"url": "data/cars.json"}, + "mark": "bar", + "encoding": { + "x": { + "field": "Origin", + "type": "nominal" + }, + "y": { + "aggregate": "count", + "field": "*", + "type": "quantitative" + } + } +} diff --git a/examples/specs/bar_size_fit.json b/examples/specs/bar_size_fit.json new file mode 100644 index 00000000000..d45aabff1d7 --- /dev/null +++ b/examples/specs/bar_size_fit.json @@ -0,0 +1,16 @@ +{ + "data": {"url": "data/cars.json"}, + "mark": "bar", + "encoding": { + "x": { + "field": "Origin", + "type": "nominal", + "scale": {"bandSize": "fit"} + }, + "y": { + "aggregate": "count", + "field": "*", + "type": "quantitative" + } + } +} diff --git a/site/docs/config.md b/site/docs/config.md index 46ac90877c2..d511d14a049 100644 --- a/site/docs/config.md +++ b/site/docs/config.md @@ -63,8 +63,8 @@ Each plot in either a single plot or a trellis plot is called a _cell_. Cell con | Property | Type | Description | | :------------ |:-------------:| :------------- | -| width | Integer | The width of the single plot or each plot in a trellis plot when the visualization has continuous x-scale. (If the plot has ordinal x-scale, the width is determined by the x-scale's [`bandSize`](scale.html#ordinal) and the cardinality of the x-scale. If the plot does not have a field on `x`, the width is derived from [scale config](#scale-config)'s `bandSize` for all marks except `text` and from [scale config](#scale-config)'s `textBandWidth` for `text` mark.) __Default value:__ `200` | -| height | Integer | The height of the single plot or each plot in a trellis plot when the visualization has continuous y-scale. (If the visualization has ordinal y-scale, the height is determined by the `bandSize` and the cardinality of the y-scale. If the plot does not have a field on `y`, the height is [scale config](#scale-config)'s `bandSize`.) __Default value:__ `200` | +| width | Integer | The default width of the single plot or each plot in a trellis plot when the visualization has a continuous (non-ordinal) x-scale or ordinal x-scale with `bandSize` = `"fit"`. __Default value:__ `200` | +| height | Integer | The default height of the single plot or each plot in a trellis plot when the visualization has a continuous (non-ordinal) y-scale with `bandSize` = `"fit"`. __Default value:__ `200` | **For more information about visualization's size, please see [Customizing Size](size.html) page.** diff --git a/site/docs/scale.md b/site/docs/scale.md index 7a60f975edb..b73372875a8 100644 --- a/site/docs/scale.md +++ b/site/docs/scale.md @@ -218,7 +218,7 @@ For ordinal, quantitative, and time fields, `range` can be a two-element array d | Property | Type | Description | | :------------ |:-------------:| :------------- | -| bandSize | Number | Width for each `x` or `y` ordinal band. __Default value:__ for `x` ordinal scale of a `text` mark, derived from [scale config](config.html#scale-config)'s `textBandWidth`; otherwise, derived from [scale config](config.html#scale-config)'s `bandSize`. | +| bandSize | Integer | String | Width for each `x` or `y` ordinal band. This can be an integer value or a string `"fit"`. For `"fit"`, the band size will be automatically adjusted to fit the scale for the specified width (for x-axis) or height (for y-axis). __Default value:__ for `x` ordinal scale of a `text` mark, derived from [scale config](config.html#scale-config)'s `textBandWidth`; otherwise, derived from [scale config](config.html#scale-config)'s `bandSize`. __Warning__: Numeric `bandSize` will be applied only if the top-level `width` (for x-scale) or `height` (for y-scale) is not specified. If `width` (for x-scale) or `height` (for y-scale) is specified, `bandWidth` will always be `"fit"`. | | padding | Number | • For `x` and `y` channels, the padding is a multiple of the spacing between points. A reasonable value is 1.0, such that the first and last point will be offset from the minimum and maximum value by half the distance between points. (See D3's [`ordinalRangePoints()`](https://github.com/mbostock/d3/wiki/Ordinal-Scales#ordinal_rangePoints) for illustration.) __Default value:__ derived from [scale config](config.html#scale-config)'s `padding`
• For `row` and `column`, padding is a pixel value for padding between cells in the trellis plots. __Default value:__ derived from [facet scale config](config.html#facet-scale-config)'s `padding`. | {:#ex-bandwidth} diff --git a/site/docs/size.md b/site/docs/size.md index 6f6cd99021c..b935dcef6a5 100644 --- a/site/docs/size.md +++ b/site/docs/size.md @@ -9,20 +9,38 @@ At its core, a Vega-Lite specification describes a single plot. When a [facet ch ## Width and Height of a Single Plot -The width of a single plot or each cell of a trellis plot is determined by the properties of the `x` channel: +This includes the width of a single plot or each cell of a trellis plot. -- If the `x` channel has an ordinal scale, the width is a product of the scale's [`bandSize`]((scale.html#ordinal)) and the field's cardinality, or number of possible distinct values of the field mapped to the `x` channel, plus the scale's padding. (_bandWidth * (xCardinality + xPadding)_). -- If `x` has a continuous scale (either quantitative or time), the width is drawn directly from the `width` property of the [cell configuration](config.html#cell-config). -- If `x` is not mapped to a field, the width is derived from [scale config](#scale-config)'s `bandSize` for all marks except `text` and from [scale config](#scale-config)'s `textBandWidth` for `text` mark. +### Explicitly Specified Width and Height -Similarly, the height of a single plot or each cell of a trellis plot is determined by the properties of the `y` channel: +When the top-level `width` property is specified, the width of the single plot is the specified value for all scale types of the x-axis. Similarly, when the top-level `height` property is specified, the height of the single plot is the specified value for all scale types of the y-axis. -- If the `y` channel has an ordinal scale, the height is a product of the scale's [`bandSize`]((scale.html#ordinal)) and the field's cardinality, or number of possible distinct values of the field mapped to the `y` channel, plus the scale's padding. (_bandHeight * (yCardinality + yPadding)_). -- If `y` has a continuous scale (either quantitative or time), the height is drawn directly from the `height` property of the [cell configuration](config.html#cell-config). -- If `y` is not mapped to a field, the height is derived from [scale config](#scale-config)'s `bandSize`. + + +Note: If numeric `bandSize` for an ordinal x/y-scale is specified when `width` / `height` is specified, the `bandSize` will be overridden with `"fit"`. + +### Default Width and Height + +If the top-level `width` / `height` property is not specified, the width / height of a single plot or each cell of a trellis plot is determined by the properties of the `x` / `y` channel: + +- If `x` / `y` axis has a continuous scale (either quantitative or time), the width is drawn directly from the [`config.cell.width`](config.html#cell-config) / [`config.cell.height`](config.html#cell-config) property. + +- If the `x` / `y` channel has an ordinal scale with a numeric `bandSize` value (default), the width / height is a product of the scale's [`bandSize`]((scale.html#ordinal)) and the field's cardinality, or number of possible distinct values of the field mapped to the `x` / `y` channel, plus the scale's padding. (_bandWidth * (cardinality + padding)_). + + + +- If the `x` / `y` channel has an ordinal scale with `bandSize` = `"fit"`, the width / height is drawn directly from the [`config.cell.width`](config.html#cell-config) / [`config.cell.height`](config.html#cell-config) property and the band of the scale will be adjusted to fit to the width. + + + +- If `x` / `y` is not mapped to a field, the width / height is derived from [config.scale.bandSize](#scale-config) except when the mark is `text`. In that case, the width will be drawn from [config.scale.textBandWidth](#scale-config). + + ## Total Width and Height of a Trellis Plots The total width of the visualization is the product of the cell's width plus the `column` scale's `padding` and the cardinality of the `column` (_(cellWidth + columnPadding) * columnCardinality_). Similarly, the total height of the visualization is the product of the cell's height plus the `row` scale's `padding` and the cardinality of the `row` (_(cellHeight + rowPadding) * rowCardinality_). + + diff --git a/site/docs/spec.md b/site/docs/spec.md index 623f39119ee..3f56e4b993f 100644 --- a/site/docs/spec.md +++ b/site/docs/spec.md @@ -37,7 +37,9 @@ In Vega-Lite, a specification can have the following top-level properties. | Property | Type | Description | | :------------ |:-------------:| :------------- | -| description | String | An _optional_ description of this mark for commenting purpose. This property has no effect on the output visualization. | +| description | String | An _optional_ description of this mark for commenting purpose. This property has no effect on the output visualization. | +| [width](size.html) | Integer | Width of a single visualization. (For faceted plot, this represents the width of a single cell.) If not specified (`undefined`), this will be determined by the following rules:
• For x-axis with a continuous (non-ordinal) scale, the width will be the value of [`config.cell.width`](config.html#cell-config).
• For x-axis with an ordinal scale: if [`bandSize`](scale.html#ordinal) is a numeric value (default), the width is determined by the value of `bandSize` and the cardinality of the field mapped to x-channel. Otherwise, if the `bandSize` is `"fit"`, the width will be the value of [`config.cell.width`](config.html#cell-config).
• If no field is mapped to `x` channel, the `width` will be the value of `textBandWidth` for `text` mark and the value of `bandSize` for other marks. __Default value:__ `undefined` . | +| [height](size.html) | Integer | Height of a single visualization. (For faceted plot, this represents the height of a single cell.) If not specified (`undefined`), this will be determined by the following rules:
• For y-axis with a continuous (non-ordinal) scale, the height will be the value of [`config.cell.height`](config.html#cell-config).
• For y-axis with an ordinal scale: if [`bandSize`](scale.html#ordinal) is a numeric value (default), the height is determined by the value of `bandSize` and the cardinality of the field mapped to y-channel. Otherwise, if the `bandSize` is `"fit"`, the height will be the value of [`config.cell.height`](config.html#cell-config).
• If no field is mapped to `x` channel, the `height` will be the value of `bandSize`. __Default value:__ `undefined` . | | [data](data.html) | Object | An object describing the data source. | | [transform](transform.html) | Object | An object describing filter and new field calculation. | | [mark](mark.html) | String | The mark type. One of `"bar"`, `"circle"`, `"square"`, `"tick"`, `"line"`, `"area"`, `"point"`, and `"text"`. |