Package {RIFanalysis}

RIFanalysis: Relative Importance Factor Analysis

Description

Tools for estimating, comparing, and visualizing Relative Importance Factor indices based on rank-frequency and power-law models.

Author(s)

Maintainer: Humberto J. Llinás M. lhumberto@uninorte.edu.co

Authors:

• Humberto J. Llinás M. lhumberto@uninorte.edu.co

• Humberto J. Llinás S. hllinas@uninorte.edu.co

• Javier A. De la Hoz M. jdelahoz@unimagdalena.edu.co

• Brian J. Llinás M. bllin001@odu.edu

• José J. Padilla jpadilla@odu.edu

Example RIF datasets with a type variable

Description

A named list with two example data frames for workflows that use a type variable. Each data frame contains type labels, factor labels, and observed counts.

Usage

data(data_by_type)

Format

A list with two data frames:

data_gr1

Group 1 data with columns type1, factor1, factor_small1, and count1.

data_gr2

Group 2 data with columns type2, factor2, factor_small2, and count2.

Example RIF datasets without a type variable

Description

A named list with two example data frames for workflows that do not use a type variable. Each data frame contains factor labels and observed counts.

Usage

data(data_no_type)

Format

A list with two data frames:

data_gr1

Group 1 data with columns factor, factor_small, and count.

data_gr2

Group 2 data with columns factor, factor_small, and count.

Export RIF results to Excel

Description

Exports RIF results, comparative RIF results, or Zipf tables to an Excel workbook. Zipf tables are exported with one consolidated ZIPF_ALL sheet and one additional sheet per type.

Usage

export_rif_excel(x, file, overwrite = TRUE)

Arguments

Value

The output file path, invisibly.

Export RIF plots

Description

Saves one or more RIF plots as PNG and/or PDF files.

Usage

export_rif_plots(
  plots,
  output_dir,
  file_prefix = "rif",
  formats = "png",
  width = 8,
  height = 6,
  units = "in",
  dpi = 300,
  overwrite = TRUE
)

Arguments

Value

A character vector with the output file paths, invisibly.

Export RIF matrix and network visualizations

Description

Builds and exports RIF matrix and network plots from rif_results or rif_compare_results objects. File names are generated automatically from the selected group tag, type, method tag, plot kind, and scope.

Usage

export_rif_visuals(
  x,
  output_dir,
  scope = c("auto", "individual", "combined", "both"),
  plot_types = c("matrix", "network"),
  methods = NULL,
  types = NULL,
  groups = NULL,
  formats = "png",
  file_prefix = "rif",
  matrix_width = 10,
  matrix_height = 7.5,
  network_width = 10,
  network_height = 7.5,
  combined_matrix_width = 16,
  combined_matrix_height = 7.2,
  combined_network_width = 16,
  combined_network_height = 7.6,
  units = "in",
  dpi = 300,
  overwrite = TRUE,
  save = TRUE,
  matrix_args = list(),
  network_args = list()
)

Arguments

Details

export_rif_visuals() builds plots through the layered RIF plotting API. Individual plots are created from rif_plot() objects, and comparative plots are created from rif_panel() objects. Matrix arguments control the matrix layer; network arguments control the network layer. In network plots, wrap_width controls the short node labels from label_col, while factor_name_wrap_width controls the longer external factor names from factor_name_col.

Value

A list of class rif_visual_export with the plot plan, plot objects, and exported file paths.

Import RIF results from Excel

Description

Imports RIF computation results, comparative RIF results, or Zipf tables from an Excel workbook created with export_rif_excel().

Usage

import_rif_excel(file)

Arguments

Value

An object of class rif_results, rif_compare_results, or rif_zipf_tbl.

Plot a RIF matrix

Description

Creates a lower-triangular matrix of pairwise Relative Importance Factor (RIF) values from RIF result tables.

Usage

