mland_save: Saves a 'MultiLand' or 'MultiLandMetrics' object
In multilandr: Landscape Analysis at Multiple Spatial Scales

mland_save

R Documentation

Saves a 'MultiLand' or 'MultiLandMetrics' object

Description

Exports an object of class 'MultiLand' to be read in the future with mland_load(), or an object of class 'MultiLandMetrics' as if it was saved with saveRDS().

Usage

mland_save(
  x,
  name = NULL,
  gdal = c("COMPRESS=DEFLATE", "PREDICTOR=2", "ZLEVEL=9"),
  dir = NULL,
  verbose = TRUE,
  ...
)

Arguments

`x`	Object of class 'MultiLand' or 'MultiLandMetrics'.
`name`	If `x` is an object of class 'MultiLand', the name of the zip file where files will be saved (without the '.zip'). If `x` is an object of class 'MultiLandMetrics', the name of the R file (.rds). If NULL (default), the name will be 'mland_' or 'mlandmetrics_' + a large random number.
`gdal`	GeoTiff creation options for rasters (GeoTiff file format). `mland_save()` uses the following compression options: c("COMPRESS=DEFLATE", "PREDICTOR=2", "ZLEVEL=9"). Only relevant if `x` is an object of class 'MultiLand'.
`dir`	Path to the export directory. This must be specified explicitly. To export to the current directory, use `dir = getwd()`. Otherwise, provide a valid path to an existing directory, ensuring it does not end with "/".
`verbose`	Print messages in the console? Default is TRUE.
`...`	If `x` is an object of class 'MultiLand', `...` should depict other arguments passed to terra::writeRaster, the function to write raster layers (from intersections and plain raster layers). Otherwise, if `x` is an object of class 'MultiLandMetrics', `...` should depict other arguments passed to `save()`. See Details.

Details

'MultiLand' objects should be exported with this function rather than exporting as an external representation of R objects with saveRDS(). This is because objects of classes 'SpatVector' and 'SpatRaster' (from package terra) contained inside a 'MultiLand' object cannot be exported as regular R objects. The exported object will be a zip file, and can be loaded again into an R session with mland_load().

Relevant arguments can be passed to the function terra::writeRaster, which is used to write raster layers from a 'MultiLand' object. Particularly, in the argument gdal one can specify relevant options regarding raster compression. This may reduce raster sizes significantly. Definition of some other arguments inside terra::writeRaster may affect exportation of raster layer objects, in the context of a 'MultiLand' object.

Objects of class 'MultiLandMetrics', instead, do not contain 'SpatVector' or 'SpatRaster' objects and can be exported as regular R objects with saveRDS(). The user may use saveRDS() or mland_save(), and the outcome will be identical.

Value

If x is an object of class 'MultiLand', a zip file or a directory containing all information regarding the 'MultiLand' object provided in 'x'. Otherwise, if x is an object of class 'MultiLandMetrics', the function will export the R object as if it was exported as a regular R object with saveRDS().

Examples


# Load MultiLand object
mland_obj <- system.file("extdata", "ernesdesign.zip", package = "multilandr")
ernesdesign2 <- mland_load(mland_obj)

# Save it again, in temporary directory for this example and with a given name
mland_save(ernesdesign2, name = "mland_example", dir = tempdir())

# Remove file for this example
unlink(file.path(tempdir(), "mland_example.zip"))

# Save it again but defining a higher compression for raster layers
mland_save(ernesdesign2, gdal = "COMPRESS=DEFLATE", name = "mland_example", dir = tempdir())

# Remove file for this example
unlink(file.path(tempdir(), "mland_example.zip"))

# Loads a MultiLandMetrics object previously generated with mland_metrics()
mlm_obj <- system.file("extdata", "ed_metrics.rds", package = "multilandr")
ed_metrics2 <- mland_load(mlm_obj)

# Save it again. In this case, mland_save() is the same as using saveRDS()
mland_save(ed_metrics2, dir = tempdir(), name = "mlandmetrics_example")

unlink(file.path(tempdir(), "mlandmetrics_example.rds"))

multilandr documentation built on April 3, 2025, 7:39 p.m.