Skip to contents

Template Dashboards

template-dashboards.Rmd

Template dashboards are for repeatable indicator-style datasets with geography, time, metric, and value columns.

Required shape

By default, template mode is inferred when a dataset contains:

  • iso3 for geography
  • year or date for time
  • variable for metric keys
  • value for numeric values
example_path <- system.file("extdata", "example_project", package = "vizRd")
ds <- vizRd::load_dataset("excises", example_path)
ds$schema$type
#> [1] "template"
names(ds$df)
#> [1] "iso3"           "year"           "variable"       "value"         
#> [5] "variable_label" "btn_ord"        "dataset_title"

Optional labels and titles

Template data can include variable_label for display labels and dataset_title for a title. RDS files may also use attributes:

attr(df, "var_labels") <- c(total = "Total excise duty")
attr(df, "app_title") <- "Excise dashboard"

vizRd keeps metric keys stable while showing labels in controls and chart text.

Dashboard views

Template dashboards support:

  • map for geography comparisons
  • bars for ranked values
  • line for trends over time
  • scatter for metric relationships
  • area for multi-geography time-series composition

Views are enabled only when the dataset and current selections satisfy their contracts. Invalid views are disabled with compact reasons instead of rendering empty charts.

Area mode and series controls

The area view uses the current ggplot2 + ggiraph renderer stack. v1.2 keeps that stack because the existing hover, click selection, sticky detail, export, share, embed, and package-local asset behavior remain part of the shipped contract.

For the packaged excises example, absolute mode is the default stacked area view:

example_path <- system.file("extdata", "example_project", package = "vizRd")
vizRd::run_app(path = example_path)

Share URLs can request the same area view explicitly:

vizRd::build_share_url(
  base_url = "https://example.org/vizrd/",
  dataset = "excises",
  view = "area",
  metric = "total_excise_duty_eur_1_000",
  geos = c("AUT", "DEU", "FRA"),
  area_mode = "absolute"
)

Use area_mode = "percent" for 100% stacked mode. Percent mode is valid only when the displayed area rows are finite, complete, non-negative, and have a positive total in every time period. If a shared or selected state violates that contract, vizRd keeps the area chart available in absolute mode and shows the invalid percent fallback: 100% mode needs non-negative complete values with a positive total in every time period. Showing absolute values.

vizRd::build_share_url(
  base_url = "https://example.org/vizrd/",
  dataset = "excises",
  view = "area",
  metric = "total_excise_duty_eur_1_000",
  area_mode = "percent"
)

When a displayed area state has more configured series than the area cap, vizRd applies deterministic Top-N plus Other aggregation after any explicit geos filter and before percent calculation. Other is a generated aggregate series with per-period sums, not discarded data. Source labels that are already called Other are disambiguated so the generated group keeps the literal Other label.

The area-series control isolates one or more displayed series after the area contract is prepared. All displayed series are selected by default; All restores that default, Clear intentionally shows the empty area state, and the chart exposes a Show all series recovery action. The generated Other series can be isolated like any named series.

vizRd::build_share_url(
  base_url = "https://example.org/vizrd/",
  dataset = "excises",
  view = "area",
  metric = "total_excise_duty_eur_1_000",
  area_mode = "percent",
  area_series = c("AUT", "Other")
)

Isolation is presentation state over the displayed contract. It does not rerun Top-N ranking and it does not renormalize percent denominators; hidden series can make visible percent areas total below 100%. PNG/PDF exports, JSON snapshots, reports, share URLs, and embed URLs preserve the same area_mode, Top-N plus Other warnings, area_series selection, and invalid percent fallback copy used by the live app.

Configuration

Explicit dataset entries in vizrd.yml keep template dashboards ordered and can attach technical notes:

datasets:
  - id: "excises"
    file: "data/excises.rds"
    title: "Cigarette Excise"
    technical_notes_pdf: "www/pdf/excises.pdf"