OCDocker.OCScore.Utils.FeatureReduction module¶

Granular feature-reduction utilities for OCScore descriptor datasets. The module keeps core behavior in reusable functions and dataclasses; the run_feature_reduction_protocol helper only orchestrates those functions.

API Surface¶

The public surface is intentionally limited to descriptor block handling, missing-row filtering, column-quality filters, correlation diagnostics, result composition, protocol generation, and output writing. Thin wrappers that only expose one branch of another function’s behavior are kept private; for example, pattern-only block detection is handled by split_descriptor_blocks with the metadata flags disabled instead of a second public function. Existing OCScore training, DNN, autoencoder, and downstream metric code is not rewired to call this module automatically. Training pipelines can consume the selected feature list later.

The documented public function surface is:

validate_descriptor_frame
split_descriptor_blocks and summarize_blocks
drop_rows_with_missing_values
find_constant_features, find_near_constant_features, find_duplicate_features, and apply_feature_drops
compute_intra_block_correlations and filter_correlated_features
compute_cross_block_correlations, compute_cross_block_predictability, and filter_cross_block_redundant_features
compose_selected_features and build_reduced_dataframe
build_feature_reduction_protocol and write_feature_reduction_outputs
run_feature_reduction_protocol

Rewiring Notes¶

OCDocker.OCScore.Utils.IO.load_data is not changed because it currently drops rows with missing values before detailed row-level reporting. The new orchestration helper uses raw pandas.read_csv when an input path is supplied, so missing-row removal can be reported reproducibly.
Ligand and receptor descriptor metadata are read from Ligand.allDescriptors and Receptor.allDescriptors when those classes can be imported. Pattern matching remains the fallback.
Scoring descriptors use Complexes.allDescriptors when available and fall back to configurable scoring-function prefixes.
Cross-block filtering is disabled by default. Cross-block diagnostics do not drop features unless filtering is explicitly enabled.

Versioning Notes¶

This is an additive API module. It does not remove or change existing public behavior. A minor version bump is appropriate if this API is released as a new feature; a patch version is only appropriate if it remains internal or undocumented.

API Reference¶

Configuration and result classes¶

class OCDocker.OCScore.Utils.FeatureReduction.DescriptorBlocks(receptor=<factory>, ligand=<factory>, scoring=<factory>, metadata=<factory>, target=<factory>, unmatched=<factory>, duplicate_assignments=<factory>, sources=<factory>)[source]

Bases: object

Descriptor columns split into conceptual blocks.

Parameters:

receptor (list[str]) – Receptor molecular descriptor columns.
ligand (list[str]) – Ligand molecular descriptor columns.
scoring (list[str]) – Scoring-function descriptor columns.
metadata (list[str]) – Metadata columns preserved in reduced outputs.
target (list[str]) – Target columns preserved in reduced outputs.
unmatched (list[str]) – Non-metadata, non-target columns that were not assigned to a block.
duplicate_assignments (dict[str, list[str]]) – Columns that matched more than one descriptor block.
sources (dict[str, str]) – Detection source used for each descriptor block.

receptor: List[str]

ligand: List[str]

scoring: List[str]

metadata: List[str]

target: List[str]

unmatched: List[str]

duplicate_assignments: Dict[str, List[str]]

sources: Dict[str, str]

property all_descriptor_columns: List[str]

Return all descriptor columns in receptor, ligand, scoring order.

Returns:: Descriptor columns from receptor, ligand, and scoring blocks.
Return type:: list[str]

property all_model_columns: List[str]

Return target plus all descriptor columns, preserving order.

Returns:: Target columns followed by descriptor columns.
Return type:: list[str]

items()[source]

Iterate over descriptor block names and columns.

Returns:: Iterator over (block_name, columns) pairs for receptor, ligand, and scoring blocks.
Return type:: Iterator[tuple[str, list[str]]]

class OCDocker.OCScore.Utils.FeatureReduction.BlockDetectionConfig(metadata_columns=<factory>, target_columns=<factory>, receptor_patterns=<factory>, ligand_patterns=<factory>, scoring_patterns=<factory>, use_ligand_class_descriptors=True, use_receptor_class_descriptors=True, use_scoring_model_descriptors=True)[source]

Bases: object

Configuration for descriptor block detection.

Parameters:

metadata_columns (list[str]) – Candidate metadata columns to preserve.
target_columns (list[str]) – Candidate target columns to preserve and optionally include in missing-row checks.
receptor_patterns (list[str]) – Prefixes used as a receptor descriptor fallback.
ligand_patterns (list[str]) – Prefixes used as a ligand descriptor fallback.
scoring_patterns (list[str]) – Prefixes used as a scoring-function descriptor fallback.
use_ligand_class_descriptors (bool) – If True, use Ligand.allDescriptors when available.
use_receptor_class_descriptors (bool) – If True, use Receptor.allDescriptors when available.
use_scoring_model_descriptors (bool) – If True, use Complexes.allDescriptors when available.

metadata_columns: List[str]

target_columns: List[str]

receptor_patterns: List[str]

ligand_patterns: List[str]

scoring_patterns: List[str]

use_ligand_class_descriptors: bool = True

use_receptor_class_descriptors: bool = True

use_scoring_model_descriptors: bool = True

class OCDocker.OCScore.Utils.FeatureReduction.MissingRowsConfig(enabled=True, subset='model_relevant_columns', preserve_index=True)[source]

Bases: object

Configuration for missing-row filtering.

Parameters:

enabled (bool) – If True, remove rows with missing values before feature reduction.
subset (str) – Column subset checked for missing values.
preserve_index (bool) – If True, keep the original DataFrame index in the cleaned DataFrame.

enabled: bool = True

subset: str = 'model_relevant_columns'

preserve_index: bool = True

class OCDocker.OCScore.Utils.FeatureReduction.ColumnQualityConfig(remove_constant=True, remove_near_constant=True, near_constant_threshold=0.995, remove_duplicates=True)[source]

Bases: object

Configuration for block-wise column-quality filters.

Parameters:

remove_constant (bool) – If True, remove columns with a single unique value.
remove_near_constant (bool) – If True, remove columns dominated by one value.
near_constant_threshold (float) – Fraction above which a dominant value marks a feature as near-constant.
remove_duplicates (bool) – If True, remove exact duplicate numeric columns.

remove_constant: bool = True

remove_near_constant: bool = True

near_constant_threshold: float = 0.995

remove_duplicates: bool = True

class OCDocker.OCScore.Utils.FeatureReduction.IntraBlockCorrelationConfig(method='spearman', receptor_threshold=0.98, ligand_threshold=0.98, scoring_threshold=0.99, retention_policy='first')[source]

Bases: object

Configuration for intra-block correlation filtering.

Parameters:

method (str) – Correlation method passed to pandas.DataFrame.corr.
receptor_threshold (float) – Absolute correlation threshold for receptor descriptors.
ligand_threshold (float) – Absolute correlation threshold for ligand descriptors.
scoring_threshold (float) – Absolute correlation threshold for scoring-function descriptors.
retention_policy (str) – Deterministic policy used to keep one feature from a correlated pair.

method: str = 'spearman'

receptor_threshold: float = 0.98

ligand_threshold: float = 0.98

scoring_threshold: float = 0.99

retention_policy: str = 'first'

threshold_for_block(block_name)[source]

Return the configured threshold for a descriptor block.

Parameters:: block_name (str) – Descriptor block name. Must be "receptor", "ligand", or "scoring".
Returns:: Correlation threshold configured for the descriptor block.
Return type:: float
Raises:: ValueError – If block_name is not a known descriptor block.

class OCDocker.OCScore.Utils.FeatureReduction.CrossBlockDiagnosticsConfig(enabled=True, correlation_threshold=0.95, ridge_cv_folds=5, random_seed=42, n_jobs=1)[source]

Bases: object

Configuration for cross-block diagnostics.

Parameters:

enabled (bool) – If True, compute cross-block diagnostics after intra-block filtering.
correlation_threshold (float) – Absolute pairwise correlation threshold used to flag cross-block pairs.
ridge_cv_folds (int) – Requested number of folds for Ridge CV predictability diagnostics.
random_seed (int) – Seed used for deterministic cross-validation splits.
n_jobs (int) – Number of parallel jobs for Ridge CV predictability diagnostics. Use 1 for serial execution or -1 for all available cores.

enabled: bool = True

correlation_threshold: float = 0.95

ridge_cv_folds: int = 5

random_seed: int = 42

n_jobs: int = 1

