DaviNeg/Alzheimer_Clinical_Predictor

Alzheimer Clinical Predictor

Modelo Gradient Boosting para classificação binária em dados tabulares do Alzheimer's Disease Dataset. É um artefato de um projeto acadêmico da Universidade de Brasília, disponibilizado para estudo e reprodução. Não foi validado clinicamente e não deve ser usado para diagnóstico, triagem ou decisões sobre pacientes.

O arquivo para baixar é model/model.pkl. Seu SHA-256 e a origem exata estão em model/provenance.json. A entrada exigida é descrita em model/feature_schema.json. Não se trata de um modelo Transformers nem de um fine tuning de um modelo pré-treinado; o algoritmo foi ajustado por busca de hiperparâmetros sobre um conjunto tabular.

Resumo

Item	Informação
Tarefa	Classificação binária; Diagnosis=1 indica diagnóstico registrado no conjunto de dados
Algoritmo	sklearn.ensemble.GradientBoostingClassifier
Entrada	59 variáveis já preparadas, numéricas, na ordem do esquema
Saída	Probabilidade estimada para classe 1 e classe com limiar padrão de 0,5
Dados	2.149 registros; 760 positivos (35,4%) no arquivo preparado
Partição na etapa final	80% treino / 20% teste, estratificada, random_state=15
Treinamento	RandomizedSearchCV, 30 combinações, CV de 5 partes, otimização de recall
Ambiente original	Python 3.12.10, scikit-learn 1.7.2, NumPy 2.4.4, pandas 2.3.3

Baixar e executar

Instale Python 3.12, baixe este repositório ou só os arquivos necessários com huggingface_hub:

pip install -r requirements.txt
python inference.py dados_preparados.csv --output predicoes.csv

O CSV de entrada deve ter exatamente as 59 colunas de model/feature_schema.json (sem Diagnosis, PatientID ou DoctorInCharge). O programa reordena as colunas conforme o treinamento e rejeita campos faltantes, extras, nulos ou não numéricos. A saída contém probability_class_1 e predicted_class. Essas probabilidades não foram calibradas para representar risco clínico individual. O limiar de 0,5 é o padrão do classificador e não foi validado para uso clínico.

Para baixar apenas os arquivos de inferência:

from huggingface_hub import snapshot_download

snapshot_download(
    repo_id="DaviNeg/Alzheimer_Clinical_Predictor",
    local_dir="alzheimer_model",
    allow_patterns=["model/*", "inference.py", "pipeline.py", "requirements.txt"],
)

Depois, execute python alzheimer_model/inference.py dados_preparados.csv. O pipeline.py implementa a interface genérica de classificação tabular do Hub, caso haja um serviço de inferência compatível. A presença desse arquivo não significa que exista um provedor de inferência ativo.

model.pkl usa cloudpickle, que pode executar código ao ser carregado. Carregue apenas artefatos de origem confiável e confira o SHA-256 publicado. O ambiente deve ser compatível com as versões em requirements.txt.

Dados e preparação

O conjunto de dados original, atribuído a Rabie El Kharoua, contém 2.149 linhas e 35 colunas. O CSV original e os CSVs intermediários não são redistribuídos aqui. Consulte a página do conjunto de dados para seus termos de uso. O repositório do projeto contém os notebooks e o arquivo preparado usado no treinamento.

A sequência documentada no repositório de origem, commit 432f8ff é:

1. nulos_imputacao.ipynb: remove identificador e campo do médico; aplica IterativeImputer às variáveis contínuas.
2. outliers.ipynb: analisa anomalias e remove linhas com escore Z absoluto acima de 3,5. O arquivo resultante mantém 2.149 linhas.
3. codificacao_categorica.ipynb: codificação one hot de etnia e escolaridade, omitindo a primeira categoria.
4. feature_engineering.ipynb: cria 23 variáveis derivadas, incluindo medidas hemodinâmicas, lipídicas, cognitivas e interações. Alguns índices têm nomes clínicos, mas aqui são apenas implementações do notebook e não escores clínicos validados.
5. normalizacao_exportacao.ipynb: aplica RobustScaler às colunas não binárias e exporta data/processed/alzheimers_prepared.csv.

