.Rbuildignore

@@ -5,3 +5,7 @@
 ^\.github$
 ^LICENSE\.md$
 ^cran-comments\.md$
+^config_drugsens\.txt$
+^script_for_qupath\.txt$
+^assets$
+^CRAN-SUBMISSION$

.gitignore

@@ -8,3 +8,5 @@
 *.html
 figures/**
 temp/**
+.DS_Store
+*.txt

DESCRIPTION

 Package: drugsens
-Title: Automated Analysis of QuPath Output Data and Metadata Extraction
-Description: A comprehensive toolkit for analyzing microscopy data output from
-    QuPath software. Provides functionality for automated data processing,
-    metadata extraction, and statistical analysis of imaging results.
-    Designed to complement the STAR Protocol Protocol for quantifying drug 
-    sensitivity in 3D patient-derived ovarian cancer models 
-    10.1016/j.xpro.2024.103274.
+Title: Automated Analysis of 'QuPath' Output Data and Metadata Extraction
+Description: A comprehensive toolkit for analyzing microscopy data output from 'QuPath' software. 
+    Provides functionality for automated data processing, metadata extraction, and statistical 
+    analysis of imaging results. The methodology implemented in this package is based on 
+    Labrosse et al. (2024) <doi:10.1016/j.xpro.2024.103274> "Protocol for quantifying drug 
+    sensitivity in 3D patient-derived ovarian cancer models", which describes the complete 
+    workflow for drug sensitivity analysis in patient-derived cancer models.
 Version: 0.1.0
 BugReports: https://git.scicore.unibas.ch/ovca-research/drugsens/-/issues
 SystemRequirements: QuPath™ 4.0.0 or higher
 Authors@R: c(
-    person("Flavio", "Lombardo", , "flavio.lombardo@unibas.ch", role = c("aut", "cre", "cph")),
+    person("Flavio", "Lombardo", , "flavio.lombardo@unibas.ch", role = c("aut", "cre", "cph"), comment = c(ORCID = "0000-0002-4853-6838")),
     person("Ricardo Coelho", role = c("cph")),   
     person("Ovarian Cancer Research", role = c("cph")),   
     person("University of Basel and University Hospital Basel", role = c("cph"))   
@@ -19,16 +19,16 @@ URL: https://git.scicore.unibas.ch/ovca-research/drugsens/
 Maintainer: Flavio Lombardo <flavio.lombardo@unibas.ch>
 License: MIT + file LICENSE
 Imports:
-    utils,
     dplyr,
-    tidyr,
-    readr,
-    stringr,
-    knitr,
     ggplot2,
     ggpubr,
+    knitr,
     roxygen2,
+    stats,
+    stringr,
+    tidyr,
     tidyselect,
+    utils,
     testthat (>= 3.0.0)
 Depends: 
     R (>= 4.2)

NAMESPACE

@@ -7,6 +7,7 @@ export(get_QC_plots)
 export(get_QC_plots_parsed_merged_data)
 export(make_count_dataframe)
 export(make_run_config)
+export(string_parsing)
 import(ggplot2)
 import(ggpubr)
 import(knitr)
@@ -14,7 +15,18 @@ import(roxygen2)
 import(testthat)
 importFrom(dplyr,filter)
 importFrom(dplyr,select)
-importFrom(readr,write_excel_csv)
+importFrom(ggplot2,aes)
+importFrom(ggplot2,aes_string)
+importFrom(ggplot2,element_text)
+importFrom(ggplot2,facet_wrap)
+importFrom(ggplot2,geom_boxplot)
+importFrom(ggplot2,geom_jitter)
+importFrom(ggplot2,geom_violin)
+importFrom(ggplot2,ggplot)
+importFrom(ggplot2,labs)
+importFrom(ggplot2,position_jitter)
+importFrom(ggplot2,stat_summary)
+importFrom(ggplot2,theme)
 importFrom(stats,setNames)
 importFrom(stringr,str_count)
 importFrom(stringr,str_extract)

R/change_data_format_to_longer.R

 #' Reformat the counts data in longer format
 #' @description
 #' This function gets the count data data.frame, that has a wider format and it returns a longer-formatted data.frame
+#' @title Data format changer
 #' @importFrom tidyr pivot_longer
 #' @importFrom dplyr select
 #' @importFrom tidyselect any_of
@@ -11,17 +12,25 @@
 #' @param unique_name_row_identifier String that indicates the unique identifier for each image, defaults as "filter_image"
 #' @export
 #' @examples
-#' list_of_relabeling =list(  "PathCellObject" = "onlyDAPIPositve",
-#' "cCasp3" = "cCASP3",  "E-Cadherin: cCASP3" = "E-Cadherin and cCASP3",
-#' "EpCAM_E-Cadherin" = "E-Cadherin",
-#' "EpCAM_E-Cadherin and cCASP3" = "E-Cadherin and cCASP3")
-#' bind_data <- data_binding(path_to_the_projects_folder =
-#' system.file("extdata/to_merge/", package = "drugsens"))
+#' \donttest{
+#' # Set up relabeling list
+#' list_of_relabeling <- list(
+#'   "PathCellObject" = "onlyDAPIPositve",
+#'   "cCasp3" = "cCASP3",
+#'   "E-Cadherin: cCASP3" = "E-Cadherin and cCASP3",
+#'   "EpCAM_E-Cadherin" = "E-Cadherin",
+#'   "EpCAM_E-Cadherin and cCASP3" = "E-Cadherin and cCASP3"
+#' )
+#'
+#' # Load and process example data
+#' bind_data <- data_binding(
+#'   path_to_the_projects_folder = system.file("extdata/to_merge/", package = "drugsens")
+#' )
 #' counts_dataframe <- make_count_dataframe(bind_data)
-#' plotting_ready_dataframe <-
-#' change_data_format_to_longer(counts_dataframe)
-
-# adding the image number so to identify the distribution
+#'
+#' # Convert to long format
+#' plotting_ready_dataframe <- change_data_format_to_longer(counts_dataframe)
+#' }
 
 # pivot_longer
 change_data_format_to_longer <- function(.data,

R/data_binding.R

 # Get a list of all the files that are in a user-specified folder and get a list of full paths
+#' Internal utility functions for file handling
+#' @name utils_internal
 #' @description
-#' This function lists the content of a selected folder either recursively or not
+#' This file contains internal utility functions for file handling and processing
 #' @keywords internal
-#' @returns list
-#' @name   "Name", "list_of_relabeling", "marker_positivity","marker_positivity_ratio", "x", "y"
 #' @importFrom utils read.csv
 #' @importFrom stats setNames
 #' @import roxygen2
-#'
-
-# important for the scripts
-globalVariables(c(
-  "Name", "list_of_relabeling", "marker_positivity",
-  "marker_positivity_ratio", "x", "y"
-))
+#' @examples
+#' \donttest{
+#' # Load example data from package
+#' bind_data <- data_binding(
+#'   path_to_the_projects_folder = system.file("extdata/to_merge/", package = "drugsens")
+#' )
+#' }
 
 # list all the files
 list_all_files <- function(define_path, extension, recursive_search) {
@@ -33,13 +33,14 @@ list_all_files <- function(define_path, extension, recursive_search) {
   )
 }
 
-# Helper function to read and process a single file
-#' @description
-#' This function returns a processed single file
+# Process a Single File
+#' @title Process a Single File
+#' @name process_file
+#' @description This function returns a processed single file
 #' @param file_path Path to the file
 #' @param extension String File extension to filter
 #' @keywords internal
-#' @returns dataframe
+#' @return dataframe
 process_file <- function(file_path,
                          # relabeling_map,
                          extension) {
@@ -85,27 +86,31 @@ process_file <- function(file_path,
 }
 
 #' Merge all the dataframes coming out from the QuPath
+#' @name data_binding
 #' @description
-#' This function try to guess the string patterns that are in the dataset and then fill the dataframe
-#' with that information. Finally the data is combined and combined them into one file
+#' This function identifies string patterns in the dataset, fills the dataframe
+#' with that information, and combines all data into a single file
 #' @import knitr
 #' @importFrom stringr str_extract
-#' @return A `dataframe`/`tibble`.
 #' @param path_to_the_projects_folder String/Path The path where the files coming out of QuPath are located
 #' @param files_extension_to_look_for String The extension of the file outputted from QuPath, (default is "csv")
 #' @param recursive_search Boolean, it defined the behavior of the file search, if recursive or not, (default is FALSE)
-#' @returns Returns a concatenated dataframe from all the files within the indicated one
+#' @param forcePath String defining an alternative path to the confic file
+#' @return A concatenated dataframe from all the files within the indicated path
 #' @export
 #' @examples
+#' \dontrun{
 #' bind_data <- data_binding(path_to_the_projects_folder = system.file("extdata/to_merge/",
-#' package = "drugsens"))
-#' #This will return the dataframe of all the data in the folder
+#'                          package = "drugsens"))
+#'}
+
 # Main function to bind data from multiple files
 data_binding <- function(path_to_the_projects_folder,
                          files_extension_to_look_for = "csv",
-                         recursive_search = FALSE) {
+                         recursive_search = FALSE,
+                         forcePath = NULL) {
   # run configuration file
-  make_run_config()
+  make_run_config(forcePath = forcePath)
 
   # Validate input parameters
   if (!dir.exists(path_to_the_projects_folder)) {

R/generate_qu_path_script.R → R/generate_qupath_script.R

@@ -2,13 +2,24 @@
 #' @description
 #' Generate a useful script to consistently save the output data from QuPath in .csv format following the naming conventions
 #' followed during the package development.
-#'
-#' @return `script_for_qupath.txt` in local working directory.
-#'
+#' @param output_dir Directory where the script should be saved. If NULL, uses tempdir()
+#' @return Invisibly returns the path to the generated script file.
 #' @export
 #' @examples
-#' generate_qupath_script()
-generate_qupath_script <- function() {
+#' \dontrun{
+#'   # Generate script in a temporary directory
+#'   generate_qupath_script()
+#'
+#'   # Generate script in a specific directory
+#'   output_dir <- tempdir()
+#'   generate_qupath_script(output_dir = output_dir)
+#' }
+generate_qupath_script <- function(output_dir = NULL) {
+  if(is.null(output_dir)) {
+    output_dir <- tempdir()
+  }
+  output_file <- file.path(output_dir, "script_for_qupath.txt")
+
   write(
     x = paste0('
 //This code script was tested with QuPath 4
@@ -53,9 +64,9 @@ def exporter  = new MeasurementExporter()
 
 print "Done!"
       '),
-    file = paste0(path.expand(getwd()), "/script_for_qupath.txt")
+    file = output_file
   )
   message("You can now take the script and personalize it to your needs")
-  message(paste0(Sys.time(), " The script file was generated here: ", getwd(), "/"))
+  message(paste0(Sys.time(), " The script file was generated here: ", output_file, "/"))
   message(paste0(Sys.time(), " Please make sure to follow the name convention here proposed, or it might fail to get all the information"))
 }

R/get_QC_plots.R

 #' Plot some QC plots to define that everything ran correctly
 #' @description
-#' Plot data to visualize immediate trends
-#' @param .data The preprocessed data (after running make_count_dataframe() and change_data_format_to_longer()) merged data.frame that should be visualized
+#' Plot data to visualize immediate trends. This function expects data that has been processed
+#' through make_count_dataframe() and change_data_format_to_longer() to ensure the correct
+#' data structure for plotting.
+#' @param .data The preprocessed data (after running make_count_dataframe() and change_data_format_to_longer())
+#'              merged data.frame that should be visualized
 #' @param patient_column_name The PID's column name in the merged data.frame (defaults to "PID")
-#' @param colors  A list of colors to supply to personalize the plot, as default 4 colors c("dark green", "red", "orange", "pink")
-#' @param save_plots  A Boolean value indicating if the plots should be saved or not, TRUE for saving in the current working directory, FALSE to not. Default is FALSE
-#' @param folder_name A string indicating the name of the folder where to save the plots in case that save_plots = TRUE
+#' @param colors A list of colors to supply to personalize the plot, defaults to c("darkgreen", "red", "orange", "pink")
+#' @param save_plots A Boolean value indicating if the plots should be saved or not (default is FALSE)
+#' @param folder_name A string indicating the name of the folder where to save the plots if save_plots is TRUE
 #' @param isolate_a_specific_patient A string indicating the patient name to isolate for single plot case (default is NULL)
 #' @param x_plot_var A string indicating the treatment's full name for the QC plots (default is "Treatment_complete")
-#'
 #' @import ggplot2
 #' @import ggpubr
 #' @importFrom dplyr filter
-#' @return A `dataframe`/`tibble`.
-#' @example
-#' \dontrun{get_QC_plots(longer_format_dataframe, patient_column_name = "PID", save_plots = TRUE, folder_name = "figures")}
+#' @return Invisibly returns NULL, but saves plots to disk if save_plots is TRUE
+#' @examples
+#' \donttest{
+#' # First process example data
+#' example_path <- system.file("extdata/to_merge/", package = "drugsens")
+#' raw_data <- data_binding(path_to_the_projects_folder = example_path)
+#' count_data <- make_count_dataframe(raw_data)
+#' processed_data <- change_data_format_to_longer(count_data)
+#'
+#' # Create and save plots to temporary directory
+#' temp_dir <- file.path(tempdir(), "qc_plots")
+#' get_QC_plots(
+#'   processed_data,
+#'   save_plots = TRUE,
+#'   folder_name = temp_dir
+#' )
+#'
+#' # Create plots for a specific patient
+#' get_QC_plots(
+#'   processed_data,
+#'   isolate_a_specific_patient = "B39",
+#'   save_plots = TRUE,
+#'   folder_name = temp_dir
+#' )
+#' }
 #' @export
 get_QC_plots <- function(.data,
                          patient_column_name = "PID",
                          colors = c("darkgreen", "red", "orange", "pink"),
                          save_plots = FALSE,
-                         folder_name = "figures",
+                         folder_name = NULL,
                          x_plot_var = "Treatment_complete",
                          isolate_a_specific_patient = NULL) {
 
-  if (!is.null(isolate_a_specific_patient)) .data <- .data[.data[[patient_column_name]] == isolate_a_specific_patient, ]
-  if (nrow(.data) < 1) stop("The data cannot be empty")
+  # Input validation
+  if (!is.data.frame(.data)) {
+    stop("Input must be a data frame")
+  }
 
-  # run for every unique PID the QC plot
-  for (i in unique(.data[patient_column_name])) {
-    message(paste0("Running the QC plot function for PID: ", i))
+  # Check required columns exist
+  required_cols <- c(patient_column_name, x_plot_var, "marker_positivity", "marker_positivity_ratio")
+  missing_cols <- setdiff(required_cols, colnames(.data))
+  if (length(missing_cols) > 0) {
+    stop("Missing required columns: ", paste(missing_cols, collapse = ", "),
+         ". Please ensure data has been processed with make_count_dataframe() and change_data_format_to_longer()")
+  }
 
-    QC_plot <- .data |>
-      dplyr::filter(.data[[patient_column_name]] == i) |>
-      ggplot(aes(x = !!as.name(x_plot_var), y = marker_positivity_ratio, col = marker_positivity)) +
-      geom_boxplot(
-        position = position_dodge(width = 1.0),
-      ) +
-      facet_wrap(~marker_positivity) +
-      geom_jitter(width = 0.15) +
-      theme_light() +
-      labs(title = paste0("Cell marker ratios for PID: ", i), color = "Cell marker") +
-      ylab("Percentage of expression marker (marker-positive-cells/total_cell_count)") +
-      xlab("Drugs") +
-      theme(axis.text.x = element_text(angle = 45, hjust = 1.0)) +
-      scale_color_manual(values = colors) +
-      stat_summary(
-        fun = "median", geom = "pointrange",
-        mapping = aes(xend = after_stat(x) - 0.25, yend = after_stat(y)),
-        size = 1.5, alpha = 1.0,
-        position = position_dodge(width = 1)
-      ) +
-      stat_summary(
-        geom = "line", fun = "median", position = position_dodge(width = 1),
-        size = 1, alpha = 0.3, aes(group = marker_positivity)
+  # Filter for specific patient if requested
+  if (!is.null(isolate_a_specific_patient)) {
+    .data <- .data[.data[[patient_column_name]] == isolate_a_specific_patient, ]
+    if (nrow(.data) < 1) {
+      stop("No data found for patient: ", isolate_a_specific_patient)
+    }
+  }
+
+  # Set up output directory if saving plots
+  if (save_plots) {
+    if (is.null(folder_name)) {
+      folder_name <- file.path(tempdir(), "figures")
+    }
+    dir.create(folder_name, showWarnings = FALSE, recursive = TRUE)
+  }
+
+  # Process each patient
+  for (current_pid in unique(.data[[patient_column_name]])) {
+    message("Processing patient: ", current_pid)
+
+    # Filter data for current patient
+    patient_data <- dplyr::filter(.data, .data[[patient_column_name]] == current_pid)
+
+    # Create the plot
+    QC_plot <- ggplot2::ggplot(patient_data,
+                               ggplot2::aes(x = .data[[x_plot_var]],
+                                            y = marker_positivity_ratio,
+                                            color = marker_positivity)) +
+      ggplot2::geom_boxplot(position = ggplot2::position_dodge(width = 1.0)) +
+      ggplot2::facet_wrap(~marker_positivity) +
+      ggplot2::geom_jitter(width = 0.15) +
+      ggplot2::theme_light() +
+      ggplot2::labs(
+        title = paste0("Cell marker ratios for PID: ", current_pid),
+        color = "Cell marker",
+        y = "Percentage of expression marker (marker-positive-cells/total_cell_count)",
+        x = "Drugs"
       ) +
-      theme(
-        axis.title.x = element_blank(),
-        plot.title = element_text(hjust = 0.5),
-        axis.ticks.x = element_blank(),
-        panel.grid = element_blank(),
-        strip.background = element_rect(
+      ggplot2::theme(
+        axis.text.x = ggplot2::element_text(angle = 45, hjust = 1.0),
+        axis.title.x = ggplot2::element_blank(),
+        plot.title = ggplot2::element_text(hjust = 0.5),
+        axis.ticks.x = ggplot2::element_blank(),
+        panel.grid = ggplot2::element_blank(),
+        strip.background = ggplot2::element_rect(
           colour = "black",
           fill = "grey1"
         )
+      ) +
+      ggplot2::scale_color_manual(values = colors) +
+      ggplot2::stat_summary(
+        fun = "median",
+        geom = "point",
+        size = 3,
+        position = ggplot2::position_dodge(width = 1)
+      ) +
+      ggplot2::stat_summary(
+        geom = "line",
+        fun = "median",
+        position = ggplot2::position_dodge(width = 1),
+        linewidth = 1,
+        alpha = 0.3,
+        aes(group = marker_positivity)
       )
 
+    # Save the plot if requested
     if (save_plots) {
-      if (!dir.exists(paths = paste0(getwd(), "/", folder_name, "/"))) dir.create(path = paste0(getwd(), "/", folder_name, "/"), showWarnings = F, recursive = T)
+      plot_filename <- file.path(
+        folder_name,
+        paste0("patients_QC_box_plots_",
+               current_pid,
+               "_median",
+               format(Sys.Date(), "%Y-%m-%d"),
+               ".pdf"
+        )
+      )
 
-      ggsave(QC_plot,
-        filename = paste0(folder_name, "/", "patients_QC_box_plots_", i, "_", "median", Sys.Date(), ".pdf"),
+      ggplot2::ggsave(
+        filename = plot_filename,
+        plot = QC_plot,
         device = "pdf",
         height = 12,
         width = 12
       )
     }
   }
-  message(paste0("If save_plots = TRUE, the plots will be saved here:", paste0(folder_name, "/", "patients_QC_box_plots_", "median", Sys.Date(), ".pdf")))
+
+  # Final message about plot locations
+  if (save_plots) {
+    message("Plots have been saved in: ", folder_name)
+  }
+
+  invisible(NULL)
 }

R/get_QC_plots_and_stats.R

-#' Plot some QC plots for the bound data
+#' Plot QC plots and calculate statistics for bound data
 #' @description
-#' This plot can show trends within the dataset and run some basic statistics.
+#' This function creates quality control plots and calculates basic statistics for microscopy data.
+#' The plots provide visual insights into marker expression patterns and data quality.
+#' @param .data The preprocessed data frame to analyze
+#' @param list_of_columns_to_plot Columns to include in plots. If NULL, all numeric columns are used.
+#' @param save_plots Logical, whether to save plots to files. Defaults to FALSE.
+#' @param saving_plots_folder Directory for saving plots. If NULL and save_plots=TRUE, uses a subdirectory of tempdir().
+#' @param save_plots_in_patient_specific_subfolders Logical, whether to create patient subdirectories. Defaults to TRUE.
+#' @param fill_color_variable Variable name for plot color filling
+#' @param PID_column_name Column name for patient IDs. Defaults to "PID".
+#' @param isolate_specific_drug Drug name to subset data
+#' @param isolate_specific_patient Patient ID to subset data
+#' @param drug_column_name Column name for drug information. Defaults to "Treatment".
+#' @param save_list_of_plots Logical, whether to return list of plot objects. Defaults to TRUE.
+#' @param p_height Plot height in inches. Defaults to 10.
+#' @param p_width Plot width in inches. Defaults to 10.
+#' @param verbose Logical, whether to show progress messages. Defaults to TRUE.
+#' @return If save_list_of_plots=TRUE, returns a named list of ggplot objects. Otherwise returns invisible(NULL).
+#' @importFrom ggplot2 ggplot aes geom_violin geom_boxplot facet_wrap theme element_text labs
+#'             geom_jitter position_jitter stat_summary aes_string
+#' @examples
+#' \donttest{
+#' # First load and process example data
+#' example_path <- system.file("extdata/to_merge/", package = "drugsens")
+#' raw_data <- data_binding(path_to_the_projects_folder = example_path)
+#' count_data <- make_count_dataframe(raw_data)
+#' processed_data <- change_data_format_to_longer(count_data)
 #'
-#' @param .data The preprocessed data (after running make_count_dataframe() and change_data_format_to_longer()) merged data.frame that should be visualized
-#' @param list_of_columns_to_plot The preprocessed data (after running make_count_dataframe() and change_data_format_to_longer()) merged data.frame that should be visualized
-#' @param save_plots Boolean, TRUE if plots should be saved (default is FALSE)
-#' @param saving_plots_folder String indicating the folder where the plots should be stored (default is "figures")
-#' @param PID_column_name String, indicating the name of the sample to subset (default is "PID")
-#' @param isolate_specific_drug String, indicating if there should be a Treatment specific data subset (default is NULL)
-#' @param isolate_specific_patient String, indicating a spacific sample to plot only (default is NULL)
-#' @param PID_column_name String, indicating the name of the sample to subset (default is "Treatment")
-#' @param save_list_of_plots Boolean, if TRUE returns a named list of all the plots ran (default is TRUE), this can be usefult to isolate specific plots
-#' @param save_plots_in_patient_specific_subfolders Boolean, if TRUE the plots will be saved (if `save_plots` TRUE) in sample specific folders (default is TRUE)
-#' @param fill_color_variable Boolean, String, indicating the name of the variable (discrete) to use for the plot's filling
-#' @param p_height Integer, indicate the plot's height (default is 10 inches)
-#' @param p_width Integer, indicate the plot's width (default is 10 inches)
-#' @param drug_column_name String, indicate the column indicating the Drug/Treament (default is "Treatment")
+#' # Basic usage - create plots for all patients
+#' plots <- get_QC_plots_parsed_merged_data(processed_data)
 #'
-#' @import ggplot2
-#' @import ggpubr
-#' @importFrom readr write_excel_csv
-#' @importFrom dplyr filter
-#' @return A `list`/`NULL`.
-#' @example
-#' \dontrun {qc <- get_QC_plots_parsed_merged_data(bind_data, save_plots = TRUE, save_list_of_plots = TRUE)}
+#' # Save plots to a temporary directory
+#' temp_dir <- file.path(tempdir(), "qc_plots")
+#' plots <- get_QC_plots_parsed_merged_data(
+#'   processed_data,
+#'   save_plots = TRUE,
+#'   saving_plots_folder = temp_dir
+#' )
+#'
+#' # Focus on a specific patient
+#' plots <- get_QC_plots_parsed_merged_data(
+#'   processed_data,
+#'   isolate_specific_patient = "B39"
+#' )
+#'
+#' # Color plots by tissue type
+#' plots <- get_QC_plots_parsed_merged_data(
+#'   processed_data,
+#'   fill_color_variable = "Tissue"
+#' )
+#' }
 #' @export
-
 get_QC_plots_parsed_merged_data <- function(.data,
                                             list_of_columns_to_plot = NULL,
                                             save_plots = FALSE,
-                                            saving_plots_folder = "figures",
+                                            saving_plots_folder = NULL,
                                             save_plots_in_patient_specific_subfolders = TRUE,
                                             fill_color_variable = NULL,
                                             PID_column_name = "PID",
@@ -38,127 +63,153 @@ get_QC_plots_parsed_merged_data <- function(.data,
                                             drug_column_name = "Treatment",
                                             save_list_of_plots = TRUE,
                                             p_height = 10,
-                                            p_width = 10) {
-  # List where plots could be stored
-  list_plottos <- list()
+                                            p_width = 10,
+                                            verbose = TRUE) {
+
+  # Define the helper function for creating individual QC plots
+  create_qc_plot <- function(data, metric, fill_var, pid, drug) {
+    p <- ggplot2::ggplot(data, ggplot2::aes(x = marker_positivity, y = unlist(data[[metric]])))
+
+    if (!is.null(fill_var)) {
+      p <- p + ggplot2::geom_violin(trim = FALSE,
+                                    ggplot2::aes_string(fill = fill_var),
+                                    color = NA)
+    } else {
+      p <- p + ggplot2::geom_violin(trim = FALSE,
+                                    fill = "#A4A4A4",
+                                    color = "darkred")
+    }
 
-  if (!is.data.frame(.data) | nrow(.data) < 1) stop("ERROR: the data provided must be not empty of dataframe type.")
+    p <- p +
+      theme_minimal() +
+      ggplot2::geom_boxplot(width = 0.1, fill = "white") +
+      ggplot2::facet_wrap(~Treatment) +
+      ggplot2::theme(axis.text.x = ggplot2::element_text(angle = 45, hjust = 1)) +
+      ggplot2::labs(
+        title = metric,
+        x = "Cell Markers",
+        y = paste0("Intensity of ", metric, " (log2)"),
+        subtitle = paste0(pid, ".", drug)
+      ) +
+      ggplot2::geom_jitter(shape = 16,
+                           position = ggplot2::position_jitter(0.01)) +
+      ggplot2::stat_summary(geom = "crossbar",
+                            fun = mean,
+                            colour = "red",
+                            width = 0.21)
+
+    return(p)
+  }
 
-  # get the number of possible plotting variables
-  if (is.null(list_of_columns_to_plot)) {
-    list_of_columns_to_plot <- colnames(.data)[which(sapply(.data, is.numeric))]
+  # Input validation
+  if (!is.data.frame(.data) || nrow(.data) < 1) {
+    stop("Input must be a non-empty data frame")
+  }
+
+  # Initialize plot storage
+  list_plottos <- list()
+
+  # If user requested to isolate specific patient, filter the data
+  if (!is.null(isolate_specific_patient)) {
+    .data <- .data[.data[[PID_column_name]] == isolate_specific_patient, ]
+    if (nrow(.data) < 1) {
+      stop("No data found for specified patient: ", isolate_specific_patient)
+    }
   }
 
-  # check that the fill_color_variable is in the dataset and not null
-  if (!is.null(fill_color_variable) & !fill_color_variable %in% colnames(.data)) stop("ERROR: the fill_color_variable must be in the colum names variables.")
+  # Set up output directory if saving plots
+  if (save_plots) {
+    # Initialize the base directory for plots
+    saving_plots_folder <- if (is.null(saving_plots_folder)) {
+      file.path(tempdir(), "drugsens_plots")
+    } else {
+      saving_plots_folder
+    }
+    dir.create(saving_plots_folder, showWarnings = FALSE, recursive = TRUE)
+  }
 
-  # if the user decides to isolate a specific sample only
-  if (!is.null(isolate_specific_patient)) .data <- .data[.data[[PID_column_name]] == isolate_specific_patient, ]
+  # Determine columns to plot
+  if (is.null(list_of_columns_to_plot)) {
+    list_of_columns_to_plot <- colnames(.data)[sapply(.data, is.numeric)]
+  }
 
+  # Process each patient
   for (pid in unique(.data[[PID_column_name]])) {
+    if (verbose) {
+      message("Processing patient: ", pid)
+    }
+
+    # Subset data for current patient
     subset_data <- .data[.data[[PID_column_name]] == pid, ]
 
-    for (i in list_of_columns_to_plot) {
-      if (!is.null(isolate_specific_drug)) subset_data <- subset_data[subset_data[[drug_column_name]] %in% isolate_specific_drug, ]
+    # Apply drug filter if specified
+    if (!is.null(isolate_specific_drug)) {
+      subset_data <- subset_data[subset_data[[drug_column_name]] %in% isolate_specific_drug, ]
+    }
 
-      if (nrow(subset_data) < 1) {
-        print(unique(subset_data[[PID_column_name]]))
-        print(unique(subset_data[[drug_column_name]]))
-        stop("ERROR: Your filtering query has returned no observations")
+    # Skip if no data after filtering
+    if (nrow(subset_data) < 1) {
+      if (verbose) {
+        message("No data found for PID: ", pid)
       }
+      next
+    }
 
-      # browser()
+    # Create patient directory if needed
+    if (save_plots && save_plots_in_patient_specific_subfolders) {
+      patient_dir <- file.path(saving_plots_folder, pid)
+      dir.create(patient_dir, showWarnings = FALSE, recursive = TRUE)
+    }
 
-      # Function to dynamically add layers to a ggplot object based on conditions
-      add_violin_layers <- function(p, fill_color_variable) {
-        if (!is.null(fill_color_variable)) {
-          p <- p + geom_violin(trim = FALSE, aes_string(fill = fill_color_variable), color = NA) +
-            geom_boxplot(width = 0.1, fill = "white")
+    # Process each metric
+    for (i in list_of_columns_to_plot) {
+      # Create plot
+      p <- create_qc_plot(subset_data, i, fill_color_variable,
+                          pid, isolate_specific_drug)
+
+      # Save plot if requested
+      if (save_plots) {
+        plot_file <- sprintf("%s_%s_%s_%s.pdf",
+                             format(Sys.Date(), "%Y%m%d"),
+                             pid,
+                             ifelse(is.null(isolate_specific_drug), "all", isolate_specific_drug),
+                             make.names(i))
+
+        # Determine save directory
+        save_dir <- if (save_plots_in_patient_specific_subfolders) {
+          file.path(saving_plots_folder, pid)
         } else {
-          p <- p + geom_violin(trim = FALSE, fill = "#A4A4A4", color = "darkred") +
-            geom_boxplot(width = 0.1, fill = "white")
+          saving_plots_folder
         }
-        return(p)
-      }
 
-      # Initialize ggplot
-      p <- ggplot(subset_data, aes(x = Name, y = log2(unlist(subset_data[[i]]))))
-
-      # Add violin and boxplot layers
-      p <- add_violin_layers(p, fill_color_variable)
-
-      # More layers on top
-      p <- p + facet_wrap(~Treatment) +
-        theme(axis.text.x = element_text(angle = 45, hjust = 1)) +
-        labs(
-          title = colnames(subset_data[i]),
-          x = "Cell Markers",
-          y = paste0("Intensity of ", colnames(subset_data[i]), " (log2)"),
-          subtitle = paste0(pid, ".", isolate_specific_drug)
-        ) +
-        geom_jitter(shape = 16, position = position_jitter(0.01)) +
-        stat_summary(geom = "crossbar", fun = mean, colour = "red", width = 0.21)
-
-      # Conditionally add to list of plots
-      if (save_list_of_plots) {
-        list_plottos[[paste0(isolate_specific_drug, ".", pid, ".", i)]] <- p
-      }
+        plot_path <- file.path(save_dir, plot_file)
 
+        ggplot2::ggsave(plot_path,
+                        plot = p,
+                        width = p_width,
+                        height = p_height,
+                        dpi = 600)
 
-      if (save_plots) {
-        if (save_plots_in_patient_specific_subfolders) {
-
-          if (!dir.exists(paste0(saving_plots_folder, "/", pid))) dir.create(paste0(saving_plots_folder, "/", pid), showWarnings = F, recursive = T)
-          ggsave(
-            plot = p,
-            filename = paste0(
-              paste0(saving_plots_folder, "/", pid),
-              "/",
-              Sys.Date(),
-              "_",
-              pid,
-              ".",
-              isolate_specific_drug,
-              ".",
-              colnames(.data[i]),
-              ".pdf"
-            ),
-            device = "pdf",
-            dpi = 600
-          )
-        } else {
-          # Saving plots in .pdf at 600 dpi
-          if (!dir.exists(saving_plots_folder)) dir.create(saving_plots_folder, showWarnings = F, recursive = T)
-          ggsave(
-            plot = p,
-            width = p_width,
-            height = p_height,
-            filename = paste0(
-              saving_plots_folder,
-              "/",
-              Sys.Date(),
-              "_",
-              pid,
-              ".",
-              isolate_specific_drug,
-              ".",
-              colnames(.data[i]),
-              ".pdf"
-            ),
-            device = "pdf",
-            dpi = 600,
-          )
+        if (verbose) {
+          message("Saved plot to: ", plot_path)
         }
+      }
 
-        message(paste0(
-          "plots for: ",
-          pid,
-          ".",
-          isolate_specific_drug,
-          ".",
-          colnames(.data[i]), " saved"
-        ))
+      # Store plot if requested
+      if (save_list_of_plots) {
+        plot_name <- paste(pid, i, sep = ".")
+        if (!is.null(isolate_specific_drug)) {
+          plot_name <- paste(isolate_specific_drug, plot_name, sep = ".")
+        }
+        list_plottos[[plot_name]] <- p
       }
     }
   }
+
+  # Return results
+  if (save_list_of_plots) {
+    return(list_plottos)
+  } else {
+    invisible(NULL)
+  }
 }

R/make_count_dataframe.R

@@ -8,12 +8,29 @@
 #' @param name_of_the_markers_column The name of the column of the .data where the marker names are expressed (ie E-Caderin, DAPI), "Defaults as Name"
 #' @export
 #' @examples
-#' bind_data <- data_binding(path_to_the_projects_folder = system.file("extdata/to_merge/", package = "drugsens"), files_extension_to_look_for = "csv")
+#' \donttest{
+#' # First load example data
+#' pkg_path <- system.file("extdata/to_merge/", package = "drugsens")
+#' bind_data <- data_binding(
+#'   path_to_the_projects_folder = pkg_path,
+#'   files_extension_to_look_for = "csv"
+#' )
+#'
+#' # Process the data
 #' counts_dataframe <- make_count_dataframe(bind_data)
+#'
+#' # Convert to plotting format
 #' plotting_ready_dataframe <- change_data_format_to_longer(counts_dataframe)
-#' @example
-#' \dontrun{make_count_dataframe(data, name_of_the_markers_column = "Name", unique_name_row_identifier = "filter_image")}
-#' @return text file
+#' }
+#'
+#' \donttest{
+#' # Example with custom parameters
+#' make_count_dataframe(
+#'   bind_data,
+#'   name_of_the_markers_column = "Name",
+#'   unique_name_row_identifier = "filter_image"
+#' )
+#' }
 
 # adding the image number so to identify the distribution
 make_count_dataframe <- function(.data, unique_name_row_identifier = "filter_image",

R/make_run_config.R

@@ -7,16 +7,20 @@
 #' @param forcePath String, Define a custom path for the config file
 #' @export
 #' @return A `dataframe`/`tibble`.
-#' @example
-#' \dontrun {make_run_config()}
+#' @examples
+#' \donttest{
+#' # Generate config in temporary directory
+#' make_run_config(forcePath = tempdir())
+#' }
 make_run_config <- function(overwrite_config = FALSE, forcePath = NULL) {
 
-  if (is.null(forcePath)) currentPath <- getwd() else currentPath <- forcePath
+  currentPath <- if (is.null(forcePath)) tempdir() else forcePath
+  config_file <- file.path(currentPath, "config_drugsens.txt")
 
-  if (file.exists("config_drugsens.txt")) {
+  if (file.exists(config_file)) {
     tryCatch(
       expr = {
-        source("config_drugsens.txt", local = FALSE)
+        source(config_file, local = FALSE)
       },
       error = function(error) {
         message("drugsens could not load the 'config.txt' file.
@@ -26,13 +30,9 @@ make_run_config <- function(overwrite_config = FALSE, forcePath = NULL) {
                 run_config to veryfy that the data was correctly read")
       }
     )
-  } else if (overwrite_config){
-    message("Overwriting config_drugsens.txt")
+  } else if (overwrite_config) {
     write(
-      x =
-        (
-        '
-        # List of markers to relabel
+      x = '# List of markers to relabel
         list_of_relabeling =
         list(
             "PathCellObject" = "onlyDAPIPositve",
@@ -40,17 +40,12 @@ make_run_config <- function(overwrite_config = FALSE, forcePath = NULL) {
             "E-Cadherin: cCASP3" = "E-Cadherin and cCASP3",
             "EpCAM_E-Cadherin" = "E-Cadherin",
             "EpCAM_E-Cadherin and cCASP3" = "E-Cadherin and cCASP3"
-          )'
-        ),
-      file = paste0(path.expand(currentPath), "/config_drugsens.txt")
+          )',
+      file = config_file
     )
-    message("config_drugsens.txt has been overwritten correctly.")
   } else {
     write(
-      x =
-        (
-          '
-        # List of markers to relabel
+      x = '# List of markers to relabel
         list_of_relabeling =
         list(
             "PathCellObject" = "onlyDAPIPositve",
@@ -58,9 +53,8 @@ make_run_config <- function(overwrite_config = FALSE, forcePath = NULL) {
             "E-Cadherin: cCASP3" = "E-Cadherin and cCASP3",
             "EpCAM_E-Cadherin" = "E-Cadherin",
             "EpCAM_E-Cadherin and cCASP3" = "E-Cadherin and cCASP3"
-          )'
-        ),
-      file = paste0(path.expand(currentPath), "/config_drugsens.txt")
+          )',
+      file = config_file
     )
   }
 }

R/parsers.R

-#' Main parsing function
+#' @title Parse image filenames to extract metadata
 #' @description
 #' This function will parse the data from the Image name and will return the metadata there contained
 #' The metadata will be then associated to the count file as well
@@ -8,11 +8,18 @@
 #' @importFrom stringr str_count
 #' @return A `dataframe`/`tibble`.
 #' @param .data dataframe with parsed metadata
+#' @export
 #' @examples
-#'  input_data <- data.frame(Image = "B516_Ascites_2023-11-25_DOC2020-12-14_dmso_rep_Ecad_cCasp3_(series 01).tif")
-#'  test <- drugsens:::string_parsing(input_data)
-#' @example
-#' \dontrun {data.parsed <- string_parsing(.data)}
+#' # Basic example with sample data
+#' input_data <- data.frame(
+#'   Image = "B516_Ascites_2023-11-25_DOC2020-12-14_dmso_rep_Ecad_cCasp3_(series 01).tif"
+#' )
+#' test <- drugsens::string_parsing(input_data)
+#'
+#' \donttest{
+#' # Example with actual data processing
+#' data.parsed <- string_parsing(input_data)
+#' }
 
 # Main function to bind data from multiple files
 string_parsing <- function(.data) {

R/zzz.R

+.onLoad <- function(libname, pkgname) {
+  utils::globalVariables(c(
+    "list_of_relabeling",
+    "marker_positivity_ratio",
+    "marker_positivity",
+    "x",
+    "y",
+    "Name"
+  ))
+}

README.md

@@ -208,7 +208,7 @@ In this code snippets we show an example of mock data `unique(bind_data$PID)` wi
 
 > ⚠️ **WARNING**: As long as you keep the formatting as the above examples. 
 The dates should also be in the format **yyy-mm-dd**. For the combinations of two drugs they should be written together with each of the different drug capilized (**C**arboplatin**P**aclitaxel) and the rest lowercased letters. 
-For example **CarboplatinPaclitaxel_100_uM_10_nM**. This indicates a drug combination of Carboplatin 100_uM and Paclitaxel 10_nM. Each drug amount and each unit should always be separated by `_`. The first 100_uM belongs to the Carboplatin and the 10_nM belongs to the Paclitaxel. Those constrains are due to the parsing of the strings into useful metadata. If some of the data is not present, you can use a `.` separated by `_`. If you need additional data parsing, please let us know by filing an issue on GitLab [GitLab Issue]("https://git.scicore.unibas.ch/ovca-research/drugsens/-/issues").
+For example **CarboplatinPaclitaxel_100_uM_10_nM**. This indicates a drug combination of Carboplatin 100_uM and Paclitaxel 10_nM. Each drug amount and each unit should always be separated by `_`. The first 100_uM belongs to the Carboplatin and the 10_nM belongs to the Paclitaxel. Those constrains are due to the parsing of the strings into useful metadata. If some of the data is not present, you can use a `.` separated by `_`. If you need additional data parsing, please let us know by filing an issue on GitLab https://git.scicore.unibas.ch/ovca-research/drugsens/-/issues.
 
 ### Counting the number of positiive cells for each marker in every image
 This function will take the previous step's generated dataframe and it will counts image by image (sum the markers of every stack) for every sample the number of marker occurrences. 
@@ -386,6 +386,6 @@ Renv will automatically activate and install the necessary packages as specified
 </details>
 
 ### Reporting Issues
-If you encounter any bugs or have suggestions for improvements, please file an issue using our [GitLab Issue]("https://git.scicore.unibas.ch/ovca-research/drugsens/-/issues"). Be sure to include as much information as possible to help us understand and address the issue.
-
+If you encounter any bugs or have suggestions for improvements, please file an issue using our **GitLab Issue:** https://git.scicore.unibas.ch/ovca-research/drugsens/-/issues. Be sure to include as much information as possible to help us understand and address the issue.
+**BugReports:** https://git.scicore.unibas.ch/ovca-research/drugsens/-/issues
 Please make sure to file the issue in the GitLab repo as this one in GitHub is a forward-only mirror repo.

man/change_data_format_to_longer.Rd

@@ -2,7 +2,7 @@
 % Please edit documentation in R/change_data_format_to_longer.R
 \name{change_data_format_to_longer}
 \alias{change_data_format_to_longer}
-\title{Reformat the counts data in longer format}
+\title{Data format changer}
 \usage{
 change_data_format_to_longer(
   .data,
@@ -26,14 +26,27 @@ A \code{dataframe}/\code{tibble}.
 \description{
 This function gets the count data data.frame, that has a wider format and it returns a longer-formatted data.frame
 }
+\details{
+Reformat the counts data in longer format
+}
 \examples{
-list_of_relabeling =list(  "PathCellObject" = "onlyDAPIPositve",
-"cCasp3" = "cCASP3",  "E-Cadherin: cCASP3" = "E-Cadherin and cCASP3",
-"EpCAM_E-Cadherin" = "E-Cadherin",
-"EpCAM_E-Cadherin and cCASP3" = "E-Cadherin and cCASP3")
-bind_data <- data_binding(path_to_the_projects_folder =
-system.file("extdata/to_merge/", package = "drugsens"))
+\donttest{
+# Set up relabeling list
+list_of_relabeling <- list(
+  "PathCellObject" = "onlyDAPIPositve",
+  "cCasp3" = "cCASP3",
+  "E-Cadherin: cCASP3" = "E-Cadherin and cCASP3",
+  "EpCAM_E-Cadherin" = "E-Cadherin",
+  "EpCAM_E-Cadherin and cCASP3" = "E-Cadherin and cCASP3"
+)
+
+# Load and process example data
+bind_data <- data_binding(
+  path_to_the_projects_folder = system.file("extdata/to_merge/", package = "drugsens")
+)
 counts_dataframe <- make_count_dataframe(bind_data)
-plotting_ready_dataframe <-
-change_data_format_to_longer(counts_dataframe)
+
+# Convert to long format
+plotting_ready_dataframe <- change_data_format_to_longer(counts_dataframe)
+}
 }

man/data_binding.Rd

@@ -7,7 +7,8 @@
 data_binding(
   path_to_the_projects_folder,
   files_extension_to_look_for = "csv",
-  recursive_search = FALSE
+  recursive_search = FALSE,
+  forcePath = NULL
 )
 }
 \arguments{
@@ -16,18 +17,19 @@ data_binding(
 \item{files_extension_to_look_for}{String The extension of the file outputted from QuPath, (default is "csv")}
 
 \item{recursive_search}{Boolean, it defined the behavior of the file search, if recursive or not, (default is FALSE)}
+
+\item{forcePath}{String defining an alternative path to the confic file}
 }
 \value{
-A \code{dataframe}/\code{tibble}.
-
-Returns a concatenated dataframe from all the files within the indicated one
+A concatenated dataframe from all the files within the indicated path
 }
 \description{
-This function try to guess the string patterns that are in the dataset and then fill the dataframe
-with that information. Finally the data is combined and combined them into one file
+This function identifies string patterns in the dataset, fills the dataframe
+with that information, and combines all data into a single file
 }
 \examples{
+\dontrun{
 bind_data <- data_binding(path_to_the_projects_folder = system.file("extdata/to_merge/",
-package = "drugsens"))
-#This will return the dataframe of all the data in the folder
+                         package = "drugsens"))
+}
 }

man/generate_qupath_script.Rd

 % Generated by roxygen2: do not edit by hand
-% Please edit documentation in R/generate_qu_path_script.R
+% Please edit documentation in R/generate_qupath_script.R
 \name{generate_qupath_script}
 \alias{generate_qupath_script}
 \title{Generate the groovy script used for the analysis}
 \usage{
-generate_qupath_script()
+generate_qupath_script(output_dir = NULL)
+}
+\arguments{
+\item{output_dir}{Directory where the script should be saved. If NULL, uses tempdir()}
 }
 \value{
-\code{script_for_qupath.txt} in local working directory.
+Invisibly returns the path to the generated script file.
 }
 \description{
 Generate a useful script to consistently save the output data from QuPath in .csv format following the naming conventions
 followed during the package development.
 }
 \examples{
-generate_qupath_script()
+\dontrun{
+  # Generate script in a temporary directory
+  generate_qupath_script()
+
+  # Generate script in a specific directory
+  output_dir <- tempdir()
+  generate_qupath_script(output_dir = output_dir)
+}
 }

man/get_QC_plots.Rd

@@ -9,29 +9,57 @@ get_QC_plots(
   patient_column_name = "PID",
   colors = c("darkgreen", "red", "orange", "pink"),
   save_plots = FALSE,
-  folder_name = "figures",
+  folder_name = NULL,
   x_plot_var = "Treatment_complete",
   isolate_a_specific_patient = NULL
 )
 }
 \arguments{
-\item{.data}{The preprocessed data (after running make_count_dataframe() and change_data_format_to_longer()) merged data.frame that should be visualized}
+\item{.data}{The preprocessed data (after running make_count_dataframe() and change_data_format_to_longer())
+merged data.frame that should be visualized}
 
 \item{patient_column_name}{The PID's column name in the merged data.frame (defaults to "PID")}
 
-\item{colors}{A list of colors to supply to personalize the plot, as default 4 colors c("dark green", "red", "orange", "pink")}
+\item{colors}{A list of colors to supply to personalize the plot, defaults to c("darkgreen", "red", "orange", "pink")}
 
-\item{save_plots}{A Boolean value indicating if the plots should be saved or not, TRUE for saving in the current working directory, FALSE to not. Default is FALSE}
+\item{save_plots}{A Boolean value indicating if the plots should be saved or not (default is FALSE)}
 
-\item{folder_name}{A string indicating the name of the folder where to save the plots in case that save_plots = TRUE}
+\item{folder_name}{A string indicating the name of the folder where to save the plots if save_plots is TRUE}
 
 \item{x_plot_var}{A string indicating the treatment's full name for the QC plots (default is "Treatment_complete")}
 
 \item{isolate_a_specific_patient}{A string indicating the patient name to isolate for single plot case (default is NULL)}
 }
 \value{
-A \code{dataframe}/\code{tibble}.
+Invisibly returns NULL, but saves plots to disk if save_plots is TRUE
 }
 \description{
-Plot data to visualize immediate trends
+Plot data to visualize immediate trends. This function expects data that has been processed
+through make_count_dataframe() and change_data_format_to_longer() to ensure the correct
+data structure for plotting.
+}
+\examples{
+\donttest{
+# First process example data
+example_path <- system.file("extdata/to_merge/", package = "drugsens")
+raw_data <- data_binding(path_to_the_projects_folder = example_path)
+count_data <- make_count_dataframe(raw_data)
+processed_data <- change_data_format_to_longer(count_data)
+
+# Create and save plots to temporary directory
+temp_dir <- file.path(tempdir(), "qc_plots")
+get_QC_plots(
+  processed_data,
+  save_plots = TRUE,
+  folder_name = temp_dir
+)
+
+# Create plots for a specific patient
+get_QC_plots(
+  processed_data,
+  isolate_a_specific_patient = "B39",
+  save_plots = TRUE,
+  folder_name = temp_dir
+)
+}
 }

man/get_QC_plots_parsed_merged_data.Rd

@@ -2,13 +2,13 @@
 % Please edit documentation in R/get_QC_plots_and_stats.R
 \name{get_QC_plots_parsed_merged_data}
 \alias{get_QC_plots_parsed_merged_data}
-\title{Plot some QC plots for the bound data}
+\title{Plot QC plots and calculate statistics for bound data}
 \usage{
 get_QC_plots_parsed_merged_data(
   .data,
   list_of_columns_to_plot = NULL,
   save_plots = FALSE,
-  saving_plots_folder = "figures",
+  saving_plots_folder = NULL,
   save_plots_in_patient_specific_subfolders = TRUE,
   fill_color_variable = NULL,
   PID_column_name = "PID",
@@ -17,39 +17,75 @@ get_QC_plots_parsed_merged_data(
   drug_column_name = "Treatment",
   save_list_of_plots = TRUE,
   p_height = 10,
-  p_width = 10
+  p_width = 10,
+  verbose = TRUE
 )
 }
 \arguments{
-\item{.data}{The preprocessed data (after running make_count_dataframe() and change_data_format_to_longer()) merged data.frame that should be visualized}
+\item{.data}{The preprocessed data frame to analyze}
 
-\item{list_of_columns_to_plot}{The preprocessed data (after running make_count_dataframe() and change_data_format_to_longer()) merged data.frame that should be visualized}
+\item{list_of_columns_to_plot}{Columns to include in plots. If NULL, all numeric columns are used.}
 
-\item{save_plots}{Boolean, TRUE if plots should be saved (default is FALSE)}
+\item{save_plots}{Logical, whether to save plots to files. Defaults to FALSE.}
 
-\item{saving_plots_folder}{String indicating the folder where the plots should be stored (default is "figures")}
+\item{saving_plots_folder}{Directory for saving plots. If NULL and save_plots=TRUE, uses a subdirectory of tempdir().}
 
-\item{save_plots_in_patient_specific_subfolders}{Boolean, if TRUE the plots will be saved (if \code{save_plots} TRUE) in sample specific folders (default is TRUE)}
+\item{save_plots_in_patient_specific_subfolders}{Logical, whether to create patient subdirectories. Defaults to TRUE.}
 
-\item{fill_color_variable}{Boolean, String, indicating the name of the variable (discrete) to use for the plot's filling}
+\item{fill_color_variable}{Variable name for plot color filling}
 
-\item{PID_column_name}{String, indicating the name of the sample to subset (default is "Treatment")}
+\item{PID_column_name}{Column name for patient IDs. Defaults to "PID".}
 
-\item{isolate_specific_drug}{String, indicating if there should be a Treatment specific data subset (default is NULL)}
+\item{isolate_specific_drug}{Drug name to subset data}
 
-\item{isolate_specific_patient}{String, indicating a spacific sample to plot only (default is NULL)}
+\item{isolate_specific_patient}{Patient ID to subset data}
 
-\item{drug_column_name}{String, indicate the column indicating the Drug/Treament (default is "Treatment")}
+\item{drug_column_name}{Column name for drug information. Defaults to "Treatment".}
 
-\item{save_list_of_plots}{Boolean, if TRUE returns a named list of all the plots ran (default is TRUE), this can be usefult to isolate specific plots}
+\item{save_list_of_plots}{Logical, whether to return list of plot objects. Defaults to TRUE.}
 
-\item{p_height}{Integer, indicate the plot's height (default is 10 inches)}
+\item{p_height}{Plot height in inches. Defaults to 10.}
 
-\item{p_width}{Integer, indicate the plot's width (default is 10 inches)}
+\item{p_width}{Plot width in inches. Defaults to 10.}
+
+\item{verbose}{Logical, whether to show progress messages. Defaults to TRUE.}
 }
 \value{
-A \code{list}/\code{NULL}.
+If save_list_of_plots=TRUE, returns a named list of ggplot objects. Otherwise returns invisible(NULL).
 }
 \description{
-This plot can show trends within the dataset and run some basic statistics.
+This function creates quality control plots and calculates basic statistics for microscopy data.
+The plots provide visual insights into marker expression patterns and data quality.
+}
+\examples{
+\donttest{
+# First load and process example data
+example_path <- system.file("extdata/to_merge/", package = "drugsens")
+raw_data <- data_binding(path_to_the_projects_folder = example_path)
+count_data <- make_count_dataframe(raw_data)
+processed_data <- change_data_format_to_longer(count_data)
+
+# Basic usage - create plots for all patients
+plots <- get_QC_plots_parsed_merged_data(processed_data)
+
+# Save plots to a temporary directory
+temp_dir <- file.path(tempdir(), "qc_plots")
+plots <- get_QC_plots_parsed_merged_data(
+  processed_data,
+  save_plots = TRUE,
+  saving_plots_folder = temp_dir
+)
+
+# Focus on a specific patient
+plots <- get_QC_plots_parsed_merged_data(
+  processed_data,
+  isolate_specific_patient = "B39"
+)
+
+# Color plots by tissue type
+plots <- get_QC_plots_parsed_merged_data(
+  processed_data,
+  fill_color_variable = "Tissue"
+)
+}
 }

man/make_count_dataframe.Rd

@@ -19,14 +19,32 @@ make_count_dataframe(
 }
 \value{
 A \code{dataframe}/\code{tibble}.
-
-text file
 }
 \description{
 This function counts every single marker present in the "Name" column of the data.frame and return a dataframe of the counts per marker
 }
 \examples{
-bind_data <- data_binding(path_to_the_projects_folder = system.file("extdata/to_merge/", package = "drugsens"), files_extension_to_look_for = "csv")
+\donttest{
+# First load example data
+pkg_path <- system.file("extdata/to_merge/", package = "drugsens")
+bind_data <- data_binding(
+  path_to_the_projects_folder = pkg_path,
+  files_extension_to_look_for = "csv"
+)
+
+# Process the data
 counts_dataframe <- make_count_dataframe(bind_data)
+
+# Convert to plotting format
 plotting_ready_dataframe <- change_data_format_to_longer(counts_dataframe)
 }
+
+\donttest{
+# Example with custom parameters
+make_count_dataframe(
+  bind_data,
+  name_of_the_markers_column = "Name",
+  unique_name_row_identifier = "filter_image"
+)
+}
+}