Skip to main content

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:

DatasetLoaderBigQuery table in bmw-prod-309117.dataform
vehicle_sale_cdfBMWSaleCDFLoaderpit_days_until_sale_inference
dealer_model_sale_cdfBMWDealerModelSaleCDFLoadersupply_days_until_sale_by_dealer_model
model_avg_sale_cdfBMWModelAvgSaleCDFLoadersupply_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.