O modelo recebe essas 59 variáveis após todas as etapas. O pacote publicado não inclui os objetos ajustados de imputação e escala, nem os parâmetros necessários para reconstruí-los fielmente a partir de uma linha bruta. Por isso, não passe valores clínicos brutos diretamente ao modelo. Para reproduzir uma entrada compatível, execute os notebooks sobre o conjunto de dados original, na mesma sequência, ou use o CSV preparado do projeto de origem. O arquivo preparado é identificado no manifesto pelo SHA-256 d907a826103e787ec80f62f9700f8b343221c890ebdae60b6a681c8b6da51aca.

Treinamento e escolha do artefato

O notebook de seleção comparou nove classificadores com validação cruzada estratificada em 10 partes. Outro notebook de seleção e otimização testou seleção de variáveis e RandomizedSearchCV sobre cinco famílias de modelo. Esses experimentos são anteriores à etapa final de calibração e não são métricas de teste do artefato aqui publicado.

Na etapa final, os dados preparados foram divididos com train_test_split(test_size=0.2, stratify=y, random_state=15). Para Gradient Boosting, a busca aleatória explorou n_estimators em {100, 200, 300, 400, 500}, learning_rate em {0.01, 0.05, 0.1, 0.2}, max_depth em {3, 5, 7, 10}, min_samples_split em {2, 5, 10} e subsample em {0.7, 0.8, 0.9, 1.0}. Foram 30 combinações aleatórias (random_state=15) com CV de 5 partes e recall como critério.

O artefato escolhido corresponde ao run MLflow 3eb740ec9a7c4cc585edc7442805e361 / modelo m-47d3d9724f9843e8b0a0e0c52f092330. Os melhores hiperparâmetros registrados foram n_estimators=200, learning_rate=0.2, max_depth=7, min_samples_split=5, subsample=0.9 (random_state=15). O Random Forest otimizado teve recall de teste inferior no mesmo registro (0,8750), e o SVM, 0,7566. O objeto serializado é o estimador já ajustado, copiado sem retreinamento.

Resultados registrados

Avaliação do Gradient Boosting	Recall
Média da CV interna de 5 partes no treino	0,9227
Teste de 20%, limiar padrão de 0,5	0,8882

Esses valores vêm dos registros MLflow e da saída do notebook de origem. O notebook também escolheu um limiar aproximado de 0,004810 usando o próprio conjunto de teste, atingindo recall 0,9145 e acurácia 0,9186 naquele conjunto. Essa escolha contamina a avaliação do limiar; esses números não são uma estimativa independente de desempenho futuro. Por esse motivo, o código de inferência publica o limiar padrão de 0,5. Não há aqui validação externa, intervalos de confiança, avaliação por subgrupos, calibração de probabilidades nem estudo prospectivo.

Limitações e uso responsável

• Imputação, engenharia de atributos com estatísticas globais e escala foram aplicadas antes da divisão treino/teste. Isso cria risco de vazamento de informação e pode superestimar a avaliação.
• O conjunto de dados é pequeno e sua representatividade para pacientes de UBS no Brasil não foi demonstrada. Desempenho em outras populações, equipamentos e fluxos de coleta é desconhecido.
• Diversas entradas incluem avaliações cognitivas e funcionais, como MMSE, ADL e FunctionalAssessment. Uma eventual associação com o rótulo do conjunto não comprova capacidade de detecção precoce independente dessas avaliações.
• Os valores de importância de variáveis de modelos de árvores não explicam causalidade nem a razão de uma predição individual.
• O modelo e os escores derivados são material educacional. Qualquer aplicação clínica exigiria revisão dos dados, pré-processamento sem vazamento, validação externa e supervisão clínica e regulatória.

Proveniência e licença

Projeto original: ArtyMend07/alzheimer-clinical-predictor. Equipe: Gabriel Guedes Fernandes, Artur Mendonça Arruda, João Marcelo Guimarães Costa Naves, Júlia Santana Campos e Davi Monteiro de Negreiros. O repositório original inclui licença MIT; sua cópia acompanha o código e o artefato aqui distribuídos. Os direitos e termos do conjunto de dados original devem ser verificados na fonte.