Package {peruocc}

Title:	Query and Standardize Biodiversity Occurrences in Peru
Version:	0.1.0
Description:	Facilitates the retrieval, spatial validation, and integration of flora and fauna occurrence records across administrative units (districts and provinces) in Peru. Retrieves official boundary geometries via 'geoperu', queries and consolidates observations from the Global Biodiversity Information Facility (GBIF, https://www.gbif.org/) and 'iNaturalist' (https://www.inaturalist.org/), and standardizes attributes into a unified Darwin Core aligned structure. Designed for biodiversity assessments and spatial workflows within user-defined areas of interest.
License:	MIT + file LICENSE
Encoding:	UTF-8
Depends:	R (≥ 4.1.0)
Imports:	cli, dplyr, geoperu, ggplot2, jsonlite, readr, rgbif, rinat, sf
Suggests:	knitr, rmarkdown, testthat (≥ 3.0.0)
VignetteBuilder:	knitr
Config/testthat/edition:	3
URL:	https://paulesantos.github.io/peruocc/
BugReports:	https://github.com/PaulESantos/peruocc/issues
Config/roxygen2/version:	8.1.0
NeedsCompilation:	no
Packaged:	2026-09-11 03:06:36 UTC; PC
Author:	Paul E. Santos Andrade [aut, cre, cph]
Maintainer:	Paul E. Santos Andrade <paulefrens@gmail.com>
Repository:	CRAN
Date/Publication:	2026-09-21 17:50:02 UTC

Coerción a objeto tabular ligero (estilo tibble)

Description

Convierte un data.frame u objeto compatible en una estructura tabular con clase c("peruocc_tbl", "tbl_df", "tbl", "data.frame"), compatible con el ecosistema tidyverse sin generar conflictos ni dependencias pesadas.

Usage

as_peruocc_tbl(x, ...)

## S3 method for class 'data.frame'
as_peruocc_tbl(x, ...)

## Default S3 method:
as_peruocc_tbl(x, ...)

## S3 method for class 'peruocc_tbl'
x[i, j, drop = FALSE]

## S3 method for class 'peruocc_tbl'
print(x, n = 10L, width = NULL, ...)

Arguments

Value

Un objeto tabular con clase c("peruocc_tbl", "tbl_df", "tbl", "data.frame").

Examples

df <- data.frame(a = 1:5, b = letters[1:5])
tbl <- as_peruocc_tbl(df)
class(tbl)

Busca ocurrencias en un distrito peruano

Description

Atajo legible de buscar_especies_peru() con nivel = "distrito". Acepte los mismos filtros y devuelve la misma estructura de resultado.

Usage

buscar_especies_distrito(
  distrito,
  departamento = NULL,
  provincia = NULL,
  nombre_cientifico = NULL,
  grupo = NULL,
  limite_por_api = configuracion_predeterminada()$limite_por_api,
  guardar_resultados = FALSE,
  tolerancia_simplificacion = configuracion_predeterminada()$tolerancia_simplificacion_m,
  ...
)

Arguments

Value

Lista con límite, ocurrencias, resumen y parámetros. Consulte el valor retornado por buscar_especies_peru().

Examples

## Not run: 
res <- buscar_especies_distrito("Miraflores", departamento = "Lima", grupo = "flora")
head(res$ocurrencias)

## End(Not run)

Busca y consolida ocurrencias en una unidad administrativa del Perú

Description

Es la función general de consulta. Obtiene el límite oficial, consulta GBIF e iNaturalist, valida localmente que cada coordenada esté dentro del polígono y unifica las columnas en un esquema común. Para áreas extensas puede dividir la consulta en lotes con checkpoint, evitando que un fallo obligue a empezar de nuevo.

Usage

buscar_especies_peru(
  nombre,
  nivel = c("distrito", "provincia"),
  departamento = NULL,
  provincia = NULL,
  nombre_cientifico = NULL,
  grupo = NULL,
  limite_por_api = configuracion_predeterminada()$limite_por_api,
  guardar_resultados = FALSE,
  dir_salida = NULL,
  tolerancia_simplificacion = configuracion_predeterminada()$tolerancia_simplificacion_m,
  estrategia_espacial = c("auto", "directa", "segmentada"),
  max_area_ha = configuracion_predeterminada()$max_area_ha_por_lote,
  max_lotes = configuracion_predeterminada()$max_lotes_espaciales,
  cache_dir = ruta_cache("consultas_ocurrencias"),
  reintentos = configuracion_predeterminada()$reintentos_api,
  pausa_entre_lotes_s = configuracion_predeterminada()$pausa_entre_lotes_s
)

Arguments

Details

La deduplicación usa source y sourceRecordID; un mismo registro procedente de GBIF e iNaturalist se mantiene, porque son fuentes distintas. Los checkpoints se escriben tras terminar cada fuente/lote. Revise resultado$resumen$fallos_lotes antes de interpretar una descarga como completa.

Value

Objeto con clase peruocc_resultado (lista con límite unidad_sf, tibble de ocurrencias, resumen estadístico y parametros).

Examples

## Not run: 
resultado <- buscar_especies_peru(
  nombre = "Tambopata", nivel = "provincia", departamento = "Madre de Dios",
  grupo = "fauna", limite_por_api = 1000, max_area_ha = 1000
)
head(resultado$ocurrencias)

## End(Not run)

Busca ocurrencias en un polígono personalizado

Description

Consulta GBIF e iNaturalist sobre un límite aportado por el usuario. El área se normaliza mediante preparar_poligono_usuario(), se consulta por WKT o caja delimitadora y, finalmente, los puntos se recortan contra la geometría exacta localmente. Soporta áreas de estudio, buffers, ANP y polígonos de múltiples partes.

Usage

buscar_especies_poligono(
  poligono,
  nombre = NULL,
  nombre_cientifico = NULL,
  grupo = NULL,
  limite_por_api = configuracion_predeterminada()$limite_por_api,
  guardar_resultados = FALSE,
  dir_salida = NULL,
  tolerancia_simplificacion = configuracion_predeterminada()$tolerancia_simplificacion_m,
  estrategia_espacial = c("auto", "directa", "segmentada"),
  max_area_ha = configuracion_predeterminada()$max_area_ha_por_lote,
  max_lotes = configuracion_predeterminada()$max_lotes_espaciales,
  cache_dir = ruta_cache("consultas_ocurrencias"),
  reintentos = configuracion_predeterminada()$reintentos_api,
  pausa_entre_lotes_s = configuracion_predeterminada()$pausa_entre_lotes_s
)

Arguments

Value

Lista con unidad_sf, ocurrencias, resumen y parametros. resumen$fallos_lotes indica si alguna fuente/lote no pudo completarse.

Examples

coords <- matrix(c(-77.05, -12.10, -77.01, -12.10, -77.01, -12.05,
                   -77.05, -12.05, -77.05, -12.10), ncol = 2, byrow = TRUE)
zona <- sf::st_as_sf(sf::st_sfc(sf::st_polygon(list(coords)), crs = 4326))
## Not run: 
resultado <- buscar_especies_poligono(zona, nombre = "Zona de prueba",
                                       grupo = "flora", limite_por_api = 500)

## End(Not run)

Busca ocurrencias en una provincia peruana

Description

Atajo de buscar_especies_peru() con nivel = "provincia". Con la estrategia predeterminada procesa los distritos de forma independiente y consolida al final, una opción más recuperable que consultar la provincia disuelta en una sola petición.

Usage

buscar_especies_provincia(
  provincia,
  departamento = NULL,
  nombre_cientifico = NULL,
  grupo = NULL,
  limite_por_api = configuracion_predeterminada()$limite_por_api,
  guardar_resultados = FALSE,
  tolerancia_simplificacion = configuracion_predeterminada()$tolerancia_simplificacion_m,
  ...
)

Arguments

Value

Lista con límite provincial disuelto, ocurrencias consolidadas, resumen de lotes y parámetros de la ejecución.

Examples

## Not run: 
res <- buscar_especies_provincia("Urubamba", departamento = "Cusco", grupo = "fauna")
head(res$ocurrencias)

## End(Not run)

Exporta un resultado de búsqueda a formatos interoperables

Description

Escribe las ocurrencias consolidadas como tabla CSV, capa GeoJSON y/o un manifiesto JSON de reproducibilidad. El manifiesto registra parámetros, geometría, versiones de paquetes y las rutas creadas. No se genera ningún archivo si resultado$ocurrencias no contiene filas.

Usage

exportar_resultados(
  resultado,
  dir_salida = NULL,
  prefijo = NULL,
  formatos = c("csv", "geojson", "manifiesto")
)

Arguments

Value

Invisiblemente, una lista nombrada con las rutas creadas. Los nombres posibles son csv, geojson y manifiesto.

Examples

## Not run: 
resultado <- buscar_especies_distrito("Miraflores", departamento = "Lima")
exportar_resultados(resultado, dir_salida = tempdir(), formatos = c("csv", "manifiesto"))

## End(Not run)

Grafica ocurrencias sobre su área de consulta

Description

Construye un mapa ggplot2 con el polígono consultado y los registros que quedaron después del filtro espacial exacto. Es apropiada para inspección exploratoria y control de calidad de coordenadas, no para cartografía final.

Usage

graficar_ocurrencias(
  resultado_lista,
  color_por = "source",
  guardar_mapa = FALSE,
  ruta_salida = NULL
)

Arguments

Value

Un objeto de clase ggplot. Puede añadirse capas o temas de ggplot2 antes de imprimirlo.

Examples

## Not run: 
resultado <- buscar_especies_distrito("Miraflores", departamento = "Lima")
graficar_ocurrencias(resultado, color_por = "source")

## End(Not run)

Obtiene el límite oficial de un distrito peruano

Description

Descarga o recupera del caché la capa distrital de geoperu, localiza la unidad solicitada sin distinguir mayúsculas ni tildes y devuelve una geometría válida en WGS84. Es la forma recomendada de inspeccionar un límite antes de una búsqueda o de resolver ambigüedades administrativas.

Usage

obtener_poligono_distrito(distrito, departamento = NULL, provincia = NULL)

Arguments

Value

Un objeto sf de una fila, EPSG:4326, con columnas departamento, provincia, distrito, capital (cuando esté disponible) y geometría.

Examples

## Not run: 
miraflores <- obtener_poligono_distrito(
  distrito = "Miraflores", departamento = "Lima", provincia = "Lima"
)

## End(Not run)

Obtiene el límite oficial de una provincia peruana

Description

Recupera los distritos de la provincia desde geoperu y disuelve sus geometrías en una sola entidad válida. Para descargar ocurrencias provinciales use buscar_especies_provincia(), que internamente conserva los distritos separados para hacer consultas más resilientes.

Usage

obtener_poligono_provincia(provincia, departamento = NULL)

Arguments

Value

Un objeto sf de una fila en EPSG:4326, con departamento, provincia, distrito (NA) y la geometría disuelta.

Examples

## Not run: 
urubamba <- obtener_poligono_provincia("Urubamba", departamento = "Cusco")

## End(Not run)

Obtiene un límite administrativo mediante una interfaz única

Description

Despacha a obtener_poligono_distrito() o obtener_poligono_provincia() según nivel. Facilita crear funciones genéricas cuando el nivel de consulta se elige en tiempo de ejecución.

Usage

obtener_poligono_unidad(
  nombre,
  nivel = c("distrito", "provincia"),
  departamento = NULL,
  provincia = NULL
)

Arguments

Value

Un objeto sf en EPSG:4326. Para provincias la geometría está disuelta; para distritos contiene una fila de la capa oficial.

Examples

## Not run: 
limite <- obtener_poligono_unidad("Tarapoto", nivel = "distrito",
                                  departamento = "San Martin")

## End(Not run)

Configura el directorio de trabajo de peruocc

Description

Define el directorio raíz donde el paquete guarda resultados exportados y, cuando se configura explícitamente, los límites y checkpoints de consultas. La configuración se conserva durante la sesión de R mediante la opción peruocc.data_dir; no modifica archivos de configuración permanentes ni crea directorios por defecto en el espacio de trabajo del usuario.

Usage

peruocc_data_dir(path = NULL)

peruspecies_data_dir(path = NULL)

Arguments

Details

Cuando está configurado, los resultados se escriben en ⁠processed/⁠ y los checkpoints en ⁠cache/⁠ dentro de este directorio.

Value

Invisiblemente, la ruta absoluta normalizada activa, o NULL si no se ha definido un directorio.

Examples

dir_temporal <- file.path(tempdir(), "peruocc-ejemplo")
peruocc_data_dir(dir_temporal)
# consultar la ruta activa:
peruocc_data_dir()

Valida y normaliza un polígono aportado por el usuario

Description

Acepta una geometría u archivo espacial, lo transforma a WGS84, corrige topología cuando es posible y unifica múltiples elementos en un único límite. Es la preparación previa que usa buscar_especies_poligono().

Usage

preparar_poligono_usuario(poligono, nombre = NULL)

Arguments

Value

Un objeto sf válido de una fila en EPSG:4326, con las columnas unidad, distrito, provincia y departamento. Las tres últimas se rellenan con NA porque el límite no procede de una unidad administrativa.

Examples

coords <- matrix(c(-77.05, -12.10, -77.01, -12.10, -77.01, -12.05,
                   -77.05, -12.05, -77.05, -12.10), ncol = 2, byrow = TRUE)
zona <- sf::st_as_sf(sf::st_sfc(sf::st_polygon(list(coords)), crs = 4326))
preparar_poligono_usuario(zona, nombre = "Zona de prueba")

Verifica las dependencias de peruocc

Description

Comprueba la disponibilidad de los paquetes requeridos para límites administrativos, operaciones espaciales, consultas a GBIF/iNaturalist, visualización y exportación. Úsela al preparar una instalación nueva o para diagnosticar un error de carga.

Usage

verificar_y_configurar_entorno()

Value

Invisiblemente TRUE si todas las dependencias están disponibles.

Examples

verificar_y_configurar_entorno()