Package {Argentum}

argentum: Argentine geospatial web services

Description

Discovers and reads the geospatial layers published by Argentine public organizations through the OGC standards WFS (vectors) and WMS (rendered maps). Every exported function starts with argentum_; type that at the console and press Tab to see the whole API.

Finding data

The usual entry point. Locate an organization, then see what it publishes.

argentum_organizations()

The catalogue of publishing organizations, as maintained by IDERA. One row per organization, with its WMS/WFS/WCS/CSW endpoints.

argentum_search_organizations()

Search that catalogue by case-insensitive regular expression.

argentum_layers()

The layers a service publishes, with title, abstract, CRS and bounding box.

argentum_capabilities()

The parsed GetCapabilities document, protocol version already negotiated. Rarely needed directly.

Reading vectors (WFS)

argentum_read_wfs()

Read a layer as an sf::sf data frame, with server-side bbox/CQL filtering, reprojection and automatic pagination.

argentum_download()

Write many layers straight to disk, with a per-layer status report; one failure does not abort the run.

Reading rasters (WMS)

argentum_read_wms()

Render a layer server-side and return it as a georeferenced terra::SpatRaster.

argentum_wms_legend()

The matching legend graphic.

Interactive use, cache and options

argentum_browse()

Pick an organization and layer from a menu.

argentum_help()

A guided console tour by topic, in Spanish or English, with copy-pasteable code.

argentum_cache_path(), argentum_cache_clear()

Where the on-disk cache lives, and how to empty it.

argentum_options

Timeouts, retries, page size, cache TTL and catalogue override, all set through options().

Deprecated

The 1.x API (argentum_list_organizations() and friends) still works with a once-per-session warning and is removed in 3.0.0; see vignette("migrating-to-2-0").

Author(s)

Maintainer: Thomas Artopoulos thomas.artopoulos@gmail.com

See Also

Useful links:

• https://github.com/thomasartopoulos/argentum

• https://thomasartopoulos.github.io/argentum/

• Report bugs at https://github.com/thomasartopoulos/argentum/issues

Deprecated functions from argentum 1.x

Description

These wrappers keep 1.x scripts running. Each forwards to its 2.0 replacement and issues a deprecation warning. They will be removed in 3.0.

Usage

argentum_list_organizations()

argentum_list_layers(organization)

argentum_get_capabilities(url, max_tries = 3, timeout = 30)

argentum_import_wfs_layer(wfs_url, layer_name)

argentum_download_layers(
  organization,
  output_dir = file.path(tempdir(), "wfs_layers"),
  layer_names = NULL,
  format = c("gpkg", "shp", "geojson"),
  overwrite = FALSE
)

argentum_interactive_import()

argentum_interactive_download(output_dir = NULL)

argentum_select_organization(search = NULL, interactive_select = interactive())

Arguments

Value

The value of the replacement function.

Browse services interactively

Description

A guided prompt that walks from organization to service to layer, then either returns the data or writes it to disk. Intended for exploration at the console; every step it performs is available as a normal function call.

Usage

argentum_browse(action = c("read", "download"), dir = NULL)

Arguments

Value

An sf object, a terra::SpatRaster, or a download report, depending on the path taken. NULL if the user cancels.

Examples

if (interactive()) {
  layer <- argentum_browse()
}

Clear the argentum cache

Description

Clear the argentum cache

Usage

argentum_cache_clear(what = c("all", "memory", "disk"))

Arguments

Value

Invisibly, the number of on-disk files removed.

Examples

argentum_cache_clear("memory")

Where argentum stores cached documents

Description

Downloads of the endpoint catalogue and of GetCapabilities documents are cached on disk so that repeated calls in a session, or across sessions, do not hammer public servers.

Usage

argentum_cache_path()

Value

A single file path. The directory is created on first use.

Examples

argentum_cache_path()

Retrieve and parse a GetCapabilities document

Description

Negotiates the protocol version by trying the newest first and falling back, which is what makes the package work against both GeoServer and ArcGIS Server deployments. The parsed document is cached; see argentum_cache_path().

Usage

argentum_capabilities(
  x,
  service = c("wfs", "wms"),
  version = NULL,
  refresh = FALSE
)

Arguments

Value

An object of class argentum_capabilities: an xml_document with service, version and url attributes.

Examples

## Not run: 
cap <- argentum_capabilities("https://wms.ign.gob.ar/geoserver/ows", "wfs")
cap

## End(Not run)

Download WFS layers to disk

Description

Writes one file per layer and returns a report. Failures are recorded and the run continues, so one broken layer does not abort a bulk download.

Usage

argentum_download(
  x,
  layers = NULL,
  dir = file.path(tempdir(), "argentum"),
  format = c("gpkg", "geojson", "shp"),
  overwrite = FALSE,
  bbox = NULL,
  crs = NULL,
  max_features = NULL,
  quiet = arg_opt("argentum.quiet")
)

Arguments

Value

Invisibly, a data frame with one row per layer and columns layer, status ("success", "skipped" or "error"), path, features and message.

Examples

## Not run: 
report <- argentum_download(
  "https://wms.ign.gob.ar/geoserver/ows",
  layers = "ign:provincia",
  dir = tempdir()
)
subset(report, status == "error")

## End(Not run)

Guided help at the console

Description

Prints a short, copy-pasteable guide for common tasks: getting started, understanding the catalogue, listing layers, downloading data, rendering WMS maps and tuning options. It complements ?argentum (the grouped reference) and the vignettes (the long-form articles).