plot_matrix(
  data,
  method = c("MLE-KS", "Bootstrapping"),
  group = NULL,
  type = NULL,
  label_col = "Factor_label",
  factor_s_label_col = NULL,
  factor_r_label_col = NULL,
  factor_s_col = "factor_s",
  factor_r_col = "factor_r",
  rif_col = "RIF",
  title = NULL,
  subtitle = NULL,
  caption = NULL,
  x_title = "s: Concept at rank s",
  y_title = "r: Concept at rank r",
  legend_position = "right",
  label_size = 3.8,
  axis_text_size = 10,
  axis_title_size = 12,
  title_size = 16,
  subtitle_size = 12,
  caption_size = 9,
  matrix_margin_top = 10,
  matrix_margin_right = 5,
  matrix_margin_bottom = 10,
  matrix_margin_left = 15,
  title_margin_bottom = 10,
  x_title_margin_top = 12,
  y_title_margin_right = 0,
  legend_title_size = NULL,
  legend_label_size = 10,
  show_matrix_factor_names = FALSE,
  factor_s_name_col = "factor_s_name",
  factor_r_name_col = "factor_r_name",
  matrix_factor_name_wrap_width = 14
)

Arguments

Details

Cells are shown on and below the main diagonal, with rank r on the y-axis and rank s on the x-axis. plot_matrix() accepts either ranked RIF result tables or already pairwise data. Internal helper functions build and format the pairwise data; these helpers are intentionally not exported. The layered API equivalent is rif_plot() followed by rif_layer_matrix(), rif_legend(), and rif_render().

Value

A ggplot object.

Plot a RIF network

Description

Creates a directed network of pairwise Relative Importance Factor (RIF) values. The network uses RIF categories for edge colors, RIF values for edge width, and rank values for node size.

Usage

plot_network(
  data,
  method = c("MLE-KS", "Bootstrapping"),
  group = NULL,
  type = NULL,
  label_col = "Factor_label",
  factor_name_col = "Factor_small",
  from_col = "factor_s",
  to_col = "factor_r",
  rif_col = "RIF",
  rank_from_col = "rank_s",
  rank_to_col = "rank_r",
  title = NULL,
  subtitle = NULL,
  caption = NULL,
  title_size = 16,
  subtitle_size = 12,
  caption_size = 9,
  title_margin_bottom = 0,
  remove_self_loops = TRUE,
  node_size_range = c(5, 24),
  edge_width_range = c(0.6, 4),
  node_color = "#9BE7A1",
  show_edge_labels = TRUE,
  edge_label_size = 3.5,
  rotate_edge_labels = TRUE,
  edge_label_rotation_mode = c("readable", "direction"),
  edge_label_position = 0.58,
  edge_label_offset = 0.04,
  show_manual_legend = FALSE,
  show_node_labels = TRUE,
  node_label_size = 3.7,
  show_network_factor_names = TRUE,
  factor_names = NULL,
  factor_name_s_col = NULL,
  factor_name_r_col = NULL,
  factor_name_size = 4,
  factor_name_offset = 0.15,
  factor_name_wrap_width = 14,
  factor_name_fontface = "bold",
  factor_name_color = "black",
  factor_name_nudge = NULL,
  wrap_labels = TRUE,
  wrap_width = 10,
  label_replacements = NULL,
  node_adjustments = NULL,
  label_nudge = NULL,
  edge_label_nudge = NULL,
  coord_x_pad = 0.35,
  coord_y_pad = 0.15,
  network_margin_top = 10,
  network_margin_right = 5,
  network_margin_bottom = 10,
  network_margin_left = 15,
  manual_legend_height = 0.14
)

Arguments

Details

plot_network() accepts either ranked RIF result tables or already pairwise data. Internal helper functions build the pairwise edges and node metadata; these helpers are intentionally not exported.

Value

A ggplot object or a cowplot object when show_manual_legend = TRUE.

Plot observed and theoretical Zipf distributions

Description

Creates a Zipf plot comparing observed counts with theoretical Zipf counts computed by rif_zipf(). Labels can optionally be added.

Usage

