Wave 5.2 MMT Residual-Explanatory Diagnostic

Build the Wave 5.2 MMT residual-explanatory diagnostic.

This script audits the exact dataset split used by the selected polished setpoint baselines, joins that provenance to existing per-curve residual metrics, materializes leakage-safe MMT signatures, and runs transparent least-squares comparisons only when training residual rows are available.

The diagnostic is intentionally non-training. It must not create campaign state, update registries, or fit explanatory coefficients on validation or test targets.

class scripts.reports.analysis.build_wave52_mmt_residual_explanatory_diagnostic.BaselineSpecification(candidate_id, surface, direction_label, architecture_class, registry_path, reference_inventory_path)

Bases: object

Describe one selected baseline and its provenance surfaces.

Parameters:

• candidate_id (str)

• surface (str)

• direction_label (str)

• architecture_class (str)

• registry_path (Path)

• reference_inventory_path (Path)

candidate_id

Candidate identifier used by curve-verification outputs.

Type:

str

surface

Directional project surface label.

Type:

str

direction_label

Dataset direction label.

Type:

str

architecture_class

Windowed or non-windowed comparison class.

Type:

str

registry_path

Dataset-scoped family registry.

Type:

pathlib.Path

reference_inventory_path

Archived model reference inventory.

Type:

pathlib.Path

candidate_id: str

surface: str

direction_label: str

architecture_class: str

registry_path: Path

reference_inventory_path: Path

class scripts.reports.analysis.build_wave52_mmt_residual_explanatory_diagnostic.LinearFitResult(coefficient_vector, matrix_rank, train_mae, evaluation_mae, evaluation_r_squared)

Bases: object

Store one transparent held-out linear-fit result.

Parameters:

• coefficient_vector (ndarray)

• matrix_rank (int)

• train_mae (float)

• evaluation_mae (float)

• evaluation_r_squared (float)

coefficient_vector

Fitted intercept and standardized coefficients.

Type:

numpy.ndarray

matrix_rank

Least-squares design-matrix rank.

Type:

int

train_mae

Mean absolute error on the fit split.

Type:

float

evaluation_mae

Mean absolute error on the evaluation split.

Type:

float

evaluation_r_squared

Held-out coefficient of determination.

Type:

float

coefficient_vector: ndarray

matrix_rank: int

train_mae: float

evaluation_mae: float

evaluation_r_squared: float

scripts.reports.analysis.build_wave52_mmt_residual_explanatory_diagnostic.parse_command_line_arguments()

Parse command-line arguments for the diagnostic builder.

Return type:

Namespace

scripts.reports.analysis.build_wave52_mmt_residual_explanatory_diagnostic.resolve_project_path(path_value)

Resolve a repository-relative or absolute path.

Parameters:

path_value (str | Path)

Return type:

Path

scripts.reports.analysis.build_wave52_mmt_residual_explanatory_diagnostic.format_project_path(path_value)

Format one path relative to the repository when possible.

Parameters:

path_value (str | Path)

Return type:

str

scripts.reports.analysis.build_wave52_mmt_residual_explanatory_diagnostic.format_float(value)

Format one optional numerical value for stable CSV output.

Parameters:

value (float | int | str | None)

Return type:

str

scripts.reports.analysis.build_wave52_mmt_residual_explanatory_diagnostic.load_yaml_dictionary(path_value)

Load one YAML file and require a dictionary root.

Parameters:

path_value (str | Path)

Return type:

dict[str, Any]

scripts.reports.analysis.build_wave52_mmt_residual_explanatory_diagnostic.write_yaml(path_value, payload)

Write a stable YAML dictionary.

Parameters:

• path_value (str | Path)

• payload (dict[str, Any])

Return type:

Path

scripts.reports.analysis.build_wave52_mmt_residual_explanatory_diagnostic.write_json(path_value, payload)

Write one readable JSON dictionary.

Parameters:

• path_value (str | Path)

• payload (dict[str, Any])

Return type:

Path

scripts.reports.analysis.build_wave52_mmt_residual_explanatory_diagnostic.write_csv(path_value, row_list)

Write a non-empty dictionary row list to CSV.

Parameters:

• path_value (str | Path)

• row_list (list[dict[str, Any]])

Return type:

Path

scripts.reports.analysis.build_wave52_mmt_residual_explanatory_diagnostic.load_config(config_path)

Load and validate the diagnostic configuration.

Parameters:

config_path (Path)

Return type:

dict[str, Any]

scripts.reports.analysis.build_wave52_mmt_residual_explanatory_diagnostic.build_baseline_specification_list(config_dictionary)

Build strongly typed baseline specifications from configuration.

Parameters:

config_dictionary (dict[str, Any])

Return type:

list[BaselineSpecification]

scripts.reports.analysis.build_wave52_mmt_residual_explanatory_diagnostic.build_dataset_split_lookup(dataset_root, validation_split, test_split, random_seed)

Reconstruct the repository file-level split without importing training.

The implementation mirrors scripts.datasets.transmission_error_dataset.split_directional_file_manifest: sorted unique CSV paths are shuffled by random.Random and the validation and test prefixes are selected from that deterministic list.

Parameters:

• dataset_root (Path)

• validation_split (float)

• test_split (float)

• random_seed (int)

Return type:

