Preparación del entorno de un proyecto de Data Mining

Con este post pretendo explicar como crear un proyecto de Data Mining y preparar el entorno de proyecto, empleando Visual Studio Code como IDE, Git para control de versiones, y uv para gestión de dependencias. Para ello, te propongo un taller para seguir paso a paso.

1.- Herramientas

Para realizar el taller vas a necesitar las siguientes herramientas:

  • Visual Studio Code: Es el entorno de desarrollo escogido, donde escribiremos el código y bastantes más cosas.
  • Git: Para controlar las versiones del proyecto y poder volver a un estado anterior del mismo si metemos la pata.
  • Uv: Para gestionar las dependencias. No voy a emplear el típico fichero requirements.txt, aunque también podemos emplearlo con uv. Personalmente me gusta más uv por su rapidez y sencillez.

Al finalizar, tendrás un proyecto que puede abrirse, ejecutarse y reconstruirse en otro equipo sin copiar el entorno virtual. El proyecto conservará sus dependencias en pyproject.toml y sus versiones exactas en uv.lock.

Instalación de Visual Studio Code

Descarga Visual Studio Code desde https://code.visualstudio.com/ e instálalo con las opciones predeterminadas. En Windows resulta útil activar la opción que añade el comando code al PATH.

Visual Studio Code será el punto de trabajo común: integra el editor, la terminal, la ejecución de Python, los notebooks y Git en una misma ventana.

Instalación de extensiones

Abre el panel Extensions con Ctrl+Shift+X e instala las extensiones siguientes:

  • Python, identificador ms-python.python.
  • Jupyter, identificador ms-toolsai.jupyter.

La extensión Python permite seleccionar intérpretes, ejecutar y depurar programas. Jupyter añade la edición y ejecución de notebooks; sin ella, los archivos .ipynb no disponen de celdas ni selector de kernel.

Ambas extensiones deben aparecer como instaladas y habilitadas en el espacio de trabajo.

Instalación de Git

Instala Git desde https://git-scm.com/downloads/.

Después, abre una terminal nueva en Visual Studio Code mediante Terminal > New Terminal y ejecuta:

git --version

Git registra la evolución del proyecto. Comprobar la versión confirma que la terminal puede localizarlo antes de inicializar o guardar cambios. La terminal debe mostrar un número de versión, por ejemplo:

git version 2.56.1.windows.1

Si Git solicita identidad al crear el primer commit, configúrala solo para este proyecto:

git config user.name "Nombre Apellidos"
git config user.email "correo@ejemplo.com"

Cada commit necesita una autoría. Al omitir la opción –global, estos datos se aplican únicamente al proyecto en curso y no modifican otros repositorios del equipo.

Instalación de uv

uv administrará la versión de Python, el entorno virtual, las dependencias y el archivo de bloqueo. Para instalarte la versión adecuada para tu equipo visita la página: https://docs.astral.sh/uv/getting-started/installation/

En Windows PowerShell se puede instalar con:

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

En macOS o Linux, desde Terminal:

curl -LsSf https://astral.sh/uv/install.sh | sh

Una vez instalado, cierra y vuelve a abrir la terminal. Verifica la instalación:

uv --version

En este punto, si no te reconoce el comando uv, cierra visual Studio Code, vuelve a abrirlo y ejecuta de nuevo el comando anterior.

uv reúne varias tareas del entorno en una sola herramienta. Verificarlo ahora evita descubrir más tarde que el comando no está disponible o que la terminal conserva un PATH antiguo.

2.-Crear el proyecto

Una vez tenemos disponibles todas las herramientas que necesitamos, es el momento de crear el proyecto.

2.1.- Preparar Python

Instalar una versión concreta de Python evita diferencias entre equipos. El proyecto podrá indicar a uv qué intérprete debe usar aunque el sistema tenga otras versiones de Python. Por ejemplo, si queremos instalar la versión 3.13, haríamos:

uv python install 3.13

2.2.- Crear la carpeta

