Documentation for `get_bw_score` Function

Purpose

The get_bw_score function is designed to normalize the the body-weight (BW) of each subject (animal) termed as ‘USUBJID’ in SEND database, using Z-scoring method. Z-scoring is a basic method which Z-scored the continuous data like the body weight, clinical pathology, lab test results by transforming each value into how many standard deviations it is above or below the control mean.

Z-Score Calculation

The Z-score normalization is performed as shown in Equation below:

$Z_{s,i} = \frac{x_{s,i} - \mu_{s,c}}{\sigma_{s,c}}$

Where: - $x_{s,i}$ is the observed endpoint value for individual $i$ in study $s$ , - $\mu_{s,c}$ is the mean value of the observed endpoint for the control group $c$ in study $s$ , - $\sigma_{s,c}$ is the standard deviation of the observed endpoint for the control group $c$ in study $s$ , - $s$ is the study identifier, - $i$ refers to an individual animal in the study, - $c$ refers to the control-treated group of animals within the study.

Function Parameters (Arguments)

Parameter	Type	Default	Description
`studyid`	Conditional, character	`NULL`	The STUDYID of the study for which the BW score is to be calculated. Required when `use_xpt_file = FALSE`. If `use_xpt_file = TRUE`, `studyid` is ignored, and the `.xpt` files of that study in the specified folder are analyzed.
`path_db`	Mandatory, character	—	The path to the database or the `.xpt` file containing study data.
`fake_study`	Optional, Boolean	`FALSE`	Indicates whether the study was generated by the `SENDsanitizer` package.
`use_xpt_file`	Mandatory, Boolean	`FALSE`	If `TRUE`, the function processes study data using `.xpt` files located in the folder specified by `path_db`. In this case, `studyid` is ignored. If `FALSE`, the function uses the database file at `path_db` and requires a valid `studyid`.
`master_compiledata`	Optional, character	`NULL`	If `master_compiledata` is not supplied (i.e., `NULL`), the function will automatically call the `get_compile_data` function to calculate it.
`return_individual_scores`	Optional, Boolean	`FALSE`	If `TRUE`, the function returns individual scores for each of the domain by averaging the scores of all the subjects/animals (`USUBJID`) in the study.
`return_zscore_by_USUBJID`	Optional, Boolean	`FALSE`	If `TRUE`, the function returns z-scores for each of the animals/subjects by `USUBJID` (unique subject identifiers).

Key Points: - Mandatory Parameter: path_db is required for the function to work. - Logical Exclusivity: Both return_individual_scores and return_zscore_by_USUBJID cannot be TRUE simultaneously.

Output

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_zscore_by_USUBJID = TRUE: Returns Z-score for each animal/subject by USUBJID for each domain per studyid.
Otherwise, a summarized BW Z-score for the specified studyid.

Implementation Details

The get_bw_score function follows a systematic approach to calculate the BW Z-score for a given study ID. Below are the key steps involved:

Database Connection

The function establishes a connection to the specified SQLite database using the RSQLite package or processes .xpt files depending on the value of the use_xpt_file parameter:

If use_xpt_file = TRUE: Data is loaded from .xpt files located in the folder specified by path_db.
If use_xpt_file = FALSE: Data is extracted from the SQLite database file located at path_db.

Data Retrieval

The function retrieves the necessary data related to the specified studyid. The data retrieval process depends on whether master_compiledata is provided or NULL:

When master_compiledata = NULL,

If master_compiledata is not provided, the function extracts data from the following SEND domains:

BW (Body Weight) : Provide the Body Weight measurements at the individual level.
DM (Demographics): Supplies animal-level demographic details.
DS (Disposition): Identifies recovery animals using the DSDECOD column.
PC (Pharmacokinetics): Provide USUBJID of the TK animals for rats and mice study.
TX (Treatment): Provide dose levels information such as “vehicle” or “HD.”

When master_compiledata is Provided,

If master_compiledata value is provided, this function retrieve the following domains:

BW (Body Weight) : Provide the Body Weight measurements at the individual level.

Baseline Weight Adjustment

The weight of each animal is normalized by subtracting their baseline weight recorded on the first day of dosing.

Z-Score Normalization

The adjusted weights are further normalized using the Z-score equation described in the “Z-Score Calculation” section above.

Handling Optional Parameters

If return_individual_scores = TRUE, Returns averaged Z-scores for each of the domain per studyid.
If return_zscore_by_USUBJID = TRUE, Returns Z-score for each animal/subject by unique subject identifiersUSUBJID.

Fake Study Handling

If fake_study = TRUE, special handling is applied for data sets generated by the SENDsanitizer package to account for their structure.

Output Generation

A data frame containing the requested scores is returned. This may include summarized scores, individual scores, or Z-scores by USUBJID, based on the parameters provided.

Dependencies

The function requires the following R packages:

RSQLite: To connect to the SQLite database.
haven : To read .xpt file, if use_xpt_file = TRUE.

This implementation ensures flexibility in handling different input types and configurations while maintaining a consistent structure for the output.

Example Usage

# 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)

Md Aminul Islam Prodhan

2025-05-01