Skip to content

Template API Reference

Jump to bottom
Wenbo Tao edited this page Jan 4, 2021 · 36 revisions

Here we document the template APIs offered by Kyrix, which enable concise authoring of common visualizations (in typically a few 10s of lines of JSON).

Note that SSV APIs are more complicated, and thus are documented in a separate wiki.

US Choropleth Maps

By passing a JSON specification of a choropleth map into Project.addUSMap, you can add a US choropleth map into an encompassing Kyrix application, either as a new set of canvases, or a set of new layers of existing canvases.

Layers and Data Bindings

Project.addUSMap adds/creates new layers on an existing canvas, or a new canvas. For the state-level canvas, the new layers are:

  • Layer 0. A static legend layer with no data bindings.
  • Layer 1. The state-level aggregation layer, which consists of colored state boundaries. Each state is bound with four data fields: bbox_x, bbox_y (centroid of the state), name (name of the state) and rate (the statistics of interest).

For the county-level canvas, the new layers are:

  • Layer 0. A static legend layer with no data bindings.
  • Layer 1. The state boundary layer. Each state boundary is bound with four data fields bbox_x, bbox_y, bbox_w, bbox_h representing the bounding boxes of the state boundary.
  • Layer 2. The county-level aggregation layer, which consists of colored county boundaries. Each county is bound with six data fields: bbox_x, bbox_y, bbox_w, bbox_h (representing the bounding box of the county boundary), name (name of the county) and rate (the statistics of interest).

JSON Schema

We document how to specify a US choropleth map in JSON down below. The JSON schema is here. An example app can be found in this spec file.

  • db: defines the database in which data (states, counties, stats) is stored. There needs to be a database table in this database for each level (state or county). See state.table for more constraints on what this table should contain.

  • state: an object which defines the state-level choropleth map, required.

    • table: the name of the database table which stores state-level information, required. Specifically, this table should have 3 columns: name is the string name of a state (must be name); rate is the statistic variable of interest (e.g. crime rate, name can be something else, specified in state.column) and geomstr is the GeoJSON string of the boundary of a state. The data for the USMap example can be used to construct this table. If you load this SQL dump into Postgres, there will be a table called state which has the three columns needed for the US crime rate choropleth example. To show some other statistics of interest, you just need to join your data with the name column to produce another column of stats.

    • column: the column in state.table which corresponds to the statistics of interest, required.

    • range: a 2-number array which indicates the range of the statistics of interest, required.

    • step: a number indicating the step used for the choropleth. This is an optional field. If unspecified, Kyrix will use a step that evenly partitions state.range into state.colorCount buckets.

    • colorCount: an integer (2 to 8) indicating how many colors are desired. This is an optional field which defaults to 7. If state.step is unspecified, this color count is exact. Otherwise this will be an upper bound.

  • county: an object which defines the county-level choropleth map and has the same set of fields as state. This object is optional. If unspecified, there will only be state-level choropleth.

  • colorScheme: D3 color scheme used for the choropleth, which should be one of the values allowed here. This field is optional, and defaults to schemeYlOrRd.

  • projection: Geo projection for the map. Two projections are currently supported: geoAlbersUsa or geoMercator. This field is optional and defaults to geoAlbersUSA.

  • stateMapWidth: The width of the state map in # of pixels. Optional, defaults to 2,000.

  • stateMapHeight: The height of the state map in # of pixels. Optional, defaults to 1,000.

  • zoomFactor: The zoom factor between the state map and the county map. This field is optional and defaults to 6. When county does not exist, this field should not exist either.

  • zoomType: type of the zoom between the state map and the county map. Can be either literal, jump or none. none implies that the two levels are disconnected and that it is the developer's job to connect them up. This field is optional and defaults to literal. When county does not exist, this field should not exist either.

  • legendTitle: Title of the color legends, a string with 80 characters maximum. This field is optional and defaults to an empty string.

  • tooltipAlias: An alias (e.g. "Crime rate") for "Rate" in the tooltip popovers (shown when the user hovers over states or counties), 20 characters maximum. This field is optional and defaults to "Rate".

Static Aggregations

Static aggregations are a suite of templates which features 1) the underlying data is a SQL group by aggregation query and 2) the graphics are static (i.e. pan is not supported). Currently Kyrix offers five types of static aggregations: pie charts, bar charts, treemaps, circle packs and word clouds. See GIFs below.

By passing a JSON specification of a static aggregation into Project.addStaticAggregation, you can add a static aggregation into an encompassing Kyrix application, either as a canvas, or a set of new layers of an existing canvas.

Layers and Data Bindings

Project.addStaticAggregation creates two new layers on an existing canvas, or a new canvas. These two layers are respectively:

  • Layer 0. The aggregation layer, which consists of aggregation objects (e.g. treemap rectangle, bar, pie). Each object is bound with columns in query.dimensions, and a field called kyrixAggValue which is the numeric aggregation.
  • Layer 1. An invisible non-aggregation layer, which holds a sample subset of data items being aggregated. The columns present in these data items are from query.dimensions, query.stackDimensions, query.measure and query.sampleFields. This layer is normally used to show in a web application the underlying data being aggregated, using the web embedding APIs.