class OCDocker.OCScore.Utils.FeatureReduction.CrossBlockFilteringConfig(enabled=False, scoring_function_priority=False)[source]

Bases: object

Configuration for optional conservative cross-block filtering.

Parameters:

enabled (bool) – If True, run conservative cross-block filtering.
scoring_function_priority (bool) – If True, scoring-function descriptors may be preferred over strongly correlated molecular descriptors.

enabled: bool = False

scoring_function_priority: bool = False

class OCDocker.OCScore.Utils.FeatureReduction.FeatureReductionConfig(block_detection=<factory>, missing_rows=<factory>, column_quality=<factory>, intra_block_correlation=<factory>, cross_block_diagnostics=<factory>, cross_block_filtering=<factory>, verbose=False)[source]

Bases: object

Configuration for the convenience feature-reduction orchestration helper.

Parameters:

block_detection (BlockDetectionConfig) – Descriptor block detection settings.
missing_rows (MissingRowsConfig) – Missing-row filtering settings.
column_quality (ColumnQualityConfig) – Constant, near-constant, and duplicate-column filtering settings.
intra_block_correlation (IntraBlockCorrelationConfig) – Intra-block correlation filtering settings.
cross_block_diagnostics (CrossBlockDiagnosticsConfig) – Cross-block diagnostic settings.
cross_block_filtering (CrossBlockFilteringConfig) – Optional cross-block filtering settings.
verbose (bool) – If True, emit step-level orchestration progress messages.

block_detection: BlockDetectionConfig

missing_rows: MissingRowsConfig

column_quality: ColumnQualityConfig

intra_block_correlation: IntraBlockCorrelationConfig

cross_block_diagnostics: CrossBlockDiagnosticsConfig

cross_block_filtering: CrossBlockFilteringConfig

verbose: bool = False

class OCDocker.OCScore.Utils.FeatureReduction.MissingRowsResult(cleaned_df, dropped_rows, missingness_by_column, missingness_by_block, summary)[source]

Bases: object

Result from missing-row filtering.

Parameters:

cleaned_df (pd.DataFrame) – DataFrame after rows with missing values were removed.
dropped_rows (pd.DataFrame) – Per-row report with original index, IDs, missing columns, and reason.
missingness_by_column (pd.DataFrame) – Missing-value counts and fractions by checked column.
missingness_by_block (pd.DataFrame) – Missing-value counts by descriptor block and target block.
summary (dict[str, Any]) – Reproducibility summary of the row-filtering operation.

cleaned_df: DataFrame

dropped_rows: DataFrame

missingness_by_column: DataFrame

missingness_by_block: DataFrame

summary: Dict[str, Any]

class OCDocker.OCScore.Utils.FeatureReduction.CorrelationReport(matrix, pairs, method, block='', threshold=None)[source]

Bases: object

Correlation matrix and long-form pairwise report.

Parameters:

matrix (pd.DataFrame) – Square correlation matrix.
pairs (pd.DataFrame) – Long-form upper-triangle correlation report.
method (str) – Correlation method used.
block (str) – Descriptor block name.
threshold (float, optional) – Threshold used to flag correlated pairs.

matrix: DataFrame

pairs: DataFrame

method: str

block: str = ''

threshold: float | None = None

class OCDocker.OCScore.Utils.FeatureReduction.CorrelationFilterResult(kept_features, dropped_features, report)[source]

Bases: object

Result from deterministic correlated-feature filtering.

Parameters:

kept_features (list[str]) – Feature columns retained after filtering.
dropped_features (list[str]) – Feature columns removed by the filter.
report (pd.DataFrame) – Per-feature drop report.

kept_features: List[str]

dropped_features: List[str]

report: DataFrame

class OCDocker.OCScore.Utils.FeatureReduction.CrossBlockFilterResult(kept_features, dropped_features, report)[source]

Bases: object

Result from optional conservative cross-block filtering.

Parameters:

kept_features (list[str]) – Molecular descriptor columns retained after filtering.
dropped_features (list[str]) – Molecular descriptor columns removed by the filter.
report (pd.DataFrame) – Cross-block filtering report.

kept_features: List[str]

dropped_features: List[str]

report: DataFrame

class OCDocker.OCScore.Utils.FeatureReduction.FeatureReductionResult(reduced_df, selected_features, blocks, cleaned_blocks, missing_result, protocol, reports, output_paths=<factory>)[source]

