Inconsistent Documentation for Running Inidividual gcamland Simulations

[peterqstorm]

Good afternoon,

I just received your submission to the Journal of Open Research Software from Dr. Kate Calvin. When attempting to run the code using the documentation in R, I kept encountering errors. However, using the instructions within paper I just received (page 5, Installing and Running the Package) it ran successfully!

So it looks like the documentation in the R package is a bit behind; I was unable to locate the documentation files to edit them for you, so I figured I should give you a heads up.

Thanks for all of the work you've put into this!

Peter

[rplzzz]

Thanks for the info. Which function were you looking at the R documentation for? Let me know, and I'll give it a look and an update sometime next week.

[peterqstorm]

The run_model function provides the following example (doesn't work):
run_model(aScenarioInfo, aPeriods = NULL, aVerbose = FALSE)

The main gcamland function provides the following functions (doesn't work):
sceninfo <- ScenarioInfo(aScenarioType = "Hindcast", aOutputDir = "./output")
rslt <- run_model(sceninfo)

However, the function that is working for me is copied in from the paper as follows:
run_model(SCENARIO.INFO, aVerbose=TRUE)
export_results(SCENARIO.INFO)
print(plotRegionalLandAllocation (SCENARIO.INFO))

[kvcalvin]

Thanks! We will fix that.

[rplzzz]

The changes in #39 should make the R help files a little easier to understand.

One thing to keep in mind is the in R documentation conventions, the Usage section shows argument names and their default values, but these lines will not in general be runnable directly as written. For example, suppose you were to try to execute:

> run_model(aScenarioInfo, aPeriods = NULL, aVerbose = FALSE)

You should expect to get an error something like object 'aScenarioInfo' not found unless you happen to have created an object by that name in your top-level environment. To run the function, you need to supply valid objects for those arguments; the Arguments section of the help page explains what "valid" means in the context of each argument. In this case, aScenarioInfo needs an object returned from the ScenarioInfo function, aPeriods needs an integer vector, and aVerbose needs a True/False value.

To make this a little clearer, we've added an Examples section that contains code that should be runnable exactly as written.