RShade-R

The RShade program calculates estimates of effective shade (topographic plus vegetative) based on the methods of Chen et al. (see below). Program code found in the HeatSource model (https://github.com/DEQrmichie/heatsource-9), which updates the Chen method to use a radial sampling technique, was ported to R for this application by Matthew Fuller. Heat Source is a computer model used by the Oregon Department of Environmental Quality to simulate stream thermodynamics and hydraulic routing. Input data required by the RShade program are generated by the R program dmapSMP (https://github.com/USEPA/dmapSMP).

Parameters for method_chen98_parchunk_star()

• If using the dmapSMP program to provide inputs, default values can be used for each of the following except for startdate, ndays, timezone, dlstime, VWidthGlobal, and vegzones.
  VWidthGlobal is set by the distance between points along the star transects and vegzones should be consistent with the number of points along the star transects entered in the dmapSMP program.

• site_data_frame: data frame that holds all the site details necessary for the inputs_fixed_star() function using the other input parameters to prepare a data frame for the actual shade calculations.

• site_id_chr: point or site ID value as text. Numbers can be used, but the format of the column must be set to character or text.

• startdate: start date for integrating shade as a text string "YYYY-MM-DD". If calculating average shade across a month, use first of month as start date value here and use the total number of days in that month in the “ndays” input parameter

• ndays: number of days to integrate/simulate shade starting on 'startdate'. An ndays value of “1” calculates shade for only the start date noted in “startdate” input parameter. To simulate shade for the entire month of August 2012 enter 'startdate = "2012-08-01" ‘ and “ndays = 31” for 31 days in August.

• timezone: Time zone is the difference between UTC and the local standard time in hours. A map of world time zones may be found at: http://aa.usno.navy.mil/graphics/TimeZoneMap2001.pdf. PST is -8 for the Pacific Northwest, USA.

• dlstime: is a daylight savings time indicator variable where you Select '1' if you want times calculated and reported as local daylight savings time or "0" to report times in local standard time.

• VWidthGlobal: Each of the 9 riparian vegetation zones on each bank are assumed to have the same width (meters) as specified here. Set to “NA” if zone widths are variable in width for the shade estimates.

• JsntMethod: Select the solar model to generate input radiation. options to select from are: 0="Bras" 3="ODEQ" 4="Ryan-Stolz"

• cloudfrac_global: global value for cloud fraction of total incoming energy that will be applied to all times. If continuous hourly values are entered in the site_data_frame, then they override this global value. Value must be between 0 and 1.

• vegzones: is the number of vegetation zones that are being applied in the shade calculations as text or a character value. For example, if the shade calculations are estimating shade using a 50m wide riparian vegetation buffer that has 10m wide zones to assess variation in riparian vegetation, then there will be five total vegetation zones in the shade calculations that are each 10m wide (vegzones = “5”).

• star_veg: TRUE/FALSE input parameter. If TRUE, then use the 8-direction star sampling of vegetation height and canopy density for shade calculations. If FALSE, then use a 3-direction (East, South, West) sampling of vegetation height and canopy density.

• ripgelev: TRUE/FALSE input parameter. If TRUE, the ground elevation (meters) of each vegetation zone has been entered into the “site_data_frame” with a column header including the “grndelevVZ” text for tracking. If FALSE, then the ground elevation for each vegetation zone is the sum of the channel elevation and the incision value at each site.

• nfac: Atmospheric turbidity factor for calculation of solar radiation that is used if the Bras option for the solar radiation model is selected. [2 = clear, 5 = smog]

• atc: Atmospheric transmission factor for calculation of solar radiation used if the Ryan-Stolzenbach option for 'JsntMethod' is selected.

Outputs

“effshd_TV”: effective shade percent from just vegetation and topography

“effshd_TVR”: effective shade percent from vegetation, topography, and accounting for light reflection from water surface (i.e., energy loss from water due to energy reflecting away from stream at water surface).

“Solar_FLUX_above”: The solar flux before any shade from vegetation or topography is applied and before any reflection from the water surface is accounted for.

“Solar_FLUX_below”: Solar flux after shade from topography and vegetation is applied, but before reflection from water surface is accounted for.

“Solar_FLUX_inh2o”: Solar flux entering the stream after vegetation and topographic shading are applied and reflection from stream surface (albedo) is accounted for.

See Chen et al. 1998 page 312 EQ 21 for details.

---

Create package file

• Go to the directory that contains the directory of this README. (It the parent directory of the directory "EPAShader".)

• Run the shell command R CMD build RShade. For example:

RShade> cd ..
r-packages> R CMD build EPAShader

---

Installation

From local directory

install.packages(<path/to/package/folder>, repos = NULL, type="source")

Of, if you have (and prefer) the package devtools:

devtools::install(<path/to/package/folder>)

Using .tar.zip file

• Copy the tar/zip file "EPAShader_x.x.x.tar.zip".

  • If you do not have that zip file see above how to create it.

• Install the R package RShade using Terminal:

R CMD INSTALL RShade_x.x.x.tar.gz 

References

[YDC1] Boyd, M., and Kasper, B. 2003. Analytical methods for dynamic open channel heat and mass transfer: Methodology for heat source model Version 7.0. https://www.oregon.gov/deq/FilterDocs/heatsourcemanual.pdf

[YDC2] Chen, Y.D. (1996). Hydrologic and water quality modeling for aquatic ecosystem protection and restoration in forest watersheds: a case study of stream temperature in the Upper Grande Ronde River, Oregon. PhD dissertation. University of Georgia. Athens, GA.

[YDC3] Chen, Y.D., Carsel, R.F., McCutcheon, S.C., and Nutter, W.L. (1998). "Stream temperature simulation of forested riparian areas: I. watershed-scale model development", Journal of Environmental Engineering. April 1998. pp 304-315.

[YDC4] Chen, Y.D., Carsel, R.F., McCutcheon, S.C., and Nutter, W.L. (1998). "Stream temperature simulation of forested riparian areas: II. model application", Journal of Environmental Engineering. April 1998. pp 316-328.

Disclaimer: The United States Environmental Protection Agency (EPA) GitHub project code is provided on an "as is" basis and the user assumes responsibility for its use. EPA has relinquished control of the information and no longer has responsibility to protect the integrity, confidentiality, or availability of the information. Any reference to specific commercial products, processes, or services by service mark, trademark, manufacturer, or otherwise, does not constitute or imply their endorsement, recommendation or favoring by EPA. The EPA seal and logo shall not be used in any manner to imply endorsement of any commercial product or activity by EPA or the United States Government.