documentation updated

DESCRIPTION

@@ -45,7 +45,8 @@ Imports:
     glue,
     matrixStats,
     magrittr,
-    haven
+    haven,
+    reprtree
 Suggests: 
     knitr,
     rmarkdown,

R/get_auc_curve_with_rf_model.R

@@ -39,14 +39,17 @@
 #' predictions are made, and the AUC is calculated and visualized with a ROC curve plot.
 #'
 #' @examples
+#' \dontrun{
 #' # Example 1: Using real data from the database
-#' get_auc_curve_with_rf_model(Data = NULL, path_db = "path/to/database.db", rat_studies = TRUE, reps = 10,
-#'                             holdback = 0.75, error_correction_method = "Prune")
-#'
-#' # Example 2: Using synthetic data with fake study IDs
-#' get_auc_curve_with_rf_model(Data = NULL, fake_study = TRUE, reps = 5, holdback = 0.8,
-#'                             error_correction_method = "Flip")
+#' #This is a placeholder example. Replace the path with a valid database.
+#'  get_auc_curve_with_rf_model(Data = NULL, path_db = "path/to/database.db", rat_studies = TRUE, reps = 10,
+#'                              holdback = 0.75, error_correction_method = "Prune")
 #'
+#' # Example 2: Using sample data (if applicable)
+#'  get_auc_curve_with_rf_model(Data = sample_data, path_db = NULL, rat_studies = FALSE, reps = 5,
+#'                              holdback = 0.5, error_correction_method = "CorrectMethod")
+#' }
+
 #' @seealso
 #' `randomForest`, `ROCR`
 #'

R/get_bw_score.R

@@ -1,29 +1,25 @@
-#' @title Calculate Body Weight Z-score for a Given STUDYID
+#' @title Calculate Body Weight Z-score for a given STUDYID from SQLite Database or `.xpt` Files
 #'
 #' @description
-#' The `get_bw_score` function calculates the Body Weight (BW) Z-score for a specified studyid using data from a provided database or .xpt file.
-#' It supports optional parameters for customize the analysis and offers the flexibility to return individual Z-score by `USUBJID` (unique subject identifier).
+#' The `get_bw_score` function calculates the Body Weight (BW) Z-score for a specified STUDYID using data from a provided database or .xpt files.
+#' It supports optional parameters to customize the analysis and offers the flexibility to return individual Z-score by `USUBJID` (unique subject identifier).
 #'
-#' @param studyid Mandatory, character \cr
-#'   The studyid for which the BW Z-score is to be calculated. Required when `use_xpt_file` = `FALSE`.
-#'   If `use_xpt_file` = `TRUE`, `studyid` is ignored, and all `.xpt` files in the specified folder (`path_db`) are analyzed.
-#' @param path_db Mandatory, character \cr
-#'   The path to the `SQLite` database file or folder containing the `.xpt` files (if `use_xpt_file = TRUE`).
-#' @param fake_study Optional, Boolean \cr
-#'   Indicates whether the study was generated by the `SENDsanitizer` package. Default is `FALSE`.
-#' @param use_xpt_file Mandatory, Boolean \cr
-#'   If `TRUE`, the function processes `.xpt` files from the folder specified in `path_db`.
-#'   If `FALSE`, it uses the `SQLite` database file at `path_db` and requires a valid `studyid`. Default is `FALSE`.
+#' @param studyid Character. STUDYID number. Defaults to `NULL`.
+#'    Required for SQLite databases (`use_xpt_file = FALSE`).
+#'    Must be `NULL` for `.xpt` files (`use_xpt_file = TRUE`).
+#' @param path_db Character. Path to the SQLite database file or a folder containing `.xpt` files. Mandatory.
+#' @param fake_study Logical. Whether the study data is generated by the `SENDsanitizer` package. Defaults to `FALSE`.
+#' @param use_xpt_file Logical. Whether to retrieve study data from `.xpt` files instead of the SQLite database. Defaults to `FALSE`.
 #' @param master_compiledata Optional, character \cr
-#'   If `master_compiledata` is not provided (i.e., `NULL`), the function will automatically call the `get_compile_data` function to calculate it.
-#' @param return_individual_scores Optional, Boolean \cr
+#'   If `master_compiledata` is not supplied (i.e., `NULL`), the function will automatically call the `get_compile_data` function to calculate it.
+#' @param return_individual_scores Optional, logical \cr
 #'   If TRUE, the function returns individual scores for each domain by averaging the scores of all subjects/animals (`USUBJID`) in the study. Default is `FALSE`.
