R: Class itemMatrix - Sparse Binary Incidence Matrix to...

itemMatrix-class {arules} | R Documentation

## Class itemMatrix — Sparse Binary Incidence Matrix to Represent Sets of Items

### Description

The `itemMatrix` class is the basic building block for transactions, itemsets and rules in package arules. The class contains a sparse Matrix representation of items (a set of itemsets or transactions) and the corresponding item labels.

### Details

Sets of itemsets (or transactions) are represented as a compressed sparse binary matrix. Columns represent items and rows are the set/transactions. In the compressed form, each itemset is a vector of column indices (called item IDs) representing the items.

Note: If you work with several itemMatrices at the same time (e.g., several transaction sets, lhs and rhs of a rule, etc.), then the encoding (itemLabes and order of the items in the binary matrix) in the different itemMatrices is important and needs to conform. See `itemCoding` to learn how to encode and recode itemMatrix objects.

### Objects from the Class

Objects can be created by calls of the form `new("itemMatrix", ...)`. However, most of the time objects will be created by coercion from a matrix, list or data.frame.

### Slots

`data`:

  Object of class `ngCMatrix` (from package Matrix) which stores item occurrences in sparse representation. Note that the `ngCMatrix` is column-oriented and `itemMatrix` is row-oriented with each row representing an element (an itemset, a transaction, etc.). As a result, the `ngCMatrix` in this slot is always a transposed version of the binary incidence matrix in `itemMatrix`.

`itemInfo`:

  a data.frame which contains named vectors of the length equal to the number of elements in the set. If the slot is not empty (contains no item labels), the first element in the data.frame must have the name `"labels"` and contain a character vector with the item labels used for representing an item. In addition to the item labels, the data.frame can contain arbitrary named vectors (of the same length) to represent, e.g., variable names and values which were used to create the binary items or hierarchical category information associated with each item label.

`itemsetInfo`:

  a data.frame which may contain additional information for the rows (mostly representing itemsets) in the matrix.

### Methods

coerce

  `signature(from = "matrix", to = "itemMatrix")`; expects `from` to be a binary matrix only containing 0s and 1s.

coerce

  `signature(from = "itemMatrix", to = "matrix")`; coerces to a dense 0-1 matrix of `storage.mode` `"integer"` instead of `"double"` to save memory.

coerce

  `signature(from = "list", to = "itemMatrix")`; `from` is a list of vectors. Each vector contains one set/transaction/....

coerce

  `signature(from = "itemMatrix", to = "list")`; see also the methods for `LIST`.

coerce

  `signature(from = "itemMatrix", to = "ngCMatrix")`; access the sparse matrix representation. Note, the `ngCMatrix` contains a transposed from of the itemMatrix.

coerce

  `signature(from = "ngCMatrix", to = "itemMatrix")`; Note, the `ngCMatrix` has to be transposed with items as rows!

c

  `signature(object = "itemMatrix")`; combine.

dim

  `signature(x = "itemMatrix")`; returns the dimensions of the itemMatrix.

dimnames, rownames, colnames

  `signature(x = "itemMatrix")`; returns row (itemsetID) and column (item) names.

dimnames

  `signature(x = "itemMatrix")`; returns dimnames.

dimnames<-

  `signature(x = "itemMatrix", value = "list")`; replace dimnames.

%in%

  `signature(x = "itemMatrix", table = "character")`; matches the strings in `table` against the item labels in `x` and returns a logical vector indicating if a row (itemset) in `x` contains any of the items specified in `table`. Note that there is a `%in%` method with `signature(x = "itemMatrix", table = "character")`. This method is described in together with `match`.

%ain%

  `signature(x = "itemMatrix", table = "character")`; matches the strings in `table` against the item labels in `x` and returns a logical vector indicating if a row (itemset) in `x` contains all of the items specified in `table`.

%oin%

  `signature(x = "itemMatrix", table = "character")`; matches the strings in `table` against the item labels in `x` and returns a logical vector indicating if a row (itemset) in `x` contains only items specified in `table`.

%pin%

  `signature(x = "itemMatrix", table = "character")`; matches the strings in `table` against the item labels in `x` (using partial matching) and returns a logical vector indicating if a row (itemset) in `x` contains any of the items specified in `table`.

itemLabels

  `signature(object = "itemMatrix")`; returns the item labels used for encoding as a character vector.

