Skip to main content

Data Models

types.py defines Patito models for DataFrame schemas and Pydantic models for pipeline inputs and results. TakeRateContextStore.get(key, schema) validates a dataset against the supplied Patito model.

PipelineStatus​

MatrixSupplyModel uses PipelineStatus to choose an inventory projection. MercedesDealerInventoryLoader maps Netstar status codes to these values.

ValueMeaningNetstar codes
ON_LOTAvailable on the dealer lotINV
IN_PRODUCTIONIn productionIP
IN_TRANSITIn transit to the dealerOTW, PNS
AT_PROCESSINGAt a vehicle processing centerVPC

See MatrixSupplyModel for the probability calculations.

DataFrame Models​

DealerInventory​

One row per inventory vehicle.

ColumnTypeMeaning
order_idstrUnique vehicle order identifier
model_idstrModel identifier
model_yearstrModel year
production_datestrISO-format production date
order_statusstrA PipelineStatus value
days_in_statusintDays in the current status

MatrixSupplyModel uses the status and elapsed time to choose and condition each vehicle's probability curve.

ModelDol​

Days-on-lot distribution parameters, with one row per model.

ColumnTypeMeaning
model_idstrUnique model identifier
weibull_shapefloatWeibull shape parameter
weibull_scalefloatWeibull scale parameter

CategoryDit​

Arrival distribution parameters, with one row per model.

ColumnTypeMeaning
model_idstrUnique model identifier
burr12_cfloatBurr Type XII c parameter
burr12_dfloatBurr Type XII d parameter
burr12_locfloatBurr Type XII location parameter
burr12_scalefloatBurr Type XII scale parameter

AttributeScoringStats​

Demand take rates, with one row per (dealer_id, model_id, attribute_type, attribute_value).

ColumnTypeMeaning
dealer_idstrDealer identifier
model_idstrModel identifier
attribute_typestrAttribute type
attribute_valuestrAttribute value
demand_take_ratefloat | NoneDemand take rate for the attribute

DemandSupplyGapScorer reads these rates. Contribution margins use the separate attribute_contribution_margin dataset.

AttributeWeights​

Scoring weights, with one row per (model_id, attribute_type).

ColumnTypeMeaning
model_idstrModel identifier
attribute_typestrAttribute type
attribute_weightfloatWeight for this attribute type

Pydantic Models​

SelectionScope​

The dealer and model being scored, with optional analysis and production dates.

FieldTypeMeaning
dealer_codestrThe OEM's dealer code, such as Stellantis 24028
model_idstrModel identifier
datestr | NoneISO-format analysis date; day zero for inventory curves
production_datestr | NoneISO-format expected production date of the candidate order

MatrixSupplyModel.compute() requires date. Its candidate-curve calculation also requires production_date. DirectRateProvider does not use either date.

For a configuration with iceberg_tables, the pipeline looks up dealer_code in the dealers table, <oem>/<market>/consolidated/dealers. It filters every table keyed by dealer on the dealer_id that the lookup returns. The BigQuery datasets of the other configurations name the OEM dealer code dealer_id. The pipeline filters those datasets by comparing that column to dealer_code, without a lookup.

NormalizedCandidate and CandidateAttribute​

See Normalization for candidate fields and source mappings.

CandidateOption​

An option line item attached to a recommendation after selection.

FieldTypeDefaultMeaning
option_idstrRequiredThe feature's option_code
namestr | NoneNoneDisplay name
pricefloat | NoneNoneOption price
subcategorystr | NoneNoneSource subcategory
is_configurablebool | NoneNoneSource configurable flag
shown_on_orderbool | NoneNoneSource shown-on-order flag
is_electiveboolTrueWhether the dealer can select the option

RecommendationMetadata​

Diagnostics for one recommendation, requested through include_metadata=True.

FieldTypeMeaning
dealer_codestrThe scope's OEM dealer code
dealer_idstr | NoneThe dealer's key in consolidated/dealers; None for a configuration without iceberg_tables
model_idstrThe scope's model
production_datestr | NoneThe scope's production date
candidate_idstrRecommended candidate
candidate_attributeslist[RecommendationAttribute]Take rates for each attribute of the candidate
misalignment_by_attribute_typelist[MisalignmentByAttributeType]Sum of the absolute demand-supply differences per attribute type
final_scorefloatCombined selection score
scorer_outputslist[ScorerOutput]Each scorer's score and rank
cnt_pre_restriction_pruneintNumber of candidates before rescope removed the ones that its production restrictions exclude
cnt_post_restriction_pruneintNumber of candidates that remain after rescope
production_restrictionslist[AttributeRestriction]The production restrictions passed to rescope

RecommendationAttribute​

Attribute statistics in RecommendationMetadata.candidate_attributes, with one row per (attribute_type, attribute_value) on the selected candidate.

FieldTypeMeaning
attribute_typestrAttribute type
attribute_valuestrAttribute value
supply_take_ratefloat | NoneAttribute supply take rate
demand_take_ratefloat | NoneAttribute demand take rate
attribute_weightfloat | NoneAttribute type's weight
rankint | NoneRank within the type by descending demand-supply gap, starting at one
num_values_in_typeint | NoneNumber of codes for this type

Recommendation​

One result per selected candidate.

FieldTypeMeaning
candidateNormalizedCandidateSelected candidate
iterationintSelection round; WeightedAverageSelection sets it to one
scorefloatCombined selection score
module_scoreslist[ModuleScore]Each scorer's output column name and raw score
metadataRecommendationMetadata | NoneDiagnostics requested through include_metadata=True

SupplyMatrix​

Daily supply estimates for inventory vehicles. MatrixSupplyModel and SimulationSupplyModel estimate on-lot probabilities. MLCDFSupplyModel uses clip(1 - sale_CDF(d), 0, 1), the probability that a vehicle has not sold. See the MLCDFSupplyModel design.

FieldTypeMeaning
model_idstrModel identifier
horizon_startintFirst day offset
horizon_daysintNumber of daily probability columns
matrixpl.DataFrameOne row per vehicle, identified by order_id; day_<offset> columns contain probabilities