Package 'RIFanalysis'

Title: Relative Importance Factor Analysis
Description: Tools for estimating, comparing, and visualizing Relative Importance Factor (RIF) indices based on rank-frequency distributions and discrete power-law models. The package provides reproducible workflows for data preparation, model fitting, goodness-of-fit assessment, bootstrap inference, and publication-ready outputs. The implemented methodology is described in Llinas et al. (2026) <doi:10.3390/math14060966>.
Authors: Humberto J. Llinás M. [aut, cre], Humberto J. Llinás S. [aut], Javier A. De la Hoz M. [aut], Brian J. Llinás M. [aut], José J. Padilla [aut]
Maintainer: Humberto J. Llinás M. <[email protected]>
License: MIT + file LICENSE
Version: 0.9.3
Built: 2026-10-12 10:11:23 UTC
Source: https://github.com/cran/RIFanalysis

Help Index

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 analyses, 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

x

An object of class rif_analysis, rif_results, rif_compare_results, or rif_zipf_tbl.
file

Output Excel file path.
overwrite

Logical. Should existing files be overwritten?

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 = 600,
  overwrite = TRUE
)

Arguments

plots

A ggplot object or a named list of ggplot objects.
output_dir

Output directory.
file_prefix

Prefix used for output filenames.
formats

Output format or formats. Options are "png" and "pdf".
width

Plot width.
height

Plot height.
units

Units for width and height.
dpi

Resolution used for PNG output.
overwrite

Logical. Should existing files be overwritten?

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 = 600,
  overwrite = TRUE,
  save = TRUE,
  matrix_args = list(),
  network_args = list()
)

Arguments

x

An object of class rif_results or rif_compare_results.
output_dir

Output directory.
scope

Plot scope. "auto" uses "individual" for rif_results objects and "both" for rif_compare_results objects. "individual" creates one plot per group, type, and method. "combined" creates one comparative panel per type and method with one subplot per group. "both" creates individual plots and comparative panels. "combined" and "both" are only available for rif_compare_results objects.
plot_types

Plot types to export. Options are "matrix" and "network".
methods

Optional methods to include. If NULL, all methods in x are used.
types

Optional types to include. If NULL, all types in x are used.
groups

Optional groups to include for individual plots. If NULL, all groups in x are used.
formats

Output format or formats. Options are "png" and "pdf".
file_prefix

Prefix used for output file names.
matrix_width

Matrix plot width.
matrix_height

Matrix plot height.
network_width

Network plot width.
network_height

Network plot height.
combined_matrix_width

Combined matrix panel width.
combined_matrix_height

Combined matrix panel height.
combined_network_width

Combined network panel width.
combined_network_height

Combined network panel height.
units

Units for plot width and height.
dpi

Resolution used for PNG output.
overwrite

Logical. Should existing files be overwritten?
save

Logical. Save plots to disk?
matrix_args

Named list of matrix-layer arguments. Common entries are label_col, label_size, axis_text_size, axis_title_size, matrix_margin_top, matrix_margin_right, matrix_margin_bottom, matrix_margin_left, legend_title_size, and legend_label_size. Arguments are passed to rif_layer_matrix() and rif_legend() as appropriate.
network_args

Named list of network-layer arguments. Common entries are label_col, factor_name_col, node_size_range, node_label_size, factor_name_size, wrap_width, factor_name_wrap_width, coord_x_pad, coord_y_pad, network_margin_top, network_margin_right, network_margin_bottom, network_margin_left, and legend_label_size. Arguments are passed to rif_layer_network() and rif_legend() as appropriate.

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

file

Input Excel file path.

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

data

An object of class rif_result_tbl, rif_results, or rif_compare_results. A data frame with pairwise columns can also be used.
method

Estimation method used when data contains multiple methods. Options are "MLE-KS" and "Bootstrapping".
group

Optional group value used to filter data.
type

Optional type value used to filter data.
label_col

Default column used as factor labels on both matrix axes when building the matrix from a RIF result table. Use a compact label column, such as "Factor_label_small", when axis labels need to stay short.
factor_s_label_col

