---
title: "Getting started"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Getting started}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(collapse = TRUE, comment = "#>", eval = FALSE)
```

```{r setup}
library(Argentum)
```

## What this package talks to

Two OGC standards, and the difference between them decides which function you
reach for.

**WFS** returns *features*: geometries with attributes, which you can filter,
join, measure and reproject. You get an `sf` object. Use it when you need the
data.

**WMS** returns a *picture*: the server draws the map with its own cartography
and sends you pixels. You get a `terra::SpatRaster`. Use it when you need a
backdrop, an orthophoto, or a layer the publisher only exposes as imagery.

Most organizations publish both. `argentum_organizations()` tells you which.

## Finding an endpoint

```{r}
orgs <- argentum_organizations()
nrow(orgs)
head(orgs$name)
```

The catalogue is cached, so this is fast after the first call. To search it:

```{r}
argentum_search_organizations("catastro")
argentum_search_organizations("buenos aires", service = "wms")
```

Every reading function accepts either a catalogue `name` or a bare URL, so you
never *have* to go through the catalogue:

```{r}
ign <- "https://wms.ign.gob.ar/geoserver/ows"
```

## Seeing what is published

```{r}
layers <- argentum_layers(ign)
layers[, c("name", "title", "crs")]
```

The `bbox` column reports each layer's extent in WGS84. It is worth reading
before you download: it tells you whether the layer covers the whole country
or one province, which changes how you should filter.

## Reading vector data

The simple case:

```{r}
provinces <- argentum_read_wfs(ign, "ign:provincia")
```

The case you will actually use. Three filters, all evaluated on the server, so
only the matching features cross the network:

```{r}
argentum_read_wfs(
  ign, "ign:provincia",
  bbox   = c(-59, -35, -57, -34),
  crs    = 4326,
  filter = "nam = 'Buenos Aires'"
)
```

`bbox` also accepts anything `sf::st_bbox()` understands, which is usually
more convenient than typing coordinates:

```{r}
aoi <- sf::read_sf("my_study_area.gpkg")
argentum_read_wfs(ign, "ign:localidad", bbox = aoi)
```

### Layers too big for one response

Servers cap how many features they will return at once, and many Argentine
deployments cap low. `argentum_read_wfs()` pages automatically: it requests
`getOption("argentum.page_size")` features at a time and stops when the server
returns a short page.

If a particular server mishandles `startIndex` — some older MapServer builds
do — turn paging off and cap the request instead:

```{r}
argentum_read_wfs(ign, "ign:localidad", page_size = Inf, max_features = 1000)
```

## Writing to disk

```{r}
report <- argentum_download(ign, dir = "data/ign", format = "gpkg")
```

`argentum_download()` returns a report rather than stopping at the first
failure, because in a bulk download over public infrastructure some layers
*will* fail:

```{r}
subset(report, status == "error")[, c("layer", "message")]
```

Prefer `"gpkg"`. Shapefile truncates field names at ten characters, which
mangles the descriptive Spanish column names these services tend to use.

## When things go wrong

Errors are classed conditions, so you can handle them selectively rather than
catching everything:

```{r}
result <- tryCatch(
  argentum_read_wfs(ign, "ign:provincia"),
  argentum_error_offline = function(e) {
    message("No network; using last night's extract instead.")
    sf::read_sf("cache/provincias.gpkg")
  }
)
```

The available classes are `argentum_error_offline`, `argentum_error_http`,
`argentum_error_ogc` (the server returned a `ServiceExceptionReport`),
`argentum_error_capabilities`, `argentum_error_read`,
`argentum_error_unknown_org`, `argentum_error_no_endpoint` and
`argentum_error_no_layers`.

## Caching

The catalogue and every `GetCapabilities` document are cached in memory for
the session and on disk between sessions:

```{r}
argentum_cache_path()
argentum_cache_clear()
options(argentum.cache_ttl = 60 * 60 * 24 * 7)  # a week
```

This matters more than it sounds. `GetCapabilities` on a large GeoServer can
take fifteen seconds, and every layer listing and every read needs one.

## Using your own catalogue

The bundled catalogue is a snapshot. If you maintain your own list of
endpoints — an internal SDI, or a corrected version of ours — point the
package at it:

```{r}
options(argentum.catalog = "endpoints.csv")
```

The file needs the columns `level`, `jurisdiction`, `dependency`,
`organization`, `updated`, `wms_url`, `wfs_url`, `wcs_url` and `csw_url`. A
`name` column is optional; without it, names are built from the organization
and whatever else identifies it. Files written for argentum 2.0.0, with
`category`, `organization`, `wms_url` and `wfs_url`, are still accepted and
keep their original names.

The bundled snapshot comes from the ["Geoservicios_IDERA"
spreadsheet](https://www.idera.gob.ar/index.php/servicios/geoservicios), the
same source the ArgentinaGeoServices QGIS plugin reads, so both tools see the
same endpoints.