DeliveryETA / README.md
AdryanAzul's picture
Upload folder using huggingface_hub
bb37757 verified
|
Raw History Blame Contribute Delete
6.9 kB
---
language:
- pt
license: mit
library_name: scikit-learn
tags:
- tabular-regression
- delivery-eta
- histgradientboosting
- scikit-learn
metrics:
- mae
- rmse
- r2
---
# DoorDash Delivery ETA Prediction (`HistGradientBoostingRegressor`)
> **AVISO IMPORTANTE:** Este modelo é **experimental** e **não está pronto para uso em produção real**. Trata-se de um modelo conservador de referência treinado exclusivamente com atributos confirmados no momento da criação do pedido, apresentando `R² = +0,0288` no conjunto de teste.
## Descrição e Objetivo
Pipeline de Machine Learning (`ColumnTransformer` + `HistGradientBoostingRegressor`) desenvolvido para prever a duração total de entrega de pedidos de delivery (`delivery_duration_minutes`) a partir de informações disponíveis no momento do checkout.
- **Repositório de código e notebooks (GitHub):** https://github.com/CarvalhoAdryan/DeliveryETA
- **Artefato do modelo:** `final_hgb_eta_pipeline.joblib`
---
## Dataset e Origem
- **Origem:** `historical_data.csv` disponibilizado pela **StrataScratch** no exercício *DoorDash Delivery Duration Prediction* (`197.428` linhas × `16` colunas originais; `197.421` válidas após remoção de `7` registros sem `actual_delivery_time`).
- **Redistribuição:** O dataset bruto **não é redistribuído** neste repositório.
- **Variável-alvo:** `delivery_duration_minutes = (actual_delivery_time - created_at).dt.total_seconds() / 60.0`.
---
## Features Utilizadas (`21` variáveis confirmadas)
O modelo utiliza exclusivamente atributos com disponibilidade confirmada no instante de criação do pedido (`store_id` foi excluído do One-Hot Encoding por alta cardinalidade — `6.743` níveis — e variáveis operacionais/rota de disponibilidade incerta foram mantidas fora do modelo conservador):
- **Metadados (One-Hot Encoding):** `market_id`, `store_primary_category`, `order_protocol`, `created_time_block`
- **Carrinho e valores:** `total_items`, `subtotal`, `num_distinct_items`, `min_item_price`, `max_item_price`, `average_item_price`, `item_price_range`, `invalid_item_price_range`, `distinct_item_ratio`, `is_single_item`, `is_large_order`
- **Temporais (horário registrado, aparente UTC):** `created_hour`, `created_dayofweek`, `created_month`, `created_is_weekend`
- **Histórico causal e protocolo:** `estimated_order_place_duration`, `historical_store_order_count`
---
## Algoritmo, Hiperparâmetros e Validação Temporal
- **Algoritmo:** `sklearn.ensemble.HistGradientBoostingRegressor`
- **Hiperparâmetros congelados (Etapa 06.2):**
- `loss="absolute_error"` (escolhida para robustez a outliers `> 24h` sem excluí-los do treino)
- `learning_rate=0.08`
- `max_iter=20` (definido via validação interna temporal 90/10 dentro do treino)
- `max_leaf_nodes=63`
- `min_samples_leaf=30`
- `l2_regularization=0.0`
- `early_stopping=False`
- `random_state=42`
- **Divisão Temporal com Embargo (Etapa 05, cortes às `10:00:00` UTC):**
- **Treino:** `138.572` registros (`created_at < 2015-02-10 10:00:00`, entregas concluídas antes do corte)
- **Validação:** `28.808` registros (`2015-02-10 10:00:00` a `2015-02-14 10:00:00`)
- **Teste (isolado até a Etapa 07):** `30.041` registros (`created_at >= 2015-02-14 10:00:00`)
---
## Resultados (Validação e Teste Final)
| Conjunto | Modelo | MAE (min) | RMSE (min) | MedAE (min) | P90_AE (min) | R² | Mean Bias |
| :--- | :--- | ---: | ---: | ---: | ---: | ---: | ---: |
| **Validação** (`n=28.808`) | Baseline (Median) | 12,8201 | 18,6790 | 9,9000 | 25,6667 | -0,0341 | -3,3927 |
| **Validação** (`n=28.808`) | **HGB Congelado** | **12,1142** | **17,9219** | **9,2317** | **24,7196** | **+0,0480** | -2,8943 |
| **Teste** (`n=30.041`) | Baseline (Median) | 14,1955 | 38,1036 | 10,4667 | 29,0833 | -0,0195 | -5,2643 |
| **Teste** (`n=30.041`) | **HGB Congelado** | **12,7797** | **37,1903** | **9,2282** | **25,9125** | **+0,0288** | -4,6494 |
- **Ganho sobre o baseline no teste:** `-9,97%` em MAE (`-1,4158 min`), `-11,83%` em MedAE (`-1,2385 min`), `-10,90%` em P90_AE (`-3,1708 min`) e `-2,40%` em RMSE (`-0,9133 min`).
- **Tempo de treino:** `4,12 s` | **Inferência no teste (`30.041`):** `0,124 s`.
![Comparação Validação vs Teste](reports/figures/test_vs_val_comparison.png)
---
## Interpretabilidade
Por *Permutation Importance* na validação (`neg_mean_absolute_error`, `n=28.808`), as variáveis mais relevantes para reduzir o MAE foram:
1. `created_hour` (`+0,77159 min`)
2. `subtotal` (`+0,41535 min`)
3. `market_id` (`+0,13144 min`)
4. `created_dayofweek` (`+0,09240 min`)
5. `estimated_order_place_duration` (`+0,08987 min`)
*(Importância preditiva não implica causalidade.)*
![Permutation Importance](reports/figures/interp_permutation_importance.png)
---
## Limitações e Possíveis Aplicações
- **Limitações:**
- Baixo poder explicativo (`R² = +0,0288` no teste) por usar apenas atributos estáticos de checkout.
- Superestimação em entregas rápidas (`<= 30 min`: Mean Bias `+15,62 min` no teste) e forte subestimação em atrasos (`> 120 min`: Mean Bias `-135,20 min` no teste).
- Janela curta (~1 mês em 2015), timestamps em provável UTC sem fuso local por mercado e ausência de sinais em tempo real confirmados (congestionamento e distância de rota).
- **Aplicações adequadas:** Estudo de portfólio, referência de baseline conservador com validação temporal rigorosa e ponto de partida para uma v2 com variáveis operacionais validadas e *target encoding* causal por loja.
---
## Como Carregar e Prever
```python
import joblib
import pandas as pd
pipeline = joblib.load("final_hgb_eta_pipeline.joblib")
sample = pd.DataFrame([{
"market_id": "1",
"store_primary_category": "american",
"order_protocol": "1",
"total_items": 3,
"subtotal": 2500,
"num_distinct_items": 2,
"min_item_price": 600.0,
"max_item_price": 1200,
"estimated_order_place_duration": 446,
"created_hour": 2,
"created_dayofweek": 5,
"created_month": 2,
"created_is_weekend": 1,
"created_time_block": "00-05h_reg",
"average_item_price": 833.33,
"item_price_range": 600.0,
"invalid_item_price_range": 0,
"distinct_item_ratio": 0.6667,
"is_single_item": 0,
"is_large_order": 0,
"historical_store_order_count": 25,
}])
eta_minutes = pipeline.predict(sample)[0]
print(f"ETA previsto: {eta_minutes:.2f} minutos")
```
---
## Uso de Ferramentas de IA
Ferramentas de inteligência artificial foram utilizadas como apoio ao longo do desenvolvimento deste projeto nas atividades de pesquisa técnica, auxílio na escrita/depuração de código, discussão de resultados exploratórios e organização da documentação. Todas as decisões metodológicas, verificações de integridade e resultados foram validados diretamente pela execução real dos experimentos.