Manual de Usuario PetroPyQAPF

Introducción

¿Qué es PetroPyQAPF?

PetroPyQAPF es una aplicación de escritorio en Python diseñada para apoyar la clasificación reproducible de rocas ígneas y la generación de informes técnicos. El software separa la decisión modal formal del contraste geoquímico, apoyo probabilístico, síntesis interpretativa, referencia mineralógica, revisión de imágenes petrográficas y presentación de reportes.

¿Quién Debe Usar PetroPyQAPF?

• Estudiantes aprendiendo petrología ígnea y clasificación de rocas
• Geólogos realizando análisis petrográfico en investigación académica
• Docentes demostrando métodos de clasificación IUGS-QAPF
• Investigadores que requieren flujos de trabajo reproducibles y trazables

Instalación y Configuración

Requisitos del Sistema

• Windows 10/11 (64-bit)
• 4 GB RAM mínimo (8 GB recomendado)
• 500 MB de espacio disponible en disco
• Microsoft Word (para generación de reportes PDF)
• Conexión a internet (para autenticación y funciones opcionales de IA)

Pasos de Instalación

1. Descarga la última versión desde el sitio oficial
2. Extrae el archivo ZIP a tu ubicación preferida
3. Ejecuta PetroPyQAPF.exe desde la carpeta extraída
4. En el primer inicio, autentícate con tu cuenta académica de Google
5. Selecciona tu idioma preferido (Español o Inglés)

Autenticación

PetroPyQAPF usa autenticación Google/Firebase para verificar acceso académico. Solo direcciones de correo autorizadas pueden ejecutar la aplicación. La autenticación no transmite muestras, datos químicos ni reportes generados—solo valida tus credenciales de acceso.

Primeros Pasos

Creando Tu Primer Proyecto

1. Inicia PetroPyQAPF
2. Haz clic en "Nuevo Proyecto" en el menú principal
3. Ingresa un nombre de proyecto y descripción opcional
4. Elige entre Entrada Manual o Importar desde CSV/Excel

Entrada Manual de Muestras

Para clasificación individual de muestras:

1. Haz clic en "Agregar Muestra"
2. Ingresa identificación de muestra (nombre, ubicación, fecha)
3. Selecciona dominio: Plutónico o Volcánico
4. Ingresa mineralogía modal (porcentajes Q, A, P, F)
5. Opcionalmente agrega datos petrográficos auxiliares (M, Pl, An, Px, Ol, Anf)
6. Opcionalmente ingresa geoquímica de óxidos mayores para comparación CIPW

Importación por Lote desde CSV/Excel

Para múltiples muestras:

1. Prepara tu archivo de datos con columnas: Sample_ID, Q, A, P, F, Domain
2. Haz clic en "Importar Lote"
3. Selecciona tu archivo CSV o Excel
4. Mapea columnas a campos de PetroPyQAPF
5. Revisa y confirma muestras importadas

Clasificación Modal

Entendiendo la Lógica IUGS-QAPF

El sistema IUGS-QAPF clasifica rocas ígneas basándose en las proporciones relativas de cuatro grupos minerales:

• Q - Cuarzo y minerales equivalentes
• A - Feldespatos alcalinos (ortoclasa, microclina, sanidina, etc.)
• P - Plagioclasas
• F - Feldespatoides (nefelina, leucita, etc.)

Selección de Dominio

PetroPyQAPF separa dominios plutónico (grano grueso, intrusivo) y volcánico (grano fino, extrusivo). Cada dominio tiene nomenclatura específica:

• Plutónico: Granito, Granodiorita, Tonalita, Diorita, Gabro, etc.
• Volcánico: Riolita, Dacita, Andesita, Basalto, Traquita, etc.

Enrutamiento Especializado

Para rocas fuera del rango QAPF estándar:

• Rocas ultramáficas (M > 90%): Usa diagramas ternarios Ol-Opx-Cpx
• Rocas gabroicas: Ternarios especializados Pl-Px-Ol y Pl-Px-Anf
• Clasificación de foidolitas: Para rocas ricas en feldespatoides

Interpretación de Resultados

Después de ingresar datos modales, PetroPyQAPF proporciona:

• Nombre oficial de roca desde posición IUGS-QAPF
• Coordenadas de posición dentro del diagrama ternario
• Advertencias de validación si se detectan problemas de calidad o consistencia de datos
• Nombres alternativos para casos de frontera

Comparación Normativa CIPW

¿Qué es CIPW?

La norma CIPW calcula un ensamblaje mineral idealizado y anhidro a partir de datos geoquímicos de roca total. Proporciona una perspectiva composicional secundaria que complementa la observación modal.

Ingreso de Datos de Óxidos

Ingresa porcentajes de óxidos mayores (% en peso):

• SiO₂, TiO₂, Al₂O₃, Fe₂O₃, FeO, MnO, MgO, CaO, Na₂O, K₂O, P₂O₅

Comparación Modal vs. CIPW

PetroPyQAPF proyecta minerales normativos CIPW sobre el diagrama QAPF y calcula:

