Package 'arules'

Description

Provides the generic function and the methods to abbreviate long item labels in transactions, associations (rules and itemsets) and transaction ID lists. Note that abbreviate() is not a generic and this arules defines a generic with the base::abbreviate() as the default.

Usage

abbreviate(names.arg, ...)

## S4 method for signature 'itemMatrix'
abbreviate(names.arg, minlength = 4, ..., method = "both.sides")

## S4 method for signature 'transactions'
abbreviate(names.arg, minlength = 4, ..., method = "both.sides")

## S4 method for signature 'rules'
abbreviate(names.arg, minlength = 4, ..., method = "both.sides")

## S4 method for signature 'itemsets'
abbreviate(names.arg, minlength = 4, ..., method = "both.sides")

## S4 method for signature 'tidLists'
abbreviate(names.arg, minlength = 4, ..., method = "both.sides")

Arguments

Author(s)

Sudheer Chelluboina and Michael Hahsler based on code by Martin Vodenicharov.

See Also

base::abbreviate()

Other associations functions: associations-class, c(), duplicated(), extract, inspect(), is.closed(), is.generator(), is.maximal(), is.redundant(), is.significant(), is.superset(), itemsets-class, match(), rules-class, sample(), sets, size(), sort(), unique()

Other itemMatrix and transactions functions: c(), crossTable(), duplicated(), extract, hierarchy, image(), inspect(), is.superset(), itemFrequency(), itemFrequencyPlot(), itemMatrix-class, match(), merge(), random.transactions(), sample(), sets, size(), supportingTransactions(), tidLists-class, transactions-class, unique()

Examples

data(Adult)
inspect(head(Adult, 1))

Adult_abbr <- abbreviate(Adult, 15)
inspect(head(Adult_abbr, 1))

Description

Provides the generic function addComplement() and a method for transactions to add complement items. That is, it adds an artificial item to each transaction which does not contain the original item. Such items are also called negative items (Antonie et al, 2014).

Usage

addComplement(x, labels, complementLabels = NULL)

## S4 method for signature 'transactions'
addComplement(x, labels, complementLabels = NULL)

Arguments

Value

Returns an object of class transactions with complement items added.

Author(s)

Michael Hahsler

References

Antonie L., Li J., Zaiane O. (2014) Negative Association Rules. In: Aggarwal C., Han J. (eds) Frequent Pattern Mining, Springer International Publishing, pp. 135-145. doi:10.1007/978-3-319-07821-2_6

Examples

data("Groceries")

## add a complement-items for "whole milk" and "other vegetables"
g2 <- addComplement(Groceries, c("whole milk", "other vegetables"))
g2
tail(itemInfo(g2))
inspect(head(g2, 3))

## use a custom label for the complement-item
g3 <- addComplement(g2, "coffee", complementLabels = "NO coffee")
inspect(head(g2, 3))

## add complements for all items (this is excessive for this dataset)
g4 <- addComplement(Groceries, itemLabels(Groceries))
g4

## add complements for all items with a minimum support of 0.1
g5 <- addComplement(Groceries, names(which(itemFrequency(Groceries) >= 0.1)))
g5

Description

The AdultUCI data set contains the questionnaire data of the Adult database (originally called the Census Income Database) formatted as a data.frame. The Adult data set contains the data already prepared and coerced to transactions for use with arules.

Format

Adult is an object of class transactions with 48842 transactions and 115 items. See below for details.

The AdultUCI data set contains a data frame with 48842 observations on the following 15 variables.

age

a numeric vector.

workclass

a factor with levels Federal-gov, Local-gov, Never-worked, Private, Self-emp-inc, Self-emp-not-inc, State-gov, and Without-pay.

education

an ordered factor with levels Preschool < ⁠1st-4th⁠ < ⁠5th-6th⁠ < ⁠7th-8th⁠ < ⁠9th⁠ < ⁠10th⁠ < ⁠11th⁠ < ⁠12th⁠ < HS-grad < Prof-school < Assoc-acdm < Assoc-voc < Some-college < Bachelors < Masters < Doctorate.

education-num

a numeric vector.

marital-status

a factor with levels Divorced, Married-AF-spouse, Married-civ-spouse, Married-spouse-absent, Never-married, Separated, and Widowed.

occupation

a factor with levels Adm-clerical, Armed-Forces, Craft-repair, Exec-managerial, Farming-fishing, Handlers-cleaners, Machine-op-inspct, Other-service, Priv-house-serv, Prof-specialty, Protective-serv, Sales, Tech-support, and Transport-moving.

relationship

a factor with levels Husband, ⁠Not-in-family⁠, Other-relative, Own-child, Unmarried, and Wife.

race

a factor with levels Amer-Indian-Eskimo, Asian-Pac-Islander, Black, Other, and White.

sex

a factor with levels Female and Male.

capital-gain

a numeric vector.

capital-loss

a numeric vector.

fnlwgt

a numeric vector.

hours-per-week

a numeric vector.

native-country

a factor with levels Cambodia, Canada, China, Columbia, Cuba, Dominican-Republic, Ecuador, El-Salvador, England, France, Germany, Greece, Guatemala, Haiti, Holand-Netherlands, Honduras, Hong, Hungary, India, Iran, Ireland, Italy, Jamaica, Japan, Laos, Mexico, Nicaragua, Outlying-US(Guam-USVI-etc), Peru, Philippines, Poland, Portugal, Puerto-Rico, Scotland, South, Taiwan, Thailand, Trinadad&Tobago, United-States, Vietnam, and Yugoslavia.

income

an ordered factor with levels small < large.

Details

The Adult database was extracted from the census bureau database found at https://www.census.gov/ in 1994 by Ronny Kohavi and Barry Becker (Data Mining and Visualization, Silicon Graphics). It was originally used to predict whether income exceeds USD 50K/yr based on census data. We added the attribute income with levels small and large (>50K).

We prepared the data set for association mining as shown in the section Examples. We removed the continuous attribute fnlwgt (final weight). We also eliminated education-num because it is just a numeric representation of the attribute education. The other 4 continuous attributes we mapped to ordinal attributes as follows:

• age: cut into levels Young (0-25), Middle-aged (26-45), Senior (46-65) and Old (66+)

• hours-per-week: cut into levels Part-time (0-25), Full-time (25-40), Over-time (40-60) and Too-much (60+)

• capital-gain and capital-loss: each cut into levels None (0), Low (0 < median of the values greater zero < max) and High (>=max)

Author(s)

Michael Hahsler

Source

https://archive.ics.uci.edu/

References

A. Asuncion & D. J. Newman (2007): UCI Repository of Machine Learning Databases. Irvine, CA: University of California, Department of Information and Computer Science.

The data set was first cited in Kohavi, R. (1996): Scaling Up the Accuracy of Naive-Bayes Classifiers: a Decision-Tree Hybrid. Proceedings of the Second International Conference on Knowledge Discovery and Data Mining.

Examples

data("AdultUCI")
dim(AdultUCI)
AdultUCI[1:2, ]

## remove attributes
AdultUCI[["fnlwgt"]] <- NULL
AdultUCI[["education-num"]] <- NULL

## map metric attributes
AdultUCI[["age"]] <- ordered(cut(AdultUCI[["age"]], c(15, 25, 45, 65, 100)),
  labels = c("Young", "Middle-aged", "Senior", "Old")
)

AdultUCI[["hours-per-week"]] <- ordered(
  cut(
    AdultUCI[["hours-per-week"]],
    c(0, 25, 40, 60, 168)
  ),
  labels = c("Part-time", "Full-time", "Over-time", "Workaholic")
)

AdultUCI[["capital-gain"]] <- ordered(cut(
  AdultUCI[["capital-gain"]],
  c(
    -Inf, 0, median(AdultUCI[["capital-gain"]][AdultUCI[["capital-gain"]] > 0]),
    Inf
  )
), labels = c("None", "Low", "High"))

AdultUCI[["capital-loss"]] <- ordered(cut(
  AdultUCI[["capital-loss"]],
  c(
    -Inf, 0, median(AdultUCI[["capital-loss"]][AdultUCI[["capital-loss"]] > 0]),
    Inf
  )
), labels = c("None", "Low", "High"))

## create transactions
Adult <- transactions(AdultUCI)
Adult

Description

Provides the generic function affinity() and methods to compute and return a similarity matrix with the affinities between items for a set itemsets stored in a matrix or in transactions via its superclass itemMatrix.

Usage

affinity(x)

## S4 method for signature 'matrix'
affinity(x)

## S4 method for signature 'itemMatrix'
affinity(x)

Arguments

Details

Affinity between the two items $i$ and $j$ is defined by Aggarwal et al. (2002) as

$A(i,j) = \frac{supp(\{i,j\})}{supp(\{i\}) + supp(\{j\}) - supp(\{i,j\})},$

where $supp(.)$ is the support measure. Note that affinity is equivalent to the Jaccard similarity between items.

Value

returns an object of class ar_similarity which represents the affinities between items in x.

Author(s)

Michael Hahsler

References

Charu C. Aggarwal, Cecilia Procopiuc, and Philip S. Yu (2002) Finding localized associations in market basket data, IEEE Trans. on Knowledge and Data Engineering, 14(1):51–62.

See Also

Other proximity classes and functions: dissimilarity(), predict(), proximity-classes

Examples

data("Adult")

## choose a sample, calculate affinities
s <- sample(Adult, 500)
s

a <- affinity(s)
image(a)

Description

Specifies the restrictions on the associations mined by apriori(). These restrictions can implement certain aspects of rule templates described by Klemettinen (1994).

Details

Note that appearance is only supported by the implementation of apriori().

Slots

labels

character vectors giving the labels of the items which can appear in the specified place (rhs, lhs or both for rules and items for itemsets). none specifies, that the items mentioned there cannot appear anywhere in the rule/itemset. Note that items cannot be specified in more than one place (i.e., you cannot specify an item in lhs and rhs, but have to specify it as both).

default

one of "both", "lhs", "rhs", "none". Specified the default appearance for all items not explicitly mentioned in the other elements of the list. Leave unspecified and the code will guess the correct setting.

set

used internally.

items

used internally.

Objects from the Class

If appearance restrictions are used, an appearance object will be created automatically within the apriori() function using the information in the named list of the function's appearance argument. In this case, the item labels used in the list will be automatically matched against the items in the used transactions.

Objects can also be created by calls of the form new("APappearance", ...). In this case, item IDs (column numbers of the transactions incidence matrix) have to be used instead of labels.

Coercions

• as("NULL", "APappearance")

• as("list", "APappearance")

Author(s)

Michael Hahsler and Bettina Gruen

References

Christian Borgelt (2004) Apriori — Finding Association Rules/Hyperedges with the Apriori Algorithm. https://borgelt.net/apriori.html

M. Klemettinen, H. Mannila, P. Ronkainen, H. Toivonen and A. I. Verkamo (1994). Finding Interesting Rules from Large Sets of Discovered Association Rules. In Proceedings of the Third International Conference on Information and Knowledge Management, 401–407.

See Also

