Create README.md

README.md

@@ -0,0 +1,127 @@
+# BoneCheck
+
+**BoneCheck** é um sistema de inteligência artificial para detecção precoce de osteopenia e osteoporose a partir de radiografias panorâmicas, exames comuns na odontologia. Utilizando redes neurais convolucionais (CNNs) e fusão de predições via XGBoost, o modelo permite identificar sinais da doença de forma rápida, acessível e não invasiva — com potencial para triagem populacional em larga escala, especialmente em regiões com acesso limitado a exames de densitometria óssea.
+
+Fornecemos tanto os pesos do modelo final (XGBoost) quanto dos modelos intermediários baseados em redes neurais (CNNs e ViTs) usados para gerar representações usadas para treinar o modelo resultante.
+
+## Detalhes do Modelo
+
+### Descrição
+
+* **Desenvolvido por:** [Gabriel Merlin](https://www.linkedin.com/in/gabrielcmerlin), [André De Mitri](https://www.linkedin.com/in/pedroamdelgado), [Ademir Guimarães](https://www.linkedin.com/in/ademir-guimaraes), [Matheus Giraldi](https://www.linkedin.com/in/matheus-giraldi-alvarenga-b2b856217), [Matheus Lenzi](https://www.linkedin.com/in/matheus-lenzi-dos-santos), [Yasmin Oliveira](https://www.linkedin.com/in/yasmin-victoria-oliveira)
+* **Parceria institucional:** Faculdade de Odontologia de Ribeirão Preto – USP (FORP-USP), com participação dos Prof. Dr. Plauto Watanabe e Dra. Luciana Munhoz
+* **Tipo do modelo:** XGBoost
+* **Correspondência:** [raia.projetos@gmail.com](mailto:raia.projetos@gmail.com), [gabrielcmerlin@gmail.com](mailto:gabrielcmerlin@gmail.com)
+
+### Fontes
+
+* **Repositório:** [https://github.com/gruporaia/BoneCheck](https://github.com/gruporaia/BoneCheck)
+
+## Usos
+
+BoneCheck é destinado a auxiliar profissionais da saúde (especialmente dentistas e clínicos gerais) na triagem de osteoporose a partir de exames rotineiros. O modelo pode ser usado para:
+
+* Triagem automatizada de risco em radiografias odontológicas;
+* Apoio a pesquisas em IA aplicada à saúde óssea;
+* Ensino e validação de soluções em medicina diagnóstica assistida por IA.
+
+## Viéses, Riscos e Limitações
+
+* **Vieses nos dados:** O desempenho pode variar de acordo com a qualidade das imagens e diversidade do conjunto de dados de treino, que pode não representar todas as populações.
+* **Risco de uso indevido:** O modelo **não substitui diagnóstico médico**. Seu uso deve ser acompanhado por um profissional da saúde.
+* **Limitações técnicas:** A performance depende da padronização da imagem (posição da mandíbula, contraste, etc.).
+
+## Como Usar
+
+```python
+from huggingface_hub import hf_hub_download
+import xgboost as xgb
+
+REPO_ID = "RAIA-BRASIL/bonecheck_xgboost"
+FILENAME = "xgb_model.json" 
+
+# baixar o arquivo do modelo do Hugging Face Hub
+model_path = hf_hub_download(repo_id=REPO_ID, filename=FILENAME)
+
+model = xgb.XGBClassifier()
+model.load_model(model_path)
+```
+
+## Detalhes do treinamento
+
+### Dados de Treino
+
+* Radiografias panorâmicas fornecidas pela FORP-USP, rotuladas por especialistas em três categorias: **Saudável**, **Osteopenia** e **Osteoporose**.
+
+### Procedimento
+
+#### Pré-processamento
+
+* Redimensionamento e padronização
+* Extração de regiões de interesse (ROI)
+* Normalização e balanceamento
+* Divisão treino/teste com validação estratificada
+
+#### Hiperparâmetros
+
+Hiperparâmetros usados para o treinamento do XGBoost:
+```json
+    "best_params": {
+        "colsample_bytree": 0.85,
+        "gamma": 1,
+        "learning_rate": 0.02,
+        "max_depth": 2,
+        "min_child_weight": 1,
+        "n_estimators": 25,
+        "subsample": 0.7
+    }
+```
+
+Hiperparâmetros usados para o treinamento das redes neurais (CNNs e ViTs):
+
+```json
+    "best_params" : {
+        "lr": 1e-4,
+        "batch_size": 64,
+        "optimizer": "Adam", # Adam para CNNs | AdamW para ViTs
+        "n_epochs": 100,
+    }
+```
+
+OBS: os hiperparâmetros escolhidos são resultantes de uma tunagem de feita usando GridSearch.
+
+### Infraestrutura computacional
+
+#### Hardware
+
+* 1x GPU (V100)
+* Linux (Ubuntu 22)
+
+#### Software
+
+* Python, PyTorch, TensorFlow, XGBoost, Streamlit
+
+## Avaliação
+
+### Dados de Teste & Métricas
+
+#### Métricas utilizadas
+
+* Acurácia
+* Precisão
+* Recall
+* F1-Score
+
+### Resultados
+
+| Modelo                 | Acurácia  | Precisão  | Recall    | F1-Score  |
+| ---------------------- | --------- | --------- | --------- | --------- |
+| ConvNeXT               | 0.688     | 0.651     | 0.631     | 0.638     |
+| EfficientNet           | 0.558     | 0.608     | 0.605     | 0.512     |
+| DeiT                   | 0.688     | 0.648     | 0.635     | 0.639     |
+| Swin Transformer       | 0.632     | 0.591     | 0.622     | 0.590     |
+| **Ensemble (XGBoost)** | **0.697** | **0.712** | **0.622** | **0.838** |
+
+## Agradecimentos
+
+Agradecimentos especiais aos membros do grupo **RAIA (Rede de Avanço em Inteligência Artificial)** do ICMC-USP São Carlos, aos professores parceiros da FORP-USP (Dra. Luciana Munhoz e Dr. Plauto Watanabe), e à comunidade de código aberto que apoia o desenvolvimento de ferramentas em IA na saúde.