datatools-dev/docs/USER-GUIDE.es.md

🌐 Idioma: Español · English

Guía del usuario

Versión: 1.6 · Actualizado: 2026-05-13

0. Primer arranque — activación

DataTools debe activarse antes de desbloquear cualquier herramienta. En el primer arranque verás la pantalla Activar.

Introduce tu nombre completo y correo, pega el código de licencia del correo de compra (empieza con DTLIC1:) y pulsa Activar. La renovación funciona igual: pega el código de renovación y pulsa Aplicar renovación.

Niveles:

Nivel	Herramientas
Lite	Buscar duplicados · Limpiar texto · Estandarizar formatos
Core	Las 9 herramientas

Un usuario Lite que abra una herramienta exclusiva de Core verá un mensaje "Actualiza tu licencia". La página de inicio también muestra una marca 🔒 Bloqueado en las tarjetas de las herramientas que tu nivel no incluye. Para actualizar, pega un código Core en la página Activar.

Cada licencia dura 1 año. La barra lateral muestra tu nivel y los días restantes en todo momento; aparece un aviso de renovación 30 días antes de la caducidad. El archivo de licencia vive en ~/.datatools/license.json (Windows: C:\Users\<tú>\.datatools\license.json).

Para usar la misma licencia en otro equipo: desactiva éste (página Activar → Desactivar este dispositivo) y vuelve a pegar tu código en el nuevo.

1. Instalación

No necesitas tener Python ni permisos de administrador — el paquete trae su propio intérprete y todas las dependencias. Dos formatos por sistema operativo, elige el que tu política de TI permita:

• Instalador — crea automáticamente acceso directo en el escritorio + entrada en el menú Inicio / Launchpad. Recomendado para la mayoría.
• .zip portable — descomprime y haz doble clic. No toca el registro, se ejecuta desde cualquier lugar (escritorio, USB, recurso de red). Úsalo si no puedes ejecutar instaladores, quieres una instalación de una sola carpeta que puedas copiar entre equipos, o estás evaluando antes de instalar.

Ambos formatos son idénticos por dentro: mismo Python, mismas dependencias, mismo comportamiento de arranque.

1.1 Windows

Opción A — Instalador (DataTools-<ver>-win-setup.exe)

1. Descarga DataTools-<ver>-win-setup.exe desde tu correo de licencia o GitHub Releases.
2. Doble clic en el instalador. La primera vez, Windows SmartScreen mostrará "Windows protegió tu PC" — pulsa Más información → Ejecutar de todas formas. (Este aviso solo aparece una vez por compilación hasta que tengamos un certificado EV de firma de código.)
3. Acepta la ruta de instalación por usuario (%LOCALAPPDATA%\Programs\DataTools por defecto — no pide UAC). Marca Crear acceso directo en el escritorio si lo quieres (activado por defecto).
4. Pulsa Instalar y luego Finalizar. El instalador te ofrece lanzar DataTools al terminar.
5. A partir de ahora ejecútalo desde: Menú Inicio → DataTools, el acceso directo del escritorio, o escribiendo DataTools en Ejecutar (Win+R) / cmd.

Para anclarlo a la barra de tareas, lanza la app una vez, clic derecho en su icono de la barra de tareas, y Anclar a la barra de tareas. Windows requiere este paso manual — ningún instalador puede anclar por programa.

Opción B — Portable (DataTools-<ver>-win-portable.zip)

1. Descarga DataTools-<ver>-win-portable.zip.
2. Clic derecho en el .zip → Extraer todo… → elige una carpeta (p. ej. C:\Tools\DataTools).
3. Abre la carpeta DataTools\ extraída, doble clic en DataTools.exe. El aviso de SmartScreen aparece solo la primera vez.
4. Para crear tu propio acceso directo en el escritorio: clic derecho en DataTools.exe → Enviar a → Escritorio (crear acceso directo).

Desinstalar (solo instalador): Configuración → Aplicaciones → DataTools → Desinstalar. Portable: borra la carpeta.