Other mining algorithms: AScontrol-classes, ASparameter-classes, apriori(), eclat(), fim4r(), ruleInduction(), weclat()

Examples

data("Adult")

## find only frequent itemsets which do not contain small or large income
is <- apriori(Adult,
  parameter = list(support = 0.1, target = "frequent"),
  appearance = list(none = c("income=small", "income=large"))
)
itemFrequency(items(is))["income=small"]
itemFrequency(items(is))["income=large"]

## find itemsets that only contain small or large income, or young age
is <- apriori(Adult,
  parameter = list(support = 0.1, target = "frequent"),
  appearance = list(items = c("income=small", "income=large", "age=Young"))
)
inspect(head(is))

## find only rules with income-related variables in the right-hand-side.
incomeItems <- grep("^income=", itemLabels(Adult), value = TRUE)
incomeItems
rules <- apriori(Adult,
  parameter = list(support = 0.2, confidence = 0.5),
  appearance = list(rhs = incomeItems)
)
inspect(head(rules))

## Note: For more complicated restrictions you have to mine all rules/itemsets and
## then filter the results afterwards.

Description

Mine frequent itemsets, association rules or association hyperedges using the Apriori algorithm.

Usage

apriori(data, parameter = NULL, appearance = NULL, control = NULL, ...)

Arguments

Details

The Apriori algorithm (Agrawal et al, 1993) employs level-wise search for frequent itemsets. The used C implementation of Apriori by Christian Borgelt (2003) includes some improvements (e.g., a prefix tree and item sorting).

Warning about automatic conversion of matrices or data.frames to transactions. It is preferred to create transactions manually before calling apriori() to have control over item coding. This is especially important when you are working with multiple datasets or several subsets of the same dataset. To read about item coding, see itemCoding.

If a data.frame is specified as x, then the data is automatically converted into transactions by discretizing numeric data using discretizeDF() and then coercion to transactions. The discretization may fail if the data is not well behaved.

Apriori only creates rules with one item in the RHS (Consequent). The default value in APparameter for minlen is 1. This meains that rules with only one item (i.e., an empty antecedent/LHS) like

$\{\} => \{beer\}$

will be created. These rules mean that no matter what other items are involved, the item in the RHS will appear with the probability given by the rule's confidence (which equals the support). If you want to avoid these rules then use the argument parameter = list(minlen = 2).

Notes on run time and memory usage: If the minimum support is chosen too low for the dataset, then the algorithm will try to create an extremely large set of itemsets/rules. This will result in very long run time and eventually the process will run out of memory. To prevent this, the default maximal length of itemsets/rules is restricted to 10 items (via the parameter element maxlen = 10) and the time for checking subsets is limited to 5 seconds (via maxtime = 5). The output will show if you hit these limits in the "checking subsets" line of the output. The time limit is only checked when the subset size increases, so it may run significantly longer than what you specify in maxtime. Setting maxtime = 0 disables the time limit.

Interrupting execution with Control-C/Esc is not recommended. Memory cleanup will be prevented resulting in a memory leak. Also, interrupts are only checked when the subset size increases, so it may take some time till the execution actually stops.

Value

Returns an object of class rules or itemsets.

Author(s)

Michael Hahsler and Bettina Gruen

References

R. Agrawal, T. Imielinski, and A. Swami (1993) Mining association rules between sets of items in large databases. In Proceedings of the ACM SIGMOD International Conference on Management of Data, pages 207–216, Washington D.C. doi:10.1145/170035.170072

Christian Borgelt (2012) Frequent Item Set Mining. Wiley Interdisciplinary Reviews: Data Mining and Knowledge Discovery 2(6):437-456. J. Wiley & Sons, Chichester, United Kingdom 2012. doi:10.1002/widm.1074

Christian Borgelt and Rudolf Kruse (2002) Induction of Association Rules: Apriori Implementation. 15th Conference on Computational Statistics (COMPSTAT 2002, Berlin, Germany) Physica Verlag, Heidelberg, Germany.

Christian Borgelt (2003) Efficient Implementations of Apriori and Eclat. Workshop of Frequent Item Set Mining Implementations (FIMI 2003, Melbourne, FL, USA).

APRIORI Implementation: https://borgelt.net/apriori.html

See Also

Other mining algorithms: APappearance-class, AScontrol-classes, ASparameter-classes, eclat(), fim4r(), ruleInduction(), weclat()

Examples

## Example 1: Create transaction data and mine association rules
a_list <- list(
  c("a", "b", "c"),
  c("a", "b"),
  c("a", "b", "d"),
  c("c", "e"),
  c("a", "b", "d", "e")
)

## Set transaction names
names(a_list) <- paste("Tr", c(1:5), sep = "")
a_list

## Use the constructor to create transactions
trans1 <- transactions(a_list)
trans1

rules <- apriori(trans1)
inspect(rules)

## Example 2: Mine association rules from an existing transactions dataset
##   using different minimum support and minimum confidence thresholds
data("Adult")

rules <- apriori(Adult,
  parameter = list(supp = 0.5, conf = 0.9, target = "rules")
)
summary(rules)

# since ... gets automatically added to parameter, we can also write the
#  same call shorter:
apriori(Adult, supp = 0.5, conf = 0.9, target = "rules")

Description

The AScontrol class holds the algorithmic parameters for the used mining algorithms. APcontrol and ECcontrol directly extend AScontrol with additional slots for parameters only suitable for the algorithms Apriori (APcontrol) and Eclat (ECcontrol).

Slots

sort

an integer scalar indicating how to sort items with respect to their frequency: (default: 2)

• 1: ascending

• -1: descending

• 0: do not sort

• 2: ascending

• -2: descending with respect to transaction size sum

verbose

a logical indicating whether to report progress

filter

a numeric scalar indicating how to filter unused items from transactions (default: 0.1)

• $=0$: do not filter items with respect to. usage in sets

• $<0$: fraction of removed items for filtering

• $>0$: take execution times ratio into account

tree

a logical indicating whether to organize transactions as a prefix tree (default: TRUE)

heap

a logical indicating whether to use heapsort instead of quicksort to sort the transactions (default: TRUE)

memopt

a logical indicating whether to minimize memory usage instead of maximize speed (default: FALSE)

load

a logical indicating whether to load transactions into memory (default: TRUE)

sparse

a numeric value for the threshold for sparse representation (default: 7)

Available Slots by Subclass

• APcontrol: filter, tree, heap, memopt, load, sort, verbose

• ECcontrol: sparse, sort, verbose

Objects from the Class

A suitable default control object will be automatically created by the apriori() or the eclat() function. By specifying a named list (names equal to slots) as the control argument for apriori() or eclat(), default values can be replaced with the values in the list.

Objects can also be created via coercion.

Coercions

• as("NULL", "APcontrol")

• as("list", "APcontrol")

• as("NULL", "ECcontrol")

• as("list", "ECcontrol")

Author(s)

Michael Hahsler and Bettina Gruen

References

Christian Borgelt (2004) Apriori — Finding Association Rules/Hyperedges with the Apriori Algorithm. https://borgelt.net/apriori.html

See Also

Other mining algorithms: APappearance-class, ASparameter-classes, apriori(), eclat(), fim4r(), ruleInduction(), weclat()

Description

The ASparameter class holds the mining parameters (e.g., minimum support) for the used mining algorithms. APparameter and ECparameter directly extend ASparameter with additional slots for parameters only suitable for apriori() (APparameter) or eclat() (ECparameter).

Slots

support

a numeric value for the minimal support of an item set (default: $0.1$)

minlen

an integer value for the minimal number of items per item set (default: 1 item)

maxlen

an integer value for the maximal number of items per item set (default: 10 items)

target

a character string indicating the type of association mined. Partial names are matched. Available targets are:

• "frequent itemsets"

• "maximally frequent itemsets"

• "generator frequent itemsets"

• "closed frequent itemsets"

• "rules" only available for apriori; use ruleInduction for eclat.

• "hyperedgesets" only available for apriori; see references for the definition of association hyperedgesets.

ext

a logical indicating whether to report coverage (i.e., LHS-support) as an extended quality measure (default: TRUE)

confidence

a numeric value for the minimal confidence of rules/association hyperedges (default: $0.8$). For frequent itemsets it is set to NA.

smax

a numeric value for the maximal support of itemsets/rules/hyperedgesets (default: 1)

arem

a character string indicating the used additional rule evaluation measure (default: "none") given by one of

• "none": no additional evaluation measure

• "diff": absolute confidence difference

• "quot": difference of confidence quotient to 1

• "aimp": absolute difference of improvement to 1

• "info": information difference to prior

• "chi2": normalized $\chi^2$ measure

Note: The measure is only reported if aval is set to TRUE. Use minval to set minimum thresholds on the measures.

aval

a logical indicating whether to return the additional rule evaluation measure selected with arem.

minval

a numeric value for the minimal value of additional evaluation measure selected with arem (default: $0.1$)

originalSupport

a logical indicating whether to use the original definition of minimum support (support of the LHS and RHS of the rule). If set to FALSE then the support of the LHS (also called coverage of the rule) is returned as support. The minimum support threshold is applied to this support. (default: TRUE)

maxtime

Time limit in seconds for checking subsets. maxtime = 0 disables the time limit. (default: 5 seconds)

tidLists

a logical indicating whether eclat() should return also a list of supporting transactions IDs. (default: FALSE)

Available Slots by Subclass

• APparameter: confidence, minval, smax, arem, aval, originalSupport, maxtime, support, minlen, maxlen, target, ext

• ECparameter: tidLists, support, minlen, maxlen, target, ext

Objects from the Class

A suitable default parameter object will be automatically created by apriori() or eclat(). By specifying a named list (names equal to slots) as parameter argument for apriori() or eclat(), the default values can be replaced with the values in the list.

Objects can also be created via coercion.

Coercions

• as("NULL", "APparameter")

• as("list", "APparameter")

• as("NULL", "ECparameter")

• as("list", "ECparameter")

Author(s)

Michael Hahsler and Bettina Gruen

References

Christian Borgelt (2004) Apriori — Finding Association Rules/Hyperedges with the Apriori Algorithm. https://borgelt.net/apriori.html

See Also

Other mining algorithms: APappearance-class, AScontrol-classes, apriori(), eclat(), fim4r(), ruleInduction(), weclat()

Description

The associations class is a virtual class which is extended to represent mining result (e.g., sets of itemsets or rules). The class defines some common methods for its subclasses.

Usage

## S4 method for signature 'associations'
quality(x)

## S4 replacement method for signature 'associations'
quality(x) <- value

## S4 method for signature 'associations'
info(x)

## S4 replacement method for signature 'associations'
info(x) <- value

## S4 method for signature 'associations'
head(x, n = 6L, by = NULL, decreasing = TRUE, ...)

## S4 method for signature 'associations'
tail(x, n = 6L, by = NULL, decreasing = TRUE, ...)

## S4 method for signature 'associations'
items(x)

## S4 method for signature 'associations'
length(x)

## S4 method for signature 'associations'
labels(object)

Arguments

Details

The implementations of associations store itemsets (e.g., the LHS and RHS of a rule) as objects of class itemMatrix (i.e., sparse binary matrices). Quality measures (e.g., support) are stored in a data.frame accessible via method quality().

