Type:	Package
Title:	Numerical Association Rule Mining using Population-Based Nature-Inspired Algorithms
Version:	0.3.1
Classification/ACM:	G.4, H.2.8
Description:	Framework is devoted to mining numerical association rules through the utilization of nature-inspired algorithms for optimization. Drawing inspiration from the 'NiaARM' 'Python' and the 'NiaARM' 'Julia' packages, this repository introduces the capability to perform numerical association rule mining in the R programming language. Fister Jr., Iglesias, Galvez, Del Ser, Osaba and Fister (2018) <doi:10.1007/978-3-030-03493-1_9>.
URL:	https://github.com/firefly-cpp/niarules
BugReports:	https://github.com/firefly-cpp/niarules/issues
Depends:	R (≥ 4.0.0)
License:	MIT + file LICENSE
Encoding:	UTF-8
RoxygenNote:	7.3.2
Imports:	stats, utils, Rcpp, dplyr, rlang, rgl
Suggests:	testthat, withr
LinkingTo:	Rcpp
NeedsCompilation:	yes
Packaged:	2025-09-14 18:05:05 UTC; iztok
Author:	Iztok Jr. Fister [aut, cre, cph], Gerlinde Emsenhuber [aut], Jan Hendrik Plümer [aut]
Maintainer:	Iztok Jr. Fister <iztok@iztok.space>
Repository:	CRAN
Date/Publication:	2025-09-15 09:10:12 UTC

Add an attribute to the "rule" list.

Description

This function adds an attribute to the existing list.

Usage

add_attribute(rules, name, type, border1, border2, value)

Arguments

Value

The updated rules list.

Examples

rules <- list()
new_rules <- add_attribute(rules, "feature1", "numerical", 0.2, 0.8, "EMPTY")

Build coral plot layout (nodes + edges) from a parsed rules object

Description

Produces the node and edge layout consumed by 'render_coral_rgl()' or 'render_coral_rgl_experimental()'. Given a parsed association-rules object (from 'parse_rules()'), this function groups rules by RHS itemset (one coral per unique RHS), arranges those corals on a square grid, and emits geometry and metadata for drawing.

**Input expectations ('parsed')** - 'parsed$items': 'data.frame' with at least 'item_id' (integer, **0-based**), 'label' (character). - 'parsed$rules': 'data.frame' with at least 'support', 'confidence', 'lift' (numeric) and 'lhs_item_ids', 'rhs_item_ids' (list-columns of **0-based** integer vectors).

Usage

build_coral_plots(
  parsed,
  lhs_sort_metric = c("confidence", "support", "lift"),
  bin_breaks = NULL,
  bin_digits = 3
)

Arguments

Details

**Grid sizing.** The number of corals ('n_plots') is computed as the number of distinct, non-empty RHS itemsets across rules. An RHS itemset’s display label is recomposed by joining the 'items$label' values for its 'rhs_item_ids' (comma-separated). The grid is arranged as a near-square: 'grid_size = ceiling(sqrt(n_plots))', with a minimum of 1.

The heavy lifting (node positions, radii, edge routing) is delegated to the C++ backend 'build_layout_cpp()', which receives the 'parsed' object, the computed 'grid_size', and the chosen 'lhs_sort_metric'.

**Output schema (for 'render_coral_rgl()').** - 'nodes' includes (at least): 'x', 'z', 'x_offset', 'z_offset', 'radius', 'path' (character key), 'node_id', 'is_root', 'coral_id', 'interval_brackets', 'bin_index' and optionally 'item', 'feature', 'step', 'interval_label', 'interval_label_short'. - 'edges' includes (at least): 'x', 'y', 'z', 'x_end', 'y_end', 'z_end', 'parent_path', 'child_path', and the rule metrics 'support', 'confidence', 'lift'. (Initial 'y'/'y_end' are typically on the base plane; vertical styling can be added later by 'render_coral_rgl()' via 'y_scale'/jitter.)

**Indexing note.** Item identifiers remain **0-based** as produced by 'parse_rules()' for cross-language stability.

Value

