defineLayer: Define a Layer object
In MagicForrest/DGVMTools: DGVM Processing, Analysis and Plotting Tools

defineLayer

R Documentation

Define a Layer object

Description

This function defines a Layer object represents a sub-component or one particular aspect of a Field object, for example one PFT or one carbon pool. It preferred to a new("Layer",...) initialisation because it does both the initialisation and also optionally adds the Layer to to a Format/Source/Field object with the add.to argument.

Usage

defineLayer(
  id,
  name = id,
  colour,
  properties = list(type = "Undefined"),
  add.to
)

Arguments

`id`	A unique character string to identify this newly defined Layer. This could be, for example, a PFT abbreviation.
`name`	A more readable character string to describe the Layer, for example the full PFT name. Optional, if omitted the id argument will be used here.
`colour`	A character string giving the preferred plot colour for this Layer.
`properties`	A list with named items containing metadata describing the Layer. These are used with the whichLayers and layerOp functions to automagically select layers. There is a lot of flexibility here, but it is recommended that the list includes at least an element called "type", and then ideally all the proprties required to describe the layer. An example for a broadleaved summergreen tree PFT could look like: `properties = list(type = "PFT", growth.form = "Tree", phenology = "Summergreen")`. A slow litter soil carbon pool could look like: `properties = list(type = "CPool", speed = "Slow", zone = "Soil", comprises = "Litter")`.
`add.to`	A Format, or a Source, or a Field object to which this newly defined layer should be added (optional). If this is specified then the defineQuantity() returns the Format/Source/Field with the Quantity added.

Details

Only the id and colour arguments are compulsory, the rest will be filled with dummy/default values if left blank. However, one advantage of formally defining a Layer object is that one can use the properties slot of the Layer to conveniently select, aggregate and operate on layers with functions whichLayers and layerOp, so it is recommended to define the properties to take advantage of this. When defining Layers it is important that the properties are defined consistently between Layer so that the functions whichLayers and layerOp work as expected.
Note that no actual data is stored in the resultant Field, only metadata.

Value

Either an Layer object (if "add.to" argument not supplied), or an updated Format/Source/Field object if "add.to" was specified.

Author(s)

Matthew Forrest matthew.forrest@senckenberg.de

Examples


## Define a couple of new Layers


## a hypothetical shrub PFT 
TeBES.PFT <- defineLayer(id = "TeBES",
                       name = "Temperate Broadleaved Evergreen Shrub",
                       colour = "red",
                       properties = list(type = "PFT",      
                                         climate.zone = "Temperate",
                                         leaf.form = "Broadleaved",
                                         phenology = "Evergreen",
                                         growth.form = "Shrub"))

# print it
print(TeBES.PFT)

# and add it to the GUESS format and check it is there
GUESS <- addTo(TeBES.PFT, GUESS)
print(GUESS@predefined.layers)

## Also add a couple of aggregate Layers *directly* to the GUESS source
## by using the "add.to" argument

# Note, not defining growth.form etc because they might get double counted 
GUESS  <- defineLayer(id = "Grass",
                       name = "Grass Total",
                       colour = "red",
                       properties = list(type = "Aggregate"),
                       add.to = GUESS)
                       
GUESS  <- defineLayer(id = "Tree",
                       name = "Tree Total",
                       colour = "gray",
                       properties = list(type = "Aggregate"),
                       add.to = GUESS)
                       
                       
# check them out 
 print(GUESS@predefined.layers)


 
## Show the plot colours in action

# Load a multi-Layer (one layer per-PFT) Field from the example data averaged in space
run.dir <- system.file("extdata", "LPJ-GUESS_Runs", "CentralEurope", package = "DGVMTools")
test.Source <- defineSource(id = "LPJ-GUESS_Example", dir = run.dir,  format = GUESS)
test.Field <- getField(source = test.Source, quant = "lai", spatial.aggregate.method = "mean", 
                       spatial.extent.id = "CentralEurope") 

# make calculate Tree and Grass sums
test.Field <- layerOp(test.Field, "+", ".Tree", "Tree")
test.Field <- layerOp(test.Field, "+", ".Grass", "Grass")

# plot - notice the defined colours for the Tree and Grass layer are plotted
print(plotTemporal(test.Field))

# also plot all the 'Aggregate' layers
print(whichLayers(test.Field, criteria = "Aggregate"))
print(plotTemporal(test.Field, whichLayers(test.Field, criteria = "Aggregate")))

MagicForrest/DGVMTools documentation built on Aug. 23, 2024, 8:05 a.m.