Bases: object

Result from the convenience orchestration helper.

Parameters:

reduced_df (pd.DataFrame) – Reduced dataset containing metadata, targets, and selected features.
selected_features (list[str]) – Final selected descriptor columns.
blocks (DescriptorBlocks) – Descriptor block assignments detected from the input dataset.
cleaned_blocks (dict[str, list[str]]) – Final retained columns by descriptor block.
missing_result (MissingRowsResult) – Missing-row filtering result.
protocol (dict[str, Any]) – JSON-serializable reproducibility protocol.
reports (dict[str, pd.DataFrame]) – Report tables generated by the workflow.
output_paths (dict[str, str]) – Paths written by write_feature_reduction_outputs.

reduced_df: DataFrame

selected_features: List[str]

blocks: DescriptorBlocks

cleaned_blocks: Dict[str, List[str]]

missing_result: MissingRowsResult

protocol: Dict[str, Any]

reports: Dict[str, DataFrame]

output_paths: Dict[str, str]

Public functions¶

OCDocker.OCScore.Utils.FeatureReduction.validate_descriptor_frame(df, descriptor_columns, allow_nan=False, allow_inf=False)[source]¶

Validate descriptor columns for existence, numeric dtype, NaN, and inf.

Parameters:

df (pd.DataFrame) – DataFrame containing descriptor columns.
descriptor_columns (Sequence[str]) – Descriptor columns to validate.
allow_nan (bool, optional) – If True, allow NaN values, by default False.
allow_inf (bool, optional) – If True, allow positive or negative infinite values, by default False.

Return type:

None

Raises:

ValueError – If no descriptors are provided, a column is missing, a descriptor is non-numeric, or forbidden NaN/inf values are present.

OCDocker.OCScore.Utils.FeatureReduction.split_descriptor_blocks(columns, metadata_columns=None, target_columns=None, receptor_patterns=None, ligand_patterns=None, scoring_patterns=None, use_ligand_class_descriptors=True, use_receptor_class_descriptors=True, use_scoring_model_descriptors=True)[source]¶

Split dataset columns into receptor, ligand, scoring, metadata, and target blocks.

Parameters:

columns (Sequence[str]) – Dataset columns to classify.
metadata_columns (Sequence[str], optional) – Metadata column names to preserve. If None, OCDocker defaults are used.
target_columns (Sequence[str], optional) – Target column names to preserve. If None, OCDocker defaults are used.
receptor_patterns (Sequence[str], optional) – Prefixes used to detect receptor descriptors by name.
ligand_patterns (Sequence[str], optional) – Prefixes used to detect ligand descriptors by name.
scoring_patterns (Sequence[str], optional) – Prefixes used to detect scoring-function descriptors by name.
use_ligand_class_descriptors (bool, optional) – If True, use Ligand.allDescriptors before pattern fallback.
use_receptor_class_descriptors (bool, optional) – If True, use Receptor.allDescriptors before pattern fallback.
use_scoring_model_descriptors (bool, optional) – If True, use Complexes.allDescriptors before pattern fallback.

Returns:

Column assignments, unmatched columns, duplicate assignments, and descriptor-source metadata.

Return type:

DescriptorBlocks

OCDocker.OCScore.Utils.FeatureReduction.summarize_blocks(blocks)[source]¶

Build a compact block summary table.

Parameters:: blocks (DescriptorBlocks) – Descriptor block assignments to summarize.
Returns:: Table with block name, number of columns, detection source, and columns.
Return type:: pd.DataFrame

OCDocker.OCScore.Utils.FeatureReduction.drop_rows_with_missing_values(df, columns=None, subset='model_relevant_columns', descriptor_columns=None, target_columns=None, blocks=None, id_columns=None, preserve_index=True, return_report=True)[source]¶

Drop rows with missing values and return a full row-removal report.

Parameters:

df (pd.DataFrame) – Input dataset. The input DataFrame is not mutated.
columns (Sequence[str], optional) – Explicit columns to check. When provided, subset and block-derived columns are ignored.
subset (str, optional) – Logical subset to check. Supported values are "model_relevant_columns", "descriptor_columns", "descriptor_and_target_columns", and "all_columns".
descriptor_columns (Sequence[str], optional) – Descriptor columns used when blocks and columns are not provided.
target_columns (Sequence[str], optional) – Target columns used when blocks and columns are not provided.
blocks (DescriptorBlocks, optional) – Descriptor block assignments used to resolve model-relevant columns and block-level missingness.
id_columns (Sequence[str], optional) – Identifier columns copied into the dropped-row report when present.
preserve_index (bool, optional) – If True, preserve the original DataFrame index in cleaned_df.
return_report (bool, optional) – Kept for API readability. Reports are always returned to avoid silent row removal.