Optional column used for labels on the rank s axis when building the matrix from a RIF result table. If NULL, label_col is used.
factor_r_label_col

Optional column used for labels on the rank r axis when building the matrix from a RIF result table. If NULL, label_col is used.
factor_s_col

Column with the factor at rank s for pairwise data.
factor_r_col

Column with the factor at rank r for pairwise data.
rif_col

Column with RIF values.
title

Plot title.
subtitle

Plot subtitle.
caption

Plot caption.
x_title

Title for the x-axis.
y_title

Title for the y-axis.
legend_position

Legend position.
label_size

Size of RIF labels inside cells.
axis_text_size

Size of axis text.
axis_title_size

Size of axis titles.
title_size

Size of plot title.
subtitle_size

Size of plot subtitle.
caption_size

Size of plot caption.
matrix_margin_top

Top plot margin.
matrix_margin_right

Right plot margin.
matrix_margin_bottom

Bottom plot margin.
matrix_margin_left

Left plot margin.
title_margin_bottom

Bottom margin for the title.
x_title_margin_top

Top margin for the x-axis title.
y_title_margin_right

Right margin for the y-axis title.
legend_title_size

Size of legend title.
legend_label_size

Size of legend labels.
show_matrix_factor_names

Logical. Show longer factor names in axis tick labels?
factor_s_name_col

Optional source-factor long-name column.
factor_r_name_col

Optional target-factor long-name column.
matrix_factor_name_wrap_width

Wrap width for longer factor names and compact axis tick labels.

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

data

An object of class rif_result_tbl, rif_results, or rif_compare_results. A data frame with pairwise columns can also be used.
method

Estimation method used when data contains multiple methods. Options are "MLE-KS" and "Bootstrapping".
group

Optional group value used to filter data.
type

Optional type value used to filter data.
label_col

Column used as short node labels when building the network from a RIF result table. These labels are drawn near the nodes and are wrapped with wrap_width.
factor_name_col

Optional column used for longer external factor names when building pairwise data from a RIF result table. These labels are drawn outside the nodes and are wrapped with factor_name_wrap_width.
from_col

Column with the source factor for pairwise data.
to_col

Column with the target factor for pairwise data.
rif_col

Column with RIF values.
rank_from_col

Optional source rank column for pairwise data.
rank_to_col

Optional target rank column for pairwise data.
title

Plot title.
subtitle

Plot subtitle.
caption

Plot caption.
title_size

Size of plot title.
subtitle_size

Size of plot subtitle.
caption_size

Size of plot caption.
title_margin_bottom

Bottom margin for the title.
remove_self_loops

Logical. Remove links where source and target are the same node?
node_size_range

Numeric range for node sizes. The range is reversed so higher-ranked factors are drawn larger.
edge_width_range

Numeric range for edge widths. Increase the second value for thicker high-RIF links.
node_color

Node color.
show_edge_labels

Logical. Show RIF values on edges?
edge_label_size

Edge label size.
rotate_edge_labels

Logical. Rotate edge labels with edge direction?
edge_label_rotation_mode

Rotation mode for edge labels. Options are "readable" and "direction".
edge_label_position

Relative position of labels along each edge.
edge_label_offset

Perpendicular offset for edge labels.
show_manual_legend

Logical. Add the manual legend for rank, edge strength, and RIF categories?
show_node_labels

Logical. Show node labels?
node_label_size

Node label size.
show_network_factor_names

Logical. Show longer factor names outside the network? The coordinate limits include these external labels to avoid clipping.
factor_names

Optional named character vector with longer factor names.
factor_name_s_col

Optional source-factor long-name column.
factor_name_r_col

Optional target-factor long-name column.
factor_name_size

Factor name label size.
factor_name_offset

Distance from each node to its longer factor name.
factor_name_wrap_width

Wrap width for longer external factor names from factor_name_col.
factor_name_fontface

Font face for longer factor names.
factor_name_color

Color for longer factor names.
factor_name_nudge

Named list with x/y nudges for longer factor names.
wrap_labels

Logical. Wrap node labels?
wrap_width

Wrap width for short node labels from label_col.
label_replacements

