14 KiB

Raw Blame History

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

# 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

# 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

# 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

# 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):

# 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

Inicia Jupyter en la raíz del repositorio: jupyter notebook
Navega a la carpeta de la lección deseada
Abre los archivos .ipynb para trabajar en los ejercicios
Los notebooks son autónomos con explicaciones y celdas de código
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

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

# 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

# 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:

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

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:

Crea un recurso de Azure Static Web App
Conéctalo al repositorio de GitHub
Configura los ajustes de construcción:
- Ubicación de la aplicación: quiz-app
- Ubicación de salida: dist
El flujo de trabajo de GitHub Actions se encargará del despliegue automático al realizar un push

Sitio de Documentación

# 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

# 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

Desarrollo Local: Instala Python, Jupyter, Node.js localmente
GitHub Codespaces: Entorno de desarrollo instantáneo basado en la nube
Contenedores de Desarrollo en VS Code: Desarrollo local basado en contenedores
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:

# Ensure correct kernel is installed
python -m ipykernel install --user --name=datascience

Fallos en npm Install:

# 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. 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.

14 KiB Raw Blame History