-
Notifications
You must be signed in to change notification settings - Fork 36
Configuration
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.
-
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
Required. The title of the chart
ex. Type of Violation
Optional. The description of the chart.
ex. Includes all public safety agencies
Currently, Socrata and Carto data sources work with VizWit. Additional data sources could be added by adding a provider.
The data provider from the hash in providers.js. Defaults to socrata for backwards compatibility.
ex. socrata or carto
Required. The domain/hostname of the data provider.
ex. data.phila.gov or phl.carto.com
Required. The 4x4 dataset ID.
ex. a8cx-la3p or crime_incidents
In most cases, aggregation can be achieved using only groupBy, but some cases require more advanced options.
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.
Optional. Defaults to count.
Optional. Defaults to *.
Optional. Allows complete override of what is selected as the value, which is normally done through aggregation.
ex. sum(votes) / sum(total) * 100
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.
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.
URL to the GeoJSON file containing the map boundaries
ex. https://data.phila.gov/resource/w4gp-aa3d.geojson
The property from each GeoJSON feature to be used as the polygon's label in the popup
ex. zip_code
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
The following options are only used in callout chart types
Numbro format string used on values
ex. 0,0
Moment format string used on labels
ex. YYYY
The following options can be used on any chart type
Optional. Order of the data query. You probably want to use label or value but don't have to.
ex. label desc
Optional. The number of results in the data query.
ex. 5
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"
}
}
]These only work with table chartTypes.
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"]