TE Curve Verification Pipeline Shape-Gated Reranker

Build a shape-gated TE Curve Verification Pipeline reranker.

class scripts.reports.analysis.build_shape_gated_te_curve_reranker.ShapeGateThresholds(minimum_fft_amplitude_similarity, minimum_derivative_correlation, minimum_smoothed_derivative_correlation, minimum_derivative_sign_agreement_rate, maximum_normalized_derivative_rmse, maximum_mean_harmonic_amplitude_error_pct, maximum_mean_harmonic_phase_error_deg, maximum_peak_to_peak_error_pct, minimum_per_curve_shape_pass_rate, near_pass_minimum_fft_amplitude_similarity, near_pass_maximum_mean_harmonic_amplitude_error_pct, near_pass_maximum_mean_harmonic_phase_error_deg, near_pass_maximum_peak_to_peak_error_pct, near_pass_minimum_derivative_sign_agreement_rate, near_pass_maximum_normalized_derivative_rmse)[source]

Bases: object

Store conservative shape-gate thresholds.

Parameters:

  • minimum_fft_amplitude_similarity (float)

  • minimum_derivative_correlation (float)

  • minimum_smoothed_derivative_correlation (float)

  • minimum_derivative_sign_agreement_rate (float)

  • maximum_normalized_derivative_rmse (float)

  • maximum_mean_harmonic_amplitude_error_pct (float)

  • maximum_mean_harmonic_phase_error_deg (float)

  • maximum_peak_to_peak_error_pct (float)

  • minimum_per_curve_shape_pass_rate (float)

  • near_pass_minimum_fft_amplitude_similarity (float)

  • near_pass_maximum_mean_harmonic_amplitude_error_pct (float)

  • near_pass_maximum_mean_harmonic_phase_error_deg (float)

  • near_pass_maximum_peak_to_peak_error_pct (float)

  • near_pass_minimum_derivative_sign_agreement_rate (float)

  • near_pass_maximum_normalized_derivative_rmse (float)

minimum_fft_amplitude_similarity: float
minimum_derivative_correlation: float
minimum_smoothed_derivative_correlation: float
minimum_derivative_sign_agreement_rate: float
maximum_normalized_derivative_rmse: float
maximum_mean_harmonic_amplitude_error_pct: float
maximum_mean_harmonic_phase_error_deg: float
maximum_peak_to_peak_error_pct: float
minimum_per_curve_shape_pass_rate: float
near_pass_minimum_fft_amplitude_similarity: float
near_pass_maximum_mean_harmonic_amplitude_error_pct: float
near_pass_maximum_mean_harmonic_phase_error_deg: float
near_pass_maximum_peak_to_peak_error_pct: float
near_pass_minimum_derivative_sign_agreement_rate: float
near_pass_maximum_normalized_derivative_rmse: float
class scripts.reports.analysis.build_shape_gated_te_curve_reranker.ShapeCurveMetric(candidate_id, candidate_family, candidate_kind, candidate_source_label, candidate_surface, direction_label, source_file_path, speed_rpm, torque_nm, oil_temperature_deg, raw_mae_deg, raw_rmse_deg, mean_percentage_error_pct, p95_candidate_percentage_error_pct, absolute_offset_error_deg, centered_mae_deg, centered_rmse_deg, peak_to_peak_error_pct, fft_amplitude_similarity, dominant_harmonic_order, dominant_harmonic_retention_pct, dominant_harmonic_phase_error_deg, mean_harmonic_amplitude_error_pct, mean_harmonic_phase_error_deg, derivative_correlation, centered_derivative_correlation, smoothed_derivative_correlation, derivative_sign_agreement_rate, derivative_rmse_deg_per_deg, normalized_derivative_rmse, shape_failure_reason, shape_pass)[source]

Bases: object

Store one per-curve shape-gated metric row.

