R/ifcb_replace_mat_values.R

Defines functions ifcb_replace_mat_values

Documented in ifcb_replace_mat_values

#' Replace Values in MATLAB Classlist
#'
#' This function replaces a target class ID with a new ID in MATLAB classlist files,
#' generated by the code in the `ifcb-analysis` repository (Sosik and Olson 2007).
#'
#' @details
#' The MAT files are read and written directly from R, producing output
#' identical to the MATLAB `ifcb-analysis` format.
#'
#' @param manual_folder A character string specifying the path to the folder containing MAT classlist files to be updated.
#' @param out_folder A character string specifying the path to the folder where updated MAT classlist files will be saved.
#' @param target_id The target class ID to be replaced.
#' @param new_id The new class ID to replace the target ID.
#' @param column_index An integer value specifying which classlist column to edit. Default is 1 (manual).
#' @param do_compression A logical value indicating whether to compress the .mat file. Default is TRUE.
#'
#' @return This function does not return any value; it updates the classlist files in the specified directory.
#' @seealso \url{https://github.com/hsosik/ifcb-analysis}
#' @references Sosik, H. M. and Olson, R. J. (2007), Automated taxonomic classification of phytoplankton sampled with imaging-in-flow cytometry. Limnol. Oceanogr: Methods 5, 204–216.
#' @examples
#' \dontrun{
#' # Replace class ID 99 with 1 in .mat classlist files
#' ifcb_replace_mat_values("output/manual", "output/manual", 99, 1, column_index = 1)
#' }
#' @export
ifcb_replace_mat_values <- function(manual_folder, out_folder, target_id, new_id, column_index = 1, do_compression = TRUE) {

  # Check if the manual_folder exists
  if (!dir.exists(manual_folder)) {
    cli_abort("The {.arg manual_folder} does not exist: {.file {manual_folder}}")
  }

  # Create the output folder if it does not exist
  if (!dir.exists(out_folder)) {
    dir.create(out_folder, recursive = TRUE)
  }

  # List files to be updated
  files <- list.files(manual_folder, pattern = "\\.mat$", full.names = TRUE)

  if (length(files) == 0) {
    cli_abort("No {.file .mat} files found in the manual folder: {.file {manual_folder}}")
  }

  for (i in seq_along(files)) {
    file_path_in <- files[i]

    # Skip empty/corrupt files
    if (file.size(file_path_in) == 0) {
      cli_warn("Empty {.file .mat} file: {.file {file_path_in}}. Skipping.")
      next
    }

    file_path_out <- file.path(out_folder, basename(files[i]))

    # Read the file, replace target_id with new_id in the requested classlist
    # column (column_index is 0-based, matching the previous Python behaviour),
    # and write the result back out
    mat_data <- read_mat_v5(file_path_in)
    classlist <- mat_data$classlist$data
    if (is.null(classlist)) {
      cli_abort("No {.field classlist} found in {.file {basename(file_path_in)}}.")
    }

    r_col <- as.integer(column_index) + 1L
    if (r_col < 1L || r_col > ncol(classlist)) {
      cli_abort(c(
        "{.arg column_index} ({column_index}) is out of range for {.file {basename(file_path_in)}}.",
        "i" = "The classlist has {ncol(classlist)} column{?s} (valid 0-based {.arg column_index}: 0:{ncol(classlist) - 1L})."
      ))
    }

    mask <- classlist[, r_col] == as.integer(target_id)
    mask[is.na(mask)] <- FALSE
    classlist[mask, r_col] <- as.integer(new_id)
    mat_data$classlist$data <- classlist
    # A classlist MATLAB stored in a narrow integer type (e.g. uint8) may no
    # longer hold new_id - ifcb_merge_manual() routinely writes ids above
    # 50000 here - so widen it to double rather than let the writer refuse.
    mat_data$classlist <- .mat_widen_numeric(mat_data$classlist)

    write_mat_v5(file_path_out, mat_data, do_compression = do_compression)
  }
}

Try the iRfcb package in your browser

Any scripts or data that you put into this service are public.

iRfcb documentation built on Aug. 20, 2026, 1:06 a.m.