A list with components: - 'nodes': 'data.frame' of node geometry and labels, - 'edges': 'data.frame' of edge geometry and attached metrics, - 'grid_size': integer grid side length used to arrange corals. - 'bin_legend': data.frame (or NULL) mapping feature -> bin index -> interval.

Entry point for R to generate coral plot data from a set of association rules.

Description

This function takes a list of parsed association rules and produces two data frames: one for the nodes and one for the edges of a coral plot. It acts as a wrapper that:

• Constructs the coral layout.

• Converts the resulting nodes and edges into R-compatible data frames.

Usage

build_layout_cpp(parsed, grid_size, lhs_sort = "confidence")

Arguments

Value

A List containing two DataFrames:

• edges: DataFrame with start and end coordinates, line width, and color for each edge.

• nodes: DataFrame with position, radius, ID, and item label for each node.

Build rules based on a candidate solution.

Description

This function takes a candidate solution vector and a features list and builds rule.

Usage

build_rule(solution, features)

Arguments

Value

A rule.

Calculate the border value based on feature information and a given value.

Description

This function calculates the border value for a feature based on the feature information and a given value.

Usage

calculate_border(feature_info, value)

Arguments

Value

The calculated border value.

Examples

feature_info <- list(type = "numerical", lower_bound = 0, upper_bound = 1)
border_value <- calculate_border(feature_info, 0.5)

Calculate the fitness of an association rule.

Description

This function calculates the fitness of an association rule using support and confidence.

Usage

calculate_fitness(supp, conf)

Arguments

Value

The fitness of the association rule.

Calculate the selected category based on a value and the number of categories.

Description

This function calculates the selected category based on a given value and the total number of categories.

Usage

calculate_selected_category(value, num_categories)

Arguments

Value

The calculated selected category.

Examples

selected_category <- calculate_selected_category(0.3, 5)

Check if the attribute conditions are satisfied for an instance.

Description

This function checks if the attribute conditions specified in the association rule are satisfied for a given instance row.

Usage

check_attribute(attribute, instance_row)

Arguments

Value

TRUE if conditions are satisfied, FALSE otherwise.

Get a theme object (experimental)

Description

