Configuration

Tim Wisniewski edited this page Apr 9, 2017 · 19 revisions

It's pretty difficult to balance functionality with simplicity, and the configuration options are probably the best indicator of where VizWit is at in that regard. The intention with the builder is to abstract this complexity with a wizard-like layout tool. But this page documents all the configuration options.

Most configuration options are used by all chart types. Some are only used by one.

Basic Information

chartType

  • bar: a bar chart
  • datetime: an area chart representing temporal categories
  • table: a sortable, pageable table
  • pie: a pie chart
  • choropleth: a map with polygon colors scaled based on a value
  • callout: a single value, typically a key metric

title

Required. The title of the chart

ex. Type of Violation

description

Optional. The description of the chart.

ex. Includes all public safety agencies

Data Source

Currently, Socrata and Carto data sources work with VizWit. Additional data sources could be added by adding a provider.

provider

The data provider from the hash in providers.js. Defaults to socrata for backwards compatibility.

ex. socrata or carto

domain

Required. The domain/hostname of the data provider.

ex. data.phila.gov or phl.carto.com

dataset

Required. The 4x4 dataset ID.

ex. a8cx-la3p or crime_incidents

Aggregation Options

In most cases, aggregation can be achieved using only groupBy, but some cases require more advanced options.

groupBy

Field to group by / pivot on.

ex. violation_type

Note: For date/time fields, grouping on a full timestamp wouldn't have much of an effect, so it's recommended to group by the month of the timestamp. In Socrata, you can do this via date_trunc_ym(field_name). In Carto, you can do this via date_trunc('month', field_name). If you do this, don't forget to set triggerField to the name of the field, without the function, so that it cross filters the other cards correctly.

aggregateFunction

Optional. Defaults to count.

aggregateField

Optional. Defaults to *.

valueField

Optional. Allows complete override of what is selected as the value, which is normally done through aggregation.

ex. sum(votes) / sum(total) * 100

triggerField

Optional. Defaults to value of groupBy. The field to filter other charts by when a user clicks this chart.

When you interact with a chart in VizWit, it filters the other charts based on the chart's groupBy field. But if you use a function in groupBy like date_trunc_ym(datetime), you want it to filter the other charts by datetime (without the function). triggerField allows you to specify this.

Choropleth Options

For datasets that represent points (such as crime incidents, where each record has a latitude and longitude), a choropleth card can show the density of the points within a set of boundaries on a map (such as zip code polygons). Each polygon's color is scaled based on the number of points that fall within it. For instance, when visualizing crime incident records, you may want a map of zip codes where the zip code polygons with more incidents are darker.

This card works by joining your dataset to a GeoJSON file of polygons. In the configuration, you'll specify the URL of the GeoJSON file, the field to join on (which should correspond to what you have in groupBy), and the field to use as each polygon's label.

For instance, if the crime incidents dataset has a field called zip_code with values like 19123, you would set groupBy to zip_code, then find a GeoJSON file that represents zip code boundaries (example). By inspecting the GeoJSON file, you can see there's a field called CODE that we'll join on by setting boundariesID to CODE. Since that field also works as a suitable label for the map's pop-up, we'll set boundariesLabel to CODE as well.

Note that your data must contain a column indicating which polygon it should join on for the choropleth card to work. Zip code is a common one, but something "council district" may be less prevalent.

The following options are only used in choropleth chart types.

boundaries

URL to the GeoJSON file containing the map boundaries ex. https://data.phila.gov/resource/w4gp-aa3d.geojson

boundariesLabel

The property from each GeoJSON feature to be used as the polygon's label in the popup

ex. zip_code

boundariesId

The property from each GeoJSON feature that represents the ID of the polygon. Used to join against the dataset using its groupBy value.

ex. _feature_id or district_number

Callout Options

The following options are only used in callout chart types

valueFormat

Numbro format string used on values

ex. 0,0

labelFormat

Moment format string used on labels

ex. YYYY

Overrides

The following options can be used on any chart type

order

Optional. Order of the data query. You probably want to use label or value but don't have to.

ex. label desc

limit

Optional. The number of results in the data query.

ex. 5

baseFilters

Optional. JSON array of base filters to always use on the data query. For example, if you wanted a visualization of parking tickets issued by police, you could set a base filter limiting the tickets data to those issued by police. [More info](Base Filters)

[
  {
    "field": "issuing_agency",
      "expression": {
        "type": "=",
        "value": "POLICE"
      }
  }
]

Table Display Options

These only work with table chartTypes.

columnsToHide

Optional. Hide columns in the data table by specifying their id (Socrata API field name) in an array named columnsToHide

ex: "columnsToHide":["id","x_coordinate","y_coordinate"]

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.