Introduction

This vignette demonstrates the standard workflow for datasets containing a single group and no Type variable. Other vignettes describe the workflows for multi-group comparisons and for datasets containing a Type variable.

Starting from a table of observed frequencies, the workflow prepares the data, fits a discrete power-law model, computes the Relative Importance Factor (RIF), and generates publication-ready tables and visualizations.

Most users will only need the high-level workflow functions described in this vignette. The Advanced usage section introduces lower-level functions for users who require additional customization.

Methodological foundation

The methods implemented in the RIFanalysis package are based on the following publication:

Llinas, B., Padilla, J., Llinas, H., Frydenlund, E., & Palacio, K. (2026). Modeling Rank Distribution and the Relative Importance Factor Index in Discrete Power-Law Models: Application to Social Resilience Using the Scopus Database. Mathematics, 14(6), 966..

Workflow overview

The complete analysis is organized as a sequence of three main stages. First, the input dataset is standardized using rif_prepare(). Next, rif_workflow_z1() performs the power-law estimation and computes the RIF measures. Finally, rif_workflow_z3() generates publication-ready visualizations from the computed RIF results.

                 Input dataset
                       │
                       ▼
                rif_prepare()
                       │
                       ▼
             rif_workflow_z1()
                       │
          ┌────────────┼────────────┐
          ▼            ▼            ▼
     Excel files   Zipf plots   RIF results
                                     │
                                     ▼
                           rif_workflow_z3()
                                     │
                      ┌──────────────┼──────────────┐
                      ▼              ▼              ▼
                 RIF matrices   RIF networks   Publication-ready figures

The workflow consists of the following steps:

1. Define user-specific objects and input parameters.

2. Import and prepare the dataset.

3. Fit discrete power-law models.

4. Compute Relative Importance Factor (RIF) measures.

5. Generate tables and graphical outputs.

6. Export results to Excel and image files.

Load the package

library(RIFanalysis)

Input dataset

The analysis begins by importing the input dataset. At a minimum, the dataset should contain variables identifying the factors (or topics), their short labels, and their observed frequencies.

data_gr1 <- read.csv("0_data_gr1.csv")

User-defined objects

Before running the workflow, define the objects that specify variable names, plot labels, output directories, and other user-specific settings. Most of these values can be left unchanged, but they may be customized for different applications.

Because this vignette is designed for datasets containing a single group and no Type variable, the objects gr_value_name and var_type_value_name do not refer to columns in the input dataset. Instead, they define labels that are assigned to all observations during the data preparation step through the group_value and type_value arguments of rif_prepare().

# Review required variable names (ALWAYS verify them in the dataset)
fact_lbl_prefix        <- "grT"                # Choose according to your needs (gr=group, T=topic, C=concept, F=factor,     
                                               # I=index, etc.)
var_factor_name        <- "factor"             # Long/original FACTOR variable
var_factor_small       <- "factor_small"       # Short FACTOR variable
var_factor_label_small <- "factor_label_small" # FACTOR_label_small variable
var_count_name         <- "count"              # COUNT variable

# Assign a label to the analysis because the dataset does not contain a Type variable.
var_type_value_name  <- "corpus_type"  # Change (abstract, index, etc.)

# Assign a label identifying the single analysis group.
gr_value_name  <- "GROUPNAME1"  # Change (Colombia, Greece, Blue Economy, etc.)
#prefix_name <- paste0(gr_name, "_")

#________________________________________________________________________
#

# If desired, change axis title  for RIF matrices (Topic, Concept, Factor, etc.) and labels. 
# IN rif_workflow_z3, SEE plot_matrix.R FUNCTION:

# Axis title: 
x_title_name  <-  "s: CHANGE_NAME at rank s" # default: Concept
y_title_name  <-  "r: CHANGE_NAME at rank r" # default: Concept
# Axis labels:  
factor_r_label_col_name <- "Factor_label" # default: factor_r_label_col = NULL
factor_s_label_col_name <- "Factor_label" # default: factor_s_label_col = NULL

#________________________________________________________________________
#

# Change titles for power-law plots (used in rif__workflow_z1 and plot_zipf)
#title default is "Observed and theoretical Zipf distributions..."
title_plotzipf_gr1_c2 <- "GROUPNAME1" # Change if desired

x_title_plotzipf_c2   <- "Position"  # Change if desired (default="Rank")
y_title_plotzipf_c2   <- "Frequency" # Change if desired (default="Count")

#________________________________________________________________________
#

# Change custom file names (if desired)
file_prefix_no_title     <- "zipf_notitle"
file_prefix_yes_title_c1 <- "zipf_yestitle_c1"
file_prefix_yes_title_c2 <- "zipf_yestitle_c2"

# Change output directories (if desired)
output_dir_personal  <- file.path(tempdir(), "Z0_personal")
output_dir_default   <- file.path(tempdir(), "Z1_RIF_basic")
output_dir_visual    <- file.path(tempdir(), "Z3_RIF_visual")

Descriptive Zipf analysis

