simu.star {leafSTAR}

Calculate simulated silhouette to area ratios

Description

Recalculate the percentage of potential exposure of flat, tilted surfaces to direct solar radiation with different custom settings of location and time.

Usage

simu.star(x, lat = NULL, long = NULL, local.time = NULL, tz = NULL,
  Ahmes = F, ID = NULL, pitch, roll, tilt.ang = NULL, horiz = T, course,
  date = NULL, o.format = NULL, c.hour = NULL, c.date = NULL,
  c.long = NULL, c.lat = NULL, c.tz = NULL, LA = NULL, details = TRUE)

Arguments

x

A dataframe with observations in the rows and at least two spatial position angles in the columns (see Details). Data can come either from 'Ahmes' 1.0 or from measurements performed with traditional instrumentation.

lat

A vector with the latitude of each observation in decimal format. If all observations correspond to the same latitude, lat can be introduced directly as a single number (see examples).

long

A vector with the longitude of each observation in decimal format. If all observations correspond to the same longitude, long can be introduced directly as a single number (see examples).

local.time

A numeric vector with the local time of each observation in decimal format. Hours from 00 to 24. Minutes in decimal format, from 0 to 99. E.g., 12:30 should be written as 12.50. If available, seconds should also be specified in decimal format. See fixhour. If all observations correspond to the same local time, local.time can be introduced directly as a single number (see examples).

tz

A vector with the time zone of each observation. If all observations correspond to the same time zone, tz can be introduced directly as a single number. Time zones located at the West of Greenwich are negative, and at the East are positive; e.g., for Colombia, tz = -5; for Reunion Island, tz = 4.

Ahmes

Logical. Do data come from 'Ahmes' 1.0? Defaults to FALSE.

ID

An optional vector with the labels of the observations. Defaults to NULL.

pitch

A vector with pitch angles in degrees. See details.

roll

A vector with roll rotation angles in degrees. See details.

tilt.ang

A vector with tilt angles in degrees. Tilt is calculated from pitch and roll angles. This argument allows to specify tilt directly if available.

horiz

Logical. Set the position of the start (zero, 0) of pitch, roll and tilt angle data. horiz = F indicates the zero is located at zenith. This is the reference system used by Ahmes. horiz = T indicates the start is at the horizon. To use tilt in further calculations (star, sal...), angle data should be expressed in the horizontal reference system (0 = horizon). Defaults to TRUE.

course

A vector with course angles in degrees. See details.

date

A vector containing the date(s) when observations were made. If input data do not come from 'Ahmes', o.format needs to be specified. See details.

o.format

A character indicating the date format in the input data. It is similar to the argument format in the function as.Date{base}. Defaults to NULL. See details and examples.

c.hour

A vector of custom hours of length equal to or greater than 1. Hours in decimal format, from 0 to 24. Minutes in decimal format, from 0 to 99. E.g., 12:30 should be written as 12.50. If available, seconds should also be specified in decimal format. See fixhour. If all observations correspond to the same local time, local.time can be introduced directly as a single number (see examples).

c.date

A vector of custom dates of length equal to or greater than 1.

c.long

A vector of custom longitude coordinates in decimal format.

c.lat

A vector of custom latitude coordinates in decimal format.

c.tz

A vector of custom time zone/s. Time zones located at the West of Greenwich are negative; e.g., for Colombia, c.tz = -5; for Reunion Island, c.tz = 4.

LA

Indicates whether leaf area data needs to be replicated to match the dimensions of the dataframe corresponding to the custom factors (see 'custom settings' in Details). When LA is specified, all the five custom factors (c.hour, c.date, c.lat, c.long, c.tz) need to be specified (i.e., they should be different from NULL). Defaults to NULL. LA does not affect the calculation of STAR. See examples.

details

Logical. If (details =FALSE) the output of simu.star() is a vector with STAR values. If details = TRUE the output is the complete dataset plus a column with STAR values. Defaults to TRUE.

Details

x may also content geographical coordinates and hour and date information.

date Internally the function uses Julian dates. Julian date is the recommended input format. Conversion tables are available at https://landweb.nascom.nasa.gov/browse/calendar.html for leap and regular years.

o.format Needs to be specified if Ahmes = FALSE AND input data format is other than Julian or the default formats handled by as.Date{base} ("%Y/%m/%d" and "%Y-%m-%d"). When Ahmes = TRUE, o.format is not needed because functions from the Ahmes family solve date issues internally.