Returns:

Cleaned DataFrame, dropped-row report, missingness summaries, and row filtering summary.

Return type:

MissingRowsResult

Raises:

ValueError – If the requested missing-value columns are not present.

OCDocker.OCScore.Utils.FeatureReduction.find_constant_features(df, columns, block='')[source]¶

Find columns with exactly one unique value.

Parameters:

df (pd.DataFrame) – DataFrame containing feature columns.
columns (Sequence[str]) – Feature columns to inspect.
block (str, optional) – Descriptor block name stored in the report.

Returns:

Drop report for constant columns. Empty when no columns are constant.

Return type:

pd.DataFrame

OCDocker.OCScore.Utils.FeatureReduction.find_near_constant_features(df, columns, threshold=0.995, block='')[source]¶

Find columns where one value accounts for more than threshold rows.

Parameters:

df (pd.DataFrame) – DataFrame containing feature columns.
columns (Sequence[str]) – Feature columns to inspect.
threshold (float, optional) – Dominant-value fraction above which a feature is near-constant.
block (str, optional) – Descriptor block name stored in the report.

Returns:

Drop report for near-constant columns. Empty when none are found.

Return type:

pd.DataFrame

Raises:

ValueError – If threshold is not in the interval (0, 1].

OCDocker.OCScore.Utils.FeatureReduction.find_duplicate_features(df, columns, block='')[source]¶

Find exact duplicate columns and keep the first stable representative.

Parameters:

df (pd.DataFrame) – DataFrame containing numeric feature columns.
columns (Sequence[str]) – Feature columns to inspect in retention order.
block (str, optional) – Descriptor block name stored in the report.

Returns:

Drop report with kept and dropped duplicate features.

Return type:

pd.DataFrame

Raises:

ValueError – If any requested column is missing or non-numeric.

OCDocker.OCScore.Utils.FeatureReduction.apply_feature_drops(columns, dropped_features)[source]¶

Return columns after dropping requested features, preserving order.

Parameters:

columns (Sequence[str]) – Original feature columns.
dropped_features (pd.DataFrame or Sequence[str] or pd.Series) – Features to remove. DataFrames may contain dropped_feature, feature, or molecular_feature columns.

Returns:

Columns remaining after dropping requested features.

Return type:

list[str]

OCDocker.OCScore.Utils.FeatureReduction.compute_intra_block_correlations(df, columns, method='spearman', threshold=None, block='')[source]¶

Compute intra-block correlations as a matrix and long-form pair report.

Parameters:

df (pd.DataFrame) – DataFrame containing numeric feature columns.
columns (Sequence[str]) – Block-specific feature columns.
method (str, optional) – Correlation method passed to pandas.DataFrame.corr.
threshold (float, optional) – Optional threshold used to flag pairs in the long-form report.
block (str, optional) – Descriptor block name stored in the report.

Returns:

Correlation matrix and pairwise upper-triangle report.

Return type:

CorrelationReport

OCDocker.OCScore.Utils.FeatureReduction.filter_correlated_features(corr_report, threshold, retention_policy='first')[source]¶

Filter correlated features deterministically from a pairwise correlation report.

Parameters:

corr_report (CorrelationReport or pd.DataFrame) – Correlation report returned by compute_intra_block_correlations or a compatible DataFrame.
threshold (float) – Absolute correlation threshold above which a feature is dropped.
retention_policy (str, optional) – Feature retention policy. Currently only "first" is supported.

Returns:

Kept features, dropped features, and the filtering report.

Return type:

CorrelationFilterResult

Raises:

ValueError – If threshold is invalid, the retention policy is unsupported, or the report lacks required columns.

OCDocker.OCScore.Utils.FeatureReduction.compute_cross_block_correlations(df, left_columns, right_columns, method='spearman', threshold=0.95, left_block='left', right_block='right')[source]¶

Compute pairwise cross-block correlations and flag values above threshold.

