get_bw_score

get_bw_score(bw, master_compiledata=None, tK_animals_df=None, return_individual_scores=False, return_zscore_by_USUBJID=False)

Processes body weight data for study subjects, calculates z-scores, and enforces mutual exclusivity of certain return options.

Parameters:

• bw (pandas.DataFrame): A DataFrame containing body weight data with columns STUDYID, USUBJID, BWTESTCD, BWSTRESN, VISITDY, and optionally BWDY.

• master_compiledata (pandas.DataFrame, optional): A DataFrame containing metadata for subjects, including USUBJID, ARMCD, SETCD, and SEX. Defaults to None.

• tK_animals_df (pandas.DataFrame, optional): A DataFrame containing information about animals to exclude, such as toxicokinetic (TK) animals. Defaults to None.

• return_individual_scores (bool, optional): If True, individual scores for each subject will be calculated and returned. Defaults to False.

• return_zscore_by_USUBJID (bool, optional): If True, z-scores by USUBJID will be calculated and returned. Defaults to False.

Raises:

• ValueError: If both return_individual_scores and return_zscore_by_USUBJID are set to True.

Returns:

• pandas.DataFrame: A DataFrame containing processed body weight data, filtered subjects, and calculated z-scores for high-dose (HD) subjects.

Notes:

This function performs the following steps: - Replaces missing VISITDY values with corresponding BWDY values. - Selects TERMBW rows or those with the maximum VISITDY > 5 if TERMBW is not available. - Filters out toxicokinetic (TK) animals using master_compiledata. - Joins body weight data with additional metadata and calculates z-scores for each subject in the “HD” group.

Example usage:

result = get_bw_score(
    bw=bw_data,
    master_compiledata=master_data,
    tK_animals_df=tk_animals,
    return_individual_scores=False,
    return_zscore_by_USUBJID=True
)

The resulting DataFrame includes columns such as STUDYID, USUBJID, SEX, and BWZSCORE.