Getting started

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)
#> 
#> Attaching package: 'dplyr'
#> The following objects are masked from 'package:stats':
#> 
#>     filter, lag
#> The following objects are masked from 'package:base':
#> 
#>     intersect, setdiff, setequal, union
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

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

There are 32 records in unfiltered dataset.


On average they have

and can drive

8 cylinder cars have
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.