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

The hardware and bandwidth for this mirror is donated by dogado GmbH, the Webhosting and Full Service-Cloud Provider. Check out our Wordpress Tutorial.
If you wish to report a bug, or if you are interested in having us mirror your free-software or open-source project, please feel free to contact us at mirror[@]dogado.de.

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
)

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

El archivo manifiesto_*.json almacena metadatos críticos para publicaciones científicas y auditorías reproducibles:

{
  "timestamp_utc": "2026-08-29T15:00:00Z",
  "paquetes": {
    "peruocc": "0.1.0",
    "sf": "1.0-19",
    "rgbif": "3.8.5",
    "rinat": "0.1.10"
  },
  "parametros": {
    "unidad": "Miraflores",
    "nivel": "distrito",
    "departamento": "Lima",
    "grupo": "flora",
    "limite_por_api": 150
  },
  "archivos_generados": [
    "ocurrencias_distrito_miraflores_flora.csv",
    "ocurrencias_distrito_miraflores_flora.geojson"
  ]
}

6. Integración con SIG y Flujos Espaciales

Las capas GeoJSON generadas pueden volver a cargarse en R para análisis espaciales posteriores (como modelos de distribución de especies o buffers):

library(sf)

# Cargar la capa de ocurrencias exportada
capa_ocurrencias <- sf::st_read("peruocc-output/processed/ocurrencias_distrito_miraflores_flora.geojson")

# Inspección rápida
print(capa_ocurrencias)

These binaries (installable software) and packages are in development.
They may not be fully stable and should be used with caution. We make no claims about them.
Health stats visible at Monitor.

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`