pitch values span from 0 to 180 degrees. If horiz = TRUE (default) 0 and 180 refer to the flat horizontal surface and 90 refers to the flat vertical surface. If horiz = FALSE 0 and 180 refer to the flat vertical surface and 90 refers to the flat horizontal surface.

roll values span from 0 to 180 degrees.

course values span from 0 (North) to 360 degrees, clockwise. Course is the angle between north and the horizontal projection of a normal vector to the surface.

For a graphical explanation, see Fig. 2 in Escribano-Rocafort et al. (2014).

Custom settings. In the functions of the simu family, the original dataframe is repeated as a block times the number of levels of the custom arguments specified (c.hour, c.date, c.lat, c.long, and c.tz). E.g., if a dataset with 10 observations is to be recalculated at two days of the year, the function will create a new dataframe with 20 rows (10 observation X 2 days). For this reason, LA needs to be specified if the user intends to calculate SAL using the output of simu.star(). In addition, the argument details allows the user to visualize the new dataframe created by the function.

Author(s)

Agustina Ventre-Lespiaucq and Silvia Santamaria Bueno.

References

Escribano-Rocafort, A.G., Ventre-Lespiaucq, A.B., Granado-Yela, C., Lopez-Pintor, A., Delgado, J.A., Munoz, V., Dorado, G.A., Balaguer, L. (2014). Simplifying data acquisition in plant canopies- Measurements of leaf angles with a cell phone. Methods in Ecology and Evolution 5:132-140. doi:10.1111/2041-210X.12141.

See Also

simu.star.app, star

Examples

# With custom vectors from outside of the dataframe
 data(guava)
  myhours<-seq(8,16,0.25) # Create a vector of hours from 8:00 to 16:00 every 15 minutes.
  mydates<-seq(1,365,60) # Create a vector of days from January 1st to December 31st, 
                         # every 60 days.
  myguava<-simu.star(guava,lat=40.8,long=-4.2,local.time=6,tz=1,
           Ahmes=FALSE,ID=NULL,pitch=guava$pitch,roll=guava$roll,
           horiz=FALSE,course=guava$course,date=30,o.format=NULL,
           c.hour=myhours,c.date=mydates,c.long=NULL,c.lat=NULL, 
           c.tz=NULL, LA=NULL)

 # LA is not NULL
  wrong<-simu.star(guava,lat=40.8,long=-4.2,local.time=6,tz=1,
         Ahmes=FALSE,ID=NULL,pitch=guava$pitch,roll=guava$roll,
         horiz=FALSE,course=guava$course,date=30,o.format=NULL,
         c.hour=c(7,9.5,12),c.date=c(0,180),LA=guava$LA.cm2,details=TRUE)
     # Some custom settings are missing. STAR is retrieved as if LA = NULL, 
     # meaning LA data will not be readily available for calculating SAL. 

  correct<-simu.star(guava,lat=40.8,long=-4.2,local.time=6,tz=1,
           Ahmes=FALSE,ID=NULL,pitch=guava$pitch,roll=guava$roll,
           horiz=FALSE,course=guava$course,date=30,o.format=NULL,
           c.hour=c(7,9.5,12),c.date=c(0,180),c.lat=40.8,c.long=-4.2, 
           c.tz=1, LA=guava$LA.cm2,details=TRUE)
     # Returns LA and STAR

 # LA is NULL
  correct1<-simu.star(guava,lat=40.8,long=-4.2,local.time=6,tz=1,
            Ahmes=FALSE,ID=NULL,pitch=guava$pitch,roll=guava$roll,
            horiz=FALSE,course=guava$course,date=30,o.format=NULL,
            c.hour=c(7,9.5,12),c.date=c(0,180),c.long=NULL,c.lat=NULL, 
            c.tz=NULL, LA=NULL,details=TRUE)
          # Is the same as
  correct2<-simu.star(guava,lat=40.8,long=-4.2,local.time=6,tz=1,
            Ahmes=FALSE,ID=NULL,pitch=guava$pitch,roll=guava$roll,
            horiz=FALSE,course=guava$course,date=30,o.format=NULL,
            c.hour=c(7,9.5,12),c.date=c(0,180),details=TRUE)
#simu.star()