R/subset.R

In arules: Mining Association Rules and Frequent Itemsets

#######################################################################
# arules - Mining Association Rules and Frequent Itemsets
# Copyright (C) 2011-2015 Michael Hahsler, Christian Buchta,
# 			Bettina Gruen and Kurt Hornik
#
# This program is free software; you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation; either version 2 of the License, or
# any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License along
# with this program; if not, write to the Free Software Foundation, Inc.,
# 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.

#' Subsetting Itemsets, Rules and Transactions
#'
#' Provides the generic function `subset()` and methods to subset
#' [associations] or [transactions] ([itemMatrix]) which meet certain conditions
#' (e.g., contains certain items or satisfies a minimum lift).
#'
#' `subset()` finds the rows/itemsets/rules of `x` that match the expression
#' given in `subset`. Parts of `x` like items, lhs, rhs and the columns in the quality data.frame (e.g., support and lift) can be directly referred to by their names
#' in `subset`.
#'
#' Important operators to select itemsets containing items specified by their
#' labels are
#'
#' * [%in%]: select itemsets matching _any_ given item
#' * [%ain%]: select only itemsets matching _all_ given item
#' * [%oin%]: select only itemsets matching _only_ the given item
#' * [%pin%]: `%in%` with _partial matching_
#'
#' @aliases subset
#' @param x object to be subsetted.
#' @param subset logical expression indicating elements to keep.
#' @param ... further arguments to be passed to or from other methods.
#' @return An object of the same class as `x` containing only the elements
#' which satisfy the conditions.
#' @author Michael Hahsler
#' @keywords manip
#' @examples
#' data("Adult")
#' rules <- apriori(Adult)
#'
#' ## select all rules with item "marital-status=Never-married" in
#' ## the right-hand-side and lift > 2
#' rules.sub <- subset(rules, subset = rhs %in% "marital-status=Never-married" &
#'   lift > 2)
#'
#' ## use partial matching for all items corresponding to the variable
#' ## "marital-status"
#' rules.sub <- subset(rules, subset = rhs %pin% "marital-status=")
#'
#' ## select only rules with items "age=Young" and "workclass=Private" in
#' ## the left-hand-side
#' rules.sub <- subset(rules, subset = lhs %ain%
#'   c("age=Young", "workclass=Private"))
setGeneric("subset")

#' @rdname subset
setMethod(
  "subset", signature(x = "itemMatrix"),
  function(x, subset, ...) {
    if (missing(subset)) {
      return(x)
    }
    i <- eval(
      substitute(subset), list(items = x),
      parent.frame(2)
    )
    x[i, ]
  }
)


#' @rdname subset
setMethod(
  "subset", signature(x = "itemsets"),
  function(x, subset, ...) {
    if (missing(subset)) {
      return(x)
    }
    i <- eval(
      substitute(subset), c(
        quality(x),
        list(items = items(x))
      ),
      parent.frame(2)
    )
    x[i, ]
  }
)

#' @rdname subset
setMethod(
  "subset", signature(x = "rules"),
  function(x, subset, ...) {
    if (missing(subset)) {
      return(x)
    }

    i <- eval(
      substitute(subset), c(
        quality(x),
        list(lhs = lhs(x), rhs = rhs(x), items = items(x))
      ),
      parent.frame(2)
    )
    x[i, ]
  }
)