updated

R/get_2bw_score.R → R/get_bw_score.R

@@ -1,33 +1,49 @@
-
-#' @title get BW score for a given studyid
+#' @title Calculate BW Score for a Given Study ID
+#'
+#' @description
+#' The `get_bw_score` function calculates the Bayesian Weighted (BW) score for a specified study ID using data from a provided database.
+#' It supports optional parameters for fine-tuning the analysis and offers the flexibility to return individual scores or z-scores by `USUBJID`.
+#'
 #' @param studyid Mandatory, character \cr
-#'   Studyid number
+#'   The study ID for which the BW score is to be calculated. If `NULL`, all studies in the database are analyzed.
 #' @param path_db Mandatory, character \cr
-#'   path of database
-#' @param fake_study optional, Boolean \cr
-#' whether study generated by SENDsanitizer package
-#' @param use_xpt_file  Mandatory, character \cr
-#'   Studyid number
-#' @param master_compiledata Mandatory, character \cr
-#'   path of database
-#' @param return_individual_scores optional, Boolean \cr
-#' whether study generated by SENDsanitizer package
-#' @param return_zscore_by_USUBJID optional, Boolean \cr
-#' whether study generated by SENDsanitizer package
-#' @return dataframe
+#'   The path to the database file containing the study data.
+#' @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 uses `.xpt` files for processing the study data. Default is `FALSE`.
+#' @param master_compiledata Optional, character \cr
+#'   The path to an additional database or compiled data file for analysis. If `NULL`, only the primary database is used.
+#' @param return_individual_scores Optional, Boolean \cr
+#'   If `TRUE`, the function returns individual scores for each record in the study. Default is `FALSE`.
+#' @param return_zscore_by_USUBJID Optional, Boolean \cr
+#'   If `TRUE`, the function returns z-scores calculated by `USUBJID` (unique subject identifiers). Default is `FALSE`.
+#'
+#' @return
+#' A `data.frame` containing the calculated BW scores. The structure of the output depends on the provided parameters:
+#' - If `return_individual_scores = TRUE`: Returns individual scores for each record.
+#' - If `return_zscore_by_USUBJID = TRUE`: Returns z-scores by `USUBJID`.
+#' - Otherwise, a summarized BW score for the specified `studyid`.
 #'
 #' @examples
 #' \dontrun{
-#' get_bw_score(studyid='1234123', path_db='path/to/database.db')
+#' # Example 1: Basic usage
+#' get_bw_score(studyid = '1234123', path_db = 'path/to/database.db')
+#'
+#' # Example 2: Include individual scores
+#' get_bw_score(studyid = '1234123', path_db = 'path/to/database.db', return_individual_scores = TRUE)
+#'
+#' # Example 3: Include z-scores by USUBJID
+#' get_bw_score(studyid = '1234123', path_db = 'path/to/database.db', return_zscore_by_USUBJID = TRUE)
 #' }
+#'
 #' @export
-
-
 #' @importFrom RSQLite dbConnect
 #' @importFrom RSQLite SQLite
 
 
 
