Skip to contents

Copy a catalogued layer to a local directory

Source: R/download_layer.R
download_layer.Rd

Copies a layer from the spatial data share to a folder of your own, bringing its documentation with it. Everything in the layer folder comes down — the data, its readme, and any ancillary files beside them — and where a product's record is split between a product readme and a variant readme, both are copied.

Usage

download_layer(
  name,
  dest,
  overwrite = FALSE,
  dry_run = FALSE,
  verify = TRUE,
  keep_theme = FALSE,
  quiet = FALSE,
  ...
)

Arguments

name

Character; a layer name ("fab_dem") or catalogue id ("elevation/fab_dem") as listed by list_layers().

dest

Character; a local directory to copy into. Created if it does not exist.

overwrite

Logical; if TRUE, copy every file again rather than skipping those already present and unchanged. Default FALSE.

dry_run

Logical; if TRUE, report what would be copied and how much it comes to, writing nothing. Default FALSE.

verify

Logical; if TRUE (default), check every copied file against its source on size and md5 checksum, and record the result in the log. Verification re-reads each copied file from the share, so it roughly doubles the time a large copy takes; pass FALSE to skip it.

keep_theme

Logical; if TRUE, include the layer's ISO topic category folder in the local path, reproducing the share's full structure. Default FALSE.

quiet

Logical; if TRUE, suppress progress messages. Default FALSE.

...

Passed to build_catalogue(), e.g. root or refresh.

Value

Invisibly, a data.frame with one row per file copied, skipped, or attempted:

source

Path on the share.

destination

Path written under dest.

bytes

Size of the source, summed over a geodatabase's contents.

part

"layer" for the layer's own files, "product" for the parent product's metadata.

status

"copied", "skipped", or "failed"; or "would copy" and "would skip" under dry_run.

verified

"ok", the reason verification failed, or "not checked". NA for a skipped file.

md5

The source checksum, where one was taken.

Details

Use this to work off the network, or to hand someone a dataset they can cite. To read a layer without copying it, use get_layer().

The copy is rooted at the product folder, which lands directly in dest: a layer catalogued as geoscientific/soilgrids/soil1km arrives as <dest>/soilgrids/soil1km, with the product's readme one level above it in <dest>/soilgrids, exactly as the two sit on the share. The ISO topic category is the share's filing system rather than part of the dataset, so it is left behind; pass keep_theme = TRUE to reproduce the full catalogue path, which is what keeps two same-named products in different themes from merging into one folder. Sibling variants of the same product are separate layers and are not copied; ask for them by name.

Only the product's non-data files are copied alongside a variant — its readme and any documentation, not a second copy of any data file that happens to sit at product level. Shapefile sidecars (.dbf, .shx, .prj and friends) are treated as data and always accompany their .shp, unlike in layer_files(), which hides them so a shapefile is listed once. An Esri file geodatabase is copied whole, as one item.

A file already present in dest and matching its source on size and modification time is skipped, so an interrupted copy resumes rather than restarts. overwrite = TRUE forces every file to be copied again; overwrite = FALSE still replaces a destination file that differs from its source.

Every copy leaves a receipt: _download_log.txt is written into the layer's folder alongside the data, recording what was copied, from where, by whom, when, how long it took, and each file's size and md5 checksum. Runs append to it rather than replacing it, so a layer topped up over several sessions keeps its whole history. A copy whose provenance lives only in the console scrollback has none by the time anyone asks, which is the same reason the readme comes down with the data.

With verify = TRUE (the default) each copied file is read back and compared to its source on size and md5 checksum before the log records it as sound. Only files copied in that run are checked: a skipped file was verified when it was copied, and the log beside it says so, which keeps a re-run cheap.

See also

get_layer() to read a layer without copying it, layer_files() to see what a layer folder holds, and layer_meta() for its metadata.

Examples

if (FALSE) { # \dontrun{
# See what a copy would cost before starting one.
download_layer("fab_dem", "D:/local_spatial", dry_run = TRUE)

download_layer("fab_dem", "D:/local_spatial")

# A variant brings its product's readme down with it.  The
# product name resolves on its own while it holds one variant;
# otherwise give the full id list_layers() reports.
p <- download_layer("soilgrids_250_v2_ab", "D:/local_spatial")
p[p$part == "product", c("destination", "status")]

# Reproduce the share's full path, theme folder included.
download_layer("fab_dem", "D:/local_spatial", keep_theme = TRUE)

# The receipt left beside the data.
cat(readLines("D:/local_spatial/fab_dem/_download_log.txt"),
    sep = "\n")

# Skip the read-back on a very large copy.
download_layer("scanfi", "D:/local_spatial", verify = FALSE)

# Re-running copies only what changed.
download_layer("fab_dem", "D:/local_spatial")
} # }