diff --git a/_includes/docs_toc.md b/_includes/docs_toc.md index 81c113f01a8..af0b9c69ade 100644 --- a/_includes/docs_toc.md +++ b/_includes/docs_toc.md @@ -6,6 +6,7 @@ - [Data]({{site.baseurl}}/docs/data.html) - [Inline Data]({{site.baseurl}}/docs/data.html#inline) - [Data from URL]({{site.baseurl}}/docs/data.html#url) + - [Format]({{site.baseurl}}/docs/data.html#format) - [Transform]({{site.baseurl}}/docs/transform.html) - [Top-level Transform Property]({{site.baseurl}}/docs/transform.html#top-level-transform-property) - [Mark]({{site.baseurl}}/docs/mark.html) @@ -25,6 +26,7 @@ - [Continuous Scale]({{site.baseurl}}/docs/sort.html#continuous-scale) - [Ordinal Scale]({{site.baseurl}}/docs/sort.html#ordinal-scale) - [Time Unit]({{site.baseurl}}/docs/timeunit.html) + - [Date/Time Units]({{site.baseurl}}/docs/timeunit.html#datetime-units) - [Scale]({{site.baseurl}}/docs/scale.html) - [Scale Type]({{site.baseurl}}/docs/scale.html#type) - [Scale Domain]({{site.baseurl}}/docs/scale.html#domain) @@ -37,11 +39,11 @@ - [Config]({{site.baseurl}}/docs/config.html) - [Top-level Configuration (config.*)]({{site.baseurl}}/docs/config.html#top-level-config) - [Cell Configuration (config.cell.*)]({{site.baseurl}}/docs/config.html#cell-config) - - [Mark Configuration (config.mark.*)]({{site.baseurl}}/docs/config.html#mark-configuration-) + - [Mark Configuration (config.mark.*)]({{site.baseurl}}/docs/config.html#mark-config) - [Scale Configuration (config.scale.*)]({{site.baseurl}}/docs/config.html#scale-config) - [Axis Configuration (config.axis.*)]({{site.baseurl}}/docs/config.html#axis-config) - [Legend Configuration (config.legend.*)]({{site.baseurl}}/docs/config.html#legend-config) - - [Facet Configuration (config.facet.*)]({{site.baseurl}}/docs/config.html#facet-configuration--) + - [Facet Configuration (config.facet.*)]({{site.baseurl}}/docs/config.html#facet-config) - [Customizing Size]({{site.baseurl}}/docs/size.html) - [Width and Height of a Single Plot]({{site.baseurl}}/docs/size.html#width-and-height-of-a-single-plot) - [Total Width and Height of a Trellis Plots]({{site.baseurl}}/docs/size.html#total-width-and-height-of-a-trellis-plots) diff --git a/examples/specs/bar_1d_bandsize_config.json b/examples/specs/bar_1d_bandsize_config.json new file mode 100644 index 00000000000..8b6cf789b6f --- /dev/null +++ b/examples/specs/bar_1d_bandsize_config.json @@ -0,0 +1,13 @@ +{ + "data": { "url": "data/population.json"}, + "transform": { + "filter": "datum.year == 2000" + }, + "mark": "bar", + "encoding": { + "x": { + "aggregate": "sum", "field": "people", "type": "quantitative", + "axis": {"title": "population"}} + }, + "config": {"scale": {"bandSize": 21}} +} diff --git a/examples/specs/bar_size_bandsize_small.json b/examples/specs/bar_size_bandsize_small.json new file mode 100644 index 00000000000..1fe2905050d --- /dev/null +++ b/examples/specs/bar_size_bandsize_small.json @@ -0,0 +1,18 @@ +{ + "description": "A simple bar chart with embedded data.", + "data": { + "values": [ + {"a": "A","b": 28}, {"a": "B","b": 55}, {"a": "C","b": 43}, + {"a": "D","b": 91}, {"a": "E","b": 81}, {"a": "F","b": 53}, + {"a": "G","b": 19}, {"a": "H","b": 87}, {"a": "I","b": 52} + ] + }, + "mark": "bar", + "encoding": { + "x": { + "field": "a", "type": "ordinal", + "scale": {"bandSize": 11} + }, + "y": {"field": "b", "type": "quantitative"} + } +} \ No newline at end of file diff --git a/examples/specs/bar_size_default.json b/examples/specs/bar_size_default.json new file mode 100644 index 00000000000..1ecb691dd71 --- /dev/null +++ b/examples/specs/bar_size_default.json @@ -0,0 +1,19 @@ +{ + "data": {"url": "data/cars.json"}, + "mark": "bar", + "encoding": { + "x": { + "field": "Origin", + "type": "nominal", + "scale": {"bandSize": 25} + }, + "y": { + "aggregate": "count", + "field": "*", + "type": "quantitative" + } + }, + "config": { + "cell": {"width": 200, "height": 200} + } +} 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_explicit_bad.json b/examples/specs/bar_size_explicit_bad.json new file mode 100644 index 00000000000..5226ffafe71 --- /dev/null +++ b/examples/specs/bar_size_explicit_bad.json @@ -0,0 +1,18 @@ +{ + "width": 120, + "height": 120, + "data": {"url": "data/cars.json"}, + "mark": "bar", + "encoding": { + "x": { + "field": "Name", + "type": "nominal", + "scale": {"round": false} + }, + "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..eaf11127601 --- /dev/null +++ b/examples/specs/bar_size_fit.json @@ -0,0 +1,19 @@ +{ + "data": {"url": "data/cars.json"}, + "mark": "bar", + "encoding": { + "x": { + "field": "Origin", + "type": "nominal", + "scale": {"bandSize": "fit"} + }, + "y": { + "aggregate": "count", + "field": "*", + "type": "quantitative" + } + }, + "config": { + "cell": {"width": 200, "height": 200} + } +} 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 d5dd25a3fef..6fce07bc233 100644 --- a/site/docs/scale.md +++ b/site/docs/scale.md @@ -218,8 +218,8 @@ 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`. | -| 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`. | +| 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__:
1) 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"`.
2) If the cardinality of the scale domain is too high, the bandSize might become less than one pixel and the mark might not appear correctly. | +| 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} #### Example: Custom Band Width @@ -230,23 +230,6 @@ Given a bar chart: We can make the band for each bar smaller by providing `scale`'s `bandSize`. -
-{ - "description": "A simple bar chart with embedded data.", - "data": { - "values": [ - {"a": "A","b": 28}, {"a": "B","b": 55}, {"a": "C","b": 43}, - {"a": "D","b": 91}, {"a": "E","b": 81}, {"a": "F","b": 53}, - {"a": "G","b": 19}, {"a": "H","b": 87}, {"a": "I","b": 52} - ] - }, - "mark": "bar", - "encoding": { - "x": { - "field": "a", "type": "ordinal", - "scale": {"bandSize": 11} - }, - "y": {"field": "b", "type": "quantitative"} - } -} -
+ + +For more information about adjusting size of a visualization, please see [this page](size.html). diff --git a/site/docs/size.md b/site/docs/size.md index 6f6cd99021c..c63ad266ef1 100644 --- a/site/docs/size.md +++ b/site/docs/size.md @@ -9,20 +9,44 @@ 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"`. + +**Warning**: If the cardinality of the x/y-field's domain is too high, the `bandSize` might become less than one pixel and the mark might not appear correctly. + + + +### 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)_). + +This example shows continuous y-scale and ordinal x-scale: + + + +- 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..217172c27da 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` .__Examples:__ Please see [Customizing Size](size.html) page. | +| [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` .__Examples:__ Please see [Customizing Size](size.html) page. | | [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"`. |