OCDocker.OCScore.CLI.train module

ocdocker ocscore train — staged Optuna from raw modeling inputs.

CLI for staged OCScore Optuna from raw unreduced modeling inputs.

The train command loads raw pipeline tables, creates a fixed outer split, fits train-only feature reduction on PDBbind training rows, and runs replicated staged Optuna on the frozen feature set.

class OCDocker.OCScore.CLI.train.ReductionArtifacts(pdbbind_df, dudez_df, selected_features, artifact_paths, extracted_dir, feature_selection=None, fixed_outer_split=None, row_cleanup_summary=None, feature_policy_metadata=None)[source]

Bases: object

Modeling artifacts produced after train-only feature reduction.

Parameters:

  • pdbbind_df (pd.DataFrame) – PDBbind dataframe with frozen train-only selected features applied.

  • dudez_df (pd.DataFrame) – DUDEz dataframe with frozen train-only selected features applied.

  • selected_features (list[str]) – Selected feature columns from train-only reduction.

  • artifact_paths (dict[str, str]) – Paths to written modeling and feature-selection artifacts.

  • extracted_dir (pathlib.Path) – Base directory associated with the loaded or written modeling inputs.

  • feature_selection (FeatureSelectionScope | None, optional) – Train-only feature-selection metadata.

  • fixed_outer_split (FixedOuterSplitAssignment | None, optional) – Fixed outer split shared by all replicas.

  • row_cleanup_summary (dict | None, optional) – Summary of selected-feature row cleanup before modeling.

  • feature_policy_metadata (dict | None, optional) – Feature-policy provenance for this reduction pass.

pdbbind_df: DataFrame
dudez_df: DataFrame
selected_features: list[str]
artifact_paths: dict[str, str]
extracted_dir: Path
feature_selection: FeatureSelectionScope | None = None
fixed_outer_split: FixedOuterSplitAssignment | None = None
row_cleanup_summary: dict[str, Any] | None = None
feature_policy_metadata: dict[str, Any] | None = None
class OCDocker.OCScore.CLI.train.StagedTrainingRun(artifacts, pdbbind_df, dudez_df, context, metadata, result, written, protocol_metadata, replica_alignments)[source]

Bases: object

Result bundle for one full or ablation staged-training pass.

Parameters:
artifacts: ReductionArtifacts
pdbbind_df: DataFrame
dudez_df: DataFrame
context: ProtocolContext
metadata: dict[str, Any]
result: ReplicatedProtocolResult
written: dict[str, str]
protocol_metadata: dict[str, Any]
replica_alignments: list[dict[str, Any]]
OCDocker.OCScore.CLI.train.add_arguments(parser)[source]

Register ocscore train command-line arguments.

Parameters:

parser (argparse.ArgumentParser) – Parser or subparser to extend.

Return type:

None

OCDocker.OCScore.CLI.train.build_argparser()[source]

Build the ocscore train command-line parser.

Return type:

ArgumentParser

OCDocker.OCScore.CLI.train.register_subparser(subparsers)[source]

Register the train subcommand on the ocscore parser.

Parameters:

subparsers (_SubParsersAction)

Return type:

None

OCDocker.OCScore.CLI.train.cmd_train(args)[source]

Dispatch handler for ocscore train.

Parameters:

args (Namespace)

Return type:

int

OCDocker.OCScore.CLI.train.resolve_reduction_source(archive_path)[source]

Validate and return a feature-reduction source path.

Directory inputs are read in place; tar/tar.gz inputs are read member-by-member by pandas and JSON/text loaders.

Parameters:

archive_path (str or pathlib.Path) – Feature-reduction archive or directory path.

Returns:

Validated source path.

Return type:

pathlib.Path

Raises:

  • FileNotFoundError – If the source path does not exist.

  • ValueError – If the source is neither a directory nor a tar archive.

OCDocker.OCScore.CLI.train.load_selected_features(extracted_dir)[source]

Load selected features from a reduction directory or tar archive.

Parameters:

extracted_dir (str or pathlib.Path) – Directory or tar archive containing feature-reduction outputs.

Returns:

Selected feature list and source identifier.

Return type:

tuple[list[str], pathlib.Path | str]

OCDocker.OCScore.CLI.train.load_reduced_datasets(extracted_dir)[source]

Load reduced PDBbind and DUDEz datasets from a directory or tar archive.

Parameters:

extracted_dir (str or pathlib.Path) – Directory or tar archive containing feature-reduction outputs.

Returns:

Reduced PDBbind dataframe, reduced DUDEz dataframe, and source paths.

Return type:

tuple[pd.DataFrame, pd.DataFrame, dict[str, str]]

OCDocker.OCScore.CLI.train.load_reduction_artifacts(extracted_dir)[source]

Reject deprecated global/precomputed reduction archives for training.

Parameters:

extracted_dir (str or pathlib.Path) – Legacy reduction directory or archive path.

Returns:

Never returned; retained for backward-compatible import paths in tests.

Return type:

ReductionArtifacts

Raises:

ValueError – If the source contains forbidden precomputed artifacts or the deprecated API is used.

OCDocker.OCScore.CLI.train.load_merged_input_dataset(source)[source]

Load merged_input_dataset.csv from a directory or tar archive.

Parameters:

source (str or pathlib.Path) – Directory or tar archive that may contain a merged raw input table.

Returns:

Merged raw input dataframe when present, otherwise None.

Return type:

pd.DataFrame | None

OCDocker.OCScore.CLI.train.apply_train_only_feature_reduction(protocol, raw_input, *, output_dir, feature_blocks=None, feature_policy=None, feature_policy_lookup_dirs=())[source]

Apply train-only feature reduction on a fixed outer split.