itemLabels<-

  `signature(object = "itemMatrix")`; replaces the item labels used for encoding.

itemInfo

  `signature(object = "itemMatrix")`; returns the whole item/column information data.frame including labels.

itemInfo<-

  `signature(object = "itemMatrix")`; replaces the item/column info by a data.frame.

itemsetInfo

  `signature(object = "itemMatrix")`; returns the item set/row information data.frame.

itemsetInfo<-

  `signature(object = "itemMatrix")`; replaces the item set/row info by a data.frame.

labels

  `signature(x = "transactions")`; returns labels for the itemsets. The following arguments can be used to customize the representation of the labels: `itemSep`, `setStart` and `setEnd`.

nitems

  `signature(x = "itemMatrix")`; returns the number of items (number in columns) in the itemMatrix.

toLongFormat

  `signature(object = "itemMatrix")`; convert the transactions to long format (a data.frame with two columns, tid and item). Column names can be specified as a character vector of length 2 called `cols`.

show

  `signature(object = "itemMatrix")`

summary

  `signature(object = "itemMatrix")`

### Author(s)

Michael Hahsler

### See Also

`LIST`, `c`, `duplicated`, `inspect`, `is.subset`, `is.superset`, `itemFrequency`, `itemFrequencyPlot`, `itemCoding`, `match`, `length`, `sets`, `subset`, `unique`, `[-methods`, `image`, `ngCMatrix-class` (from Matrix), `transactions-class`, `itemsets-class`, `rules-class`

### Examples

    set.seed(1234)

    ## Generate a logical matrix with 5000 random itemsets for 20 items
    m <- matrix(runif(5000*20)>0.8, ncol=20,
                dimnames = list(NULL, paste("item", c(1:20), sep="")))
    head(m)

    ## Coerce the logical matrix into an itemMatrix object
    imatrix <- as(m, "itemMatrix")
    imatrix

    ## An itemMatrix contains a set of itemsets (each row is an itemset).
    ## The length of the set is the number of rows.
    length(imatrix)

    ## The sparese matrix also has regular matrix  dimensions.
    dim(imatrix)
    nrow(imatrix)
    ncol(imatrix)

    ## Subsetting: Get first 5 elements (rows) of the itemMatrix. This can be done in
    ## several ways.
    imatrix[1:5]            ### get elements 1:5
    imatrix[1:5, ]          ### Matrix subsetting for rows 1:5
    head(imatrix, n = 5)    ### head()

    ## Get first 5 elements (rows) of the itemMatrix as list.
    as(imatrix[1:5], "list")

    ## Get first 5 elements (rows) of the itemMatrix as matrix.
    as(imatrix[1:5], "matrix")

    ## Get first 5 elements (rows) of the itemMatrix as sparse ngCMatrix.
    ## Warning: For efficiency reasons, the ngCMatrix is transposed!
    as(imatrix[1:5], "ngCMatrix")

    ## Get labels for the first 5 itemsets (first default and then with
    ## custom formating)
    labels(imatrix[1:5])
    labels(imatrix[1:5], itemSep = " + ", setStart = "", setEnd = "")

    ## Create itemsets manually from an itemMatrix. Itemsets contain items in the form of
    ## an itemMatrix and additional quality measures (not supplied in the example).
    is <- new("itemsets", items = imatrix)
    is
    inspect(head(is, n = 3))

    ## Create rules manually. I use imatrix[4:6] for the lhs of the rules and
    ## imatrix[1:3] for the rhs. Rhs and lhs cannot share items so I use
    ## itemSetdiff here. I also assign missing values for the quality measures support
    ## and confidence.
    rules <- new("rules",
                 lhs = itemSetdiff(imatrix[4:6], imatrix[1:3]),
                 rhs = imatrix[1:3],
                 quality = data.frame(support = c(NA, NA, NA),
                                      confidence =  c(NA, NA, NA)
              ))
    rules
    inspect(rules)

    ## Manually create a itemMatrix with an item encoding that matches imatrix (20 items in order
    ## item1, item2, ..., item20)
    itemset_list <- list(c("item1","item2"),
                         c("item3"))

    imatrix_new <- encode(itemset_list, itemLabels = imatrix)
    imatrix_new
    compatible(imatrix_new, imatrix)

[Package arules version 1.7-2 Index]