plot_zipf(
  x,
  group = NULL,
  type = NULL,
  label_col = NULL,
  title = "Observed and theoretical Zipf distributions",
  x_title = "Rank",
  y_title = "Count",
  legend_title = "Distribution:",
  label_size = 3.5,
  label_nudge_x = 0,
  label_nudge_y = 0,
  label_force = 1,
  show_observed = TRUE,
  show_theoretical = TRUE
)

Arguments

Value

A ggplot object.

Examples

df <- data.frame(
    Factor = c("A", "B", "C", "D", "E", "F"),
    Count = c(100, 60, 35, 20, 12, 8)
)

rif_data <- rif_prepare(
    data = df,
    factor_col = "Factor",
    count_col = "Count",
    prefix = "T"
)

zipf_tbl <- rif_zipf(rif_data)

plot_zipf(zipf_tbl)

plot_zipf(
    zipf_tbl,
    label_col = "factor_label"
)

Print RIF analysis

Description

Prints a compact summary of a RIF analysis object.

Usage

## S3 method for class 'rif_analysis'
print(x, ...)

Arguments

Value

x, invisibly.

Print RIF power-law fit

Description

Prints a compact summary of a RIF power-law fit.

Usage

## S3 method for class 'rif_powerlaw_fit'
print(x, ...)

Arguments

Value

x, invisibly.

Print RIF results

Description

Prints a compact summary of RIF result tables.

Usage

## S3 method for class 'rif_results'
print(x, ...)

Arguments

Value

x, invisibly.

Print RIF data object

Description

Prints a compact summary of prepared RIF data.

Usage

## S3 method for class 'rif_tbl'
print(x, ...)

Arguments

Value

x, invisibly.

Print RIF Zipf table

Description

Prints a compact summary of a RIF Zipf table.

Usage

## S3 method for class 'rif_zipf_tbl'
print(x, ...)

Arguments

Value

x, invisibly.

Run basic RIF analysis

Description

Fits the power-law model and bootstrap summaries for prepared RIF data. If the data contains multiple types, each type is fitted independently.

Usage

rif_analysis(
  data,
  no_of_sims = 1000,
  threads = 1,
  seed = 123,
  bootstrap_engine = c("poweRlaw", "manual")
)

Arguments

Value

An object of class rif_analysis.

Create comparative RIF results

Description

Creates comparative RIF tables from two rif_compute_results() objects for subsequent export, visualization, and analysis.

Usage

rif_compare_results(rif_results1, rif_results2)

Arguments

Value

An object of class rif_compare_results.

Compute RIF values

Description

Computes the Relative Importance Factor (RIF) table from a basic RIF analysis object, using the fitted alpha and xmin values for each type.

Usage

rif_compute(x, method = c("MLE-KS", "Bootstrapping"), digits = 3)

Arguments

Value

An object of class rif_result_tbl.

Examples

df <- data.frame(
    Factor = c("A", "B", "C", "D", "E", "F"),
    Count = c(100, 60, 35, 20, 12, 8)
)

rif_data <- rif_prepare(
    data = df,
    factor_col = "Factor",
    count_col = "Count",
    prefix = "T"
)

res <- rif_analysis(
    data = rif_data,
    no_of_sims = 50,
    bootstrap_engine = "manual"
)

rif_compute(res, method = "MLE-KS")

Compute RIF results for all methods

Description

Computes RIF tables for MLE-KS and Bootstrapping.

Usage

rif_compute_results(x, digits = 3)

Arguments

Value

An object of class rif_results.

Bootstrap estimates for discrete power-law model

Description

Estimates bootstrap summaries for a discrete power-law model.

Usage

rif_fit_bootstrap(
  counts,
  model = NULL,
  no_of_sims = 1000,
  threads = 1,
  seed = 123,
  engine = c("poweRlaw", "manual")
)

Arguments

Value

A list with bootstrap table and raw bootstrap results.

Fit discrete power-law model using MLE-KS

Description

Fits a discrete power-law model and returns MLE-KS summary statistics.

Usage

rif_fit_mle_ks(counts)

Arguments

Value

A list with model, estimate, and summary table.

Fit power-law model for RIF data

Description

Fits MLE-KS and bootstrap power-law summaries for RIF count data.