1.2 macOS

Opción A — DMG instalador (DataTools-<ver>-mac.dmg)

1. Descarga DataTools-<ver>-mac.dmg.
2. Doble clic en el .dmg. Se abre una ventana de Finder con el icono DataTools y un alias Aplicaciones.
3. Arrastra DataTools sobre Aplicaciones. Espera a que termine la copia y expulsa el DMG.
4. En compilaciones sin firma, el primer arranque muestra "No se puede abrir 'DataTools' porque no se puede verificar al desarrollador". Solución: clic derecho en DataTools en /Aplicaciones → Abrir → confirma Abrir en el diálogo. macOS recuerda la elección — los siguientes arranques no muestran nada.
5. Ejecútalo desde Launchpad, Spotlight (⌘ Espacio → escribe "DataTools"), o Aplicaciones en Finder.

Para mantener DataTools en el Dock: lanza la app, clic derecho en su icono del Dock → Opciones → Mantener en el Dock. macOS no permite que los instaladores fijen al Dock automáticamente.

Opción B — Portable (DataTools-<ver>-mac-portable.zip)

1. Descarga DataTools-<ver>-mac-portable.zip. Safari descomprime al descargar por defecto; en Finder verás DataTools.app directamente.
2. Mueve DataTools.app a Aplicaciones si quieres que aparezca en Launchpad — o déjalo en el escritorio, un USB o un recurso de red. La .app portable se ejecuta desde cualquier sitio.
3. Doble clic en DataTools.app. Clic derecho → Abrir la primera vez (misma rutina que con el DMG).

Desinstalar: arrastra DataTools.app a la Papelera. Tus archivos de datos siguen donde estén — la app no instala nada más.

1.3 Linux

DataTools-<ver>-linux-x86_64.AppImage ya es portable — no hay .zip aparte.

1. Descarga el .AppImage.
2. chmod +x DataTools-*.AppImage.
3. Doble clic, o ejecútalo desde la terminal.

Si tu distro no incluye FUSE 2: sudo apt install libfuse2 (Debian/Ubuntu) o equivalente.

1.4 Qué pasa al arrancar por primera vez

El lanzador (llamado DataTools.exe / DataTools.app / DataTools.AppImage) hace tres cosas, en orden:

1. Elige un puerto TCP libre en 127.0.0.1 — normalmente el 8501; si está ocupado prueba 8502, 8503, …
2. Arranca un servidor Streamlit local en ese puerto. El servidor solo está enlazado a localhost, nunca a tu red.
3. Abre tu navegador predeterminado en http://127.0.0.1:<puerto>/. Si el navegador no se abre en 5 segundos, pega esa URL manualmente.

La ventana del lanzador queda abierta en segundo plano. Cerrarla detiene el servidor — la pestaña del navegador dirá "no se puede acceder a este sitio" la próxima vez.

1.5 Cómo funciona la GUI

• Se ejecuta localmente en tu equipo. Sin internet, sin subidas.
• El navegador es solo la capa de visualización. Cerrarlo NO detiene la app — cierra la ventana del lanzador (o sal de la .app de macOS desde el Dock) para terminar del todo.
• ¿Prefieres la terminal? Cada herramienta incluye también una CLI — ver Sección 3.

1.6 Requisitos del sistema

• Windows 10/11 (64 bits), macOS 11+, Linux moderno (2020+).
• Navegador moderno (Chrome, Edge, Firefox, Safari, últimos 3 años).
• ~500 MB de espacio libre en disco (el paquete ocupa ~300 MB; el resto es espacio de trabajo para CSV grandes).

OCR para PDFs escaneados viene incluido — Tesseract 5.5 y el modelo en inglés eng.traineddata vienen dentro de cada instalador / portable / AppImage. La ruta de extracción de PDFs escaneados del Extractor de PDF funciona sin configuración adicional; no hace falta instalar nada por separado. (Quien ejecute desde un checkout con pip install -r requirements.txt sigue necesitando Tesseract del sistema en el PATH — ver DEVELOPER.md §PDF Extractor — bundled Tesseract (solo en inglés).)