Parameters:

  • candidate_id (str)

  • candidate_family (str)

  • candidate_kind (str)

  • candidate_source_label (str)

  • candidate_surface (str)

  • direction_label (str)

  • source_file_path (str)

  • speed_rpm (float)

  • torque_nm (float)

  • oil_temperature_deg (float)

  • raw_mae_deg (float)

  • raw_rmse_deg (float)

  • mean_percentage_error_pct (float)

  • p95_candidate_percentage_error_pct (float)

  • absolute_offset_error_deg (float)

  • centered_mae_deg (float)

  • centered_rmse_deg (float)

  • peak_to_peak_error_pct (float)

  • fft_amplitude_similarity (float)

  • dominant_harmonic_order (int)

  • dominant_harmonic_retention_pct (float)

  • dominant_harmonic_phase_error_deg (float)

  • mean_harmonic_amplitude_error_pct (float)

  • mean_harmonic_phase_error_deg (float)

  • derivative_correlation (float)

  • centered_derivative_correlation (float)

  • smoothed_derivative_correlation (float)

  • derivative_sign_agreement_rate (float)

  • derivative_rmse_deg_per_deg (float)

  • normalized_derivative_rmse (float)

  • shape_failure_reason (str)

  • shape_pass (bool)

candidate_id: str
candidate_family: str
candidate_kind: str
candidate_source_label: str
candidate_surface: str
direction_label: str
source_file_path: str
speed_rpm: float
torque_nm: float
oil_temperature_deg: float
raw_mae_deg: float
raw_rmse_deg: float
mean_percentage_error_pct: float
p95_candidate_percentage_error_pct: float
absolute_offset_error_deg: float
centered_mae_deg: float
centered_rmse_deg: float
peak_to_peak_error_pct: float
fft_amplitude_similarity: float
dominant_harmonic_order: int
dominant_harmonic_retention_pct: float
dominant_harmonic_phase_error_deg: float
mean_harmonic_amplitude_error_pct: float
mean_harmonic_phase_error_deg: float
derivative_correlation: float
centered_derivative_correlation: float
smoothed_derivative_correlation: float
derivative_sign_agreement_rate: float
derivative_rmse_deg_per_deg: float
normalized_derivative_rmse: float
shape_failure_reason: str
shape_pass: bool
to_csv_row()[source]

Return a stable CSV row.

Return type:

dict[str, Any]

class scripts.reports.analysis.build_shape_gated_te_curve_reranker.EvaluationFailure(candidate_id, candidate_family, candidate_kind, candidate_source_label, candidate_surface, surface_scope, error_type, error_message)[source]

Bases: object

Store one candidate evaluation failure.

Parameters:

  • candidate_id (str)

  • candidate_family (str)

  • candidate_kind (str)

  • candidate_source_label (str)

  • candidate_surface (str)

  • surface_scope (str)

  • error_type (str)

  • error_message (str)

candidate_id: str
candidate_family: str
candidate_kind: str
candidate_source_label: str
candidate_surface: str
surface_scope: str
error_type: str
error_message: str
class scripts.reports.analysis.build_shape_gated_te_curve_reranker.ShapeCandidateSummary(rank, candidate_id, candidate_family, candidate_kind, candidate_source_label, candidate_surface, direction_label, curve_count, mean_raw_mae_deg, mean_raw_rmse_deg, mean_percentage_error_pct, p95_mean_percentage_error_pct, mean_absolute_offset_error_deg, mean_centered_mae_deg, mean_centered_rmse_deg, mean_peak_to_peak_error_pct, mean_fft_amplitude_similarity, mean_dominant_harmonic_retention_pct, mean_dominant_harmonic_phase_error_deg, mean_harmonic_amplitude_error_pct, mean_harmonic_phase_error_deg, mean_derivative_correlation, mean_smoothed_derivative_correlation, mean_derivative_sign_agreement_rate, mean_derivative_rmse_deg_per_deg, mean_normalized_derivative_rmse, per_curve_shape_pass_rate, raw_error_score, shape_score, harmonic_score, offset_score, robustness_score, composite_score, decision_label, veto_reason)[source]

Bases: object

Store one candidate-level shape-gated summary.