+
 get_bw_score <- function(studyid = NULL,
                          path_db,
                          fake_study = FALSE,

R/get_1compile_data.R → R/get_compile_data.R

@@ -1,22 +1,24 @@
-#' @title filter out tk and recovery animal
-#' @param studyid Mandatory, character \cr
-#'   Studyid number
-#' @param path_db Mandatory, character \cr
-#'   path of database
-#' @param fake_study optional, Boolean \cr
-#' whether study generated by SENDsanitizer package
-##' @param use_xpt_file optional, Boolean \cr
-#' whether study generated by SENDsanitizer package
-#' @return dataframe
+#' @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.
+#' @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.
 #'
 #' @examples
 #' \dontrun{
-#' get_compile_data(studyid='1234123', path_db='path/to/database.db')
+#' # Retrieve data for a specific study ID from the database
+#' get_compile_data(studyid = '1234123', path_db = 'path/to/database.db')
+#'
+#' # Retrieve data from an XPT file
+#' get_compile_data(path_db = 'path/to/file.xpt', use_xpt_file = TRUE)
 #' }
 #' @export
-
-
-#' @importFrom magrittr %>%
+#'
+#' @importFrom magrittr %>
 
 get_compile_data <- function(studyid = NULL,
                              path_db,

R/get_4lb_score.R → R/get_lb_score.R

@@ -1,25 +1,39 @@
-
-#' @title get LB score for a given studyid
-#' @param studyid Mandatory, character \cr
-#'   Studyid number
-#' @param path_db Mandatory, character \cr
-#'   path of database
-#' @param fake_study optional, Boolean \cr
-#' whether study generated by SENDsanitizer package
-#' @param use_xpt_file Mandatory, character \cr
-#'   Studyid number
-#' @param master_compiledata Mandatory, character \cr
-#'   path of database
-#' @param return_individual_scores optional, Boolean \cr
-#' whether study generated by SENDsanitizer package
-#' @param return_zscore_by_USUBJID optional, Boolean \cr
-#' whether study generated by SENDsanitizer package
-#' @return score
+#' @title Get LB Score for a Given Study ID
+#'
+#' @description
+#' This function computes the LB score for a given study ID using data stored in a specified database.
+#' It offers various optional parameters to customize the output, such as whether to return individual scores or Z-scores by `USUBJID`.
+#'
+#' @param studyid Mandatory, character
+#'   The study ID number for which the LB score is calculated.
+#'
+#' @param path_db Mandatory, character
+#'   The path to the database containing the necessary data for the calculation.
+#'
+#' @param fake_study Optional, boolean
+#'   Indicates whether the study is generated by the SENDsanitizer package. Defaults to `FALSE`.
+#'
+#' @param use_xpt_file Mandatory, character
+#'   Specifies the path to the XPT (SAS transport) file if it is being used for the study.
+#'
+#' @param master_compiledata Mandatory, character
+#'   The path to the compiled master dataset that will be used to calculate the LB score.
+#'
+#' @param return_individual_scores Optional, boolean
+#'   If `TRUE`, the function will return individual scores for each subject. Defaults to `FALSE`.
+#'
+#' @param return_zscore_by_USUBJID Optional, boolean
+#'   If `TRUE`, the function will return Z-scores by `USUBJID`. Defaults to `FALSE`.
+#'
+#' @return numeric
+#'   The calculated LB score based on the provided data and parameters.
 #'
 #' @examples
 #' \dontrun{
+#' # Example usage of the function
 #' get_lb_score(studyid='1234123', path_db='path/to/database.db')
 #' }
+#'
 #' @export
 
 get_lb_score <- function(studyid = NULL,

R/get_6liver_om_lb_mi_tox_score_list.R → R/get_liver_om_lb_mi_tox_score_list.R

@@ -1,26 +1,48 @@
-
-
 #' @title get_liver_om_lb_mi_tox_score_list
-#' @param studyid_or_studyids  Mandatory, character \cr
-#'   Studyid number
-#' @param path_db Mandatory, character \cr
-#'   path of database
-#' @param fake_study optional, Boolean \cr
-#' whether study generated by SENDsanitizer package
-#' @param use_xpt_file Mandatory, character \cr
-#'   path of database
-#' @param multiple_xpt_folder Mandatory, character \cr
-#'   path of database
-#' @param output_individual_scores optional, Boolean \cr
-#' whether study generated by SENDsanitizer package
-#' @param output_zscore_by_USUBJID optional, Boolean \cr
-#' whether study generated by SENDsanitizer package
-#' @return dataframe
+#'
+#' @description
+#' This function processes liver organ toxicity scores, body weight z-scores, and other related metrics
+#' for a set of studies or XPT files. It can output individual scores, z-scores by USUBJID, or averaged scores
+#' for multiple studies, and handles errors during the processing steps.
+#'
+#' @param studyid_or_studyids A character vector or a single study ID to process.
+#' If multiple studies are provided, the function processes each study sequentially. (Mandatory)
+#'
+#' @param path_db A character string specifying the path to the database or directory containing the data files.
+#' (Mandatory)
+#'
+#' @param fake_study A boolean flag indicating if the study data is simulated (`TRUE`) or real (`FALSE`). Default is `FALSE`. (Optional)
+#'
+#' @param use_xpt_file A boolean flag indicating whether to use an XPT file for the study data. Default is `FALSE`. (Mandatory)
+#'
+#' @param multiple_xpt_folder A character string specifying the path to the folder containing multiple XPT files.
+#' (Optional)
+#'
+#' @param output_individual_scores A boolean flag indicating whether individual scores should be returned (`TRUE`) or averaged scores (`FALSE`). Default is `FALSE`. (Optional)
+#'
+#' @param output_zscore_by_USUBJID A boolean flag indicating whether to output z-scores by `USUBJID` (`TRUE`) or averaged scores (`FALSE`). Default is `FALSE`. (Optional)
+#'
+#' @return A data frame containing the calculated scores for each study. The type of result depends on the flags passed:
+#' - If `output_individual_scores` is `TRUE`, a data frame with individual scores for each study is returned.
+#' - If `output_zscore_by_USUBJID` is `TRUE`, a data frame with z-scores by `USUBJID` for each study is returned.
+#' - If neither flag is set, the function returns a data frame with averaged scores for each study.
 #'
 #' @examples
 #' \dontrun{
-#' get_compile_data(studyid='1234123', path_db='path/to/database.db')
+#' # Get averaged scores for a single study
+#' result <- get_liver_om_lb_mi_tox_score_list(
+#'   studyid_or_studyids = "Study_001",
+#'   path_db = "path/to/database"
+#' )
+#'
+#' # Get individual scores for multiple studies
+#' result_individual_scores <- get_liver_om_lb_mi_tox_score_list(
+#'   studyid_or_studyids = c("Study_001", "Study_002"),
+#'   path_db = "path/to/database",
+#'   output_individual_scores = TRUE
+#' )
 #' }
+#'
 #' @export
 
 

R/get_3livertobw_score.R → R/get_livertobw_score.R

@@ -1,33 +1,62 @@
-#' @title get_liver_livertobw_score
-#' @param studyid Mandatory, character \cr
-#'   Studyid number
-#' @param path_db Mandatory, character \cr
-#'   path of database
-#' @param fake_study optional, Boolean \cr
-#' whether study generated by SENDsanitizer package
-#' @param use_xpt_file optional, Boolean \cr
-#' whether use_xpt_file is used on not
-#' @param master_compiledata optional, Boolean \cr
-#' whether use_xpt_file is used on not
-#' @param bwzscore_BW optional, Boolean \cr
-#' whether use_xpt_file is used on not
-#' @param return_individual_scores optional, logical \cr
-#' whether use_xpt_file is used on not
-#' @param return_zscore_by_USUBJID optional, logical \cr
-#' whether use_xpt_file is used on not
-#' @return dataframe
+#' @title Calculate Liver-to-Body-Weight Scores and Z-Scores
+#'
+#' @description
+#' This function computes liver-to-body-weight (Liver:BW) ratios 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 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`.
+#'
+#' @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`).
 #'
 #' @examples
 #' \dontrun{
-#' get_compile_data(studyid='1234123', path_db='path/to/database.db')
+#' # Example 1: Default averaged scores
+#' result <- get_livertobw_score(
+#'   studyid = '1234123',
+#'   path_db = 'path/to/database.db'
+#' )
+#' head(result)
+#'
+#' # Example 2: Individual scores by study
+#' result <- get_livertobw_score(
+#'   studyid = '1234123',
+#'   path_db = 'path/to/database.db',
+#'   return_individual_scores = TRUE
+#' )
+#' head(result)
+#'
+#' # Example 3: Z-scores by USUBJID
+#' result <- get_livertobw_score(
+#'   studyid = '1234123',
+#'   path_db = 'path/to/database.db',
+#'   return_zscore_by_USUBJID = TRUE
+#' )
+#' head(result)
 #' }
+#'
 #' @export
 
 
 
-
-
-
 get_livertobw_score <- function (studyid = NULL,
                                   path_db,
                                   fake_study = FALSE,

R/get_5mi_score.R → R/get_mi_score.R

@@ -1,27 +1,40 @@
-
-#' @title get MI score for a given studyid
+#' @title Get MI score for a given studyid
+#'
+#' @description
+#' This function calculates the MI score for a given study using the provided study ID and database. It allows flexibility in terms of returning individual scores, Z-scores, and more. The function is compatible with both SENDsanitizer-generated datasets and standard clinical study databases.
+#'
 #' @param studyid Mandatory, character \cr
-#'   Studyid number
+#'   The study ID number for the clinical study.
+#'
 #' @param path_db Mandatory, character \cr
-#'   path of database
-#' @param fake_study optional, Boolean \cr
-#' whether study generated by SENDsanitizer package
-#' @param use_xpt_file Mandatory, character \cr
-#'   Studyid number
+#'   The file path to the database that contains the study data.
+#'
+#' @param fake_study Optional, logical \cr
+#'   If TRUE, the function assumes that the study data was generated by the SENDsanitizer package. Default is FALSE.
+#'
+#' @param use_xpt_file Mandatory, logical \cr
+#'   If TRUE, indicates that an XPT file should be used instead of a database for analysis.
+#'
 #' @param master_compiledata Mandatory, character \cr
-#'   path of database
-#' @param return_individual_scores optional, Boolean \cr
-#' whether study generated by SENDsanitizer package
-#' @param  return_zscore_by_USUBJID optional, Boolean \cr
-#' whether study generated by SENDsanitizer package
-#' @return score
+#'   The path to the master compile data, often used to supplement or compile data from multiple sources.
+#'
+#' @param return_individual_scores Optional, logical \cr
+#'   If TRUE, the function returns individual MI scores for each participant. Default is FALSE.
+#'
+#' @param return_zscore_by_USUBJID Optional, logical \cr
+#'   If TRUE, the function returns the Z-scores by `USUBJID` (subject identifier). Default is FALSE.
+#'
+#' @return A numeric vector or data frame containing the MI scores. The format depends on the specified parameters, such as individual scores or aggregated scores.
 #'
 #' @examples
 #' \dontrun{
-#' get_mi_score(studyid='1234123', path_db='path/to/database.db')
+#' # Example usage of get_mi_score
+#' get_mi_score(studyid = '1234123', path_db = 'path/to/database.db')
 #' }
+#'
 #' @export
 
+
 get_mi_score <- function(studyid = NULL,
                          path_db,
                          fake_study=FALSE,