Parameters:

  • protocol (StagedTrainProtocol) – Loaded staged training protocol defining split policy and task columns.

  • raw_input (RawModelingInput) – Validated raw unreduced modeling input.

  • output_dir (pathlib.Path) – Directory where fixed split and train-only reduction artifacts are written.

  • feature_blocks (Sequence[str] | None, optional) – Descriptor blocks eligible for this reduction pass. None keeps the full ligand+receptor+scoring protocol.

  • feature_policy (FeaturePolicy | None, optional) – Feature-ablation policy used to constrain candidate model descriptors before train-only reduction is fitted.

  • feature_policy_lookup_dirs (Sequence[str | pathlib.Path], optional) – Lookup directories recorded in feature-policy provenance.

Returns:

Modeling tables and metadata after frozen train-only feature selection.

Return type:

ReductionArtifacts

OCDocker.OCScore.CLI.train.validate_selected_features(pdbbind_df, dudez_df, selected_features)[source]

Validate selected feature columns before staged Optuna modeling.

Parameters:

  • pdbbind_df (pd.DataFrame) – Reduced PDBbind dataframe.

  • dudez_df (pd.DataFrame) – Reduced DUDEz dataframe.

  • selected_features (Sequence[str]) – Selected feature columns from feature reduction.

Raises:

ValueError – If selected features are missing, non-numeric, or contain NaN/Inf.

Return type:

None

OCDocker.OCScore.CLI.train.prepare_pdbbind_for_optuna(pdbbind_df, target_column='experimental')[source]

Prepare reduced PDBbind rows for regression Optuna.

The default behavior is explicit: rows with missing or non-numeric target values are dropped and the dropped-row count is returned for logging.

Parameters:

  • pdbbind_df (pd.DataFrame) – Reduced PDBbind dataframe.

  • target_column (str, optional) – Regression target column, by default "experimental".

Returns:

Cleaned PDBbind dataframe and number of dropped target rows.

Return type:

tuple[pd.DataFrame, int]

Raises:

ValueError – If the target column is missing or no rows remain after cleanup.

OCDocker.OCScore.CLI.train.prepare_dudez_for_optuna(dudez_df, kind_column='kind', positive_kind='ligands', negative_kind='decoys', ignore_unknown_kind=False)[source]

Prepare reduced DUDEz rows for screening Optuna.

The final kind values passed to the staged Optuna API are standardized to "ligands" and "decoys" so custom CLI kind names can still be used with the reusable DUDEz stage.

Parameters:

  • dudez_df (pd.DataFrame) – Reduced DUDEz dataframe.

  • kind_column (str, optional) – Column containing active/decoy kind values, by default "kind".

  • positive_kind (str, optional) – Raw kind value mapped to label 1, by default "ligands".

  • negative_kind (str, optional) – Raw kind value mapped to label 0, by default "decoys".

  • ignore_unknown_kind (bool, optional) – Drop rows with unknown kind values instead of failing, by default False.

Returns:

Prepared DUDEz dataframe, class counts, and dropped unknown-kind rows.

Return type:

tuple[pd.DataFrame, dict[int, int], int]

Raises:

ValueError – If the kind column is missing, unknown kinds are present, or only one class remains.

OCDocker.OCScore.CLI.train.copy_feature_reduction_artifacts(extracted_dir, output_dir)[source]

Copy optional feature-reduction reports into the Optuna output directory.

Parameters:

  • extracted_dir (str or pathlib.Path) – Directory or tar archive containing feature-reduction outputs.

  • output_dir (str or pathlib.Path) – Staged Optuna output directory.

Returns:

Mapping from artifact filename to copied output path.

Return type:

dict[str, str]

OCDocker.OCScore.CLI.train.build_protocol_context(pdbbind_df, dudez_df, selected_features, output_dir, random_seed, metadata=None)[source]

Build the staged Optuna protocol context.

Parameters:

  • pdbbind_df (pd.DataFrame) – Prepared reduced PDBbind dataframe.

  • dudez_df (pd.DataFrame) – Prepared reduced DUDEz dataframe.

  • selected_features (Sequence[str]) – Selected feature columns from feature reduction.

  • output_dir (str or pathlib.Path) – Staged Optuna output directory.

  • random_seed (int) – Random seed used by protocol stages.

  • metadata (dict[str, Any], optional) – Dataset paths, reduction artifact paths, and run metadata.

Returns:

Context passed to the staged Optuna API.

Return type:

ProtocolContext

OCDocker.OCScore.CLI.train.write_example_outputs(result, base_context, reduction_archive, extracted_dir, output_dir)[source]

Write example-level summaries around replicated protocol outputs.

Parameters:

  • result (ReplicatedProtocolResult) – Result returned by the replicated staged Optuna protocol.

  • base_context (ProtocolContext) – Base protocol context shared by all modeling replicas.

  • reduction_archive (str or pathlib.Path) – Source feature-reduction archive path.

  • extracted_dir (str or pathlib.Path) – Directory or archive containing feature-reduction outputs.

  • output_dir (str or pathlib.Path) – Staged Optuna output directory.

Returns:

Written summary output paths.

Return type:

dict[str, str]

OCDocker.OCScore.CLI.train.main(argv=None)[source]

Run staged OCScore Optuna from raw unreduced modeling inputs.

Parameters:

argv (list[str], optional) – Optional argument list for testing or programmatic execution.

Returns:

Process exit code. Zero indicates success.

Return type:

int

OCDocker.OCScore.CLI.train.main_from_args(args)[source]

Run the unified leakage-safe staged training protocol.

Parameters:

args (argparse.Namespace) – Parsed command-line arguments.

Returns:

Process exit code. Zero indicates success.

Return type:

int

Raises:

ValueError – If deprecated reduction inputs are supplied or protocol validation fails.