Parameters:

  • rank (int)

  • candidate_id (str)

  • candidate_family (str)

  • candidate_kind (str)

  • candidate_source_label (str)

  • candidate_surface (str)

  • direction_label (str)

  • curve_count (int)

  • mean_raw_mae_deg (float)

  • mean_raw_rmse_deg (float)

  • mean_percentage_error_pct (float)

  • p95_mean_percentage_error_pct (float)

  • mean_absolute_offset_error_deg (float)

  • mean_centered_mae_deg (float)

  • mean_centered_rmse_deg (float)

  • mean_peak_to_peak_error_pct (float)

  • mean_fft_amplitude_similarity (float)

  • mean_dominant_harmonic_retention_pct (float)

  • mean_dominant_harmonic_phase_error_deg (float)

  • mean_harmonic_amplitude_error_pct (float)

  • mean_harmonic_phase_error_deg (float)

  • mean_derivative_correlation (float)

  • mean_smoothed_derivative_correlation (float)

  • mean_derivative_sign_agreement_rate (float)

  • mean_derivative_rmse_deg_per_deg (float)

  • mean_normalized_derivative_rmse (float)

  • per_curve_shape_pass_rate (float)

  • raw_error_score (float)

  • shape_score (float)

  • harmonic_score (float)

  • offset_score (float)

  • robustness_score (float)

  • composite_score (float)

  • decision_label (str)

  • veto_reason (str)

rank: int
candidate_id: str
candidate_family: str
candidate_kind: str
candidate_source_label: str
candidate_surface: str
direction_label: str
curve_count: int
mean_raw_mae_deg: float
mean_raw_rmse_deg: float
mean_percentage_error_pct: float
p95_mean_percentage_error_pct: float
mean_absolute_offset_error_deg: float
mean_centered_mae_deg: float
mean_centered_rmse_deg: float
mean_peak_to_peak_error_pct: float
mean_fft_amplitude_similarity: float
mean_dominant_harmonic_retention_pct: float
mean_dominant_harmonic_phase_error_deg: float
mean_harmonic_amplitude_error_pct: float
mean_harmonic_phase_error_deg: float
mean_derivative_correlation: float
mean_smoothed_derivative_correlation: float
mean_derivative_sign_agreement_rate: float
mean_derivative_rmse_deg_per_deg: float
mean_normalized_derivative_rmse: float
per_curve_shape_pass_rate: float
raw_error_score: float
shape_score: float
harmonic_score: float
offset_score: float
robustness_score: float
composite_score: float
decision_label: str
veto_reason: str
ranking_key()[source]

Return a deterministic reranking key.

Return type:

tuple[int, float, float, str]

to_csv_row()[source]

Return a stable CSV row.

Return type:

dict[str, Any]

scripts.reports.analysis.build_shape_gated_te_curve_reranker.build_argument_parser()[source]

Build the command-line argument parser.

Return type:

ArgumentParser

scripts.reports.analysis.build_shape_gated_te_curve_reranker.parse_command_line_arguments()[source]

Parse command-line arguments.

Return type:

Namespace

scripts.reports.analysis.build_shape_gated_te_curve_reranker.format_float(value)[source]

Format finite floats for stable artifacts.

Parameters:

value (float)

Return type:

str

scripts.reports.analysis.build_shape_gated_te_curve_reranker.safe_mean(value_list)[source]

Return the finite-value mean.

Parameters:

value_list (list[float])

Return type:

float

scripts.reports.analysis.build_shape_gated_te_curve_reranker.percentile(value_list, percentile_value)[source]

Compute a deterministic percentile from finite values.

Parameters:

  • value_list (list[float])

  • percentile_value (float)

Return type:

float

scripts.reports.analysis.build_shape_gated_te_curve_reranker.normalize_score(value, value_list, higher_is_better=False)[source]

Normalize one metric into a bounded zero-best score.

Parameters:

  • value (float)

  • value_list (list[float])

  • higher_is_better (bool)

Return type:

float

scripts.reports.analysis.build_shape_gated_te_curve_reranker.compute_correlation(left_array, right_array)[source]

Compute Pearson correlation with constant-signal guards.

Parameters:

  • left_array (ndarray)

  • right_array (ndarray)

Return type:

float