Optional named character vector with replacement node labels.
node_adjustments

Named list with x/y adjustments for node positions.
label_nudge

Named list with x/y nudges for node labels.
edge_label_nudge

Named list with x/y nudges for edge labels. Names must use the "from->to" form.
coord_x_pad

Extra x padding around the network and external labels.
coord_y_pad

Extra y padding around the network and external labels.
network_margin_top

Top plot margin.
network_margin_right

Right plot margin.
network_margin_bottom

Bottom plot margin.
network_margin_left

Left plot margin.
manual_legend_height

Relative height of the manual legend.

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

x

An object of class rif_zipf_tbl, usually created with rif_zipf().
group

Optional group value used to filter x.
type

Optional type value used to filter x.
label_col

Optional column used for labels. Use NULL for no labels.
title

Plot title.
x_title

X-axis title.
y_title

Y-axis title.
legend_title

Legend title.
label_size

Label size.
label_nudge_x

Horizontal adjustment for labels.
label_nudge_y

Vertical adjustment for labels.
label_force

Repulsion force used by ggrepel.
show_observed

Logical. Show observed counts.
show_theoretical

Logical. Show theoretical Zipf counts.

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

x

Object of class rif_analysis.
...

Additional 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

x

Object of class rif_powerlaw_fit.
...

Additional 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

x

Object of class rif_results.
...

Additional 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

x

An object of class rif_tbl.
...

Additional 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

x

An object of class rif_zipf_tbl.
...

Additional 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("manual", "poweRlaw")
)

Arguments

data

An object of class rif_tbl.
no_of_sims

Number of bootstrap simulations.
threads

Number of threads for the bootstrap routine.
seed

Random seed.
bootstrap_engine

Bootstrap engine. "manual" is the recommended default. "poweRlaw" is deprecated and will be removed in version 1.0.0.

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

rif_results1

An object of class rif_results.
rif_results2

An object of class rif_results.

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

x

An object of class rif_analysis.
method

Estimation method. Options are "MLE-KS" or "Bootstrapping".
digits

Number of decimal places.

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 = 10,
    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

x

An object of class rif_analysis.
digits

Number of decimal places.

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("manual", "poweRlaw")
)

Arguments

counts

Numeric vector of count values.
model

Optional fitted poweRlaw::displ model.
no_of_sims

Number of bootstrap simulations.
threads

Number of threads.
seed

Random seed.
engine

Bootstrap engine. "manual" is the recommended default. "poweRlaw" is deprecated and will be removed in version 1.0.0 because poweRlaw::bootstrap_p() can fail in clean package sessions.

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

counts

Numeric vector of count values.

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("manual", "poweRlaw")
)

Arguments

data

A rif_tbl object or a data frame with a count column.
count_col

Count column name.
group_col

Optional group column name.
group

Optional group value.
type_col

Optional type column name.
type

Optional type value.
no_of_sims

Number of bootstrap simulations.
threads

Number of threads.
seed

Random seed.
bootstrap_engine

Bootstrap engine. "manual" is the recommended default. "poweRlaw" is deprecated and will be removed in version 1.0.0.

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

x

A rif_plot object created with rif_plot().
title

Plot title.
subtitle

Plot subtitle.
caption

Plot caption.

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

x

A rif_plot or rif_panel object with a network layer.
show

Logical. Show RIF values on edges?
size

Edge label size.
position

Relative position of labels along each edge.
offset

Perpendicular offset for edge labels.
rotate

Logical. Rotate edge labels with edge direction?
rotation_mode

Rotation mode for edge labels. Options are "readable" and "direction".
nudge

Named list with x/y nudges for edge labels.

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

x

A rif_plot or rif_panel object with a network layer.
width_range

Numeric range for edge widths.
width_by

Edge width variable. Currently only "rif_value" is supported.
color_by

Edge color variable. Currently only "rif_category" is supported.

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

x

A rif_plot or rif_panel object.
label_col

Default column used as factor labels on both matrix axes when building the matrix from a RIF result table. Use a compact label column, such as "Factor_label_small", when axis labels need to stay short.
factor_s_label_col