Usage

argentum_help(topic = "inicio", lang = c("es", "en"))

Arguments

Value

topic, invisibly. Called for its printed output.

Examples

argentum_help()
argentum_help("descargar")
argentum_help("download", lang = "en")

List the layers published by a service

Description

List the layers published by a service

Usage

argentum_layers(x, service = c("wfs", "wms"), refresh = FALSE)

Arguments

Value

A data frame with columns name, title, abstract, crs and bbox (a WGS84 ⁠xmin,ymin,xmax,ymax⁠ string). Zero rows if the service publishes none. crs is normalised to EPSG:code form even when the service declares it as a URN.

Examples

## Not run: 
layers <- argentum_layers("https://wms.ign.gob.ar/geoserver/ows")
head(layers[, c("name", "title")])

## End(Not run)

Package options

Description

Argentum reads its defaults from options(). Set them in a script or in .Rprofile.

Details

argentum.timeout

Seconds before an individual HTTP request is abandoned. Default 30.

argentum.max_tries

How many times a transient failure is retried with exponential backoff. Default 3.

argentum.page_size

Features requested per WFS page. Default 5000. Lower it for servers that cap response size.

argentum.cache_ttl

Seconds a cached catalogue or capabilities document stays fresh. Default 86400 (one day).

argentum.catalog

Path to a CSV overriding the bundled endpoint catalogue. See vignette("getting-started", package = "Argentum").

argentum.quiet

Suppress progress messages. Default FALSE.

List organizations publishing OGC services

Description

Returns the catalogue of Argentine public bodies known to expose OGC geoservices, as published in IDERA's own spreadsheet.

Usage

argentum_organizations(
  service = c("any", "wfs", "wms", "wcs", "csw"),
  refresh = FALSE
)

Arguments

Value

A data frame with columns name, level, jurisdiction, dependency, organization, updated, wms_url, wfs_url, wcs_url and csw_url. name is the human-readable label used by the rest of the package.

See Also

argentum_search_organizations(), argentum_layers()

Examples

## Not run: 
orgs <- argentum_organizations()
head(orgs$name)

# Only those with a usable WMS endpoint
argentum_organizations(service = "wms")

## End(Not run)

Read a WFS layer as an sf object

Description

Improves on the v1 importer in four ways: the protocol version is taken from the negotiated capabilities rather than hard-coded, large layers are fetched page by page instead of in one request that times out, a spatial or attribute filter can be pushed down to the server, and if the endpoint cannot produce GeoJSON the request falls back to GML.

Usage

argentum_read_wfs(
  x,
  layer,
  bbox = NULL,
  crs = NULL,
  max_features = NULL,
  page_size = arg_opt("argentum.page_size"),
  filter = NULL,
  quiet = arg_opt("argentum.quiet")
)

Arguments

Details

When a read fails outright the request is retried with paging disabled and then against each older protocol version, exactly as the ArgentinaGeoServices QGIS plugin does: several Argentine GeoServer installs advertise 2.0.0 and then fail to serialise GML in that version while answering 1.0.0 perfectly. If every attempt fails, the server is asked for a single feature so that its own error message can be reported instead of a bare parse failure.

Value

An sf data frame. Zero rows if the filter matches nothing.

See Also

argentum_download() to write layers straight to disk.

Examples

## Not run: 
url <- "https://wms.ign.gob.ar/geoserver/ows"

# Everything in a small layer
provinces <- argentum_read_wfs(url, "ign:provincia")

# Only what falls inside a bounding box, reprojected
argentum_read_wfs(
  url, "ign:provincia",
  bbox = c(-59, -35, -57, -34),
  crs = 4326
)

## End(Not run)

Render a WMS layer as a raster

Description

Issues a GetMap request and returns the rendered image georeferenced as a terra::SpatRaster. Unlike a WFS read this gives you the server's own cartography — useful for basemaps, orthophotos and any layer published only as a picture.

Usage

argentum_read_wms(
  x,
  layer,
  bbox,
  crs = NULL,
  width = NULL,
  height = NULL,
  style = NULL,
  format = NULL,
  transparent = TRUE,
  quiet = arg_opt("argentum.quiet")
)

Arguments

Value

A terra::SpatRaster with the CRS set, ready to combine with vector data read via argentum_read_wfs().

See Also

argentum_wms_legend() for the matching legend graphic.

Examples

## Not run: 
r <- argentum_read_wms(
  "https://wms.ign.gob.ar/geoserver/ows",
  layer = "ign:provincia",
  bbox  = c(-59, -35, -57, -34),
  width = 800
)
terra::plotRGB(r)

## End(Not run)

Search the organization catalogue

Description

Search the organization catalogue

Usage

argentum_search_organizations(
  pattern,
  service = c("any", "wfs", "wms", "wcs", "csw"),
  refresh = FALSE
)

Arguments

Value

A data frame, possibly with zero rows.

Examples

## Not run: 
argentum_search_organizations("buenos aires")
argentum_search_organizations("catastro", service = "wfs")

## End(Not run)

Retrieve the legend graphic for a WMS layer

Description

Retrieve the legend graphic for a WMS layer

Usage

argentum_wms_legend(x, layer, style = NULL, format = "image/png")

Arguments

Value

A terra::SpatRaster holding the legend image (no CRS: it is a picture, not a map).

Examples

## Not run: 
argentum_wms_legend("https://wms.ign.gob.ar/geoserver/ows", "ign:provincia")

## End(Not run)