See Sections Functions and See Also to see all available methods.

Note: Associations can store multisets with duplicated elements. Duplicated elements can result from combining several sets of associations. Use unique() to remove duplicate associations.

Functions

• quality(associations): returns the quality data.frame.

• quality(associations) <- value: replaces the quality data.frame. The lengths of the vectors in the data.frame have to equal the number of associations in the set.

• info(associations): returns the info list.

• info(associations) <- value: replaces the info list.

• head(associations): returns the first n associations.

• tail(associations): returns the last n associations.

• items(associations): dummy method. This method has to be implemented by all subclasses of associations and return the items which make up each association as an object of class itemMatrix.

• length(associations): dummy method. This method has to be implemented by all subclasses of associations and return the number of elements in the association.

• labels(associations): dummy method. This method has to be implemented by all subclasses of associations and return a vector of length(object) of labels for the elements in the association.

Slots

quality

a data.frame

info

a list

Objects from the Class

A virtual class: No objects may be created from it.

Author(s)

Michael Hahsler

See Also

Subclasses: rules, itemsets

Other associations functions: abbreviate(), c(), duplicated(), extract, inspect(), is.closed(), is.generator(), is.maximal(), is.redundant(), is.significant(), is.superset(), itemsets-class, match(), rules-class, sample(), sets, size(), sort(), unique()

Description

Provides the methods to combine several associations or transactions objects into a single object.

Usage

## S4 method for signature 'itemMatrix'
c(x, ..., recursive = FALSE)

## S4 method for signature 'transactions'
c(x, ..., recursive = FALSE)

## S4 method for signature 'tidLists'
c(x, ..., recursive = FALSE)

## S4 method for signature 'rules'
c(x, ..., recursive = FALSE)

## S4 method for signature 'itemsets'
c(x, ..., recursive = FALSE)

Arguments

Details

Combining arules objects is done by combining the rows of itemMatrix objects representing the associations or transactions.

Note that c() can result in duplicates. Use union() rather than c() to combine several mined itemsets or rules into a single set without duplicates.

Value

An object of the same class as x.

Author(s)

Michael Hahsler

See Also

Other associations functions: abbreviate(), associations-class, duplicated(), extract, inspect(), is.closed(), is.generator(), is.maximal(), is.redundant(), is.significant(), is.superset(), itemsets-class, match(), rules-class, sample(), sets, size(), sort(), unique()

Other itemMatrix and transactions functions: abbreviate(), crossTable(), duplicated(), extract, hierarchy, image(), inspect(), is.superset(), itemFrequency(), itemFrequencyPlot(), itemMatrix-class, match(), merge(), random.transactions(), sample(), sets, size(), supportingTransactions(), tidLists-class, transactions-class, unique()

Examples

data("Adult")

## combine transactions
a1 <- Adult[1:10]
a2 <- Adult[101:110]

aComb <- c(a1, a2)
summary(aComb)

## combine rules (can contain the same rule multiple times)
r1 <- apriori(Adult[1:1000])
r2 <- apriori(Adult[1001:2000])
rComb <- c(r1, r2)
rComb

## union of rules (a set with only unique rules: same as unique(rComb))
rUnion <- union(r1, r2)
rUnion

Description

Defines a method to compute confidence intervals for interest measures for association rules.

Usage

## S3 method for class 'rules'
confint(
  object,
  parm = "oddsRatio",
  level = 0.95,
  measure = NULL,
  side = c("two.sided", "lower", "upper"),
  method = NULL,
  replications = 1000,
  smoothCounts = 0,
  transactions = NULL,
  ...
)

Arguments

Details

This method creates a contingency table for each rule and then constructs a confidence interval for the specified measures.

Fast confidence interval approximations are currently available for the measures "support", "count", "confidence", "lift", "oddsRatio", and "phi". For all other measures, bootstrap sampling from a multinomial distribution is used.

Haldan-Anscombe correction (Haldan, 1940; Anscombe, 1956) to avoids issues with zero counts can be specified by smoothCounts = 0.5. Here .5 is added to each count in the contingency table.

Value

Returns a matrix with with one row for each rule and the two columns named "LL" and "UL" with the interval boundaries. The matrix has the following additional attributes:

Author(s)

Michael Hahsler

References

Wilson, E. B. (1927). "Probable inference, the law of succession, and statistical inference". Journal of the American Statistical Association, 22 (158): 209-212. doi:10.1080/01621459.1927.10502953

Clopper, C.; Pearson, E. S. (1934). "The use of confidence or fiducial limits illustrated in the case of the binomial". Biometrika, 26 (4): 404-413. doi:10.1093/biomet/26.4.404

Doob, J. L. (1935). "The Limiting Distributions of Certain Statistics". Annals of Mathematical Statistics, 6: 160-169. doi:10.1214/aoms/1177732594

Fisher, R.A. (1962). "Confidence limits for a cross-product ratio". Australian Journal of Statistics, 4, 41.

Woolf, B. (1955). "On estimating the relation between blood group and diseases". Annals of Human Genetics, 19, 251-253.

Haldane, J.B.S. (1940). "The mean and variance of the moments of chi-squared when used as a test of homogeneity, when expectations are small". Biometrika, 29, 133-134.

Anscombe, F.J. (1956). "On estimating binomial response relations". Biometrika, 43, 461-464.

See Also

Other interest measures: coverage(), interestMeasure(), is.redundant(), is.significant(), support()

Examples

data("Income")

# mine some rules with the consequent "language in home=english"
rules <- apriori(Income,
  parameter = list(support = 0.5),
  appearance = list(rhs = "language in home=english")
)

# calculate the confidence interval for the rules' odds ratios.
# note that we use Haldane-Anscombe correction (with smoothCounts = .5)
# to avoid issues with 0 counts in the contingency table.
ci <- confint(rules, "oddsRatio", smoothCounts = .5)
ci

# We add the odds ratio (with Haldane-Anscombe correction)
# and the confidence intervals to the quality slot of the rules.
quality(rules) <- cbind(
  quality(rules),
  oddsRatio = interestMeasure(rules, "oddsRatio", smoothCounts = .5),
  oddsRatio = ci
)

rules <- sort(rules, by = "oddsRatio")
inspect(rules)

# use confidence intervals for lift to find rules with a lift significantly larger then 1.
# We set the confidence level to 95%, create a one-sided interval and check
# if the interval does not cover 1 (i.e., the lower limit is larger than 1).
ci <- confint(rules, "lift", level = 0.95, side = "lower")
ci

inspect(rules[ci[, "LL"] > 1])

Description

Provides the generic function and a method to calculate the coverage (support of the left-hand-side) of rules.

Usage

coverage(x, transactions = NULL, reuse = TRUE)

## S4 method for signature 'rules'
coverage(x, transactions = NULL, reuse = TRUE)

Arguments

Details

Coverage (also called cover or LHS-support) is the support of the left-hand-side of the rule $X => Y$, i.e., $supp(X)$. It represents a measure of to how often the rule can be applied.

Coverage can be quickly calculated from the rule's quality measures (support and confidence) stored in the quality slot. If these values are not present, then the support of the LHS is counted using the data supplied in transactions.

Coverage is also one of the measures available via the function interestMeasure().

Value

A numeric vector of the same length as x containing the coverage values for the sets in x.

Author(s)

Michael Hahsler

See Also

Other interest measures: confint(), interestMeasure(), is.redundant(), is.significant(), support()

Examples

data("Income")

## find and some rules (we only use 5 rules here) and calculate coverage
rules <- apriori(Income)[1:5]
quality(rules) <- cbind(quality(rules), coverage = coverage(rules))

inspect(rules)

Description

Provides the generic function crossTable() and a method to cross-tabulate joint occurrences across all pairs of items.

Usage

crossTable(x, ...)

## S4 method for signature 'itemMatrix'
crossTable(
  x,
  measure = c("count", "support", "probability", "lift"),
  sort = FALSE
)

Arguments

Value

A symmetric matrix of n x n, where n is the number of items times in x. The matrix contains the co-occurrence counts between pairs of items.

Author(s)

Michael Hahsler

See Also

Other itemMatrix and transactions functions: abbreviate(), c(), duplicated(), extract, hierarchy, image(), inspect(), is.superset(), itemFrequency(), itemFrequencyPlot(), itemMatrix-class, match(), merge(), random.transactions(), sample(), sets, size(), supportingTransactions(), tidLists-class, transactions-class, unique()

Examples

data("Groceries")

ct <- crossTable(Groceries, sort = TRUE)
ct[1:5, 1:5]

sp <- crossTable(Groceries, measure = "support", sort = TRUE)
sp[1:5, 1:5]

lift <- crossTable(Groceries, measure = "lift", sort = TRUE)
lift[1:5, 1:5]

Description

Provides the generic function DATAFRAME() and the methods to create a data.frame representation from some arules objects. These methods are used for the coercion to a data.frame, but offer more control over the coercion process (item separators, etc.).

Usage

DATAFRAME(from, ...)

## S4 method for signature 'rules'
DATAFRAME(from, separate = TRUE, ...)

## S4 method for signature 'itemsets'
DATAFRAME(from, ...)

## S4 method for signature 'itemMatrix'
DATAFRAME(from, ...)

Arguments

Details

Using DATAFRAME() is equivalent to the standard coercion as(x, "data.frame"). However, for rules, the argument separate = TRUE will produce separate columns for the LHS and the RHS of the rule.

Furthermore, the arguments itemSep, setStart, setEnd (and ruleSep for separate = FALSE) will be passed on to the labels() method for the object specified in from.

Value

a data.frame.

Author(s)

Michael Hahsler

See Also

Other import/export: LIST(), pmml, read, write()

Examples

data(Adult)

DATAFRAME(head(Adult))
DATAFRAME(head(Adult), setStart = "", itemSep = " + ", setEnd = "")

rules <- apriori(Adult,
  parameter = list(supp = 0.5, conf = 0.9, target = "rules")
)
rules <- head(rules, by = "conf")


### default coercions (same as as(rules, "data.frame"))
DATAFRAME(rules)

DATAFRAME(rules, separate = TRUE)
DATAFRAME(rules, separate = TRUE, setStart = "", itemSep = " + ", setEnd = "")

Description

This function implements several basic unsupervised methods to convert a continuous variable into a categorical variable (factor) using different binning strategies. For convenience, a whole data.frame can be discretized (i.e., all numeric columns are discretized).

Usage

discretize(
  x,
  method = "frequency",
  breaks = 3,
  labels = NULL,
  include.lowest = TRUE,
  right = FALSE,
  dig.lab = 3,
  ordered_result = FALSE,
  infinity = FALSE,
  onlycuts = FALSE,
  categories = NULL,
  ...
)

discretizeDF(df, methods = NULL, default = NULL)

Arguments

Details

Discretize calculates breaks between intervals using various methods and then uses base::cut() to convert the numeric values into intervals represented as a factor.

Discretization may fail for several reasons. Some reasons are

• A variable contains only a single value. In this case, the variable should be dropped or directly converted into a factor with a single level (see factor).