‘r lifecycle::badge(’experimental')'

Usage

coral_get_theme(
  name = c("default", "studio", "flat", "dark", "none"),
  overrides = NULL
)

Arguments

Value

an object of class 'coral_theme'

Available themes (experimental)

Description

‘r lifecycle::badge(’experimental')'

Usage

coral_list_themes()

Value

character vector of theme names

Calculate the cut point for an association rule.

Description

This function calculates the cut point, denoting which part of the vector belongs to the antecedent and which to the consequent of the mined association rule.

Usage

cut_point(sol, num_attr)

Arguments

Value

The cut point value.

Implementation of Differential Evolution metaheuristic algorithm.

Description

This function uses Differential Evolution, a stochastic population-based optimization algorithm, to find the optimal numerical association rule.

Usage

differential_evolution(
  d = 10,
  np = 10,
  f = 0.5,
  cr = 0.9,
  nfes = 1000,
  features,
  data,
  is_time_series = FALSE
)

Arguments

Value

A list containing the best solution, its fitness value, and the number of function evaluations and list of identified association rules.

References

Storn, R., & Price, K. (1997). "Differential Evolution – A Simple and Efficient Heuristic for Global Optimization over Continuous Spaces." Journal of Global Optimization, 11(4), 341–359. doi:10.1023/A:1008202821328

Evaluate a candidate solution, with optional time series filtering.

Description

This function evaluates the fitness of an association rule using support and confidence. If time series data is used, it restricts evaluation to the specified time range.

Usage

evaluate(solution, features, instances, is_time_series = FALSE)

Arguments

Value

A list containing fitness and identified rules.

References

Fister, I., Iglesias, A., Galvez, A., Del Ser, J., Osaba, E., & Fister, I. (2018). "Differential evolution for association rule mining using categorical and numerical attributes." In Intelligent Data Engineering and Automated Learning–IDEAL 2018: 19th International Conference, Madrid, Spain, November 21–23, 2018, Proceedings, Part I (pp. 79-88). Springer International Publishing. doi:10.1007/978-3-030-03496-2_9

Fister Jr, I., Podgorelec, V., & Fister, I. (2021). "Improved nature-inspired algorithms for numeric association rule mining." In Intelligent Computing and Optimization: Proceedings of the 3rd International Conference on Intelligent Computing and Optimization 2020 (ICO 2020) (pp. 187-195). Springer International Publishing. doi:10.1007/978-3-030-68154-8_19

Extract feature information from a dataset, excluding timestamps.

Description

This function analyzes the given dataset and extracts information about each feature.

Usage

extract_feature_info(data, timestamp_col = "timestamp")

Arguments

Value

A list containing information about each feature, including type and bounds/categories.

Get the position of a feature.

Description

This function returns the position of a feature in the vector, considering the type of the feature.

Usage

feature_position(features, feature)

Arguments

Value

The position of the feature.

Examples

features <- list(
  feature1 = list(type = "numerical"),
  feature2 = list(type = "categorical"),
  feature3 = list(type = "numerical")
)
position <- feature_position(features, "feature2")

Fix Borders of a Numeric Vector

Description

This function ensures that all values greater than 1.0 are set to 1.0, and all values less than 0.0 are set to 0.0.

Usage

fix_borders(vector)

Arguments

Value

A numeric vector with borders fixed.

Format Rule Parts

Description

This function formats the parts of an association rule into a string.

Usage

format_rule_parts(parts)

Arguments

Value

A formatted string representing the rule parts.

Map solution boundaries to time series instances.

Description

This function maps the lower and upper bounds of the solution vector to a subset of the dataset.

Usage

map_to_ts(lower, upper, instances)

Arguments

Value

A list with 'low', 'up', and 'filtered_instances'.

Compute metric domains (experimental)

Description

‘r lifecycle::badge(’experimental')'

Returns numeric ranges [min, max] for the metrics 'support', 'confidence', and 'lift' from various input types.

Usage

metric_domains(x, ...)

## S3 method for class 'parsed'
metric_domains(x, ...)

## S3 method for class 'data.frame'
metric_domains(x, ...)

## Default S3 method:
metric_domains(x, ...)

Arguments

Value

A named list with numeric vectors of length 2: 'list(support = c(min, max), confidence = c(min, max), lift = c(min, max))'.

Parse association rules into a reusable, layout-agnostic structure

Description

Converts association rules into a normalized representation for downstream layout/rendering. Accepts either: - a 'data.frame' with **required** columns 'Antecedent', 'Consequence', 'Support', 'Confidence', 'Fitness', or - a native 'niarules' rules object (which is exported to CSV internally via 'niarules::write_association_rules_to_csv()' and then parsed).

The output separates **items** from **rules** and uses stable **0-based** item identifiers suitable for cross-language use.

Usage

parse_rules(arules = NULL)

Arguments

Details

**Input requirements** - 'Antecedent', 'Consequence': character encodings of itemsets per rule. - 'Support', 'Confidence', 'Fitness': numeric metrics; 'Fitness' is interpreted as the **lift-like** metric and is exposed as 'lift' in the returned 'rules'.

When 'arules' is not a 'data.frame', the function requires the **niarules** package at runtime to serialize the rules to CSV. Missing required columns trigger an error.

**Output schema** - 'items' ('data.frame'): 'item_id' (integer, **0-based**), 'label', 'feature', 'kind', 'category_value', 'lo', 'hi', 'incl_low', 'incl_high', 'op', 'label_long', 'label_short'. - 'rules' ('data.frame'): 'rule_id', 'support', 'confidence', 'lift', 'lhs_item_ids' (list of integer vectors; **0-based ids**), 'rhs_item_ids' (list of integer vectors; **0-based ids**), 'antecedent_length', 'consequent_length'.

**Indexing note** 'item_id' values are **0-based** for stability across languages. In R, convert to 1-based with 'items$item_id + 1L' if needed.

Value

A list with components: - 'items': 'data.frame' describing unique items, - 'rules': 'data.frame' describing association rules.

Low-level C++ parser for association rules

Description

'parse_rules_cpp()' is the Rcpp-exposed engine behind parse_rules. It accepts a data frame of association rules and returns a layout-agnostic parsed structure consisting of an items table and a rules table. This function is exported by Rcpp primarily for internal use and testing.

Usage

parse_rules_cpp(rules_df)

Arguments

Details

Parsing rules

• Both LHS and RHS are split on "," or "&" outside of brackets; leading/trailing whitespace is trimmed.

• A single outer brace pair {...} on RHS is stripped if present.

• Supported item syntaxes:

  • Categorical equality: feature = value (value may be quoted).

  • Numeric interval: feature in [lo, hi], (lo, hi], etc.

  • Relational: feature >= x, > x, <= x, < x.

• For relational items, the unused bound is set to NA.

• Fitness is carried through as lift.

Value

A list with two data frames:

items

Columns:

• item_id: integer, 0-based stable ID within this parsed object.

• label: original item string.

• feature: base feature name.

• kind: one of "numeric", "categorical", "set", "unknown".

• category_value: categorical value (quotes removed).

• lo, hi: numeric bounds (may be NA).

• incl_low, incl_high: logical inclusivity flags.

• op: one of "<", "<=", ">", ">=", "=", "in".

• label_long, label_short: preformatted interval labels.

rules

Columns:

• rule_id: 1-based rule index (for display).

• support, confidence, lift: rule-level metrics.

• lhs_item_ids, rhs_item_ids: list-columns of integer vectors of 0-based item_ids.

• antecedent_length, consequent_length: integer lengths of LHS/RHS.

Errors

Throws an error if required columns are missing or have inconsistent lengths.

Implementation of Particle Swarm Optimization (PSO) metaheuristic algorithm.

Description

This function uses PSO, a stochastic population-based optimization algorithm, to find the optimal numerical association rule.

Usage

particle_swarm_optimization(
  d = 10,
  np = 10,
  w = 0.7,
  c1 = 1.5,
  c2 = 1.5,
  nfes = 1000,
  features,
  data,
  is_time_series = FALSE
)

Arguments

Value

A list containing the best solution, its fitness value, and the number of function evaluations and list of identified association rules.

References

Kennedy, J., & Eberhart, R. (1995). "Particle swarm optimization." Proceedings of ICNN'95 - International Conference on Neural Networks, 4, 1942–1948. IEEE. doi:10.1109/ICNN.1995.488968

Print Numerical Association Rules

Description

This function prints association rules including antecedent, consequence, support, confidence, and fitness. For time series datasets, it also includes the start and end timestamps instead of indices.

Usage

print_association_rules(rules, is_time_series = FALSE, timestamps = NULL)

Arguments

Value

Prints the association rules.

Print feature information extracted from a dataset.

Description

This function prints the information extracted about each feature.

Usage

print_feature_info(feature_info)

Arguments

Value

A message is printed to the console for each feature, providing information about the feature's type, and additional details such as lower and upper bounds for numerical features, or categories for categorical features. No explicit return value is generated.

Calculate the dimension of the problem, excluding timestamps.

Description

Calculate the dimension of the problem, excluding timestamps.

Usage

problem_dimension(feature_info, is_time_series = FALSE)

Arguments

Value

The calculated dimension based on the feature types.

Read a CSV Dataset

Description

Reads a dataset from a CSV file and optionally parses a timestamp column.

Usage

read_dataset(
  dataset_path,
  timestamp_col = "timestamp",
  timestamp_formats = c("%d/%m/%Y %H:%M:%S", "%H:%M:%S %d/%m/%Y")
)

Arguments

Value

A data frame containing the dataset.

Apply styling to coral plots and render them with rgl

Description

Renders a 3D "coral" plot produced by 'build_coral_layout()', with edge width/color/alpha mapped from association rule metrics and node colors derived from item/type groupings. The function draws a floor grid, edges as 3D segments, nodes as spheres, and optional labels/legend.

**Required columns** - 'edges': 'x', 'y', 'z', 'x_end', 'y_end', 'z_end', 'parent_path', 'child_path', and metric columns 'support', 'confidence', 'lift'. - 'nodes': 'x', 'z', 'x_offset', 'z_offset', 'radius', 'path'.

**Optional columns** - 'nodes$item', 'nodes$feature' (for labels/legend & color-by), 'nodes$step' (roots identified as 'step == 0'), 'nodes$interval_label', 'nodes$interval_label_short' (label text when requested).

Usage

render_coral_rgl(
  nodes,
  edges,
  grid_size,
  grid_color = "grey80",
  legend = FALSE,
  label_mode = c("none", "interval", "item", "interval_short"),
  label_cex = 0.7,
  label_offset = 1.5,
  max_labels = 100,
  edge_width_metric = c("confidence", "lift", "support"),
  edge_color_metric = c("confidence", "lift", "support"),
  edge_alpha_metric = NULL,
  edge_width_range = c(1, 5),
  edge_width_transform = c("linear", "sqrt", "log"),
  edge_gradient = c("#2166AC", "#67A9CF", "#D1E5F0", "#FDDBC7", "#EF8A62", "#B2182B"),
  edge_color_transform = c("linear", "sqrt", "log"),
  edge_alpha = 0.5,
  edge_alpha_range = c(0.25, 0.5),
  edge_alpha_transform = c("linear", "sqrt", "log"),
  node_color_by = c("type", "item", "none", "edge_incoming", "edge_outgoing_mean"),
  node_gradient = "match",
  node_gradient_map = c("even", "hash", "frequency"),
  y_scale = 0,
  jitter_sd = 0,
  jitter_mode = c("deterministic", "random"),
  jitter_seed = NULL,
  return_data = FALSE
)

Arguments

Details

Metric scaling uses the helper '.norm_metric()' which: 1) rescales the chosen metric to '[0,1]' over finite values, and 2) applies the selected transform: - '"linear"': identity, - '"sqrt"': emphasizes differences at the low end, - '"log"': 'log1p(9*t)/log(10)', emphasizing very small values.

Node elevation ('y') is computed as 'y_scale * r_norm' where 'r_norm' is the node’s radial distance from its center normalized to the max within that coral. Optional jitter is added (fading to zero at the center). Root nodes ('step == 0') that overlap are vertically stacked with small stems for readability.

Value

Invisibly returns 'NULL' after drawing. If 'return_data = TRUE', returns (invisibly) a list with components: - 'nodes': input 'nodes' with added columns 'y', 'color' (and possibly stacked draw positions for roots), - 'edges': input 'edges' with added columns 'width', 'color', 't_color_norm', 'y', 'y_end', and 'width_binned'.

Requirements

Requires an interactive OpenGL device ('rgl'). On headless systems, consider using an off-screen context or skipping examples.

Coral 3D renderer (experimental)

Description

‘r lifecycle::badge(’experimental')' API and argument names may change before 0.4.0.

Renders a 3D "coral" plot produced by 'build_coral_layout()', with edge width/color/alpha mapped from association rule metrics and node colors derived from item/type groupings. The function draws a floor grid, edges as 3D segments, nodes as spheres, and optional labels/legend.

**Required columns** - 'edges': 'parent_path', 'child_path', and metric columns 'support', 'confidence', 'lift'. (Endpoint coordinates 'x', 'y', 'z', 'x_end', 'y_end', 'z_end' are recomputed by this function.) - 'nodes': 'x', 'z', 'x_offset', 'z_offset', 'radius', 'path'.

**Optional columns** - 'nodes$item', 'nodes$feature' (for labels/legend & color-by), 'nodes$step' (roots identified as 'step == 0'), 'nodes$interval_label', 'nodes$interval_label_short' (label text when requested).

Usage

render_coral_rgl_experimental(
  nodes,
  edges,
  grid_size,
  grid_outline = FALSE,
  grid_color = "grey92",
  legend = FALSE,
  legend_style = c("auto", "feature", "grouped", "feature_bins"),
  legend_cex = 1,
  legend_pos = c("inside_right", "topright", "topleft", "custom"),
  legend_items_per_feature = 6L,
  legend_features_max = 10L,
  legend_xy = c(0.92, 0.96),
  legend_panel_width = 0.28,
  legend_panel_margin = 0.02,
  legend_reserve = NULL,
  legend_title_cex = NULL,
  legend_row_cex = NULL,
  legend_col_gap = 0.004,
  label_mode = c("none", "interval", "item", "interval_short", "bin"),
  label_cex = 0.7,
  label_offset = 1.5,
  label_color = NULL,
  label_non_numeric = c("none", "category", "item"),
  max_labels = 0,
  bin_legend = NULL,
  bin_breaks = NULL,
  bin_infer = TRUE,
  bin_label_fmt = c("index", "roman"),
  theme = c("default", "studio", "flat", "dark", "none"),
  theme_overrides = NULL,
  apply_theme = TRUE,
  edge_width_domain = NULL,
  edge_color_domain = NULL,
  edge_alpha_domain = NULL,
  edge_width_metric = c("confidence", "lift", "support"),
  edge_color_metric = c("confidence", "lift", "support"),
  edge_alpha_metric = NULL,
  edge_width_range = c(1, 5),
  edge_width_transform = c("linear", "sqrt", "log"),
  edge_gradient = c("#2166AC", "#67A9CF", "#D1E5F0", "#FDDBC7", "#EF8A62", "#B2182B"),
  edge_color_transform = c("linear", "sqrt", "log"),
  edge_alpha = 0.5,
  edge_alpha_range = c(0.25, 0.5),
  edge_alpha_transform = c("linear", "sqrt", "log"),
  node_color_by = c("type", "item", "none", "edge_incoming", "edge_outgoing_mean"),
  node_gradient = "match",
  node_gradient_map = c("even", "hash", "frequency"),
  node_scale = 1,
  radial_expand = 1,
  radial_gamma = 1,
  y_scale = 0,
  jitter_sd = 0,
  jitter_mode = c("deterministic", "random"),
  jitter_seed = NULL,
  keep_camera = FALSE,
  view_theta = 0,
  view_phi = NULL,
  view_fov = 60,
  view_zoom = NULL,
  view_userMatrix = NULL,
  return_data = FALSE
)

Arguments

Details

Metric scaling uses a helper that: 1) rescales the chosen metric to '[0,1]' over finite values, and 2) applies the selected transform: - '"linear"': identity, - '"sqrt"': emphasizes differences at the low end, - '"log"': 'log1p(9*t)/log(10)', emphasizing very small values.