Optional column used for labels on the rank s axis when building the matrix from a RIF result table. If NULL, label_col is used.
factor_r_label_col

Optional column used for labels on the rank r axis when building the matrix from a RIF result table. If NULL, label_col is used.
factor_s_col

Column with the factor at rank s for pairwise data.
factor_r_col

Column with the factor at rank r for pairwise data.
rif_col

Column with RIF values.
title

Plot title.
subtitle

Plot subtitle.
caption

Plot caption.
x_title

Title for the x-axis.
y_title

Title for the y-axis.
legend_position

Legend position.
label_size

Size of RIF labels inside cells.
axis_text_size

Size of axis text.
axis_title_size

Size of axis titles.
title_size

Size of plot title.
subtitle_size

Size of plot subtitle.
caption_size

Size of plot caption.
matrix_margin_top

Top plot margin.
matrix_margin_right

Right plot margin.
matrix_margin_bottom

Bottom plot margin.
matrix_margin_left

Left plot margin.
title_margin_bottom

Bottom margin for the title.
x_title_margin_top

Top margin for the x-axis title.
y_title_margin_right

Right margin for the y-axis title.
show_matrix_factor_names

Logical. Show longer factor names in axis tick labels?
factor_s_name_col

Optional source-factor long-name column.
factor_r_name_col

Optional target-factor long-name column.
matrix_factor_name_wrap_width

Wrap width for longer factor names and compact axis tick labels.

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

x

A rif_plot or rif_panel object.
layout

Network layout passed to the network layer. Currently "circle" is used by the drawing helpers.
label_col

Column used as short node labels when building the network from a RIF result table. These labels are drawn near the nodes and are wrapped with wrap_width.
factor_name_col

Optional column used for longer external factor names when building pairwise data from a RIF result table. These labels are drawn outside the nodes and are wrapped with factor_name_wrap_width.
from_col

Column with the source factor for pairwise data.
to_col

Column with the target factor for pairwise data.
rif_col

Column with RIF values.
rank_from_col

Optional source rank column for pairwise data.
rank_to_col

Optional target rank column for pairwise data.
title

Plot title.
subtitle

Plot subtitle.
caption

Plot caption.
title_size

Size of plot title.
subtitle_size

Size of plot subtitle.
caption_size

Size of plot caption.
title_margin_bottom

Bottom margin for the title.
remove_self_loops

Logical. Remove links where source and target are the same node?
node_size_range

Numeric range for node sizes. The range is reversed so higher-ranked factors are drawn larger.
edge_width_range

Numeric range for edge widths. Increase the second value for thicker high-RIF links.
node_color

Node color.
show_edge_labels

Logical. Show RIF values on edges?
edge_label_size

Edge label size.
rotate_edge_labels

Logical. Rotate edge labels with edge direction?
edge_label_rotation_mode

Rotation mode for edge labels. Options are "readable" and "direction".
edge_label_position

Relative position of labels along each edge.
edge_label_offset

Perpendicular offset for edge labels.
show_manual_legend

Logical. Add the manual legend for rank, edge strength, and RIF categories?
show_node_labels

Logical. Show node labels?
node_label_size

Node label size.
show_network_factor_names

Logical. Show longer factor names outside the network? The coordinate limits include these external labels to avoid clipping.
factor_names

Optional named character vector with longer factor names.
factor_name_s_col

Optional source-factor long-name column.
factor_name_r_col

Optional target-factor long-name column.
factor_name_size

Factor name label size.
factor_name_offset

Distance from each node to its longer factor name.
factor_name_wrap_width

Wrap width for longer external factor names from factor_name_col.
factor_name_fontface

Font face for longer factor names.
factor_name_color

Color for longer factor names.
factor_name_nudge

Named list with x/y nudges for longer factor names.
wrap_labels

Logical. Wrap node labels?
wrap_width

Wrap width for short node labels from label_col.
label_replacements

Optional named character vector with replacement node labels.
node_adjustments

Named list with x/y adjustments for node positions.
label_nudge

Named list with x/y nudges for node labels.
edge_label_nudge

