Title: KPI Widgets for Quarto Dashboards with Crosstalk
Version: 0.1.1
Description: Provides an easy way to create interactive KPI (key performance indicator) widgets for 'Quarto' dashboards using 'Crosstalk'. The package enables visualization of key metrics in a structured format, supporting interactive filtering and linking with other 'Crosstalk'-enabled components. Designed for use in 'Quarto' Dashboards.
License: MIT + file LICENSE
Encoding: UTF-8
RoxygenNote: 7.3.2
Imports: crosstalk, htmlwidgets
Suggests: dplyr, DT, flexdashboard, htmltools, knitr, rmarkdown, testthat (≥ 3.0.0)
VignetteBuilder: knitr
URL: https://arnold-kakas.github.io/kpiwidget/, https://github.com/Arnold-Kakas/kpiwidget
Config/testthat/edition: 3
BugReports: https://github.com/Arnold-Kakas/kpiwidget/issues
NeedsCompilation: no
Packaged: 2025-02-08 18:06:39 UTC; Arnold
Author: Arnold Kakas [aut, cre, cph]
Maintainer: Arnold Kakas <kakasarnold@gmail.com>
Repository: CRAN
Date/Publication: 2025-02-09 17:00:11 UTC

Create an interactive KPI widget for Quarto dashboards with Crosstalk support.

Description

This function computes and displays a key performance indicator (KPI) based on a variety of statistics. The data can be filtered using formulas. In addition, a comparison mode can be applied by specifying the comparison parameter as either "ratio" or "share". For example, if comparison = "ratio" and kpi = "sum" (with a column indicating sales), the widget will calculate the ratio of sales between two groups defined by group1 and group2.

Usage

kpiwidget(
  data,
  kpi = c("count", "distinctCount", "duplicates", "sum", "mean", "min", "max"),
  comparison = NULL,
  column = NULL,
  selection = NULL,
  group1 = NULL,
  group2 = NULL,
  decimals = 1,
  big_mark = " ",
  prefix = NULL,
  suffix = NULL,
  width = "auto",
  height = "auto",
  elementId = NULL,
  group = NULL
)

Arguments

data

A crosstalk::SharedData object.

kpi

A character string specifying the metric to compute. Options are: "sum", "mean", "min", "max", "count", "distinctCount", "duplicates". The default is count.

comparison

Optional. A character string indicating a comparison mode. Options are "ratio" or "share". If not provided (NULL), no comparison is performed.

column

A column name (as a string) to be used for numeric aggregation. In standard mode this is required. In comparison mode, if provided it is used for both groups; if omitted, counts are used.

selection

A one-sided formula to filter rows.

group1

For comparison mode: a one-sided formula defining group 1. This is required in comparison mode.

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.

decimals

Number of decimals to round the computed result. Default: 1.

big_mark

Character to be used as the thousands separator. Default: " ".

prefix

A string to be prepended to the displayed value.

suffix

A string to be appended to the displayed value.

width

Widget width (passed to htmlwidgets::createWidget). Default: "auto".

height

Widget height (passed to htmlwidgets::createWidget). Default: "auto".

elementId

Optional element ID for the widget.

group

crosstalk group name. Typically provided by the SharedData object.

Value

An object of class htmlwidget that will print itself into an HTML page.

Examples

# Standard KPI example:
mtcars_shared <- crosstalk::SharedData$new(mtcars, key = ~ 1:nrow(mtcars), group = "mtcars_group")
kpiwidget(mtcars_shared, kpi = "mean", column = "mpg", decimals = 1,
suffix = " mpg", height = "25px"
)

# Comparison (ratio) example: ratio of mean mpg between two groups.
kpiwidget(mtcars_shared, kpi = "mean", comparison = "ratio", column = "mpg",
  group1 = ~ cyl == 4, group2 = ~ cyl == 6,  height = "25px"
)