Parameters:

df (pd.DataFrame) – DataFrame containing both descriptor blocks.
left_columns (Sequence[str]) – Columns from the left descriptor block.
right_columns (Sequence[str]) – Columns from the right descriptor block.
method (str, optional) – Correlation method passed to pandas.DataFrame.corr.
threshold (float, optional) – Absolute correlation threshold used to flag pairs.
left_block (str, optional) – Name stored for the left descriptor block.
right_block (str, optional) – Name stored for the right descriptor block.

Returns:

Pairwise cross-block correlation report. Empty when either block is empty.

Return type:

pd.DataFrame

Raises:

ValueError – If requested columns are missing or non-numeric.

OCDocker.OCScore.Utils.FeatureReduction.compute_cross_block_predictability(df, predictor_columns, target_columns, model='ridge', cv_folds=5, random_seed=42, n_jobs=1, predictor_block='predictor', target_block='scoring')[source]¶

Estimate how predictable target columns are from predictor columns using CV R2.

Parameters:

df (pd.DataFrame) – DataFrame containing predictors and targets.
predictor_columns (Sequence[str]) – Numeric columns used as Ridge predictors.
target_columns (Sequence[str]) – Numeric target columns predicted one at a time.
model (str, optional) – Predictability model. Currently only "ridge" is supported.
cv_folds (int, optional) – Requested number of cross-validation folds.
random_seed (int, optional) – Seed used for deterministic KFold shuffling.
n_jobs (int, optional) – Number of parallel jobs passed to sklearn.model_selection.cross_val_score. Use 1 for serial execution or -1 for all available cores.
predictor_block (str, optional) – Predictor block name stored in the report.
target_block (str, optional) – Target block name stored in the report.

Returns:

CV R2 report with mean, standard deviation, number of predictors, and redundancy interpretation. Empty when predictors or targets are empty.

Return type:

pd.DataFrame

Raises:

ValueError – If the model is unsupported, folds are invalid, data are too small, or requested columns are missing or non-numeric.

OCDocker.OCScore.Utils.FeatureReduction.filter_cross_block_redundant_features(cross_corr_report, molecular_columns, scoring_columns, threshold=0.95, scoring_function_priority=False)[source]¶

Optionally drop molecular descriptors correlated with scoring functions.

Parameters:

cross_corr_report (pd.DataFrame) – Cross-block pairwise correlation report.
molecular_columns (Sequence[str]) – Molecular descriptor columns eligible for removal.
scoring_columns (Sequence[str]) – Scoring-function descriptor columns that may be prioritized.
threshold (float, optional) – Absolute correlation threshold required for removal.
scoring_function_priority (bool, optional) – If False, no features are removed. If True, strongly correlated molecular descriptors may be dropped.

Returns:

Kept molecular descriptors, dropped descriptors, and filtering report.

Return type:

CrossBlockFilterResult

Raises:

ValueError – If the correlation report lacks required columns.

OCDocker.OCScore.Utils.FeatureReduction.compose_selected_features(receptor_columns, ligand_columns, scoring_columns)[source]¶

Compose final selected feature names in receptor, ligand, scoring order.

Parameters:

receptor_columns (Sequence[str]) – Retained receptor descriptor columns.
ligand_columns (Sequence[str]) – Retained ligand descriptor columns.
scoring_columns (Sequence[str]) – Retained scoring-function descriptor columns.

Returns:

Unique selected features, preserving receptor, ligand, then scoring order.

Return type:

list[str]

OCDocker.OCScore.Utils.FeatureReduction.build_reduced_dataframe(df, metadata_columns=None, target_columns=None, selected_features=None)[source]¶

Build a reduced DataFrame with metadata, target, and selected features.

Parameters:

df (pd.DataFrame) – Source DataFrame. The input is not mutated.
metadata_columns (Sequence[str], optional) – Metadata columns to retain.
target_columns (Sequence[str], optional) – Target columns to retain.
selected_features (Sequence[str], optional) – Selected descriptor columns to retain.

Returns:

Copy of the reduced DataFrame in metadata, target, feature order.

Return type:

pd.DataFrame

Raises:

ValueError – If any requested column is missing.