Named list with x/y nudges for edge labels. Names must use the "from->to" form.
coord_x_pad

Extra x padding around the network and external labels.
coord_y_pad

Extra y padding around the network and external labels.
network_margin_top

Top plot margin.
network_margin_right

Right plot margin.
network_margin_bottom

Bottom plot margin.
network_margin_left

Left plot margin.
manual_legend_height

Relative height of the manual legend.

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

x

A rif_plot or rif_panel object with a network layer.
color

Node color.
size_range

Numeric range for node sizes.
size_by

Node size variable. Currently only "rank" is supported.

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

x

A rif_plot or rif_panel object.
show

Logical. Should the layer show its legend?
position

Legend position for layers that use ggplot legends, such as matrix plots. Common values are "none", "right", "left", "top", and "bottom".
size

Relative size reserved for panel legends or network manual legends.
spacing

Relative spacing between panel plots and panel legends. For individual matrix plots, this is interpreted as lines of spacing around the ggplot legend box.
title_size

Size of the legend title.
label_size

Size of the legend labels.

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

x

A rif_plot or rif_panel object with a matrix layer.
x_title

Title for the x-axis.
y_title

Title for the y-axis.
factor_name_wrap_width

Wrap width for longer factor names and compact axis tick labels.

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

x

A rif_plot or rif_panel object with a matrix layer.
label_size

Size of RIF labels inside cells.
axis_text_size

Size of axis text.
axis_title_size

Size of axis titles.
margin

Numeric vector of length four for top, right, bottom, and left plot margins.
title_margin_bottom

Bottom margin for the title.
x_title_margin_top

Top margin for the x-axis title.
y_title_margin_right

Right margin for the y-axis title.

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

x

A rif_plot or rif_panel object with a network layer.
show_node_labels

Logical. Show node labels?
node_label_size

Node label size.
factor_names

Optional named character vector with longer factor names.
factor_name_size

Factor name label size.
factor_name_color

Factor name label color.
factor_name_fontface

Factor name label font face.
wrap_labels

Logical. Wrap node labels?
wrap_width

Wrap width for node labels.
factor_name_wrap_width

Wrap width for longer factor names.
label_replacements

Optional named character vector with replacement node labels.

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

x

A rif_plot or rif_panel object with a network layer.
layout

Network layout. Defaults to "circle".
node_adjustments

Named list with x/y adjustments for node positions.
label_nudge

Named list with x/y nudges for node labels.
edge_label_nudge

Named list with x/y nudges for edge labels.
factor_name_nudge

Named list with x/y nudges for longer factor names.
factor_name_offset

Distance from each node to its longer factor name.
coord_x_pad

Extra x padding.
coord_y_pad

Extra y padding.
margin

Numeric vector of length four for top, right, bottom, and left plot margins.
title_margin_bottom

Bottom margin for the title.

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

...

Named rif_plot objects. Names are used as panel labels.
nrow

Optional number of panel rows.
ncol

Optional number of panel columns.

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

data

An object accepted by RIF plot functions, such as rif_results, rif_compare_results, rif_result_tbl, or a data frame.
method

Estimation method. Options are "MLE-KS" and "Bootstrapping".
group

Optional group value used by later plot layers.
type

Optional type value used by later plot layers.

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

data

A data frame.
factor_col

Name of the factor/concept column.
count_col

Name of the frequency/count column.
factor_small_col

Optional name of the short factor label column.
group_col

Optional name of the group column.
type_col

Optional name of the type column.
group_value

Group value used when group_col = NULL.
type_value

Type value used when type_col = NULL.
prefix

Prefix used to create factor labels.
factor_small_label_style

Style for the combined short label. Options are "inline", "newline", and "colon".

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

x

A rif_plot or rif_panel object.

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

x

A rif_plot or rif_panel object.
title_size

Size of plot titles.
subtitle_size

Size of plot subtitles.
caption_size

Size of plot captions.

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("manual", "poweRlaw"),
  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 = 600,
  analysis_excel_file = NULL
)

Arguments

rif_data

An object of class rif_tbl, usually created with rif_prepare().
alpha_zipf

