BR-Risk-ML

Classificador multiclasse da gravidade de acidentes rodoviários registrados nas rodovias federais brasileiras, desenvolvido com XGBoost e dados públicos da Polícia Rodoviária Federal (PRF).

Versão do projeto: 1.0.0
Autor: Fellype Moura
Código-fonte: GitHub — llype-ENG/br-risk-ml
Modelo: Hugging Face — fellype-dev-ai/br-risk-ml

Escopo importante: este modelo classifica registros de acidentes que já ocorreram. Ele não prevê quando ou onde um acidente acontecerá e não estima o risco de acidentes em locais sem registros.

Resumo

O BR-Risk-ML utiliza registros históricos da PRF para classificar cada ocorrência em uma das três classes:

Com Vítimas Fatais
Com Vítimas Feridas
Sem Vítimas

O artefato publicado é um pipeline do scikit-learn contendo o pré-processamento e o estimador XGBoost. O arquivo serializado é br_risk_xgboost.joblib.

Uso pretendido

O modelo foi desenvolvido para:

estudo e experimentação em classificação multiclasse;
análise retrospectiva de registros de acidentes rodoviários;
demonstração de um fluxo de Machine Learning com dados tabulares;
investigação de desempenho por classe e interpretação de modelos.

Não foi desenvolvido ou validado para decisões operacionais em tempo real, despacho de emergência, fiscalização, precificação de seguros ou decisões que afetem diretamente pessoas.

Dados e treinamento

Os dados de origem são registros públicos de acidentes da PRF, referentes ao período de 2017 a 2025, agrupados por ocorrência.

Fontes:

O artefato atual foi treinado com 486.974 registros de 2017 a 2023. Dez registros sem variável-alvo foram removidos antes da modelagem.

Variáveis de entrada

Tipo	Variáveis
Categóricas	`tipo_acidente`, `causa_acidente`, `fase_dia`
Numéricas	`pessoas`, `veiculos`, `latitude`, `longitude`

Colunas que revelam diretamente a classificação ou seus componentes — incluindo classificacao_acidente, mortos, feridos, feridos_leves, feridos_graves, ilesos e ignorados — foram excluídas das entradas do modelo.

O pré-processamento inclui imputação numérica pela mediana, preenchimento de categorias ausentes, codificação one-hot e tratamento de categorias raras e desconhecidas.

Configuração do XGBoost

Parâmetro	Valor
`max_depth`	8
`learning_rate`	0.1
`n_estimators`	400
`min_child_weight`	3
`subsample`	0.8
`colsample_bytree`	0.8
`reg_lambda`	1
`random_state`	42

O treinamento utiliza a raiz quadrada dos pesos balanceados por classe. Após o treinamento, a implementação aplica multiplicadores de score: 0.978 para fatais, 1.000 para feridos e 1.118 para sem vítimas.

Resultados de avaliação

Avaliação temporal diagnóstica — 2024–2025

Métrica	Resultado
Registros	145.729
Accuracy	0.7567
F1 Macro	0.5726
Balanced Accuracy	0.5753

Classe	Precision	Recall	F1-score	Suporte
Com Vítimas Fatais	0.3840	0.4321	0.4067	10.434
Com Vítimas Feridas	0.8458	0.8507	0.8482	112.375
Sem Vítimas	0.4847	0.4432	0.4630	22.920

Matriz de confusão — linhas = classe real; colunas = classe prevista:

Classe real / prevista	Fatais	Feridas	Sem vítimas
Com Vítimas Fatais	4.509	5.178	747
Com Vítimas Feridas	6.723	95.601	10.051
Sem Vítimas	509	12.254	10.157

Comparação com baseline

Uma DummyClassifier(strategy="most_frequent") obteve F1 Macro de 0.2903, Accuracy de 0.7711 e Balanced Accuracy de 0.3333 no mesmo conjunto diagnóstico. O XGBoost obteve F1 Macro de 0.5726 e Balanced Accuracy de 0.5753. A baseline sempre prevê a classe majoritária, o que explica sua acurácia mais alta, apesar de não identificar as classes minoritárias.

Ressalva essencial sobre avaliação

O período 2024–2025 não foi usado para treinar o artefato atual, mas já foi consultado em experimentos anteriores durante o desenvolvimento. Portanto, esses números são uma avaliação temporal diagnóstica da configuração atual e não constituem um holdout independente e intocado.

O ano de 2023 participou da seleção e otimização e também foi incluído no treinamento do artefato final. Por isso, a métrica anteriormente observada em 2023 (F1 Macro = 0.6143) é in-sample, e não deve ser interpretada como desempenho independente.

