How ada-nuevalos/garbage-classification works
Este repositorio es un proyecto de investigación/experimentación, no una aplicación de producción. Su arquitectura está organizada alrededor de un flujo de trabajo de clasificación de imágenes de residuos, con notebooks como capa principal de orquestación y módulos Python reutilizables para las arquitecturas.
Visión general del sistema
El sistema se puede entender en cuatro capas:
1. Datos
- Imágenes originales del dataset TrashNet en data/raw/, organizadas por clase:
cardboard, glass, metal, paper, plastic y trash.
- Un dataset ya preprocesado y serializado en data/processed/trashnet_224x224.npz, que representa la versión normalizada y redimensionada a 224×224.
- Esta separación marca el límite entre ingestión cruda y entrenamiento experimental.
2. Experimentos y entrenamiento
- Los notebooks en notebooks/ son el centro de ejecución del proyecto.
- Hay dos líneas experimentales claramente diferenciadas:
- Modelos clásicos / baselines: EDA, regresión logística y SVM usando características tipo HOG.
- Deep Learning: CNNs entrenadas desde cero y modelos con transfer learning basados en EfficientNetV2.
3. Definición de modelos
- El directorio models/ contiene las arquitecturas reutilizables en Python.
- Cada archivo define una variante concreta de modelo:
- Serie A: CNNs desde cero, de menor a mayor capacidad.
- Serie D: variantes de EfficientNetV2 con distintos grados de fine-tuning y cabezas de clasificación.
- Esto separa la arquitectura del modelo del proceso experimental de los notebooks.
4. Resultados, documentación y referencias
- reports/ almacena figuras y artefactos generados, como la infografía y la gráfica bias-varianza.
- sota_references/ contiene los papers y un índice de bibliografía que sustentan el estado del arte.
- code_exmaple/ incluye notebooks externos de referencia, útiles como comparación o inspiración, pero no forman parte del flujo principal del proyecto.
---
Flujo de datos principal
El flujo de trabajo del repositorio sigue esta secuencia:
Imágenes originales en data/raw/
→ preprocesamiento y normalización
→ dataset empaquetado en data/processed/trashnet_224x224.npz
→ carga desde notebooks
→ entrenamiento/evaluación de modelos
→ generación de métricas y gráficos en reports/
En paralelo, para las baselines clásicas el flujo alternativo es:
Imágenes
→ extracción de características manuales
→ clasificadores como regresión logística o SVM
→ evaluación comparativa
Y para deep learning:
Imágenes preprocesadas
→ CNNs A1–A5 o EfficientNet D0–D4
→ entrenamiento con validación
→ métricas macro y matriz de confusión
→ selección del mejor modelo final
---
Subsistemas principales
1. Subsistema de datos
• data/raw/ es la fuente primaria.
• data/processed/trashnet_224x224.npz es la representación lista para modelado.
• El dataset está desbalanceado, especialmente la clase trash, lo que influye en la elección de métricas y en el análisis de resultados.
Este subsistema es importante porque separa el almacenamiento del dato original del formato consumido por entrenamiento.
2. Subsistema de exploración y análisis
• notebooks/1_EDA_Garbage_Classification.ipynb se dedica al análisis exploratorio.
• Sirve para inspeccionar clases, distribución, ejemplos visuales y características generales del dataset.
• También ayuda a justificar decisiones posteriores, como el uso de F1 macro frente a accuracy simple.
3. Subsistema de baselines clásicos
• 2.1.Modelo_Lineal_Garbage_Classification.ipynb
• 2.2.Modelo_ML_Garbage_Classification.ipynb
• Estos notebooks representan la línea de base tradicional:
- regresión logística
- SVM
- características manuales tipo HOG
Arquitecturalmente, este bloque funciona como referencia mínima para medir si las CNN aportan valor real.
4. Subsistema de CNNs desde cero
• Archivos en models/ y notebooks asociados:
- A1_simple_cnn
- A2_cnn_small
- A3_cnn_medium
- A4_cnn_large
- A5_D5_cnn_frontier
• Esta serie explora el trade-off entre capacidad del modelo y sobreajuste.
• El objetivo es ver cómo escala el rendimiento cuando aumenta la complejidad de la red sin usar preentrenamiento.
5. Subsistema de transfer learning
• Serie D0 a D4 basada en EfficientNetV2.
• Los notebooks correspondientes prueban distintas estrategias de fine-tuning:
- descongelado completo
- bloques superiores
- cabeza personalizada
- pooling global adicional
- versión mínima descongelada
• Este es el bloque más importante del proyecto, porque termina produciendo el modelo final recomendado: D4 — EffNet Minimal.
---
Boundarys importantes
Boundary de preprocesamiento
El proyecto distingue claramente entre:
• datos crudos del dataset,
• y datos preprocesados 224×224 normalizados.
Esa frontera es importante porque el entrenamiento y la reproducibilidad dependen de la versión procesada del dataset, no de las imágenes originales.
Boundary entre experimentación y definición de modelo
Los notebooks controlan el ciclo experimental, pero la lógica de las arquitecturas está separada en models/.
Eso permite reutilizar las redes en distintos experimentos sin duplicar código.
Boundary entre código propio y referencias externas
• sota_references/ contiene la base académica.
• code_exmaple/ contiene ejemplos externos o notebooks de referencia.
Ninguno de los dos parece ser parte del pipeline principal; son soportes para investigación.
---
Tecnologías y estilo de arquitectura
Aunque el repositorio no expone una aplicación desplegada, sí se reconoce un stack típico de aprendizaje profundo en Python:
• notebooks para experimentación,
• módulos .py para modelos reutilizables,
• procesamiento de imágenes y entrenamiento de clasificadores,
• serialización de datos procesados en .npz.
La estructura sugiere un flujo de trabajo orientado a ciencia de datos/ML más que a servicio online:
• no hay API,
• no hay frontend,
• no hay capa de inferencia en producción,
• no hay microservicios ni componentes de despliegue.
---
Resultado arquitectónico final
El repositorio culmina en una arquitectura de investigación comparativa con tres familias de modelos:
1. Baselines clásicos
Regresión logística y SVM sobre características manuales.
2. CNNs entrenadas desde cero
Serie A, usada para estudiar capacidad, sesgo y varianza.
3. Transfer learning con EfficientNetV2
Serie D, que ofrece el mejor equilibrio entre rendimiento y coste.
La selección final del proyecto es D4 — EffNet Minimal, porque mantiene una métrica alta en test con menor complejidad que el modelo completo.
En resumen, el diagrama arquitectónico correcto para este repositorio debería mostrar:
• una fuente de datos TrashNet,
• una etapa de preprocesamiento a 224×224,
• dos ramas de modelado (clásica y deep learning),
• un conjunto de notebooks que orquestan los experimentos,
• módulos de arquitecturas compartidas,
• y una capa de artefactos/resultados/documentación.
Main entry points: trashnet_224x224.npz 224x224 NPZ · utils.py Utilities · D4_effnet_minimal.ipynb D4 run · A1_simple_cnn.py CNN series
Components 19
Data
Raw images and processed dataset artifacts.
- TrashNet raw · Original class-organized images under data/raw/.
data/raw - 224x224 NPZ · Serialized preprocessed dataset used by the experiments.
data/processed/trashnet_224x224.npz
Experiments
Notebooks that orchestrate exploration, baselines, and training runs.
- EDA notebook · Dataset inspection, class balance analysis, and visual exploration.
notebooks/1_EDA_Garbage_Classification.ipynb - Linear baseline · Regression-logistic baseline over engineered features.
notebooks/2.1.Modelo_Lineal_Garbage_Classification.ipynb - HOG + SVM · Traditional feature-extraction and SVM experiment.
notebooks/2.2.Modelo_ML_Garbage_Classification.ipynb - Simple NN · Early neural baseline bridging classical ML and CNN experiments.
notebooks/2.3.Modelo_Red_Neuronal_Simple.ipynb - A2 run · Notebook for the small CNN variant.
notebooks/3.A2_cnn_small.ipynb - A3 run · Notebook for the medium CNN variant.
notebooks/3.A3_cnn_medium.ipynb - A4 run · Notebook for the large CNN variant.
notebooks/3.A4_cnn_large.ipynb - A5 run · Notebook for the frontier CNN variant.
notebooks/3.A5_cnn_frontier.ipynb - D0 run · Full fine-tuning EfficientNetV2 experiment.
notebooks/D0_effnet_full.ipynb - D4 run · Minimal fine-tuning EfficientNetV2 experiment that becomes the recommended model.
notebooks/D4_effnet_minimal.ipynb
Model defs
Reusable Python modules that define CNN and EfficientNet variants.
- CNN series · Reusable CNN definitions from A1 through A5.
models/A1_simple_cnn.py - EffNet series · Reusable EfficientNetV2 variants from D0 through D4.
models/D0_effnet_full.py - Utilities · Shared utility helpers used by notebooks and model code.
scr/utils.py
References
Supporting literature, examples, and generated reports.
Connections 30
- TrashNet raw → 224x224 NPZ: preprocess · Raw images are normalized and resized into the serialized dataset.
- 224x224 NPZ → EDA notebook: inspect · EDA reads the processed dataset to understand classes and balance.
- 224x224 NPZ → Linear baseline: features · Classical baselines consume image data through engineered features.
- 224x224 NPZ → HOG + SVM: features · HOG-style feature extraction feeds the SVM baseline.
- 224x224 NPZ → Simple NN: train · The simple neural baseline trains from the prepared dataset.
- 224x224 NPZ → A2 run: train · CNN experiments use the prepared dataset for training and validation.
- 224x224 NPZ → A3 run: train · CNN experiments use the prepared dataset for training and validation.
- 224x224 NPZ → A4 run: train · CNN experiments use the prepared dataset for training and validation.
- 224x224 NPZ → A5 run: train · CNN experiments use the prepared dataset for training and validation.
- 224x224 NPZ → D0 run: fine-tune · Transfer-learning experiments consume the prepared dataset.
- 224x224 NPZ → D4 run: fine-tune · Minimal fine-tuning experiment consumes the prepared dataset.
- CNN series → A2 run: defines · Notebook runs use the shared CNN architecture implementations.
- CNN series → A3 run: defines · Notebook runs use the shared CNN architecture implementations.
- CNN series → A4 run: defines · Notebook runs use the shared CNN architecture implementations.
- CNN series → A5 run: defines · Notebook runs use the shared CNN architecture implementations.
- EffNet series → D0 run: defines · Notebook runs use the shared EfficientNetV2 variants.
- EffNet series → D4 run: defines · Notebook runs use the shared EfficientNetV2 variants.
- Utilities → EDA notebook: supports · Shared utilities support data handling and plotting.
- Utilities → Linear baseline: supports · Shared utilities support feature extraction and evaluation.
- Utilities → HOG + SVM: supports · Shared utilities support feature extraction and evaluation.
- Utilities → Simple NN: supports · Shared utilities support training workflow helpers.
- Utilities → A2 run: supports · Shared utilities support training workflow helpers.
- Utilities → D4 run: supports · Shared utilities support training workflow helpers.
- D4 run → Reports: outputs · Best-performing transfer-learning run produces the main artifacts and figures.
- A5 run → Reports: outputs · CNN experiments contribute comparative metrics and plots.
- EDA notebook → SOTA refs: context · Exploration and analysis are informed by the bibliography.
- D4 run → SOTA refs: context · Transfer-learning choices are grounded in the referenced papers.
- README → EDA notebook: documents · Repository documentation points to the experimental workflow.
- README → D4 run: documents · Repository documentation summarizes the final recommended model.
- Examples → A2 run: inspires · External examples provide reference implementations and comparisons.