Package 'nuggets'

Description

This function calculates various additional interest measures for association rules based on their contingency table counts.

Usage

## S3 method for class 'associations'
add_interest(x, measures = NULL, smooth_counts = 0, p = 0.5, ...)

add_interest(x, ...)

Arguments

Details

The input nugget object must contain the columns pp (positive antecedent & positive consequent), pn (positive antecedent & negative consequent), np (negative antecedent & positive consequent), and nn (negative antecedent & negative consequent), representing the counts from the contingency table. These columns are automatically produced by dig_associations().

The supported interest measures that can be calculated include:

• Founded GUHA (General Unary Hypothesis Automaton) quantifiers:

  • "fi" - Founded Implication, which equals to the "confidence" measure calculated automatically by dig_associations().

  • "dfi" - Double Founded Implication computed as $pp / (pp + pn + np)$

  • "fe" - Founded Equivalence computed as $(pp + nn) / (pp + pn + np + nn)$

• GUHA quantifiers based on binomial tests - these measures require the additional parameter p, which represents the conditional probability of the consequent being true given that the antecedent is true under the null hypothesis. The measures are computed as one-sided p-values from the Clopper-Pearson confidence interval for the binomial proportion:

  • "lci" - Lower Critical Implication computed as $\sum_{i=pp}^{pp+pn} \frac{(pp+pn)!}{i!(pp+pn-i)!} p^i (1-p)^{pp+pn-i}$

  • "uci" - Upper Critical Implication computed as $\sum_{i=0}^{pp} \frac{(pp+pn)!}{i!(pp+pn-i)!} p^i (1-p)^{pp+pn-i}$

  • "dlci" - Double Lower Critical Implication computed as $\sum_{i=pp}^{pp+pn+np} \frac{(pp+pn+np)!}{i!(pp+pn+np-i)!} p^i (1-p)^{pp+pn+np-i}$

  • "duci" - Double Upper Critical Implication computed as $\sum_{i=0}^{pp} \frac{(pp+pn+np)!}{i!(pp+pn+np-i)!} p^i (1-p)^{pp+pn+np-i}$

  • "lce" - Lower Critical Equivalence computed as $\sum_{i=pp}^{pp+pn+np+nn} \frac{(pp+pn+np+nn)!}{i!(pp+pn+np+nn-i)!} p^i (1-p)^{pp+pn+np+nn-i}$

  • "uce" - Upper Critical Equivalence computed as $\sum_{i=0}^{pp} \frac{(pp+pn+np+nn)!}{i!(pp+pn+np+nn-i)!} p^i (1-p)^{pp+pn+np+nn-i}$

• measures adopted from the arules package:

  • "added_value" - Added Value, see https://mhahsler.github.io/arules/docs/measures#addedvalue for details

  • "casual_confidence" - Casual Confidence, see https://mhahsler.github.io/arules/docs/measures#casualconfidence for details

  • "casual_support" - Casual Support, see https://mhahsler.github.io/arules/docs/measures#casualsupport for details

  • "centered_confidence" - Centered Confidence, see https://mhahsler.github.io/arules/docs/measures#centeredconfidence for details

  • "certainty" - Certainty Factor, see https://mhahsler.github.io/arules/docs/measures#certainty for details

  • "collective_strength" - Collective Strength, see https://mhahsler.github.io/arules/docs/measures#collectivestrength for details

  • "confirmed_confidence" - Descriptive Confirmed Confidence, see https://mhahsler.github.io/arules/docs/measures#confirmedconfidence for details

  • "conviction" - Conviction, see https://mhahsler.github.io/arules/docs/measures#conviction for details

  • "cosine" - Cosine, see https://mhahsler.github.io/arules/docs/measures#cosine for details

  • "counterexample" - Example and Counter-Example Rate, see https://mhahsler.github.io/arules/docs/measures#counterexample for details

  • "doc" - Difference of Confidence, see https://mhahsler.github.io/arules/docs/measures#doc for details

  • "gini" - Gini Index, see https://mhahsler.github.io/arules/docs/measures#gini for details

  • "imbalance" - Imbalance Ratio, see https://mhahsler.github.io/arules/docs/measures#imbalance for details

  • "implication_index" - Implication Index, see https://mhahsler.github.io/arules/docs/measures#implicationindex for details

  • "importance" - Importance, see https://mhahsler.github.io/arules/docs/measures#importance for details

  • "j_measure" - J-Measure, see https://mhahsler.github.io/arules/docs/measures#jmeasure for details

  • "jaccard" - Jaccard Coefficient, see https://mhahsler.github.io/arules/docs/measures#jaccard for details

  • "kappa" - Kappa, see https://mhahsler.github.io/arules/docs/measures#kappa for details

  • "kulczynski" - Kulczynski, see https://mhahsler.github.io/arules/docs/measures#kulczynski for details

  • "lambda" - Lambda, see https://mhahsler.github.io/arules/docs/measures#lambda for details

  • "least_contradiction" - Least Contradiction, see https://mhahsler.github.io/arules/docs/measures#leastcontradiction for details

  • "lerman" - Lerman Similarity, see https://mhahsler.github.io/arules/docs/measures#lerman for details

  • "leverage" - Leverage, see https://mhahsler.github.io/arules/docs/measures#leverage for details

  • "maxconfidence" - Max Confidence, see https://mhahsler.github.io/arules/docs/measures#maxconfidence for details

  • "mutual_information" - Mutual Information, see https://mhahsler.github.io/arules/docs/measures#mutualinformation for details

  • "odds_ratio" - Odds Ratio, see https://mhahsler.github.io/arules/docs/measures#oddsratio for details

  • "phi" - Phi Correlation Coefficient, see https://mhahsler.github.io/arules/docs/measures#phi for details

  • "ralambondrainy" - Ralambondrainy, see https://mhahsler.github.io/arules/docs/measures#ralambondrainy for details

  • "relative_risk" - Relative Risk, see https://mhahsler.github.io/arules/docs/measures#relativerisk for details

  • "rule_power_factor" - Rule Power Factor, see https://mhahsler.github.io/arules/docs/measures#rulepowerfactor for details

  • "sebag" - Sebag-Schoenauer, see https://mhahsler.github.io/arules/docs/measures#sebag for details

  • "varying_liaison" - Varying Rates Liaison, see https://mhahsler.github.io/arules/docs/measures#varyingliaison for details

  • "yule_q" - Yule's Q, see https://mhahsler.github.io/arules/docs/measures#yuleq for details

  • "yule_y" - Yule's Y, see https://mhahsler.github.io/arules/docs/measures#yuley for details

All the above measures are primarily intended for use with binary (logical) data. While they can be computed for numerical data as well, their interpretations may not be meaningful in that context - users should exercise caution when applying these measures to non-binary data.

Many measures are based on the contingency table counts, and some may be undefined for certain combinations of counts (e.g., division by zero). This issue can be mitigated by applying smoothing using the smooth_counts argument.

Value

An S3 object which is an instance of associations and nugget classes and which is a tibble containing all the columns of the input nugget x, plus additional columns for each of the requested interest measures.

Author(s)

Michal Burda

See Also

dig_associations()

Examples

