> ## Documentation Index
> Fetch the complete documentation index at: https://offthepace.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# fct_cliff_prediction_features
> Lap-grain feature table for the tyre cliff XGBoost model.
Part of the [Marts](/transform/families/marts) family.
> For the conceptual foundation, read [Fct Cliff Prediction Features](/decomposition/methodology).
Lap-grain feature table for the tyre cliff XGBoost model. One row per valid race lap. Target is next\_lap\_degradation\_jump\_s (NULL on the last lap of each stint). Excludes synthetic-teammate features to prevent causal label leakage into a predictive model.
Breaking a column type on this model fails the dbt build - this is the enforced handoff contract with `ml/`.
## Lineage
```mermaid theme={null}
flowchart LR
dim_circuits --> fct_cliff_prediction_features
dim_compounds_season --> fct_cliff_prediction_features
int_compound_cliff_predicted --> fct_cliff_prediction_features
int_event_corrections --> fct_cliff_prediction_features
int_lap_air_state --> fct_cliff_prediction_features
int_lap_anomaly_flags --> fct_cliff_prediction_features
int_lap_corner_inputs --> fct_cliff_prediction_features
int_lap_proximity --> fct_cliff_prediction_features
int_lap_residual_decomposed --> fct_cliff_prediction_features
int_lap_residual_stint_detrend --> fct_cliff_prediction_features
int_lap_telemetry_aggregates --> fct_cliff_prediction_features
int_lap_thermal_proxy --> fct_cliff_prediction_features
int_qualifying_driver_summary --> fct_cliff_prediction_features
int_sc_hazard_history --> fct_cliff_prediction_features
style fct_cliff_prediction_features fill:#e40404,stroke:#e40404,color:#fff
```
## Overview
| Property | Value |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Layer | `marts` |
| Family | [Marts](/transform/families/marts) |
| Contract enforced | ✅ Yes |
| Upstream | [`int_lap_residual_decomposed`](../int/int_lap_residual_decomposed), [`int_lap_anomaly_flags`](../int/int_lap_anomaly_flags), [`int_compound_cliff_predicted`](../int/int_compound_cliff_predicted), [`int_lap_thermal_proxy`](../int/int_lap_thermal_proxy), [`int_lap_air_state`](../int/int_lap_air_state), [`int_lap_proximity`](../int/int_lap_proximity), [`int_lap_corner_inputs`](../int/int_lap_corner_inputs), [`int_event_corrections`](../int/int_event_corrections), [`int_qualifying_driver_summary`](../int/int_qualifying_driver_summary), [`int_sc_hazard_history`](../int/int_sc_hazard_history), [`int_lap_residual_stint_detrend`](../int/int_lap_residual_stint_detrend), [`int_lap_telemetry_aggregates`](../int/int_lap_telemetry_aggregates), [`dim_compounds_season`](../dim/dim_compounds_season), [`dim_circuits`](../dim/dim_circuits) |
| Model-level tests | `expect_column_values_to_be_between`, `expect_column_values_to_be_between` |
**3 tests** [guard](/transform/ci/overview) this model - 2 generic, 1 singular.
## Columns
| Column | Type | Nullable | Tests | Description |
| --------------------------------------- | -------------- | -------- | ----- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `lap_id` | `varchar` | No | | Surrogate PK from stg\_laps |
| `stint_id` | `varchar` | No | | Stint surrogate key |
| `race_year` | `integer` | No | | Season year |
| `race_id` | `varchar` | No | | Race identifier |
| `circuit_key` | `varchar` | No | | Circuit identifier (track\_id via race\_to\_track); L0-1 cohort key and predictions output column |
| `driver_id` | `varchar` | No | | FastF1 three-letter driver code |
| `constructor_id` | `varchar` | Yes | | Team name |
| `lap_number` | `integer` | No | | Lap number within race |
| `lap_in_stint` | `bigint` | Yes | | Lap position within current tyre stint |
| `age_in_stint` | `integer` | Yes | | Tyre age in laps (may differ from lap\_in\_stint for used tyres) |
| `compound` | `varchar` | Yes | | Tyre compound (SOFT, MEDIUM, HARD, etc.) |
| `compound_grip_peak` | `double` | Yes | | Fitted peak grip coefficient for this compound × circuit × season |
| `compound_wear_gradient` | `double` | Yes | | Fitted wear gradient (s/lap) for this compound × circuit × season |
| `compound_optimal_temp_low` | `double` | Yes | | Lower bound of optimal operating temperature window (°C) |
| `compound_optimal_temp_high` | `double` | Yes | | Upper bound of optimal operating temperature window (°C) |
| `compound_cliff_onset_laps` | `double` | Yes | | Expected lap age at cliff onset for this compound × circuit × season |
| `compound_cliff_severity` | `double` | Yes | | Fitted cliff severity (s/lap post-cliff) for this compound × circuit × season |
| `push_residual` | `double` | Yes | | Lap pace against the stint's point-in-time baseline, from int\_lap\_thermal\_proxy. NULL until the stint has one valid prior lap (08e); the NULL is deterministic on baseline\_observations\_n below. |
| `cumulative_push_load_surface` | `double` | Yes | | EW cumulative push load (τ≈3 laps) for tyre surface |
| `cumulative_push_load_bulk` | `double` | Yes | | EW cumulative push load (τ≈5 laps) for tyre bulk |
| `baseline_observations_n` | `bigint` | Yes | | Valid prior laps behind this stint's baseline. NOT a feature -- it is not in ml/src/schema.py's FEATURE\_COLUMNS, and putting it in X is an add-ablation someone has to gate. It ships in the contract because the four thermal columns are NULL exactly where it is 0, and unlike 02a's rebuild that missingness is not declarable from any other contract column: it rises with SC and pit disruption, so it is plausibly correlated with the outcome. |
| `dirty_air_share_lap` | `decimal(2,1)` | No | | Fraction of this lap spent in dirty air (sector 2) |
| `dirty_air_thermal_load_surface` | `double` | No | | EW dirty air thermal load on tyre surface |
| `dirty_air_thermal_load_bulk` | `double` | No | | EW dirty air thermal load on tyre bulk |
| `air_state_dominant` | `varchar` | No | | Dominant air state this lap (free\_air, tow\_zone, drs\_train, dirty\_air) |
| `share_lap_within_1s` | `double` | No | | Share of the lap's 100 track bins with a car within 1 s ahead on track (position channel; mean 0.2011) |
| `share_lap_within_2s` | `double` | No | | Share of the lap's track bins with a car within 2 s ahead on track (mean 0.4063) |
| `share_lap_in_train` | `double` | No | | Share of the lap in a train rather than a single tow - within 1 s of the car ahead AND that car within 1 s of its own car ahead (mean 0.0800) |
| `share_lap_behind_within_1s` | `double` | No | | Share of the lap's track bins with a car within 1 s BEHIND. The half of traffic DistanceToDriverAhead structurally cannot see (mean 0.2012) |
| `time_within_1s` | `double` | No | | Seconds of the lap spent within 1 s of the car ahead, time-weighted by real bin duration rather than counted in bins (mean 18.36 s) |
| `gap_ahead_min_s` | `double` | Yes | | Closest the car ahead on track came this lap (s). NULL = a full lap of clear air; median 0.92 s |
| `gap_ahead_median_s` | `double` | Yes | | Median gap to the car ahead on track across the lap's bins (s). NULL = clear air; median 2.26 s |
| `ahead_identity_stability` | `double` | Yes | | Share of the lap's within-3 s bins held by the single most frequent car ahead. 1.0 = a settled follow, low = the car ahead rotated. NULL on the 27.3% of laps with no car within 3 s |
| `n_distinct_cars_ahead_3s` | `integer` | Yes | | How many distinct cars were within 3 s ahead at some point in the lap (mean 1.348) |
| `corner_input_coverage` | `double` | No | | 02c. Share of the lap's measured corners that cleared int\_corner\_skill\_residuals' field\_corner\_sample\_n >= 5 gate, so carry a residual at all (mean 0.794 over mart rows, 0.799 over the training-eligible ones; 0.813 over int\_lap\_corner\_inputs, which is the same column before the COALESCE below adds the uncovered laps. Laps average 16.35 corners measured, 13.27 of them mapped). COALESCE-d to 0.0 on the 2.5% of mart laps with no corner row, because a lap with no mapped corner genuinely has zero coverage. NOT a nuisance column: coverage is correlated with the label (the 4.15% of training-eligible rows with no braking mean average +1.393 s of 5-lap jump against -2.330 s for covered rows, sd 10.196 vs 5.938), so it is admitted explicitly and ablated separately rather than left to XGBoost as an implicit NaN pattern. |
| `corner_braking_loss_mean_s` | `double` | Yes | | 02c. Mean braking\_loss\_s across the lap's corners that have a braking point (mean +0.0065 s since 00d; -0.0065 s before). Distance-of-first-brake-application vs the backward-only trailing-5 field median (02g), converted to seconds at s2 trap speed, signed (field - own) so POSITIVE = braked earlier than the field = time lost. NULL, never 0.0, where the lap has no measured braking corner - 0.0 would assert the driver braked exactly at the field median. |
| `corner_braking_loss_sd_s` | `double` | Yes | | 02c. Sample sd of braking\_loss\_s across the lap's corners (mean 0.3289 s; NULL on 2.57% of corner-covered laps, which have fewer than two measured braking corners). Unchanged by 00d's sign fix - a sample sd is invariant to negation. The tyre-management statistic of the three: a driver even across the lap loads the tyre differently from one spiking in two corners and coasting the rest, at equal mean. |
| `corner_braking_loss_max_s` | `double` | Yes | | 02c. Largest (most positive) braking\_loss\_s on the lap - the corner where the driver lost the most time on entry (mean +0.6475 s). 00d: this is the one corner-input column that is NOT a sign flip of its pre-00d self, because MAX does not commute with negation. It changed from "the corner braked latest" to "the corner braked earliest relative to the field". Pre-00d mean +0.5459 s, corr(old, new) = 0.080 over 131,482 laps. Mart-only and outside FEATURE\_COLUMNS, and 02c's arms over it are already void and must re-run. |
| `corner_mid_residual_mean_s` | `double` | Yes | | 02c. Mean mid\_corner\_residual\_s across the lap's corners (mean -0.0102 s). Apex-speed deficit vs the trailing-5 field median, in seconds. Highest-coverage of the three phases (81.12% of corner rows, and 100% of the mapped ones) because every corner has an apex, while not every corner has a discrete braking zone or a clean full-throttle point. |
| `corner_mid_residual_sd_s` | `double` | Yes | | 02c. Sample sd of mid\_corner\_residual\_s across the lap's corners (mean 0.1439 s; NULL on 2.39% of corner-covered laps). |
| `corner_mid_residual_max_s` | `double` | Yes | | 02c. Largest mid\_corner\_residual\_s on the lap - the corner with the biggest apex-speed deficit (mean 0.2543 s). |
| `corner_exit_residual_mean_s` | `double` | Yes | | 02c. Mean exit\_residual\_s across the lap's corners that reach full throttle (mean 0.0589 s). Distance-to-full-throttle vs the trailing-5 field median, in seconds. Sparsest of the three phases (47.00% of corner rows, 57.94% of the mapped ones): throttle\_point\_m is NULL where the driver never reaches 100% throttle before the next apex, which is a real answer about a corner sequence rather than missing data. |
| `corner_exit_residual_sd_s` | `double` | Yes | | 02c. Sample sd of exit\_residual\_s across the lap's corners (mean 0.2115 s; NULL on 9.78% of corner-covered laps, the sparsest phase). |
| `corner_exit_residual_max_s` | `double` | Yes | | 02c. Largest exit\_residual\_s on the lap - the corner the driver was slowest back to power in (mean 0.4367 s). |
| `quali_push_laps_n` | `bigint` | No | | Push laps this driver set across Q1/Q2/Q3 this weekend. 0, not NULL, when the driver has no row in int\_qualifying\_driver\_summary. |
| `quali_constructor_pace_mean_s` | `double` | Yes | | Mean constructor\_component\_s over the driver's qualifying push laps this weekend - car pace at low fuel, new tyres, near-zero traffic. |
| `quali_constructor_pace_se_mean_s` | `double` | Yes | | Mean estimation SE of constructor\_component\_s over the same push laps. |
| `quali_pace_delta_best_s` | `double` | Yes | | Driver's single best qualifying push lap this weekend (MIN of quali\_pace\_delta\_s, which is higher = slower by construction). |
| `quali_ratio_to_segment_best_min` | `double` | Yes | | How close the driver's best lap in any segment came to that segment's own fastest push lap (MIN of ratio\_to\_segment\_best). |
| `quali_skill_session_avg_s` | `double` | Yes | | Driver's one-lap qualifying skill for the weekend - the residual of their best push lap per segment, averaged over segments contested. |
| `quali_segments_contested_n` | `bigint` | Yes | | Segments (1-3) in which the driver set a best qualifying push lap this weekend. |
| `circuit_sc_hazard_per_lap` | `double` | Yes | | 02d. Per-racing-lap safety-car hazard for this circuit, empirical-Bayes shrunk, from int\_sc\_hazard\_history joined on (circuit\_key, race\_year) -- POINT-IN-TIME as of the start of the season, estimated from races at this venue in seasons strictly earlier. Circuit x season grain, so constant across every lap of the weekend. NULL, never 0.0, where the hazard is unknowable: season 2018 is the earliest in the warehouse, so no 2018 row has a prior season to estimate from nor a prior-season pooled rate to shrink toward. 0.0 would assert a venue never throws a safety car, which is a measurement nobody made. The NaN mask is therefore EXACTLY race\_year = 2018 (14,982 of 119,822 training-eligible rows, 12.5%), and race\_year is not itself in FEATURE\_COLUMNS -- see the leaf doc's arm D, which isolates that channel rather than letting it ride inside the hazard block. |
| `circuit_vsc_hazard_per_lap` | `double` | Yes | | 02d. As circuit\_sc\_hazard\_per\_lap, for virtual-safety-car onsets (status\_code 6). Not collinear with the SC rate -- corr(sc onsets, vsc onsets) = 0.125 per race over 149 races -- so the two are separate channels rather than one measured twice. |
| `circuit_any_hazard_per_lap` | `double` | Yes | | 02d. SC or VSC. EXACTLY circuit\_sc\_hazard\_per\_lap + circuit\_vsc\_hazard\_per\_lap: the onset counts add and the shrinkage priors add with them, so this carries no information the other two lack. Retained because a tree cannot form the sum itself, which makes it a basis rotation rather than a redundant column. |
| `circuit_hazard_prior_racing_laps` | `bigint` | Yes | | 02d. Racing laps of prior-season exposure the hazard estimate rests on, at this venue, seasons strictly before this one. 0 on a venue's debut season. Never NULL -- the source reports it unfloored, and 0 is the measured "no prior exposure" rather than an invented value. Carried as its own channel so the ablation can separate safety-car risk from calendar tenure, which has no SC mechanism in it (arm C). |
| `circuit_hazard_prior_seasons_n` | `bigint` | Yes | | 02d. Distinct prior seasons in which this venue appears, strictly before this one. 0 on a debut season. The companion count to circuit\_hazard\_prior\_racing\_laps and the second half of arm C. |
| `expected_compound_pace_s` | `double` | Yes | | Model-expected compound pace contribution from int\_compound\_cliff\_predicted |
| `expected_degradation_rate_s_per_lap` | `double` | Yes | | Model-expected degradation rate (s/lap) at current tyre age |
| `cliff_onset_passed` | `boolean` | Yes | | TRUE if tyre has passed its fitted cliff onset lap |
| `laps_past_cliff` | `double` | Yes | | Laps elapsed since cliff onset (0 if not passed) |
| `ambient_temp_delta` | `double` | Yes | | Difference between current ambient temp and optimal temp midpoint (°C) |
| `track_energy_index` | `double` | Yes | | Track energy index from dim\_circuits |
| `circuit_abrasiveness_index` | `integer` | Yes | | Track abrasiveness index from dim\_circuits |
| `n_gear_changes` | `integer` | Yes | | Gear changes this lap (telemetry powertrain group; NULL if no telemetry) |
| `mean_rpm` | `double` | Yes | | Mean engine RPM this lap |
| `max_rpm` | `double` | Yes | | Max engine RPM this lap |
| `pct_full_throttle` | `double` | Yes | | Fraction of the lap at full throttle (0–1) |
| `pct_drs_active` | `double` | Yes | | Fraction of the lap with DRS active (0–1) |
| `short_shift_index` | `double` | Yes | | Fraction of upshifts taken below 92% of lap-max RPM (short-shifting) |
| `mid_corner_speed_loss_kph` | `double` | Yes | | Within-stint drift: early-stint baseline minus this lap's mean local-minimum (corner-apex) speed. Positive = slow points getting slower vs own baseline. NULL if no telemetry. |
| `traction_wheelspin_proxy` | `double` | Yes | | Share of corner-exit full-throttle samples with non-positive accel (wheelspin proxy, 0–1) |
| `throttle_trace_decay` | `double` | Yes | | Within-stint drift of full-throttle fraction (early-stint baseline minus this lap) |
| `braking_point_drift_m` | `double` | Yes | | Within-stint drift: early-stint baseline minus this lap's mean brake-onset distance. Positive = braking earlier than own baseline. NULL if no telemetry. |
| `lift_coast_share` | `double` | Yes | | Off-throttle, non-braking, decelerating share of the lap (0–1). CONFOUND with fuel-saving consumed alongside int\_lap\_fuel\_state, not equated with degradation. |
| `fuel_mass_kg` | `double` | Yes | | Estimated fuel mass on board at this lap |
| `event_flag_any` | `boolean` | No | | TRUE if any race event contaminated this lap (SC, VSC, restart, etc.) |
| `cliff_candidate_flag` | `boolean` | Yes | | TRUE if this lap shows a MAD-score cliff spike consistent with tyre cliff. Removed from ML feature contract by 08j (2026-09-09): ruled dead on both substrates by 08g (carried no information in any family). Retained in mart for audit and historical reference; not consumed by current ML features. |
| `anomaly_class` | `varchar` | Yes | | Anomaly classification (clean\_cliff, mistake, event\_driven, conditions, normal) |
| `is_rain_lap` | `boolean` | Yes | | TRUE if rainfall was detected on this lap |
| `surface_bulk_ratio` | `double` | Yes | | C3 feature (42nd): ratio of surface thermal load to total thermal load (cumulative\_push\_load\_surface / (surface + bulk)). NULL when both loads are zero. Helps the model distinguish early-stint surface-dominated warming from bulk-driven structural degradation. |
| `survival_weight` | `double` | Yes | | C2 metadata (not a feature): IPW weight = 1 / P(stint reaches lap\_in\_stint \| compound), clipped to \[0.25, 4]. Used by train.py for quantile regressor sample weighting to correct for survivorship bias (degraded stints pitted early are under-represented at high lap\_in\_stint values). |
| `next_lap_degradation_jump_detrended_s` | `double` | Yes | | C1 PRIMARY target: per-lap change in driver skill residual with per-stint linear drift removed. drift\_s\_per\_lap (OLS slope on pre-cliff laps, Step 0 median -0.072 s/lap) is subtracted so fuel-lightening and track-evolution leaks are cancelled. Bounded \[-10, 10]. NULL on last lap of each stint. |
| `next_lap_degradation_jump_s` | `double` | Yes | | Legacy target (undetrended): change in driver skill residual on the next lap, bounded \[-10, 10]. Kept alongside the detrended primary for gate comparison. NULL on last lap. |
| `next_3_lap_cumulative_jump_s` | `double` | Yes | | Cumulative detrended degradation jump over the next 3 laps: SUM over i=1..3 of (residual(t+i) - residual(t) - i \* drift\_s\_per\_lap), i.e. the current residual is subtracted once per horizon step and per-stint drift is removed on the same schedule as next\_lap\_degradation\_jump\_detrended\_s. Signed and bounded \[-30, 30] (the per-lap +/-10 s bound scaled by the horizon). NULL unless laps t+1..t+3 are all present in the stint -- the guard is on true lap offsets, not row offsets. |
| `next_5_lap_cumulative_jump_s` | `double` | Yes | | As next\_3\_lap\_cumulative\_jump\_s over a 5-lap horizon: SUM over i=1..5 of (residual(t+i) - residual(t) - i \* drift\_s\_per\_lap). Signed and bounded \[-50, 50]. NULL unless laps t+1..t+5 are all present in the stint. |
| `laps_until_cliff_class` | `varchar` | Yes | | Bucket: 0\_to\_2, 3\_to\_5, 6\_plus, none\_in\_stint. Laps until the FIRST crossing of the >1.0s detrended jump threshold, scanned over every remaining lap of the stint at true lap offsets. The buckets partition the horizon exactly as their names read -- 6\_plus is 6-or-more, not exactly 6, and none\_in\_stint means no crossing anywhere in the remaining stint. NULL on the last lap of a stint, where there is no horizon to scan. |
| `is_training_eligible` | `boolean` | No | | TRUE if this lap is suitable for model training (age\_in\_stint > 3, no anomaly) |