• Some calculated breaks are not unique. This can happen for method frequency with very skewed data (e.g., a large portion of the values is 0). In this case, non-unique breaks are dropped with a warning. It would be probably better to look at the histogram of the data and decide on breaks for the method fixed.

discretize only implements unsupervised discretization. See arulesCBA::discretizeDF.supervised() in package arulesCBA for supervised discretization.

discretizeDF() applies discretization to each numeric column. Individual discretization parameters can be specified in the form: methods = list(column_name1 = list(method = ,...), column_name2 = list(...)). If no discretization method is specified for a column, then the discretization in default is applied (NULL invokes the default method in discretize()). The special method "none" can be specified to suppress discretization for a column.

Value

discretize() returns a factor representing the categorized continuous variable with attribute "discretized:breaks" indicating the used breaks or and "discretized:method" giving the used method. If onlycuts = TRUE is used, a vector with the calculated interval boundaries is returned.

discretizeDF() returns a discretized data.frame.

Author(s)

Michael Hahsler

See Also

base::cut(), arulesCBA::discretizeDF.supervised().

Other preprocessing: hierarchy, itemCoding, merge(), sample()

Examples

data(iris)
x <- iris[, 1]

### look at the distribution before discretizing
hist(x, breaks = 20, main = "Data")

def.par <- par(no.readonly = TRUE) # save default
layout(mat = rbind(1:2, 3:4))

### convert continuous variables into categories (there are 3 types of flowers)
### the default method is equal frequency
table(discretize(x, breaks = 3))
hist(x, breaks = 20, main = "Equal Frequency")
abline(v = discretize(x,
  breaks = 3,
  onlycuts = TRUE
), col = "red")
# Note: the frequencies are not exactly equal because of ties in the data

### equal interval width
table(discretize(x, method = "interval", breaks = 3))
hist(x, breaks = 20, main = "Equal Interval length")
abline(v = discretize(x,
  method = "interval", breaks = 3,
  onlycuts = TRUE
), col = "red")

### k-means clustering
table(discretize(x, method = "cluster", breaks = 3))
hist(x, breaks = 20, main = "K-Means")
abline(v = discretize(x,
  method = "cluster", breaks = 3,
  onlycuts = TRUE
), col = "red")

### user-specified (with labels)
table(discretize(x,
  method = "fixed", breaks = c(-Inf, 6, Inf),
  labels = c("small", "large")
))
hist(x, breaks = 20, main = "Fixed")
abline(v = discretize(x,
  method = "fixed", breaks = c(-Inf, 6, Inf),
  onlycuts = TRUE
), col = "red")

par(def.par) # reset to default

### prepare the iris data set for association rule mining
### use default discretization
irisDisc <- discretizeDF(iris)
head(irisDisc)

### discretize all numeric columns differently
irisDisc <- discretizeDF(iris, default = list(
  method = "interval", breaks = 2,
  labels = c("small", "large")
))
head(irisDisc)

### specify discretization for the petal columns and don't discretize the others
irisDisc <- discretizeDF(iris,
  methods = list(
    Petal.Length = list(
      method = "frequency", breaks = 3,
      labels = c("short", "medium", "long")
    ),
    Petal.Width = list(
      method = "frequency", breaks = 2,
      labels = c("narrow", "wide")
    )
  ),
  default = list(method = "none")
)
head(irisDisc)

### discretize new data using the same discretization scheme as the
###   data.frame supplied in methods. Note: NAs may occure if a new
###   value falls outside the range of values observed in the
###   originally discretized table (use argument infinity = TRUE in
###   discretize to prevent this case.)
discretizeDF(iris[sample(1:nrow(iris), 5), ], methods = irisDisc)

Description

Provides the generic function dissimilarity() and the methods to compute and returns distances for binary data in a matrix, transactions or associations which can be used for grouping and clustering. See Hahsler (2016) for an introduction to distance-based clustering of association rules.

Usage

dissimilarity(x, y = NULL, method = NULL, args = NULL, ...)

## S4 method for signature 'matrix'
dissimilarity(x, y = NULL, method = NULL, args = NULL)

## S4 method for signature 'itemMatrix'
dissimilarity(x, y = NULL, method = NULL, args = NULL, which = "transactions")

## S4 method for signature 'associations'
dissimilarity(x, y = NULL, method = NULL, args = NULL, which = "associations")

Arguments

Value

returns an object of class dist.

Author(s)

Michael Hahsler

References

Aggarwal, C.C., Cecilia Procopiuc, and Philip S. Yu. (2002) Finding localized associations in market basket data. IEEE Trans. on Knowledge and Data Engineering 14(1):51–62.

Dice, L. R. (1945) Measures of the amount of ecologic association between species. Ecology 26, pages 297–302.

Gupta, G., Strehl, A., and Ghosh, J. (1999) Distance based clustering of association rules. In Intelligent Engineering Systems Through Artificial Neural Networks (Proceedings of ANNIE 1999), pages 759-764. ASME Press.

Hahsler, M. (2016) Grouping association rules using lift. In C. Iyigun, R. Moghaddess, and A. Oztekin, editors, 11th INFORMS Workshop on Data Mining and Decision Analytics (DM-DA 2016).

Sneath, P. H. A. (1957) Some thoughts on bacterial classification. Journal of General Microbiology 17, pages 184–200.

Sokal, R. R. and Michener, C. D. (1958) A statistical method for evaluating systematic relationships. University of Kansas Science Bulletin 38, pages 1409–1438.

Toivonen, H., Klemettinen, M., Ronkainen, P., Hatonen, K. and Mannila H. (1995) Pruning and grouping discovered association rules. In Proceedings of KDD'95.

See Also

Other proximity classes and functions: affinity(), predict(), proximity-classes

Examples

## cluster items in Groceries with support > 5%
data("Groceries")

s <- Groceries[, itemFrequency(Groceries) > 0.05]
d_jaccard <- dissimilarity(s, which = "items")
plot(hclust(d_jaccard, method = "ward.D2"), main = "Dendrogram for items")

## cluster transactions for a sample of Adult
data("Adult")
s <- sample(Adult, 500)

##  calculate Jaccard distances and do hclust
d_jaccard <- dissimilarity(s)
hc <- hclust(d_jaccard, method = "ward.D2")
plot(hc, labels = FALSE, main = "Dendrogram for Transactions (Jaccard)")

## get 20 clusters and look at the difference of the item frequencies (bars)
## for the top 20 items) in cluster 1 compared to the data (line)
assign <- cutree(hc, 20)
itemFrequencyPlot(s[assign == 1], population = s, topN = 20)

## calculate affinity-based distances between transactions and do hclust
d_affinity <- dissimilarity(s, method = "affinity")
hc <- hclust(d_affinity, method = "ward.D2")
plot(hc, labels = FALSE, main = "Dendrogram for Transactions (Affinity)")

## cluster association rules
rules <- apriori(Adult, parameter = list(support = 0.3))
rules <- subset(rules, subset = lift > 2)

## use affinity to cluster rules
## Note: we need to supply the transactions (or affinities) from the
## dataset (sample).
d_affinity <- dissimilarity(rules,
  method = "affinity",
  args = list(transactions = s)
)
hc <- hclust(d_affinity, method = "ward.D2")
plot(hc, main = "Dendrogram for Rules (Affinity)")

## create 4 groups and inspect the rules in the first group.
assign <- cutree(hc, k = 3)
inspect(rules[assign == 1])

Description

Provides the generic function duplicated() and the methods to find duplicated elements in itemMatrix, associations and their subclasses.

Usage

duplicated(x, incomparables = FALSE, ...)

## S4 method for signature 'itemMatrix'
duplicated(x, incomparables = FALSE)

## S4 method for signature 'rules'
duplicated(x, incomparables = FALSE)

## S4 method for signature 'itemsets'
duplicated(x, incomparables = FALSE)

Arguments

Value

A logical vector indicating duplicated elements.

Author(s)

Michael Hahsler

See Also

Other associations functions: abbreviate(), associations-class, c(), extract, inspect(), is.closed(), is.generator(), is.maximal(), is.redundant(), is.significant(), is.superset(), itemsets-class, match(), rules-class, sample(), sets, size(), sort(), unique()

Other itemMatrix and transactions functions: abbreviate(), c(), crossTable(), extract, hierarchy, image(), inspect(), is.superset(), itemFrequency(), itemFrequencyPlot(), itemMatrix-class, match(), merge(), random.transactions(), sample(), sets, size(), supportingTransactions(), tidLists-class, transactions-class, unique()

Examples

data("Adult")

r1 <- apriori(Adult[1:1000], parameter = list(support = 0.5))
r2 <- apriori(Adult[1001:2000], parameter = list(support = 0.5))

## Note this creates a collection of rules from two sets of rules
r_comb <- c(r1, r2)
duplicated(r_comb)

Description

Mine frequent itemsets with the Eclat algorithm. This algorithm uses simple intersection operations for equivalence class clustering along with bottom-up lattice traversal.

Usage

eclat(data, parameter = NULL, control = NULL, ...)

Arguments

Details

Calls the C implementation of the Eclat algorithm by Christian Borgelt for mining frequent itemsets.

Eclat can also return the transaction IDs for each found itemset using tidLists = TRUE as a parameter and the result can be retrieved as a tidLists object with method tidLists() for class itemsets. Note that storing transaction ID lists is very memory intensive, creating transaction ID lists only works for minimum support values which create a relatively small number of itemsets. See also supportingTransactions().

ruleInduction() can be used to generate rules from the found itemsets.

A weighted version of ECLAT is available as function weclat(). This version can be used to perform weighted association rule mining (WARM).

Value

Returns an object of class itemsets.

Author(s)

Michael Hahsler and Bettina Gruen

References

Mohammed J. Zaki, Srinivasan Parthasarathy, Mitsunori Ogihara, and Wei Li. (1997) New algorithms for fast discovery of association rules. KDD'97: Proceedings of the Third International Conference on Knowledge Discovery and Data Mining, August 1997, Pages 283-286.

Christian Borgelt (2003) Efficient Implementations of Apriori and Eclat. Workshop of Frequent Item Set Mining Implementations (FIMI 2003, Melbourne, FL, USA).

ECLAT Implementation: https://borgelt.net/eclat.html

See Also

Other mining algorithms: APappearance-class, AScontrol-classes, ASparameter-classes, apriori(), fim4r(), ruleInduction(), weclat()

Examples

data("Adult")
## Mine itemsets with minimum support of 0.1 and 5 or less items
itemsets <- eclat(Adult,
  parameter = list(supp = 0.1, maxlen = 5)
)
itemsets

## Create rules from the frequent itemsets
rules <- ruleInduction(itemsets, confidence = .9)
rules

Description

The Epub data set contains the download history of documents from the electronic publication platform of the Vienna University of Economics and Business Administration. The data was recorded between Jan 2003 and Dec 2008.

Format

Object of class transactions with 15729 transactions and 936 items. Item labels are document IDs of the form "doc_11d". Session IDs and time stamps for transactions are also provided as transaction information.

Author(s)

