Package {fcmfd}

Build Fuzzy Dictionary

Description

Constructs a fuzzy dictionary based on the selected scale type (symmetric or asymmetric).

Usage

build_dictionary(type, option, dictionary = NULL)

Arguments

Details

For symmetric dictionaries, predefined TFN structures are generated. For asymmetric dictionaries, user-defined matrices are validated and converted to list format.

Value

A list representing the fuzzy dictionary.

Check Convergence of Membership Matrix

Description

Evaluates convergence based on the Frobenius norm between two membership matrices.

Usage

check_convergence(U_old, U_new, epsilon = 1e-06)

Arguments

Value

Logical value indicating convergence.

Hard Cluster Assignment

Description

Assigns each observation to the cluster with the highest membership value.

Usage

cluster_assignment(object)

Arguments

Value

A factor indicating cluster labels.

Cluster Sizes

Description

Computes the size of each cluster using both hard assignments and fuzzy memberships.

Usage

cluster_size(object)

Arguments

Details

Hard size is obtained by assigning each observation to the cluster with the highest membership degree.

Fuzzy size is computed as the sum of membership degrees for each cluster.

Value

A data.frame containing:

Cluster

Cluster label.

Hard_Size

Number of observations assigned to the cluster.

Fuzzy_Size

Sum of membership degrees.

Compute Cluster Prototypes

Description

Computes fuzzy cluster prototypes (centroids) using membership degrees and triangular fuzzy numbers.

Usage

compute_prototypes(fuzzy_data, U, m = 2)

Arguments

Details

Each prototype is calculated as a weighted average of fuzzy observations using membership degrees raised to the fuzzifier parameter m.

Value

A list of prototype matrices.

Compute Adaptive Weights

Description

Computes adaptive weights for modal (wc) and spread (ws) components based on fuzzy distances and membership degrees.

Usage

compute_weights(fuzzy_data, prototypes, U, m = 2)

Arguments

Value

A list with wc and ws.

Compute Xie-Beni Cluster Validity Index

Description

Computes the Xie-Beni (XB) index used to evaluate the compactness and separation of fuzzy clusters.

Usage

compute_xie_beni_index(fuzzy_data, U, prototypes, wc, ws, m = 2)

Arguments

Details

The Xie-Beni index is defined as:

XB = \frac{ \sum_{i=1}^{n} \sum_{g=1}^{k} u_{ig}^{m} d^{2}(x_i, h_g) }{ n \min_{g \ne g'} d^{2}(h_g, h_{g'}) }

Lower values indicate better clustering performance.

Value

Numeric value representing the Xie-Beni index.

Convert Matrix to Dictionary List

Description

Converts a matrix representation of triangular fuzzy numbers (TFN) into a named list format used internally by the system.

Usage

convert_matrix_to_list(matrix)

Arguments

Details

The input matrix must contain three columns: (l, c, r), where: l = left spread c = modal value r = right spread

Value

A named list containing triangular fuzzy numbers.

Convert Data to Triangular Fuzzy Numbers (TFN)

Description

Converts ordinal data into triangular fuzzy numbers using the provided fuzzy dictionary.

Usage

convert_to_tfn(data, dictionary)

Arguments

Details

Each observation is transformed into a matrix where rows represent variables and columns correspond to (l, c, r) values.

Value

A list of matrices containing TFN representations.

Default Symmetric Fuzzy Dictionary

Description

Generates predefined symmetric triangular fuzzy number (TFN) dictionaries for ordinal Likert-type scales.

Usage

default_symmetric_dictionary(option = "A")

Arguments

Details

Available options: A: 5-point scale B: 7-point scale C: 10-point scale (1–10) D: 11-point scale (0–10)

Value

A list containing triangular fuzzy numbers (l, c, r).

Fuzzy C-Means Clustering for Triangular Fuzzy Numbers

Description

Performs fuzzy clustering on ordinal Likert-type data represented as triangular fuzzy numbers (TFNs).

Usage

fcmTFN(
  data,
  type = "symmetric",
  option = "B",
  dictionary = NULL,
  k_values = 2:6,
  m = 2,
  epsilon = 1e-06,
  max_iter = 1000,
  verbose = TRUE
)

