---
title: "Primeros Pasos con peruocc"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Primeros Pasos con peruocc}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.width = 8,
  fig.height = 5.5,
  fig.align = "center",
  out.width = "100%",
  dpi = 300,
  fig.retina = 2
)
```

## Introducción

`peruocc` es un paquete en R diseñado para facilitar la búsqueda, descarga, validación espacial y consolidación de registros de ocurrencias de biodiversidad (**flora y fauna**) en el territorio peruano, tomando como marco de referencia las delimitaciones político-administrativas oficiales provistas por **`geoperu`** (distritos y provincias).

El paquete integra y estandariza la información proveniente de dos de las plataformas más representativas en biodiversidad:
* **GBIF** (*Global Biodiversity Information Facility*)
* **iNaturalist**

---

## Carga del Paquete

Carga el paquete en tu sesión de R:

```{r}
library(peruocc)
```

### Configuración del Directorio de Trabajo (Opcional)

Si deseas almacenar automáticamente capas en caché o resultados exportados en un directorio específico de tu proyecto, puedes configurarlo con `peruocc_data_dir()`:

```{r, eval = FALSE}
# Configurar carpeta de salida personalizada (opcional)
peruocc_data_dir("mi-carpeta-proyecto")
```

Por defecto, todas las consultas y geometrías se procesan directamente en memoria RAM sin escribir archivos en el disco.

---

## Consultas de Ocurrencias

Por defecto, las consultas se ejecutan directamente en memoria (`guardar_resultados = FALSE`), lo que agiliza el flujo interactivo y previene la creación de archivos no deseados en el disco.

### 1. Búsqueda a Nivel de Distrito

Para consultar registros en un distrito específico (por ejemplo, el distrito de **Cusco**, en la provincia y departamento de **Cusco**):

```{r}
resultado_cusco <- buscar_especies_distrito(
  distrito = "Cusco",
  departamento = "Cusco",
  provincia = "Cusco",
  grupo = "flora",            # "flora", "fauna" o NULL
  limite_por_api = 150
)
```

### 2. Búsqueda a Nivel de Provincia

Para consultar una provincia completa (donde `peruocc` disuelve automáticamente las geometrías distritales):

```{r}
resultado_urubamba <- buscar_especies_provincia(
  provincia = "Urubamba",
  departamento = "Cusco",
  grupo = "fauna",
  limite_por_api = 200
)
```

### 3. Filtro por Especie o Taxón Específico

También es posible restringir la búsqueda a un taxón en particular utilizando el argumento `nombre_cientifico`:

```{r}
resultado_jaguar <- buscar_especies_distrito(
  distrito = "Tambopata",
  departamento = "Madre de Dios",
  provincia = "Tambopata",
  nombre_cientifico = "Panthera onca",
  limite_por_api = 50
)
```

---

## Estructura del Objeto Consolidado

Las funciones de búsqueda retornan un objeto de tipo `list` estructurado con 4 componentes clave:

```{r}
names(resultado_cusco)
#> [1] "unidad_sf"   "ocurrencias" "resumen"     "parametros"
```

| Componente | Tipo | Descripción |
| :--- | :--- | :--- |
| **`unidad_sf`** | `sf` (WGS84) | Polígono oficial validado y proyectado en EPSG:4326. |
| **`ocurrencias`** | `peruocc_tbl` / `data.frame` | Registros estandarizados bajo el estándar Darwin Core. |
| **`resumen`** | `list` | Estadísticas de la consulta (conteo total, por fuente, reinos). |
| **`parametros`** | `list` | Metadatos y filtros utilizados en la llamada (fechas, límites). |

### Inspección de Registros

```{r}
# Vista previa de las primeras ocurrencias
head(resultado_cusco$ocurrencias[, c("scientificName", "source", "eventDate", "decimalLatitude", "decimalLongitude")])
```

---

## Visualización y Exportación

### Visualización Rápida

Puedes generar inmediatamente un mapa temático con `ggplot2`:

```{r}
# Visualizar mapa coloreando por repositorio de origen (GBIF vs iNaturalist)
mapa <- graficar_ocurrencias(resultado_cusco, color_por = "source")
print(mapa)
```

### Exportación a Disco

Para guardar los datos en formatos estándar (`CSV`, `GeoJSON` y `manifiesto JSON` de reproducibilidad), especifica el directorio de destino mediante `dir_salida`:

```{r}
# Exportar resultados a un directorio (por ejemplo, temporal para la viñeta)
archivos <- exportar_resultados(resultado_cusco, dir_salida = tempdir())
```

---

## Siguientes Pasos

Para profundizar en las capacidades de `peruocc`, consulta las viñetas especializadas:

* **[Flujo Espacial y Filtrado Topológico Riguroso](flujo_espacial.html)**: Detalles de simplificación métrica UTM, corrección CCW y estrategias de partición.
* **[Búsqueda con Polígonos Personalizados](busqueda_poligono_usuario.html)**: Consultas con shapefiles, buffers, áreas naturales protegidas y capas vectoriales propias.
* **[Configuración, Exportación y Visualización](visualizacion_y_exportacion.html)**: Integración con SIG (QGIS/ArcGIS), personalización de mapas con ggplot2 y manifiestos de auditoría científica.