Michael Hahsler

Source

Provided by Michael Hahsler from the custom information system ePub-WU (which has since been replaced by eprint).

Examples

data(Epub)
inspect(head(Epub))

Description

Methods for "[", i.e., extraction or subsetting for arules objects.

Usage

## S4 method for signature 'itemMatrix,ANY,ANY,ANY'
x[i, j, ..., drop = TRUE]

## S4 method for signature 'transactions,ANY,ANY,ANY'
x[i, j, ..., drop = TRUE]

## S4 method for signature 'tidLists,ANY,ANY,ANY'
x[i, j, ..., drop = TRUE]

## S4 method for signature 'rules,ANY,ANY,ANY'
x[i, j, ..., drop = TRUE]

## S4 method for signature 'itemsets,ANY,ANY,ANY'
x[i, j, ..., drop = TRUE]

Arguments

Author(s)

Michael Hahsler

See Also

Other associations functions: abbreviate(), associations-class, c(), duplicated(), inspect(), is.closed(), is.generator(), is.maximal(), is.redundant(), is.significant(), is.superset(), itemsets-class, match(), rules-class, sample(), sets, size(), sort(), unique()

Other itemMatrix and transactions functions: abbreviate(), c(), crossTable(), duplicated(), hierarchy, image(), inspect(), is.superset(), itemFrequency(), itemFrequencyPlot(), itemMatrix-class, match(), merge(), random.transactions(), sample(), sets, size(), supportingTransactions(), tidLists-class, transactions-class, unique()

Examples

data(Adult)
Adult

## select first 10 transactions
Adult[1:10]

## select first 10 items for first 100 transactions
Adult[1:100, 1:10]

## select the first 100 transactions for the items containing
## "income" or "age=Young" in their labels
Adult[1:100, c("income=small", "income=large", "age=Young")]

Description

Interfaces the algorithms implemented in fim4r. The algorithms include: Apriori, Eclat, FPgrowth, Carpenter, IsTa, RElim and SaM.

Usage

fim4r(
  transactions,
  method = NULL,
  target = "frequent",
  support = 0.1,
  confidence = 0.8,
  originalSupport = TRUE,
  appear = NULL,
  report = NULL,
  verbose = TRUE,
  ...
)

Arguments

Details

Installation: The package fim4r is not available via CRAN. If needed, the fim4r() function downloads and installs the current version of the package automatically. Your system needs to have build tools installed.

Build tools: You need to be able to install source packages. For Windows users this means that you need to install the RTools with a version matching your R version.

Additional Notes:

• Support and confidence are specified here in the range $[0,1]$. This is different from the use in fim4r package where supp and conf have the range $[0, 100]$. arules::fim4r() automatically converts support and confidence internally.

• fim4r methods also return the empty itemset while arules methods do not.

• See ? fim4r::fim4r for help on additional available arguments. This is only available after package fim4r is installed.

• Algorithm descriptions and references can be found on the fim4r web page in the References Section.

Value

An object of class itemsets or rules.

References

Christian Borgelt, fimi4r: Frequent Item Set Mining and Association Rule Induction for R. https://borgelt.net/fim4r.html

See Also

Other mining algorithms: APappearance-class, AScontrol-classes, ASparameter-classes, apriori(), eclat(), ruleInduction(), weclat()

Examples

## Not run: 
data(Adult)

# list available algorithms
fim4r()

# mine association rules with FPgrowth
r <- fim4r(Adult,
  method = "fpgrowth",
  target = "rules", supp = .7, conf = .8
)
r
inspect(head(r, by = "lift"))

# mine closed itemsets with Carpenter or IsTa
fim4r(Adult,
  method = "carpenter",
  target = "closed", supp = .7
)
fim4r(Adult,
  method = "ista",
  target = "closed", supp = .7
)

# mine frequent itemset of length 2 (zmin and zmax = 2)
freq_2 <- fim4r(Adult,
  method = "relim", target = "frequent", supp = .7,
  zmin = 2, zmax = 2
)
inspect(freq_2)

# mine maximal frequent itemsets
mfis <- fim4r(Adult, method = "sam", target = "maximal", supp = .7)
inspect(mfis)

# Examples for how to use item appearance with apriori, eclat,
#   fpgrowth in fim4r. We first mine all rules.
inspect(fim4r(Adult,
  method = "fpgrowth",
  target = "rules", supp = .8
))

# ignore item "capital-gain=None"
inspect(fim4r(Adult,
  method = "fpgrowth",
  target = "rules", supp = .8,
  appear = list(c("capital-gain=None"), c("-"))
))

# "capital-gain=None" cannot appear in consequent (antecedent only)
inspect(fim4r(Adult,
  method = "fpgrowth",
  target = "rules", supp = .8,
  appear = list(c("capital-gain=None"), c("a"))
))

# "capital-gain=None" cannot appear in the antecedent
inspect(fim4r(Adult,
  method = "fpgrowth",
  target = "rules", supp = .8,
  appear = list(c("capital-gain=None"), c("c"))
))

# restrict the consequent to the item "capital-gain=None".
# That is, "" = all items can only appear in the antecedent with the
# exception that "capital-gain=None" can only appear in the consequent.
inspect(fim4r(Adult,
  method = "fpgrowth",
  target = "rules", supp = .8,
  appear = list(c("", "capital-gain=None"), c("a", "c"))
))

## End(Not run)

Description

The Groceries data set contains 1 month (30 days) of real-world point-of-sale transaction data from a typical local grocery outlet. The data set contains 9835 transactions and the items are aggregated to 169 categories.

Format

Object of class transactions.

Details

If you use this data set in your paper, please cite to the paper in the References Section.

Author(s)

Michael Hahsler

Source

The data set is provided for arules by Michael Hahsler, Kurt Hornik and Thomas Reutterer.

References

Michael Hahsler, Kurt Hornik, and Thomas Reutterer (2006) Implications of probabilistic data modeling for mining association rules. In M. Spiliopoulou, R. Kruse, C. Borgelt, A. Nuernberger, and W. Gaul, editors, From Data and Information Analysis to Knowledge Engineering, Studies in Classification, Data Analysis, and Knowledge Organization, pages 598–605. Springer-Verlag.

Description

Functions to use item hierarchies to aggregate items at different group levels, to perform multi-level transaction analysis.

Usage

addAggregate(x, by, postfix = "*")

filterAggregate(x)

aggregate(x, ...)

## S4 method for signature 'itemMatrix'
aggregate(x, by)

## S4 method for signature 'itemsets'
aggregate(x, by)

## S4 method for signature 'rules'
aggregate(x, by)

Arguments

Details

Often an item hierarchy is available for transactions used for association rule mining. For example in a supermarket dataset items like "bread" and "beagle" might belong to the item group (category) "baked goods."

Transactions can store item hierarchies as additional columns in the itemInfo data.frame ("labels" cannot be used since it is reserved for the item labels).

Aggregation: To perform analysis at a group level of the item hierarchy, aggregate() produces a new object with items aggregated to a given group level. A group-level item is present if one or more of the items in the group are present in the original object. If rules are aggregated, and the aggregation would lead to the same aggregated group item in the lhs and in the rhs, then that group item is removed from the lhs. Rules or itemsets, which are not unique after the aggregation, are also removed. Note also that the quality measures are not applicable to the new rules and thus are removed. If these measures are required, then aggregate the transactions before mining rules.

Multi-level analysis: To analyze relationships between individual items and item groups at the same time, addAggregate() can be used to create a new transactions object which contains both, the original items and group-level items (marked with a given postfix). In association rule mining, all items are handled the same, which means that we will produce a large number of rules of the type:

⁠item A => group of item A⁠

with a confidence of 1. This will also happen if you mine itemsets. filterAggregate() can be used to filter these spurious rules or itemsets.

Value

aggregate() returns an object of the same class as x encoded with a number of items equal to the number of unique values in by. Note that for associations (itemsets and rules) the number of associations in the returned set will most likely be reduced since several associations might map to the same aggregated association and aggregate returns a unique set. If several associations map to a single aggregated association then the quality measures of one of the original associations is randomly chosen.

addAggregate() returns a new transactions object with the original items and the group-items added. filterAggregateRules() returns a new rules object with the spurious rules remove.

Author(s)

Michael Hahsler

See Also

Other preprocessing: discretize(), itemCoding, merge(), sample()

Other itemMatrix and transactions functions: abbreviate(), c(), crossTable(), duplicated(), extract, image(), inspect(), is.superset(), itemFrequency(), itemFrequencyPlot(), itemMatrix-class, match(), merge(), random.transactions(), sample(), sets, size(), supportingTransactions(), tidLists-class, transactions-class, unique()

Examples

data("Groceries")
Groceries

## Groceries contains a hierarchy stored in itemInfo
head(itemInfo(Groceries))

## Example 1: Aggregate items using an existing hierarchy stored in itemInfo.
## We aggregate to level2 stored in Groceries. All items with the same level2 label
## will become a single item with that name.
## Note that the number of items is therefore reduced to 55
Groceries_level2 <- aggregate(Groceries, by = "level2")
Groceries_level2
head(itemInfo(Groceries_level2)) ## labels are alphabetically sorted!


## compare original and aggregated transactions
inspect(head(Groceries, 2))
inspect(head(Groceries_level2, 2))

## Example 2: Aggregate using a character vector.
## We create here labels manually to organize items by their first letter.
mylevels <- toupper(substr(itemLabels(Groceries), 1, 1))
head(mylevels)

Groceries_alpha <- aggregate(Groceries, by = mylevels)
Groceries_alpha
inspect(head(Groceries_alpha, 2))

## Example 3: Aggregate rules
## Note: You could also directly mine rules from aggregated transactions to
## get support, lift and support
rules <- apriori(Groceries, parameter = list(supp = 0.005, conf = 0.5))
rules
inspect(rules[1])

rules_level2 <- aggregate(rules, by = "level2")
inspect(rules_level2[1])

## Example 4: Mine multi-level rules.
## (1) Add aggregate items. These items will have labels ending with a *
Groceries_multilevel <- addAggregate(Groceries, "level2")
summary(Groceries_multilevel)
inspect(head(Groceries_multilevel))

rules <- apriori(Groceries_multilevel,
  parameter = list(support = 0.01, conf = .9)
)
inspect(head(rules, by = "lift"))
## Note that this contains many spurious rules of type 'item X => aggregate of item X'
## with a confidence of 1 and high lift. We can filter spurious rules resulting from
## the aggregation
rules <- filterAggregate(rules)
inspect(head(rules, by = "lift"))

Description

Compute the hub transaction weights for a collection of transactions using the HITS (hubs and authorities) algorithm.

Usage

hits(
  data,
  iter = 16L,
  tol = NULL,
  type = c("normed", "relative", "absolute"),
  verbose = FALSE
)

Arguments

Details

Model a collection of transactions as a bipartite graph of hubs (transactions) and authorities (items) with unit arcs and free node weights. That is, a transaction weight is the sum of the (normalized) weights of the items and vice versa. The weights are estimated by iterating the model to a steady-state using a builtin convergence tolerance of FLT_EPSILON for (the change in) the norm of the vector of authorities.

