Looking at RHESSys output - RHESSys/RHESSys GitHub Wiki
These instructions apply to working with RHESSys output in the program R
This is for use with Legacy (standard) output
Read in RHESSys Output R function
Requirements & Installation
About the readin_rhessys_output function
How to use the readin_rhessys_output R function
Three dimensional array format
Requirements and installation
- R chron package
Include the following new functions in your R workspace
- mkdate (dependency) (and must have the chron R package loaded to use)
- cal.wyd (dependency)
- readin_rhessys_output
- rhessys_diff
Some different methods to get these functions into the R workspace:
- Install the RHESSysIOinR package (Recommended method)
following the same installation procedure as for the RHESSysPreprocessing package - Run the array.R script text file from within your R workspace to run all the commands within it and create the new functions, i.e.:
In Rstudio, open the array.R script and use the source button to run the contents of the active document
In R, at the command line type: source(“array.R”) - Mac users also have the option - Paste all the commands in the array.R text file into your .Rprofile text file (located in your user directory), so the functions load/are included automatically every time you start R
- Copy each of the functions (either from the array.R text file or from the links above) and paste them into your R workspace
About
This function only works with daily output.
Output for all levels of the spatial hierarchy can be read into the same three-dimensional array, i.e. the array can contain basin, hill, zone, patch, stratum, and growth output in the same R object. In addition to all the daily output variables included in RHESSys output files, the readin_rhessys_output function also automatically computes some of the variables users often need, and it also assigns a date variable to each object in the array, and aggregates the daily data by water year (wy) and water year day (wyd).
By default, the function readin_rhessys_output reads in basin.daily and grow_basin.daily RHESSys output files. The function recognizes 1 as ON and 0 as OFF, and by default, basin and basin growth RHESSys output are set to 1, or ON, and all other levels set to 0, or OFF. If you do not have basin growth output, you must then set growth to 0 (off).
e.g. by default:
- Basin: b=1 (on by default)
- Growth: g=1 (on by default - if you don't have growth output - you must turn it off, g=0)
- Hillslope: h=0
- Zone: z=0
- Patch: p=0
- Stratum: c=0
If you want to include another level of spatial output, you would set that level to 1 as well (e.g. to also read in canopy strata output, set c=1). If you don’t have growth output, you would set growth to 0 (i.e. g=0).
The readin_rhessys_output function only requires the prefix of your output files as input. It automatically looks for the RHESSys defined extensions (i.e. basin.daily, grow_basin.daily, etc…)
For a list of variables that are included within the different (raw) RHESSys output files, see RHESSys output options
Using the function readin rhessys output
R> new_array = readin_rhessys_output(“prefix_name_of_output”)
Examples – if the prefix name of your RHESSys output is ‘hja.base’ (i.e. your output is hja.base_basin.daily) to create a new R array called base:
R> base = readin_rhessys_ouptut(“hja.base”)
This would read in the basin and basin growth output files by default.
If you wanted to also read in patch and stratum ouput:
R> base = readin_rhessys_ouptut(“hja.base”, p=1, c=1)
If you don’t have growth output to read in:
R> base = readin_rhessys_ouptut(“hja.base”, g=0)
This creates a new three-dimensional array called ‘base’.
This three-dimensional array has a predetermined naming convention for the objects contained within:
- Basin daily = bd
- Basin daily growth = bdg
- Hillslope daily = hd
- Hillslope daily growth = hdg
- Zone daily = zd
- Zone daily growth = zdg
- Patch daily = pd
- Patch daily growth = pdg
- Canopy stratum daily = cd
- Canopy stratum daily growth = cdg
- Water year aggregation = appended by .wy (i.e. bd.wy)
- Water year day aggregation = appended by .wyd (i.e. bd.wyd)
- The first letter indicates the spatial level (b for basin, p for patch, etc...)
- the second letter indicates the temporal level (d for daily). Right now this function is just set up for daily output (not hourly/monthly/yearly).
- If there is a third letter "g", this indicates growth output for the associated spatial level
- The function also automatically aggregates daily data by water year (wy) and water year day (wyd) and creates new objects in the array appended by an abbreviation for the level of aggregation (i.e. bd.wy = basin daily aggregated by wateryear).
Three dimensional array format
Array_name$object_name$variable_name
Following the previous example:
Array_name = base
Object_name = bd, bdg, bd.wy, etc...
Variable_name = lai, streamflow, npp, etc... (RHESSys variable names in raw RHESSys output)
The variables (i.e. lai, streamflow) are within each individual object (i.e. basin.daily output or bd; grow_basin.daily output or bdg) that are within the array (i.e. base) that you created in R when the function readin_rhessys_output was run.
Examples:
base$bd$lai = leaf area index results from basin daily output
base$pdg$soil_resp = soil respiration from patch daily growth output
To view the objects within the three-dimension array named ‘base’:
R> names(base)
This will just return all the possible objects within the array called 'base' – so you will see object names for all the possible levels, even those objects that will be empty because you did not read in that type of output (i.e. you will see cdg listed even though you didn’t read in canopy_stratum daily growth output).
To view the variables within the objects within the three-dimensional array:
R> head(base$bd) or names(base$bd)
So – essentially you are just using the same R commands you already know, giving the command (i.e. head), followed by the array name (base$) and the object you are interested in (bd). So instead of
R> head(bd) it would be R> head(base$bd)
incorrect correct
To work with just a particular variable:
R> head(base$bd$lai)
R> plot(base$bd$lai, type=”l”)
You will see that there are some additional variables other than just the default RHESSys output variables. This new function automatically creates some of the variables users often need:
In bd: ET, unfilled_cap
In bdg: porosity, veg_awc
In cdg: woodc, plantc
It also assigns a date variable to each object in the array, and aggregates by water year (wy) and water year day (wyd). (You must have the mkdate function in your R workspace). This creates new temporal objects within the array for each level of the spatial hierarchy, i.e.
bd.wy (basin daily aggregated by wateryear) and
bdg.wyd (basin daily growth aggregated by water year day).
For example:
R> head(base$bdg.wy)
R> plot(base$bdg.wy$soiln, type=”l”)
R function rhessys diff
The function rhessys_diff calculates the difference between objects within arrays.
If you have two arrays, i.e. a baseline scenario and one where the temperature was increased by 2 degrees (i.e. base and T2):
R> base = readin_rhessys_output(“hja.base”)
R> T2 = readin_rhessys_output(“hja.T2”)
Then you could use the function rhessys_diff to calculate the differences in the output (you supply the function rhessys_diff with the names of the two arrays you want to calculate the difference for):
R> change = rhessys_diff(base, T2)
Look at the output in the new array called change:
R> names(change)
R> head(change$bd)
R> plot(change$bd$streamflow)