`metadata()` is an optional function for the `envar` package workflow. Added at the end of a pipeline, it collects everything the pipeline did and writes it to disk as a reproducibility record: the data sources that were contacted (source URLs and the date each file was downloaded), the variables that were produced, the temporal period they refer to, the native resolution of each source dataset, the resolution and coordinate reference system of the output, and the processing settings that were used (those given to [par_set()] as well as the arguments of every dataset function that was called).
Value
`x`, so that the pipeline object is not altered, with the summary attached:
for a list input, as the elements `metadata` (the summary as a `data.frame`) and `metadata_path` (the paths of the two files written);
for a `SpatRaster` or `data.frame` input, as the attributes `"envar_metadata"` and `"metadata_path"`, retrievable with `attr(x, "envar_metadata")`.
Details
The information is gathered while the pipeline runs. [par_set()] clears the record and stores the study-area settings, each dataset function registers its own call, and every download and every source raster is registered as it is handled. `metadata()` therefore describes the pipeline that started with the most recent call to [par_set()] in the current R session; the output object itself (variables, resolution, CRS, extent) is described directly from `x`.
Two files are written: a readable report (`envar_metadata.txt`) and the same information as a table with one row per dataset (`envar_metadata.csv`). As in [corr_check()], an interactive R session asks at the console for the directory to store them in every time the function is called, with an empty answer meaning the working directory. When a pipeline contains both `corr_check()` and `metadata()` the question is therefore asked twice, once for each function. In non-interactive sessions (e.g. scripts or `R CMD check`) a temporary directory is used and no prompt is shown.
Examples
# Called outside a pipeline, metadata() still describes the object it is
# given (variables, resolution, CRS, extent) and reports that no download was
# recorded. This runs offline on the example raster bundled with the package:
switzerland <- terra::rast(
system.file("extdata", "switzerland.tif", package = "envar")
)
m <- metadata(switzerland)
attr(m, "metadata_path")
# \donttest{
# Store the provenance of a pipeline
processed <- par_set(country = "Italy", crs = 3035, buffer = 10) %>%
melc(vars = c("ice")) %>%
chelsa(vars = c("pr"), months = 12, year = 2015) %>%
metadata()
# The summary is also returned with the object
attr(processed, "envar_metadata")
# Together with corr_check(): the directory is asked twice, once per function
checked <- par_set(country = "Italy") %>%
chelsa(vars = c("bio1", "bio12")) %>%
corr_check() %>%
metadata()
checked$metadata
# }