OCDocker.OCScore.Utils.Data module¶

Set of functions to manage data processment in OCDocker in the context of scoring functions.

Usage:

import OCDocker.OCScore.Utils.Data as ocscoredata

OCDocker.OCScore.Utils.Data.apply_pca(df, pca_model, columns_to_skip_pca=[], inplace=False)[source]¶

Applies PCA to a DataFrame using a pre-trained PCA model.

Parameters:

df (pd.DataFrame) – Input DataFrame.
pca_model (str) – Path to the pre-trained PCA model or the PCA model.
columns_to_skip_pca (list[str], optional) – List of columns to keep in the DataFrame before applying PCA. The default is [].
inplace (bool, optional) – If True, the original DataFrame is modified. If False, a new DataFrame is returned. The default is False.

Returns:

DataFrame with PCA applied if inplace is False. None if inplace is True.

Return type:

pd.DataFrame or None

Raises:

FileNotFoundError – If the PCA model path is not found.
TypeError – If the PCA model type is invalid. Must be a string or a PCA model.

OCDocker.OCScore.Utils.Data.get_column_order(data=None)[source]¶

Get the column order from a data source (file path or DataFrame) or from config.

This function extracts the column order from either a file path, an existing DataFrame, or from the config file if no data source is provided. This ensures consistency with the order used during model training. This is critical for proper mask application and feature alignment.

Parameters:

data (str | pd.DataFrame | None, optional) – Either: - A file path (CSV or gzipped CSV) to load column order from - A pandas DataFrame to extract column order from - None to use the column order from config (default: None)

Returns:

List of column names in the exact order they appear in the data source or config.

Return type:

list[str]

Raises:

FileNotFoundError – If data is a string path and the file is not found.
TypeError – If data is neither a string, DataFrame, nor None.
ValueError – If data is None and config does not have reference_column_order set.

OCDocker.OCScore.Utils.Data.invert_values_conditionally(df, regex_pattern='^(VINA|SMINA|PLANTS).*|^experimental$', inplace=False)[source]¶

Inverts the values of specific columns in a DataFrame. The inversion is applied to columns that start with ‘VINA’, ‘SMINA’, or ‘PLANTS’ as well as the column named ‘experimental’.

This function multiplies the values in these columns by -1, effectively inverting them. It’s particularly useful in scenarios where the sign of these values needs to be reversed for analysis or data processing.

Parameters:

df (pd.DataFrame) – Input DataFrame.
regex_pattern (str) – Regular expression pattern to match the columns to invert. The default pattern matches columns that start with ‘VINA’ or ‘SMINA’, as well as the column named ‘experimental’. (r”^(VINA|SMINA).*|^experimental$”)
inplace (bool) – If True, the original DataFrame is modified. If False, a new DataFrame is returned.

Returns:

DataFrame with inverted values, ensuring not to modify the original DataFrame.

Return type:

pd.DataFrame

OCDocker.OCScore.Utils.Data.norm_data(df, scaler='standard', inplace=False)[source]¶

Preprocesses the input DataFrame by scaling selected feature columns using a Scaler. The metadata columns (“receptor”, “ligand”, “name”, “type”, “db”) and target variable (“experimental”) are preserved and excluded from scaling.

Parameters:

df (pd.DataFrame) – Input DataFrame.
scaler (str | StandardScaler | MinMaxScaler) – Scaler to use. Options are: - “standard” or “minmax”: Creates and fits a new scaler - StandardScaler or MinMaxScaler object: Uses the provided pre-fitted scaler
inplace (bool) – If True, the original DataFrame is modified. If False, a new DataFrame is returned.

Returns:

DataFrame with normalized features while preserving metadata and target variable. If scaler is a string (new scaler), returns tuple of (DataFrame, fitted_scaler) if inplace=False, or just DataFrame if inplace=True. If scaler is a pre-fitted object, returns only the DataFrame.

Return type:

pd.DataFrame | tuple[pd.DataFrame, Union[StandardScaler, MinMaxScaler]]

OCDocker.OCScore.Utils.Data.remove_other_columns(df, columns_to_keep, inplace=False)[source]¶

Removes columns from a DataFrame that are not in the specified list.

Parameters:

df (pd.DataFrame) – Input DataFrame.
columns_to_keep (list) – List of columns to keep.
inplace (bool) – If True, the original DataFrame is modified. If False, a new DataFrame is returned.

Returns:

DataFrame with only the specified columns.

Return type:

pd.DataFrame

OCDocker.OCScore.Utils.Data.reorder_columns_to_match_data_order(df, data_source=None, keep_extra_columns=True, fill_missing_columns=False)[source]¶

Reorder DataFrame columns to match the column order from another data source.

!!! CRITICAL: This function ensures that all columns are in the exact same order as the data source, which is essential for proper mask application and model inference. The order of scoring functions (SFs) is particularly important for masks.

This is typically used to ensure prediction data has the same column order as the training data, ensuring masks and models work correctly.

Parameters:

df (pd.DataFrame) – Input DataFrame to reorder.
data_source (str | pd.DataFrame | None, optional) – Data source to match column order from. Either: - A file path (CSV or gzipped CSV) to load column order from - A pandas DataFrame to extract column order from - None to use reference_column_order from config (default: None)
keep_extra_columns (bool, optional) – If True, columns not in data_source are kept at the end (default: True). If False, extra columns are dropped.
fill_missing_columns (bool, optional) – If True, missing columns from data_source are added as NaN (default: False). If False, missing columns are simply not included.

Returns:

DataFrame with columns reordered to match data_source column order.

Return type:

pd.DataFrame

Raises:

FileNotFoundError – If data_source is a string path and the file is not found.
TypeError – If data_source is neither a string nor a DataFrame.