The first step is to prepare the dataset for the RIF workflow. The rif_prepare() function validates the input data, assigns Zipf ranks, and creates the standardized table required by the remaining functions. The resulting object (rif_data1) serves as the input for all subsequent workflow functions.

rif_data1 <- rif_prepare(data= data_gr1, 
    factor_col = var_factor_name,
    count_col = var_count_name ,
    factor_small_col = var_factor_small,
    group_col = NULL,
    type_col = NULL,
    group_value = gr_value_name,
    type_value = var_type_value_name,
    prefix = fact_lbl_prefix,
    factor_small_label_style = "inline")

Inspect the resulting object if desired.

rif_data1
names(rif_data1)

Z1: Power-law Estimation and RIF Computation

The main workflow is executed with rif_workflow_z1(). This function fits the discrete power-law model, computes all RIF measures, generates diagnostic plots, and optionally exports the results to Excel and image files.

z1 <- rif_workflow_z1(
    rif_data= rif_data1,
    alpha_zipf = 1,
    no_of_sims = 1000,
    threads = 8,
    seed = 123,
    bootstrap_engine = "poweRlaw",
    output_dir = output_dir_default,
    excel_file = NULL,
    zipf_excel_file = NULL,
    save_excel = TRUE,
    save_plots = TRUE,
    plot_formats = c("png", "pdf"),
    plot_format = NULL,
    plot_dir = NULL,
    plot_width = 8,
    plot_height = 6,
    plot_dpi = 300
)

The workflow returns a single object containing all intermediate and final results. The table below summarizes its most important components.

The following commands illustrate how to access each component.

z1$data
z1$zipf
z1$analysis
z1$rif_results
z1$plots
z1$files

Z3: RIF Visualization

The rif_workflow_z3() function generates publication-ready visualizations, including RIF matrices, networks, and other graphical summaries derived from the computed RIF results.

rif_workflow_z3(
  x = z1$rif_results,
  formats = c("png", "pdf"),
    #plot_types = "matrix",
  output_dir = output_dir_visual,
  
  #SEE plot_matrix.R FUNCTION:  
  matrix_args = list(
    #factor_r_label_col = factor_r_label_col_name,
    factor_s_label_col = factor_s_label_col_name,
    x_title = x_title_name,
    y_title = y_title_name 
    )
)

Advanced usage

The following examples illustrate how individual functions can be used independently of the main workflow to customize plots, export files, or inspect intermediate objects.

# Default title
plt_zipf_withTitle_c1 <- plot_zipf(tbl_zipf, 
                               label_col = var_factor_label_small)
plt_zipf_withTitle_c1

#Custom title 
plt_zipf_withTitle_c2 <- plot_zipf(tbl_zipf, 
                               label_col = var_factor_label_small,
                               title = title_plotzipf_gr1_c2, 
                               x_title = x_title_plotzipf_c2, 
                               y_title = y_title_plotzipf_c2)
plt_zipf_withTitle_c2

#No title
plt_zipf_noTitle <- plot_zipf(tbl_zipf, 
                               label_col = var_factor_label_small, 
                               title = "")
plt_zipf_noTitle

export_rif_plots(
  plots = plt_zipf_withTitle_c1,
  output_dir = output_dir_personal,
  file_prefix = file_prefix_yes_title_c1,
  formats = c("png", "pdf")
  )

export_rif_plots(
  plots = plt_zipf_withTitle_c2,
  output_dir = output_dir_personal,
  file_prefix = file_prefix_yes_title_c2,
  formats = c("png", "pdf")
  )

export_rif_plots(
  plots = plt_zipf_noTitle,
  file_prefix = file_prefix_no_title,
  output_dir = output_dir_personal,
  formats = c("png", "pdf")
  )

tbl_zipf <- rif_zipf(rif_data1)
tbl_zipf
names(tbl_zipf)

plreg <- rif_fit_powerlaw(
    data= rif_data1,
    count_col = "count",
    group_col = "group",
    group = NULL,
    type_col = "type",
    type = NULL,
    no_of_sims = 1000,
    threads = 8,
    seed = 123,
    bootstrap_engine = c("poweRlaw")
)

names(plreg$df_KS_boot)

rif_an <- rif_analysis(data = rif_data1, threads = 8)
rif_an$tables$ks_boot

names(rif_an$tables$ks_boot)
names(plreg$df_KS_boot)

z1_zipf <- z1$zipf
z1_zipf

class(z1_zipf)
class(tbl_zipf)

rif_result_z1 <- z1$rif_results
rif_result_z1
class(rif_result_z1)

rif_result_an <- rif_compute_results(rif_an)
class(rif_result_an)
rif_result_an

# Export
export_rif_excel(
  rif_result_an,
  file.path(tempdir(), "Z0_personal", "rif_result_an.xlsx")
)

# Import
rif_result_excel <- import_rif_excel("Workflow_results/Z1_RIF_basic/NOM_RIF_3sheets.xlsx") #Change NOM
rif_result_excel
class(rif_result_excel)