OCDocker.OCScore.Utils.FeatureSelectionMetadata module

Feature-selection scope metadata for OCScore staged protocols.

Records whether selected features were derived globally during reduce or fit on training data only during train, so staged runs fail closed on leakage.

class OCDocker.OCScore.Utils.FeatureSelectionMetadata.FeatureSelectionScope(scope, fit_dataset, fit_split=None, selected_features_source='reduction_protocol', uses_supervised_target=False, reduction_archive=None, n_selected_features=None, fit_row_indices=None, fit_row_count=None, fit_row_indices_hash=None, fit_row_content_hash=None, fit_row_indices_artifact=None, feature_selection_mode=None, selected_features=None, selected_features_hash=None, removed_features=None, removed_features_hash=None, transform_artifacts=<factory>, transform_artifact_hashes=<factory>, notes=<factory>)[source]

Bases: object

Provenance for how model input features were chosen.

Parameters:

  • scope (str) – precomputed_global when the reduce CLI used all rows before modeling splits; train_only when fit on training rows only during staged train.

  • fit_dataset (str) – Dataset partition used to derive features (e.g. pdbbind_train).

  • fit_split (str | None) – Split name when scope is train-only (e.g. train).

  • selected_features_source (str) – reduction_protocol, externally_supplied, or train_derived.

  • uses_supervised_target (bool, optional) – True when target-aware selection was used, by default False.

  • reduction_archive (str | None, optional) – Path to reduction archive when externally supplied.

  • n_selected_features (int | None, optional) – Count of selected features for quick audit.

  • fit_row_indices (list[int] | None, optional) – Row indices when scope is train-only. Kept in memory for optional artifact writing, but omitted from summary dictionaries by default.

  • fit_row_count (int | None, optional) – Number of rows used to fit feature selection.

  • fit_row_indices_hash (str | None, optional) – SHA-256 hash of the ordered fit-row index list.

  • fit_row_content_hash (str | None, optional) – SHA-256 hash of fit-row identifiers/content used for audit.

  • fit_row_indices_artifact (str | None, optional) – Path to the full fit-row index artifact when written.

  • feature_selection_mode (str | None, optional) – Validation mode active when metadata was recorded.

  • selected_features (list[str] | None, optional) – Ordered selected feature list for reproducibility checks.

  • selected_features_hash (str | None, optional) – SHA-256 hash of selected_features.

  • removed_features (list[str] | None, optional) – Features removed during reduction relative to the fit input.

  • removed_features_hash (str | None, optional) – SHA-256 hash of removed_features.

  • transform_artifacts (list[str], optional) – Names of frozen transform/selection steps (for example correlation filters).

  • transform_artifact_hashes (dict[str, str], optional) – Optional hashes keyed by transform artifact name.

  • notes (list[str], optional) – Human-readable warnings or context.

scope: Literal['precomputed_global', 'train_only']
fit_dataset: str
fit_split: str | None = None
selected_features_source: Literal['externally_supplied', 'reduction_protocol', 'train_derived'] = 'reduction_protocol'
uses_supervised_target: bool = False
reduction_archive: str | None = None
n_selected_features: int | None = None
fit_row_indices: list[int] | None = None
fit_row_count: int | None = None
fit_row_indices_hash: str | None = None
fit_row_content_hash: str | None = None
fit_row_indices_artifact: str | None = None
feature_selection_mode: Literal['production-strict', 'external-blind'] | None = None
selected_features: list[str] | None = None
selected_features_hash: str | None = None
removed_features: list[str] | None = None
removed_features_hash: str | None = None
transform_artifacts: list[str]
transform_artifact_hashes: dict[str, str]
notes: list[str]
to_dict(*, include_fit_row_indices=False)[source]

Return a JSON-serializable dictionary.

The full fit_row_indices list is intentionally omitted by default so summary/provenance reports stay readable. Write it to feature_selection_fit_rows.json when the full audit trail is needed.

Parameters:

include_fit_row_indices (bool)

Return type:

dict[str, Any]

classmethod from_dict(payload)[source]

Build scope from a JSON-compatible mapping.

Parameters:

payload (dict[str, Any])

Return type:

FeatureSelectionScope

classmethod precomputed_global(*, fit_dataset='merged_pdbbind_dudez', selected_features_source='reduction_protocol', reduction_archive=None, n_selected_features=None, notes=None)[source]

Scope recorded by the reduce CLI only; not valid for staged train.

Parameters:

  • fit_dataset (str)

  • selected_features_source (Literal['externally_supplied', 'reduction_protocol', 'train_derived'])

  • reduction_archive (str | None)

  • n_selected_features (int | None)

  • notes (Sequence[str] | None)

Return type:

FeatureSelectionScope

classmethod train_only(*, fit_dataset='pdbbind_train', fit_split='train', fit_row_count, fit_row_indices=None, selected_features, removed_features=None, transform_artifacts=None, feature_selection_mode='production-strict', notes=None)[source]

Scope for train-only feature reduction after an outer split.

Parameters:

  • fit_dataset (str)

  • fit_split (str)

  • fit_row_count (int)

  • fit_row_indices (list[int] | None)

  • selected_features (Sequence[str])

  • removed_features (Sequence[str] | None)

  • transform_artifacts (Sequence[str] | None)

  • feature_selection_mode (Literal['production-strict', 'external-blind'])

  • notes (Sequence[str] | None)

Return type:

FeatureSelectionScope

OCDocker.OCScore.Utils.FeatureSelectionMetadata.attach_feature_hashes(scope, *, selected_features=None, removed_features=None)[source]

Return a copy of scope with feature-list hashes populated.

Parameters:

  • scope (FeatureSelectionScope)

  • selected_features (Sequence[str] | None)

  • removed_features (Sequence[str] | None)

Return type:

FeatureSelectionScope

OCDocker.OCScore.Utils.FeatureSelectionMetadata.load_feature_selection_json(source)[source]

Load feature-selection scope from a directory or JSON file.

Parameters:

source (str | Path)

Return type:

FeatureSelectionScope

OCDocker.OCScore.Utils.FeatureSelectionMetadata.validate_train_only_feature_selection(scope)[source]

Validate that feature selection metadata is train-only and reproducible.

Parameters:

scope (FeatureSelectionScope)

Return type:

None

OCDocker.OCScore.Utils.FeatureSelectionMetadata.verify_selected_features_against_scope(selected_features, scope)[source]

Verify that selected_features matches saved scope metadata.

Parameters:
Return type:

None

OCDocker.OCScore.Utils.FeatureSelectionMetadata.write_feature_selection_fit_rows_json(output_dir, scope, filename='feature_selection_fit_rows.json')[source]

Write full train-only fit-row indices as a separate audit artifact.

Parameters:
Return type:

Path

OCDocker.OCScore.Utils.FeatureSelectionMetadata.write_feature_selection_json(output_dir, scope, filename='feature_selection.json')[source]

Write feature_selection.json to output_dir.

Parameters:
Return type:

Path