Arguments

Details

The function automatically determines the optimal number of clusters based on the Xie-Beni validity index.

Value

An object of class '"fcmTFN"' and '"fcm"'.

References

Coppi, R., D'Urso, P., & Giordani, P. (2012). Fuzzy and possibilistic clustering for fuzzy data. <doi:10.1016/j.csda.2010.09.013>

Xie, X. L., & Beni, G. (1991). A validity measure for fuzzy clustering. <doi:10.1109/34.85677>

Fuzzy K-Means for TFN Data

Description

Core iterative algorithm for fuzzy clustering using triangular fuzzy numbers.

Usage

fkm_f_algorithm(fuzzy_data, k, m = 2, epsilon = 1e-06, max_iter = 1000)

Arguments

Value

List containing clustering results.

Compute Fuzzy Distance Between TFNs

Description

Computes the distance between two triangular fuzzy number (TFN) matrices using weighted Euclidean distance.

Usage

fuzzy_distance(x, h, wc, ws)

Arguments

Details

The distance accounts for differences in modal values and spreads, controlled by weights wc and ws.

Value

A numeric distance value.

Initialize Membership Matrix

Description

Generates an initial fuzzy membership matrix (U) with random values and normalizes each row so that memberships sum to 1.

Usage

initialize_U(n, k)

Arguments

Value

A numeric matrix of size n × k representing initial membership degrees.

Extract Membership Matrix

Description

Returns the fuzzy membership matrix obtained from the Fuzzy C-Means clustering process.

Usage

membership(object)

Arguments

Value

A matrix where rows represent observations and columns represent clusters.

Membership Quality Assessment

Description

Evaluates the quality of fuzzy assignments for each cluster using membership-based measures.

Usage

membership_quality(object)

Arguments

Details

This function computes both cluster-specific metrics based on hardened assignments (maximum membership rule) and global partition criteria to evaluate how well-defined the fuzzy boundaries are.

Value

A list containing:

cluster_summary

Data frame with one row per cluster containing:

• Hard_Size: number of observations primarily assigned to the cluster.

• Avg_Membership: average membership of those observations.

• Avg_Margin: average difference between the largest and second-largest memberships, indicating the clarity of assignment.

partition_coefficient

Global partition coefficient (PC).

partition_entropy

Global partition entropy (PE).

Plot Fuzzy Dictionary

Description

Plots the triangular fuzzy numbers defining the Likert-scale dictionary.

Usage

plot_dictionary(object, show_title = TRUE, ...)

Arguments

Value

Invisibly returns NULL.

Plot Cluster Prototypes

Description

Visualizes cluster prototypes as interval plots using triangular fuzzy numbers (l, c, r).

Usage

plot_prototypes(
  object,
  cluster = 1,
  view = c("single", "global"),
  use_var_names = FALSE,
  var_names = NULL,
  show_title = TRUE,
  ...
)

Arguments

Value

Invisibly returns NULL.

Plot Xie-Beni Index

Description

Plots the Xie-Beni validity index across candidate numbers of clusters.

Usage

plot_xb(object, mark_optimal = TRUE, type = "b", show_title = TRUE, ...)

Arguments

Value

Invisibly returns NULL.

Prepare Input System

Description

Prepares and validates all input components required for fuzzy clustering analysis.

Usage

prepare_input_system(data, type = "symmetric", option = "A", dictionary = NULL)

Arguments

Details

The function performs the following steps: 1. Validates raw data 2. Builds fuzzy dictionary 3. Validates data values against dictionary 4. Converts data into triangular fuzzy numbers (TFN)

Value

A list containing processed system inputs.

Print Method for fcmTFN Objects

Description

Displays a concise summary of a fitted fuzzy C-means model using triangular fuzzy numbers.

Usage

print_fcmTFN(x, ...)

Arguments

Value

The input object (invisibly).

Prototype Results

Description

Returns cluster prototypes either as a flat matrix or as a list of tables containing l, c, r values for each variable.

Usage

prototype_results(
  object,
  use_var_names = FALSE,
  var_names = NULL,
  format = c("flat", "table")
)

