defineQuantity: Define a Quantity object

In MagicForrest/DGVMTools: DGVM Processing, Analysis and Plotting Tools

Define a Quantity object

Description

This function defines a Quantity object which represents physical variables say LAI or evaoptranspiration. It is preferred to a new("Quantityr",...) initialisation because it does the initialisation (inclduing some defaults) and also optionally adds the newly defined Quantity to a Format/Source/Field object with the add.to argument.

Usage

defineQuantity(
  id,
  name = id,
  units,
  colours = viridis::viridis,
  format = "Standard",
  standard_name = "unknown",
  add.to
)

Arguments

id	A unique character string to identify this newly defined Quantity. This could be, for example, a "LAI" or "mNPP". (mandatory)
name	A more readable character string to describe the Quantity, for example the "Leaf Area Index" or "Monthly NPP". Optional, if omitted the id argument will be used here.
units	A character string describing the units of the Quantity (mandatory)
colours	A functions giving the preferred colour palette for this Quantity. Defaults to viridis.
format	A character string (or a list of character strings) defining which Format this quantity is defined for. Should match the id/ids of the Formats.
standard_name	A character string givien the standard CF-compliant name for writing netCDF files, e.g. "leaf_area_index" (optional, such standard names don't exist for all variables)
add.to	A Format, or a Source, or a Field object to which this newly defined Quantity should be added (optional). If this is specified then the defineQuantity() returns the Format/Source/Field with the Quantity added. Note that for a Field this over-writes the previous Quantity (ie the 'quant' slot) of the Field

Details

Use this function when you either:

• Want to examine new output from a model/dataset which is not defined in the default Format. You can specify the Format (or Source) in the 'add.to' argument so that this Quantity is sensibly defined and visible.

• Have modified a Format or calculated a new one entirely, and then want to update the Quantity to reflext this. In this case you can specify the modified/created Field in the 'add.to' argument so that the Field is updated.#'

Note that when the 'add.to' argument is used the function returns a modified version of that object *not* a Quantity

Only the id and units arguments are compulsory, the rest will be filled with dummy/default values if left blank. Note that no actual data is stored in the resultant Quantity, only metadata.

Value

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

Author(s)

Matthew Forrest [e-mail]

See Also

Source, Format, Field, availableQuantities, addTo

Examples

## Define a new Quantity

## eg. C turnover time
Cturnover.Quantity <- defineQuantity(id = "Cturnover",
                                     name = "Carbon Turnover Time",
                                     colours = viridis::magma,
                                     units = "y") # note no CF standard name is defined

# print it
print(Cturnover.Quantity)

# and add it to the GUESS format and check it is there
GUESS.updated <- addTo(Cturnover.Quantity, GUESS)
print(GUESS.updated@quantities)

## Also add it *directly* to the GUESS Source by using the "add.to" argument of the defineQuantity

GUESS.updated2 <- defineQuantity(id = "Cturnover2",
                        name = "Carbon Turnover Time",
                        colours = viridis::magma,
                        units = "y",
                        add.to = GUESS) 
                       
                       
# check it out 
print(GUESS.updated2@quantities)
 

 
# Define a Source and make a dummy test Field
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") 
                       
# Define a new Quantity and add it to the Source
test.Source.new <- defineQuantity(id = "Cturnover",
                        name = "Carbon Turnover Time",
                        colours = viridis::magma,
                        units = "y",
                        add.to = test.Source)
                        
# check that it is added correctly to the end of @quantities slot of the @format slot of the Source
print(test.Source.new@format@quantities[[length(test.Source@format@quantities)]]) 

## also define it for the test Field
## note that is actually changes the Quantity of the Field
test.Field <- defineQuantity(id = "Cturnover",
                        name = "Carbon Turnover Time",
                        colours = viridis::magma,
                        units = "y",
                        add.to = test.Field)
 print(test.Field)    
                    
# plot - notice the updated metadata 
print(plotTemporal(test.Field))

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