• Distancia: Distancia euclidiana entre posiciones modal y normativa
• Nivel de consistencia: Acuerdo Alto, Moderado o Bajo
• Advertencias: Señales para discrepancias significativas que pueden indicar alteración, problemas analíticos o complejidad magmática

Por Qué Modal y CIPW Pueden Diferir

• Alteración: Meteorización o alteración hidrotermal cambia la química mineral
• Historia magmática: Texturas cumuladas, fraccionamiento cristalino o mezcla
• Incertidumbre analítica: Errores en conteo modal o análisis geoquímico
• Supuestos CIPW: La norma asume condiciones idealizadas de equilibrio

Apoyo de Machine Learning

Arquitectura de Modelos ML

PetroPyQAPF usa modelos ML específicos por dominio entrenados con conjuntos de datos geoquímicos regionales:

• Dominio volcánico: Clasificador XGBoost
• Dominio plutónico: Clasificador Random Forest

Leyendo la Salida ML

Para cada muestra, la capa ML proporciona:

• Predicción principal: Clase de roca más probable basada en geoquímica
• Puntaje de confianza: Probabilidad de la predicción principal (0-100%)
• Clases alternativas: Segunda y tercera clases más probables con puntajes
• Indicador de concordancia: Si la predicción ML coincide con clasificación modal

Cuando ML No Concuerda con Modal

Si clasificaciones ML y modal difieren significativamente:

1. Revisa precisión del conteo modal
2. Verifica alteración o meteorización
3. Verifica calidad analítica de óxidos
4. Considera complejidad magmática (mezcla, cumulados)
5. Consulta la interpretación NIM para contexto

Modelo de Interpretación Normalizada (NIM)

¿Qué es NIM?

NIM sintetiza evidencia de capas modal, CIPW y ML en una interpretación coherente. Cuantifica:

• Nivel de soporte: Acuerdo entre métodos de clasificación
• Incertidumbre: Confianza en la clasificación formal
• Factores de evidencia: Pesos para datos modales, geoquímicos y probabilísticos
• Recomendaciones: Acciones de seguimiento sugeridas (recontar, re-analizar, etc.)

Niveles de Soporte

• Alto: Todos los métodos concuerdan; clasificación es robusta
• Moderado: Algo de desacuerdo; revisión recomendada
• Bajo: Conflictos significativos; re-evaluación petrográfica necesaria

Usando NIM Efectivamente

NIM no reclasifica rocas. Te ayuda a entender la calidad y coherencia de tu clasificación. Usa recomendaciones NIM para priorizar muestras para revisión detallada o re-análisis.

Visor Petrográfico

Cargando Fotomicrografías

1. Selecciona una muestra en tu proyecto
2. Haz clic en "Adjuntar Imagen" en el panel Visor
3. Elige PPL (luz plano-polarizada) o XPL (luz polarizada cruzada)
4. Navega a tu archivo de fotomicrografía (JPG, PNG, TIFF)
5. Repite para cargar imágenes PPL y XPL para comparación

Herramientas de Comparación

Cuando ambas imágenes PPL y XPL están cargadas:

• Modo lado a lado: Ver imágenes una junto a otra
• Modo deslizador: Divisor vertical u horizontal para comparar imágenes registradas
• Zoom y paneo: Navegación sincronizada en ambas vistas

Calibración de Escala

1. Haz clic en "Calibrar Escala"
2. Dibuja una línea sobre un diámetro conocido (ej. campo de visión, barra de escala)
3. Ingresa la medición real en micrómetros (µm) o milímetros (mm)
4. Mediciones y anotaciones ahora mostrarán dimensiones calibradas

Anotaciones y Mediciones

• Marcadores de punto: Identificar granos minerales
• Mediciones de línea: Tamaño de grano, espaciado de maclas
• Etiquetas de texto: Anotar nombres de minerales o características
• Selección de área: Resaltar zonas de interés

Capturar para Reportes

Haz clic en "Capturar Vista" para guardar el estado actual del visor (incluyendo anotaciones) como imagen. Imágenes capturadas se incluyen automáticamente en reportes exportados.

Atlas Mineralógico

Accediendo al Atlas

Haz clic en "Atlas Mineralógico" en la barra de herramientas principal para abrir la guía de referencia integrada de minerales formadores de rocas.

Búsqueda y Navegación

• Búsqueda por nombre: Encuentra minerales por nombres comunes o sistemáticos
• Búsqueda por fórmula: Busca por fórmula química (ej. SiO₂, CaAl₂Si₂O₈)
• Filtro por categoría: Navega por grupo mineral (feldespatos, piroxenos, anfíboles, etc.)

Fichas de Información Mineral

Cada entrada mineral incluye:

• Fórmula química y sistema cristalino
• Propiedades ópticas: Relieve, birrefringencia, ángulo de extinción, pleocroísmo
• Ocurrencias comunes: Tipos de rocas típicos y contextos geológicos
• Características distintivas: Criterios clave de identificación
• Referencias visuales: Ejemplos de fotomicrografías PPL y XPL

Soporte Bilingüe

El atlas mineral está disponible en Español e Inglés. El contenido cambia automáticamente para coincidir con el idioma seleccionado de la aplicación.