El proyecto va a vivir en una carpeta. Hay que tener muy claro donde lo ubicamos, da igual si creas la carpeta con el administrador de archivos y luego la abres en VS Code, o si lo haces desde el Terminal.

Si lo haces desde terminal, situate en el directorio donde quieras crear tu carpeta y ejecuta:

mkdir <nombre de la carpeta de tu proyecto>

mkdir crea una carpeta nueva, y luego con el comando cd nos movemos a esa carpeta que será la ubicación de trabajo:

cd <nombre de la carpeta de tu proyecto>

En el Terminal puedes ver como estás dentro del directorio que acabas de crear

2.3.-Generar la estructura del proyecto

Con uv vamos a generar la estructura del proyecto, para ello tecleamos en el Terminal el siguiente comando:

uv init

Con este comando, creamos la estructura y los metadatos del proyecto.

Y con el comando:

code .

abrimos exactamente la carpeta como espacio de trabajo en VS Code. Fijate que el comando incorpora un punto al final, separado del comando. Si code no se reconoce, abre la carpeta desde el menú File.

Cuando VS Code pregunte si confías en la carpeta, selecciona la opción de confianza solo si tú la has creado o conoces su procedencia. VS Code limita la ejecución automática de tareas y extensiones en carpetas no confiables. La confianza habilita todas las funciones necesarias para un proyecto propio.

2.4.-Revisar la estructura de proyecto

La estructura exacta puede variar ligeramente con la versión de uv, pero debe incluir estos elementos:

.
|-- .git/
|-- .gitignore
|-- .python-version
|-- README.md
|-- pyproject.toml
`-- src/
`-- taller_python/
`-- __init__.py

Los siguientes elementos cumplen con la siguiente función

  • .git/: Guarda el historial local del proyecto.
  • .gitignore: Indica qué archivos no deben entrar en Git.
  • .python-version: Indica la versión de Python que debe utilizar uv.
  • pyproject.toml: Describe el proyecto y declara sus dependencias directas.

Reconocer la función de cada archivo permite detectar errores de ubicación y evita editar a mano elementos que gestiona uv, como el archivo de bloqueo.

3.- El entorno

Con el proyecto creado, pasamos a configurar todo lo que se necesita del entorno.

3.1.- Instalar dependencias

Añade soporte de kernel para poder ejecutar notebooks con el mismo Python del proyecto:

uv add ipykernel

ipykernel conecta un notebook con el intérprete del entorno virtual. Así, las celdas usan las mismas dependencias que los programas del proyecto.

La primera orden de proyecto crea automáticamente la carpeta .venv, actualiza pyproject.toml y genera uv.lock. No instales paquetes manualmente dentro de .venv.

¿Qué consigue uv add? Además de instalar, registra la decisión en pyproject.toml y actualiza uv.lock. Esto hace que las dependencias no dependan de la memoria del desarrollador ni de instalaciones manuales.

3.2.- Comprobar el entorno

Para una primera comprobación del entorno de trabajo, podemos ejecutar los comandos siguientes en el Terminal:

uv run python --version
uv run python -c "import ipykernel; print('Dependencias correctas')"
uv tree

Debe aparecer Python 3.13, el mensaje Dependencias correctas y el árbol de paquetes sin errores. Estas tres comprobaciones validan aspectos distintos: la versión de Python, la importación de una dependencia y la resolución completa del conjunto de paquetes.

3.3.- Sincronizar el entorno

En ocasiones podemos necesitar reconstruir el entorno al completo, a partir de la información guardada. Para ello podemos utilizar el comando sync de uv:

uv sync

Este comando reconstruye el entorno a partir de pyproject.toml y uv.lock. No usa directamente requirements.txt.

Para migrar un proyecto antiguo, puede importarse con:

uv add -r requirements.txt.

Sincronizar obliga al entorno local a coincidir con la descripción del proyecto. Es la operación que se repetirá al recibir el proyecto en otro equipo.

4.- Git

Git es la herramienta que emplearemos para controlar las versiones de nuestro proyecto. Debes conocer como funciona esta herramienta, si tienes alguna duda puedes echar un vistazo rápido a este post.

4.1.- Revisar el fichero .gitignore

Abre .gitignore y verifica que, como mínimo, contiene:

.venv/
__pycache__/
*.py[cod]
.pytest_cache/
.ruff_cache/
.ipynb_checkpoints/

Estas carpetas y archivos se generan de forma automática, dependen del equipo o pueden reconstruirse. Excluirlos mantiene el repositorio pequeño y evita conflictos innecesarios.

Y comprueba que se cumplen las reglas. Por ejemplo, que Git ignora el entorno virtual y una carpeta de caché:

git check-ignore -v .venv
git check-ignore -v __pycache__

No basta con escribir las reglas: esta orden muestra qué línea de .gitignore coincide con cada ruta y permite comprobar el comportamiento antes del primer commit.

Guarda .gitignore, comprueba que estás en la raíz del proyecto y repite la orden.

4.2.- Guarda el punto de partida

Antes del primer commit, revisa exactamente qué archivos se van a guardar con el comando

git status

Este comando muestra los cambios sin preparar.

Para incorporarlos al área de preparación usamos el comando:

git add .

Con el punto incorporamos todos los ficheros y directorios a seguimiento. Todos los que no están en el fichero .gitignore

Si queremos incorporar a seguimiento unicamente un fichero o una carpeta, podemos sustituir el punto por el nombre del elemento en cuestión.

Tecleamos ahora de nuevo en el Terminal:

git status

Esta segunda vez permite revisar la selección antes de hacer un commit, y crear un punto permanente del historial.

Realizamos ahora el commit con un mensaje representativo para que luego podamos identificarlo facilmente

git commit -m "Configura el entorno inicial del proyecto"

Y con el comando log podemos ver el registro de este commit para confirmar su identificador y mensaje, facilitando volver a este estado o comparar cambios posteriores

git log --oneline

Si quieres todo el detalle, puedes hacer sencillamente:

git log

5.- Chuletas de comandos

Finalmente te dejo unas tablas con los comandos principales para git, uv y Terminal. De todos modos, si necesitas conocer los comandos de cada herramienta, normalmente puedes acceder a una lista de los mismos con el comando help. Por ejemplo:

git help

5.1.- Comandos de Git

ComandoUso
git –versionComprueba que Git está disponible.
git statusMuestra los cambios y el área de preparación.
git add .Prepara todos los cambios de la carpeta actual.
git commit -m «mensaje»Guarda un punto del historial con una descripción.
git log –oneline -1Muestra el commit más reciente.
git check-ignore -v rutaExplica qué regla hace que Git ignore una ruta.

5.2.- Comandos de uv

ComandoUso
uv –versionComprueba que uv está disponible.
uv python install 3.13Instala la versión de Python del taller.
uv initInicializa el proyecto en la carpeta actual.
uv add paqueteAñade una dependencia de ejecución.
uv add –dev paqueteAñade una herramienta de desarrollo.
uv remove paqueteElimina una dependencia.
uv syncReconstruye y sincroniza el entorno.
uv run python archivo.pyEjecuta un programa dentro del entorno.
uv treeMuestra el árbol de dependencias.

5.3.- Comandos de Terminal

ComandoUso
mkdir nombreCrea una carpeta.
cd nombreEntra en una carpeta.
cd ..Sube a la carpeta superior.
pwdMuestra la ruta de trabajo actual.
lsLista el contenido en macOS, Linux y PowerShell.
code .Abre la carpeta actual en Visual Studio Code.

Introducción a Git y GitHub

Git y GitHub aparecen juntos en muchos tutoriales, pero cumplen funciones diferentes. Git registra versiones de un proyecto en tu equipo, es decir, con Git vamos a trabajar en local. GitHub aloja repositorios Git en Internet, con lo que estaremos trabajando en remoto. Comprender esta diferencia es crucial y permite saber dónde se están registrando los cambios y qué necesitas hacer para conservarlos o publicarlos.

Algunos conceptos previos

Antes de explicar como emplear Git y GitHub en nuestros proyectos, conviene introducir algunos conceptos previos.

  • Repositorio: Es el contenedor que almacena todo el historial de un proyecto, incluyendo todos los archivos, carpetas y metadatos de versiones.
  • Staging area (área de preparación): Es una zona donde se seleccionan los cambios que se incluirán en el próximo commit. El comando git add incorpora los cambios a esta zona y git commit guarda la selección en el historial local.
  • Commit: Una instantánea del estado completo del proyecto en un momento específico, acompañada de información sobre quién realizó los cambios y por qué.
  • Branch (Rama): Una línea de desarrollo independiente que permite trabajar en características diferentes sin afectar el código principal.
  • Merge (Fusión): El proceso de combinar cambios de diferentes ramas en una sola, integrando el trabajo realizado en paralelo.
  • Push: Es la operación que envia los commits de una rama local a un repositorio remoto, como GitHub, y actualiza allí la rama correspondiente. Se realiza con el comando git push
  • Remoto: Una versión del repositorio almacenada en otro lugar (como GitHub) que facilita la colaboración entre múltiples desarrolladores.

Qué guarda un repositorio

Un repositorio Git conserva el historial de los archivos que decides versionar. Estos archivos los has marcado previamente con el comando git add. También puedes indicar a git que ignore determinados ficheros o carpetas, incluyendolos en el fichero .gitignore. Algunos archivos o carpetas de las que no vas a querer versionar son por ejemplo un fichero con tus APIKeys o la carpeta de entorno.

En un proyecto local, la carpeta .git contiene los archivos que vas modificando y has indicado a git que este atento a sus modificaciones, porque vas a versionarlos. Cuando el proyeto llegue a una fase con cierta entidad, puedes decidir que es el momento de hacer un commit y guardar una foto del estado del proyecto.

Un commit registra una instantánea del contenido preparado, junto con datos de autoría, fecha y mensaje. Cada commit que hagas tiene su identificador que permite consultar qué cambió y comparar estados. Además puedes añadir un mensaje al commit que luego te ayude a recordar el estado del proyecto cuando hiciste el commit. El mensaje debería ser explicito y descriptivo de dicha instantanea, por ejemplo: «primera versión sin depurar. Oct 26».

Se trabaja en una rama del proyecto, que es una referencia que avanza con los commits de una línea de desarrollo. La rama principal suele llamarse main, aunque otros proyectos utilizan master. Crear una rama permite separar una tarea, y de esta manera trabajar en la tarea sin afectar a la rama main del desarrollo. Una vez se halla validado el desarrollo de una rama, podemos fusionarla a la rama main con un merge.

Las tres zonas de Git

Trabajando en local con Git, tenemos que distinguir 3 zonas fundamentales:

Las tres zonas Git trabajando en local
Las tres zonas Git trabajando en local (Imagen generada con IA)

La primera zona es el directorio de trabajo del proyecto, a fin de cuentas ahí es donde están los ficheros del proyecto que vamos a ir modificando, de los que git hará seguimiento.

Con git add, marcamos para git los ficheros que tiene que vigilar, y cada vez que halla una modificación de esos ficheros, los pasará al área de Staging. Una especie de limbo donde los cambios esperan hasta que juzguemos que ya hemos avanzado bastante y conviene guardar una versión del proyecto.

Para guardar la versión actual del proyecto, realizaremos un commit, y la instantanea tomada se guardara en el repositorio local.

El fichero .gitignore

El fichero .gitignore contiene las reglas que Git emplea para decidir qué archivos y carpetas debe ignorar y no hacer seguimiento de ellos. Se suele colocar en la raíz del proyecto y se escribe una regla por línea.

Cómo funciona el fichero .gitignore (Imagen generada con IA)

Por ejemplo, las reglas que contiene el fichero .gitignore en la imagen de arriba serían:

  • *.log: Indica a Git que debe ignorar los archivos de extensión log.
  • temp/: debe ignorarse la carpeta temp y su contenido.
  • .env: excluye el fichero de nombre .env

Qué aporta GitHub

GitHub aporta un repositorio en la nube, donde guardar una versión de tu proyecto. Para acceder a ella, vas a usar lo que se conoce como un remoto, que no es otra cosa que un nombre asociado a una dirección, a una url. El nombre más habitual es origin.

Sincronización del repositorio local y el remoto
Sincronización del repositorio local y el remoto

Para guardar una versión del proyecto en el repositorio al que apunta el remoto, es decir, para hacer un commit al repositorio en la nube, se emplea la instrucción git push.

Si lo que queremos es descargar información remota se usa la instrucción git fetch, y git pull para la descarga e integración en la rama local.

Cuando lo que queremos es hacer una copia local del repositorio remoto, emplearemos la instrucción git clone.

Git funciona sin conexión para las operaciones locales. Por el contrario, el acceso a GitHub sí requiere conectividad y permisos. Un repositorio privado limita quién puede acceder al código, pero no justifica guardar contraseñas ni claves en sus commits. Toda la información sensible que no quieres que se suba al remoto debe estar indicada en el fichero .gitignore

Talleres

Para practicar con Git y GitHub, de ire dejando una serie de talleres las próximas semanas

Metodologías para proyectos de datos

Un proyecto de datos necesita una pregunta útil, una forma de organizar el trabajo y criterios para comprobar si finalmente tenemos o no éxito. Para organizar todo esto, tenemo que emplear una metodología que nos ayude a conectar el análisis técnico con el problema que se quiere resolver y a revisar las decisiones cuando aparecen nuevas evidencias.

¿Qué es un proyecto?

Antes de nada, empecemos definiendo lo que es un proyecto, sin traernoslo todavía a la categoría de proyecto de datos. En general, un proyecto es un esfuerzo temporal orientado a obtener un resultado único. Es temporal porque tiene un comienzo y un fin, los proyectos hay que terminarlos y sino hay que matarlos, pero no podemos vivir con el «muerto en el salón». Un proyecto tiene un objetivo y requiere coordinar actividades, recursos y personas.

Normalmente nos vamos a encontrar con tres KPIs, tres métricas ampliamente empleadas para medir la desviación del proyecto, y obviamente corregirla. Estas métricas las escribo en inglés porque seguramente será así como te las encuentres:

  • On time: mide la desviación en tiempo sobre la planificación.
  • On budget: mide la desviación sobre el presupuesto, tanto como si te estás pasando como si te está sobrando.
  • On scope: mide la desviación sobre el objetivo.

Estas métricas se mide a nivel de tareas, para la situación actual del proyecto, y cuando se tenga una desviación importante en alguna de las métricas puede forzar a una replanificación del proyecto.

Proyecto vs Proceso

En una empresa, básicamente puedes trabajar en proyectos, procesos o en ambos a la vez. Por ello me parece importante que distingas ambos conceptos claramente, y que sepas discernir en que entorno de juego estás.

Los proyectos son esfuerzos con una duración temporal, mientras que los procesos se repiten constantemente, pueden verse como ciclicos. Por ello, cuando trabajes en proyectos, se te va a pedir eficacia, es decir que entregues lo comprometido en las condiciones acordadas. Empleando las métricas vistas antes, esto puede traducirse en entregar el resultado esperado, dentro del plazo y sin salirse del presupuesto. Por el contrario, cuando trabajes en un proceso, se te va a exigir eficiencia, ya no se trata de entregar lo comprometido, sino de hacerlo mejor a cada ciclo, lo que puede traducirse por entregar más valor o entregar el mismo con menos coste.

Los roles responsables de proyectos, normalmente jefe de proyecto o director de proyecto, aplicaran técnicas de gestión de proyectos, y probablemente estarán englobados en una oficina de proyectos (PMO: Project Management Office). El rol de responsable de proceso suele ser el BPO (Business Process Owner) por sus siglas en inglés, que aplicará técnicas de mejora continua y seguramente pertenecerá al departamento de Calidad.

Comparativa entre proyectos y procesos
Proyectos vs Procesos

Metodologías de proyectos

Existen multiples metodologías para la gestión de proyectos, que logicamente tambi´én aplican a los proyectos de datos. De manera un poco general, estas metodologías pueden agruparse en dos familias: las metodologías formal o predictiva, y las metodologías ágiles.

Lo que pretendo en este apartado es darte una comparativa sencilla entre ambas familias, sin entrar en ninguna técnica especifica. Con este propósito, creo que el cuadro siguiente proporciona una comparativa sencilla y clara:

Formal o predictivaÁgiles
Requerimientos: se cierran al inicio del proyecto, siendo posteriormente muy costoso cambiarlos.Se obtiene el feedback periódico del cliente y se van adaptando el resultado.
Se da mucha importancia a la planificación.Se planifica el corto. El largo plazo no se cumple nunca.
Se siguen una serie de fases predeterminadas.Se trabaja en lapsos de tiempo corto, entre interacciones con el cliente, en las que se obtiene su feedback.
Se distribuye el trabajo en cascada.Los miembros del equipo se autoasignan el trabajo y toman la responsabilidad del mismo.
El objetivo es lograr el producto previsto en el tiempo planificado y costes estimados.El objetivo es la satisfacción del Cliente

Cómo elegir la mejor metodología para un proyecto de datos

La metodología debe encajar con las características del proyecto y con la empresa que la aplicará. Influyen la claridad de los requisitos, el acceso a los datos, la incertidumbre técnica y la capacidad del equipo para revisar avances con las personas que tomarán decisiones.

Cuando el resultado está bien definido, una planificación detallada ayuda a coordinar tareas y dependencias. Un cronograma permite concretar entregas y responsabilidades. Aquí empleariamos una metodologías de la familia formal o predictiva.

En cambio, si todavía se desconoce qué información será útil o qué resultados pueden obtenerse, conviene trabajar mediante iteraciones cortas que permitan aprender y ajustar el rumbo. En esta caso, escogeríamos una metodologías de la familia de las águiles.
La elección admite combinaciones. Es posible fijar un presupuesto, una fecha de revisión y unos entregables, mientras el equipo explora distintas formas de preparar los datos o resolver el problema. La planificación aporta coordinación y las iteraciones permiten gestionar la incertidumbre.

CRISP-DM

Finalmente quiero introducir un marco especifico para los proyectos de datos, se trata del framework CRISP-DM, desarrollado por IBM.

Framework CRISP-DM

Lo que más me gusta de este framework es las dos primeras fases: business understanding y data understanding. Sin duda, los perfiles hibridos, que sean capaces de entender el negocio y que sepan como trabajar con los datos, serán los más valiosos, los que puedan extraer de los datos información valiosa para el negocio. Hoy en día, todavia hay muchas empresas con muchos datos que no saben como sacarles partido.

Te dejo una breve descripción de las fases de la figura.

  1. Comprensión del negocio: Se concreta el problema, el uso esperado del resultado y los criterios de éxito. La pregunta inicial es qué decisión se pretende mejorar.
  2. Comprensión de los datos: Se exploran las fuentes disponibles, su contenido y sus limitaciones. Esta revisión permite valorar si la información sirve para abordar el objetivo.
  3. Preparación de los datos: Se construye el conjunto de datos que utilizará el análisis. Puede ser necesario combinar fuentes, corregir inconsistencias y transformar variables.
  4. Modelado: Se prueban técnicas adecuadas al problema y a la información disponible. Las primeras aproximaciones sirven como referencia para valorar alternativas más complejas.
  5. Evaluación: Se comprueba si los resultados responden a la necesidad inicial. El rendimiento técnico se interpreta junto con las condiciones reales de uso.
  6. Despliegue: Se entrega el resultado de una forma utilizable. Puede ser un informe, una aplicación a traves de una API o una integración en el trabajo habitual.

Si quieres más detalle de estas fases, lo mejor es que consultes directamente la información que proporciona IBM, que es el creador del framework. Puedes encontrarla en el siguiente enlace.