Matriz de soporte completa: REQUIREMENTS.md (solo en inglés).

2. Qué incluye

#	Herramienta	Propósito	Estado
01	Buscar duplicados	Coincidencia exacta + difusa, 5 normalizadores, auditoría	Listo
02	Limpiar texto	Espacios, caracteres tipográficos, BOM, finales de línea, mayúsculas/minúsculas	Listo
03	Estandarizar formatos	Fechas / teléfonos / correos / direcciones / nombres / monedas / booleanos	Listo
04	Corregir valores faltantes	Nulos disfrazados, imputación, descarte por umbral	Próximamente
05	Mapear columnas	Renombrar + aplicar esquema	Próximamente
06	Detectar valores atípicos	z-score, IQR, multivariante	Próximamente
07	Combinar archivos	Combina varios archivos	Próximamente
08	Verificación de calidad	Reglas + informe PDF/Excel	Próximamente
09	Flujos automatizados	Lanzador multi-herramienta de un clic	Próximamente

Datos de muestra (samples/): messy_sales.csv, bank_export.xlsx.

3. Uso

3.1 GUI (recomendada)

1. Inicia el paquete.
2. Selecciona una herramienta en la barra lateral.
3. Suelta tu archivo (o elige una muestra).
4. Los valores por defecto están preconfigurados — pulsa Ejecutar para previsualizar.
5. Pulsa Guardar salida para escribir el archivo limpio.

Las opciones avanzadas se encuentran en paneles desplegables. El archivo original nunca se modifica.

Ayuda en la herramienta: cada página tiene un botón Help a la derecha del título. Al pulsarlo se abre una ventana emergente con una guía compacta (Cuándo usarla · Pasos · Ejemplos · Consejo). Úsala como recordatorio a media tarea — la ventana se cierra al hacer clic fuera y tus datos no se ven afectados.

Navegación lateral: la barra lateral agrupa las herramientas en secciones (Análisis, Limpiadores de datos, Transformaciones, Automatizaciones). Cada cabecera muestra + cuando está plegada y − cuando está desplegada — pulsa la cabecera para alternar.

3.2 CLI

deduplicator       customers.csv [--apply]
text-cleaner       messy.csv     [--apply]
format-standardize feed.csv      [--apply]

Ayuda: deduplicator --help. Referencia completa: CLI-REFERENCE.es.md.

3.3 Orden de ejecución (cuando uses las herramientas manualmente)

Si no usas Flujos automatizados, sigue este orden:

1. 02 Limpiar texto primero — normaliza espacios y caracteres especiales.
2. 03 Estandarizar formatos — fechas, teléfonos, etc. necesitan texto limpio.
3. 04 Corregir valores faltantes — códigos centinela se ocultan como números.
4. 05 Mapear columnas — esquema antes que estadísticas de atípicos.
5. 06 Detectar valores atípicos — necesita datos numéricos limpios. Calcular estadísticas con NaN o -999 envenena los resultados.
6. 07 Combinar archivos, 08 Verificación de calidad según sea necesario.
7. 01 Buscar duplicados es flexible en cuanto al orden (normaliza internamente para la coincidencia).

Flujos automatizados aplica este orden automáticamente.

3.4 Idioma

La barra lateral tiene un selector Language / Idioma. Se incluyen dos paquetes hoy:

• English (por defecto)
• Español

Elige el idioma una vez — la opción persiste durante la sesión y el selector es visible desde cualquier página. Cambia cuando quieras; la página se vuelve a renderizar en su sitio sin perder datos.