Usage

rif_fit_powerlaw(
  data,
  count_col = "count",
  group_col = "group",
  group = NULL,
  type_col = "type",
  type = NULL,
  no_of_sims = 1000,
  threads = 1,
  seed = 123,
  bootstrap_engine = c("poweRlaw", "manual")
)

Arguments

Value

An object of class rif_powerlaw_fit.

Add labels to a RIF plot object

Description

Stores shared plot labels that can be used by later RIF plot layers.

Usage

rif_labels(x, title = NULL, subtitle = NULL, caption = NULL)

Arguments

Value

A rif_plot object.

Configure network edge labels

Description

Updates edge-label settings for a stored network layer.

Usage

rif_layer_edge_labels(
  x,
  show = NULL,
  size = NULL,
  position = NULL,
  offset = NULL,
  rotate = NULL,
  rotation_mode = NULL,
  nudge = NULL
)

Arguments

Value

A rif_plot or rif_panel object.

Configure network edges

Description

Updates edge settings for a stored network layer.

Usage

rif_layer_edges(x, width_range = NULL, width_by = NULL, color_by = NULL)

Arguments

Value

A rif_plot or rif_panel object.

Add a matrix layer to a RIF plot

Description

Stores a RIF matrix layer specification in a rif_plot or rif_panel object. Use rif_render() to build the final plot.

Usage

rif_layer_matrix(
  x,
  label_col = "Factor_label",
  factor_s_label_col = NULL,
  factor_r_label_col = NULL,
  factor_s_col = "factor_s",
  factor_r_col = "factor_r",
  rif_col = "RIF",
  title = NULL,
  subtitle = NULL,
  caption = NULL,
  x_title = "s: Concept at rank s",
  y_title = "r: Concept at rank r",
  legend_position = NULL,
  label_size = NULL,
  axis_text_size = NULL,
  axis_title_size = NULL,
  title_size = NULL,
  subtitle_size = NULL,
  caption_size = NULL,
  matrix_margin_top = NULL,
  matrix_margin_right = NULL,
  matrix_margin_bottom = NULL,
  matrix_margin_left = NULL,
  title_margin_bottom = 10,
  x_title_margin_top = 12,
  y_title_margin_right = 12,
  show_matrix_factor_names = FALSE,
  factor_s_name_col = "factor_s_name",
  factor_r_name_col = "factor_r_name",
  matrix_factor_name_wrap_width = 14
)

Arguments

Details

When x is a rif_panel, matrix text sizes use panel-oriented defaults. Values supplied directly to rif_layer_matrix() or later through rif_matrix_layout() override those defaults.

Value

A rif_plot or rif_panel object.

Add a network layer to a RIF plot

Description

Stores a RIF network layer specification in a rif_plot or rif_panel object. Use rif_render() to build the final plot.

Usage

rif_layer_network(
  x,
  layout = "circle",
  label_col = "Factor_label",
  factor_name_col = "Factor_small",
  from_col = "factor_s",
  to_col = "factor_r",
  rif_col = "RIF",
  rank_from_col = "rank_s",
  rank_to_col = "rank_r",
  title = NULL,
  subtitle = NULL,
  caption = NULL,
  title_size = NULL,
  subtitle_size = NULL,
  caption_size = NULL,
  title_margin_bottom = 0,
  remove_self_loops = TRUE,
  node_size_range = NULL,
  edge_width_range = c(0.6, 4),
  node_color = "#9BE7A1",
  show_edge_labels = TRUE,
  edge_label_size = 3.5,
  rotate_edge_labels = TRUE,
  edge_label_rotation_mode = c("readable", "direction"),
  edge_label_position = 0.58,
  edge_label_offset = 0.04,
  show_manual_legend = NULL,
  show_node_labels = TRUE,
  node_label_size = NULL,
  show_network_factor_names = TRUE,
  factor_names = NULL,
  factor_name_s_col = NULL,
  factor_name_r_col = NULL,
  factor_name_size = NULL,
  factor_name_offset = 0.15,
  factor_name_wrap_width = 14,
  factor_name_fontface = "bold",
  factor_name_color = "black",
  factor_name_nudge = NULL,
  wrap_labels = TRUE,
  wrap_width = 10,
  label_replacements = NULL,
  node_adjustments = NULL,
  label_nudge = NULL,
  edge_label_nudge = NULL,
  coord_x_pad = 0.35,
  coord_y_pad = 0.15,
  network_margin_top = NULL,
  network_margin_right = NULL,
  network_margin_bottom = NULL,
  network_margin_left = NULL,
  manual_legend_height = 0.14
)

