Skip to content

Commit

Permalink
Small wording updates from review
Browse files Browse the repository at this point in the history
  • Loading branch information
@r-ash
r-ash committed Dec 19, 2024
1 parent 414b9ab commit 0987a37
Showing 1 changed file with 17 additions and 17 deletions.
34 changes: 17 additions & 17 deletions vignettes/metadata.Rmd
View file
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ knitr::opts_chunk$set(

## Motivation

Historically Hint had different components for their plots each with their own logic on how to handle different filter selections. For example:
Historically HINT had different components for its plots each with its own logic on how to handle different filter selections. For example:

### Choropleth
![Choropleth state 1](images/choropleth-1.png)
Expand All @@ -29,7 +29,7 @@ Historically Hint had different components for their plots each with their own l
![Table state 1](images/table-1.png)
![Table state 2](images/table-2.png)

There are lots of differences between these but the main relevant differences are:
There are lots of differences between these filters but the main relevant differences are:

* Some filters are single selects and some are multi-selects
* The barchart's `X Axis` and `Disaggregate by` filters turn whatever is selected into a multi-select dropdown while keeping the rest single selects
Expand All @@ -39,20 +39,20 @@ The aim is to unify these differences into one framework that can support all th

## Implementation overview

The structure we settled on is the backend (this repository) sending the frontend json response that tells it how to construct the UI and also how to dynamically update it based on the value of the dropdowns.
The backend (this repository) provides metadata JSON endpoints that tell the frontend how to construct the UI and also how to dynamically update it based on the value of the dropdowns.

Note: For each tab there is a different response that specifies the metadata:
Note: For each tab in the frontend UI there is a different endpoint and associated JSON schema that specifies the metadata:

* [`Review output`](../inst/schema/CalibrateMetadataResponse.schema.json)
* [`Calibrate model`](../inst/schema/CalibratePlotMetadata.schema.json)
* [`Review inputs`](../inst/schema/ReviewInputFilterMetadataResponse.schema.json)

The structure of these are the same bar the keys to the `plotSettingsControl` which identifies the plot. In the bullet points above there are two main types of dropdowns that we want:
The structures of these are the same bar the keys to the `plotSettingsControl` which identifies the plot. In the bullet points above there are two main types of dropdowns that we want:

1. Dropdowns that influence other dropdowns - we will call these `controls` and call their values `settings`
1. Dropdowns that acts as filters for slicing the data - we will call these `filters` and their values `selections`

A useful visualisation that I'll keep referring to so that we don't get lost in the json nestings is (note that `indicators` is not expanded as this just contains metadata about the indicator values such as their format which isn't relevant to the metadata structure):
Here is a useful visualisation of the schema that I'll keep referring to so that we don't get lost in the JSON nesting (note that `indicators` is not expanded as this just contains metadata about the indicator values such as their format which isn't relevant to the metadata structure):

```php
├── filterTypes[]
Expand All @@ -71,7 +71,7 @@ A useful visualisation that I'll keep referring to so that we don't get lost in
│ ├── plotSettings[]
│ │ ├── label
│ │ ├── id
│ │ ├── visible
│ │ ├── hidden
│ │ ├── value
│ │ ├── options[]
│ │ │ │ ├── id
Expand Down Expand Up @@ -103,7 +103,7 @@ This is just a full version of the json schema.
│ ├── plotSettings[]
│ │ ├── label
│ │ ├── id
│ │ ├── visible
│ │ ├── hidden
│ │ ├── value
│ │ ├── options[]
│ │ │ │ ├── id
Expand All @@ -117,9 +117,9 @@ This is just a full version of the json schema.
The `filterTypes` key is the simplest. It is an array of all the filters that can be displayed in the UI with their options. Explanations for each number in the visualisation:

1. The `id` is just an id we can assign to the filter to refer to it later
1. The `column_id` this is the column name of the data which we have to filter
1. The `column_id` this is the column id of the data which we have to filter
1. `use_shape_regions` is a boolean that should largely be ignored, it is a one off trick to reduce the amount of payload we send to the frontend by telling it to derive the options of a filter select with this boolean from the shape file that the user has uploaded
1. The `options` are the options visible to the user in the dropdown, with an `id` for the store, the `label` for what to display in the dropdown menu and an optional `description` prop for contextual information (this doesn't get displayed to the user at all)
1. The `options` are the options visible to the user in the dropdown. Each option has an `id` by which filter selections can refer to the option, a `label` to display in the dropdown menu and an optional `description` prop for contextual information (this doesn't get displayed to the user at all)

## Plot Settings Control

Expand All @@ -140,7 +140,7 @@ The `filterTypes` key is the simplest. It is an array of all the filters that ca
│ ├── plotSettings[] # 2
│ │ ├── label # 3
│ │ ├── id # 4
│ │ ├── visible # 5
│ │ ├── hidden # 5
│ │ ├── value # 6
│ │ ├── options[]
│ │ │ │ ├── id # a
Expand All @@ -158,7 +158,7 @@ The plot settings controls is an object with keys of the relevant plot name (e.g
1. `plotSettings` is an array of all the `controls` a tab will have
1. `label` is the title of the dropdown the user will see in the UI
1. `id` is the id of the plot settings (this id is how the store keeps track of which `setting` of the `control` is selected)
1. `visible` boolean - there are times we want the `control` to be invisible. The calibrate plot reuses the barchart component however they expect an `X Axis` and `Disaggregate by` control - these controls are fixed in the calibrate plot so we set them to a constant value and hide them from the user allowing us to reuse the barchart component without any special code
1. `hidden` boolean - there are times we want the `control` to be invisible. The calibrate plot reuses the barchart component, however they expect an `X Axis` and `Disaggregate by` control - these controls are fixed in the calibrate plot so we set them to a constant value and hide them from the user allowing us to reuse the barchart component without any special code
1. `value` is an optional key to set the default value of the `control` as something other than the default (default in frontend for single select is the first value and for a multi-select is all the values). This is the `id` of the option (`a` in the visualisation)

## Settings
Expand All @@ -180,7 +180,7 @@ The plot settings controls is an object with keys of the relevant plot name (e.g
│ ├── plotSettings[]
│ │ ├── label
│ │ ├── id
│ │ ├── visible
│ │ ├── hidden
│ │ ├── value
│ │ ├── options[] # here
│ │ │ │ ├── id # 1
Expand Down Expand Up @@ -217,7 +217,7 @@ The `settings` completely determine the `filters` and their `selections`. The ne
│ ├── plotSettings[]
│ │ ├── label
│ │ ├── id
│ │ ├── visible
│ │ ├── hidden
│ │ ├── value
│ │ ├── options[]
│ │ │ │ ├── id
Expand All @@ -243,11 +243,11 @@ For this section we will need a more detailed view of the effects structure

Explanation of each effect and how the frontend aggregates this:

1. `setFilters` is how the effect specifies what `filters` the user sees from the `filterTypes` The frontend aggregates this by replacing it. So if two `settings` set filters, the last `setFilters` in the for loop would be used when going through all the `settings`. Keys:
1. `setFilters` is how the effect specifies what `filters` the user sees from the `filterTypes`. Only one `setFilters` effect is used, they are not combined. So if two `settings` set filters, the last `setFilters` in the for loop would be used when going through all the `settings`. Keys:
1. `filterId` is the `id` key in a `filterTypes`element (`a` in the visualisation)
1. `label` is the title of the `filter` displayed to the user in the UI
1. `stateFilterId` is the id the state uses to identify this filter. This is distinct to the `filterId` because in the bubble plot we have two indicators filters that are the same filter type (so have the same `options` and the same `column_id`) however they are distinct because one controls the color of the bubbles and one controls the size of the bubbles so while both their `filterId`s are `indicator`, the `stateFilterId`s for both are different, `colorIndicator` and `sizeIndicator`. For most cases this can be set as the same thing as the `filterId`. All other effects will now identify filters by `stateFilterId` as these uniquely correspond to what the user sees
1. `setMultiple` is an effect that sets a `filter` to a multi-select dropdown (they are all single select by default). It is an array of `stateFilterId`s (`1.3` in the visualisation) This is aggregated via concatenation in the frontend so if two settings have `setMultiple` properties `["state_id_1", "state_id_2"]` and `["state_id_3"]` respectively then all three filters with those state ids will be set to multi-selects
1. `setMultiple` is an effect that converts a `filter` to a multi-select dropdown (they are all single select by default). It is an array of `stateFilterId`s (`1.3` in the visualisation) This is aggregated via concatenation in the frontend so if two settings have `setMultiple` properties `["state_id_1", "state_id_2"]` and `["state_id_3"]` respectively then all three filters with those state ids will be set to multi-selects
1. `setFilterValues` is an effect that sets the selection of the filters in `setFilters`. It is an object with keys equal to `stateFilterId` and value an array of ids of the `selections` (`b` in the visualisation). Note this is still an array of length one if you want to specify a value for a single select filter. This is aggregated by the [spread operator](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Spread_syntax#spread_in_object_literals) in the frontend
1. `setHidden` is an effect that hides `filters` and is usually used when we have a fixed filter that we don't want the user to change but is still required to slice the data. This is aggregated via concatenation in the frontend

Expand Down Expand Up @@ -298,7 +298,7 @@ type PlotSettingOption = {
type PlotSetting = {
id: PlotControlId,
label: string,
visible?: boolean,
hidden?: boolean,
value?: PlotSettingId,
options: PlotSettingOption[]
}
Expand Down

0 comments on commit 0987a37

Please sign in to comment.