# Data Exploration Widgets

## Specification

Each widget is specified as an entry in the `widgets` array in `map-config.js`.

```javascript
const widgets = [
    {
        type: string,
        display: string,
        options: { ... },
        ...
    }
];
```

All widgets require the following fields:

| Key       | Type                                                | Description                                                                                  |
| --------- | --------------------------------------------------- | -------------------------------------------------------------------------------------------- |
| `type`    | One of: `histogram`, `scatter`, `scatter3d`, `line` | The basic type of widget.                                                                    |
| `display` | One of: `pinned`, `tray`, `hidden`                  | The starting position of the widget; widgets can be dragged by users.                        |
| `options` | Map                                                 | Additional options: see below. You must specify a value; to use default values, set to `{}`. |

## Widget Types

### Histograms

Create visualizations for single variables with histograms. Histograms are also interactive and can be used to filter what's highlighted on the map.

#### Configuration

```javascript
{
    type: "histogram",
    display: "pinned" | "tray" | "hidden",
    variable: string,
    options: {
        header: string,
        foregroundColor: color,
        xAxisLabel: string,
        yAxisLabel: string,
        thresholds: int
    }
}
```

| Key                       | Type     | Description                                                                                                     | Default   |
| ------------------------- | -------- | --------------------------------------------------------------------------------------------------------------- | --------- |
| `variable`                | string   | The name of the variable to display.                                                                            | Required  |
| `options.header`          | string   | The header/title of the widget.                                                                                 | null      |
| `options.foregroundColor` | hex code | The color of the bars.                                                                                          | `#000000` |
| `options.xAxisLabel`      | string   | The label of the x-axis.                                                                                        | null      |
| `options.yAxisLabel`      | string   | The label of the y-axis.                                                                                        | null      |
| `options.thresholds`      | int      | This option will be passed to D3's binning function; the number of bins is not guaranteed to match this number. | 40        |

### 2D Scatterplots

#### Configuration

```javascript
{
    type: "scatter",
    display: "pinned" | "tray" | "hidden",
    xVariable: string,
    yVariable: string,
    options: {
        header: string,
        foregroundColor: color,
        pointSize: number,
        xAxisLabel: string,
        yAxisLabel: string,
        showBestFitLine: bool,
        removeZeroValues: bool
    }
}
```

| Key                        | Type     | Description                                                                   | Default   |
| -------------------------- | -------- | ----------------------------------------------------------------------------- | --------- |
| `xVariable`                | string   | The name of the x-axis variable.                                              | Required  |
| `yVariable`                | string   | The name of the y-axis variable.                                              | Required  |
| `options.header`           | string   | The header/title of the widget.                                               | null      |
| `options.foregroundColor`  | hex code | The color of the points.                                                      | `#000000` |
| `options.pointSize`        | number   | The radius of the scatter points.                                             | 0.1       |
| `options.xAxisLabel`       | string   | The label of the x-axis.                                                      | null      |
| `options.yAxisLabel`       | string   | The label of the y-axis.                                                      | null      |
| `options.showBestFitLine`  | bool     | Set to true to calculate and display a best fit line using linear regression. | false     |
| `options.removeZeroValues` | bool     | Set to true to remove points with zero values.                                | false     |

#### LISA Scatterplots

LISA statistics can be generated and plotted in Scatterplot widgets. To plot spatial lag values, set your `yVariable` to `LISA`:

```javascript
{
    type: "scatter",
    yVariable: "LISA"
    // ...
}
```

Best fit lines are not supported for LISA scatterplots.

#### Clustering

Scatterplot widgets can calculate clusters using k-means clustering and display them as colors.

```javascript
{
    type: "scatter",
    options: {
        foregroundColor: "cluster",
        numClusters: int,
        clusterColors: color[]
        // ...
    }
    // ...
}
```

**Additional configuration options for cluster charts**

| Key                       | Type               | Description                                                                         | Default  |
| ------------------------- | ------------------ | ----------------------------------------------------------------------------------- | -------- |
| `options.foregroundColor` | string             | Should be set to `"cluster"`                                                        | Required |
| `options.numClusters`     | int                | The number of clusters to generate.                                                 | 2        |
| `options.clusterColors`   | array of hex codes | The colors to use for each cluster. Should be an array with length >= `numClusters` | Required |

### 3D Scatterplots

#### Configuration

```javascript
{
    type: "scatter3d",
    display: "pinned" | "tray" | "hidden",
    xVariable: string,
    yVariable: string,
    zVariable: string,
    options: {
        header: string,
        foregroundColor: color,
        pointSize: number,
        xAxisLabel: string,
        yAxisLabel: string,
        zAxisLabel: string,
        gridlinesInterval: [number, number, number]
    }
}
```

| Key                         | Type       | Description                                                                                                     | Default   |
| --------------------------- | ---------- | --------------------------------------------------------------------------------------------------------------- | --------- |
| `xVariable`                 | string     | The name of the x-axis variable.                                                                                | Required  |
| `yVariable`                 | string     | The name of the y-axis variable.                                                                                | Required  |
| `zVariable`                 | string     | The name of the z-axis variable.                                                                                | Required  |
| `options.header`            | string     | The header/title of the widget.                                                                                 | null      |
| `options.foregroundColor`   | hex code   | The color of the points.                                                                                        | `#000000` |
| `options.pointSize`         | number     | The radius of the scatter points.                                                                               | 0.5       |
| `options.xAxisLabel`        | string     | The label of the x-axis.                                                                                        | null      |
| `options.yAxisLabel`        | string     | The label of the y-axis.                                                                                        | null      |
| `options.zAxisLabel`        | string     | The label of the z-axis.                                                                                        | null      |
| `options.gridlinesInterval` | number\[3] | The intervals at which to draw gridlines and labels. Order: \[x, y, z]. If omitted, no gridlines will be shown. | null      |

### Line

Display one-dimensional variables over time as a 2D line chart.

#### Configuration

```javascript
{
    type: "line",
    display: "pinned" | "tray" | "hidden",
    variable: string,
    options: {
        header: string,
        foregroundColor: color,
        pointSize: number,
        xAxisLabel: string,
        yAxisLabel: string,
        showBestFitLine: bool,
        removeZeroValues: bool
    }
}
```

| Key                       | Type     | Description                                                                                              | Default      |
| ------------------------- | -------- | -------------------------------------------------------------------------------------------------------- | ------------ |
| `variable`                | string   | The name of the variable to display.                                                                     | Required7    |
| `options.header`          | string   | The header/title of the widget.                                                                          | null         |
| `options.foregroundColor` | hex code | The color of the line.                                                                                   | `#000000`    |
| `options.pointSize`       | number   | The radius of the points on the line.                                                                    | 1            |
| `options.xAxisLabel`      | string   | The label of the x-axis.                                                                                 | null         |
| `options.yAxisLabel`      | string   | The label of the y-axis.                                                                                 | null         |
| `options.dateFormat`      | string   | The format of the date labels. [Specification on Day.js docs](https://day.js.org/docs/en/display/format) | "YYYY-MM-DD" |