Arguments

Details

When x is a rif_panel, node sizes, node-label sizes, factor-name sizes, and plot margins use panel-oriented defaults. Values supplied directly to rif_layer_network() or later through rif_layer_nodes(), rif_network_labels(), or rif_network_layout() override those defaults. wrap_width controls short node labels from label_col; factor_name_wrap_width controls longer external factor names from factor_name_col.

Value

A rif_plot or rif_panel object.

Configure network nodes

Description

Updates node settings for a stored network layer.

Usage

rif_layer_nodes(x, color = NULL, size_range = NULL, size_by = NULL)

Arguments

Value

A rif_plot or rif_panel object.

Configure legends for a RIF plot object

Description

Stores shared legend settings that can be used by later RIF plot layers.

Usage

rif_legend(
  x,
  show = NULL,
  position = NULL,
  size = NULL,
  spacing = NULL,
  title_size = NULL,
  label_size = NULL
)

Arguments

Value

A rif_plot or rif_panel object.

Configure matrix labels

Description

Updates axis and factor-name label settings for a stored matrix layer.

Usage

rif_matrix_labels(
  x,
  x_title = NULL,
  y_title = NULL,
  factor_name_wrap_width = NULL
)

Arguments

Value

A rif_plot or rif_panel object.

Configure matrix layout

Description

Updates text-size and spacing settings for a stored matrix layer.

Usage

rif_matrix_layout(
  x,
  label_size = NULL,
  axis_text_size = NULL,
  axis_title_size = NULL,
  margin = NULL,
  title_margin_bottom = NULL,
  x_title_margin_top = NULL,
  y_title_margin_right = NULL
)

Arguments

Value

A rif_plot or rif_panel object.

Configure network labels

Description

Updates node-label and factor-name label settings for a stored network layer.

Usage

rif_network_labels(
  x,
  show_node_labels = NULL,
  node_label_size = NULL,
  factor_names = NULL,
  factor_name_size = NULL,
  factor_name_color = NULL,
  factor_name_fontface = NULL,
  wrap_labels = NULL,
  wrap_width = NULL,
  factor_name_wrap_width = NULL,
  label_replacements = NULL
)

Arguments

Value

A rif_plot or rif_panel object.

Configure network layout

Description

Updates layout and nudge settings for a stored network layer.

Usage

rif_network_layout(
  x,
  layout = NULL,
  node_adjustments = NULL,
  label_nudge = NULL,
  edge_label_nudge = NULL,
  factor_name_nudge = NULL,
  factor_name_offset = NULL,
  coord_x_pad = NULL,
  coord_y_pad = NULL,
  margin = NULL,
  title_margin_bottom = NULL
)

Arguments

Value

A rif_plot or rif_panel object.

Create a RIF panel object

Description

Creates a lightweight panel specification from multiple rif_plot objects. Later RIF layers can use this object to build one plot per specification and combine them into a panel.

Usage

rif_panel(..., nrow = 1, ncol = NULL)

Arguments

Value

An object of class rif_panel.

Create a RIF plot object

Description

Creates a lightweight plot specification that can be extended by RIF plotting layers. This object stores the input data and selection context, but does not draw a plot by itself.

Usage

rif_plot(
  data,
  method = c("MLE-KS", "Bootstrapping"),
  group = NULL,
  type = NULL
)

Arguments

Value

An object of class rif_plot.

Prepare data for RIF analysis

Description

Converts a user data frame into a standardized RIF object.

Usage

