diff --git a/README.es-ES.md b/README.es-ES.md new file mode 100644 index 0000000..c7fd4b4 --- /dev/null +++ b/README.es-ES.md @@ -0,0 +1,118 @@ +# 🚀 Plantilla para tu Proyecto de Investigación + +Esta plantilla proporciona herramientas y mejores prácticas para iniciar rápidamente tu proyecto de investigación con un entorno totalmente funcional y estructuras base para tu código. Está basada en mi propia experiencia y la de otros, y tiene como objetivo ayudarte a comenzar de manera efectiva. Siéntete libre de usar esta plantilla y modificarla según tus necesidades. La plantilla incluye lo siguiente: + +- ⚡ [Pytorch Lightning](https://lightning.ai/docs/pytorch/stable/): Un framework para organizar tu investigación de deep learning. +- 🔧 [Hydra](https://hydra.cc/): Un potente sistema de gestión de configuraciones. +- ✅ [Pre-commit](https://pre-commit.com/): Una herramienta para asegurar que el código esté limpio y formateado. +- 🧪 [Unit Testing](https://docs.pytest.org/en/6.2.x/): Para verificar que cada función funcione según lo esperado. +- 📊 [Integración con WandB](https://wandb.ai/site): Para el seguimiento y la visualización de experimentos. +- 🤖 [CI con Github Actions](https://docs.github.com/en/actions): Configuración de Integración Continua para mantener la calidad del proyecto. + +Utilidades adicionales: +- Notebook de Jupyter listo para usar en `report/plots/notebook.ipynb` para crear gráficos de Seaborn reproducibles, extrayendo datos directamente de tu proyecto de WandB. +- Archivo de configuración del depurador de VScode pre-implementado en `.vscode/launch.json` para depurar tu código. + +--- + +## 🛠️ Descripción General de Herramientas + +### ⚡ PyTorch Lightning +Esta plantilla está construida alrededor del framework PyTorch Lightning. Se espera que organices tus módulos en la carpeta `src`: +- `src/model.py`: Define la arquitectura de tu modelo y la función `forward`. Cada modelo debe ser una clase que herede de `pl.LightningModule`. +- `src/dataset.py`: Define tus datasets (`torch.utils.data.Dataset`) y datamodules (`pl.LightningDataModule`). +- `src/task.py`: Implementa tu función forward global, la función de pérdida, los pasos de entrenamiento y evaluación, y las métricas. Agrega callbacks personalizados si es necesario. +- `src/train.py`: El script principal. Carga el archivo de configuración, instancia los componentes, entrena el modelo y guarda los logs y resultados. + +Aprende más sobre PyTorch Lightning [aquí](https://lightning.ai/docs/pytorch/stable/). + +--- + +### 🔧 Configuración de Hydra +La plantilla utiliza Hydra para una gestión de configuración flexible. Los archivos de configuración se almacenan en la carpeta `configs`: +- `configs/train.yaml`: El archivo de configuración principal donde defines los hiperparámetros. + +También puedes definir diferentes configuraciones para distintos experimentos, sobrescribir configs, crear configs anidadas, etc. El sistema de configuración es muy flexible y te permite definir tu propia estructura. Usa Hydra para estructurar tu sistema de configuración de manera efectiva. Más detalles [aquí](https://hydra.cc/). + +--- + +### ✅ Pre-commit +Los hooks de Pre-commit aseguran que tu código esté limpio y formateado antes de confirmar (commit) cualquier cambio cuando trabajas con múltiples colaboradores. Los hooks están definidos en el archivo `.pre-commit-config.yaml`. +Cuando los hooks se activen, deberás volver a realizar el commit de cualquier cambio que hayan realizado. También se ejecutan automáticamente mediante el pipeline de CI en tu repositorio remoto para mantener la calidad del código. +Instálalos con: +```bash +pre-commit install +``` + +--- + +### 🧪 Pruebas Unitarias (Unit Testing) +Se incluye un archivo de pruebas unitarias, `test_all.py`, para verificar que cada una de tus funciones funcione según lo esperado. Aunque no es obligatorio para proyectos sencillos, es una buena práctica para proyectos más grandes o colaborativos. Las pruebas se ejecutan automáticamente mediante el pipeline de CI en tu repositorio remoto, y se envían notificaciones si alguna prueba falla. + +--- + +### 📊 Integración con WandB +Registra experimentos y métricas sin complicaciones con WandB. La integración ya está incluida en la plantilla, y el registro es tan simple como usar la función `self.log()` en PyTorch Lightning. Para configurar WandB, solo edita `configs/train.yaml`: +```yaml +logger: + _target_: lightning.pytorch.loggers.WandbLogger + entity: # Agrega tu entidad de WandB aquí + project: # Agrega tu proyecto de WandB aquí +``` +Aprende más sobre WandB [aquí](https://wandb.ai/site). + +--- + +## ⚙️ Instalación +Se requiere Python 3.6 o posterior. Se recomienda usar un entorno virtual para evitar conflictos de paquetes. + +1️⃣ Instala las dependencias: +```bash +pip install -r requirements.txt +``` + +2️⃣ Configura los hooks de pre-commit: +```bash +pre-commit install +``` + +3️⃣ Configura WandB (si aplica): +Edita `configs/train.yaml` con la información de tu entidad y proyecto de WandB. + +4️⃣ ¡Ya estás listo para empezar! + +--- + +## ▶️ Uso + +Para ejecutar tu código, simplemente ejecuta el script `train.py`. Pasa los hiperparámetros como argumentos: +```bash +python train.py seed=0 my_custom_argument=config_1 +``` +Esto iniciará una ejecución de entrenamiento con los hiperparámetros especificados. + +Para trabajos paralelos en un clúster, usa la función `--multirun` de Hydra: +```bash +python train.py --multirun seed=0,1,2,3,4 my_custom_argument=config_1,config_2 +``` + +Si utilizas Slurm, se usará la configuración de lanzador predeterminada `hydra/launcher/slurm.yaml` basada en el plugin `submitit` para Hydra. + +Aprende más sobre Hydra [aquí](https://hydra.cc/docs/intro). + +--- + +## 🤝 Contribución + +¡Todo tipo de contribuciones son bienvenidas! Puedes añadir herramientas, mejorar prácticas o sugerir alternativas. +👉 Si añades dependencias externas, asegúrate de actualizar el archivo `requirements.txt`. + +Esta plantilla está directamente inspirada en nuestro proyecto [PrequentialCode](https://github.com/3rdCore/PrequentialCode), hecho posible por Eric Elmoznino y Tejas Kasetty: + + + + + +--- + +¡Siéntete libre de sumergirte y comenzar tu proyecto! 🌟