OCDocker.OCScore.Utils.FeatureReduction.build_feature_reduction_protocol(config, blocks, missing_result, cleaned_blocks, selected_features, reduced_df, input_path=None, input_shape=None, block_summary=None, dropped_features=None, intra_block_correlation_report=None, cross_block_pairwise_correlation_report=None, cross_block_predictability_report=None, cross_block_filter_report=None, output_paths=None, warnings=None)[source]¶

Build a JSON-serializable reproducibility protocol for feature reduction.

Parameters:

config (FeatureReductionConfig) – Configuration used for the run.
blocks (DescriptorBlocks) – Descriptor block assignments detected from the input dataset.
missing_result (MissingRowsResult) – Missing-row filtering result.
cleaned_blocks (Mapping[str, Sequence[str]]) – Final retained columns by descriptor block.
selected_features (Sequence[str]) – Final selected descriptor columns.
reduced_df (pd.DataFrame) – Reduced dataset.
input_path (str, optional) – Input file path when data were loaded from disk.
input_shape (tuple[int, int], optional) – Shape of the raw input dataset.
block_summary (pd.DataFrame, optional) – Block summary report.
dropped_features (pd.DataFrame, optional) – Feature-drop report.
intra_block_correlation_report (pd.DataFrame, optional) – Intra-block pairwise correlation report.
cross_block_pairwise_correlation_report (pd.DataFrame, optional) – Cross-block pairwise correlation report.
cross_block_predictability_report (pd.DataFrame, optional) – Ridge CV predictability report.
cross_block_filter_report (pd.DataFrame, optional) – Optional cross-block filtering report.
output_paths (Mapping[str, str], optional) – Output paths already written by an orchestration layer.
warnings (Sequence[str], optional) – Warning messages to embed in the protocol.

Returns:

JSON-serializable reproducibility protocol.

Return type:

dict[str, Any]

OCDocker.OCScore.Utils.FeatureReduction.write_feature_reduction_outputs(output_dir, reduced_df, selected_features, protocol, missing_result=None, block_summary=None, dropped_features=None, intra_block_correlation_report=None, cross_block_pairwise_correlation_report=None, cross_block_predictability_report=None, cross_block_filter_report=None, config=None, write_markdown=True)[source]¶

Write reduced dataset, reports, config, and protocol files with stable names.

Parameters:

output_dir (str or pathlib.Path) – Directory where output files are written.
reduced_df (pd.DataFrame) – Reduced dataset to write as reduced_dataset.csv.
selected_features (Sequence[str]) – Selected features written as JSON and text.
protocol (Mapping[str, Any]) – Reproducibility protocol to write as JSON and optionally Markdown.
missing_result (MissingRowsResult, optional) – Missing-row result used to write row-filtering reports.
block_summary (pd.DataFrame, optional) – Block summary report.
dropped_features (pd.DataFrame, optional) – Feature-drop report.
intra_block_correlation_report (pd.DataFrame, optional) – Intra-block pairwise correlation report.
cross_block_pairwise_correlation_report (pd.DataFrame, optional) – Cross-block pairwise correlation report.
cross_block_predictability_report (pd.DataFrame, optional) – Ridge CV predictability report.
cross_block_filter_report (pd.DataFrame, optional) – Optional cross-block filtering report.
config (FeatureReductionConfig, optional) – Configuration written to config_used.json.
write_markdown (bool, optional) – If True, also write feature_reduction_protocol.md.

Returns:

Mapping from output artifact names to written file paths.

Return type:

dict[str, str]

OCDocker.OCScore.Utils.FeatureReduction.run_feature_reduction_protocol(df=None, input_path=None, output_dir=None, config=None, write_outputs=False)[source]¶

Convenience orchestration over the granular feature-reduction API.

Parameters:

df (pd.DataFrame, optional) – Input dataset. The DataFrame is copied before processing.
input_path (str or pathlib.Path, optional) – CSV file to load when df is not provided. Raw pandas.read_csv is used so missing rows can be reported before removal.
output_dir (str or pathlib.Path, optional) – Directory where reports are written when write_outputs is True.
config (FeatureReductionConfig, optional) – Run configuration. If None, scientific defaults are used.
write_outputs (bool, optional) – If True, write reduced data, reports, and protocol files.

Returns:

Reduced dataset, selected features, descriptor blocks, reports, protocol, and output paths.

Return type:

FeatureReductionResult

Raises:

ValueError – If input arguments are inconsistent, no descriptors are detected, or output writing is requested without output_dir.