rif_prepare(
  data,
  factor_col,
  count_col,
  factor_small_col = NULL,
  group_col = NULL,
  type_col = NULL,
  group_value = "G",
  type_value = "corpus_type",
  prefix = "F",
  factor_small_label_style = "inline"
)

Arguments

Value

An object of class rif_tbl.

Render a RIF plot object

Description

Builds the final plot from a rif_plot or rif_panel object with a stored layer specification.

Usage

rif_render(x)

Arguments

Value

A ggplot object or a combined cowplot object.

Configure shared RIF plot theme settings

Description

Stores shared theme settings that can be used by later RIF plot layers when rendering.

Usage

rif_theme(x, title_size = NULL, subtitle_size = NULL, caption_size = NULL)

Arguments

Value

A rif_plot or rif_panel object.

Run complete Z1 RIF workflow

Description

Runs the complete Z1 workflow for prepared RIF data: Zipf table, power-law fitting, RIF computation, plots, and Excel export.

Usage

rif_workflow_z1(
  rif_data,
  alpha_zipf = 1,
  no_of_sims = 1000,
  threads = 1,
  seed = 123,
  bootstrap_engine = c("poweRlaw", "manual"),
  output_dir = NULL,
  title_prefix = "Observed and theoretical Zipf distributions for ",
  x_title = "Rank",
  y_title = "Count",
  excel_file = NULL,
  zipf_excel_file = NULL,
  save_excel = FALSE,
  save_plots = FALSE,
  plot_formats = "png",
  plot_format = NULL,
  plot_dir = NULL,
  plot_width = 8,
  plot_height = 6,
  plot_dpi = 300
)

Arguments

Value

A list of class rif_workflow_z1.

Run complete Z2 comparative RIF workflow

Description

Runs the complete Z2 workflow for two RIF inputs. Both inputs must be the same kind: either prepared RIF data or previously computed RIF results. If the inputs are rif_tbl objects, the workflow runs rif_workflow_z1() for each group and then creates the comparative tables. If the inputs are rif_results objects, the workflow skips model fitting, RIF computation, and Zipf plots, and only creates the comparative tables and Excel export.

Usage

rif_workflow_z2(
  rif_data1,
  rif_data2,
  alpha_zipf = 1,
  no_of_sims = 1000,
  threads = 1,
  seed = 123,
  bootstrap_engine = c("poweRlaw", "manual"),
  output_dir = NULL,
  title_prefix = "Observed and theoretical Zipf distributions for ",
  x_title = "Rank",
  y_title = "Count",
  excel_file = NULL,
  save_excel = FALSE,
  save_plots = FALSE,
  plot_formats = "png",
  plot_format = NULL,
  plot_dir = NULL,
  plot_width = 8,
  plot_height = 6,
  plot_dpi = 300
)

Arguments

Value

A list of class rif_workflow_z2.

Run Z3 RIF visual workflow

Description

Creates matrix and network visualizations from individual or comparative RIF results. The workflow accepts only rif_results and rif_compare_results objects; use rif_workflow_z1() or rif_workflow_z2() first when starting from prepared RIF tables.

Usage

rif_workflow_z3(
  x,
  output_dir = "Z3_results_RIF_visuals",
  scope = c("auto", "individual", "combined", "both"),
  plot_types = c("matrix", "network"),
  methods = NULL,
  types = NULL,
  groups = NULL,
  formats = "png",
  matrix_width = 10,
  matrix_height = 7.5,
  network_width = 10,
  network_height = 7.5,
  combined_matrix_width = 16,
  combined_matrix_height = 7.2,
  combined_network_width = 16,
  combined_network_height = 7.6,
  units = "in",
  dpi = 300,
  overwrite = TRUE,
  save = TRUE,
  matrix_args = list(),
  network_args = list()
)

Arguments

Value

A list of class rif_workflow_z3.

Build Zipf table for RIF data

Description

Computes theoretical Zipf counts and related errors for prepared RIF data.

Usage

rif_zipf(data, alpha_zipf = 1)

Arguments

Value

An object of class rif_zipf_tbl.