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 instalado — el paquete es autocontenido.

Sistema operativo	Archivo	Cómo
Windows	BundleName-Setup-1.0.exe	Doble clic en el instalador → acceso directo en el escritorio.
macOS	BundleName-1.0.dmg	Monta el DMG y arrástralo a Aplicaciones. Firmado y notarizado.
Linux	BundleName-1.0.AppImage	chmod +x, doble clic. (También hay un .tar.gz de respaldo.)

Al iniciar la app, se abre tu navegador predeterminado en una página local (http://localhost:8501).

Cómo funciona la interfaz gráfica (GUI)

• Se ejecuta localmente en tu equipo. Sin internet, sin subidas.
• El navegador es solo la capa de visualización. Cerrarlo detiene el programa subyacente.
• ¿Prefieres la terminal? Cada herramienta incluye también una interfaz de línea de comandos (CLI) — ver Sección 3.

Requisitos del sistema

• Windows 10/11 (64 bits), macOS 11+, Linux moderno (2020+).
• Navegador moderno (Chrome, Edge, Firefox, Safari, últimos 3 años).
• ~400-500 MB de espacio libre en disco.

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.

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://localhost:8501. Error de puerto ocupado → cierra otras instancias.
• ¿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". Estándar para software sin firma EV.
• macOS "La aplicación está dañada" — descárgala de nuevo (probablemente se corrompió en tránsito).
• El AppImage de Linux no se ejecuta — chmod +x archivo.AppImage. Si falta FUSE → sudo apt install libfuse2 o usa el .tar.gz.
• 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.
• Necesito ayuda — escribe al correo que aparece en tu recibo de compra.

7. Licencia

Usuario único. Consulta LICENSE.txt.