Node elevation (‘y') is computed as 'y_scale * r_norm' where 'r_norm' is the node’s radial distance from its center normalized to the max within that coral. Optional jitter is added (fading to zero at the center). Root nodes ('step == 0') that overlap are vertically stacked (with small stems drawn). Labels are rendered on top of geometry.

Value

Invisibly returns 'NULL' after drawing. If 'return_data = TRUE', returns (invisibly) a list with components: - 'nodes': input 'nodes' with added columns like 'y' (base elevation) and 'color'. - 'edges': input 'edges' with added columns 'width', 'color', 'alpha', 't_color_norm', 'y', 'y_end', 'width_binned', 'alpha_binned'.

Requirements

Requires an interactive OpenGL device ('rgl'). On headless systems, consider using an off-screen context or skipping examples.

See Also

[rgl::material3d()], [rgl::light3d()]

Simple Random Search

Description

This function generates a vector of random solutions for a specified length.

Usage

rs(candidate_len)

Arguments

Value

A vector of random solutions between 0 and 1.

Examples

candidate_len <- 10
random_solutions <- rs(candidate_len)
print(random_solutions)

Calculate support and confidence for an association rule.

Description

This function calculates the support and confidence for the given antecedent and consequent in the dataset instances.

Usage

supp_conf(antecedent, consequent, instances, features)

Arguments

Value

A list containing support and confidence values.

Write Association Rules to CSV file

Description

This function writes association rules to a CSV file. For time series datasets, it also includes start and end timestamps instead of indices.

Usage

write_association_rules_to_csv(
  rules,
  file_path,
  is_time_series = FALSE,
  timestamps = NULL
)

Arguments

Value

No explicit return value. The function writes association rules to a CSV file.