d <- partition(mtcars, .breaks = 2)
rules <- dig_associations(d,
                          antecedent = !starts_with("mpg"),
                          consequent = starts_with("mpg"),
                          min_support = 0.3,
                          min_confidence = 0.8)
rules <- add_interest(rules,
                   measures = c("conviction", "leverage", "jaccard"))

Description

The association matrix is a matrix where rows correspond to antecedents, columns correspond to consequents, and the values are taken from a specified column of the nugget. Missing values are filled with zeros.

A pair of antecedent and consequent must be unique in the nugget. If there are multiple rows with the same pair, an error is raised.

Usage

association_matrix(
  x,
  value,
  error_context = list(arg_x = "x", arg_value = "value", call = current_env())
)

Arguments

Value

A numeric matrix with row names corresponding to antecedents and column names corresponding to consequents. Values are taken from the column specified by value. Missing values are filled with zeros.

Author(s)

Michal Burda

Examples

d <- partition(mtcars, .breaks = 2)
rules <- dig_associations(d,
                          antecedent = everything(),
                          consequent = everything(),
                          min_support = 0.3)
association_matrix(rules, confidence)

Description

This function computes the range of numeric values in a vector and adjusts the bounds to "nice" rounded numbers. Specifically, it rounds the lower bound downwards (similar to floor()) and the upper bound upwards (similar to ceiling()) to the specified number of digits. This can be useful when preparing data ranges for axis labels, plotting, or reporting. The function returns a numeric vector of length two, containing the adjusted lower and upper bounds.

Usage

bound_range(x, digits = 0, na_rm = FALSE)

Arguments

Value

A numeric vector of length two with the rounded lower and upper bounds of the range of x. The lower bound is always rounded down, and the upper bound is always rounded up. If x is NULL or has length zero, the function returns NULL.

Author(s)

Michal Burda

See Also

floor(), ceiling()

Examples

bound_range(c(1.9, 2, 3.1), digits = 0)      # returns c(1, 4)
bound_range(c(190, 200, 301), digits = -2)   # returns c(100, 400)

Description

This function clusters association rules based on the selected numeric attribute by (e.g., confidence or lift) and summarizes the clusters. The clustering is performed using the k-means algorithm.

Each cluster is represented by a label consisting of the number of rules in the cluster and the most common predicates in the antecedents of those rules.

Usage

cluster_associations(
  x,
  n,
  by,
  algorithm = "Hartigan-Wong",
  predicates_in_label = 2
)

Arguments

Value

A tibble with one row per (cluster, consequent) pair. The columns are:

• cluster: the cluster number;

• cluster_label: a label for the cluster, consisting of the number of rules in the cluster and the most common predicates in the antecedents of those rules;

• consequent: consequents of the rules;

• other numeric columns from the input nugget, aggregated by mean within each cluster.

Author(s)

Michal Burda

See Also

dig_associations(), association_matrix() stats::kmeans()

Examples

# Prepare the data
cars <- mtcars |>
    partition(cyl, vs:gear, .method = "dummy") |>
    partition(carb, .method = "crisp", .breaks = c(0, 3, 10)) |>
    partition(mpg, disp:qsec, .method = "triangle", .breaks = 3)

# Search for associations
rules <- dig_associations(cars,
                          antecedent = everything(),
                          consequent = everything(),
                          max_length = 3,
                          min_support = 0.2)

# Cluster the found rules
clu <- cluster_associations(rules, 10, "lift")

# Print the number of clusters
length(unique(clu$cluster))

## Not run: 
# Plot the clustered rules
library(ggplot2)

ggplot(clu) +
   aes(x = cluster_label, y = consequent, color = lift, size = support) +
   geom_point() +
   xlab("predicates in antecedent groups") +
   scale_y_discrete(limits = rev) +
   theme(axis.text.x = element_text(angle = 45, hjust = 1))

## End(Not run)

Description

A general function for searching for patterns of a custom type. The function allows selection of columns of x to be used as condition predicates. It enumerates all possible conditions in the form of elementary conjunctions of selected predicates, and for each condition executes a user-defined callback function f. The callback is expected to perform some analysis and return an object (often a list) representing a pattern or patterns related to the condition. The results of all calls are returned as a list.

The callback function f may accept a number of arguments (see f argument description). The algorithm automatically provides condition-related information to f based on which arguments are present.

In addition to conditions, the function can evaluate focus predicates (foci). Foci are specified separately and are tested within each generated condition. Extra information about them is then passed to f.

Restrictions may be imposed on generated conditions, such as:

• minimum and maximum condition length (min_length, max_length);

• minimum condition support (min_support);

• minimum focus support (min_focus_support), i.e. support of rows where both the condition and the focus hold.

Usage

dig(
  x,
  f,
  condition = everything(),
  focus = NULL,
  disjoint = var_names(colnames(x)),
  excluded = NULL,
  min_length = 0,
  max_length = Inf,
  min_support = 0,
  min_focus_support = 0,
  min_conditional_focus_support = 0,
  max_support = 1,
  filter_empty_foci = FALSE,
  t_norm = "goguen",
  max_results = Inf,
  verbose = FALSE,
  threads = 1L,
  error_context = list(arg_x = "x", arg_f = "f", arg_condition = "condition", arg_focus =
    "focus", arg_disjoint = "disjoint", arg_excluded = "excluded", arg_min_length =
    "min_length", arg_max_length = "max_length", arg_min_support = "min_support",
    arg_min_focus_support = "min_focus_support", arg_min_conditional_focus_support =
    "min_conditional_focus_support", arg_max_support = "max_support",
    arg_filter_empty_foci = "filter_empty_foci", arg_t_norm = "t_norm", arg_max_results =
    "max_results", arg_verbose = "verbose", 
     arg_threads = "threads", call =
    current_env())
)

Arguments

Details

Let $P$ be the set of condition predicates selected by condition and $E$ be the set of focus predicates selected by focus. The function generates all possible conditions as elementary conjunctions of distinct predicates from $P$. These conditions are filtered using disjoint, excluded, min_length, max_length, min_support, and max_support.

For each remaining condition, all foci from $E$ are tested and filtered using min_focus_support and min_conditional_focus_support. If at least one focus remains (or if filter_empty_foci = FALSE), the callback f is executed with details of the condition and foci. Results of all calls are collected and returned as a list.

Let $C$ be a condition ($C \subseteq P$), $F$ the set of filtered foci ($F \subseteq E$), $R$ the set of rows of x, and $\mu_C(r)$ the truth degree of condition $C$ on row $r$. The parameters passed to f are defined as:

• condition: a named integer vector of column indices representing the predicates of $C$. Names correspond to column names.

• sum: a numeric scalar value of the number of rows satisfying $C$ for logical data, or the sum of truth degrees for fuzzy data, $sum = \sum_{r \in R} \mu_C(r)$.

• support: a numeric scalar value of relative frequency of rows satisfying $C$, $supp = sum / |R|$.