Value

A numeric vector with transaction weights for data.

Author(s)

Christian Buchta

References

K. Sun and F. Bai (2008). Mining Weighted Association Rules without Preassigned Weights. IEEE Transactions on Knowledge and Data Engineering, 4 (30), 489–495.

See Also

Other weighted association mining functions: SunBai, weclat()

Examples

data(SunBai)

## calculate transaction weigths
w <- hits(SunBai)
w

## add transaction weight to the dataset
transactionInfo(SunBai)[["weight"]] <- w
transactionInfo(SunBai)

## calulate regular item frequencies
itemFrequency(SunBai, weighted = FALSE)

## calulate weighted item frequencies
itemFrequency(SunBai, weighted = TRUE)

Description

Provides image() methods to generate level plots to visually inspect binary incidence matrices, i.e., objects based on itemMatrix (e.g., transactions, tidLists, items in itemsets or rhs/lhs in rules). These plots can be used to identify problems in a data set (e.g., recording problems with some transactions containing all items).

Usage

## S4 method for signature 'itemMatrix'
image(x, xlab = "Items (Columns)", ylab = "Elements (Rows)", ...)

## S4 method for signature 'transactions'
image(x, xlab = "Items (Columns)", ylab = "Transactions (Rows)", ...)

## S4 method for signature 'tidLists'
image(x, xlab = "Transactions (Columns)", ylab = "Items/itemsets (Rows)", ...)

Arguments

Author(s)

Michael Hahsler

See Also

image() in package Matrix

Other itemMatrix and transactions functions: abbreviate(), c(), crossTable(), duplicated(), extract, hierarchy, inspect(), is.superset(), itemFrequency(), itemFrequencyPlot(), itemMatrix-class, match(), merge(), random.transactions(), sample(), sets, size(), supportingTransactions(), tidLists-class, transactions-class, unique()

Examples

data("Epub")

## in this data set we can see that not all
## items were available from the beginning.
image(Epub[1:1000])

Description

Survey example data from the book The Elements of Statistical Learning.

Format

The data is provided in two formats:

1. Income is an object of class transactions with 6876 transactions (complete cases) and 50 items. See below for details.

2. IncomeESL is a data frame with 8993 observations on the following 14 variables:

income

an ordered factor with levels ⁠[0,10)⁠ < ⁠[10,15)⁠ < ⁠[15,20)⁠ < ⁠[20,25)⁠ < ⁠[25,30)⁠ < ⁠[30,40)⁠ < ⁠[40,50)⁠ < ⁠[50,75)⁠ < ⁠75+⁠

sex

a factor with levels male female

marital status

a factor with levels married cohabitation divorced widowed single

age

an ordered factor with levels 14-17 < 18-24 < 25-34 < 35-44 < 45-54 < 55-64 < ⁠65+⁠

education

an ordered factor with levels grade <9 < ⁠grades 9-11⁠ < ⁠high school graduate⁠ < college (1-3 years) < ⁠college graduate⁠ < ⁠graduate study⁠

occupation

a factor with levels professional/managerial sales laborer clerical/service homemaker student military retired unemployed

years in bay area

an ordered factor with levels ⁠<1⁠ < 1-3 < 4-6 < 7-10 < ⁠>10⁠

dual incomes

a factor with levels ⁠not married⁠ yes no

number in household

an ordered factor with levels 1 < 2 < 3 < 4 < 5 < 6 < 7 < 8 < ⁠9+⁠

number of children

an ordered factor with levels 0 < 1 < 2 < 3 < 4 < 5 < 6 < 7 < 8 < ⁠9+⁠

householder status

a factor with levels own rent ⁠live with parents/family⁠

type of home

a factor with levels house condominium apartment mobile Home other

ethnic classification

a factor with levels ⁠american indian⁠ asian black ⁠east indian⁠ hispanic ⁠pacific islander⁠ white other

language in home

a factor with levels english spanish other

Details

The IncomeESL data set originates from an example in the book The Elements of Statistical Learning (see Section source). The data set is an extract from this survey. It consists of 8993 instances (obtained from the original data set with 9409 instances, by removing those observations with the annual income missing) with 14 demographic attributes. The data set is a good mixture of categorical and continuous variables with a lot of missing data. This is characteristic of data mining applications. The Income data set contains the data already prepared and coerced to transactions.

To create transactions for Income, the original data frame in IncomeESL is prepared in a similar way as described in The Elements of Statistical Learning. We removed cases with missing values and cut each ordinal variable (age, education, income, years in bay area, number in household, and number of children) at its median into two values (see Section examples).

Author(s)

Michael Hahsler

Source

Impact Resources, Inc., Columbus, OH (1987).

Obtained from the web site of the book: Hastie, T., Tibshirani, R. & Friedman, J. (2001) The Elements of Statistical Learning. Springer-Verlag.

Examples

data("IncomeESL")
IncomeESL[1:3, ]

## remove incomplete cases
IncomeESL <- IncomeESL[complete.cases(IncomeESL), ]

## preparing the data set
IncomeESL[["income"]] <- factor((as.numeric(IncomeESL[["income"]]) > 6) + 1,
  levels = 1:2, labels = c("$0-$40,000", "$40,000+")
)

IncomeESL[["age"]] <- factor((as.numeric(IncomeESL[["age"]]) > 3) + 1,
  levels = 1:2, labels = c("14-34", "35+")
)

IncomeESL[["education"]] <- factor((as.numeric(IncomeESL[["education"]]) > 4) + 1,
  levels = 1:2, labels = c("no college graduate", "college graduate")
)

IncomeESL[["years in bay area"]] <- factor(
  (as.numeric(IncomeESL[["years in bay area"]]) > 4) + 1,
  levels = 1:2, labels = c("1-9", "10+")
)

IncomeESL[["number in household"]] <- factor(
  (as.numeric(IncomeESL[["number in household"]]) > 3) + 1,
  levels = 1:2, labels = c("1", "2+")
)

IncomeESL[["number of children"]] <- factor(
  (as.numeric(IncomeESL[["number of children"]]) > 1) + 0,
  levels = 0:1, labels = c("0", "1+")
)

##  creating transactions
Income <- transactions(IncomeESL)
Income

Description

Provides the generic function inspect() and methods to display associations and transactions plus additional information formatted for online inspection.

Usage

inspect(x, ...)

## S4 method for signature 'itemsets'
inspect(x, itemSep = ", ", setStart = "{", setEnd = "}", linebreak = NULL, ...)

## S4 method for signature 'rules'
inspect(
  x,
  itemSep = ", ",
  setStart = "{",
  setEnd = "}",
  ruleSep = "=>",
  linebreak = NULL,
  ...
)

## S4 method for signature 'transactions'
inspect(x, itemSep = ", ", setStart = "{", setEnd = "}", linebreak = NULL, ...)

## S4 method for signature 'itemMatrix'
inspect(x, itemSep = ", ", setStart = "{", setEnd = "}", linebreak = NULL, ...)

## S4 method for signature 'tidLists'
inspect(x, ...)

Arguments

Details

inspect() prints the results directly. If you need to create a data.frame with a human readable version, then you can use DATAFRAME().

Value

Nothing is returned (see the Details Section).

Author(s)

Michael Hahsler and Kurt Hornik

See Also

Other associations functions: abbreviate(), associations-class, c(), duplicated(), extract, is.closed(), is.generator(), is.maximal(), is.redundant(), is.significant(), is.superset(), itemsets-class, match(), rules-class, sample(), sets, size(), sort(), unique()

Other itemMatrix and transactions functions: abbreviate(), c(), crossTable(), duplicated(), extract, hierarchy, image(), is.superset(), itemFrequency(), itemFrequencyPlot(), itemMatrix-class, match(), merge(), random.transactions(), sample(), sets, size(), supportingTransactions(), tidLists-class, transactions-class, unique()

Examples

data("Adult")
rules <- apriori(Adult)

## display some rules
inspect(rules[1000:1001])
inspect(rules[1000:1001],
  ruleSep = "~~>", itemSep = " + ", setStart = "", setEnd = "",
  linebreak = FALSE
)

## to get rules in readable format, use coercion or DATAFRAME with additional parameters.
as(rules[1000:1001], "data.frame")
DATAFRAME(rules[1000:1001])
DATAFRAME(rules[1000:1001], separate = TRUE, setStart = "", setEnd = "")

Description

Provides the generic function interestMeasure() and the methods to calculate various additional interest measures for existing sets of itemsets or rules.

Usage

interestMeasure(x, measure, transactions = NULL, reuse = TRUE, ...)

## S4 method for signature 'itemsets'
interestMeasure(x, measure, transactions = NULL, reuse = TRUE, ...)

## S4 method for signature 'rules'
interestMeasure(x, measure, transactions = NULL, reuse = TRUE, ...)

Arguments

Details

A searchable list of definitions, equations and references for all available interest measures can be found at https://mhahsler.github.io/arules/docs/measures. The descriptions are also linked in the list below.

The following measures are implemented for itemsets:

• "support": Support.

• "count": Support Count.

• "allConfidence": All-Confidence.

• "crossSupportRatio": Cross-Support Ratio.

• "lift": Lift.

The following measures are implemented for rules:

• "support": Support.

• "confidence": Confidence.

• "lift": Lift.

• "count": Support Count.

• "addedValue": Added Value.

• "boost": Confidence Boost.

• "casualConfidence": Casual Confidence.

• "casualSupport": Casual Support.

• "centeredConfidence": Centered Confidence.

• "certainty": Certainty Factor.

• "chiSquared": Chi-Squared. Additional parameters are: significance = TRUE returns the p-value of the test for independence instead of the chi-squared statistic. For p-values, substitution effects (the occurrence of one item makes the occurrence of another item less likely) can be tested using the parameter complements = FALSE. Note: Correction for multiple comparisons can be done using stats::p.adjust().

• "collectiveStrength": Collective Strength.

• "confirmedConfidence": Descriptive Confirmed Confidence.

• "conviction": Conviction.

• "cosine": Cosine.

• "counterexample": Example and Counter-Example Rate.

• "coverage": Coverage.

• "doc": Difference of Confidence.

• "fishersExactTest": Fisher's Exact Test. By default complementary effects are mined, substitutes can be found by using the parameter complements = FALSE. Note that Fisher's exact test is equal to hyper-confidence with significance = TRUE. Correction for multiple comparisons can be done using stats::p.adjust().

• "gini": Gini Index.

• "hyperConfidence": Hyper-Confidence. Reports the confidence level by default and the significance level if significance = TRUE is used. By default complementary effects are mined, substitutes (too low co-occurrence counts) can be found by using the parameter complements = FALSE.

• "hyperLift": Hyper-Lift. The used quantile can be changed using parameter level (default: level = 0.99).

• "imbalance": Imbalance Ratio.

• "implicationIndex": Implication Index.

• "importance": Importance.

• "improvement": Improvement. The additional parameter improvementMeasure (default: 'confidence') can be used to specify the measure used for the improvement calculation. See Generalized improvement.

• "jaccard": Jaccard Coefficient.

