Configuración, Exportación y Visualización de Resultados

Introducción

El paquete peruocc está diseñado tanto para la exploración interactiva y rápida de ocurrencias de biodiversidad en memoria, como para flujos de trabajo reproducibles en producción y análisis espacial (SIG).

Esta guía explica: 1. Cómo configurar el directorio de almacenamiento y caché (peruocc_data_dir()). 2. La diferencia entre consultas interactivas en memoria (guardar_resultados = FALSE) y persistencia en disco (guardar_resultados = TRUE). 3. La función dedicada exportar_resultados() y los formatos generados (CSV, GeoJSON y Manifiesto de reproducibilidad). 4. La visualización cartográfica con graficar_ocurrencias().

1. Configuración del Directorio de Trabajo: `peruocc_data_dir()`

La función peruocc_data_dir() permite centralizar opcionalmente la ubicación en el disco donde se almacenarán capas espaciales descargadas en caché y los resultados exportados.

library(peruocc)

# Configurar el directorio raíz del proyecto para artefactos (opcional)
peruocc_data_dir("mi-carpeta-proyecto")

¿Por qué es útil y cómo funciona?

Control y Orden del Proyecto: Mantiene todas las salidas y capas auxiliares organizadas en una única carpeta personalizada en lugar de dispersarlas en la raíz de trabajo.
Caché Opcional de Geometrías: Al configurar una ruta, el paquete guarda copias .rds en cache/. Las siguientes consultas a esa misma zona cargarán la geometría instantáneamente sin volver a descargarla de internet.
Configuración Global Transparente: Al ejecutar peruocc_data_dir(), la ruta se guarda en las opciones de R (options(peruocc.data_dir = ...)).

¿Qué ocurre si NO ejecuto `peruocc_data_dir()`?

No habrá ningún error y las consultas funcionarán con normalidad. * Caché: peruocc almacena las capas en la memoria RAM de la sesión (.peruocc_mem_cache), garantizando cero escrituras en disco no solicitadas. * Exportaciones: Si decides exportar archivos más adelante con exportar_resultados(), simplemente indica la carpeta deseada mediante el argumento dir_salida (por ejemplo, dir_salida = tempdir()).

2. Ejecución en Memoria vs. Guardado en Disco (`guardar_resultados`)

Todas las funciones principales de búsqueda (buscar_especies_distrito(), buscar_especies_provincia(), buscar_especies_peru()) incluyen el argumento guardar_resultados.

# Firma de la función
buscar_especies_distrito(
  distrito,
  departamento = NULL,
  provincia = NULL,
  ...,
  guardar_resultados = FALSE  # <- FALSE por defecto
)

Comparativa: Consultas Experimentales vs. Guardado Automático

Característica	`guardar_resultados = FALSE` (Por defecto / Experimental)	`guardar_resultados = TRUE` (Guardado Automático)
Destino de datos	Solo memoria RAM en la sesión de R.	Memoria RAM + archivos guardados en disco.
Velocidad de ejecución	Más rápida. Evita la sobrecarga de I/O y serialización espacial.	Requiere tiempo adicional para escribir CSV, GeoJSON y JSON.
Archivos generados	Ninguno.	`.csv`, `.geojson` y `manifiesto_*.json` en la subcarpeta `processed/`.
Casos de uso	Análisis exploratorio, filtrado rápido, visualización interactiva y pruebas de parámetros.	Pipelines automatizados, ejecuciones desatendidas o procesamiento en lotes (batch).

Flujo de Trabajo Recomendado

Para la mayoría de los análisis, la mejor práctica es trabajar primero en memoria y luego exportar selectivamente cuando los datos estén listos:

# Paso 1: Consulta rápida en memoria (experimental / interactiva)
resultado <- buscar_especies_distrito(
  distrito = "Miraflores",
  departamento = "Lima",
  provincia = "Lima",
  grupo = "flora",
  limite_por_api = 150
)
#> 
#> ── Búsqueda Integrada: MIRAFLORES (DISTRITO) ───────────────────────────────────
#> • Departamento: Lima
#> • Provincia: Lima
#> • Grupo: flora
#> ℹ Descargando límites de LIMA vía geoperu...
#> ℹ [GBIF] Iniciando búsqueda de ocurrencias...
#> ✔ Polígono simplificado con éxito a tolerancia de 100 metros (WKT: 822 caracteres).
#> ℹ [GBIF] Filtrando por reino Plantae (Flora).
#> ℹ [GBIF] Consultando registros dentro del polígono de MIRAFLORES (límite: "150")...
#> ✔ [GBIF] Búsqueda finalizada. Se filtraron 148 registro(s) que caen dentro del polígono seleccionado.
#> ℹ [iNaturalist] Iniciando búsqueda de ocurrencias...
#> ℹ [iNaturalist] Filtrando por reino Plantae (Flora).
#> ℹ [iNaturalist] Consultando registros dentro de la caja delimitadora de MIRAFLORES (límite: "150")...
#> ℹ [iNaturalist] Se descargaron 150 registros en la caja delimitadora. Aplicando filtro espacial...
#> ✔ [iNaturalist] Búsqueda finalizada. 133 de 150 registros caen dentro del polígono seleccionado.
#> ✔ Consolidación exitosa. Total de registros unificados: 281
#> 
#> ── Resumen de Registros ──
#> 
#> • GBIF: 148 registro(s)
#> • iNaturalist: 133 registro(s)
#> ✔ Total consolidado: 281 registro(s)

# Paso 2: Inspeccionar resultados o graficar
summary(resultado$ocurrencias)
#>     occurrenceID   sourceRecordID     sourceURL       datasetKey 
#>  Length   :281   Length   :281    Length   :281   Length   :281  
#>  N.unique :281   N.unique :281    N.unique :281   N.unique :  2  
#>  N.blank  :  0   N.blank  :  0    N.blank  :  0   N.blank  :  0  
#>  Min.nchar: 10   Min.nchar:  9    Min.nchar: 42   Min.nchar: 36  
#>  Max.nchar: 50   Max.nchar: 10    Max.nchar: 50   Max.nchar: 36  
#>                                                   NAs      :133  
#>                                                                  
#>       license      basisOfRecord   scientificName decimalLatitude 
#>  Length   :281   Length   :281   Length   :281    Min.   :-12.14  
#>  N.unique :  8   N.unique :  2   N.unique :119    1st Qu.:-12.13  
#>  N.blank  : 19   N.blank  :  0   N.blank  :  0    Median :-12.12  
#>  Min.nchar:  0   Min.nchar: 16   Min.nchar: 11    Mean   :-12.12  
#>  Max.nchar: 58   Max.nchar: 17   Max.nchar: 58    3rd Qu.:-12.12  
#>                                                   Max.   :-12.11  
#>                                                                   
#>  decimalLongitude     eventDate       taxonRank        kingdom   
#>  Min.   :-77.05   Length   :281   Length   :281   Length   :281  
#>  1st Qu.:-77.04   N.unique :233   N.unique :  1   N.unique :  1  
#>  Median :-77.03   N.blank  :  0   N.blank  :  0   N.blank  :  0  
#>  Mean   :-77.03   Min.nchar: 10   Min.nchar:  7   Min.nchar:  7  
#>  3rd Qu.:-77.03   Max.nchar: 20   Max.nchar:  7   Max.nchar:  7  
#>  Max.   :-77.01                   NAs      :133                  
#>                                                                  
#>        phylum          class           order           family   
#>  Length   :281   Length   :281   Length   :281   Length   :281  
#>  N.unique :  2   N.unique :  4   N.unique : 21   N.unique : 35  
#>  N.blank  :  0   N.blank  :  0   N.blank  :  0   N.blank  :  0  
#>  Min.nchar: 10   Min.nchar:  9   Min.nchar:  6   Min.nchar:  7  
#>  Max.nchar: 12   Max.nchar: 15   Max.nchar: 14   Max.nchar: 16  
#>  NAs      :133   NAs      :133   NAs      :133   NAs      :133  
#>                                                                 
#>        genus          species        recordedBy  coordinateUncertaintyInMeters
#>  Length   :281   Length   :281   Length   :281   Min.   :   2.0               
#>  N.unique : 53   N.unique : 63   N.unique :119   1st Qu.:  12.0               
#>  N.blank  :  0   N.blank  :  0   N.blank  :  0   Median :  21.0               
#>  Min.nchar:  5   Min.nchar: 11   Min.nchar:  5   Mean   : 334.2               
#>  Max.nchar: 16   Max.nchar: 28   Max.nchar: 30   3rd Qu.:  30.0               
#>  NAs      :133   NAs      :133   NAs      : 10   Max.   :3945.0               
#>                                                  NAs    :54                   
#>        source         district        province       department 
#>  Length   :281   Length   :281   Length   :281   Length   :281  
#>  N.unique :  2   N.unique :  1   N.unique :  1   N.unique :  1  
#>  N.blank  :  0   N.blank  :  0   N.blank  :  0   N.blank  :  0  
#>  Min.nchar:  4   Min.nchar: 10   Min.nchar:  4   Min.nchar:  4  
#>  Max.nchar: 11   Max.nchar: 10   Max.nchar:  4   Max.nchar:  4  
#>                                                                 
#> 