-#' @param return_zscore_by_USUBJID Optional, Boolean \cr
+#' @param return_zscore_by_USUBJID Optional, logical \cr
 #'    If `TRUE`, the function returns Z-scores for each animal/subject by `USUBJID`. Default is `FALSE`.
 #'
 #' @return
 #' A `data.frame` containing the calculated BW Z-scores. The structure of the output depends on the provided parameters:
-#' - If `return_individual_scores = TRUE`: Returns averaged Z-scores for each of the domain per `studyid`.
+#' - If `return_individual_scores = TRUE`: Returns averaged Z-scores for each  domain per `studyid`.
 #' - If `return_zscore_by_USUBJID = TRUE`: Returns Z-score for each animal/subject by `USUBJID` for each domain per `studyid`.
 #' - Otherwise, a summarized BW score for the specified `studyid`.
 #'
@@ -44,8 +40,6 @@
 #' @importFrom RSQLite SQLite
 
 
-
-
 get_bw_score <- function(studyid = NULL,
                          path_db,
                          fake_study = FALSE,

R/get_compile_data.R

@@ -1,20 +1,35 @@
-#' @title Retrieve Compiled Data from SQLite Database or XPT File
-#' @description This function retrieves and compiles data for a given study ID
-#'   from either a SQLite database or XPT file.
-#' @param studyid Character. Study ID number. Defaults to `NULL`.
-#'   If `NULL`, all available studies may be retrieved (behavior depends on the database structure).
-#' @param path_db Character. Path to the SQLite database file. Mandatory.
+#' @title Retrieve and Compile Study Data from SQLite Database or `.xpt` Files
+#' @description Retrieves, cleans, and compiles data for a specified STUDYID
+#'   from either a SQLite database or `.xpt` files in a given folder.
+#' @param studyid Character. STUDYID number. Defaults to `NULL`.
+#'    Required for SQLite databases (`use_xpt_file = FALSE`).
+#'    Must be `NULL` for `.xpt` files (`use_xpt_file = TRUE`).
+#' @param path_db Character. Path to the SQLite database file or a folder containing `.xpt` files. Mandatory.
 #' @param fake_study Logical. Whether the study data is generated by the `SENDsanitizer` package. Defaults to `FALSE`.
-#' @param use_xpt_file Logical. Whether to retrieve study data from an XPT file format instead of the database. Defaults to `FALSE`.
-#' @return A data frame containing the compiled study data. The structure of the returned data frame depends on the database or XPT file contents.
+#' @param use_xpt_file Logical. Whether to retrieve study data from `.xpt` files instead of the SQLite database. Defaults to `FALSE`.
+##' @return A data frame containing the following columns:
+#' \itemize{
+#'   \item \code{STUDYID} - Study identifier.
+#'   \item \code{USUBJID} - Unique subject identifier.
+#'   \item \code{Species} - Species of the test subject.
+#'   \item \code{SEX} - Sex of the test subject.
+#'   \item \code{ARMCD} - Code representing specific Trial Arm (e.g., Low Dose, Mid Dose).
+#'   \item \code{SETCD} - Code representing distinct "groups" or "trial sets".
+#' }
 #'
 #' @examples
 #' \dontrun{
 #' # Retrieve data for a specific study ID from the database
-#' get_compile_data(studyid = '1234123', path_db = 'path/to/database.db')
+#' get_compile_data(studyid = '1234123',
+#'                  path_db = 'path/to/database.db',
+#'                  fake_study = FALSE,
+#'                  use_xpt_file = FALSE)
 #'
-#' # Retrieve data from an XPT file
-#' get_compile_data(path_db = 'path/to/file.xpt', use_xpt_file = TRUE)
+#' # Retrieve data from all XPT files in a folder
+#' get_compile_data(studyid = NULL,
+#'                  path_db = 'path/to/folder',
+#'                  fake_study = FALSE,
+#'                  use_xpt_file = TRUE)
 #' }
 #' @export
 #'

R/get_histogram_barplot.R

@@ -38,11 +38,13 @@
 #' displaying the average scores for each finding in a bar plot.
 #'
 #' @examples
+#' \dontrun{
 #' # Example 1: Generate a bar plot with fake study data
-#' get_histogram_barplot(generateBarPlot = TRUE, fake_study = TRUE)
+#' #get_histogram_barplot(generateBarPlot = TRUE, fake_study = TRUE)
 #'
 #' # Example 2: Get processed data without generating a plot
-#' data <- get_histogram_barplot(generateBarPlot = FALSE, fake_study = FALSE, path_db = "path/to/db")
+#' #data <- get_histogram_barplot(generateBarPlot = FALSE, fake_study = FALSE, path_db = "path/to/db")
+#' }
 #'
 #' @import ggplot2
 #' @import DBI

R/get_imp_features_from_rf_model_with_cv.R

@@ -30,6 +30,7 @@
 #' }
 #'
 #' @examples
+#' \dontrun{
 #' # Example of calling the function
 #' result <- get_imp_features_from_rf_model_with_cv(
 #'   Data = scores_df,
@@ -39,6 +40,7 @@
 #'   Type = 2,
 #'   nTopImportance = 10
 #' )
+#' }
 #'
 #' @export
 

R/get_livertobw_score.R

@@ -1,31 +1,29 @@
-#' @title Calculate Liver-to-Body-Weight Scores and Z-Scores
+#' @title Calculate Liver-to-Body-Weight ratio Z-Scores for each animal in a given STUDYID from SQLite Database or `.xpt` Files
 #'
 #' @description
-#' This function computes liver-to-body-weight (Liver:BW) ratios and their corresponding z-scores from study data.
+#' This function computes liver-to-body-weight ratio  (livertoBW) of each animal and their corresponding z-scores from study data.
 #' It supports retrieving data from SQLite databases or `.xpt` files and provides flexible options for output formats.
 #'
-#' @param studyid Optional, character. \cr
-#'   Study ID for which the calculations are performed. If `NULL`, data for all studies in the database is used.
-#' @param path_db Mandatory, character. \cr
-#'   Path to the SQLite database or directory containing `.xpt` files.
-#' @param fake_study Optional, logical. \cr
-#'   Indicates whether the study is a fake/test study generated by the `SENDsanitizer` package. Default is `FALSE`.
-#' @param use_xpt_file Optional, logical. \cr
-#'   Specifies whether to use `.xpt` files instead of a SQLite database. Default is `FALSE`.
-#' @param master_compiledata Optional, data.frame. \cr
-#'   Precompiled dataset of study information. If `NULL`, the function fetches the data using `get_compile_data`.
+#' #' @param studyid Character. STUDYID number. Defaults to `NULL`.
+#'    Required for SQLite databases (`use_xpt_file = FALSE`).
+#'    Must be `NULL` for `.xpt` files (`use_xpt_file = TRUE`).
+#' @param path_db Character. Path to the SQLite database file or a folder containing `.xpt` files. Mandatory.
+#' @param fake_study Logical. Whether the study data is generated by the `SENDsanitizer` package. Defaults to `FALSE`.
+#' @param use_xpt_file Logical. Whether to retrieve study data from `.xpt` files instead of the SQLite database. Defaults to `FALSE`.
+#' @param master_compiledata Optional, character \cr
+#'   If `master_compiledata` is not supplied (i.e., `NULL`), the function will automatically call the `get_compile_data` function to calculate it.
 #' @param bwzscore_BW Optional, data.frame. \cr
-#'   Precomputed body weight z-scores. If `NULL`, they are calculated using `get_bw_score`.
-#' @param return_individual_scores Optional, logical. \cr
-#'   If `TRUE`, returns individual z-scores averaged by study. Default is `FALSE`.
-#' @param return_zscore_by_USUBJID Optional, logical. \cr
-#'   If `TRUE`, returns z-scores grouped by `USUBJID`. Default is `FALSE`.
+#'   if `bwzscore_BW` is not supplied (i.e., `NULL`), the function will automatically call the `get_bw_score` function to calculate it.
+#' @param return_individual_scores Optional, logical \cr
+#'   If TRUE, the function returns individual scores for each domain by averaging the scores of all subjects/animals (`USUBJID`) in the study. Default is `FALSE`.
+#' @param return_zscore_by_USUBJID Optional, logical \cr
+#'    If `TRUE`, the function returns Z-scores for each animal/subject by `USUBJID`. Default is `FALSE`.
 #'
 #' @return
-#' A data frame containing liver-to-body-weight z-scores:
-#' - Averaged by study (default).
-#' - Individual scores averaged by study (`return_individual_scores = TRUE`).
-#' - Z-scores grouped by `USUBJID` (`return_zscore_by_USUBJID = TRUE`).
+#' A data frame containing liver-to-body-weight ratio z-scores:
+#' - If `return_individual_scores = TRUE`: Returns averaged Z-scores for each  domain per `studyid`.
+#' - If `return_zscore_by_USUBJID = TRUE`: Returns Z-score for each animal/subject by `USUBJID` for each domain per `studyid`.
+#' - Otherwise, a summarized BW score for the specified `studyid`.
 #'
 #' @examples
 #' \dontrun{

R/get_ml_data_and_tuned_hyperparameters.R

@@ -25,6 +25,7 @@
 #' @export
 #'
 #' @examples
+#' \dontrun{
 #' # Example usage:
 #' Data <- scores_df
 #' studyid_metadata <- read.csv("path/to/study_metadata.csv")
@@ -41,6 +42,7 @@
 #' )
 #' rfData <- result$rfData
 #' best_mtry <- result$best.m
+#' }
 
 
 get_ml_data_and_tuned_hyperparameters <- function(Data, # Data == "scores_df"

R/get_prediction_plot.R

@@ -29,6 +29,7 @@
 #' - The predictions are averaged over the test repetitions and a histogram is plotted to visualize the distribution of predicted probabilities for `LIVER`.
 #'
 #' @examples
+#' \dontrun{
 #' # Example function call
 #' get_prediction_plot(
 #'   path_db = "path_to_db",
@@ -40,6 +41,7 @@
 #'   error_correction_method = "Flip",
 #'   testReps = 5
 #' )
+#' }
 #'
 #' @export
 

R/get_reprtree_from_rf_model.R

@@ -27,7 +27,8 @@
 #' 4. **Visualization**: The first tree from the Random Forest model is plotted using the `reprtree::plot.getTree` function.
 #'
 #' @examples
-#' get_reprtree_from_rf_model(
+#' \dontrun{
+#' #get_reprtree_from_rf_model(
 #'   Data = my_data,
 #'   path_db = "path/to/database",
 #'   rat_studies = TRUE,
@@ -42,7 +43,7 @@
 #'   hyperparameter_tuning = FALSE,
 #'   error_correction_method = "Flip"
 #' )
-#'
+#' }
 #' @import randomForest
 #' @import reprtree
 #' @export

R/get_rf_input_param_list_output_cv_imp.R

@@ -36,6 +36,7 @@
 #' }
 #'
 #' @examples
+#' \dontrun{
 #' # Example usage of the function
 #' result <- get_rf_input_param_list_output_cv_imp(
 #'   path_db = "path/to/database",
@@ -57,7 +58,7 @@
 #'   Type = "classification",
 #'   nTopImportance = 10
 #' )
-#'
+#' }
 #' @import DBI
 #' @import RSQLite
 #' @importFrom stats lm

R/get_rf_model_with_cv.R

@@ -29,24 +29,26 @@
 #' A random forest model is trained on the training set, and predictions are evaluated on the test set. The results are aggregated to provide summary performance metrics.
 #'
 #' @examples
+#' \dontrun{
 #' # Load necessary libraries
 #' library(randomForest)
 #' library(caret)
 #'
 #' # Example dataset
-#' data(iris)
-#' iris$Target_Organ <- ifelse(iris$Species == "setosa", 1, 0)
-#' iris <- iris[, -5]  # Remove Species column
+#'
+#' Data$Target_Organ <- ifelse(iris$Species == "setosa", 1, 0)
+#' Data <- Data[, -5]  # Remove Species column
 #'
 #' # Run the function
 #' results <- get_rf_model_with_cv(Data = iris,
-#'                                 Undersample = TRUE,
+#'                                Undersample = TRUE,
 #'                                 best.m = 2,
 #'                                 testReps = 5,
 #'                                 Type = 2)
 #'
 #' # Print results
 #' print(results$performance_metrics)
+#' }
 #'
 #' @export
 

R/get_zone_exclusioned_rf_model_cv_imp.R

@@ -30,7 +30,8 @@
 #' top `nTopImportance` features based on either Mean Decrease Accuracy or Mean Decrease Gini.
 #'
 #' @examples
-#' # Example usage of the function
+#' \dontrun{
+#' #Example usage of the function
 #' result <- get_rf_model_output_cv_imp(
 #'   scores_df = your_data,
 #'   Undersample = FALSE,
@@ -42,11 +43,12 @@
 #'   nTopImportance = 10
 #' )
 #'
-#' # View performance metrics
+#' #View performance metrics
 #' print(result$performance_metrics)
 #'
-#' # View top features by importance
+#' #View top features by importance
 #' print(result$feature_importance)
+#' }
 #'
 #' @import randomForest
 #' @import caret

R/get_zone_exclusioned_rf_model_with_cv.R

@@ -43,17 +43,17 @@
 #' # Example usage
 #' Data <- your_data_frame  # Replace with actual dataset
 #' results <- get_zone_exclusioned_rf_model_with_cv(Data = Data,
-#'                                                 Undersample = TRUE,
-#'                                                 best.m = 5,
+#'                                                  Undersample = TRUE,
+#'                                                best.m = 5,
 #'                                                 testReps = 10,
 #'                                                 indeterminateUpper = 0.8,
 #'                                                 indeterminateLower = 0.2,
-#'                                                 Type = 1)
+#'                                                  Type = 1)
 #'
-#' # View the aggregated performance metrics
+#'  View the aggregated performance metrics
 #' print(results$performance_metrics)
 #'
-#' # Access raw results for further analysis
+#'  Access raw results for further analysis
 #' print(results$raw_results)
 #' }
 #'