OCDocker.OCScore.Utils.IO module

Set of functions to manage I/O operations in OCDocker in the context of scoring functions.

Usage:

import OCDocker.OCScore.Utils.IO as ocscoreio

OCDocker.OCScore.Utils.IO.LOGGER = <Logger ocdocker.ocscore.utils.io (DEBUG)>

Copyright (c) Federal University of Rio de Janeiro (UFRJ), Artur Duque Rossi, and Pedro Henrique Monteiro Torres.

SPDX-License-Identifier: BSD-3-Clause

See the LICENSE file for full terms.

OCDocker.OCScore.Utils.IO.get_models_dir()[source]

Get the path to the OCScore models directory.

This directory is used to store models and masks that are shipped with the code. The directory is located at the project root level (same level as ODDT_models), separate from the code folder. The directory is created if it doesn’t exist.

Returns:

Path to the models directory.

Return type:

str

OCDocker.OCScore.Utils.IO.load_data(file_name, exclude_column='experimental')[source]

Loads a CSV file into a DataFrame, removes rows with NaNs (except in a specified column), and notifies the user.

Parameters:

  • file_name (str) – Name of the CSV file to load.

  • exclude_column (str) – Column to exclude from the NaN removal process.

Returns:

DataFrame containing the data from the CSV file.

Return type:

pd.DataFrame

OCDocker.OCScore.Utils.IO.load_mask(name, models_dir=None)[source]

Load a mask from a file in the models directory.

Parameters:

  • name (str) – Name of the mask file (without extension). The function will look for ‘{name}_mask.pkl’ in the models directory.

  • models_dir (str, optional) – Custom directory to load the mask from. If None, uses the default OCScore models directory. Default is None.

Returns:

The loaded mask array.

Return type:

np.ndarray

Raises:

FileNotFoundError – If the mask file is not found.

OCDocker.OCScore.Utils.IO.load_object(file_name, serialization_method='auto', trusted=False)[source]

Load an object from a file using pickle, joblib, or torch.

Security

Only load serialized files from trusted sources. Pickle/joblib deserialization can execute arbitrary code if the file is malicious or untrusted.

param file_name:

The name of the file from which to load the object.

type file_name:

str

param serialization_method:

The serialization method used to save the object. Options are: - “auto”: Automatically detect from file extension (.pt/.pth -> torch, .pkl -> joblib/pickle) - “joblib”: Use joblib to load - “pickle”: Use pickle to load - “torch”: Use torch.load to load (for PyTorch models)

type serialization_method:

str

param trusted:

Explicit opt-in that the serialized input is trusted. If False, loading is blocked unless OCDOCKER_ALLOW_UNSAFE_DESERIALIZATION=1 is set. Default is False.

type trusted:

bool, optional

returns:

The loaded object.

rtype:

Any

raises ValueError:

If the serialization method is not recognized.

Parameters:

  • file_name (str)

  • serialization_method (str)

  • trusted (bool)

Return type:

Any

OCDocker.OCScore.Utils.IO.save_mask(mask, name, models_dir=None)[source]

Save a mask to a file in the models directory.

Parameters:

  • mask (list | np.ndarray) – The mask array of 0s and 1s to save.

  • name (str) – Name for the mask file (without extension). The file will be saved as ‘{name}_mask.pkl’ in the models directory.

  • models_dir (str, optional) – Custom directory to save the mask. If None, uses the default OCScore models directory. Default is None.

Returns:

Path to the saved mask file.

Return type:

str

Raises:

ValueError – If the mask is not a valid array of 0s and 1s.

OCDocker.OCScore.Utils.IO.save_object(obj, filename, serialization_method='auto')[source]

Save an object to a file using pickle, joblib, or torch.

Parameters:

  • obj (Any) – The object to be saved.

  • filename (str) – The name of the file where the object will be stored.

  • serialization_method (str) – The serialization method to use. Options are: - “auto”: Automatically detect from file extension (.pt/.pth -> torch, .pkl -> joblib) - “joblib”: Use joblib to save (recommended for sklearn models, XGBoost) - “pickle”: Use pickle to save - “torch”: Use torch.save to save (for PyTorch models)

Return type:

None

OCDocker.OCScore.Utils.IO.read_csv_column_names(csv_path)[source]

Read CSV column names without loading table rows.

Parameters:

csv_path (str or pathlib.Path) – Path to a CSV file.

Returns:

Column names from the header row.