• pp, pn, np, nn: a numeric vector of entries of a contingency table for $C$ and $F$, satisfying the Ruspini condition $pp + pn + np + nn = |R|$. The $i$-th elements of these vectors correspond to the $i$-th focus $F_i$ from $F$ and are defined as:

  • pp[i]: rows satisfying both $C$ and $F_i$, $pp_i = \sum_{r \in R} \mu_{C \land F_i}(r)$.

  • pn[i]: rows satisfying $C$ but not $F_i$, $pn_i = \sum_{r \in R} \mu_C(r) - pp_i$.

  • np[i]: rows satisfying $F_i$ but not $C$, $np_i = \sum_{r \in R} \mu_{F_i}(r) - pp_i$.

  • nn[i]: rows satisfying neither $C$ nor $F_i$, $nn_i = |R| - (pp_i + pn_i + np_i)$.

Value

A list of results returned by the callback function f.

Author(s)

Michal Burda

See Also

partition(), var_names(), dig_grid()

Examples

library(tibble)

# Prepare iris data
d <- partition(iris, .breaks = 2)

# Simple callback: return formatted condition names
dig(x = d,
    f = function(condition) format_condition(names(condition)),
    min_support = 0.5)

# Callback returning condition and support
res <- dig(x = d,
           f = function(condition, support) {
               list(condition = format_condition(names(condition)),
                    support = support)
           },
           min_support = 0.5)
do.call(rbind, lapply(res, as_tibble))

# Within each condition, evaluate also supports of columns starting with
# "Species"
res <- dig(x = d,
           f = function(condition, support, pp) {
               c(list(condition = format_condition(names(condition))),
                 list(condition_support = support),
                 as.list(pp / nrow(d)))
           },
           condition = !starts_with("Species"),
           focus = starts_with("Species"),
           min_support = 0.5,
           min_focus_support = 0)
do.call(rbind, lapply(res, as_tibble))

# Multiple patterns per condition based on foci
res <- dig(x = d,
           f = function(condition, support, pp) {
               lapply(seq_along(pp), function(i) {
                   list(condition = format_condition(names(condition)),
                        condition_support = support,
                        focus = names(pp)[i],
                        focus_support = pp[[i]] / nrow(d))
               })
           },
           condition = !starts_with("Species"),
           focus = starts_with("Species"),
           min_support = 0.5,
           min_focus_support = 0)

# Flatten result and convert to tibble
res <- unlist(res, recursive = FALSE)
do.call(rbind, lapply(res, as_tibble))

Description

Searches for all association rules that are ancestors of the given association rule, i.e. all rules whose antecedent is a subset of the antecedent of the given rule and whose consequent is equal to the consequent of the given rule. The search is performed using the same disjoint, excluded, and t_norm parameters as the original search that produced the given rule.

Usage

## S3 method for class 'associations'
dig_ancestors(x, data, ...)

dig_ancestors(x, data, ...)

Arguments

Value

A nugget of flavour associations containing all association rules that are ancestors of the given rule x.

Author(s)

Michal Burda

See Also

dig_associations()

Examples

d <- partition(mtcars, .breaks = 2)
rules <- dig_associations(d,
                          antecedent = !starts_with("mpg"),
                          consequent = starts_with("mpg"),
                          min_support = 0.3,
                          min_confidence = 0.8)
r <- rules[1, ]  # get first rule
anc <- dig_ancestors(r, d)

Description

Association rules identify conditions (antecedents) under which a specific feature (consequent) is present very often.

Scheme:

⁠A => C⁠

If condition A is satisfied, then the feature C is present very often.

Example:

⁠university_edu & middle_age & IT_industry => high_income⁠

People in middle age with university education working in IT industry have very likely a high income.

Antecedent A is usually a set of predicates, and consequent C is a single predicate.

For the following explanations we need a mathematical function $supp(I)$, which is defined for a set $I$ of predicates as a relative frequency of rows satisfying all predicates from $I$. For logical data, $supp(I)$ equals to the relative frequency of rows, for which all predicates $i_1, i_2, \ldots, i_n$ from $I$ are TRUE. For numerical (double) input, $supp(I)$ is computed as the mean (over all rows) of truth degrees of the formula ⁠i_1 AND i_2 AND ... AND i_n⁠, where AND is a triangular norm selected by the t_norm argument.

Association rules are characterized with the following quality measures.

Length of a rule is the number of elements in the antecedent.

Coverage of a rule is equal to $supp(A)$.

Consequent support of a rule is equal to $supp(\{c\})$.

Support of a rule is equal to $supp(A \cup \{c\})$.

Confidence of a rule is the fraction $supp(A) / supp(A \cup \{c\})$.

Lift of a rule is the ratio of its support to the expected support assuming antecedent and consequent are independent, i.e., $supp(A \cup \{c\}) / (supp(A) * supp(\{c\}))$.

Usage

dig_associations(
  x,
  antecedent = everything(),
  consequent = everything(),
  disjoint = var_names(colnames(x)),
  excluded = NULL,
  min_length = 0L,
  max_length = Inf,
  min_coverage = 0,
  min_support = 0,
  min_confidence = 0,
  contingency_table = deprecated(),
  t_norm = "goguen",
  max_results = Inf,
  verbose = FALSE,
  threads = 1,
  error_context = list(arg_x = "x", arg_antecedent = "antecedent", arg_consequent =
    "consequent", arg_disjoint = "disjoint", arg_excluded = "excluded", arg_min_length =
    "min_length", arg_max_length = "max_length", arg_min_coverage = "min_coverage",
    arg_min_support = "min_support", arg_min_confidence = "min_confidence",
    arg_contingency_table = "contingency_table", arg_t_norm = "t_norm", arg_max_results =
    "max_results", arg_verbose = "verbose", arg_threads = "threads", call =
    current_env())
)

Arguments

Value

An S3 object, which is an instance of associations and nugget classes, and which is a tibble with found patterns and computed quality measures.

Author(s)

Michal Burda

See Also

partition(), var_names(), dig()

Examples

d <- partition(mtcars, .breaks = 2)
dig_associations(d,
                 antecedent = !starts_with("mpg"),
                 consequent = starts_with("mpg"),
                 min_support = 0.3,
                 min_confidence = 0.8)

Description

Baseline contrast patterns identify conditions under which a specific feature is significantly different from a given value by performing a one-sample statistical test.

Scheme:

var != 0 | C

Variable var is (in average) significantly different from 0 under the condition C.

Example:

⁠(measure_error != 0 | measure_tool_A ⁠

If measuring with measure tool A, the average measure error is significantly different from 0.

The baseline contrast is computed using a one-sample statistical test, which is specified by the method argument. The function computes the contrast between all variables specified by the vars argument. Baseline contrasts are computed in sub-data corresponding to conditions generated from the condition columns. Function dig_baseline_contrasts() supports crisp conditions only, i.e., the condition columns in x must be logical.

Usage

dig_baseline_contrasts(
  x,
  condition = where(is.logical),
  vars = where(is.numeric),
  disjoint = var_names(colnames(x)),
  excluded = NULL,
  min_length = 0L,
  max_length = Inf,
  min_support = 0,
  max_support = 1,
  method = "t",
  alternative = "two.sided",
  h0 = 0,
  conf_level = 0.95,
  max_p_value = 0.05,
  wilcox_exact = FALSE,
  wilcox_correct = TRUE,
  wilcox_tol_root = 1e-04,
  wilcox_digits_rank = Inf,
  max_results = Inf,
  verbose = FALSE,
  threads = 1
)

Arguments

Value

An S3 object which is an instance of baseline_contrasts and nugget classes and which is a tibble with found patterns in rows. The following columns are always present:

For the "t" method, the following additional columns are also present (see also t.test()):

Author(s)

Michal Burda

See Also

dig_paired_baseline_contrasts(), dig_complement_contrasts(), dig(), dig_grid(), stats::t.test(), stats::wilcox.test()

Examples

d <- partition(mtcars, .breaks = 2, .keep = TRUE)
dig_baseline_contrasts(d,
                       condition = where(is.logical),
                       vars = where(is.numeric),
                       min_support = 0.3,
                       max_length = 2)

Description

Complement contrast patterns identify conditions under which there is a significant difference in some numerical variable between elements that satisfy the identified condition and the rest of the data table.

Scheme:

⁠(var | C) != (var | not C)⁠

There is a statistically significant difference in variable var between group of elements that satisfy condition C and a group of elements that do not satisfy condition C.

Example:

(life_expectancy | smoker) < (life_expectancy | non-smoker)

The life expectancy in people that smoke cigarettes is in average significantly lower than in people that do not smoke.

The complement contrast is computed using a two-sample statistical test, which is specified by the method argument. The function computes the complement contrast in all variables specified by the vars argument. Complement contrasts are computed based on sub-data corresponding to conditions generated from the condition columns and the rest of the data table. Function #' dig_complement_contrasts() supports crisp conditions only, i.e., the condition columns in x must be logical.

Usage

dig_complement_contrasts(
  x,
  condition = where(is.logical),
  vars = where(is.numeric),
  disjoint = var_names(colnames(x)),
  excluded = NULL,
  min_length = 0L,
  max_length = Inf,
  min_support = 0,
  max_support = 1 - min_support,
  method = "t",
  alternative = "two.sided",
  h0 = if (method == "var") 1 else 0,
  conf_level = 0.95,
  max_p_value = 0.05,
  t_var_equal = FALSE,
  wilcox_exact = FALSE,
  wilcox_correct = TRUE,
  wilcox_tol_root = 1e-04,
  wilcox_digits_rank = Inf,
  max_results = Inf,
  verbose = FALSE,
  threads = 1L
)

Arguments

Value

An S3 object which is an instance of complement_contrasts and nugget classes and which is a tibble with found patterns in rows. The following columns are always present:

For the "t" method, the following additional columns are also present (see also t.test()):

Author(s)

Michal Burda

See Also

dig_baseline_contrasts(), dig_paired_baseline_contrasts(), dig(), dig_grid(), stats::t.test(), stats::wilcox.test(), stats::var.test()

Examples

d <- partition(mtcars, .breaks = 2, .keep = TRUE)
dig_complement_contrasts(d,
                         condition = where(is.logical),
                         vars = where(is.numeric),
                         min_support = 0.3,
                         max_length = 2)

Description

Conditional correlations are patterns that identify strong relationships between pairs of numeric variables under specific conditions.

Scheme:

xvar ~ yvar | C

xvar and yvar highly correlates in data that satisfy the condition C.

Example:

study_time ~ test_score | hard_exam

For hard exams, the amount of study time is highly correlated with the obtained exam's test score.

The function computes correlations between all combinations of xvars and yvars columns of x in multiple sub-data corresponding to conditions generated from condition columns.

Usage

dig_correlations(
  x,
  condition = where(is.logical),
  xvars = where(is.numeric),
  yvars = where(is.numeric),
  disjoint = var_names(colnames(x)),
  excluded = NULL,
  method = "pearson",
  alternative = "two.sided",
  exact = NULL,
  min_length = 0L,
  max_length = Inf,
  min_support = 0,
  max_support = 1,
  max_results = Inf,
  verbose = FALSE,
  threads = 1
)

Arguments

Value

An S3 object which is an instance of correlations and nugget classes and which is tibble with found patterns.

Author(s)

Michal Burda

See Also

dig(), stats::cor.test()

Examples

# convert iris$Species into dummy logical variables
d <- partition(iris, Species)

# find conditional correlations between all pairs of numeric variables
dig_correlations(d,
                 condition = where(is.logical),
                 xvars = Sepal.Length:Petal.Width,
                 yvars = Sepal.Length:Petal.Width)

# With `condition = NULL`, dig_correlations() computes correlations between
# all pairs of numeric variables on the whole dataset only, which is an
# alternative way of computing the correlation matrix
dig_correlations(iris,
                 condition = NULL,
                 xvars = Sepal.Length:Petal.Width,
                 yvars = Sepal.Length:Petal.Width)

Description

This function creates a grid column names specified by xvars and yvars (see var_grid()). After that, it enumerates all conditions created from data in x (by calling dig()) and for each such condition and for each row of the grid of combinations, a user-defined function f is executed on each sub-data created from x by selecting all rows of x that satisfy the generated condition and by selecting the columns in the grid's row.

Function is useful for searching for patterns that are based on the relationships between pairs of columns, such as in dig_correlations().

Usage

dig_grid(
  x,
  f,
  condition = where(is.logical),
  xvars = where(is.numeric),
  yvars = where(is.numeric),
  disjoint = var_names(colnames(x)),
  excluded = NULL,
  allow = "all",
  na_rm = FALSE,
  type = "crisp",
  min_length = 0L,
  max_length = Inf,
  min_support = 0,
  max_support = 1,
  max_results = Inf,
  verbose = FALSE,
  threads = 1L,
  error_context = list(arg_x = "x", arg_f = "f", arg_condition = "condition", arg_xvars =
    "xvars", arg_yvars = "yvars", arg_disjoint = "disjoint", arg_excluded = "excluded",
    arg_allow = "allow", arg_na_rm = "na_rm", arg_type = "type", arg_min_length =
    "min_length", arg_max_length = "max_length", arg_min_support = "min_support",
    arg_max_support = "max_support", arg_max_results = "max_results", arg_verbose =
    "verbose", arg_threads = "threads", call = current_env())
)

Arguments

Value

An S3 object, which is an instance of nugget class, and which is a tibble with found patterns. Each row represents a single call of the callback function f.

Author(s)

Michal Burda

See Also

dig(), var_grid(); see also dig_correlations() and dig_paired_baseline_contrasts(), as they are using this function internally.

Examples

# *** Example of crisp (boolean) patterns:
# dichotomize iris$Species
crispIris <- partition(iris, Species)

# a simple callback function that computes mean difference of `xvar` and `yvar`
f <- function(pd) {
    list(m = mean(pd[[1]] - pd[[2]]),
         n = nrow(pd))
    }

# call f() for each condition created from column `Species`
dig_grid(crispIris,
         f,
         condition = starts_with("Species"),
         xvars = starts_with("Sepal"),
         yvars = starts_with("Petal"),
         type = "crisp")

# *** Example of fuzzy patterns:
# create fuzzy sets from Sepal columns
fuzzyIris <- partition(iris,
                       starts_with("Sepal"),
                       .method = "triangle",
                       .breaks = 3)

# a simple callback function that computes a weighted mean of a difference of
# `xvar` and `yvar`
f <- function(d, weights) {
    list(m = weighted.mean(d[[1]] - d[[2]], w = weights),
         w = sum(weights))
}

# call f() for each fuzzy condition created from column fuzzy sets whose
# names start with "Sepal"
dig_grid(fuzzyIris,
         f,
         condition = starts_with("Sepal"),
         xvars = Petal.Length,
         yvars = Petal.Width,
         type = "fuzzy")

Description

Paired baseline contrast patterns identify conditions under which there is a significant difference in some statistical feature between two paired numeric variables.

Scheme:

(xvar - yvar) != 0 | C

There is a statistically significant difference between paired variables xvar and yvar under the condition C.

Example:

(daily_ice_cream_income - daily_tea_income) > 0 | sunny

Under the condition of sunny weather, the paired test shows that daily ice-cream income is significantly higher than the daily tea income.

The paired baseline contrast is computed using a paired version of a statistical test, which is specified by the method argument. The function computes the paired contrast between all pairs of variables, where the first variable is specified by the xvars argument and the second variable is specified by the yvars argument. Paired baseline contrasts are computed in sub-data corresponding to conditions generated from the condition columns. Function dig_paired_baseline_contrasts() supports crisp conditions only, i.e., the condition columns in x must be logical.

Usage

dig_paired_baseline_contrasts(
  x,
  condition = where(is.logical),
  xvars = where(is.numeric),
  yvars = where(is.numeric),
  disjoint = var_names(colnames(x)),
  excluded = NULL,
  min_length = 0L,
  max_length = Inf,
  min_support = 0,
  max_support = 1,
  method = "t",
  alternative = "two.sided",
  h0 = 0,
  conf_level = 0.95,
  max_p_value = 1,
  t_var_equal = FALSE,
  wilcox_exact = FALSE,
  wilcox_correct = TRUE,
  wilcox_tol_root = 1e-04,
  wilcox_digits_rank = Inf,
  max_results = Inf,
  verbose = FALSE,
  threads = 1
)

Arguments

Value

An S3 object which is an instance of paired_baseline_contrasts and nugget classes and which is a tibble with found patterns in rows. The following columns are always present:

For the "t" method, the following additional columns are also present (see also t.test()):

Author(s)

Michal Burda

See Also

dig_baseline_contrasts(), dig_complement_contrasts(), dig(), dig_grid(), stats::t.test(), stats::wilcox.test()

Examples

# Compute ratio of sepal and petal length and width for iris dataset
crispIris <- iris
crispIris$Sepal.Ratio <- iris$Sepal.Length / iris$Sepal.Width
crispIris$Petal.Ratio <- iris$Petal.Length / iris$Petal.Width

# Create predicates from the Species column
crispIris <- partition(crispIris, Species)

# Compute paired contrasts for ratios of sepal and petal length and width
dig_paired_baseline_contrasts(crispIris,
                              condition = where(is.logical),
                              xvars = Sepal.Ratio,
                              yvars = Petal.Ratio,
                              method = "t",
                              min_support = 0.1)

Description

This function finds tautologies in a dataset, i.e., rules of the form ⁠{a1 & a2 & ... & an} => {c}⁠ where a1, a2, ..., an are antecedents and c is a consequent. The intent of searching for tautologies is to find rules that are always true, which may be used for filtering of further generated conditions. The resulting rules may be used as a basis for the list of excluded formulae (see the excluded argument of dig()).

The search for tautologies is performed by iteratively searching for rules with increasing length of the antecedent. Rules found in previous iterations are used as excluded argument in the next iteration.

Usage

dig_tautologies(
  x,
  antecedent = everything(),
  consequent = everything(),
  disjoint = var_names(colnames(x)),
  max_length = Inf,
  min_coverage = 0,
  min_support = 0,
  min_confidence = 0,
  contingency_table = deprecated(),
  t_norm = "goguen",
  max_results = Inf,
  verbose = FALSE,
  threads = 1
)

Arguments

Value

An S3 object which is an instance of associations and nugget classes and which is a tibble with found tautologies in the format equal to the output of dig_associations().

Author(s)

Michal Burda

Examples

d <- partition(mtcars, .breaks = 2)
dig_tautologies(d,
                antecedent = everything(),
                consequent = everything(),
                min_confidence = 0.99)

Description

Launches an interactive Shiny application for visual exploration of mined association rules. The explorer provides tools for inspecting rule quality, comparing interestingness measures, and interactively filtering subsets of rules. When the original dataset is supplied, the application also allows for contextual exploration of rules with respect to the underlying data.

Usage

## S3 method for class 'associations'
explore(x, data = NULL, ...)

Arguments

Value

An object of class shiny.appobj representing the Shiny application. When "printed" in an interactive R session, the application is launched immediately in the default web browser.

Author(s)

Michal Burda

See Also

dig_associations()

Examples

## Not run: 
data("iris")
# convert all columns into dummy logical variables
part <- partition(iris, .breaks = 3)

# find association rules
rules <- dig_associations(part)

# launch the interactive explorer
explore(rules, data = part)

## End(Not run)

Description

Launches an interactive Shiny application for visual exploration of baseline contrast patterns. The explorer provides tools for inspecting pattern quality, comparing measures, and interactively filtering subsets of patterns. When the original dataset is supplied, the application also allows for contextual exploration of contrasts with respect to the underlying data.

Usage

## S3 method for class 'baseline_contrasts'
explore(x, data = NULL, ...)

Arguments

Value

An object of class shiny.appobj representing the Shiny application. When "printed" in an interactive R session, the application is launched immediately in the default web browser.

Author(s)

Michal Burda

See Also

dig_baseline_contrasts()

Examples

## Not run: 
d <- partition(mtcars, .breaks = 2, .keep = TRUE)
res <- dig_baseline_contrasts(d,
                              condition = where(is.logical),
                              vars = where(is.numeric),
                              min_support = 0.3,
                              max_length = 2)

# launch the interactive explorer
explore(res, data = d)

## End(Not run)

Description

Launches an interactive Shiny application for visual exploration of complement contrast patterns. The explorer provides tools for inspecting pattern quality, comparing measures, and interactively filtering subsets of patterns. When the original dataset is supplied, the application also allows for contextual exploration of contrasts with respect to the underlying data.

Usage

## S3 method for class 'complement_contrasts'
explore(x, data = NULL, ...)

Arguments

Value

An object of class shiny.appobj representing the Shiny application. When "printed" in an interactive R session, the application is launched immediately in the default web browser.

Author(s)

Michal Burda

See Also

dig_complement_contrasts()

Examples

## Not run: 
d <- partition(mtcars, .breaks = 2, .keep = TRUE)
res <- dig_complement_contrasts(d,
                                condition = where(is.logical),
                                vars = where(is.numeric),
                                min_support = 0.3,
                                max_length = 2)

# launch the interactive explorer
explore(res, data = d)

## End(Not run)

Description

Launches an interactive Shiny application for visual exploration of conditional correlation patterns. The explorer provides tools for inspecting pattern quality, comparing measures, and interactively filtering subsets of patterns. When the original dataset is supplied, the application also allows for contextual exploration of correlations with respect to the underlying data.

Usage

## S3 method for class 'correlations'
explore(x, data = NULL, ...)

Arguments

Value

An object of class shiny.appobj representing the Shiny application. When "printed" in an interactive R session, the application is launched immediately in the default web browser.

Author(s)

Michal Burda

See Also

dig_correlations()

Examples

## Not run: 
d <- partition(iris, Species)
res <- dig_correlations(d,
                        condition = where(is.logical),
                        xvars = Sepal.Length:Petal.Width,
                        yvars = Sepal.Length:Petal.Width)

# launch the interactive explorer
explore(res, data = d)

## End(Not run)

Description

Launches an interactive Shiny application for visual exploration of paired baseline contrast patterns. The explorer provides tools for inspecting pattern quality, comparing measures, and interactively filtering subsets of patterns. When the original dataset is supplied, the application also allows for contextual exploration of contrasts with respect to the underlying data.

Usage

## S3 method for class 'paired_baseline_contrasts'
explore(x, data = NULL, ...)

Arguments

Value

An object of class shiny.appobj representing the Shiny application. When "printed" in an interactive R session, the application is launched immediately in the default web browser.

Author(s)

Michal Burda

See Also

dig_paired_baseline_contrasts()

Examples

## Not run: 
crispIris <- iris
crispIris$Sepal.Ratio <- iris$Sepal.Length / iris$Sepal.Width
crispIris$Petal.Ratio <- iris$Petal.Length / iris$Petal.Width
crispIris <- partition(crispIris, Species)
res <- dig_paired_baseline_contrasts(crispIris,
                                     condition = where(is.logical),
                                     xvars = Sepal.Ratio,
                                     yvars = Petal.Ratio,
                                     method = "t",
                                     min_support = 0.1)

# launch the interactive explorer
explore(res, data = crispIris)

## End(Not run)

Description

Given a data frame or matrix of truth values for predicates, compute the truth values of a set of conditions expressed as elementary conjunctions.

Each element of condition must be a character string of the format "{p1,p2,p3}", where "p1", "p2", and "p3" are predicate names. The data object x must contain columns whose names correspond exactly to all predicates referenced in the conditions. Each condition is evaluated for every row of x as a conjunction of its predicates, with the conjunction operation determined by the t_norm argument. An empty condition ("{}") is always evaluated as 1 (i.e., fully true).

Usage

fire(x, condition, t_norm = "goguen")

Arguments

Value

A numeric matrix with entries in the interval $[0, 1]$ giving the truth degrees of the conditions. The matrix has nrow(x) rows and length(condition) columns. The element in row i and column j corresponds to the truth degree of the j-th condition evaluated on the i-th row of x.

Author(s)

Michal Burda

See Also

format_condition(), partition()

Examples

d <- data.frame(
  a = c(1, 0.8, 0.5, 0.2, 0),
  b = c(0.5, 1, 0.5, 0, 1),
  c = c(0.9, 0.9, 0.1, 0.8, 0.7)
)

# Evaluate conditions with different t-norms
fire(d, c("{a,c}", "{}", "{a,b,c}"), t_norm = "goguen")
fire(d, c("{a,c}", "{a,b}"), t_norm = "goedel")
fire(d, c("{b,c}"), t_norm = "lukas")

Description

Convert a character vector of predicate names into a standardized string representation of a condition. Predicates are concatenated with commas and enclosed in curly braces. This formatting ensures consistency when storing or comparing conditions in other functions.

Usage

format_condition(condition)

Arguments

Value

A character scalar containing the formatted condition string.

Author(s)

Michal Burda

See Also

parse_condition(), fire()

Examples

format_condition(NULL)
format_condition(character(0))
format_condition(c("a", "b", "c"))

Description

Create a custom ggplot2 geom for visualizing lattice structures as diamond plots. This geom is particularly useful for displaying association rules and their ancestor–descendant relationships in a clear, compact graphical form.

In a diamond plot, nodes (diamonds) represent items or conditions within the lattice, while edges denote inclusion (subset) relationships between them. The geom combines node and edge rendering with flexible control over aesthetics such as labels, color, and size.

Usage

geom_diamond(
  mapping = NULL,
  data = NULL,
  stat = "identity",
  position = "identity",
  na.rm = FALSE,
  linetype = "solid",
  neg_linetype = "31",
  linecolour = "#999999",
  neg_linecolour = "#cc9999",
  linewidth = NA,
  nudge_x = 0,
  nudge_y = 0.125,
  show.legend = NA,
  inherit.aes = TRUE,
  ...
)

Arguments

Details

Concept overview

A lattice represents inclusion relationships between conditions. Each node corresponds to a condition, and a line connects a condition to its direct descendants:

       {a}          <- ancestor (parent)
      /   \
  {a,b}   {a,c}     <- direct descendants (children)
     \     /
     {a,b,c}        <- leaf condition

The layout positions broader (more general) conditions above their descendants. This helps visualize hierarchical structures such as those produced by association rule mining or subset lattices.

Supported aesthetics

• condition – character vector of conditions formatted with format_condition(). Each condition defines one node in the lattice. The hierarchy is determined by subset inclusion: a condition $X$ is a descendant of $Y$ if $Y \subset X$. Each condition must be unique.

• label – optional text label for each node. If omitted, the condition string is used.

• colour – border color of the node.

• fill – interior color of the node.

• size – size of nodes.

• shape – node shape.

• alpha – transparency of nodes.

• stroke – border line width of nodes.

• linewidth – edge width between parent and child nodes, computed as the difference of this aesthetic between them.

Value

A ggplot2 layer object that adds a diamond lattice visualization to an existing plot.

Author(s)

Michal Burda

Examples

## Not run: 
library(ggplot2)

# Prepare data by partitioning numeric columns into fuzzy or crisp sets
part <- partition(iris, .breaks = 3)

# Find all antecedents with "Sepal" for rules with consequent "Species=setosa"
rules <- dig_associations(part,
                          antecedent = starts_with("Sepal"),
                          consequent = `Species=setosa`,
                          min_length = 0,
                          max_length = Inf,
                          min_coverage = 0,
                          min_support = 0,
                          min_confidence = 0,
                          measures = c("lift", "conviction"),
                          max_results = Inf)

# Add abbreviated labels for readability
rules$abbrev <- shorten_condition(rules$antecedent)

# Plot the lattice of rules as a diamond diagram
ggplot(rules) +
  aes(condition = antecedent,
      fill = confidence,
      linewidth = confidence,
      size = coverage,
      label = abbrev) +
  geom_diamond()

## End(Not run)

Description

Check if a vector contains (almost) the same value in the majority of its elements. The function returns TRUE if the proportion of the most frequent value in x is greater than or equal to the specified threshold.

This is useful for detecting low-variability or degenerate variables, which may be uninformative in modeling or analysis.

Usage

is_almost_constant(x, threshold = 1, na_rm = FALSE)

Arguments

Value

A logical scalar. Returns TRUE in the following cases:

• x is empty or has length one.

• x contains only NA values.

• The proportion of the most frequent value in x is greater than or equal to threshold. Otherwise, returns FALSE.

Author(s)

Michal Burda

See Also

remove_almost_constant(), unique(), table()

Examples

is_almost_constant(1)
is_almost_constant(1:10)
is_almost_constant(c(NA, NA, NA), na_rm = TRUE)
is_almost_constant(c(NA, NA, NA), na_rm = FALSE)
is_almost_constant(c(NA, NA, NA, 1, 2), threshold = 0.5, na_rm = FALSE)
is_almost_constant(c(NA, NA, NA, 1, 2), threshold = 0.5, na_rm = TRUE)

Description

A valid condition is a character vector of predicate names, where each predicate corresponds to a column name in a given data frame or matrix. This function verifies that each element of a list x contains only valid predicates that match column names of data.

Special cases:

• An empty character vector (character(0)) is considered a valid condition and always passes the check.

• A NULL element is treated the same as an empty character vector, i.e., it is also a valid condition.

Usage

is_condition(x, data)

Arguments

Value

A logical vector with one element for each condition in x. An element is TRUE if the corresponding condition is valid, i.e. all of its predicates are column names of data. Otherwise, it is FALSE.

Author(s)

Michal Burda

See Also

remove_ill_conditions(), format_condition()

Examples

d <- data.frame(foo = 1:5, bar = 1:5, blah = 1:5)

is_condition(list("foo"), d)
is_condition(list(c("bar", "blah"), NULL, c("foo", "bzz")), d)

Description

Check if the input consists only of numeric values between 0 and 1, inclusive. This is often useful when validating truth degrees, membership values in fuzzy sets, or probabilities.

Usage

is_degree(x, na_rm = FALSE)

Arguments

Value

A logical scalar. Returns TRUE if all (non-NA) elements of x are numeric and lie within the closed interval $[0,1]$. Returns FALSE if:

• x contains any NA values and na_rm = FALSE

• any element is outside the interval $[0,1]$

• x is not numeric

• x is empty (length(x) == 0)

Author(s)

Michal Burda

See Also

is.numeric()

Examples

is_degree(0.5)
is_degree(c(0, 0.2, 1))
is_degree(c(0.5, NA), na_rm = TRUE)   # TRUE
is_degree(c(0.5, NA), na_rm = FALSE)  # FALSE
is_degree(c(-0.1, 0.5))               # FALSE
is_degree(numeric(0))                 # FALSE

Description

Check if an object is logical or numeric with only 0s and 1s

Usage

is_logicalish(x)

Arguments

Value

A logical value indicating whether x is logical or numeric containing only 0s and 1s.

Author(s)

Michal Burda

Examples

is_logicalish(c(TRUE, FALSE, NA))        # returns TRUE
is_logicalish(c(0, 1, 1, 0, NA))         # returns TRUE
is_logicalish(c(0.0, 1.0, NA))           # returns TRUE
is_logicalish(c(0, 0.5, 1))              # returns FALSE
is_logicalish("TRUE")                    # returns FALSE

Description

Check if the given object is a nugget, i.e. an object created by nugget(). If a flavour is specified, the function returns TRUE only if the object is a nugget of the given flavour.

Technically, nuggets are implemented as S3 objects. An object is considered a nugget if it inherits from the S3 class "nugget". It is a nugget of a given flavour if it inherits from both the specified flavour class and the "nugget" class.

Usage

is_nugget(x, flavour = NULL)

Arguments

Value

A logical scalar: TRUE if x is a nugget (and of the specified flavour, if given), otherwise FALSE.

Author(s)

Michal Burda

See Also

nugget()

Examples

d <- partition(mtcars, .breaks = 2)
rules <- dig_associations(d, min_support = 0.3)
is_nugget(rules)
is_nugget(rules, "associations")
is_nugget(mtcars)

Description

Check if all elements of x are also contained in y. This is equivalent to testing whether setdiff(x, y) is empty.

Usage

is_subset(x, y)

Arguments

Details

• If x is empty, the result is always TRUE (the empty set is a subset of any set).

• If y is empty and x is not, the result is FALSE.

• Duplicates in x are ignored; only set membership is tested.

• NA values are treated as ordinary elements. In particular, NA in x is considered a subset element only if NA is also present in y.

Value

A logical scalar. Returns TRUE if x is a subset of y, i.e. all elements of x are also elements of y. Returns FALSE otherwise.

Author(s)

Michal Burda

See Also

base::setdiff(), base::intersect(), base::union()

Examples

is_subset(1:3, 1:5)               # TRUE
is_subset(c(2, 5), 1:4)           # FALSE
is_subset(numeric(0), 1:5)        # TRUE
is_subset(1:3, numeric(0))        # FALSE
is_subset(c(1, NA), c(1, 2, NA))  # TRUE
is_subset(c(NA), 1:5)             # FALSE

Description

Construct a nugget object, which is an S3 object used to store and represent results (e.g., rules or patterns) in the nuggets framework.

A nugget is technically a tibble (or data frame) that inherits from both the "nugget" class and, optionally, a flavour-specific S3 class. This allows distinguishing different types of nuggets (flavours) while still supporting generic methods for all nuggets.

Usage

nugget(x, flavour, call_function, call_data, call_args)

Arguments

Details

Each nugget stores additional provenance information in attributes:

• "call_function" — the name of the function that created the nugget.

• "call_args" — the list of arguments passed to that function.

These attributes make it possible to reconstruct or track how the nugget was created, which supports reproducibility, transparency, and debugging. For example, one can inspect attr(n, "call_args") to recover the original parameters used to mine the patterns.

Value

A tibble object that is an S3 subclass of "nugget" and, if specified, the given flavour class. The object also contains attributes "call_function" and "call_args" describing its provenance.

Author(s)

Michal Burda

See Also

is_nugget()

Examples

df <- data.frame(lhs = c("a", "b"), rhs = c("c", "d"))
n <- nugget(df,
            flavour = "rules",
            call_function = "example_function",
            call_data = list(ncol = 2,
                             nrow = 2,
                             colnames = c("lhs", "rhs")),
            call_args = list(data = "mydata"))

inherits(n, "nugget")      # TRUE
inherits(n, "rules")       # TRUE
attr(n, "call_function")   # "dig_example_function"
attr(n, "call_args")       # list(data = "mydata")

Description

Parse a character vector of conditions into a list of predicate vectors. Each element of the list corresponds to one condition. A condition is a string of predicates separated by commas and enclosed in curly braces, as produced by format_condition(). The function splits each string into its component predicates.

If multiple vectors of conditions are provided via ..., they are combined element-wise. The result is a single list where each element is formed by merging the predicates from the corresponding elements of all input vectors. If the input vectors differ in length, shorter ones are recycled.

Empty conditions ("{}") are parsed as empty character vectors (character(0)).

Usage

parse_condition(..., .sort = FALSE)

Arguments

Value

A list of character vectors, where each element corresponds to one condition and contains the parsed predicates.

Author(s)

Michal Burda

See Also

format_condition(), is_condition(), fire()

Examples

parse_condition(c("{a}", "{x=1, z=2, y=3}", "{}"))

# Merge conditions from multiple vectors element-wise
parse_condition(c("{b}", "{x=1, z=2, y=3}", "{q}", "{}"),
                c("{a}", "{v=10, w=11}",    "{}",  "{r,s,t}"))

# Sorting predicates within each condition
parse_condition("{z,y,x}", .sort = TRUE)

Description

Transform selected columns of a data frame into either dummy logical variables or membership degrees of fuzzy sets, while leaving all remaining columns unchanged. Each transformed column typically produces multiple new columns in the output.

These transformations are most often used as a preprocessing step before calling dig() or one of its derivatives, such as dig_correlations(), dig_paired_baseline_contrasts(), or dig_associations().

The transformation depends on the column type:

• logical column x is expanded into two logical columns: x=TRUE and x=FALSE;

• factor column x with levels l1, l2, l3 becomes three logical columns: x=l1, x=l2, and x=l3;

• numeric column x is transformed according to .method:

  • .method = "dummy": the column is treated as a factor with one level per unique value, then expanded into dummy columns;

  • .method = "crisp": the column is discretized into intervals (defined by .breaks, .style, and .style_params) and expanded into dummy columns representing those intervals;

  • .method = "triangle" or .method = "raisedcos": the column is converted into one or more fuzzy sets, each represented by membership degrees in $[0,1]$ (triangular or raised-cosine shaped).

Details of numeric transformations are controlled by .breaks, .labels, .style, .style_params, .right, .span, and .inc.

Usage

partition(
  .data,
  .what = everything(),
  ...,
  .breaks = NULL,
  .labels = NULL,
  .na = TRUE,
  .keep = FALSE,
  .method = "crisp",
  .style = "equal",
  .style_params = list(),
  .right = TRUE,
  .span = 1,
  .inc = 1
)

Arguments

Details

• Crisp partitioning is efficient and works well when attributes have distinct categories or clear boundaries.

• Fuzzy partitioning is recommended for modeling gradual changes or uncertainty, allowing smooth category transitions at a higher computational cost.

Value

A tibble with .data transformed into Boolean or fuzzy predicates.

Crisp transformation of numeric data

For .method = "crisp", numeric columns are discretized into a set of dummy logical variables, each representing one interval of values.

• If .breaks is an integer, it specifies the number of intervals into which the column should be divided. The intervals are determined using the .style and .style_params arguments, allowing not only equal-width but also data-driven breakpoints (e.g., quantile or k-means based). The first and last intervals automatically extend to infinity.

• If .breaks is a numeric vector, it specifies interval boundaries directly. Infinite values are allowed.

The .style argument defines how breakpoints are computed when .breaks is an integer. Supported methods (from classInt::classIntervals()) include:

• "equal" – equal-width intervals across the column range (default);

• "quantile" – equal-frequency intervals (see quantile() for additional parameters that may be passed through .style_params; note that the probs parameter is set automatically and should not be included in .style_params);

• "kmeans" – intervals found by 1D k-means clustering (see kmeans() for additional parameters);

• "sd" – intervals based on standard deviations from the mean;

• "hclust" – hierarchical clustering intervals (see hclust() for additional parameters);

• "bclust" – model-based clustering intervals (see e1071::bclust() for additional parameters);

• "fisher" / "jenks" – Fisher–Jenks optimal partitioning;

• "dpih" – kernel-based density partitioning (see KernSmooth::dpih() for additional parameters);

• "headtails" – head/tails natural breaks;

• "maximum" – maximization-based partitioning;

• "box" – breaks at boxplot hinges.

Additional parameters for these methods can be passed through .style_params, which should be a named list of arguments accepted by the respective algorithm in classInt::classIntervals(). For example, when .style = "kmeans", one can specify .style_params = list(algorithm = "Lloyd") to request Lloyd's algorithm for k-means clustering.

With .span = 1 and .inc = 1, the generated intervals are consecutive and non-overlapping. For example, with .breaks = c(1, 3, 5, 7, 9, 11) and .right = TRUE, the intervals are $(1;3]$, $(3;5]$, $(5;7]$, $(7;9]$, and $(9;11]$. If .right = FALSE, the intervals are left-closed: $[1;3)$, $[3;5)$, etc.

Larger .span values produce overlapping intervals. For example, with .span = 2, .inc = 1, and .right = TRUE, intervals are $(1;5]$, $(3;7]$, $(5;9]$, $(7;11]$.

The .inc argument controls how far the window shifts along .breaks.

• .span = 1, .inc = 2 → $(1;3]$, $(5;7]$, $(9;11]$.

• .span = 2, .inc = 3 → $(1;5]$, $(9;11]$.

Fuzzy transformation of numeric data

For .method = "triangle" or .method = "raisedcos", numeric columns are converted into fuzzy membership degrees in $[0,1]$.

• If .breaks is an integer, it specifies the number of fuzzy sets.

• If .breaks is a numeric vector, it directly defines fuzzy set boundaries. Infinite values produce open-ended sets.

With .span = 1, each fuzzy set is defined by three consecutive breaks: membership is 0 outside the outer breaks, rises to 1 at the middle break, then decreases back to 0 — yielding triangular or raised-cosine sets.

With .span > 1, fuzzy sets use four consecutive breaks: membership increases between the first two, remains 1 between the middle two, and decreases between the last two — creating trapezoidal sets. Border shapes are linear for .method = "triangle" and cosine for .method = "raisedcos".

The .inc argument defines the step between break windows:

• .span = 1, .inc = 1 → $(1;3;5)$, $(3;5;7)$, $(5;7;9)$, $(7;9;11)$.

• .span = 2, .inc = 1 → $(1;3;5;7)$, $(3;5;7;9)$, $(5;7;9;11)$.

• .span = 1, .inc = 3 → $(1;3;5)$, $(7;9;11)$.

Author(s)

Michal Burda

Examples

# Crisp transformation using equal-width bins
partition(CO2, conc, .method = "crisp", .breaks = 4)

# Crisp transformation using quantile-based bins
partition(CO2, conc, .method = "crisp", .breaks = 4, .style = "quantile")

# Crisp transformation using k-means clustering for breakpoints
partition(CO2, conc, .method = "crisp", .breaks = 4, .style = "kmeans")

# Crisp transformation using Lloyd algorithm for k-means clustering for breakpoints
partition(CO2, conc, .method = "crisp", .breaks = 4, .style = "kmeans",
          .style_params = list(algorithm = "Lloyd"))

# Fuzzy triangular transformation (default)
partition(CO2, conc:uptake, .method = "triangle", .breaks = 3)

# Raised-cosine fuzzy sets
partition(CO2, conc:uptake, .method = "raisedcos", .breaks = 3)

# Overlapping trapezoidal fuzzy sets (Ruspini condition)
partition(CO2, conc:uptake, .method = "triangle", .breaks = 3,
          .span = 2, .inc = 2)

# Different settings per column
CO2 |>
  partition(Plant:Treatment) |>
  partition(conc,
            .method = "raisedcos",
            .breaks = c(-Inf, 95, 175, 350, 675, 1000, Inf)) |>
  partition(uptake,
            .method = "triangle",
            .breaks = c(-Inf, 7.7, 28.3, 45.5, Inf),
            .labels = c("low", "medium", "high"))