• "jMeasure": J-Measure.

• "kappa": Kappa.

• "kulczynski": Kulczynski.

• "lambda": Lambda.

• "laplace": Laplace Corrected Confidence. Parameter k can be used to specify the number of classes (default is 2).

• "leastContradiction": Least Contradiction.

• "lerman": Lerman Similarity.

• "leverage": Leverage.

• "LIC": Lift Increase. The additional parameter improvementMeasure (default: 'lift') can be used to specify the measure used for the increase calculation. See Generalized increase ratio.

• "maxconfidence": MaxConfidence.

• "mutualInformation": Mutual Information.

• "oddsRatio": Odds Ratio.

• "phi": Phi Correlation Coefficient.

• "ralambondrainy": Ralambondrainy.

• "relativeRisk": Relative Risk.

• "rhsSupport": Right-Hand-Side Support.

• "RLD": Relative Linkage Disequilibrium.

• "rulePowerFactor": Rule Power Factor.

• "sebag": Sebag-Schoenauer.

• "stdLift": Standardized Lift.

• "table": Contingency Table. Returns the four counts for the contingency table. The entries are labeled n11, n01, n10, and n00 (the first subscript is for X and the second is for Y; 1 indicated presence and 0 indicates absence). If several measures are specified, then the counts have the prefix table.

• "varyingLiaison": Varying Rates Liaison.

• "yuleQ": Yule's Q.

• "yuleY": Yule's Y.

Value

If only one measure is used, the function returns a numeric vector containing the values of the interest measure for each association in the set of associations x.

If more than one measures are specified, the result is a data.frame containing the different measures for each association as columns.

NA is returned for rules/itemsets for which a certain measure is not defined.

Author(s)

Michael Hahsler

References

Hahsler, Michael (2015). A Probabilistic Comparison of Commonly Used Interest Measures for Association Rules, 2015, URL: https://mhahsler.github.io/arules/docs/measures.

Haldane, J.B.S. (1940). "The mean and variance of the moments of chi-squared when used as a test of homogeneity, when expectations are small". Biometrika, 29, 133-134.

Anscombe, F.J. (1956). "On estimating binomial response relations". Biometrika, 43, 461-464.

See Also

itemsets, rules

Other interest measures: confint(), coverage(), is.redundant(), is.significant(), support()

Examples

data("Income")
rules <- apriori(Income)

## calculate a single measure and add it to the quality slot
quality(rules) <- cbind(quality(rules),
  hyperConfidence = interestMeasure(rules,
    measure = "hyperConfidence",
    transactions = Income
  )
)

inspect(head(rules, by = "hyperConfidence"))

## calculate several measures
m <- interestMeasure(rules, c("confidence", "oddsRatio", "leverage"),
  transactions = Income
)
inspect(head(rules))
head(m)

## calculate all available measures for the first 5 rules and show them as a
## table with the measures as rows
t(interestMeasure(head(rules, 5), transactions = Income))

## calculate measures on a different set of transactions (I use a sample here)
## Note: reuse = TRUE (default) would just return the stored support on the
## 	data set used for mining
newTrans <- sample(Income, 100)
m2 <- interestMeasure(rules, "support", transactions = newTrans, reuse = FALSE)
head(m2)

## calculate all available measures for the 5 frequent itemsets with highest support
its <- apriori(Income, parameter = list(target = "frequent itemsets"))
its <- head(its, 5, by = "support")
inspect(its)

interestMeasure(its, transactions = Income)

Description

Provides the generic function and the method is.closed() for finding closed itemsets. Closed itemsets are used as a concise representation of frequent itemsets. The closure of an itemset is its largest proper superset which has the same support (is contained in exactly the same transactions). An itemset is closed, if it is its own closure (Pasquier et al. 1999).

Usage

is.closed(x)

## S4 method for signature 'itemsets'
is.closed(x)

Arguments

Details

Closed frequent itemsets can also be mined directly using apriori() or eclat() with target "closed frequent itemsets".

Value

a logical vector with the same length as x indicating for each element in x if it is a closed itemset.

Author(s)

Michael Hahsler

References

Nicolas Pasquier, Yves Bastide, Rafik Taouil, and Lotfi Lakhal (1999). Discovering frequent closed itemsets for association rules. In Proceeding of the 7th International Conference on Database Theory, Lecture Notes In Computer Science (LNCS 1540), pages 398–416. Springer, 1999.

See Also

Other postprocessing: is.generator(), is.maximal(), is.redundant(), is.significant(), is.superset()

Other associations functions: abbreviate(), associations-class, c(), duplicated(), extract, inspect(), is.generator(), is.maximal(), is.redundant(), is.significant(), is.superset(), itemsets-class, match(), rules-class, sample(), sets, size(), sort(), unique()

Description

Provides the generic function and the method 'is.generator() for finding generator itemsets. Generators are part of concise representations for frequent itemsets. A generator in a set of itemsets is an itemset that has no subset with the same support (Liu et al, 2008). Note that the empty set is by definition a generator, but it is typically not stored in the itemsets in arules.

Usage

is.generator(x)

## S4 method for signature 'itemsets'
is.generator(x)

Arguments

Value

a logical vector with the same length as x indicating for each element in x if it is a generator itemset.

Author(s)

Michael Hahsler

References

Yves Bastide, Niolas Pasquier, Rafik Taouil, Gerd Stumme, Lotfi Lakhal (2000). Mining Minimal Non-redundant Association Rules Using Frequent Closed Itemsets. In International Conference on Computational Logic, Lecture Notes in Computer Science (LNCS 1861). pages 972–986. doi:10.1007/3-540-44957-4_65

Guimei Liu, Jinyan Li, Limsoon Wong (2008). A new concise representation of frequent itemsets using generators and a positive border. Knowledge and Information Systems 17(1):35-56. doi:10.1007/s10115-007-0111-5

See Also

Other postprocessing: is.closed(), is.maximal(), is.redundant(), is.significant(), is.superset()

Other associations functions: abbreviate(), associations-class, c(), duplicated(), extract, inspect(), is.closed(), is.maximal(), is.redundant(), is.significant(), is.superset(), itemsets-class, match(), rules-class, sample(), sets, size(), sort(), unique()

Examples

# Example from Liu et al (2008)
trans_list <- list(
  t1 = c("a", "b", "c"),
  t2 = c("a", "b", "c", "d"),
  t3 = c("a", "d"),
  t4 = c("a", "c")
)

trans <- transactions(trans_list)
its <- apriori(trans, support = 1 / 4, target = "frequent itemsets")

is.generator(its)

Description

Provides the generic function is.maximal() and methods for finding maximal itemsets. Maximal frequent itemsets are used as a concise representation of frequent itemsets. An itemset is maximal in a set if no proper superset of the itemset is contained in the set (Zaki et al., 1997).

Usage

is.maximal(x, ...)

## S4 method for signature 'itemMatrix'
is.maximal(x)

## S4 method for signature 'itemsets'
is.maximal(x)

## S4 method for signature 'rules'
is.maximal(x)

Arguments

Details

Maximally frequent itemsets can also be mined directly using apriori() or eclat() with target "maximally frequent itemsets".

We define here maximal rules, as the rules generated by maximal itemsets.

Value

a logical vector with the same length as x indicating for each element in x if it is a maximal itemset.

Author(s)

Michael Hahsler

References

Mohammed J. Zaki, Srinivasan Parthasarathy, Mitsunori Ogihara, and Wei Li (1997). New algorithms for fast discovery of association rules. Technical Report 651, Computer Science Department, University of Rochester, Rochester, NY 14627.

See Also

Other postprocessing: is.closed(), is.generator(), is.redundant(), is.significant(), is.superset()

Other associations functions: abbreviate(), associations-class, c(), duplicated(), extract, inspect(), is.closed(), is.generator(), is.redundant(), is.significant(), is.superset(), itemsets-class, match(), rules-class, sample(), sets, size(), sort(), unique()

Description

Provides the generic function is.redundant() and the method to find redundant rules based on any interest measure.

Usage

is.redundant(x, ...)

## S4 method for signature 'rules'
is.redundant(
  x,
  measure = "confidence",
  confint = FALSE,
  level = 0.95,
  smoothCounts = 1,
  ...
)

Arguments

Details

Simple improvement-based redundancy: (confint = FALSE) A rule can be defined as redundant if a more general rules with the same or a higher confidence exists. That is, a more specific rule is redundant if it is only equally or even less predictive than a more general rule. A rule is more general if it has the same RHS but one or more items removed from the LHS. Formally, a rule $X \Rightarrow Y$ is redundant if

$\exists X' \subset X \quad conf(X' \Rightarrow Y) \ge conf(X \Rightarrow Y).$

This is equivalent to a negative or zero improvement as defined by Bayardo et al. (2000).

The idea of improvement can be extended other measures besides confidence. Any other measure available for function interestMeasure() (e.g., lift or the odds ratio) can be specified in measure.

Confidence interval-based redundancy: (confint = TRUE) Li et al (2014) propose to use the confidence interval (CI) of the odds ratio (OR) of rules to define redundancy. A more specific rule is redundant if it does not provide a significantly higher OR than any more general rule. Using confidence intervals as error bounds, a more specific rule is defined as redundant if its OR CI overlaps with the CI of any more general rule. This type of redundancy detection removes more rules than improvement since it takes differences in counts due to randomness in the dataset into account.

The odds ratio and the CI are based on counts which can be zero and which leads to numerical problems. In addition to the method described by Li et al (2014), we use additive smoothing (Laplace smoothing) to alleviate this problem. The default setting adds 1 to each count (see confint()). A different pseudocount (smoothing parameter) can be defined using the additional parameter smoothCounts. Smoothing can be disabled using smoothCounts = 0.

Warning: This approach of redundancy checking is flawed since rules with non-overlapping CIs are non-redundant (same result as for a 2-sample t-test), but overlapping CIs do not automatically mean that there is no significant difference between the two measures which leads to a higher type II error. At the same time, multiple comparisons are performed leading to an increased type I error. If we are more worried about missing important rules, then the type II error is more concerning.

Confidence interval-based redundancy checks can also be used for other measures with a confidence interval like confidence (see confint()).

Value

returns a logical vector indicating which rules are redundant.

Author(s)

Michael Hahsler and Christian Buchta

References

Bayardo, R. , R. Agrawal, and D. Gunopulos (2000). Constraint-based rule mining in large, dense databases. Data Mining and Knowledge Discovery, 4(2/3):217–240.

Li, J., Jixue Liu, Hannu Toivonen, Kenji Satou, Youqiang Sun, and Bingyu Sun (2014). Discovering statistically non-redundant subgroups. Knowledge-Based Systems. 67 (September, 2014), 315–327. doi:10.1016/j.knosys.2014.04.030

See Also

Other postprocessing: is.closed(), is.generator(), is.maximal(), is.significant(), is.superset()

Other associations functions: abbreviate(), associations-class, c(), duplicated(), extract, inspect(), is.closed(), is.generator(), is.maximal(), is.significant(), is.superset(), itemsets-class, match(), rules-class, sample(), sets, size(), sort(), unique()

