Esta página documenta la estructura completa del proyecto, explicando el propósito de cada carpeta y módulo.
Árbol de Directorios proyectoia/ ├── data/ # Dataset (descargar de Kaggle) │ └── chest_xray/ │ ├── train/ │ │ ├── NORMAL/ │ │ └── PNEUMONIA/ │ └── test/ │ ├── NORMAL/ │ └── PNEUMONIA/ ├── models/ # Modelos entrenados │ ├── best_model.keras # Mejor modelo según validación │ └── final_model.keras # Modelo al final del entrenamiento ├── results/ # Gráficas y resultados │ ├── training_history.png # Evolución del entrenamiento │ ├── confusion_matrix.png # Matriz de confusión │ ├── roc_curve.png # Curva ROC y AUC │ └── predictions.png # Ejemplos de predicciones ├── src/ # Código fuente │ ├── model.py # Arquitectura CNN │ ├── data_loader.py # Carga de datos │ ├── train.py # Entrenamiento │ └── evaluate.py # Evaluación ├── main.py # Script principal ├── verificar_dataset.py # Verificador de dataset ├── PLANTEAMIENTO.md # Paso 1: Definición del problema ├── DISEÑO_MODELO.md # Paso 2: Arquitectura del modelo ├── INSTRUCCIONES_DATASET.md # Paso 3: Instrucciones del dataset ├── GUIA_COMPLETA.md # Guía completa de implementación ├── LEEME.md # Guía rápida en español ├── README.md # Documentación principal ├── Pipfile # Dependencias del proyecto └── Pipfile.lock # Versiones bloqueadas
Carpetas Principales data/
Dataset Contiene las radiografías de tórax descargadas de Kaggle. Tamaño : ~1.15 GBNo incluido en el repositorio - Debes descargarlo manualmente
Estructura esperada :data/chest_xray/ ├── train/ │ ├── NORMAL/ # 1,341 imágenes │ └── PNEUMONIA/ # 3,875 imágenes └── test/ ├── NORMAL/ # 234 imágenes └── PNEUMONIA/ # 390 imágenes
Total: 5,863 imágenes de rayos X de tórax en formato JPEG
models/
Modelos Entrenados Almacena los modelos de Keras entrenados durante la ejecución.
Archivos generados :Archivo Descripción Cuándo se genera best_model.kerasMejor modelo según validación Durante entrenamiento (checkpoint) final_model.kerasModelo al finalizar todas las épocas Al terminar entrenamiento
El archivo best_model.keras es el que se usa para evaluación, ya que tiene el mejor desempeño en el conjunto de validación.
results/
Visualizaciones Contiene todas las gráficas y resultados de evaluación.
Archivos generados : training_history.png
confusion_matrix.png
roc_curve.png
predictions.png
Gráficas de evolución durante el entrenamiento:
Loss (pérdida) en train y validación
Accuracy (precisión) en train y validación
Útil para identificar overfitting o underfitting. Matriz de confusión mostrando:
Verdaderos positivos (TP)
Verdaderos negativos (TN)
Falsos positivos (FP)
Falsos negativos (FN)
Incluye métricas: Accuracy, Precision, Recall, F1-Score Curva ROC (Receiver Operating Characteristic):
Eje X: Tasa de falsos positivos
Eje Y: Tasa de verdaderos positivos
Incluye el valor AUC (Area Under Curve)
Un AUC cercano a 1.0 indica excelente desempeño. Grid de ejemplos visuales mostrando:
Imagen original del rayo X
Etiqueta real (NORMAL/PNEUMONIA)
Predicción del modelo
Probabilidad de la predicción
Útil para presentaciones y demos. src/
Código Fuente Módulos principales de la aplicación.
Esta carpeta contiene todo el código Python del proyecto, organizado en 4 módulos principales.
Módulos del Código src/model.py Arquitectura de la CNN Propósito
Función Principal
# Define la arquitectura de la red neuronal convolucional # 3 bloques convolucionales + capas densas
Componentes :
3 capas convolucionales (32, 64, 128 filtros)
MaxPooling después de cada convolución
Capa Flatten
Capa Dense (128 neuronas)
Dropout (0.5) para regularización
Capa de salida (2 neuronas, Softmax)
Ejecutar :pipenv run python src/model.py
Muestra un resumen del modelo con el número total de parámetros.
src/data_loader.py Cargador de Datos con Augmentation Propósito
Funciones Principales
# Carga las imágenes del dataset # Aplica data augmentation para mejorar generalización # Prepara los datos para entrenamiento
Data Augmentation aplicado :
Rotación aleatoria (±15 grados)
Desplazamiento horizontal/vertical (±10%)
Zoom aleatorio (±20%)
Flip horizontal
Rescalado a [0, 1]
El data augmentation solo se aplica al conjunto de entrenamiento, no al de test.
src/train.py Entrenamiento del Modelo # Entrena el modelo CNN con el dataset # Implementa early stopping y checkpoints # Guarda el mejor modelo y visualizaciones
Callbacks implementados : ModelCheckpoint
EarlyStopping
ReduceLROnPlateau
Guarda el mejor modelo según validation accuracy: ModelCheckpoint( 'models/best_model.keras' , monitor = 'val_accuracy' , save_best_only = True )
Detiene el entrenamiento si no hay mejora: EarlyStopping( monitor = 'val_loss' , patience = 5 , restore_best_weights = True )
Reduce el learning rate si hay estancamiento: ReduceLROnPlateau( monitor = 'val_loss' , factor = 0.5 , patience = 3 )
Ejecutar :pipenv run python src/train.py
Output esperado :Epoch 1/20 163/163 [==============================] - 45s 276ms/step loss: 0.3456 - accuracy: 0.8234 - val_loss: 0.2891 - val_accuracy: 0.8567 ... Entrenamiento completado Mejor modelo guardado en: models/best_model.keras
src/evaluate.py Evaluación del Modelo Propósito
Métricas Calculadas
# Evalúa el modelo entrenado en el test set # Calcula métricas completas # Genera visualizaciones de resultados
Ejecutar :pipenv run python src/evaluate.py
Output esperado :Evaluando modelo en test set... Métricas de Evaluación: ======================== Accuracy: 0.8526 Precision: 0.8234 Recall: 0.9231 F1-Score: 0.8705 AUC-ROC: 0.9234 Gráficas guardadas en results/
Scripts Auxiliares main.py Script Principal de Ejecución
Punto de Entrada Script unificado para ejecutar train y/o evaluate.
Uso :Todo (Train + Evaluate)
Solo Entrenar
Solo Evaluar
verificar_dataset.py Verificador de Dataset
Validación Verifica que el dataset esté correctamente descargado y estructurado.
Ejecutar :pipenv run python verificar_dataset.py
Output esperado :Verificando dataset... ✓ Carpeta data/chest_xray/ encontrada ✓ Train set: 5,216 imágenes - NORMAL: 1,341 - PNEUMONIA: 3,875 ✓ Test set: 624 imágenes - NORMAL: 234 - PNEUMONIA: 390 Dataset verificado correctamente!
Archivos de Documentación Archivos Markdown
PLANTEAMIENTO.md Paso 1 : Definición del problema biomédico y justificación
DISEÑO_MODELO.md Paso 2 : Arquitectura CNN y justificación técnica
INSTRUCCIONES_DATASET.md Paso 3 : Cómo descargar y preparar el dataset
GUIA_COMPLETA.md Pasos 1-4 : Guía completa de implementación
README.md Documentación principal del proyecto en inglés
LEEME.md Guía rápida en español para empezar
Gestión de Dependencias Pipfile Dependencias del proyecto :[ packages ] tensorflow = "*" keras = "*" numpy = "*" matplotlib = "*" scikit-learn = "*" pillow = "*" [ requires ] python_version = "3.9"
Instalación Flujo de Trabajo El flujo típico de trabajo con este proyecto es:
Setup inicial
git clone < rep o > cd proyectoia pipenv install
Preparar datos
Descargar dataset de Kaggle
Extraer en data/chest_xray/
Ejecutar verificar_dataset.py
Entrenar
pipenv run python src/train.py
Espera 15-30 minutos
Evaluar
pipenv run python src/evaluate.py
Genera gráficas en results/
Analizar
Revisa:
results/training_history.pngresults/confusion_matrix.pngresults/roc_curve.pngresults/predictions.png Resumen Esta estructura modular facilita:
Mantenibilidad Código organizado en módulos claros y separados
Escalabilidad Fácil agregar nuevas funcionalidades
Reproducibilidad Dependencias versionadas con Pipfile.lock
Claridad Documentación extensa en archivos .md
