---
title: "Getting Started with arulesViz"
author: "Michael Hahsler"
output:
  rmarkdown::html_vignette:
    toc: true
vignette: >
  %\VignetteIndexEntry{Getting Started with arulesViz}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include=FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.width = 7,
  fig.height = 5
)
library(arulesViz)
set.seed(1234)
```

`arulesViz` adds static and interactive visualizations for association rules
and frequent itemsets created with
[`arules`](https://CRAN.R-project.org/package=arules). This vignette shows a
typical first workflow: mine a set of rules, look at its overall structure,
select an interesting subset, and inspect that subset in more detail.

## Installation

Install the released version from CRAN and load it:

```{r installation, eval=FALSE}
install.packages("arulesViz")
library(arulesViz)
```

Loading `arulesViz` also loads `arules`, which provides the data structures and
mining algorithms used below.

## Create a set of rules

We use the `Groceries` transaction data included with `arules` and mine rules
with the Apriori algorithm. The thresholds are deliberately restrictive so
the resulting rule set is small enough to explore comfortably.

```{r mine-rules}
data("Groceries")

rules <- apriori(
  Groceries,
  parameter = list(support = 0.005, confidence = 0.5),
  control = list(verbose = FALSE)
)
rules
```

`arulesViz` extends the standard `plot()` generic for objects of class
`rules` and `itemsets`. For rules, the default is a scatter plot of support
against confidence, with color representing lift.

## Start with an overview

```{r scatterplot}
plot(rules)
```

Each point is one rule. Rules toward the upper right have higher support and
confidence, while the color scale identifies rules with high lift. Measures
can be changed explicitly, and `limit` keeps the most highly shaded rules when
a rule set is too large to display clearly.

```{r custom-scatterplot}
plot(
  rules,
  measure = c("support", "lift"),
  shading = "confidence",
  limit = 100
)
```

A two-key plot uses color for the rule length (also called its order).

```{r two-key-plot}
plot(rules, method = "two-key plot")
```

## Focus on interesting rules

Most detailed visualizations work best on a selected subset. Here we sort by
lift and retain 20 rules. In a real analysis, selection should also reflect
the application, for example by requiring a particular item on the left- or
right-hand side.

```{r select-rules}
rules_top <- head(sort(rules, by = "lift"), 20)
inspect(head(rules_top, 5))
```

A graph makes the items shared by rules easy to see. Rule vertices connect
left-hand-side items to right-hand-side items.

```{r graph}
plot(rules_top, method = "graph")
```

A matrix plot places antecedents in columns and consequents in rows. Color
represents the selected interest measure; the default shading measure is
lift.

```{r matrix}
plot(rules_top, method = "matrix")
```

For larger rule sets, the grouped matrix view clusters similar antecedents.
The `k` argument controls the number of groups.

```{r grouped-matrix}
plot(rules, method = "grouped matrix", k = 10)
```

Other available methods include parallel coordinates (`"paracoord"`) and,
for a single rule together with its original transactions, mosaic and double
decker plots. Use the built-in help interface to discover the methods,
rendering engines, and method-specific controls:

```{r plot-help, eval=FALSE}
plot(rules, method = "help")
plot(rules, method = "graph", engine = "help")
plot(rules, method = "graph", control = "help")
```

## Interactive exploration

Several visualization methods can produce HTML widgets. Hovering over points
in this scatter plot reveals the corresponding rule and its quality measures.

```{r interactive-scatterplot, eval=FALSE}
plot(rules, engine = "htmlwidget")
```

`inspectDT()` creates a searchable and sortable table, while `ruleExplorer()`
starts a Shiny application that combines filtering, tables, and plots.

```{r interactive-tools, eval=FALSE}
inspectDT(rules)
ruleExplorer(rules)
```

HTML widgets can become slow with very large rule sets. Select rules first or
use `limit` before creating an interactive visualization.

## Visualize frequent itemsets

The same interface also supports frequent itemsets. For example, mine
itemsets with `eclat()` and display the ten most frequent itemsets as a graph:

```{r itemsets}
itemsets <- eclat(
  Groceries,
  parameter = list(support = 0.02, minlen = 2),
  control = list(verbose = FALSE)
)

plot(itemsets, method = "graph", limit = 10)
```

For a complete description of all visualization methods and their arguments,
see `?arulesViz::plot`. The package documentation for `inspectDT()` and
`ruleExplorer()` covers the interactive tools in more detail.