Getting started

In kpiwidget: KPI Widgets for Quarto Dashboards with Crosstalk

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)

Introduction

The kpiwidget package provides an easy way to create KPI (Key Performance Indicator) widgets for dashboards using crosstalk shared data. This vignette demonstrates different options and functionalities available in kpiwidget.

Installation

Before using kpiwidget, ensure that it is installed along with crosstalk:

# install.packages("crosstalk")
# Install kpiwidget from CRAN or GitHub
# install.packages("kpiwidget")
# devtools::install_github("your_github/kpiwidget")

Loading Required Libraries

library(kpiwidget)
library(crosstalk)
library(DT)
library(dplyr)
library(htmltools)

Creating a Shared Data Object

To enable interactivity, we first wrap our dataset in SharedData from crosstalk. This allows filtering across multiple widgets using the same dataset.

# Create a shared data object with row numbers as keys
df_shared <- crosstalk::SharedData$new(mtcars, key = ~ 1:nrow(mtcars), group = "mtcars_group")

Adding Filters

crosstalk allows dynamic filtering of data. Here, we add a filter to select vehicles based on the number of gears:

crosstalk::filter_checkbox("gear", "Gear", df_shared, ~gear, inline = TRUE)

Using kpiwidget

The kpiwidget function provides a simple way to display key performance indicators. The column parameter is required, and by default, it calculates the count (number of rows in the dataset).

kpiwidget(
  data = df_shared,
  column = "mpg",
  height = "25px"
)

Parameters

• data - A crosstalk::SharedData object.
• kpi - A character string specifying the metric to compute. Options: count, distinctCount, duplicates, sum, mean, min, max. Default is count.
• comparison - A character string indicating a comparison mode. Options are ratio or share. Default is NULL.
• column - A column name (as a string) to be used for numeric aggregation. Default is NULL, this parameter is REQUIRED.
• selection - A one-sided formula. Serves as a global filter. Default is NULL.
• group1 - For comparison mode: a one-sided formula defining group 1. This is required in comparison mode. Default is NULL.
• group2 - For comparison mode: a one-sided formula defining group 2. For comparison = "ratio", if not provided, it defaults to the complement of group1. For comparison = "share", if not provided, it defaults to all rows. Default is NULL.
• decimals - Number of decimals to round the computed result. Default is 1.
• big_mark - Character to be used as the thousands separator. Default is " ".
• prefix - A string to be prepended to the displayed value. Default is NULL.
• suffix - A string to be appended to the displayed value. Default is NULL.
• width - Widget width (passed to htmlwidgets::createWidget). Default is NULL.
• height - Widget height (passed to htmlwidgets::createWidget). Default is NULL.
• elementId - Optional element ID for the widget. Default is NULL.
• group - Crosstalk group name. Typically provided by the SharedData object. Default is NULL.

KPI Options

The kpi parameter allows different types of calculations. Below, we demonstrate various options available in kpiwidget.

Sum

Calculates the sum of the selected column.

kpiwidget(
  data = df_shared,
  column = "mpg",
  kpi = "sum",
  height = "25px"
)

Mean

Computes the average (mean) of the selected column.

kpiwidget(
  data = df_shared,
  column = "mpg",
  kpi = "mean",
  height = "25px"
)

Minimum

Finds the minimum value in the selected column.

kpiwidget(
  data = df_shared,
  column = "mpg",
  kpi = "min",
  height = "25px"
)

Maximum

Finds the maximum value in the selected column.

kpiwidget(
  data = df_shared,
  column = "mpg",
  kpi = "max",
  height = "25px"
)

Count

Counts the number of rows in the dataset.

kpiwidget(
  data = df_shared,
  column = "mpg",
  kpi = "count",
  height = "25px"
)

Distinct Count

Counts the number of unique values in the selected column.

kpiwidget(
  data = df_shared,
  column = "cyl",
  kpi = "distinctCount",
  height = "25px"
)

Comparison Options

Ratio

Calculates the ratio of a subset defined with group1 parameter (e.g., cars with 4 cylinders) compared to the complement of group1 filter (default setting for "ratio") or to the subset defined with group2 parameter.

default:

kpiwidget(
  data = df_shared,
  column = "mpg",
  kpi = "mean",
  comparison = "ratio",
  group1 = ~ cyl == 4,
  height = "25px"
)

group2:

kpiwidget(
  data = df_shared,
  column = "mpg",
  kpi = "mean",
  comparison = "ratio",
  group1 = ~ cyl == 4,
  group2 = ~ cyl == 6,
  height = "25px"
)

Share

Computes the share between two groups (e.g., cars with 4 cylinders and full dataset or subset defined with group2 pamarater).

default:

kpiwidget(
  data = df_shared,
  column = "mpg",
  kpi = "count",
  comparison = "share",
  group1 = ~ cyl == 4,
  height = "25px"
)

group2:

kpiwidget(
  data = df_shared,
  column = "mpg",
  kpi = "count",
  comparison = "share",
  group1 = ~ cyl == 4,
  group2 = ~ cyl %in% c(4, 6),
  height = "25px"
)

using selection:

kpiwidget(
  data = df_shared,
  column = "mpg",
  kpi = "count",
  selection = ~ cyl %in% c(4, 6),
  comparison = "share",
  group1 = ~ cyl == 4,
  height = "25px"
)

Formatting Options

Decimals

kpiwidget(
  data = df_shared,
  column = "mpg",
  kpi = "mean",
  decimals = 3,
  height = "25px"
)

Big Mark

kpiwidget(
  data = df_shared,
  column = "disp",
  kpi = "sum",
  big_mark = " ,",
  height = "25px"
)

Prefix

kpiwidget(
  data = df_shared,
  column = "mpg",
  kpi = "mean",
  prefix = "mean mpg: ",
  height = "25px"
)

Suffix

kpiwidget(
  data = df_shared,
  column = "mpg",
  kpi = "count",
  comparison = "share",
  group1 = ~ cyl == 4,
  suffix = " %",
  height = "25px"
)

Bringing It All Together

  crosstalk::filter_slider("wt", "Weight", df_shared, ~wt, width = "100%")

  DT::datatable(df_shared, 
            extensions = "Scroller",
            style = "bootstrap",
            class = "compact",
            width = "100%",
            options = list(deferRender = TRUE, 
                           scrollY = 300,
                           scroller = TRUE)
            )

There are 32 records in unfiltered dataset. r kpiwidget(data = df_shared, kpi = "count", column = "mpg", decimals = 0, suffix = " car(s) are currently selected.")
On average they have r kpiwidget(data = df_shared, kpi = 'mean', column = 'hp', decimals = 0, suffix = " HP")
and can drive r kpiwidget(data = df_shared, column = "mpg", kpi = "mean", suffix = " mpg.")
8 cylinder cars have r kpiwidget(data = df_shared, column = "hp", kpi = "mean", comparison = "ratio", group1 = ~ cyl == 8) times more HP than the rest of cars in selection.

Conclusion

The kpiwidget package provides a flexible way to display KPIs in interactive dashboards. Using crosstalk, it enables real-time filtering and comparison of data.

kpiwidget documentation built on April 4, 2025, 2:31 a.m.