Arguments

Value

If format = "flat", a data.frame containing prototype values.

If format = "table", a named list of data.frames, one for each cluster.

Select Optimal Number of Clusters

Description

Runs the fuzzy clustering algorithm for multiple candidate values of k and selects the optimal one using the Xie-Beni index.

Usage

select_optimal_k(
  fuzzy_data,
  k_values,
  m = 2,
  epsilon = 1e-06,
  max_iter = 100,
  verbose = TRUE
)

Arguments

Value

A list containing:

• best_k Optimal number of clusters

• xb_values Xie-Beni values

• results List of clustering results

Simulated Likert 1–7 Survey Dataset

Description

A simulated Likert-type dataset with three well-separated clusters, specifically designed for testing fuzzy clustering of ordinal data.

Usage

sim_likert7

Format

A data frame with 300 rows and 12 variables:

Q1

Simulated survey response measured on a 1–7 Likert scale.

Q10

Simulated survey response measured on a 1–7 Likert scale.

Q11

Simulated survey response measured on a 1–7 Likert scale.

Q12

Simulated survey response measured on a 1–7 Likert scale.

Q2

Simulated survey response measured on a 1–7 Likert scale.

Q3

Simulated survey response measured on a 1–7 Likert scale.

Q4

Simulated survey response measured on a 1–7 Likert scale.

Q5

Simulated survey response measured on a 1–7 Likert scale.

Q6

Simulated survey response measured on a 1–7 Likert scale.

Q7

Simulated survey response measured on a 1–7 Likert scale.

Q8

Simulated survey response measured on a 1–7 Likert scale.

Q9

Simulated survey response measured on a 1–7 Likert scale.

Details

The dataset contains 300 observations divided into three distinct clusters of 100 observations each. Data generation was based on three latent profiles centered approximately at:

• Low agreement: \approx 2

• Moderate agreement: \approx 4

• High agreement: \approx 6

Source

Simulated data generated for package examples.

Student Wellbeing During COVID-19

Description

Survey data on subjective well-being, optimism, gratitude, emotional closeness, worry, and depression, collected from university students.

Usage

students_wellbeing

Format

A data frame with 651 rows and 9 variables:

Details

All variables are measured on an 11-point ordinal scale ranging from 0 to 10, where higher values indicate greater satisfaction.

Source

Martinez, L., Valencia, I., Trofimoff, V., & Valenzuela, L. S. (2020). Students wellbeing during COVID-19. <doi:10.17632/w9brygpwg7.2>

Summary for fcmTFN Objects

Description

Displays a summary of the Fuzzy C-Means clustering results for triangular fuzzy numbers.

Usage

## S3 method for class 'fcmTFN'
summary(object, ...)

Arguments

Value

Prints a formatted summary of the clustering result.

Update Membership Matrix

Description

Updates the fuzzy membership matrix (U) based on distances between observations and cluster prototypes.

Usage

update_membership(fuzzy_data, prototypes, wc, ws, m = 2)

Arguments

Value

Updated membership matrix U.

Validate Asymmetric Fuzzy Dictionary

Description

Validates a user-defined asymmetric triangular fuzzy number (TFN) dictionary to ensure structural consistency with the selected scale.

Usage

validate_asymmetric_dictionary(matrix, option)

Arguments

Details

The function verifies: - Object type (matrix) - Number of columns (l, c, r) - Number of rows according to selected option - Valid modal values - Logical ordering (l <= c <= r) - Value bounds within allowed scale limits

Value

Invisibly returns TRUE if validation passes.

Validate Input Data

Description

Checks that the input data object is valid for fuzzy clustering analysis.

Usage

validate_data(data)

Arguments

Details

The function verifies: - Object type (data.frame or matrix) - Non-zero dimensions - Absence of missing values

Value

Invisibly returns TRUE if validation passes.

Validate Data Values Against Dictionary

Description

Checks that all values in the input data are present in the fuzzy dictionary modes.

Usage

validate_data_values(data, dictionary)

Arguments

Details

The function verifies that every unique value in the dataset matches a valid dictionary key.

Value

Invisibly returns TRUE if validation passes.