# Paso 3: Si los datos son conformes, exportar a disco
# exportar_resultados(resultado)

3. Exportación de Resultados y Estructura de Artefactos

La función exportar_resultados() toma el objeto devuelto por cualquier búsqueda y genera artefactos estructurados y listos para interoperabilidad:

# Exportación completa (por defecto a processed/ de peruocc_data_dir)
archivos <- exportar_resultados(resultado)

# Exportación personalizada a otra carpeta y formatos específicos:
exportar_resultados(
  resultado = resultado,
  dir_salida = "mis_analisis/capas",
  formatos = c("csv", "geojson")
)

Estructura del Directorio de Salida

Cuando se utiliza peruocc_data_dir("peruocc-output"), la estructura queda organizada de la siguiente manera:

peruocc-output/
├── cache/
│   ├── distritos_lima.rds                 # Geometrías oficiales cacheadas
│   └── distritos_peru_completo.rds
└── processed/
    ├── ocurrencias_distrito_miraflores_flora.csv
    ├── ocurrencias_distrito_miraflores_flora.geojson
    └── manifiesto_distrito_miraflores_flora.json

Descripción de los Formatos Exportados

ocurrencias_*.csv:
- Tabla plana estandarizada según el estándar internacional Darwin Core (scientificName, decimalLatitude, decimalLongitude, eventDate, source, etc.).
ocurrencias_*.geojson:
- Capa espacial vectorial de puntos con proyección geográfica WGS84 (EPSG:4326). Se puede arrastrar directamente a QGIS, ArcGIS o visores web (Leaflet, Mapbox).
manifiesto_*.json:
- Manifiesto de auditoría y reproducibilidad científica. Registra:
  - Fecha y hora exacta de la consulta (UTC).
  - Versiones de R y paquetes utilizados (sf, rgbif, rinat, geoperu).
  - Polígono de consulta en formato WKT (Well-Known Text).
  - Parámetros y filtros aplicados (fechas, límites por API, reinos).
results/mapa_*.png (opcional):
- Gráficos cartográficos en alta resolución (300 DPI) generados por graficar_ocurrencias(..., guardar_mapa = TRUE).

4. Visualización Cartográfica con `graficar_ocurrencias()`

La función graficar_ocurrencias() produce composiciones visuales basadas en ggplot2, integrando la delimitación poligonal oficial de fondo con las observaciones superpuestas.

Comparación por Proveedor de Datos (`source`)

# Visualizar diferenciando aportes de GBIF vs iNaturalist
mapa_fuente <- graficar_ocurrencias(
  resultado_lista = resultado,
  color_por = "source"
)