Return type:

list[str]

Raises:

  • ValueError – If the CSV is empty or has no columns.

  • FileNotFoundError – If csv_path does not exist.

OCDocker.OCScore.Utils.IO.pdbbind_columns_from_header(columns)[source]

Return PDBbind column names after prepare_pdbbind_dataframe additions.

Parameters:

columns (Sequence[str]) – Raw PDBbind CSV header columns.

Returns:

Header columns plus any workflow columns added during preparation.

Return type:

list[str]

OCDocker.OCScore.Utils.IO.dudez_columns_from_header(columns)[source]

Return DUDEz column names after prepare_dudez_dataframe additions.

Parameters:

columns (Sequence[str]) – Raw DUDEz CSV header columns.

Returns:

Header columns plus any workflow columns added during preparation.

Return type:

list[str]

OCDocker.OCScore.Utils.IO.read_pipeline_csv_columns(archive_path, member_name=None)[source]

Read pipeline CSV column names without loading table rows.

Parameters:

  • archive_path (str or pathlib.Path) – Path to a pipeline CSV file, extracted directory, or tar archive.

  • member_name (str, optional) – Explicit tar member path when multiple pipeline CSV files exist.

Returns:

Column names from the selected pipeline CSV header.

Return type:

list[str]

Raises:

  • FileNotFoundError – If the path or a canonical pipeline CSV is missing.

  • ValueError – If the archive cannot be read or the CSV header is empty.

OCDocker.OCScore.Utils.IO.load_pipeline_results_from_archive(archive_path, member_name=None)[source]

Load pipeline results from a CSV file, directory, or tar archive.

Accepts a bare .csv path, a directory, or a tar archive containing one of: pipeline_results.csv, PDBbind.csv, or DUDEz.csv (classic and ocdb2 layouts). When multiple matching members exist inside a tar archive, pass member_name to select one.

Parameters:

  • archive_path (str or pathlib.Path) – Path to a pipeline CSV file, extracted directory, or tar archive.

  • member_name (str, optional) – Explicit tar member path when multiple pipeline CSV files exist.

Returns:

Loaded pipeline results table.

Return type:

pd.DataFrame

Raises:

  • FileNotFoundError – If the path or a canonical pipeline CSV is missing.

  • ValueError – If the archive cannot be read, the CSV is empty, or multiple members exist without an explicit member_name.

OCDocker.OCScore.Utils.IO.load_pipeline_results(archive_path, member_name=None)

Load pipeline results from a CSV file, directory, or tar archive.

Accepts a bare .csv path, a directory, or a tar archive containing one of: pipeline_results.csv, PDBbind.csv, or DUDEz.csv (classic and ocdb2 layouts). When multiple matching members exist inside a tar archive, pass member_name to select one.

Parameters:

  • archive_path (str or pathlib.Path) – Path to a pipeline CSV file, extracted directory, or tar archive.

  • member_name (str, optional) – Explicit tar member path when multiple pipeline CSV files exist.

Returns:

Loaded pipeline results table.

Return type:

pd.DataFrame

Raises:

  • FileNotFoundError – If the path or a canonical pipeline CSV is missing.

  • ValueError – If the archive cannot be read, the CSV is empty, or multiple members exist without an explicit member_name.

OCDocker.OCScore.Utils.IO.drop_empty_input_rows(df, *, label='input')[source]

Drop rows that are entirely empty before OCScore modeling preparation.

CSV rows containing only blank strings are treated as empty as well as rows parsed as all-NaN.

Parameters:

  • df (DataFrame)

  • label (str)

Return type:

tuple[DataFrame, int]

OCDocker.OCScore.Utils.IO.prepare_pdbbind_dataframe(df)[source]

Prepare PDBbind pipeline rows for OCScore feature workflows.

Parameters:

df (pd.DataFrame) – Raw PDBbind pipeline results.

Returns:

Prepared PDBbind rows with dataset and label columns.

Return type:

pd.DataFrame

Raises:

ValueError – If the PDBbind affinity target column is missing.

OCDocker.OCScore.Utils.IO.prepare_dudez_dataframe(df)[source]

Prepare DUDEz pipeline rows for OCScore feature workflows.

Parameters:

df (pd.DataFrame) – Raw DUDEz pipeline results.

Returns:

Prepared DUDEz rows with dataset and label columns.

Return type:

pd.DataFrame

Raises:

ValueError – If the DUDEz kind column is missing.