tuple[dict[str, str], dict[str, int]]

scripts.reports.analysis.build_wave52_mmt_residual_explanatory_diagnostic.load_selected_residual_row_list(residual_metrics_path, baseline_specification_list, split_lookup, residual_target_name_list)

Load selected baseline residual rows with authoritative split labels.

Parameters:

• residual_metrics_path (Path)

• baseline_specification_list (list[BaselineSpecification])

• split_lookup (dict[str, str] | None)

• residual_target_name_list (list[str])

Return type:

list[dict[str, Any]]

scripts.reports.analysis.build_wave52_mmt_residual_explanatory_diagnostic.build_split_count_dictionary_from_residual_rows(residual_row_list)

Count unique dataset files using replay-provided split membership.

Parameters:

residual_row_list (list[dict[str, Any]])

Return type:

dict[str, int]

scripts.reports.analysis.build_wave52_mmt_residual_explanatory_diagnostic.build_baseline_manifest_row_list(baseline_specification_list)

Resolve registry and archived-model provenance for each baseline.

Parameters:

baseline_specification_list (list[BaselineSpecification])

Return type:

list[dict[str, Any]]

scripts.reports.analysis.build_wave52_mmt_residual_explanatory_diagnostic.build_split_audit_row_list(residual_row_list)

Build per-candidate split coverage rows.

Parameters:

residual_row_list (list[dict[str, Any]])

Return type:

list[dict[str, Any]]

scripts.reports.analysis.build_wave52_mmt_residual_explanatory_diagnostic.build_mmt_signature_row_list(config_dictionary)

Materialize the current geometry-locked MMT signature inventory.

Parameters:

config_dictionary (dict[str, Any])

Return type:

list[dict[str, Any]]

scripts.reports.analysis.build_wave52_mmt_residual_explanatory_diagnostic.build_descriptive_summary_row_list(residual_row_list, residual_target_name_list)

Summarize residual targets without fitting on held-out data.

Parameters:

• residual_row_list (list[dict[str, Any]])

• residual_target_name_list (list[str])

Return type:

list[dict[str, Any]]

scripts.reports.analysis.build_wave52_mmt_residual_explanatory_diagnostic.standardize_matrix_from_training(training_matrix, evaluation_matrix)

Standardize feature matrices with training statistics only.

Parameters:

• training_matrix (ndarray)

• evaluation_matrix (ndarray)

Return type:

tuple[ndarray, ndarray]

scripts.reports.analysis.build_wave52_mmt_residual_explanatory_diagnostic.compute_r_squared(target_vector, prediction_vector)

Compute a finite coefficient of determination.

Parameters:

• target_vector (ndarray)

• prediction_vector (ndarray)

Return type:

float

scripts.reports.analysis.build_wave52_mmt_residual_explanatory_diagnostic.fit_transparent_linear_model(training_feature_matrix, training_target_vector, evaluation_feature_matrix, evaluation_target_vector)

Fit least squares on training data and score held-out data.

Parameters:

• training_feature_matrix (ndarray)

• training_target_vector (ndarray)

• evaluation_feature_matrix (ndarray)

• evaluation_target_vector (ndarray)

Return type:

LinearFitResult

scripts.reports.analysis.build_wave52_mmt_residual_explanatory_diagnostic.run_bounded_self_test(random_seed)

Verify the least-squares and shuffled-control helpers synthetically.

Parameters:

random_seed (int)

Return type:

dict[str, Any]

scripts.reports.analysis.build_wave52_mmt_residual_explanatory_diagnostic.build_comparison_row_list(residual_row_list, baseline_specification_list, config_dictionary)

Fit allowed controls and expose unavailable physical calibration.

Parameters:

• residual_row_list (list[dict[str, Any]])

• baseline_specification_list (list[BaselineSpecification])

• config_dictionary (dict[str, Any])

Return type:

tuple[list[dict[str, Any]], str, list[str]]

scripts.reports.analysis.build_wave52_mmt_residual_explanatory_diagnostic.build_report_markdown(run_instance_id, config_path, output_directory, residual_metrics_path, baseline_manifest_row_list, split_count_dictionary, split_audit_row_list, descriptive_summary_row_list, mmt_signature_row_list, comparison_row_list, decision, blocker_list)

Build the human-readable analytical report.

Parameters:

• run_instance_id (str)

• config_path (Path)

• output_directory (Path)

• residual_metrics_path (Path)

• baseline_manifest_row_list (list[dict[str, Any]])

• split_count_dictionary (dict[str, int])

• split_audit_row_list (list[dict[str, Any]])

• descriptive_summary_row_list (list[dict[str, Any]])

• mmt_signature_row_list (list[dict[str, Any]])

• comparison_row_list (list[dict[str, Any]])

• decision (str)

• blocker_list (list[str])

Return type:

str

scripts.reports.analysis.build_wave52_mmt_residual_explanatory_diagnostic.execute_diagnostic(config_path, run_instance_id, run_self_test)

Execute the bounded non-training diagnostic.

Parameters:

• config_path (Path)

• run_instance_id (str)

• run_self_test (bool)

Return type:

dict[str, Any]

scripts.reports.analysis.build_wave52_mmt_residual_explanatory_diagnostic.main()

Run the diagnostic builder.

Return type:

None