print(mapa_fuente)

Mapa de distribución de ocurrencias coloreado por repositorio de origen (GBIF vs iNaturalist)

Comparación por Reino Biológico (`kingdom`)

# Visualizar distribución por reinos (Plantae, Animalia, Fungi, etc.)
mapa_reino <- graficar_ocurrencias(
  resultado_lista = resultado,
  color_por = "kingdom"
)

print(mapa_reino)

Mapa de distribución de ocurrencias coloreado por reino taxonómico (Plantae vs Animalia)

Personalización con Capas de `ggplot2`

Dado que graficar_ocurrencias() retorna un objeto estándar de clase ggplot, puedes extenderlo y personalizarlo con cualquier tema, escala o etiqueta de ggplot2:

library(ggplot2)

mapa_personalizado <- mapa_fuente +
  ggplot2::theme_minimal(base_size = 12) +
  ggplot2::labs(
    title = "Biodiversidad en Miraflores, Lima",
    subtitle = "Ocurrencias consolidadas vía peruocc (GBIF + iNaturalist)",
    caption = "Fuente: Repositorios de Biodiversidad / INEI geoperu"
  )

print(mapa_personalizado)

Mapa temático personalizado con tema minimal y títulos adicionales de ggplot2

Exportar el Mapa Directamente a Imagen

# Genera y guarda automáticamente el mapa en results/ en formato PNG a 300 DPI
mapa_guardado <- graficar_ocurrencias(
  resultado_lista = resultado,
  color_por = "source",
  guardar_mapa = TRUE
)

Configuración, Exportación y Visualización de Resultados

Introducción

1. Configuración del Directorio de Trabajo: `peruocc_data_dir()`

¿Por qué es útil y cómo funciona?

¿Qué ocurre si NO ejecuto `peruocc_data_dir()`?

2. Ejecución en Memoria vs. Guardado en Disco (`guardar_resultados`)

Comparativa: Consultas Experimentales vs. Guardado Automático

Flujo de Trabajo Recomendado

3. Exportación de Resultados y Estructura de Artefactos

Estructura del Directorio de Salida

Descripción de los Formatos Exportados

4. Visualización Cartográfica con `graficar_ocurrencias()`

Comparación por Proveedor de Datos (`source`)

Comparación por Reino Biológico (`kingdom`)

Personalización con Capas de `ggplot2`

Exportar el Mapa Directamente a Imagen

5. Auditoría Científica: Estructura del Manifiesto JSON

6. Integración con SIG y Flujos Espaciales

Configuración, Exportación y Visualización de Resultados

Introducción

1. Configuración del Directorio de Trabajo: peruocc_data_dir()

¿Por qué es útil y cómo funciona?

¿Qué ocurre si NO ejecuto peruocc_data_dir()?

2. Ejecución en Memoria vs. Guardado en Disco (guardar_resultados)

Comparativa: Consultas Experimentales vs. Guardado Automático

Flujo de Trabajo Recomendado

3. Exportación de Resultados y Estructura de Artefactos

Estructura del Directorio de Salida

Descripción de los Formatos Exportados

4. Visualización Cartográfica con graficar_ocurrencias()

Comparación por Proveedor de Datos (source)

Comparación por Reino Biológico (kingdom)

Personalización con Capas de ggplot2

Exportar el Mapa Directamente a Imagen

5. Auditoría Científica: Estructura del Manifiesto JSON

6. Integración con SIG y Flujos Espaciales

1. Configuración del Directorio de Trabajo: `peruocc_data_dir()`

¿Qué ocurre si NO ejecuto `peruocc_data_dir()`?

2. Ejecución en Memoria vs. Guardado en Disco (`guardar_resultados`)

4. Visualización Cartográfica con `graficar_ocurrencias()`

Comparación por Proveedor de Datos (`source`)

Comparación por Reino Biológico (`kingdom`)

Personalización con Capas de `ggplot2`