ScatterChartBuilder

Builder for scatter charts. For more details, see the [Google Charts documentation](https://developers.google.com/chart/interactive/docs/gallery/scatterchart).

Here is an example that shows how to build a scatter chart. The data is [imported from a Google spreadsheet](https://developers.google.com/chart/interactive/docs/spreadsheets#Google_Spreadsheets_as_a_Data_Source).

```javascript
// Get sample data from a spreadsheet.
const dataSourceUrl = 'https://docs.google.com/spreadsheet/tq?range=C1%3AD' +
    '&key=0Aq4s9w_HxMs7dHpfX05JdmVSb1FpT21sbXd4NVE3UEE&gid=4&headers=-1';

const chartBuilder = Charts.newScatterChart()
                         .setTitle('Adjusted GDP & U.S. Population')
                         .setXAxisTitle('U.S. Population (millions)')
                         .setYAxisTitle('Adjusted GDP ($ billions)')
                         .setDimensions(600, 500)
                         .setLegendPosition(Charts.Position.NONE)
                         .setDataSourceUrl(dataSourceUrl);

const chart = chartBuilder.build();
```

### Methods

| Method | Return type | Brief description |
|---|---|---|
| `https://developers.google.com/apps-script/reference/charts/scatter-chart-builder#build()` | `https://developers.google.com/apps-script/reference/charts/chart` | Builds the chart. |
| `https://developers.google.com/apps-script/reference/charts/scatter-chart-builder#setBackgroundColor(String)` | `https://developers.google.com/apps-script/reference/charts/scatter-chart-builder#` | Sets the background color for the chart. |
| `https://developers.google.com/apps-script/reference/charts/scatter-chart-builder#setColors(String)` | `https://developers.google.com/apps-script/reference/charts/scatter-chart-builder#` | Sets the colors for the lines in the chart. |
| `https://developers.google.com/apps-script/reference/charts/scatter-chart-builder#setDataSourceUrl(String)` | `https://developers.google.com/apps-script/reference/charts/scatter-chart-builder#` | Sets the data source URL that is used to pull data in from an external source, such as Google Sheets. |
| `https://developers.google.com/apps-script/reference/charts/scatter-chart-builder#setDataTable(DataTableBuilder)` | `https://developers.google.com/apps-script/reference/charts/scatter-chart-builder#` | Sets the data table to use for the chart using a DataTableBuilder. |
| `https://developers.google.com/apps-script/reference/charts/scatter-chart-builder#setDataTable(DataTableSource)` | `https://developers.google.com/apps-script/reference/charts/scatter-chart-builder#` | Sets the data table which contains the lines for the chart, as well as the X-axis labels. |
| `https://developers.google.com/apps-script/reference/charts/scatter-chart-builder#setDataViewDefinition(DataViewDefinition)` | `https://developers.google.com/apps-script/reference/charts/scatter-chart-builder#` | Sets the data view definition to use for the chart. |
| `https://developers.google.com/apps-script/reference/charts/scatter-chart-builder#setDimensions(Integer,Integer)` | `https://developers.google.com/apps-script/reference/charts/scatter-chart-builder#` | Sets the dimensions for the chart. |
| `https://developers.google.com/apps-script/reference/charts/scatter-chart-builder#setLegendPosition(Position)` | `https://developers.google.com/apps-script/reference/charts/scatter-chart-builder#` | Sets the position of the legend with respect to the chart. |
| `https://developers.google.com/apps-script/reference/charts/scatter-chart-builder#setLegendTextStyle(TextStyle)` | `https://developers.google.com/apps-script/reference/charts/scatter-chart-builder#` | Sets the text style of the chart legend. |
| `https://developers.google.com/apps-script/reference/charts/scatter-chart-builder#setOption(String,Object)` | `https://developers.google.com/apps-script/reference/charts/scatter-chart-builder#` | Sets advanced options for this chart. |
| `https://developers.google.com/apps-script/reference/charts/scatter-chart-builder#setPointStyle(PointStyle)` | `https://developers.google.com/apps-script/reference/charts/scatter-chart-builder#` | Sets the style for points in the line. |
| `https://developers.google.com/apps-script/reference/charts/scatter-chart-builder#setTitle(String)` | `https://developers.google.com/apps-script/reference/charts/scatter-chart-builder#` | Sets the title of the chart. |
| `https://developers.google.com/apps-script/reference/charts/scatter-chart-builder#setTitleTextStyle(TextStyle)` | `https://developers.google.com/apps-script/reference/charts/scatter-chart-builder#` | Sets the text style of the chart title. |
| `https://developers.google.com/apps-script/reference/charts/scatter-chart-builder#setXAxisLogScale()` | `https://developers.google.com/apps-script/reference/charts/scatter-chart-builder#` | Makes the horizontal axis into a logarithmic scale (requires all values to be positive). |
| `https://developers.google.com/apps-script/reference/charts/scatter-chart-builder#setXAxisRange(Number,Number)` | `https://developers.google.com/apps-script/reference/charts/scatter-chart-builder#` | Sets the range for the horizontal axis of the chart. |
| `https://developers.google.com/apps-script/reference/charts/scatter-chart-builder#setXAxisTextStyle(TextStyle)` | `https://developers.google.com/apps-script/reference/charts/scatter-chart-builder#` | Sets the horizontal axis text style. |
| `https://developers.google.com/apps-script/reference/charts/scatter-chart-builder#setXAxisTitle(String)` | `https://developers.google.com/apps-script/reference/charts/scatter-chart-builder#` | Adds a title to the horizontal axis. |
| `https://developers.google.com/apps-script/reference/charts/scatter-chart-builder#setXAxisTitleTextStyle(TextStyle)` | `https://developers.google.com/apps-script/reference/charts/scatter-chart-builder#` | Sets the horizontal axis title text style. |
| `https://developers.google.com/apps-script/reference/charts/scatter-chart-builder#setYAxisLogScale()` | `https://developers.google.com/apps-script/reference/charts/scatter-chart-builder#` | Makes the vertical axis into a logarithmic scale (requires all values to be positive). |
| `https://developers.google.com/apps-script/reference/charts/scatter-chart-builder#setYAxisRange(Number,Number)` | `https://developers.google.com/apps-script/reference/charts/scatter-chart-builder#` | Sets the range for the vertical axis of the chart. |
| `https://developers.google.com/apps-script/reference/charts/scatter-chart-builder#setYAxisTextStyle(TextStyle)` | `https://developers.google.com/apps-script/reference/charts/scatter-chart-builder#` | Sets the vertical axis text style. |
| `https://developers.google.com/apps-script/reference/charts/scatter-chart-builder#setYAxisTitle(String)` | `https://developers.google.com/apps-script/reference/charts/scatter-chart-builder#` | Adds a title to the vertical axis. |
| `https://developers.google.com/apps-script/reference/charts/scatter-chart-builder#setYAxisTitleTextStyle(TextStyle)` | `https://developers.google.com/apps-script/reference/charts/scatter-chart-builder#` | Sets the vertical axis title text style. |

## Detailed documentation

### `build()`

Builds the chart.

#### Return


`https://developers.google.com/apps-script/reference/charts/chart` --- A Chart object, which can be embedded into documents, UI elements, or used as a static
image.

*** ** * ** ***

### `setBackgroundColor(cssValue)`

Sets the background color for the chart.

```javascript
// Creates a line chart builder and sets the background color to gray
const builder = Charts.newLineChart();
builder.setBackgroundColor('gray');
```

#### Parameters

| Name | Type | Description |
|---|---|---|
| `cssValue` | `String` | The CSS value for the color (such as `"blue"` or `"#00f"`). |

#### Return


`https://developers.google.com/apps-script/reference/charts/scatter-chart-builder#` --- This builder, useful for chaining.

*** ** * ** ***

### `setColors(cssValues)`

Sets the colors for the lines in the chart.

```javascript
// Creates a line chart builder and sets the first two lines to be drawn in
// green and red, respectively.
const builder = Charts.newLineChart();
builder.setColors(['green', 'red']);
```

#### Parameters

| Name | Type | Description |
|---|---|---|
| `cssValues` | `String[]` | An array of color CSS values, such as `["red", "#acf"]`. The nth element in the array represents the color of the nth line in the chart. |

#### Return


`https://developers.google.com/apps-script/reference/charts/scatter-chart-builder#` --- This builder, useful for chaining.

*** ** * ** ***

### `setDataSourceUrl(url)`

Sets the data source URL that is used to pull data in from an external source, such as Google
Sheets. If a data source URL and a DataTable are provided, the data source URL is ignored.

For more information about querying data sources, check out the [Google Charts documentation](https://developers.google.com/chart/interactive/docs/queries).

#### Parameters

| Name | Type | Description |
|---|---|---|
| `url` | `String` | The data source URL, including any query parameters. |

#### Return


`https://developers.google.com/apps-script/reference/charts/scatter-chart-builder#` --- This builder, useful for chaining.

*** ** * ** ***

### `setDataTable(tableBuilder)`

Sets the data table to use for the chart using a DataTableBuilder. This is a convenience method
for setting the data table without needing to call `build()`.

#### Parameters

| Name | Type | Description |
|---|---|---|
| `tableBuilder` | `https://developers.google.com/apps-script/reference/charts/data-table-builder` | A data table builder. A new data table is created instantly as part of this call, so any further updates to the builder won't be reflected in the chart. |

#### Return


`https://developers.google.com/apps-script/reference/charts/scatter-chart-builder#` --- This builder, useful for chaining.

*** ** * ** ***

### `setDataTable(table)`

Sets the data table which contains the lines for the chart, as well as the X-axis labels. The
first column should be a string, and contain the horizontal axis labels. Any number of columns
can follow, all must be numeric. Each column is displayed as a separate line.

#### Parameters

| Name | Type | Description |
|---|---|---|
| `table` | `https://developers.google.com/apps-script/reference/charts/data-table-source` | The data table to use for the chart. |

#### Return


`https://developers.google.com/apps-script/reference/charts/scatter-chart-builder#` --- This builder, useful for chaining.

*** ** * ** ***

### `setDataViewDefinition(dataViewDefinition)`

Sets the data view definition to use for the chart.

#### Parameters

| Name | Type | Description |
|---|---|---|
| `dataViewDefinition` | `https://developers.google.com/apps-script/reference/charts/data-view-definition` | A data view definition object that defines the view that should be derived from the given data source for the chart drawing. |

#### Return


`https://developers.google.com/apps-script/reference/charts/scatter-chart-builder#` --- This builder, useful for chaining.

*** ** * ** ***

### `setDimensions(width, height)`

Sets the dimensions for the chart.

#### Parameters

| Name | Type | Description |
|---|---|---|
| `width` | `Integer` | The width of the chart, in pixels. |
| `height` | `Integer` | The height of the chart, in pixels. |

#### Return


`https://developers.google.com/apps-script/reference/charts/scatter-chart-builder#` --- This builder, useful for chaining.

*** ** * ** ***

### `setLegendPosition(position)`

Sets the position of the legend with respect to the chart. By default, there is no legend.

```javascript
// Creates a line chart builder and sets the legend position to right.
const builder = Charts.newLineChart();
builder.setLegendPosition(Charts.Position.RIGHT);
```

#### Parameters

| Name | Type | Description |
|---|---|---|
| `position` | `https://developers.google.com/apps-script/reference/charts/position` | The position of the legend. |

#### Return


`https://developers.google.com/apps-script/reference/charts/scatter-chart-builder#` --- This builder, useful for chaining.

*** ** * ** ***

### `setLegendTextStyle(textStyle)`

Sets the text style of the chart legend.

```javascript
// Creates a line chart builder and sets it up for a  blue, 26-point legend.
const textStyleBuilder =
    Charts.newTextStyle().setColor('#0000FF').setFontSize(26);
const style = textStyleBuilder.build();
const builder = Charts.newLineChart();
builder.setLegendTextStyle(style);
```

#### Parameters

| Name | Type | Description |
|---|---|---|
| `textStyle` | `https://developers.google.com/apps-script/reference/charts/text-style` | The text style to use for the chart legend. |

#### Return


`https://developers.google.com/apps-script/reference/charts/scatter-chart-builder#` --- This builder, useful for chaining.

*** ** * ** ***

### `setOption(option, value)`

Sets advanced options for this chart. See [the available options for
this chart](https://developers.google.com/chart/interactive/docs/gallery/scatterchart). This method has no effect if the given option is invalid.

```javascript
// Build a scatter chart with a 1-second animation duration.
const builder = Charts.newScatterChart();
builder.setOption('animation.duration', 1000);
const chart = builder.build();
```

#### Parameters

| Name | Type | Description |
|---|---|---|
| `option` | `String` | The option to set. |
| `value` | `Object` | The value to set. |

#### Return


`https://developers.google.com/apps-script/reference/charts/scatter-chart-builder#` --- This builder, useful for chaining.

*** ** * ** ***

### `setPointStyle(style)`

Sets the style for points in the line. By default, points have no particular styles, and only
the line is visible.

```javascript
// Creates a line chart builder and sets large point style.
const builder = Charts.newLineChart();
builder.setPointStyle(Charts.PointStyle.LARGE);
```

#### Parameters

| Name | Type | Description |
|---|---|---|
| `style` | `https://developers.google.com/apps-script/reference/charts/point-style` | The style to use for points in the line. |

#### Return


`https://developers.google.com/apps-script/reference/charts/scatter-chart-builder#` --- This builder, useful for chaining.

#### See also

- `https://developers.google.com/apps-script/reference/charts/point-style`

*** ** * ** ***

### `setTitle(chartTitle)`

Sets the title of the chart. The title is displayed centered above the chart.

```javascript
// Creates a line chart builder and title to 'My Line Chart'.
const builder = Charts.newLineChart();
builder.setTitle('My Line Chart');
```

#### Parameters

| Name | Type | Description |
|---|---|---|
| `chartTitle` | `String` | the chart title. |

#### Return


`https://developers.google.com/apps-script/reference/charts/scatter-chart-builder#` --- This builder, useful for chaining.

*** ** * ** ***

### `setTitleTextStyle(textStyle)`

Sets the text style of the chart title.

```javascript
// Creates a line chart builder and sets it up for a  blue, 26-point title.
const textStyleBuilder =
    Charts.newTextStyle().setColor('#0000FF').setFontSize(26);
const style = textStyleBuilder.build();
const builder = Charts.newLineChart();
builder.setTitleTextStyle(style);
```

#### Parameters

| Name | Type | Description |
|---|---|---|
| `textStyle` | `https://developers.google.com/apps-script/reference/charts/text-style` | The text style to use for the chart title. You can create a `https://developers.google.com/apps-script/reference/charts/text-style-builder` object by calling `https://developers.google.com/apps-script/reference/charts/charts#newTextStyle()`. |

#### Return


`https://developers.google.com/apps-script/reference/charts/scatter-chart-builder#` --- This builder, useful for chaining.

*** ** * ** ***

### `setXAxisLogScale()`

Makes the horizontal axis into a logarithmic scale (requires all values to be positive).

#### Return


`https://developers.google.com/apps-script/reference/charts/scatter-chart-builder#` --- This builder, useful for chaining.

*** ** * ** ***

### `setXAxisRange(start, end)`

Sets the range for the horizontal axis of the chart.

If any data points fall outside the range, the range is expanded to include those data
points.

```javascript
// Creates a scatter chart builder and sets the X-axis range to be 0 to 100.
const builder = Charts.newTableChart();
builder.setXAxisRange(0, 100);
```

#### Parameters

| Name | Type | Description |
|---|---|---|
| `start` | `Number` | The value for the lowest grid line of the horizontal axis. |
| `end` | `Number` | The value for the highest grid line of the horizontal axis. |

#### Return


`https://developers.google.com/apps-script/reference/charts/scatter-chart-builder#` --- This builder, useful for chaining.

*** ** * ** ***

### `setXAxisTextStyle(textStyle)`

Sets the horizontal axis text style.

```javascript
// Creates a line chart builder and sets the X-axis text style to blue, 18-point
// font.
const textStyle =
    Charts.newTextStyle().setColor('blue').setFontSize(18).build();
const builder = Charts.newLineChart();
builder.setXAxisTextStyle(textStyle);
```

#### Parameters

| Name | Type | Description |
|---|---|---|
| `textStyle` | `https://developers.google.com/apps-script/reference/charts/text-style` | The text style to use for the horizontal axis title. You can create a `https://developers.google.com/apps-script/reference/charts/text-style-builder` object by calling `https://developers.google.com/apps-script/reference/charts/charts#newTextStyle()`. |

#### Return


`https://developers.google.com/apps-script/reference/charts/scatter-chart-builder#` --- This builder, useful for chaining.

*** ** * ** ***

### `setXAxisTitle(title)`

Adds a title to the horizontal axis. The title is centered and appears below the axis value
labels.

```javascript
// Creates a line chart builder and sets the X-axis title.
const builder = Charts.newLineChart();
builder.setTitle('X-axis Title');
```

#### Parameters

| Name | Type | Description |
|---|---|---|
| `title` | `String` | The title for the X-axis. |

#### Return


`https://developers.google.com/apps-script/reference/charts/scatter-chart-builder#` --- This builder, useful for chaining.

*** ** * ** ***

### `setXAxisTitleTextStyle(textStyle)`

Sets the horizontal axis title text style.

```javascript
// Creates a line chart builder and sets the X-axis title text style to blue,
// 18-point font.
const textStyle =
    Charts.newTextStyle().setColor('blue').setFontSize(18).build();
const builder = Charts.newLineChart();
builder.setXAxisTitleTextStyle(textStyle);
```

#### Parameters

| Name | Type | Description |
|---|---|---|
| `textStyle` | `https://developers.google.com/apps-script/reference/charts/text-style` | The text style to use for the horizontal axis title. You can create a `https://developers.google.com/apps-script/reference/charts/text-style-builder` object by calling `https://developers.google.com/apps-script/reference/charts/charts#newTextStyle()`. |

#### Return


`https://developers.google.com/apps-script/reference/charts/scatter-chart-builder#` --- This builder, useful for chaining.

*** ** * ** ***

### `setYAxisLogScale()`

Makes the vertical axis into a logarithmic scale (requires all values to be positive).

#### Return


`https://developers.google.com/apps-script/reference/charts/scatter-chart-builder#` --- This builder, useful for chaining.

*** ** * ** ***

### `setYAxisRange(start, end)`

Sets the range for the vertical axis of the chart. If any data points fall outside the range,
the range is expanded to include those data points.

```javascript
// Creates a scatter chart builder and sets the Y-axis range to be 0 to 100.
const builder = Charts.newTableChart();
builder.setYAxisRange(0, 100);
```

#### Parameters

| Name | Type | Description |
|---|---|---|
| `start` | `Number` | The value for the lowest grid line of the vertical axis. |
| `end` | `Number` | The value for the highest grid line of the vertical axis. |

#### Return


`https://developers.google.com/apps-script/reference/charts/scatter-chart-builder#` --- This builder, useful for chaining.

*** ** * ** ***

### `setYAxisTextStyle(textStyle)`

Sets the vertical axis text style.

```javascript
// Creates a line chart builder and sets the Y-axis text style to blue, 18-point
// font.
const textStyle =
    Charts.newTextStyle().setColor('blue').setFontSize(18).build();
const builder = Charts.newLineChart();
builder.setYAxisTextStyle(textStyle);
```

#### Parameters

| Name | Type | Description |
|---|---|---|
| `textStyle` | `https://developers.google.com/apps-script/reference/charts/text-style` | The text style to use for the horizontal axis title. You can create a `https://developers.google.com/apps-script/reference/charts/text-style-builder` object by calling `https://developers.google.com/apps-script/reference/charts/charts#newTextStyle()`. |

#### Return


`https://developers.google.com/apps-script/reference/charts/scatter-chart-builder#` --- This builder, useful for chaining.

*** ** * ** ***

### `setYAxisTitle(title)`

Adds a title to the vertical axis. The title is centered and appears to the left of the value
labels.

```javascript
// Creates a line chart builder and sets the Y-axis title.
const builder = Charts.newLineChart();
builder.setYAxisTitle('Y-axis Title');
```

#### Parameters

| Name | Type | Description |
|---|---|---|
| `title` | `String` | The title for the Y-axis. |

#### Return


`https://developers.google.com/apps-script/reference/charts/scatter-chart-builder#` --- This builder, useful for chaining.

*** ** * ** ***

### `setYAxisTitleTextStyle(textStyle)`

Sets the vertical axis title text style.

```javascript
// Creates a line chart builder and sets the Y-axis title text style to blue,
// 18-point font.
const textStyle =
    Charts.newTextStyle().setColor('blue').setFontSize(18).build();
const builder = Charts.newLineChart();
builder.setYAxisTitleTextStyle(textStyle);
```

#### Parameters

| Name | Type | Description |
|---|---|---|
| `textStyle` | `https://developers.google.com/apps-script/reference/charts/text-style` | The text style to use for the horizontal axis title. You can create a `https://developers.google.com/apps-script/reference/charts/text-style-builder` object by calling `https://developers.google.com/apps-script/reference/charts/charts#newTextStyle()`. |

#### Return


`https://developers.google.com/apps-script/reference/charts/scatter-chart-builder#` --- This builder, useful for chaining.