Reportes y Exportación

Generación de Reportes

1. Selecciona una o más muestras en tu proyecto
2. Haz clic en "Generar Reporte"
3. Elige formato de reporte:
   • JSON: Datos legibles por máquina para archivado o integración
   • Texto: Resumen en texto plano para revisión rápida
   • PDF: Reporte técnico formal con diagramas e imágenes

Contenidos del Reporte PDF

El reporte PDF formal incluye:

• Metadatos de proyecto y muestra
• Resultados de clasificación modal con posición en diagrama QAPF
• Datos normativos CIPW y métricas de comparación
• Predicciones ML y puntajes de confianza
• Interpretación NIM y recomendaciones
• Capturas del visor petrográfico (si están adjuntas)
• Tablas de datos y advertencias de validación

Exportación de Paquete de Proyecto

Exporta tu proyecto completo como archivo ZIP conteniendo:

• Archivo de proyecto .gisgeo: Datos completos del proyecto en formato JSON
• Resumen CSV/Excel: Datos tabulares para todas las muestras
• Reportes JSON individuales: Uno por muestra
• Imágenes adjuntas: Fotomicrografías PPL/XPL y capturas

Abriendo Proyectos Guardados

Haz clic en "Abrir Proyecto" y selecciona un archivo .gisgeo para restaurar tu trabajo. Todos los datos de muestras, imágenes, anotaciones y configuraciones se preservan.

Interpretación Asistida por IA (Opcional)

Configurando Backends de IA

PetroPyQAPF puede integrarse con servicios de IA para interpretación en lenguaje natural:

• Ollama Local: Ejecuta modelos en tu propia máquina
• API de OpenAI: GPT-4 u otros modelos de OpenAI
• API de Anthropic: Modelos Claude

Para configurar:

1. Abre Configuración → Configuración de IA
2. Selecciona tu backend preferido
3. Ingresa credenciales API (si usas servicios en la nube)
4. Prueba la conexión

Usando GPKE (Motor de Conocimiento Geológico-Petrológico)

GPKE sintetiza evidencia modal, geoquímica y probabilística en hipótesis de lenguaje natural:

• Escenarios petrogenéticos (evolución magmática, mezcla, contaminación)
• Inferencias de ambiente tectónico
• Interpretaciones de alteración o meteorización
• Evaluación de calidad y sugerencias de revisión de datos

Limitaciones Importantes

• Las interpretaciones de IA no son conclusiones científicas revisadas por pares
• GPKE no reclasifica rocas—proporciona contexto e hipótesis
• Siempre valida sugerencias de IA contra observaciones petrográficas y contexto geológico

Solución de Problemas

Problemas de Autenticación

Problema: No puedo iniciar sesión con cuenta de Google

• Verifica que tu correo está registrado para acceso académico en /es/portfolio/petropyqapf/register
• Verifica conexión a internet
• Asegúrate que el firewall permita a PetroPyQAPF acceder a servidores Firebase
• Contacta jordanzav@gisgeo.dev si el acceso es denegado después de registro

Errores de Importación de Datos

Problema: Importación CSV/Excel falla o produce resultados incorrectos

• Verifica que encabezados de columnas coincidan con nombres de campo esperados (Q, A, P, F, Domain)
• Revisa valores faltantes o no numéricos en columnas de porcentaje mineral
• Asegúrate que codificación de archivo sea UTF-8 (especialmente para caracteres españoles)
• Usa la plantilla CSV proporcionada como referencia

Advertencias de Cálculo CIPW

Problema: Norma CIPW falla o muestra "Composición inválida"

• Verifica total de óxidos: debe ser 98-102%
• Verifica que todos los óxidos requeridos estén ingresados (SiO₂, Al₂O₃, FeO, MgO, CaO, Na₂O, K₂O)
• Asegúrate que no haya valores negativos o valores atípicos extremos
• Revisa relación Fe₂O₃/FeO—ambos no deben ser cero

Exportación PDF Falla

Problema: No puedo generar reportes PDF

• Asegúrate que Microsoft Word esté instalado y activado
• Cierra cualquier documento de Word abierto antes de exportar
• Verifica permisos de escritura para el directorio de salida
• Intenta exportar a una carpeta diferente (evita directorios del sistema)

Problemas del Visor Petrográfico

Problema: Las imágenes no cargan o se muestran incorrectamente

• Formatos soportados: JPG, PNG, TIFF, BMP
• Tamaño máximo de archivo: 50 MB por imagen
• Intenta reducir resolución de imagen si el archivo es muy grande
• Verifica que la ruta del archivo no tenga caracteres especiales

Preguntas Frecuentes

Soporte y Contacto

Soporte Técnico

Para errores, solicitudes de funciones o preguntas técnicas:
Email: jordanzav@gisgeo.dev

Registro Académico

Para registrarte para acceso académico:
Solicitar Acceso Académico

Licenciamiento Comercial

Para uso empresarial, de consultoría o institucional:
Email: jordanzav@gisgeo.dev

Actualizaciones de Documentación

Este manual se actualiza con cada versión del software. Consulta la página principal de PetroPyQAPF para la versión más reciente.