scripts.reports.analysis.build_shape_gated_te_curve_reranker.compute_centered_array(value_array)[source]

Return a mean-centered float array.

Parameters:

value_array (ndarray)

Return type:

ndarray

scripts.reports.analysis.build_shape_gated_te_curve_reranker.compute_moving_average(value_array, window_size)[source]

Return an edge-padded moving average with a fixed odd window.

Parameters:

  • value_array (ndarray)

  • window_size (int)

Return type:

ndarray

scripts.reports.analysis.build_shape_gated_te_curve_reranker.compute_derivative_sign_agreement_rate(truth_derivative, predicted_derivative)[source]

Compute derivative sign agreement while ignoring near-flat truth samples.

Parameters:

  • truth_derivative (ndarray)

  • predicted_derivative (ndarray)

Return type:

float

scripts.reports.analysis.build_shape_gated_te_curve_reranker.compute_fft_amplitude_similarity(truth_curve_deg, predicted_curve_deg)[source]

Compute cosine similarity between centered real-FFT amplitude spectra.

Parameters:

  • truth_curve_deg (ndarray)

  • predicted_curve_deg (ndarray)

Return type:

float

scripts.reports.analysis.build_shape_gated_te_curve_reranker.prepare_curve_arrays(candidate_entry)[source]

Resolve finite sorted curve arrays with unique angular positions.

Parameters:

candidate_entry (dict[str, Any])

Return type:

tuple[ndarray, ndarray, ndarray]

scripts.reports.analysis.build_shape_gated_te_curve_reranker.compute_dominant_harmonic_metrics(harmonic_row_list)[source]

Select the strongest truth harmonic and return retention and phase error.

Parameters:

harmonic_row_list (list[dict[str, float]])

Return type:

tuple[int, float, float]

scripts.reports.analysis.build_shape_gated_te_curve_reranker.compute_shape_pass(metric, thresholds)[source]

Return whether one curve satisfies the shape gate.

Parameters:
Return type:

bool

scripts.reports.analysis.build_shape_gated_te_curve_reranker.build_shape_failure_reason_list(metric, thresholds)[source]

Return the strict shape-gate failure reasons for one curve.

Parameters:
Return type:

list[str]

scripts.reports.analysis.build_shape_gated_te_curve_reranker.derivative_gate_passes(metric, thresholds)[source]

Return whether one curve passes at least one derivative-agreement screen.

Parameters:
Return type:

bool

scripts.reports.analysis.build_shape_gated_te_curve_reranker.near_pass_gate_passes(summary, thresholds)[source]

Return whether a failed active candidate is close enough to keep under review.

Parameters:
Return type:

bool

scripts.reports.analysis.build_shape_gated_te_curve_reranker.build_thresholds(arguments)[source]

Build threshold configuration from CLI arguments.

Parameters:

arguments (Namespace)

Return type:

ShapeGateThresholds

scripts.reports.analysis.build_shape_gated_te_curve_reranker.resolve_timestamped_output_paths(output_root, report_topic_root, report_date)[source]

Resolve timestamped output and report directories.

Parameters:

  • output_root (Path)

  • report_topic_root (Path)

  • report_date (str | None)

Return type:

tuple[str, Path, Path]

scripts.reports.analysis.build_shape_gated_te_curve_reranker.load_training_config(config_path, dataset_name)[source]

Load and prepare a selected-active TE Curve Verification config.

Parameters:

  • config_path (Path)

  • dataset_name (str)

Return type:

dict[str, Any]

scripts.reports.analysis.build_shape_gated_te_curve_reranker.resolve_candidate_configuration_list(training_config, dataset_name, surface_scope, active_family_list)[source]

Resolve the reduced candidate list for one dataset and surface.

Parameters:

  • training_config (dict[str, Any])

  • dataset_name (str)

  • surface_scope (str)

  • active_family_list (list[str])

Return type:

list[dict[str, Any]]

scripts.reports.analysis.build_shape_gated_te_curve_reranker.evaluate_surface_candidate_payloads(training_config, dataset_name, surface_scope, candidate_configuration_list)[source]

Evaluate selected candidates and return curve payload entries.

