# AGENTS.md ## Resumen del Proyecto Data Science for Beginners es un plan de estudios completo de 10 semanas y 20 lecciones creado por los Azure Cloud Advocates de Microsoft. El repositorio es un recurso de aprendizaje que enseña conceptos fundamentales de ciencia de datos a través de lecciones basadas en proyectos, incluyendo notebooks de Jupyter, cuestionarios interactivos y tareas prácticas. **Tecnologías Clave:** - **Jupyter Notebooks**: Medio principal de aprendizaje utilizando Python 3 - **Bibliotecas de Python**: pandas, numpy, matplotlib para análisis y visualización de datos - **Vue.js 2**: Aplicación de cuestionarios (carpeta quiz-app) - **Docsify**: Generador de sitios de documentación para acceso offline - **Node.js/npm**: Gestión de paquetes para componentes JavaScript - **Markdown**: Todo el contenido de las lecciones y documentación **Arquitectura:** - Repositorio educativo multilingüe con extensas traducciones - Estructurado en módulos de lecciones (1-Introducción hasta 6-Ciencia-de-Datos-en-el-Mundo) - Cada lección incluye README, notebooks, tareas y cuestionarios - Aplicación de cuestionarios Vue.js independiente para evaluaciones antes/después de las lecciones - Soporte para GitHub Codespaces y contenedores de desarrollo en VS Code ## Comandos de Configuración ### Configuración del Repositorio ```bash # Clone the repository (if not already cloned) git clone https://github.com/microsoft/Data-Science-For-Beginners.git cd Data-Science-For-Beginners ``` ### Configuración del Entorno de Python ```bash # Create a virtual environment (recommended) python -m venv venv source venv/bin/activate # On Windows: venv\Scripts\activate # Install common data science libraries (no requirements.txt exists) pip install jupyter pandas numpy matplotlib seaborn scikit-learn ``` ### Configuración de la Aplicación de Cuestionarios ```bash # Navigate to quiz app cd quiz-app # Install dependencies npm install # Start development server npm run serve # Build for production npm run build # Lint and fix files npm run lint ``` ### Servidor de Documentación Docsify ```bash # Install Docsify globally npm install -g docsify-cli # Serve documentation locally docsify serve # Documentation will be available at localhost:3000 ``` ### Configuración de Proyectos de Visualización Para proyectos de visualización como meaningful-visualizations (lección 13): ```bash # Navigate to starter or solution folder cd 3-Data-Visualization/13-meaningful-visualizations/starter # Install dependencies npm install # Start development server npm run serve # Build for production npm run build # Lint files npm run lint ``` ## Flujo de Trabajo de Desarrollo ### Trabajando con Jupyter Notebooks 1. Inicia Jupyter en la raíz del repositorio: `jupyter notebook` 2. Navega a la carpeta de la lección deseada 3. Abre los archivos `.ipynb` para trabajar en los ejercicios 4. Los notebooks son autónomos con explicaciones y celdas de código 5. La mayoría de los notebooks utilizan pandas, numpy y matplotlib; asegúrate de que estén instalados ### Estructura de las Lecciones Cada lección típicamente contiene: - `README.md` - Contenido principal de la lección con teoría y ejemplos - `notebook.ipynb` - Ejercicios prácticos en Jupyter notebook - `assignment.ipynb` o `assignment.md` - Tareas prácticas - Carpeta `solution/` - Notebooks y código de solución - Carpeta `images/` - Materiales visuales de apoyo ### Desarrollo de la Aplicación de Cuestionarios - Aplicación Vue.js 2 con recarga en caliente durante el desarrollo - Cuestionarios almacenados en `quiz-app/src/assets/translations/` - Cada idioma tiene su propia carpeta de traducción (en, fr, es, etc.) - La numeración de los cuestionarios comienza en 0 y llega hasta 39 (40 cuestionarios en total) ### Agregar Traducciones - Las traducciones se colocan en la carpeta `translations/` en la raíz del repositorio - Cada idioma tiene una estructura completa de lecciones reflejada desde el inglés - Traducción automatizada mediante GitHub Actions (co-op-translator.yml) ## Instrucciones de Pruebas ### Pruebas de la Aplicación de Cuestionarios ```bash cd quiz-app # Run lint checks npm run lint # Test build process npm run build # Manual testing: Start dev server and verify quiz functionality npm run serve ``` ### Pruebas de Notebooks - No existe un marco de pruebas automatizado para notebooks - Validación manual: Ejecuta todas las celdas en secuencia para asegurarte de que no haya errores - Verifica que los archivos de datos sean accesibles y que los resultados se generen correctamente - Comprueba que las visualizaciones se rendericen adecuadamente ### Pruebas de Documentación ```bash # Verify Docsify renders correctly docsify serve # Check for broken links manually by navigating through content # Verify all lesson links work in the rendered documentation ``` ### Verificaciones de Calidad de Código ```bash # Vue.js projects (quiz-app and visualization projects) cd quiz-app # or visualization project folder npm run lint # Python notebooks - manual verification recommended # Ensure imports work and cells execute without errors ``` ## Guías de Estilo de Código ### Python (Jupyter Notebooks) - Sigue las guías de estilo PEP 8 para código Python - Usa nombres de variables claros que expliquen los datos que se están analizando - Incluye celdas de markdown con explicaciones antes de las celdas de código - Mantén las celdas de código enfocadas en conceptos u operaciones individuales - Utiliza pandas para manipulación de datos, matplotlib para visualización - Patrón común de importación: ```python import pandas as pd import numpy as np import matplotlib.pyplot as plt ``` ### JavaScript/Vue.js - Sigue la guía de estilo de Vue.js 2 y las mejores prácticas - Configuración de ESLint en `quiz-app/package.json` - Usa componentes de archivo único de Vue (.vue files) - Mantén una arquitectura basada en componentes - Ejecuta `npm run lint` antes de confirmar cambios ### Documentación en Markdown - Usa una jerarquía clara de encabezados (# ## ### etc.) - Incluye bloques de código con especificadores de lenguaje - Agrega texto alternativo para imágenes - Enlaza a lecciones y recursos relacionados - Mantén longitudes de línea razonables para facilitar la lectura ### Organización de Archivos - Contenido de las lecciones en carpetas numeradas (01-definiendo-ciencia-de-datos, etc.) - Soluciones en subcarpetas dedicadas `solution/` - Las traducciones reflejan la estructura en inglés en la carpeta `translations/` - Mantén los archivos de datos en `data/` o carpetas específicas de las lecciones ## Construcción y Despliegue ### Despliegue de la Aplicación de Cuestionarios ```bash cd quiz-app # Build production version npm run build # Output is in dist/ folder # Deploy dist/ folder to static hosting (Azure Static Web Apps, Netlify, etc.) ``` ### Despliegue de Azure Static Web Apps La aplicación quiz-app puede desplegarse en Azure Static Web Apps: 1. Crea un recurso de Azure Static Web App 2. Conéctalo al repositorio de GitHub 3. Configura los ajustes de construcción: - Ubicación de la aplicación: `quiz-app` - Ubicación de salida: `dist` 4. El flujo de trabajo de GitHub Actions se encargará del despliegue automático al realizar un push ### Sitio de Documentación ```bash # Build PDF from Docsify (optional) npm run convert # Docsify documentation is served directly from markdown files # No build step required for deployment # Deploy repository to static hosting with Docsify ``` ### GitHub Codespaces - El repositorio incluye configuración de contenedor de desarrollo - Codespaces configura automáticamente el entorno de Python y Node.js - Abre el repositorio en Codespace a través de la interfaz de GitHub - Todas las dependencias se instalan automáticamente ## Guías para Pull Requests ### Antes de Enviar ```bash # For Vue.js changes in quiz-app cd quiz-app npm run lint npm run build # Test changes locally npm run serve ``` ### Formato del Título de PR - Usa títulos claros y descriptivos - Formato: `[Componente] Breve descripción` - Ejemplos: - `[Lección 7] Corrige error de importación en notebook de Python` - `[Aplicación de Cuestionarios] Agrega traducción al alemán` - `[Documentación] Actualiza README con nuevos requisitos` ### Verificaciones Requeridas - Asegúrate de que todo el código se ejecute sin errores - Verifica que los notebooks se ejecuten completamente - Confirma que las aplicaciones Vue.js se construyan correctamente - Comprueba que los enlaces de la documentación funcionen - Prueba la aplicación de cuestionarios si fue modificada - Verifica que las traducciones mantengan una estructura consistente ### Guías de Contribución - Sigue el estilo y los patrones de código existentes - Agrega comentarios explicativos para lógica compleja - Actualiza la documentación relevante - Prueba los cambios en diferentes módulos de lecciones si aplica - Revisa el archivo CONTRIBUTING.md ## Notas Adicionales ### Bibliotecas Comunes Utilizadas - **pandas**: Manipulación y análisis de datos - **numpy**: Computación numérica - **matplotlib**: Visualización y gráficos de datos - **seaborn**: Visualización estadística de datos (algunas lecciones) - **scikit-learn**: Aprendizaje automático (lecciones avanzadas) ### Trabajando con Archivos de Datos - Archivos de datos ubicados en la carpeta `data/` o directorios específicos de las lecciones - La mayoría de los notebooks esperan archivos de datos en rutas relativas - Los archivos CSV son el formato principal de datos - Algunas lecciones utilizan JSON para ejemplos de datos no relacionales ### Soporte Multilingüe - Más de 40 traducciones de idiomas mediante GitHub Actions automatizadas - Flujo de trabajo de traducción en `.github/workflows/co-op-translator.yml` - Traducciones en la carpeta `translations/` con códigos de idioma - Traducciones de cuestionarios en `quiz-app/src/assets/translations/` ### Opciones de Entorno de Desarrollo 1. **Desarrollo Local**: Instala Python, Jupyter, Node.js localmente 2. **GitHub Codespaces**: Entorno de desarrollo instantáneo basado en la nube 3. **Contenedores de Desarrollo en VS Code**: Desarrollo local basado en contenedores 4. **Binder**: Lanza notebooks en la nube (si está configurado) ### Guías de Contenido de las Lecciones - Cada lección es autónoma pero se basa en conceptos previos - Cuestionarios previos a la lección evalúan conocimientos previos - Cuestionarios posteriores a la lección refuerzan el aprendizaje - Las tareas proporcionan práctica práctica - Los sketchnotes ofrecen resúmenes visuales ### Solución de Problemas Comunes **Problemas con el Kernel de Jupyter:** ```bash # Ensure correct kernel is installed python -m ipykernel install --user --name=datascience ``` **Fallos en npm Install:** ```bash # Clear npm cache and retry npm cache clean --force rm -rf node_modules package-lock.json npm install ``` **Errores de Importación en Notebooks:** - Verifica que todas las bibliotecas requeridas estén instaladas - Comprueba la compatibilidad de la versión de Python (se recomienda Python 3.7+) - Asegúrate de que el entorno virtual esté activado **Docsify No Carga:** - Verifica que estés sirviendo desde la raíz del repositorio - Comprueba que `index.html` exista - Asegúrate de tener acceso adecuado a la red (puerto 3000) ### Consideraciones de Rendimiento - Los conjuntos de datos grandes pueden tardar en cargarse en los notebooks - La renderización de visualizaciones puede ser lenta para gráficos complejos - El servidor de desarrollo de Vue.js permite recarga en caliente para iteración rápida - Las construcciones de producción están optimizadas y minificadas ### Notas de Seguridad - No se deben comprometer datos sensibles ni credenciales - Usa variables de entorno para cualquier clave API en lecciones en la nube - Las lecciones relacionadas con Azure pueden requerir credenciales de cuenta de Azure - Mantén las dependencias actualizadas para parches de seguridad ## Contribuyendo a las Traducciones - Traducciones automatizadas gestionadas mediante GitHub Actions - Correcciones manuales son bienvenidas para mejorar la precisión de las traducciones - Sigue la estructura de carpetas de traducción existente - Actualiza los enlaces de los cuestionarios para incluir el parámetro de idioma: `?loc=fr` - Prueba las lecciones traducidas para verificar su correcta visualización ## Recursos Relacionados - Plan de estudios principal: https://aka.ms/datascience-beginners - Microsoft Learn: https://docs.microsoft.com/learn/ - Student Hub: https://docs.microsoft.com/learn/student-hub - Foro de Discusión: https://github.com/microsoft/Data-Science-For-Beginners/discussions - Otros planes de estudios de Microsoft: ML for Beginners, AI for Beginners, Web Dev for Beginners ## Mantenimiento del Proyecto - Actualizaciones regulares para mantener el contenido actualizado - Contribuciones de la comunidad son bienvenidas - Problemas rastreados en GitHub - PRs revisados por los mantenedores del plan de estudios - Revisiones y actualizaciones de contenido mensuales --- **Descargo de responsabilidad**: Este documento ha sido traducido utilizando el servicio de traducción automática [Co-op Translator](https://github.com/Azure/co-op-translator). Aunque nos esforzamos por garantizar la precisión, tenga en cuenta que las traducciones automatizadas pueden contener errores o imprecisiones. El documento original en su idioma nativo debe considerarse como la fuente autorizada. Para información crítica, se recomienda una traducción profesional realizada por humanos. No nos hacemos responsables de malentendidos o interpretaciones erróneas que puedan surgir del uso de esta traducción.