Other interest measures: confint(), coverage(), interestMeasure(), is.significant(), support()

Examples

data("Income")

## mine some rules with the consequent "language in home=english"
rules <- apriori(Income,
  parameter = list(support = 0.5),
  appearance = list(rhs = "language in home=english")
)

## for better comparison we add Bayado's improvement and sort by improvement
quality(rules)$improvement <- interestMeasure(rules, measure = "improvement")
rules <- sort(rules, by = "improvement")
inspect(rules)
is.redundant(rules)

## find non-redundant rules using improvement of confidence
## Note: a few rules have a very small improvement over the rule {} => {language in home=english}
rules_non_redundant <- rules[!is.redundant(rules)]
inspect(rules_non_redundant)

## use non-overlapping confidence intervals for the confidence measure instead
## Note: fewer rules have a significantly higher confidence
inspect(rules[!is.redundant(rules,
  measure = "confidence",
  confint = TRUE, level = 0.95
)])

## find non-redundant rules using improvement of the odds ratio.
quality(rules)$oddsRatio <- interestMeasure(rules, measure = "oddsRatio", smoothCounts = .5)
inspect(rules[!is.redundant(rules, measure = "oddsRatio")])

## use the confidence interval for the odds ratio.
## We see that no rule has a significantly better odds ratio than the most general rule.
inspect(rules[!is.redundant(rules,
  measure = "oddsRatio",
  confint = TRUE, level = 0.95
)])

##  use the confidence interval for lift
inspect(rules[!is.redundant(rules,
  measure = "lift",
  confint = TRUE, level = 0.95
)])

Description

Provides the generic functions is.significant() and the method to find significant rules.

Usage

is.significant(x, ...)

## S4 method for signature 'rules'
is.significant(
  x,
  transactions = NULL,
  method = "fisher",
  alpha = 0.01,
  adjust = "none",
  reuse = TRUE,
  ...
)

Arguments

Details

The implementation for association rules uses Fisher's exact test with correction for multiple comparisons to test the null hypothesis that the LHS and the RHS of the rule are independent. Significant rules have a p-value less then the specified significance level alpha (the null hypothesis of independence is rejected). See Hahsler and Hornik (2007) for details.

Value

returns a logical vector indicating which rules are significant.

Author(s)

Michael Hahsler

References

Hahsler, Michael and Kurt Hornik (2007). New probabilistic interest measures for association rules. Intelligent Data Analysis, 11(5):437–455. doi:10.3233/IDA-2007-11502

See Also

stats::p.adjust()

Other interest measures: confint(), coverage(), interestMeasure(), is.redundant(), support()

Other postprocessing: is.closed(), is.generator(), is.maximal(), is.redundant(), is.superset()

Other associations functions: abbreviate(), associations-class, c(), duplicated(), extract, inspect(), is.closed(), is.generator(), is.maximal(), is.redundant(), is.superset(), itemsets-class, match(), rules-class, sample(), sets, size(), sort(), unique()

Examples

data("Income")
rules <- apriori(Income, support = 0.2)
is.significant(rules)

rules[is.significant(rules)]

# Adjust P-values for multiple comparisons
rules[is.significant(rules, adjust = "bonferroni")]

Description

Provides the generic functions is.subset() and is.superset(), and the methods for finding super or subsets in associations and itemMatrix objects.

Usage

is.superset(x, y = NULL, proper = FALSE, sparse = TRUE, ...)

is.subset(x, y = NULL, proper = FALSE, sparse = TRUE, ...)

## S4 method for signature 'itemMatrix'
is.superset(x, y = NULL, proper = FALSE, sparse = TRUE)

## S4 method for signature 'associations'
is.superset(x, y = NULL, proper = FALSE, sparse = TRUE)

## S4 method for signature 'itemMatrix'
is.subset(x, y = NULL, proper = FALSE, sparse = TRUE)

## S4 method for signature 'associations'
is.subset(x, y = NULL, proper = FALSE, sparse = TRUE)

Arguments

Details

Determines for each element in x which elements in y are supersets or subsets. Note that the method can be very slow and memory intensive if x and/or y are very dense (contain many items).

For rules, the union of lhs and rhs is used a the set of items.

Value

returns a logical matrix or a sparse Matrix::ngCMatrix with length(x) rows and length(y) columns. Each logical row vector represents which elements in y are supersets (subsets) of the corresponding element in x. If either x or y have length zero, NULL is returned instead of a matrix.

Author(s)

Michael Hahsler and Ian Johnson

See Also

Other postprocessing: is.closed(), is.generator(), is.maximal(), is.redundant(), is.significant()

Other associations functions: abbreviate(), associations-class, c(), duplicated(), extract, inspect(), is.closed(), is.generator(), is.maximal(), is.redundant(), is.significant(), itemsets-class, match(), rules-class, sample(), sets, size(), sort(), unique()

Other itemMatrix and transactions functions: abbreviate(), c(), crossTable(), duplicated(), extract, hierarchy, image(), inspect(), itemFrequency(), itemFrequencyPlot(), itemMatrix-class, match(), merge(), random.transactions(), sample(), sets, size(), supportingTransactions(), tidLists-class, transactions-class, unique()

Examples

data("Adult")
set <- eclat(Adult, parameter = list(supp = 0.8))

### find the supersets of each itemset in set
is.superset(set, set)
is.superset(set, set, sparse = FALSE)

Description

The order in which items are stored in an itemMatrix is called the item coding. The following generic functions and methods are used to translate between the representation in the itemMatrix format (used in transactions, rules and itemsets), item labels and numeric item IDs (i.e., the column numbers in the itemMatrix representation).

Usage

decode(x, ...)

## S4 method for signature 'numeric'
decode(x, itemLabels)

## S4 method for signature 'list'
decode(x, itemLabels)

encode(x, ...)

## S4 method for signature 'character'
encode(x, itemLabels, itemMatrix = TRUE)

## S4 method for signature 'numeric'
encode(x, itemLabels, itemMatrix = TRUE)

## S4 method for signature 'list'
encode(x, itemLabels, itemMatrix = TRUE)

recode(x, ...)

## S4 method for signature 'itemMatrix'
recode(x, itemLabels = NULL, match = NULL)

## S4 method for signature 'itemsets'
recode(x, itemLabels = NULL, match = NULL)

## S4 method for signature 'rules'
recode(x, itemLabels = NULL, match = NULL)

compatible(x, y)

## S4 method for signature 'itemMatrix'
compatible(x, y)

## S4 method for signature 'associations'
compatible(x, y)

Arguments

Details

Item coding compatibility: When working with several datasets or different subsets of the same dataset, combining or compare the found itemsets or rules requires a compatible item coding. That is, the sparse matrices representing the items (the itemMatrix objects) have columns for the same items in exactly the same order. The coercion to transactions with transactions() or as(x, "transactions") will create the item coding by adding items in the order they are encountered in the dataset. This can lead to different item codings (different order, missing items) for even only slightly different datasets or versions of a dataset. Method compatible() can be used to check if two sets have the same item coding.

Defining a common item coding: When working with many sets, then first a common item coding should be defined by creating a vector with all possible item labels and then specify them as itemLabels to create transactions with transactions(). Compatible itemMatrix objects can be created using encode().

Recoding and Decoding: Two incompatible objects can be made compatible using recode(). Recode one object by specifying the other object in itemLabels.

decode() converts from the column IDs used in the itemMatrix representation to item labels. decode() is used by LIST().

Value

recode() always returns an object of the same class as x.

For encode() with itemMatrix = TRUE an object of class itemMatrix is returned. Otherwise the result is of the same type as x, e.g., a list or a vector.

Author(s)

Michael Hahsler

See Also

LIST(), associations, itemMatrix

Other preprocessing: discretize(), hierarchy, merge(), sample()

Examples

data("Adult")

## Example 1: Manual decoding
## Extract the item coding as a vector of item labels.
iLabels <- itemLabels(Adult)
head(iLabels)

## get undecoded list (itemIDs)
list <- LIST(Adult[1:5], decode = FALSE)
list

## decode itemIDs by replacing them with the appropriate item label
decode(list, itemLabels = iLabels)


## Example 2: Manually create an itemMatrix using iLabels as the common item coding
data <- list(
  c("income=small", "age=Young"),
  c("income=large", "age=Middle-aged")
)

# Option a: encode to match the item coding in Adult
iM <- encode(data, itemLabels = Adult)
iM
inspect(iM)
compatible(iM, Adult)

# Option b: coercion plus recode to make it compatible to Adult
#           (note: the coding has 115 item columns after recode)
iM <- as(data, "itemMatrix")
iM
compatible(iM, Adult)

iM <- recode(iM, itemLabels = Adult)
iM
compatible(iM, Adult)


## Example 3: use recode to make itemMatrices compatible
## select first 100 transactions and all education-related items
sub <- Adult[1:100, itemInfo(Adult)$variables == "education"]
itemLabels(sub)
image(sub)

## After choosing only a subset of items (columns), the item coding is now
## no longer compatible with the Adult dataset
compatible(sub, Adult)

## recode to match Adult again
sub.recoded <- recode(sub, itemLabels = Adult)
image(sub.recoded)


## Example 4: manually create 2 new transaction for the Adult data set
##            Note: check itemLabels(Adult) to see the available labels for items
twoTransactions <- as(
  encode(list(
    c("age=Young", "relationship=Unmarried"),
    c("age=Senior")
  ), itemLabels = Adult),
  "transactions"
)

twoTransactions
inspect(twoTransactions)

## the same using the transactions constructor function instead
twoTransactions <- transactions(
  list(
    c("age=Young", "relationship=Unmarried"),
    c("age=Senior")
  ),
  itemLabels = Adult
)

twoTransactions
inspect(twoTransactions)

## Example 5: Use a common item coding

# Creation of transactions separately will produce different item codings
trans1 <- transactions(
  list(
    c("age=Young", "relationship=Unmarried"),
    c("age=Senior")
  )
)
trans1

trans2 <- transactions(
  list(
    c("age=Middle-aged", "relationship=Married"),
    c("relationship=Unmarried", "age=Young")
  )
)
trans2

compatible(trans1, trans2)

# produce common item coding (all item labels in the two sets)
commonItemLabels <- union(itemLabels(trans1), itemLabels(trans2))
commonItemLabels

trans1 <- recode(trans1, itemLabels = commonItemLabels)
trans1
trans2 <- recode(trans2, itemLabels = commonItemLabels)
trans2

compatible(trans1, trans2)


## Example 6: manually create a rule using the item coding in Adult
## and calculate interest measures
aRule <- new("rules",
  lhs = encode(list(c("age=Young", "relationship=Unmarried")),
    itemLabels = Adult
  ),
  rhs = encode(list(c("income=small")),
    itemLabels = Adult
  )
)

## shorter version using the rules constructor
aRule <- rules(
  lhs = list(c("age=Young", "relationship=Unmarried")),
  rhs = list(c("income=small")),
  itemLabels = Adult
)

quality(aRule) <- interestMeasure(aRule,
  measure = c("support", "confidence", "lift"), transactions = Adult
)

inspect(aRule)