added read_image_resulsts() function

added a function to load results of charcoal analyses made with ImageJ

DESCRIPTION

@@ -1,7 +1,7 @@
 Package: tapas
 Title: Trend And PeAkS analysis in paleo-ecological time series
-Version: 0.1.3
-Date: 03-01-2023
+Version: 0.1.4
+Date: 18-04-2024
 Authors@R:
   c(
     person("Walter", "Finsinger", , "walter.finsinger@umontpellier.fr",

NAMESPACE

@@ -15,13 +15,15 @@ export(plot_ar_i)
 export(plot_raw)
 export(pretreatment)
 export(pretreatment_data)
+export(read_imagej_results)
 export(tapas2mgcv)
 export(tapas_export)
 importFrom(changepoint,cpt.meanvar)
 importFrom(changepoint,cpts)
 importFrom(dplyr,"%>%")
 importFrom(dplyr,all_of)
 importFrom(dplyr,bind_cols)
+importFrom(dplyr,bind_rows)
 importFrom(dplyr,count)
 importFrom(dplyr,everything)
 importFrom(dplyr,left_join)
@@ -66,3 +68,4 @@ importFrom(stats,sd)
 importFrom(stringr,str_remove)
 importFrom(stringr,str_replace)
 importFrom(tidyselect,last_col)
+importFrom(utils,read.csv)

NEWS.md

@@ -1,4 +1,9 @@
 
+# tapas 0.1.4
+
+- added a function to load results of charcoal analyses made with ImageJ
+
+
 # tapas 0.1.3
 
 - modified the pretreatment() function to calculate sediment-accumulation

R/read_imagej_results.R

@@ -0,0 +1,119 @@
+#' Reads results of charcoal analyses made with ImageJ
+#'
+#' @param folder_in Sets the path to the directory where the *.csv files are
+#'                  located (e.g. "./data_in/")
+#' @param metadata A vector that describes the metadata stored in the file names.
+#'                 By default, metadata = c("core_id", "depth", "image_id"),
+#'                 for file names formatted as "CoreID_Depth_ImageID.csv".
+#'                 However, other file name formats are possible. See the
+#'                 Description here below.
+#' @param image_id_default Specifies the value or character that shall be
+#'                          added if the file name does not include the
+#'                          information for the ImageID. By default,
+#'                          \code{image_id_default = "a"}.
+#'
+#' @description
+#' The function loads spreadsheets obtained with ImageJ (https://imagej.net/)
+#' that were stored as *.csv files (comma-separated) in a common folder whose
+#' path is specified by the \code{folder_in} argument.
+#' The function expects that the file names include a set of information that
+#' identify the samples unequivocally, and that the information is given as
+#' strings separated by a dash (-) or an underscore (_) (do not use empty
+#' spaces (space bar) to separate the metadata).
+#'
+#' By default the following information is expected:
+#'  - a site identifier;
+#'  - a sample identifier, for instance the master core depth;
+#'  - an image identifier (a character string) in case several images were
+#'     taken for a sample. If only one image was taken from a sample, the
+#'     image identifier is optional (an "a" will be added if the file name does
+#'     not include this information).
+#'
+#' However, the function allows to use a different set and number of
+#' identifiers. Possible alternatives may include:
+#' - "CoreID_SectionID_Depth_ImageID.csv" or
+#' - "CoreID_SectionID_DepthInDrive_ImageID.csv".
+#'
+#' If the file names include a "depth" value, make sure to take note as to
+#' which depth values are mentioned (top depth, mid depth, bottom depth), as
+#' well as to which depth scale the values are referring to (e.g. the master
+#' core depth, depth in drive, or other).
+#' Further, make sure the file names include useful information to link
+#' the data with other data types from the same sediment archive,
+#' such as the chronology or other proxy data.
+#'
+#' @returns
+#' A data.frame with the specified metadata columns, and all columns that
+#'  are common to all input files.
+#'
+#' @author Walter Finsinger
+#'
+#' @export
+#'
+#' @importFrom dplyr bind_cols
+#' @importFrom dplyr bind_rows
+#' @importFrom utils read.csv
+
+read_imagej_results <- function(folder_in = NULL,
+                                metadata = c("site_id", "depth", "image_id"),
+                                image_id_default = "a") {
+
+  ## Read file names in the 'folder_in'
+  file_names <- list.files(folder_in)
+  n_files <- length(file_names)
+
+  ## Loop to read the *.csv files, split the file names, and add columns with
+  ## metadata written in the file names:
+  df_list <- list()
+
+  for (i in 1:n_files) {
+    # i = 1
+    ## Get the metadata from the file name:
+    f_ids_i <- unlist(strsplit(file_names[i], split = '[. _ -]+'))
+    f_ids_i <- f_ids_i[!f_ids_i == "csv"]
+
+    # Check if file name is compatible with the desired metadata:
+    if (!length(f_ids_i) == length(metadata) &&
+        !length(f_ids_i) == length(metadata) - 1) {
+      stop(print(
+        paste("The filename", file_names[i],
+              "is incompatible with the desired set of metadata")))
+    }
+
+
+    # If the file name passes the check-up, write metadata in metadata_i:
+    if (length(f_ids_i) == length(metadata) - 1) {
+      f_ids_i[length(f_ids_i) + 1] <- image_id_default
+    }
+
+    metadata_i <- matrix(NA, ncol = length(metadata))
+    colnames(metadata_i) <- metadata
+
+    for (j in 1:length(metadata)) {
+      if (metadata[j] == "depth") {
+        metadata_i[j] <- as.numeric(f_ids_i[j])
+      } else {
+        metadata_i[j] <- f_ids_i[j]
+      }
+    }
+
+    ## Get data from the .csv file:
+    f_data_i <- read.csv(paste0(folder_in, file_names[i]))
+    colnames(f_data_i)[1] <- "char_id"
+
+    ## If the file has no data but has been saved:
+    if (dim(f_data_i)[1] == 0) {
+      f_data_i[1, ] <- 0
+    }
+
+    ## Add metadata to the loaded data.frame, and move it to the list:
+    f_data_i <- dplyr::bind_cols(metadata_i, f_data_i)
+    df_list[[i]] <- f_data_i
+  }
+
+  ## Gather data from list of data.frames
+  df <- dplyr::bind_rows(df_list)
+
+  ## Return output:
+  return(df)
+}