JSON Schema

We document how to specify a static aggregation in JSON down below. The JSON schema is here. An example app can be found in this spec file.

  • db: defines the database in which data is stored, required.

  • query: an object which defines how to fetch data from db, required. Basically, this object has information needed to form a SQL group-by query.

    • table: the name of the database table which stores the data for the static aggregation, required.
    • dimensions: an array of columns in query.table which will be present in the GROUP BY clause of the SQL query, required. Each unique value combination of the dimension columns will correspond to one object in the static aggregation (e.g. a treemap rectangle).
    • measure: a string representing the aggregation metric being calculated, required. This string should be in the form Func(col) where Func is one of the following: AVG, SUM, COUNT, MAX or MIN, and col is a column in query.table or *. The SQL group by query for the static aggregation can be formed with this field and query.dimensions (plus query.stackDimensions for stacked bar charts).
    • stackDimensions: an array of columns in query.table which specifies the dimension columns from which a stacked bar chart is stacked. Only allowed when type is bar. This field is optional and defaults to an empty array.
    • sampleFields: an array of column names in query.table which, together with all columns in query.dimensions, query.stackDimensions and query.measure, form the data for the invisible non-aggregation layer. The columns in query.dimensions, query.measure and query.sampleFields need to be disjoint. This field is optional and defaults to an empty array.

    Note that Kyrix only fetches a limited number of groups to the frontend for rendering. This is to avoid slow DB results and visual clutter.

  • type: type of the static aggregation. Can be one of the following values: pie, bar, treemap, circlePack or wordCloud.

  • tooltip: an object which defines what to show as tooltip when the user hovers over an object (e.g. a treemap rectangle). This field is optional. By default the tooltips show all columns in query.dimensions (plus query.stackDimensions for stacked bar charts) and the aggregation metric calculated by query.measure.

  • colorScheme: D3 color scheme used for the static aggregation. When type is pie, bar or wordCloud, the color scheme should be one of the categorical schemes allowed here. When type is treemap or circlePack, the color scheme should be one of the interpolated schemes allowed here. This field is optional. When type is pie, bar or wordCloud, this field defaults to schemeTableau10. When type is treemap or circlePack, this field defaults to interpolateGnBu. Note that when type is pie, the color count in the scheme imposes a limit on the number of pies. If the query produces more categories than the number of colors available in the color scheme, only the categories with the largest aggregation metrics will be shown. When type is bar, this scheme does not take effect if query.stackDimensions is empty or not present (i.e. when the bar chart is not stacked). In non-stacked barcharts, the color of the bars defaults to #80b1d3.

  • transition: a boolean indicating whether transitions are desired. This field is optional and defaults to true.

  • legend: an object which defines the legend for the static aggregation.

    • title: a string which represents the title of the legend. 80 characters maximum. This field is optional and defaults to an empty string.
    • domain: a JS object which maps raw category values to desired aliases. Only allowed for pies and stacked bar charts. This field is optional and defaults to an empty JS map. Note that if there are multiple columns present in one category, the raw category values should be specified as values from those columns joined using the underscore. Also note that for pie charts, categories are determined by query.dimensions where as for stacked bar charts, categories are determined by query.stackDimensions.

  • width: a number between 600 and 1,500 which represents the width of the static aggregation. This field is optional and defaults to 1,000.

  • height: a number between 600 and 1,500 which represents the height of the static aggregation. This field is optional and defaults to 1,000.

  • textFields: An array of columns representing the fields in the data to show in objects (e.g. treemap rectangles, texts for word clouds). Only allowed when type is treemap, circlePack or wordCloud. This field is optional and defaults to an empty array, which indicates that no text will be shown. The columns specified must be dimension fields.

  • padding: a number between 0 and 15 (pixels) representing the amount of padding between objects (e.g. treemap rectangles). Only allowed when type is treemap, circlePack or wordCloud. This field is optional and defaults to 3.

  • radius: a number between 100 and 400 representing the outer radius of the pie chart. Only allowed when type is pie. This field is optional and defaults to 300.

  • axis: an object defining the axes. Only allowed when type is bar.

    • xTitle: a string to show as the title of the x axis.
    • yTitle: a string to show as the title of the y axis.

  • cloud: an object for customizing word clouds. Only allowed when type is wordCloud.

    • fontFamily: the font family of the words. Defaults to Impact.
    • rotation: an array of angles (in degrees) from which the orientation of the words will be randomly drawn. Defaults to an array with only 0, i.e., all words are horizontal.
    • maxTextLength: maximum length of the words. Defaults to 15 characters. If a word is larger than this length, only a prefix with `maxTextLength characters plus an ellipsis are shown.
    • minTextSize: minimum font size of the words. Defaults to 15 pixels.
    • maxTextSize: maximum font size of the words. Defaults to 60 pixels.
Clone this wiki locally