| Title: | PEcAn Settings package |
|---|---|
| Description: | Contains functions to read PEcAn settings files. |
| Authors: | David LeBauer [aut, cre], Rob Kooper [aut], University of Illinois, NCSA [cph] |
| Maintainer: | David LeBauer <[email protected]> |
| License: | BSD_3_clause + file LICENSE |
| Version: | 1.9.1.9000 |
| Built: | 2026-06-05 14:42:02 UTC |
| Source: | https://github.com/PecanProject/pecan |
Extract SafeList component by name
## S3 method for class 'SafeList' x$name## S3 method for class 'SafeList' x$name
x |
the SafeList object |
name |
the name of the component |
Overrides $.list, and works just like it except forces exact match
(i.e., makes x$name behave exactly like x[[name, exact=T]])
The specified component
Ryan Kelly
Add secret information from ~/.pecan.xml
addSecrets(settings, force = FALSE)addSecrets(settings, force = FALSE)
settings |
settings file |
force |
Logical: add secrets even if they have been added previously? |
Copies certains sections from ~/.pecan.xml to the settings. This allows a user to have their own unique parameters also when sharing the pecan.xml file we don't expose these secrets. Currently this will copy the database sections
will return the updated settings values
Rob Kooper
check to make sure BETY is up to date
check.bety.version(dbcon)check.bety.version(dbcon)
dbcon |
database connection object |
Check Database
check.database(database)check.database(database)
database |
settings list to check.
You'll probably use |
Check Database Settings
check.database.settings(settings)check.database.settings(settings)
settings |
settings file |
Check ensemble Settings
check.ensemble.settings(settings)check.ensemble.settings(settings)
settings |
settings file |
check to see if inputs are specified - this should be part of the model code
check.inputs(settings)check.inputs(settings)
settings |
settings file |
Check Model Settings
check.model.settings(settings, dbcon = NULL)check.model.settings(settings, dbcon = NULL)
settings |
settings file |
dbcon |
database connection. |
Check Run Settings
check.run.settings(settings, dbcon = NULL)check.run.settings(settings, dbcon = NULL)
settings |
settings file |
dbcon |
database connection. |
Sanity checks. Checks the settings file to make sure expected fields exist. It will try to use default values for any missing values, or stop the exection if no defaults are possible.
check.settings(settings, force = FALSE)check.settings(settings, force = FALSE)
settings |
settings file |
force |
Logical: Rerun check even if these settings have been checked previously? |
Expected fields in settings file are:
pfts with at least one pft defined
will return the updated settings values with defaults set.
Rob Kooper, David LeBauer
Check Workflow Settings
check.workflow.settings(settings, dbcon = NULL)check.workflow.settings(settings, dbcon = NULL)
settings |
settings file |
dbcon |
database connection |
This will try and clean the settings file so it is ready for a new run. This will remove all run specific information and set the outdir to be 'pecan' for the next run.
clean.settings(inputfile = "pecan.xml", outputfile = "pecan.xml", write = TRUE)clean.settings(inputfile = "pecan.xml", outputfile = "pecan.xml", write = TRUE)
inputfile |
the PEcAn settings file to be used. |
outputfile |
the name of file to which the settings will be written inside the outputdir. |
write |
Indicates whether to write the modified settings to a file. |
list of all settings as saved to the XML file(s)
Rob Kooper
## Not run: clean.settings('output/PEcAn_1/pecan.xml', 'pecan.xml') ## End(Not run)## Not run: clean.settings('output/PEcAn_1/pecan.xml', 'pecan.xml') ## End(Not run)
Create a MultiSettings object containing (identical) run blocks for multiple different sites
createMultiSiteSettings(templateSettings, siteIds)createMultiSiteSettings(templateSettings, siteIds)
templateSettings |
A |
siteIds |
The site IDs to be used in the resulting MultiSettings.
May be a vector or a data frame with a mandatory |
Starts with a template settings object, and duplicates the run$site
block once for each specified site ID. The resulting MultiSettings is thus
identical to the input, except ready to run for each site in the vector
of site IDs.
If siteIds is a data frame with a column named id,
each resulting run$site block will contain all the site parameters
(lat, lon, site name, etc) that are specified in its other columns.
A MultiSettings object with the same settings as
templateSettings but replicated run$site blocks,
one for each specified site ID.
Ryan Kelly
dontrun <- function() { # Added by Alexey Shiklomanov # so this doesn't run and break the build # This isn't necessarily a fully working settings object. # Enough to get the idea though. # Note it has a $run block with settings that will be shared across all sites template <- Settings(list( info = structure(list( notes = NULL, userid = "1000000005", username = "Ryan Kelly", date = "2016/07/13 13:23:46 -0400"), .Names = c("notes", "userid", "username", "date")), database = structure(list( bety = structure( list(user = "bety", password = "bety", host = "psql-pecan.bu.edu", dbname = "bety", driver = "PostgreSQL", write = "TRUE"), .Names = c("user", "password", "host", "dbname", "driver", "write")), fia = structure( list(user = "bety", password = "bety", host = "psql-pecan.bu.edu", dbname = "fia5", driver = "PostgreSQL", write = "true"), .Names = c("user", "password", "host", "dbname", "driver", "write"))), .Names = c("bety", "fia")), pfts = structure(list( pft = structure( list(comment = NULL, name = "temperate.Evergreen_Hardwood", constants = structure(list(num = "1"), .Names = "num")), .Names = c("comment", "name", "constants")), pft = structure( list(name = "temperate.Hydric", constants = structure(list(num = "2"), .Names = "num")), .Names = c("name", "constants"))), .Names = c("pft", "pft")), meta.analysis = structure(list( iter = "3000", random.effects = list(on = FALSE, use_ghs = TRUE), update = "AUTO", threshold = "1.2"), .Names = c("iter", "random.effects", "update", "threshold")), ensemble = structure(list(size = "1", variable = "NPP"), .Names = c("size", "variable")), model = structure(list(id = "2000000005", edin = "/home/rykelly/pecan/RK_files/ED2IN/ED2IN.rgit.mandifore_04", config.header = structure(list( radiation = structure(list(lai_min = "0.01"), .Names = "lai_min"), ed_misc = structure(list(output_month = "12"), .Names = "output_month")), .Names = c("radiation", "ed_misc")), phenol.scheme = "0", prerun = "module load hdf5/1.8.11", binary = "/usr2/postdoc/rykelly/ED2/ED/build/ed_2.1-opt"), .Names = c("id", "edin", "config.header", "phenol.scheme", "prerun", "binary")), host = structure(list(name = "geo.bu.edu", user = "rykelly", folder = "/projectnb/dietzelab/pecan.data/output/rykelly", qsub = "qsub -V -N @NAME@ -o @STDOUT@ -e @STDERR@ -S /bin/bash", qsub.jobid = "Your job ([0-9]+) .*", qstat = "qstat -j @JOBID@ || echo DONE", prerun = "module load udunits R/R-3.0.0_gnu-4.4.6", dbfiles = "/projectnb/dietzelab/pecan.data/input", modellauncher = structure(list( binary = "/usr2/postdoc/rykelly/pecan/utils/modellauncher/modellauncher", qsub.extra = "-pe omp 20"), .Names = c("binary", "qsub.extra"))), .Names = c("name", "user", "folder", "qsub", "qsub.jobid", "qstat", "prerun", "dbfiles", "modellauncher")), run = structure(list( inputs = structure(list( met = structure(list(source = "NARR", output = "ED2"), .Names = c("source", "output")), lu = structure(list(id = "294", path = "/projectnb/dietzelab/EDI/ed_inputs/glu/"), .Names = c("id", "path")), soil = structure(list(id = "297", path = "/projectnb/dietzelab/EDI/faoOLD/FAO_"), .Names = c("id", "path")), thsum = structure(list(id = "295", path = "/projectnb/dietzelab/EDI/ed_inputs/"), .Names = c("id", "path")), veg = structure(list(id = "296", path = "/projectnb/dietzelab/EDI/oge2OLD/OGE2_"), .Names = c("id", "path")), pss = structure(list(source = "FIA"), .Names = "source")), .Names = c("met", "lu", "soil", "thsum", "veg", "pss")), start.date = "2004/01/01", end.date = "2004/01/31"), .Names = c("inputs", "start.date", "end.date")) )) sitegroupId <- 1000000002 startDate <- "2000/01/01" endDate <- "2015/12/31" nSite <- 10 outDir <- "~/multisite_setup_test" template <- setDates(template, startDate = startDate, endDate = endDate) template <- setOutDir(template, outDir) multiRunSettings <- createSitegroupMultiSettings( template, sitegroupId = sitegroupId, nSite = nSite) dir.create(outDir, showWarnings = FALSE) write.settings(multiRunSettings, outputfile = "pecan.xml") } # dontrundontrun <- function() { # Added by Alexey Shiklomanov # so this doesn't run and break the build # This isn't necessarily a fully working settings object. # Enough to get the idea though. # Note it has a $run block with settings that will be shared across all sites template <- Settings(list( info = structure(list( notes = NULL, userid = "1000000005", username = "Ryan Kelly", date = "2016/07/13 13:23:46 -0400"), .Names = c("notes", "userid", "username", "date")), database = structure(list( bety = structure( list(user = "bety", password = "bety", host = "psql-pecan.bu.edu", dbname = "bety", driver = "PostgreSQL", write = "TRUE"), .Names = c("user", "password", "host", "dbname", "driver", "write")), fia = structure( list(user = "bety", password = "bety", host = "psql-pecan.bu.edu", dbname = "fia5", driver = "PostgreSQL", write = "true"), .Names = c("user", "password", "host", "dbname", "driver", "write"))), .Names = c("bety", "fia")), pfts = structure(list( pft = structure( list(comment = NULL, name = "temperate.Evergreen_Hardwood", constants = structure(list(num = "1"), .Names = "num")), .Names = c("comment", "name", "constants")), pft = structure( list(name = "temperate.Hydric", constants = structure(list(num = "2"), .Names = "num")), .Names = c("name", "constants"))), .Names = c("pft", "pft")), meta.analysis = structure(list( iter = "3000", random.effects = list(on = FALSE, use_ghs = TRUE), update = "AUTO", threshold = "1.2"), .Names = c("iter", "random.effects", "update", "threshold")), ensemble = structure(list(size = "1", variable = "NPP"), .Names = c("size", "variable")), model = structure(list(id = "2000000005", edin = "/home/rykelly/pecan/RK_files/ED2IN/ED2IN.rgit.mandifore_04", config.header = structure(list( radiation = structure(list(lai_min = "0.01"), .Names = "lai_min"), ed_misc = structure(list(output_month = "12"), .Names = "output_month")), .Names = c("radiation", "ed_misc")), phenol.scheme = "0", prerun = "module load hdf5/1.8.11", binary = "/usr2/postdoc/rykelly/ED2/ED/build/ed_2.1-opt"), .Names = c("id", "edin", "config.header", "phenol.scheme", "prerun", "binary")), host = structure(list(name = "geo.bu.edu", user = "rykelly", folder = "/projectnb/dietzelab/pecan.data/output/rykelly", qsub = "qsub -V -N @NAME@ -o @STDOUT@ -e @STDERR@ -S /bin/bash", qsub.jobid = "Your job ([0-9]+) .*", qstat = "qstat -j @JOBID@ || echo DONE", prerun = "module load udunits R/R-3.0.0_gnu-4.4.6", dbfiles = "/projectnb/dietzelab/pecan.data/input", modellauncher = structure(list( binary = "/usr2/postdoc/rykelly/pecan/utils/modellauncher/modellauncher", qsub.extra = "-pe omp 20"), .Names = c("binary", "qsub.extra"))), .Names = c("name", "user", "folder", "qsub", "qsub.jobid", "qstat", "prerun", "dbfiles", "modellauncher")), run = structure(list( inputs = structure(list( met = structure(list(source = "NARR", output = "ED2"), .Names = c("source", "output")), lu = structure(list(id = "294", path = "/projectnb/dietzelab/EDI/ed_inputs/glu/"), .Names = c("id", "path")), soil = structure(list(id = "297", path = "/projectnb/dietzelab/EDI/faoOLD/FAO_"), .Names = c("id", "path")), thsum = structure(list(id = "295", path = "/projectnb/dietzelab/EDI/ed_inputs/"), .Names = c("id", "path")), veg = structure(list(id = "296", path = "/projectnb/dietzelab/EDI/oge2OLD/OGE2_"), .Names = c("id", "path")), pss = structure(list(source = "FIA"), .Names = "source")), .Names = c("met", "lu", "soil", "thsum", "veg", "pss")), start.date = "2004/01/01", end.date = "2004/01/31"), .Names = c("inputs", "start.date", "end.date")) )) sitegroupId <- 1000000002 startDate <- "2000/01/01" endDate <- "2015/12/31" nSite <- 10 outDir <- "~/multisite_setup_test" template <- setDates(template, startDate = startDate, endDate = endDate) template <- setOutDir(template, outDir) multiRunSettings <- createSitegroupMultiSettings( template, sitegroupId = sitegroupId, nSite = nSite) dir.create(outDir, showWarnings = FALSE) write.settings(multiRunSettings, outputfile = "pecan.xml") } # dontrun
Helps to create a MultiSettings object to run some or all sites in a Sitegroup.
createSitegroupMultiSettings( templateSettings, sitegroupId, nSite, con = NULL, params = templateSettings$database$bety )createSitegroupMultiSettings( templateSettings, sitegroupId, nSite, con = NULL, params = templateSettings$database$bety )
templateSettings |
A |
sitegroupId |
The Bety ID of the sitegroup to draw from |
nSite |
The number of sites to randomly select (without replacement) from the siteGroup. Omit to use all sites in the group. |
con, params
|
Bety DB connection or parameters.
Passed directly to |
Starts with a template settings object, and fills in the run block
with site info sampled from the sitegroup.
The template could be fully set up except for the site info,
or more or less empty if you plan to fill in the other settings later.
A MultiSettings is created from templateSettings,
nSite sites (or all of them, if nSite is unset) are selected
from Bety, and their info is dropped into the MultiSettings.
A MultiSettings object with the same settings as
templateSettings but site information for the selected sites
Ryan Kelly
dontrun <- function() { # Added by Alexey Shiklomanov # so this doesn't run and break the build # This isn't necessarily a fully working settings object. # Enough to get the idea though. # Note it has a $run block with settings that will be shared across all sites template <- Settings(list( info = structure(list( notes = NULL, userid = "1000000005", username = "Ryan Kelly", date = "2016/07/13 13:23:46 -0400"), .Names = c("notes", "userid", "username", "date")), database = structure(list( bety = structure( list(user = "bety", password = "bety", host = "psql-pecan.bu.edu", dbname = "bety", driver = "PostgreSQL", write = "TRUE"), .Names = c("user", "password", "host", "dbname", "driver", "write")), fia = structure( list(user = "bety", password = "bety", host = "psql-pecan.bu.edu", dbname = "fia5", driver = "PostgreSQL", write = "true"), .Names = c("user", "password", "host", "dbname", "driver", "write"))), .Names = c("bety", "fia")), pfts = structure(list( pft = structure( list(comment = NULL, name = "temperate.Evergreen_Hardwood", constants = structure(list(num = "1"), .Names = "num")), .Names = c("comment", "name", "constants")), pft = structure( list(name = "temperate.Hydric", constants = structure(list(num = "2"), .Names = "num")), .Names = c("name", "constants"))), .Names = c("pft", "pft")), meta.analysis = structure(list( iter = "3000", random.effects = list(on = FALSE, use_ghs = TRUE), update = "AUTO", threshold = "1.2"), .Names = c("iter", "random.effects", "update", "threshold")), ensemble = structure(list(size = "1", variable = "NPP"), .Names = c("size", "variable")), model = structure(list(id = "2000000005", edin = "/home/rykelly/pecan/RK_files/ED2IN/ED2IN.rgit.mandifore_04", config.header = structure(list( radiation = structure(list(lai_min = "0.01"), .Names = "lai_min"), ed_misc = structure(list(output_month = "12"), .Names = "output_month")), .Names = c("radiation", "ed_misc")), phenol.scheme = "0", prerun = "module load hdf5/1.8.11", binary = "/usr2/postdoc/rykelly/ED2/ED/build/ed_2.1-opt"), .Names = c("id", "edin", "config.header", "phenol.scheme", "prerun", "binary")), host = structure(list(name = "geo.bu.edu", user = "rykelly", folder = "/projectnb/dietzelab/pecan.data/output/rykelly", qsub = "qsub -V -N @NAME@ -o @STDOUT@ -e @STDERR@ -S /bin/bash", qsub.jobid = "Your job ([0-9]+) .*", qstat = "qstat -j @JOBID@ || echo DONE", prerun = "module load udunits R/R-3.0.0_gnu-4.4.6", dbfiles = "/projectnb/dietzelab/pecan.data/input", modellauncher = structure(list( binary = "/usr2/postdoc/rykelly/pecan/utils/modellauncher/modellauncher", qsub.extra = "-pe omp 20"), .Names = c("binary", "qsub.extra"))), .Names = c("name", "user", "folder", "qsub", "qsub.jobid", "qstat", "prerun", "dbfiles", "modellauncher")), run = structure(list( inputs = structure(list( met = structure(list(source = "NARR", output = "ED2"), .Names = c("source", "output")), lu = structure(list(id = "294", path = "/projectnb/dietzelab/EDI/ed_inputs/glu/"), .Names = c("id", "path")), soil = structure(list(id = "297", path = "/projectnb/dietzelab/EDI/faoOLD/FAO_"), .Names = c("id", "path")), thsum = structure(list(id = "295", path = "/projectnb/dietzelab/EDI/ed_inputs/"), .Names = c("id", "path")), veg = structure(list(id = "296", path = "/projectnb/dietzelab/EDI/oge2OLD/OGE2_"), .Names = c("id", "path")), pss = structure(list(source = "FIA"), .Names = "source")), .Names = c("met", "lu", "soil", "thsum", "veg", "pss")), start.date = "2004/01/01", end.date = "2004/01/31"), .Names = c("inputs", "start.date", "end.date")) )) sitegroupId <- 1000000002 startDate <- "2000/01/01" endDate <- "2015/12/31" nSite <- 10 outDir <- "~/multisite_setup_test" template <- setDates(template, startDate = startDate, endDate = endDate) template <- setOutDir(template, outDir) multiRunSettings <- createSitegroupMultiSettings( template, sitegroupId = sitegroupId, nSite = nSite) dir.create(outDir, showWarnings = FALSE) write.settings(multiRunSettings, outputfile = "pecan.xml") } # dontrundontrun <- function() { # Added by Alexey Shiklomanov # so this doesn't run and break the build # This isn't necessarily a fully working settings object. # Enough to get the idea though. # Note it has a $run block with settings that will be shared across all sites template <- Settings(list( info = structure(list( notes = NULL, userid = "1000000005", username = "Ryan Kelly", date = "2016/07/13 13:23:46 -0400"), .Names = c("notes", "userid", "username", "date")), database = structure(list( bety = structure( list(user = "bety", password = "bety", host = "psql-pecan.bu.edu", dbname = "bety", driver = "PostgreSQL", write = "TRUE"), .Names = c("user", "password", "host", "dbname", "driver", "write")), fia = structure( list(user = "bety", password = "bety", host = "psql-pecan.bu.edu", dbname = "fia5", driver = "PostgreSQL", write = "true"), .Names = c("user", "password", "host", "dbname", "driver", "write"))), .Names = c("bety", "fia")), pfts = structure(list( pft = structure( list(comment = NULL, name = "temperate.Evergreen_Hardwood", constants = structure(list(num = "1"), .Names = "num")), .Names = c("comment", "name", "constants")), pft = structure( list(name = "temperate.Hydric", constants = structure(list(num = "2"), .Names = "num")), .Names = c("name", "constants"))), .Names = c("pft", "pft")), meta.analysis = structure(list( iter = "3000", random.effects = list(on = FALSE, use_ghs = TRUE), update = "AUTO", threshold = "1.2"), .Names = c("iter", "random.effects", "update", "threshold")), ensemble = structure(list(size = "1", variable = "NPP"), .Names = c("size", "variable")), model = structure(list(id = "2000000005", edin = "/home/rykelly/pecan/RK_files/ED2IN/ED2IN.rgit.mandifore_04", config.header = structure(list( radiation = structure(list(lai_min = "0.01"), .Names = "lai_min"), ed_misc = structure(list(output_month = "12"), .Names = "output_month")), .Names = c("radiation", "ed_misc")), phenol.scheme = "0", prerun = "module load hdf5/1.8.11", binary = "/usr2/postdoc/rykelly/ED2/ED/build/ed_2.1-opt"), .Names = c("id", "edin", "config.header", "phenol.scheme", "prerun", "binary")), host = structure(list(name = "geo.bu.edu", user = "rykelly", folder = "/projectnb/dietzelab/pecan.data/output/rykelly", qsub = "qsub -V -N @NAME@ -o @STDOUT@ -e @STDERR@ -S /bin/bash", qsub.jobid = "Your job ([0-9]+) .*", qstat = "qstat -j @JOBID@ || echo DONE", prerun = "module load udunits R/R-3.0.0_gnu-4.4.6", dbfiles = "/projectnb/dietzelab/pecan.data/input", modellauncher = structure(list( binary = "/usr2/postdoc/rykelly/pecan/utils/modellauncher/modellauncher", qsub.extra = "-pe omp 20"), .Names = c("binary", "qsub.extra"))), .Names = c("name", "user", "folder", "qsub", "qsub.jobid", "qstat", "prerun", "dbfiles", "modellauncher")), run = structure(list( inputs = structure(list( met = structure(list(source = "NARR", output = "ED2"), .Names = c("source", "output")), lu = structure(list(id = "294", path = "/projectnb/dietzelab/EDI/ed_inputs/glu/"), .Names = c("id", "path")), soil = structure(list(id = "297", path = "/projectnb/dietzelab/EDI/faoOLD/FAO_"), .Names = c("id", "path")), thsum = structure(list(id = "295", path = "/projectnb/dietzelab/EDI/ed_inputs/"), .Names = c("id", "path")), veg = structure(list(id = "296", path = "/projectnb/dietzelab/EDI/oge2OLD/OGE2_"), .Names = c("id", "path")), pss = structure(list(source = "FIA"), .Names = "source")), .Names = c("met", "lu", "soil", "thsum", "veg", "pss")), start.date = "2004/01/01", end.date = "2004/01/31"), .Names = c("inputs", "start.date", "end.date")) )) sitegroupId <- 1000000002 startDate <- "2000/01/01" endDate <- "2015/12/31" nSite <- 10 outDir <- "~/multisite_setup_test" template <- setDates(template, startDate = startDate, endDate = endDate) template <- setOutDir(template, outDir) multiRunSettings <- createSitegroupMultiSettings( template, sitegroupId = sitegroupId, nSite = nSite) dir.create(outDir, showWarnings = FALSE) write.settings(multiRunSettings, outputfile = "pecan.xml") } # dontrun
generic function for expanding multi-settings.
expandMultiSettings(x)expandMultiSettings(x)
x |
object to be expanded. |
Checks for and attempts to fix deprecated settings structure
fix.deprecated.settings(settings, force = FALSE)fix.deprecated.settings(settings, force = FALSE)
settings |
settings list |
force |
Logical: re-run fixing of deprecated settings even if it has been done previously? |
updated settings list
Ryan Kelly
Used in web/workflow.R to parse command line arguments. See also https://github.com/PecanProject/pecan/pull/2626.
get_args()get_args()
list generated by parse_args; see there for details.
## Example using a script called from your bash terminal: ## If workflow.R contains `get_args()` and settings are in foo.xml, run as ## ./workflow.R -s settings.xml## Example using a script called from your bash terminal: ## If workflow.R contains `get_args()` and settings are in foo.xml, run as ## ./workflow.R -s settings.xml
Processes one site from the siteIds argument of createMultiSiteSettings.
You probably don't need to call it directly.
getRunSettings(templateSettings, siteId)getRunSettings(templateSettings, siteId)
templateSettings |
A |
siteId |
site to process. See |
A generic function to convert list to XML
listToXml(x, ...)listToXml(x, ...)
x |
list to be converted |
... |
arguments passed to methods |
Convert List to XML
## Default S3 method: listToXml(x, tag = "pecan", ...)## Default S3 method: listToXml(x, tag = "pecan", ...)
x |
object to be converted. Despite the function name, need not actually be a list |
tag |
name to use for the root tag of the resulting XML tree |
... |
further arguments, currently ignored |
Can convert list or other object to an xml object using xmlNode
xmlNode
David LeBauer, Carl Davidson, Rob Kooper
The csv or the text file needs to have a header and be separated using comma. Under the first column in the text file, one needs to specify the site id and in the second column there has to be the name of the PFT.
loadPath.sitePFT(Path)loadPath.sitePFT(Path)
Path |
Character of file name with extension. |
a dataframe of two columns of site and pft
Create a PEcAn MultiSettings object
MultiSettings(...) as.MultiSettings(x) is.MultiSettings(x)MultiSettings(...) as.MultiSettings(x) is.MultiSettings(x)
... |
Settings objects to concatenate |
x |
object to test or coerce |
list with class "Multisettings"
as.MultiSettings(): coerce an existing object to MultiSettings
is.MultiSettings(): test if an object is a MultiSettings
Ryan Kelly
Works like lapply(), but for PEcAn Settings and MultiSettings objects
papply(settings, fn, ..., stop.on.error = FALSE)papply(settings, fn, ..., stop.on.error = FALSE)
settings |
A |
fn |
The function to apply to |
... |
additional arguments to |
stop.on.error |
Whether to halt execution if a single element in
|
papply is mainly used to call a function on each
Settings object in a MultiSettings object,
and returning the results in a list.
It has some additional features, however:
If the result of fn is a Settings object,
then papply will coerce the returned list into a new
MultiSettings.
If settings is a Settings object,
then papply knows to call fn on it directly.
If settings is a generic list,
then papply coerces it to a Settings object
and then calls fn on it directly.
This is meant for backwards compatibility with old-fashioned PEcAn
settings lists, but could have unintended consequences
By default, papply will proceed even if fn throws an
error for one or more of the elements in settings.
Note that if this option is used, the returned results list will
have entries for only those elements that did not
result in an error.
A single fn return value, or a list of such values
(coerced to MultiSettings if appropriate; see Details)
Ryan Kelly
f = function(settings, ...) { # Here's how I envisioned a typical use case within a standard PEcAn function if(is.MultiSettings(settings)) { return(papply(settings, f, ...)) } # Don't worry about the beolow, it's just some guts to make the function do something we can see l <- list(...) for(i in seq_along(l)) { ind <- length(settings) + 1 settings[[ind]] <- l[[i]] if(!is.null(names(l))) { names(settings)[ind] <- names(l)[i] } } return(settings) } # Example settings1 <- Settings(list(a="aa", b=1:3, c="NA")) settings2 <- Settings(list(a="A", b=4:5, c=paste)) multiSettings <- MultiSettings(settings1, settings2) # The fucntion should add element $d = D to either a Settings, or each entry in a MultiSettings f(settings1, d="D") print(f(multiSettings, d="D"), TRUE)f = function(settings, ...) { # Here's how I envisioned a typical use case within a standard PEcAn function if(is.MultiSettings(settings)) { return(papply(settings, f, ...)) } # Don't worry about the beolow, it's just some guts to make the function do something we can see l <- list(...) for(i in seq_along(l)) { ind <- length(settings) + 1 settings[[ind]] <- l[[i]] if(!is.null(names(l))) { names(settings)[ind] <- names(l)[i] } } return(settings) } # Example settings1 <- Settings(list(a="aa", b=1:3, c="NA")) settings2 <- Settings(list(a="A", b=4:5, c=paste)) multiSettings <- MultiSettings(settings1, settings2) # The fucntion should add element $d = D to either a Settings, or each entry in a MultiSettings f(settings1, d="D") print(f(multiSettings, d="D"), TRUE)
Update, set defaults for, and otherwise prepare a PEcAn Settings object
prepare.settings(settings, force = FALSE)prepare.settings(settings, force = FALSE)
settings |
settings list |
force |
Whether to force the function to run even if it determines it has been run on these settings already. |
Performs various checks, fixes deprecated contructs, and assigns missing values where possible.
Ryan Kelly
Betsy Cowdery
generic function for printing contents of objects.
printAll(x)printAll(x)
x |
object to be printed. |
This will try and find the PEcAn settings file in the following order:
--settings <file> passed as command line argument using --settings
inputfile passed as argument to function
PECAN_SETTINGS environment variable PECAN_SETTINGS pointing to a specific file
./pecan.xml pecan.xml in the current folder
read.settings(inputfile = "pecan.xml")read.settings(inputfile = "pecan.xml")
inputfile |
the PEcAn settings file to be used. |
Once the function finds a valid file, it will not look further.
Thus, if inputfile is supplied, PECAN_SETTINGS will be
ignored.
Even if a file argument is passed, it will be ignored if a file
is passed through a higher priority method.
list of all settings as loaded from the XML file(s)
Shawn Serbin
Rob Kooper
David LeBauer
Ryan Kelly
Betsy Cowdery
test.settings.file <- system.file("test.xml", package = "PEcAn.settings") settings <- read.settings(test.settings.file)test.settings.file <- system.file("test.xml", package = "PEcAn.settings") settings <- read.settings(test.settings.file)
SafeList is a wrapper class for the normal R list. It should behave
identically, except for the $ operator being overridden to require exact
matches.
SafeList(...) as.SafeList(x) is.SafeList(x)SafeList(...) as.SafeList(x) is.SafeList(x)
... |
A list to upgrade to SafeList, or elements to be added to a new SafeList |
x |
list object to be tested or coerced |
The constructor works identical to list() unless:
The only argument is a list, in which case the result is the same list, with its class attribute updated to include 'SafeList', or
The only argument is a SafeList, in which case that argument is returned unchanged
The resulting SafeList
a SafeList version of x
logical
as.SafeList(): Coerce an object to SafeList.
is.SafeList(): Test if object is already a SafeList.
Ryan Kelly
Sets the run, ensemble, and sensitivity analysis dates of PEcAn Settings
setDates(settings, startDate, endDate)setDates(settings, startDate, endDate)
settings |
A |
startDate, endDate
|
The desired start and end dates |
Sets the start/end dates in settings$run to the specified dates,
and sets the corresponding years for settings$ensemble and
settings$sensitivity.analysis.
Either date can be omitted to leave it unchanged.
The original Settings object with updated dates
Ryan Kelly
Propagates a filename pattern into the relevant paths of a multi-site
settings. For example if your files are named like "mymet/siteA/scenario1.nc"
up through "mymet/siteZ/scenario50.nc",
setEnsemblePaths(settings, n_reps = 50, "mymet/{id}/scenario{n}.nc") will
add them all to your settings in one shot.
setEnsemblePaths( settings, n_reps, input_type = "met", path_template = "./{id}/{n}.nc", ... )setEnsemblePaths( settings, n_reps, input_type = "met", path_template = "./{id}/{n}.nc", ... )
settings |
a PEcAn MultiSettings object |
n_reps |
number of replicates to insert for each path. |
input_type |
subsection of the |
path_template |
format for the paths to be inserted, as a |
... |
additional variables to be interpolated into |
Operates on one input section (met, poolinitcond, etc) at a time because it's common to have different path conventions for met vs IC.
The path template should be a string recognized by glue::glue(),
with curly braces wrapping any expressions to be interpolated.
{n} will be replaced with each value of 1:n_reps, {id} will be
replaced with the siteid of each site, and any other variables need to be
passed as named arguments in ....
If inputs$<input_type> does not exist, it will be created with a path
element that matches the requested pattern. If it does exist, any existing
path element will be overwritten.
updated settings object
s <- as.Settings(list( run = list( start.date = "TBD", site = list(), inputs = list( met = list(), poolinitcond = list() ) ) )) m <- createMultiSiteSettings(s, c("a1", "b2")) m1 <- setEnsemblePaths(m, 2) m1$run$site.a1$inputs m2 <- setEnsemblePaths( m, 2, "poolinitcond", icdir = "some/long/path", path_template = "{icdir}/{id}/{n}.nc" ) m2$run$site.a1$inputss <- as.Settings(list( run = list( start.date = "TBD", site = list(), inputs = list( met = list(), poolinitcond = list() ) ) )) m <- createMultiSiteSettings(s, c("a1", "b2")) m1 <- setEnsemblePaths(m, 2) m1$run$site.a1$inputs m2 <- setEnsemblePaths( m, 2, "poolinitcond", icdir = "some/long/path", path_template = "{icdir}/{id}/{n}.nc" ) m2$run$site.a1$inputs
Sets the main output directory and nulls out the others
setOutDir(settings, outDir)setOutDir(settings, outDir)
settings |
A |
outDir |
The desired output directory |
Sets the main output directory (settings$outdir) to outDir,
and sets numerous others (settings$modeloutdir,
settings$host$rundir, settings$host$outdir,
settings$host$modeloutdir) to NULL so they will revert to defaults
when check.settings is run.
The original Settings object with updated output directories
Ryan Kelly
function that can retrieve or update the names of multi-settings.
settingNames(multiSettings, settingNames)settingNames(multiSettings, settingNames)
multiSettings |
object for which to retrieve or set the names. |
settingNames |
names to be set for the multi-settings object. |
Create a PEcAn Settings object
Settings(...) as.Settings(x) is.Settings(x)Settings(...) as.Settings(x) is.Settings(x)
... |
objects to concatenate |
x |
object to test or coerce |
a list containing all objects in ...,
with class c("Settings", "SafeList", "list").
as.Settings(): coerce an object to Settings
is.Settings(): test if object is already a Settings
Ryan Kelly
This function reads in a pecan setting and check for the pft.site xml tag under run>inputs. If a path or a ID for the input is defined then, it will be used for linking sites with the pfts.
site.pft.link.settings(settings)site.pft.link.settings(settings)
settings |
settings list |
pecan xml setting file
This function creates the required tags inside pecan.xml to link sites with pfts given a look up table. If the required tags are already defined in the pecan xml then they will be updated. If there are multiple pfts that they need to be used for a site, each pft needs to have a separate row in the lookup table, resulting multiple rows for a site.
site.pft.linkage(settings, site.pft.links)site.pft.linkage(settings, site.pft.links)
settings |
pecan settings list. |
site.pft.links |
dataframe. Your look up table should have two columns of site and pft with site ids under site column and pft names under pft column. |
pecan setting list
## Not run: #setting up the Look up tables site.pft.links <-tribble( ~site, ~pft, "1000025731", "temperate.broadleaf.deciduous1", "1000025731", "temperate.needleleaf.evergreen", "1000000048", "temperate.broadleaf.deciduous2", "772", "temperate.broadleaf.deciduous3", "763", "temperate.broadleaf.deciduous4" ) settings <- PEcAn.settings::read_settings("pecan.xml") site.pft.linkage(settings, site.pft.links) ## End(Not run)## Not run: #setting up the Look up tables site.pft.links <-tribble( ~site, ~pft, "1000025731", "temperate.broadleaf.deciduous1", "1000025731", "temperate.needleleaf.evergreen", "1000000048", "temperate.broadleaf.deciduous2", "772", "temperate.broadleaf.deciduous3", "763", "temperate.broadleaf.deciduous4" ) settings <- PEcAn.settings::read_settings("pecan.xml") site.pft.linkage(settings, site.pft.links) ## End(Not run)
Updates a pecan.xml file to match new layout. This will take care of the conversion to the latest pecan.xml file.
## S3 method for class 'settings' update(settings, force = FALSE)## S3 method for class 'settings' update(settings, force = FALSE)
settings |
settings file |
force |
Logical: update even if settings have previously been updated?. |
will return the updated settings values
Rob Kooper
If outputdir is NULL, the whole path is taken from outputfile.
If both outputfile and outputdir are NULL, no file is written
and it returns the formatted XML as character.
This can be handy for debugging.
write.settings(settings, outputfile, outputdir = settings$outdir)write.settings(settings, outputfile, outputdir = settings$outdir)
settings |
settings list |
outputfile |
the file name to write to |
outputdir |
the directory to write to |
path to written XML file, or settings as an XML string if outputfile is NULL
Ryan Kelly
Betsy Cowdery