MLCDFSupplyModel design
MLCDFSupplyModel builds a supply matrix from BMW sale predictions for each VIN.
The configuration selects it with supply_model.type: ml_cdf.
Sale predictions and arrival delay
The model uses this curve for every VIN in vehicle_sale_cdf, regardless of vehicle
status:
supply_curve(d) = clip(1 - sale_CDF(d), 0, 1)
The sale predictions account for arrival delay through input features such as
approx_ev_days_until_dealerarrival. Using the sale CDF alone preserves that delay
in the supply curve. A separate arrival CDF can reduce the supply weight of a
recently ordered vehicle below that of a vehicle that has been on the lot for a
long time. Stale arrival estimates can also distort the sale predictions.
The curve measures the probability that a vehicle has not sold. The supply model uses that probability as its estimate of future supply, including vehicles that have not reached the lot.
Input datasets
The BMW configuration is
packages/candidate_selection/src/candidate_selection/configs/bmw_ml_cdf.yaml.
It declares three sale-CDF datasets:
| Dataset | Loader | BigQuery table in bmw-prod-309117.dataform |
|---|---|---|
vehicle_sale_cdf | BMWSaleCDFLoader | pit_days_until_sale_inference |
dealer_model_sale_cdf | BMWDealerModelSaleCDFLoader | supply_days_until_sale_by_dealer_model |
model_avg_sale_cdf | BMWModelAvgSaleCDFLoader | supply_days_until_sale_by_model_avg |
The loaders read sold_within_n_days_cdf. Each element contains n_days and
prob_sold_within_n_days. They unpack the array in SQL and create columns day_0
through day_200 in Polars.
BMWSaleCDFLoader maps the source VIN field id to order_id. The configured
icc_table supplies model_id for filtering by dealer and model.
BMWInventoryCandidatesLoader uses the same sale table to select inventory VINs
and joins their attributes from inventory_candidate_configurations.
The aggregate loaders use the configured mapping_table to map BMW model_code
values to model_id. The dealer/model dataset has one row per dealer and model.
The model-average dataset has one row per model.
Supply filtering during model-year changes
Older inventory can lack features offered on new candidates. Including that inventory lowers the supply take rates for those features and can increase their recommendations.
For affected model_id values, set the same model_code_supply list and
mapping_table on the inventory_candidates and vehicle_sale_cdf loaders.
Both loaders then restrict those models to the model_code values in the mapping
table for the dealer and model. Matching filters keep the inventory attributes
and sale predictions consistent. vehicle_sale_cdf also requires icc_table
for this filtering.
The mapping table determines which model years are included; the filter does not
automatically select the latest year. Other models retain inventory from all
model years. Both lists are empty in bmw_ml_cdf.yaml, which disables this filter.
Supply matrix
compute() first selects an aggregate sale CDF for confirmed orders. It uses the
row for the scope's dealer and model. If that row is absent, it uses the model
average. It raises ValueError if neither dataset has an estimate for the model.
An invented zero CDF would assign full supply probability to every day.
The matrix contains one row per VIN in vehicle_sale_cdf. Its columns are
order_id and day_0 through day_364. Days 201 through 364 repeat the day-200
probability. A VIN absent from vehicle_sale_cdf contributes no matrix row or
supply weight. An empty vehicle dataset produces an empty matrix, provided an
aggregate estimate exists.
Confirmed orders
A confirmed order has no VIN-specific inference row. update_from_candidate()
uses the aggregate sale CDF selected by compute() and appends a matrix row under
the supplied order_id. It returns None if the matrix has not been computed.
compute_on_lot_curve() returns the same aggregate survival curve with 366
entries. It repeats the final predicted value beyond day 200. It returns zeros
before compute() has selected an aggregate estimate. Its model_id,
production_date, and scope_date arguments do not change the stored curve.
The model does not require a vehicle-status mapping or Weibull/Burr12 parameters.