Data in a package

Summary:

Files with the following extensions will be read by R as data:

plain R code in .R and .r files are sourced using source()
text tables in .tab, .txt, .csv files are read using read() ** objects in R image files: .RData, .rda are loaded using load()
- capitalization matters
- all objects in foo.RData are loaded into environment
- pro: easiset way to store objects in R format
- con: format is application (R) specific (discussed in #318)

Details are in ?data, which is mostly a copy of Data section of Writing R Extensions.

Accessing data

Data in the [data] directory will be accessed in the following ways,

efficient way: (especially for large data sets) using the data function:

data(foo) # accesses data with, e.g. load(foo.RData), read(foo.csv), or source(foo.R)

easy way: by adding the following line to the package DESCRIPTION: note: this should be used with caution or it can cause difficulty as discussed in redmine issue #1118
```
LazyData: TRUE
```
From the R help page:

Currently, a limited number of data formats can be accessed using the data function by placing one of the following filetypes in a packages' data directory:

files ending .R or .r are source()d in, with the R working directory changed temporarily to the directory containing the respective file. (data ensures that the utils package is attached, in case it had been run via utils::data.)
files ending .RData or .rda are load()ed.
files ending .tab, .txt or .TXT are read using read.table(..., header = TRUE), and hence result in a data frame.
files ending .csv or .CSV are read using read.table(..., header = TRUE, sep = ';'), and also result in a data frame.

If your data does not fall in those 4 categories, or you can use the system.file function to get access to the data:

system.file("data", "ed.trait.dictionary.csv", package="PEcAn.utils")
[1] "/home/kooper/R/x86_64-pc-linux-gnu-library/2.15/PEcAn.utils/data/ed.trait.dictionary.csv"

The arguments are folder, filename(s) and then package. It will return the fully qualified path name to a file in a package, in this case it points to the trait data. This is almost the same as the data function, however we can now use any function to read the file, such as read.csv instead of read.csv2 which seems to be the default of data. This also allows us to store arbitrary files in the data folder, such as the the bug file and load it when we need it.

Examples of data in PEcAn packages

Redmine issue #1060 added time constants in source:utils/data/time.constants.RData
outputs: [/modules/uncertainties/data/output.RData]
parameter samples [/modules/uncertainties/data/samples.RData]

Packages used in development

roxygen2

Used to document code. See instructions under [[R#Coding_Style|Coding Style]]

devtools

Provides functions to simplify development

Documentation: The R devtools packate

load_all("pkg")
document("pkg")
test("pkg")
install("pkg")
build("pkg")

other tips for devtools (from the documentation):

Adding the following to your ~/.Rprofile will load devtools when running R in interactive mode:
```
# load devtools by default
if (interactive()) {
suppressMessages(require(devtools))
}
```

Adding the following to your .Rpackages will allow devtools to recognize package by folder name, rather than directory path

# in this example, devhome is the pecan trunk directory 
devhome <- "/home/dlebauer/R-dev/pecandev/"
list(
  default = function(x) {
    file.path(devhome, x, x)
  }, 
"utils" = paste(devhome, "pecandev/utils", sep = "")
"common" = paste(devhome, "pecandev/common", sep = "")
"all" = paste(devhome, "pecandev/all", sep = "")
"ed" = paste(devhome, "pecandev/models/ed", sep = "")
"uncertainty" = paste(devhome, "modules/uncertainty", sep = "")
"meta.analysis" = paste(devhome, "modules/meta.analysis", sep = "")
"db" = paste(devhome, "db", sep = "")
)

Now, devtools can take pkg as an argument instead of /path/to/pkg/, e.g. so you can use build("pkg") instead of build("/path/to/pkg/")

Package Data