R/create_relation_matrix.R

In ISMtools: Interpretive Structural Modelling Analysis Tools

#' Create or Convert to Adjacency Matrix
#'
#' Creates a new adjacency matrix or converts existing data to an adjacency
#' matrix format suitable for ISM analysis.
#'
#' @param input Input data. Accepts:
#'   \itemize{
#'     \item Integer n: creates an n x n zero matrix
#'     \item Matrix: validates and returns (or converts from edge list)
#'     \item Data frame: converts from edge list format
#'   }
#' @param from Column position or name for source nodes (when input is an edge
#'   list). Default is 1.
#' @param to Column position or name for target nodes (when input is an edge
#'   list). Default is 2.
#' @param nodes Optional character vector of predefined node names. Ensures
#'   matrix completeness when converting from edge lists.
#'
#' @return A square adjacency matrix with node labels as dimnames. A value of 1
#'   at position (i,j) indicates a directed relationship from element i to
#'   element j.
#'
#' @details
#' This function provides a unified interface for creating adjacency matrices
#' in ISM analysis. It handles three common scenarios:
#' \enumerate{
#'   \item Creating an empty matrix of specified size for manual population
#'   \item Converting edge list data (data.frame or matrix) to adjacency format
#'   \item Validating existing adjacency matrices
#' }
#'
#' @seealso
#' \code{\link{convert_to_matrix}} for the underlying conversion logic,
#' \code{\link{compute_reachability}} for computing reachability matrices.
#'
#' @export
#' @examples
#' # Create a 3x3 zero matrix
#' create_relation_matrix(3)
#'
#' # Create with custom node labels
#' create_relation_matrix(3, nodes = c("A", "B", "C"))
#'
#' # Convert edge list data.frame
#' edge_df <- data.frame(source = c("A", "B"), target = c("B", "C"))
#' create_relation_matrix(edge_df, from = "source", to = "target",
#'                        nodes = LETTERS[1:4])
#'
#' # Validate existing matrix
#' existing_mat <- matrix(c(0, 1, 1, 0), nrow = 2)
#' create_relation_matrix(existing_mat)
create_relation_matrix <- function(input, from = 1, to = 2, nodes = NULL) {
  # Scenario 1: Create empty matrix
  if (is.numeric(input) && length(input) == 1) {
    n <- as.integer(input)
    if (n <= 0) {
      stop("Matrix dimension must be a positive integer", call. = FALSE)
    }

    node_names <- if (is.null(nodes)) as.character(seq_len(n)) else nodes
    if (length(node_names) != n) {
      stop("Length of 'nodes' must equal matrix dimension", call. = FALSE)
    }

    matrix(0, nrow = n, ncol = n, dimnames = list(node_names, node_names))

  # Scenario 2: Process matrix/data frame
  } else {
    # Reuse conversion logic from convert_to_matrix
    adj_matrix <- convert_to_matrix(
      x = input,
      from = from,
      to = to,
      nodes = nodes
    )

    # Additional matrix validation
    if (nrow(adj_matrix) != ncol(adj_matrix)) {
      stop("Converted matrix must be square. Current dimension: ",
           nrow(adj_matrix), "x", ncol(adj_matrix),
           call. = FALSE)
    }

    adj_matrix
  }
}