Theoretical Zipf alpha value.
no_of_sims

Number of bootstrap simulations.
threads

Number of threads for poweRlaw bootstrap.
seed

Random seed.
bootstrap_engine

Bootstrap engine. "manual" is the recommended default. "poweRlaw" is deprecated and will be removed in version 1.0.0.
output_dir

Output directory. Required when saving files unless all relevant file or directory paths are supplied explicitly.
title_prefix

Plot title.
x_title

X-axis title.
y_title

Y-axis title.
excel_file

Output Excel filename.
zipf_excel_file

Output Excel filename for the Zipf table.
save_excel

Logical. Save RIF results to Excel?
save_plots

Logical. Save Zipf plots to disk?
plot_formats

Plot export format or formats. Options are "png" and "pdf".
plot_format

Deprecated alias for plot_formats.
plot_dir

Output directory for plots. If NULL, results_powerlaw_basic inside output_dir is used.
plot_width

Plot width used when saving plots.
plot_height

Plot height used when saving plots.
plot_dpi

Resolution used when saving PNG plots.
analysis_excel_file

Output Excel filename for the complete power-law analysis, including the individual bootstrap simulations.

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("manual", "poweRlaw"),
  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 = 600
)

Arguments

rif_data1

First object of class rif_tbl or rif_results.
rif_data2

Second object of class rif_tbl or rif_results. Must have the same class family as rif_data1.
alpha_zipf

Theoretical Zipf alpha value.
no_of_sims

Number of bootstrap simulations.
threads

Number of threads for poweRlaw bootstrap.
seed

Random seed.
bootstrap_engine

Bootstrap engine. "manual" is the recommended default. "poweRlaw" is deprecated and will be removed in version 1.0.0.
output_dir

Output directory. Required when saving files.
title_prefix

Plot title.
x_title

X-axis title.
y_title

Y-axis title.
excel_file

Output Excel filename.
save_excel

Logical. Save comparative RIF results to Excel?
save_plots

Logical. Save Zipf plots to disk? Only available when both inputs are objects of class rif_tbl.
plot_formats

Plot export format or formats. Options are "png" and "pdf".
plot_format

Deprecated alias for plot_formats.
plot_dir

Output directory for plots. If NULL, each group subfolder is used.
plot_width

Plot width used when saving plots.
plot_height

Plot height used when saving plots.
plot_dpi

Resolution used when saving PNG plots.

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,
  plot_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",
  plot_dpi = 600,
  overwrite = TRUE,
  save_plots = FALSE,
  matrix_args = list(),
  network_args = list(),
  dpi = NULL,
  save = NULL
)

Arguments

x

An object of class rif_results or rif_compare_results.
output_dir

Output directory.
scope

Plot scope. Uses the same logic as export_rif_visuals(): "auto" becomes "individual" for rif_results and "both" for rif_compare_results.
plot_types

Plot types to export. Options are "matrix" and "network".
methods

Optional methods to include. If NULL, all methods in x are used.
types

Optional types to include. If NULL, all types in x are used.
groups

Optional groups to include for individual plots. If NULL, all groups in x are used.
plot_formats

Output format or formats. Options are "png" and "pdf".
matrix_width

Matrix plot width.
matrix_height

Matrix plot height.
network_width

Network plot width.
network_height

Network plot height.
combined_matrix_width

Combined matrix panel width.
combined_matrix_height

Combined matrix panel height.
combined_network_width

Combined network panel width.
combined_network_height

Combined network panel height.
units

Units for plot width and height.
plot_dpi

Resolution used for PNG output.
overwrite

Logical. Should existing files be overwritten?
save_plots

Logical. Save plots to disk?
matrix_args

Named list of additional arguments passed to plot_matrix().
network_args

Named list of additional arguments passed to plot_network().
dpi

Deprecated alias for plot_dpi. It will be removed in version 1.0.0.
save

Deprecated alias for save_plots. It will be removed in version 1.0.0.

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

data

An object of class rif_tbl.
alpha_zipf

Theoretical Zipf alpha value. Default is 1.

Value

An object of class rif_zipf_tbl.