Parameters:

  • training_config (dict[str, Any])

  • dataset_name (str)

  • surface_scope (str)

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

Return type:

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

scripts.reports.analysis.build_shape_gated_te_curve_reranker.compute_curve_metric(candidate_entry, harmonic_order_list, thresholds)[source]

Compute one per-curve shape-gated metric.

Parameters:

  • candidate_entry (dict[str, Any])

  • harmonic_order_list (list[int])

  • thresholds (ShapeGateThresholds)

Return type:

ShapeCurveMetric

scripts.reports.analysis.build_shape_gated_te_curve_reranker.attach_candidate_p95(metric_list)[source]

Attach candidate-level P95 raw percentage error to every per-curve row.

Parameters:

metric_list (list[ShapeCurveMetric])

Return type:

list[ShapeCurveMetric]

scripts.reports.analysis.build_shape_gated_te_curve_reranker.build_candidate_summary_list(per_curve_metric_list, thresholds, failure_list)[source]

Build ranked candidate summaries from per-curve metrics.

Parameters:
Return type:

list[ShapeCandidateSummary]

scripts.reports.analysis.build_shape_gated_te_curve_reranker.build_failure_summary_list(failure_list)[source]

Build insufficient-evidence summaries for candidates that failed evaluation.

Parameters:

failure_list (list[EvaluationFailure])

Return type:

list[ShapeCandidateSummary]

scripts.reports.analysis.build_shape_gated_te_curve_reranker.add_block_scores(summary_list)[source]

Attach normalized block scores and composite scores.

Parameters:

summary_list (list[ShapeCandidateSummary])

Return type:

list[ShapeCandidateSummary]

scripts.reports.analysis.build_shape_gated_te_curve_reranker.rerank_candidate_summaries(summary_list)[source]

Sort summaries and assign ranks plus recommendation labels.

Parameters:

summary_list (list[ShapeCandidateSummary])

Return type:

list[ShapeCandidateSummary]

scripts.reports.analysis.build_shape_gated_te_curve_reranker.resolve_surface_scope_list(arguments)[source]

Resolve CLI surface scopes.

Parameters:

arguments (Namespace)

Return type:

list[str]

scripts.reports.analysis.build_shape_gated_te_curve_reranker.build_shape_metrics_for_surface(training_config, dataset_name, surface_scope, active_family_list, harmonic_order_list, thresholds)[source]

Build all per-curve shape metrics for one surface.

Parameters:

  • training_config (dict[str, Any])

  • dataset_name (str)

  • surface_scope (str)

  • active_family_list (list[str])

  • harmonic_order_list (list[int])

  • thresholds (ShapeGateThresholds)

Return type:

tuple[list[ShapeCurveMetric], list[EvaluationFailure]]

scripts.reports.analysis.build_shape_gated_te_curve_reranker.build_threshold_sweep_row_list(per_curve_metric_list, thresholds)[source]

Build compact derivative-threshold sweep rows for calibration review.

Parameters:
Return type:

list[dict[str, Any]]

scripts.reports.analysis.build_shape_gated_te_curve_reranker.write_csv(csv_path, row_list)[source]

Write a CSV file from dictionaries.

Parameters:

  • csv_path (Path)

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

Return type:

None

scripts.reports.analysis.build_shape_gated_te_curve_reranker.build_surface_decision_payload(run_instance_id, config_path, dataset_name, surface_summary_map, thresholds)[source]

Build a machine-readable reranking decision payload.

Parameters:
Return type:

dict[str, Any]

scripts.reports.analysis.build_shape_gated_te_curve_reranker.build_report_markdown(run_instance_id, config_path, dataset_name, surface_summary_map, thresholds, output_directory)[source]

Build the human-readable shape-gated reranking report.

Parameters:
Return type:

str

scripts.reports.analysis.build_shape_gated_te_curve_reranker.build_report_filename(config_path)[source]

Build a report filename scoped to the evaluated config.

Parameters:

config_path (Path)

Return type:

str

scripts.reports.analysis.build_shape_gated_te_curve_reranker.main()[source]

Run the command-line entry point.

Return type:

None