---
title: "Getting started"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{getting_started}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
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`:

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

## Loading Required Libraries

```{r setup}
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.

```{r}
# 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:

```{r}
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).

```{r}
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.

```{r}
kpiwidget(
  data = df_shared,
  column = "mpg",
  kpi = "sum",
  height = "25px"
)
```

### Mean

Computes the average (mean) of the selected column.

```{r}
kpiwidget(
  data = df_shared,
  column = "mpg",
  kpi = "mean",
  height = "25px"
)
```

### Minimum

Finds the minimum value in the selected column.

```{r}
kpiwidget(
  data = df_shared,
  column = "mpg",
  kpi = "min",
  height = "25px"
)
```

### Maximum

Finds the maximum value in the selected column.

```{r}
kpiwidget(
  data = df_shared,
  column = "mpg",
  kpi = "max",
  height = "25px"
)
```

### Count

Counts the number of rows in the dataset.

```{r}
kpiwidget(
  data = df_shared,
  column = "mpg",
  kpi = "count",
  height = "25px"
)
```

### Distinct Count

Counts the number of unique values in the selected column.

```{r}
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:
```{r}
kpiwidget(
  data = df_shared,
  column = "mpg",
  kpi = "mean",
  comparison = "ratio",
  group1 = ~ cyl == 4,
  height = "25px"
)
```

group2:
```{r}
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:
```{r}
kpiwidget(
  data = df_shared,
  column = "mpg",
  kpi = "count",
  comparison = "share",
  group1 = ~ cyl == 4,
  height = "25px"
)
```

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

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

## Formatting Options

### Decimals

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

### Big Mark

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

### Prefix

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

### Suffix

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

## Bringing It All Together

```{r example, echo=FALSE}
  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.")`<br>
On average they have `r kpiwidget(data = df_shared, kpi = 'mean', column = 'hp', decimals = 0, suffix = " HP")`<br>
and can drive `r kpiwidget(data = df_shared, column = "mpg", kpi = "mean", suffix = " mpg.")`<br>
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.