Cobertura (v1.6): página de inicio, tarjetas de herramientas, panel de carga y análisis, lista de hallazgos, indicador de la verificación de normalización CSV, selector lateral y pantalla de cierre. Los cuerpos de cada página de herramienta (etiquetas de opciones avanzadas, indicaciones del mapeador de columnas, etiquetas de revisión de duplicados) están planificados para paquetes futuros — actualmente se muestran en inglés en ambos modos. Si una cadena que esperabas ver traducida no cambia, se trata de una clave de paquete pendiente, no de un fallo del selector; escribe a soporte adjuntando una captura.

4. Verificación de Revisar y Normalizar

Cada archivo subido se analiza antes de que cualquier herramienta lo toque.

Niveles de confianza:

• Alta — seguras de ida y vuelta. El botón "Corregir automáticamente lo de alta confianza" las aplica todas con un clic.
• Media — normalmente correctas, con falsos positivos ocasionales. Previsualiza primero.
• Baja — heurística. Desactivada por defecto; opt-in por hallazgo.
• Error — bloquea la verificación (archivo vacío, U+FFFD, filas no reparables).

Sustitución de codificación: cuando el detector reporta encoding_uncertain o detectas mojibake (é) o caracteres <EFBFBD>, elige el codepage correcto en la parte superior de la página (cp1252 para Excel occidental, KOI8-R para ruso antiguo, Big5 para chino tradicional, …) → Re-analizar.

Salida avanzada: un desplegable ⚙️ en la descarga te permite ajustar la codificación, el delimitador y el terminador de línea. El nombre del archivo descargado se ajusta automáticamente (.tsv para tabulador, .csv en los demás casos).

5. Salida

Cada ejecución escribe:

• Archivo limpio junto al original (o donde indiques).
• Archivo de auditoría (cambios celda por celda en herramientas de texto/formato, grupos de coincidencia en deduplicación).
• Registro con marca de tiempo en logs/.

El archivo original nunca se modifica.

6. Solución de problemas

• La GUI no se abre / el navegador no se inicia — espera 10-15 s; visita manualmente http://127.0.0.1:8501 (o el puerto que muestre la ventana del lanzador). Error de puerto ocupado → cierra otras instancias. El lanzador recorre los puertos 8501–8550 buscando uno libre, así que una instancia colgada puede desplazar la URL.
• ¿Por qué se abre el navegador? — patrón de aplicación web local (igual que Jupyter o RStudio). Nada sale de tu equipo.
• Windows SmartScreen — pulsa "Más información" → "Ejecutar de todas formas". Una sola vez por compilación hasta que tengamos un certificado EV.
• macOS "La aplicación está dañada" / "no se puede verificar al desarrollador" — clic derecho en la app → Abrir → confirma. Si el mensaje persiste, el archivo se corrompió en tránsito — vuelve a descargarlo. Último recurso: xattr -cr /Applications/DataTools.app limpia el atributo de cuarentena.
• macOS — el .zip portable extraído no abre — Safari descomprime al descargar; si ves una carpeta __MACOSX/ o archivos ._DataTools.app usaste otro descompresor. Vuelve a extraer con la Utilidad de Archivo integrada (clic derecho en el .zip → Abrir con → Utilidad de Archivo) para preservar los metadatos de la .app.
• Windows — el antivirus pone en cuarentena DataTools.exe del portable — tu antivirus no reconoce el paquete. Añade la carpeta extraída a la lista blanca. El instalador .exe activa menos antivirus porque es un envoltorio Inno Setup conocido.
• El AppImage de Linux no se ejecuta — chmod +x archivo.AppImage. Si falta FUSE → sudo apt install libfuse2.
• Lento con archivos grandes — por encima de ~100k filas tarda más; la barra de progreso lo indica. Para millones de filas → usa la CLI directamente.
• ¿Dónde guarda la app mi licencia / configuración? — ~/.datatools/ en macOS y Linux, C:\Users\<tú>\.datatools\ en Windows. Tus archivos de entrada y salida siguen donde los dejes; la app nunca los copia a otro sitio.
• Necesito ayuda — escribe al correo que aparece en tu recibo de compra.

7. Licencia

Usuario único. Consulta LICENSE.txt.