Theme: A defensible workflow connects the decision, data, modelling, validation, interpretation, and communication
Why This Chapter Matters
An analysis is not complete because a model has been fitted. It is complete only when the workflow can be inspected from the original decision question to the final recommendation.
This chapter brings the guide together in one case study. The objective is not to find a perfect model. It is to produce an analysis whose data transformations, comparisons, limitations, and claims remain defensible when another analyst reviews the work.
The case study follows six connected questions:
What decision must the analysis support?
What information would genuinely be available at prediction time?
How should development and final evaluation data be separated?
Which modelling strategy performs well enough for the intended use?
What threshold balances missed cases against review capacity?
What can responsibly be concluded, communicated, and monitored?
The governing rule
The final holdout set is opened once, after preprocessing choices, candidate comparison, hyperparameter selection, and threshold selection have been completed using development data only.
Case Study: Prioritising Equipment Inspections
A maintenance team receives more equipment alerts than it can inspect immediately. It wants a model that ranks new alerts by the likelihood that an inspection will identify a fault requiring prompt follow-up.
The model will support a triage queue. It will not cancel inspections, certify equipment as safe, or automatically authorise maintenance work.
Decision statement
For each newly recorded alert, estimate the probability that inspection will confirm a priority fault, then use an agreed threshold to place the alert in the priority-review queue.
This statement identifies the unit of analysis, prediction time, outcome, and intended action.
Design element
Case-study definition
Unit of analysis
One equipment alert
Prediction time
When the alert enters the review system
Outcome
Priority fault confirmed during inspection
Prediction horizon
The subsequent inspection episode
Model output
Estimated probability of a confirmed priority fault
Human action
Prioritise an alert for earlier review
Out-of-scope action
Declaring equipment safe without inspection
Success criteria
The team specifies the criteria before comparing models:
discrimination must improve meaningfully over a simple baseline;
probability estimates should be sufficiently calibrated for threshold selection;
recall is prioritised because missed priority faults are costly;
the predicted-positive rate must remain compatible with review capacity;
performance must be examined across sites and equipment-age groups;
the final recommendation must state uncertainty and operational limitations.
Accuracy alone is unsuitable because priority faults are less common than non-priority outcomes and the two error types have different consequences.
Workflow Map
Code
flowchart TD A[Define decision and outcome] --> B[Audit prediction-time data] B --> C[Lock time-based holdout] C --> D[Develop pipelines and candidates] D --> E[Select threshold on development predictions] E --> F[Evaluate once on final holdout] F --> G[Communicate, deploy cautiously, and monitor]
flowchart TD
A[Define decision and outcome] --> B[Audit prediction-time data]
B --> C[Lock time-based holdout]
C --> D[Develop pipelines and candidates]
D --> E[Select threshold on development predictions]
E --> F[Evaluate once on final holdout]
F --> G[Communicate, deploy cautiously, and monitor]
Each stage creates evidence needed by the next stage. If the decision or prediction time changes, the feature audit, validation design, threshold, and claims may also need to change.
1. Establish the Analytical Contract
Before inspecting model performance, record the intended use and foreseeable misuse.
analytical_contract = {"unit": "equipment alert","prediction_time": "alert creation","outcome": "priority fault confirmed at inspection","intended_use": "prioritise alerts for human review","prohibited_use": "declare equipment safe or cancel inspection","primary_metric": "recall at an operationally feasible threshold","secondary_metrics": ["average precision","ROC AUC","precision","Brier score", ],}
The contract prevents a technically valid result from being reused for a decision it was never designed to support.
2. Build and Audit the Analysis Table
Assume the raw alert, equipment, and inspection tables have already been joined into one row per alert. The analysis table contains:
alert_date: when the alert was recorded;
site: operating site;
equipment_type: broad equipment category;
equipment_age_years: age at alert time;
sensor_score: standardised sensor anomaly score;
temperature_c: temperature observed with the alert;
alerts_last_30d: number of earlier alerts in the previous 30 days;
days_since_maintenance: elapsed time since the latest completed maintenance;
priority_fault: binary outcome recorded after inspection.
Prediction-time availability
Every candidate feature must pass a prediction-time audit.
Variable
Available when alert arrives?
Use?
Reason
sensor_score
Yes
Yes
Recorded with the alert
alerts_last_30d
Yes
Yes
Uses historical alerts only
days_since_maintenance
Yes
Yes
Derived from prior maintenance
technician_notes
Not always
No
Missing until review begins
repair_cost
No
No
Determined after inspection
inspection_result
No
Outcome only
Defines the target
Using repair_cost or post-review notes would leak information from the future. Excellent validation performance produced by such variables would not survive real use.
The audit should also check impossible values, duplicate alerts, changing category labels, implausible dates, and whether multiple alerts from the same equipment create dependence that the validation design must respect.
3. Lock the Final Holdout
Alerts arrive over time, so a random split would make evaluation less representative of future use. The most recent period becomes the final holdout.
The split boundary should be recorded in the analysis log. The holdout must not guide feature selection, preprocessing, candidate selection, hyperparameter tuning, or threshold selection.
A common hidden leak
Fitting an imputer, scaler, encoder, or feature selector on the complete dataset exposes information from the holdout period. Put every learned transformation inside the modelling pipeline.
4. Create One Reusable Preprocessing Definition
Identifiers, dates, predictors, and outcomes have different roles. Only prediction-time features enter the model.
Class weighting changes the fitted decision function; it does not make the observed population balanced. Predicted probabilities must therefore be checked for calibration rather than assumed to be calibrated.
6. Compare Candidates Using Development Data
Because observations are ordered in time, expanding-window validation is preferable to shuffled cross-validation.
The fold standard deviations matter. A small improvement with substantially greater instability, complexity, or monitoring burden may not justify selecting the more complex model.
Model selection rule
Choose the simplest candidate that:
materially exceeds both baselines on average precision;
retains acceptable recall under the operational capacity constraint;
has stable fold-level results;
produces probability estimates that can be calibrated adequately;
does not show an unacceptable subgroup failure.
This rule should be written before the final holdout is evaluated.
7. Generate Out-of-Fold Development Probabilities
Thresholds must not be chosen from in-sample probabilities. Use predictions for observations that were not used to fit the corresponding fold model.
The earliest block has no earlier training block and therefore has no out-of-fold prediction. That is an expected property of expanding-window validation.
8. Select an Operational Threshold
Suppose the team can prioritise approximately 20% of incoming alerts and requires development recall of at least 0.80 when feasible.
from sklearn.metrics import precision_score, recall_scorethreshold_rows = []for threshold in np.linspace(0.05, 0.95, 181): predicted = (p_oof >= threshold).astype(int) threshold_rows.append({"threshold": threshold,"recall": recall_score(y_oof, predicted, zero_division=0),"precision": precision_score(y_oof, predicted, zero_division=0),"review_rate": predicted.mean(), })threshold_table = pd.DataFrame(threshold_rows)feasible = threshold_table.loc[ (threshold_table["recall"] >=0.80)& (threshold_table["review_rate"] <=0.20)]if feasible.empty:raiseRuntimeError("No threshold satisfies both recall and capacity requirements. ""Revise the model, resources, or operating target explicitly." )selected_threshold = feasible.sort_values( ["recall", "precision"], ascending=False,).iloc[0]["threshold"]
The RuntimeError is analytically important. When no threshold satisfies both safety and capacity requirements, the correct response is not to hide the conflict. The team must improve the workflow, increase review capacity, or revise the requirement with decision owners.
9. Fit Once and Evaluate the Final Holdout
After the model class and threshold have been frozen, fit the selected pipeline on all development data and evaluate the untouched holdout.
ROC AUC describes ranking across all possible thresholds.
Average precision focuses attention on performance for the positive class.
Brier score evaluates probability accuracy.
Recall measures how many priority faults enter the priority queue.
Precision measures how many prioritised alerts are confirmed as priority faults.
Review rate connects model output to operational capacity.
No single metric answers the full decision question.
10. Quantify Uncertainty
A point estimate can appear more certain than the available holdout permits. A stratified bootstrap provides an empirical interval while preserving outcome representation in each resample.
If alerts from the same equipment are strongly dependent, resample equipment clusters rather than individual rows. The uncertainty method must reflect the data-generating structure.
11. Inspect Calibration and Threshold Behaviour
A ranking model can discriminate well while producing poorly calibrated probabilities. Calibration matters when probabilities are used to set thresholds, allocate resources, or communicate risk.
Small subgroup estimates should be labelled unstable rather than over-interpreted. A performance difference can reflect sample size, prevalence, measurement quality, operational practice, or genuine model weakness. It is a signal for investigation, not an automatic causal explanation.
13. Interpret the Model Without Overclaiming
If logistic regression is selected, transformed coefficients can help describe the fitted associations. They do not establish causal effects.
Within this fitted predictive model, higher sensor anomaly scores were associated with higher predicted odds of a confirmed priority fault, conditional on the included features.
Inappropriate language:
Increasing the sensor score causes priority faults.
The second statement is causal and is not supported by this predictive design.
14. Perform Error Analysis
Aggregate metrics should be followed by structured review of errors.
The review should ask whether errors cluster by site, equipment type, missingness pattern, age, or time. Case-level review must use authorised, privacy-preserving procedures and must not expose sensitive operational records in public reports.
15. Translate Results Into a Decision
The final recommendation should connect evidence to a bounded action.
Example decision record
Decision component
Recorded conclusion
Proposed use
Rank new alerts for priority human review
Selected model
Frozen preprocessing and regularised logistic pipeline
Threshold basis
Out-of-fold development predictions plus review capacity
Final evidence
Holdout discrimination, calibration, threshold metrics, and uncertainty
Safeguard
No alert is closed or declared safe by the model
Escalation rule
Suspend automated ranking if data or performance checks breach limits
Review date
Set before operational use begins
Claim ladder
Separate what the evidence directly shows from what remains conditional:
Observed: report the final-holdout metrics and uncertainty intervals.
Supported: state that the frozen workflow showed useful prioritisation performance during the holdout period.
Conditional: recommend a monitored pilot under the stated review capacity and safeguards.
Unsupported: do not claim that the model prevents failures, improves safety, or generalises indefinitely without further evidence.
16. Save Reproducible Outputs
Save the fitted pipeline together with the analytical contract, feature lists, threshold, split boundary, software versions, and final metric table.
from datetime import datetime, timezonefrom pathlib import Pathimport jsonimport joblibimport sklearnPath("models").mkdir(exist_ok=True)Path("results/tables").mkdir(parents=True, exist_ok=True)joblib.dump(final_model, "models/18-priority-alert-pipeline.joblib")comparison.to_csv("results/tables/18-model-comparison.csv", index=False,)metadata = {"created_utc": datetime.now(timezone.utc).isoformat(),"holdout_start": str(HOLDOUT_START.date()),"selected_threshold": float(selected_threshold),"numeric_features": numeric_features,"categorical_features": categorical_features,"final_metrics": {key: float(value) for key, value in final_metrics.items()},"sklearn_version": sklearn.__version__,"intended_use": analytical_contract["intended_use"],"prohibited_use": analytical_contract["prohibited_use"],}withopen("models/18-model-metadata.json", "w", encoding="utf-8") asfile: json.dump(metadata, file, indent=2)
A serialized model without its threshold, feature contract, intended use, and evaluation context is not a complete analytical deliverable.
17. Define Monitoring Before Deployment
Monitoring should cover the entire decision workflow, not only model accuracy.
Recall, precision, calibration after outcomes arrive
Revalidate or retrain
Subgroups
Site and equipment-age performance
Investigate local failure
Operations
Queue delays, overrides, unresolved alerts
Redesign workflow
Retraining should be triggered by evidence and governed as a new model version. It should not occur silently on a calendar without renewed validation.
18. Reproducibility Checklist
Before considering the case study complete, confirm that:
Common Failure Modes
Starting with an algorithm
Failure: selecting a model before defining the decision and outcome. Consequence: technically impressive results may be irrelevant to the real workflow. Correction: begin with the analytical contract.
Randomly splitting time-dependent data
Failure: mixing future and earlier alerts across train and test sets. Consequence: evaluation does not represent forward-looking use. Correction: use time-respecting development and holdout periods.
Preprocessing before validation
Failure: imputing or scaling the complete dataset. Consequence: fold and holdout information leaks into model development. Correction: place learned transformations inside pipelines.
Selecting the threshold on the holdout
Failure: changing the threshold after inspecting final results. Consequence: the holdout becomes development data and no longer provides an unbiased final estimate. Correction: select the threshold from out-of-fold development predictions.
Reporting only the best metric
Failure: presenting ROC AUC without calibration, threshold metrics, uncertainty, or review volume. Consequence: decision owners cannot judge operational usefulness. Correction: report a metric set linked to the intended action.
Treating interpretation as causation
Failure: describing predictive features as causes or intervention targets. Consequence: stakeholders may act beyond the evidence. Correction: use association language and reserve causal claims for suitable designs.
Exercises
Rewrite the analytical contract for a regression problem in which the outcome is time to complete an inspection.
Identify three additional variables that would create target leakage in this case study.
Replace the time-based validation with grouped validation by equipment. Explain which deployment question each design answers.
Change the minimum recall and maximum review-rate requirements. Describe how the selected threshold and error balance change.
Compare logistic regression with a nonlinear candidate. Write a model-selection justification that considers stability, calibration, interpretability, and maintenance burden.
Design a clustered bootstrap when multiple alerts belong to the same equipment unit.
Draft a one-paragraph executive summary that distinguishes observed performance, supported interpretation, conditional recommendation, and unsupported claims.
Create a monitoring table with named owners, review frequency, warning limits, and stop-use limits.
Chapter Summary
An end-to-end workflow is a chain of justified decisions. The decision question determines the outcome and prediction time. Prediction time determines which features are legitimate. The deployment setting determines the validation design. Validation results support model selection, while development predictions support threshold selection. The untouched holdout supports the final performance claim. Interpretation, uncertainty, limitations, and monitoring determine whether that claim can responsibly support action.
The central lesson is simple:
A useful model is not merely one that predicts well. It is one whose purpose, data, validation, operating rule, limitations, and consequences remain visible from beginning to end.
This case study completes the technical workflow developed throughout the guide and prepares the reader to apply it to new domains without treating any single algorithm as the workflow itself.