Interpretabilidade e diagnóstico

As análises de interpretabilidade e erros foram feitas como diagnóstico do artefato atual.

Importância por Gain

Participação no Gain agregado às variáveis originais:

Variável	Participação
`tipo_acidente`	42.93%
`causa_acidente`	12.47%
`pessoas`	12.40%
`latitude`	11.49%
`longitude`	9.85%
`veiculos`	6.70%
`fase_dia`	4.16%

SHAP global

Média dos valores absolutos de SHAP, agrupando as colunas one-hot por variável original, em uma amostra de 2.000 registros:

Variável	Mean absolute SHAP
`causa_acidente`	2.3133
`tipo_acidente`	1.2088
`latitude`	0.4349
`longitude`	0.3917
`fase_dia`	0.3264
`veiculos`	0.2514
`pessoas`	0.1675

Gain e SHAP medem aspectos diferentes do modelo e podem apresentar ordenações distintas. Os valores SHAP explicam as saídas internas do XGBoost antes dos multiplicadores aplicados posteriormente pela regra de decisão.

Erros na classe fatal

No conjunto diagnóstico de 2024–2025, o modelo identificou corretamente 4.509 de 10.434 acidentes fatais (recall de 0.4321). Outros 5.178 foram classificados como acidentes com feridos e 747 como acidentes sem vítimas.

Colisão traseira, saída de leito carroçável e colisão transversal concentraram, juntas, 50.64% dos falsos negativos fatais. O recall fatal variou bastante por tipo: 85.01% em colisões frontais, 81.22% em atropelamentos de pedestres e 7.39% em colisões transversais.

Essas diferenças descrevem padrões observados nos dados avaliados. Não demonstram causalidade nem garantem o mesmo comportamento em outros períodos ou populações.

Como baixar o artefato

from huggingface_hub import hf_hub_download
import joblib

model_path = hf_hub_download(
    repo_id="fellype-dev-ai/br-risk-ml",
    filename="br_risk_xgboost.joblib",
)

artifact = joblib.load(model_path)

pipeline = artifact["pipeline"]
classes = artifact["classes"]
features = artifact["features"]

print("Features:", features)
print("Classes:", classes)

O objeto pipeline contém o pré-processamento e o estimador. Para reproduzir a regra de decisão usada no projeto, incluindo os multiplicadores por classe, consulte predict.py no repositório de código.

Importante: não use diretamente os scores brutos do pipeline como se fossem a saída final do projeto. A implementação de inferência aplica uma etapa adicional de ajuste por classe e normalização. Mesmo após esse ajuste, os scores não são probabilidades calibradas.

Limitações, riscos e vieses

Classificação retrospectiva: as entradas descrevem acidentes já registrados. O modelo não prevê a ocorrência de acidentes.
Disponibilidade das informações: causa e tipo do acidente, número de pessoas e número de veículos podem depender do registro ou da investigação posterior. Isso limita qualquer interpretação de uso em tempo real.
Desbalanceamento: o desempenho é melhor para a classe Com Vítimas Feridas; as classes Com Vítimas Fatais e Sem Vítimas apresentam desempenho inferior.
Representatividade: padrões históricos da PRF podem refletir diferenças regionais, temporais e de registro. Não há garantia de desempenho uniforme por UF, tipo de rodovia ou grupo.
Sem inferência causal: importância de variáveis e valores SHAP não indicam causalidade.
Sem dados de exposição: a base contém registros de acidentes, mas não observações completas de locais e períodos sem acidentes ou denominadores de exposição ao tráfego. Não é possível estimar diretamente o risco de ocorrência.
Avaliação não independente: 2023 participou do desenvolvimento e treinamento final; 2024–2025 foi consultado em experimentos anteriores.
Uso de alto impacto: o modelo não deve ser usado isoladamente para decisões de segurança pública, emergência, fiscalização, seguros ou decisões sobre indivíduos.

Formato e segurança do artefato

O modelo é disponibilizado como arquivo Python joblib. Arquivos serializados podem executar código durante a desserialização. Baixe e carregue o artefato somente de uma fonte confiável e em ambiente controlado. A compatibilidade depende das versões de Python e das bibliotecas usadas no treinamento.

Licença

O código e a documentação originais do projeto estão sob licença MIT. Essa licença não concede automaticamente direitos sobre os dados da PRF ou bibliotecas de terceiros. Consulte as condições das fontes originais.

Referências

Downloads last month: -