| Title: | Silhouette to Area Ratio of Tilted Surfaces |
|---|---|
| Description: | Implementation of trigonometric functions to calculate the exposure of flat, tilted surfaces, such as leaves and slopes, to direct solar radiation. It implements the equations in A.G. Escribano-Rocafort, A. Ventre-Lespiaucq, C. Granado-Yela, et al. (2014) <doi:10.1111/2041-210X.12141> in a few user-friendly R functions. All functions handle data obtained with 'Ahmes' 1.0 for Android, as well as more traditional data sources (compass, protractor, inclinometer). The main function (star()) calculates the potential exposure of flat, tilted surfaces to direct solar radiation (silhouette to area ratio, STAR). It is equivalent to the ratio of the leaf projected area to total leaf area, but instead of using area data it uses spatial position angles, such as pitch, roll and course, and information on the geographical coordinates, hour, and date. The package includes additional functions to recalculate STAR with custom settings of location and time, to calculate the tilt angle of a surface, and the minimum angle between two non-orthogonal planes. |
| Authors: | Agustina Ventre Lespiaucq [aut, cre], Silvia Santamaria Bueno [aut] |
| Maintainer: | Agustina Ventre Lespiaucq <[email protected]> |
| License: | AGPL-3 |
| Version: | 1.0 |
| Built: | 2025-02-15 03:08:23 UTC |
| Source: | https://github.com/cran/leafSTAR |
Application for smartphones that allows to characterize the 3-dimensional position of flat surfaces. It measures four position angles, namely pitch, roll, azimuth and course relative to the Earth's magnetic and gravitational fields using the integrated sensors of the cell phone. The latest version is 'Ahmes' 1.0 and runs under Android 2.2 or later version.
AhmesAhmes
An object of class character of length 1.
The details of 'Ahmes' are described in Escribano-Rocafort et al. (2014).
Ahmes 1.0 https://play.google.com/store/apps/details?id=com.movil.hoja.movihoja.ahmes&hl=en
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.
Calculate the minimum angle between two non-orthogonal planes, such as the angle describing leaf torsion, the angle between two halves of conduplicate or plicate leaves, the angle between the petiole and the branch, between two leaves and between two branches.
dihedral(plane1, plane2, Ahmes = FALSE, ID = NULL, pitch1, roll1, course1, pitch2, roll2, course2, horiz = TRUE)dihedral(plane1, plane2, Ahmes = FALSE, ID = NULL, pitch1, roll1, course1, pitch2, roll2, course2, horiz = TRUE)
plane1, plane2
|
Objects of class data.frame containing the angles of plane1 and plane2 and row labels. |
Ahmes |
Logical. Do data come from 'Ahmes'? Defaults to FALSE |
ID |
An optional vector with the labels of the observations. Defaults to |
pitch1, pitch2
|
Numeric. The name of the variables containing the pitch angles of planes 1 and 2 in degrees. See details. |
roll1, roll2
|
Numeric. The name of the variables containing the roll angles of planes 1 and 2 in degrees. See details. |
course1, course2
|
Numeric. The name of the variables containing the course angles of planes 1 and 2 in degrees. See details. |
horiz |
Logical. Set the position of the start (zero, 0) of pitch, roll and tilt angle data. |
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 of leaf angles, see Fig. 2 in Escribano-Rocafort et al. (2014).
Agustina Ventre-Lespiaucq and Silvia Santamaria Bueno.
dihedral Santalo, L.A. (1970). Vectores y tensores con sus aplicaciones. p. 61, 8 Edicion. EUDEBA (eds), Buenos Aires, Argentina.
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.
orchids Ventre-Lespiaucq, A.B., Delgado, J.A., Ospina-Calderon, N.H., Otero, J.T., Escudero, A., Sanchez, M.A., Balaguer, L., Flanagan, N.S. (2017). A tropical epiphytic orchid uses a low-light interception strategy in a spatially heterogeneous light environment. Biotropica, 49:318-327. doi:10.1111/btp.12425.
data(orchids) pseudobulbs<-subset(orchids,organ=="pseudobulb") #subset leaves<-subset(orchids,organ=="leaf") dihedral(plane1=pseudobulbs,plane2=leaves,Ahmes=FALSE,ID=NULL,pitch1=pseudobulbs$pitch, roll1=pseudobulbs$roll,course1=pseudobulbs$course,pitch2=leaves$pitch,roll2=leaves$roll, course2=leaves$course,horiz=FALSE) #dihedral()data(orchids) pseudobulbs<-subset(orchids,organ=="pseudobulb") #subset leaves<-subset(orchids,organ=="leaf") dihedral(plane1=pseudobulbs,plane2=leaves,Ahmes=FALSE,ID=NULL,pitch1=pseudobulbs$pitch, roll1=pseudobulbs$roll,course1=pseudobulbs$course,pitch2=leaves$pitch,roll2=leaves$roll, course2=leaves$course,horiz=FALSE) #dihedral()
Convert the output of 'Ahmes' 1.0 to a dataframe that can be handled by 'leafSTAR' and 'R' in general.
fixfile(x)fixfile(x)
x |
The output of 'Ahmes' 1.0. A .csv file |
This function does not modify the original dataset. To have a permanent fixed version of the data, see Example. If using the new data within the package, be aware that the argument Ahmes should be set to FALSE.
Agustina Ventre-Lespiaucq and Silvia Santamaria Bueno.
data(olea) olea_fixed<-fixfile(olea) ## Store the fixed file as a new object. #fixfile()data(olea) olea_fixed<-fixfile(olea) ## Store the fixed file as a new object. #fixfile()
Convert the hour from sexagesimal character to decimal numeric format.
fixhour(x, seconds = FALSE)fixhour(x, seconds = FALSE)
x |
A character vector with the hour expressed as sexagesimal characters HH:MM or HH:MM:SS. |
seconds |
Logical. Is the hour expressed as HH:MM:SS ( |
Silvia Santamaria Bueno.
datahours<-c("00:30","10:00","18:20","20:55") datahours_fixed<-fixhour(datahours,seconds=FALSE) #fixhour()datahours<-c("00:30","10:00","18:20","20:55") datahours_fixed<-fixhour(datahours,seconds=FALSE) #fixhour()
The guava data frame has 239 rows and 11 columns
guavaguava
This data frame contains the following columns:
tree.ID Identification of the tree.
leaf.ID Identification of the leaf.
measure.ID Number of observation (from 'Ahmes').
sector Sector of the tree where leaf data was collected, with five levels corresponding to the north, east, south, and west sectors of the crown base (1N, 2E, 3S, 4W, respectively) and the top crown sector (5A).
azimuth Azimuth angle in degrees.
pitch Pitch angle in degrees.
roll Roll angle in degrees.
course Course angle in degrees with the zero placed at South (old 'Ahmes' version)
LA.cm2 Leaf area.
tilt.degrees Tilt angle calculated from pitch and roll with a changed reference system (horiz = T).
course.degrees Course angle in degrees with the zero placed at North (latest 'Ahmes' version 1.0).
These data are measurements of four leaf position angles of 239 leaves in five guava trees (Psidium guajava), each leaf in a row. guava is an object of class data.frame and results from applying the function fixfile to the output of an earlier version of 'Ahmes', where the reference for course was placed at South.
guava Ventre-Lespiaucq, A., et al. Unpublished data.
Ahmes 1.0 https://play.google.com/store/apps/details?id=com.movil.hoja.movihoja.ahmes&hl=en
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.
The olea data frame has 24 rows and 15 columns
oleaolea
This data frame contains the following columns:
Num.Medida Number of observation.
Cabeceo Pitch angle in degrees.
Alabeo Roll angle in degrees.
Azimuth Azimuth angle in degrees.
Rumbo Course angle in degrees.
Estado_Brujula Compass_State. The values depend on the sensors of each cell phone.
Estado_Acelerometro Accelerometer_State. The values depend on the sensors of each cell phone.
Estado_Campo_Magnetico Magnetic_Field_State. The values depend on the sensors of each cell phone.
Fecha Date. Note this is a date-hour column. See details.
Hora Hour. Instead of the hour, it contains the values of the next column. See details.
Bateria Battery. State of the battery.
Temperatura Temperature. Only available when using temperature sensors coupled to the cell phone.
Presion Pressure. Only available when using pressure sensors coupled to the cell phone.
Error_Relativo Relative error. See Escribano-Rocafort et al. (2014).
Empty column
These data are measurements of four leaf position angles of 20 leaves in an olive tree (Olea europaea), each leaf in a row. The format of the data is an example of the raw output from 'Ahmes' 1.0. olea is a .csv file. This file presents some issues that need to be corrected. There are four extra rows to be deleted (1:3, final row). The hour and date are in the same colum, which needs to be separated in order to extract hour and date information directly from the data. This makes column headers to be displaced from columns 10 to 15. In addition, the headers of the output of Ahmes are provided in Spanish. Function fixfile implements solutions to these issues and renames the variables in English.
olea Ventre-Lespiaucq, A., Santamaria Bueno, S., unpublished data.
Ahmes 1.0 https://play.google.com/store/apps/details?id=com.movil.hoja.movihoja.ahmes&hl=en
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.
The olive data frame has 20 rows and 10 columns
oliveolive
This data frame contains the following columns:
location Where measurements were taken.
latitude Latitude where measurements were taken, in decimal format.
longitude Longitude where measurements were taken, in decimal format.
date Date.
hour Hour.
tz UTC time zone. Time zones west of Greenwich should be indicated with a minus sign (e.g., tz = -2).
leaf.ID Identification of the leaf.
tilt Tilt angle measured with a digital clinometer.
course Course angle measured with a compass.
azimuth Azimuth angle measured with a compass.
These data are measurements of three leaf position angles of 20 leaves in an olive tree (Olea europaea), each leaf in a row. This dataset is an example of compass and inclinometer measurements. Tilt was measured instead of pitch and roll. The data.frame includes data on the geographic location, date and time. All these variables can be used directly as arguments in the functions of the star family.
olive Ventre-Lespiaucq, A., Santamaria Bueno, S., unpublished data.
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.
The orchids data.frame has 500 rows and 7 columns
orchidsorchids
This data.frame contains the following columns:
measure.ID Number of observation (from Ahmes).
orchid.ID Identification of the orchid.
organ Tags each observation with "leaf" or "pseudobulb".
module Identifies the leaf-pseudobulb pair.
pitch Pitch angle in degrees.
roll Roll angle in degrees.
course Course angle in degrees.
Subset of the dataset in Ventre-Lespiaucq et al. (2017). These data are measurements of three leaf position angles of 250 leaf-pseudobulb pairs in 84 epiphytic orchids (Rodriguezia granadensis). Each row contains either pseudobulb or leaf angle data.
orchids Ventre-Lespiaucq, A., Delgado, J.A., Ospina-Calderon, N.H., Otero, J.T., Escudero, A., Sanchez, M.A., Balaguer, L., Flanagan, N.S. (2017) A tropical epiphytic orchid uses a low-light interception strategy in a spatially heterogeneous light environment. Biotropica 49:318-327. doi:10.1111/btp.12425.
Ahmes 1.0 https://play.google.com/store/apps/details?id=com.movil.hoja.movihoja.ahmes&hl=en
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.
Retrieves the projected area of the surface in area units.
sal(x, LA)sal(x, LA)
x |
Numeric vector, commonly the output of functions of the |
LA |
Numeric vector containing the total area of the surface of each observation. |
Agustina Ventre-Lespiaucq and Silvia Santamaria Bueno.
SAL can be calculated with STAR data coming from star, simu.star, star.app, and simu.star.app
data(guava) ## Calculate SAL for a given location, date and time gua<-star(guava,lat=40.82,long=-4.21,local.time=12,tz=1, Ahmes=FALSE,ID=NULL,pitch=guava$pitch,roll=guava$roll, horiz=FALSE,course=guava$course,date=30,o.format=NULL) sal(gua,LA=guava$LA.cm2) ## Calculate SAL from simu.star() sim.gua<-simu.star(guava,lat=40.82,long=-4.21,local.time=12,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=30,c.lat=40.8,c.long=-4.2,c.tz=1, LA=guava$LA.cm2,details=TRUE) sal.guava<-sal(sim.gua$STAR,LA=sim.gua$LA) #sal()data(guava) ## Calculate SAL for a given location, date and time gua<-star(guava,lat=40.82,long=-4.21,local.time=12,tz=1, Ahmes=FALSE,ID=NULL,pitch=guava$pitch,roll=guava$roll, horiz=FALSE,course=guava$course,date=30,o.format=NULL) sal(gua,LA=guava$LA.cm2) ## Calculate SAL from simu.star() sim.gua<-simu.star(guava,lat=40.82,long=-4.21,local.time=12,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=30,c.lat=40.8,c.long=-4.2,c.tz=1, LA=guava$LA.cm2,details=TRUE) sal.guava<-sal(sim.gua$STAR,LA=sim.gua$LA) #sal()
Recalculate the percentage of potential exposure of flat, tilted surfaces to direct solar radiation with different custom settings of location and time.
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)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)
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, |
long |
A vector with the longitude of each observation in decimal format. If all observations correspond to the same longitude, |
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 |
tz |
A vector with the time zone of each observation. If all observations correspond to the same time zone, |
Ahmes |
Logical. Do data come from 'Ahmes' 1.0? Defaults to |
ID |
An optional vector with the labels of the observations. Defaults to |
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. |
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 |
A character indicating the date format in the input data. It is similar to the argument |
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 |
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, |
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 |
details |
Logical. If ( |
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.
Agustina Ventre-Lespiaucq and Silvia Santamaria Bueno.
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.
# 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()# 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()
This is a version of simu.star function that only works with the output of 'Ahmes' 1.0. simu.star.app() re-calculates the percentage of potential exposure of flat, tilted surfaces to direct solar radiation with different custom settings of location and time.
simu.star.app(x, lat, long, tz, o.format = NULL, c.hour = NULL, c.date = NULL, c.long = NULL, c.lat = NULL, c.tz = NULL, LA = NULL, details = FALSE)simu.star.app(x, lat, long, tz, o.format = NULL, c.hour = NULL, c.date = NULL, c.long = NULL, c.lat = NULL, c.tz = NULL, LA = NULL, details = FALSE)
x |
Output of 'Ahmes' 1.0. A .csv file. |
lat |
A vector with the latitude of each observation in decimal format. If all observations correspond to the same latitude, |
long |
A vector with the longitude of each observation in decimal format. If all observations correspond to the same longitude, |
tz |
A vector with the time zone of each observation. If all observations correspond to the same time zone, |
o.format |
A character indicating the date format in the input data. It is similar to the argument |
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 |
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, |
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 |
details |
Logical. If ( |
This function calls fixfile internally before calculating STAR. However, it does not modify the original dataset. To have a permanent fixed version of the data, use new.file<-fixfile(your.data). If using new.file within the package, be aware that the argument Ahmes should be set to FALSE.
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 of the Ahmes family solve date issues internally.
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.
Agustina Ventre-Lespiaucq and Silvia Santamaria Bueno.
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.
data(olea) simustar_olea<-simu.star.app(olea,lat=40,long=4,tz=2, c.hour=c(8,12,18),c.date=c(1,60,120,180,240)) #simu.star.app()data(olea) simustar_olea<-simu.star.app(olea,lat=40,long=4,tz=2, c.hour=c(8,12,18),c.date=c(1,60,120,180,240)) #simu.star.app()
Calculate the percentage of potential exposure of flat, tilted surfaces to direct solar radiation. It is equivalent to the ratio of the surface projected area to total surface area, but instead of using area data it uses spatial position angles (pitch, roll and course or tilt and course), geographical coordinates, hour and date information. This function implements equation 3 in Escribano-Rocafort et al. (2014).
star(x, lat, long, local.time = NULL, tz, Ahmes = F, ID = NULL, pitch = NULL, roll = NULL, horiz = T, tilt.ang = NULL, course = NULL, date = NULL, o.format = NULL)star(x, lat, long, local.time = NULL, tz, Ahmes = F, ID = NULL, pitch = NULL, roll = NULL, horiz = T, tilt.ang = NULL, course = NULL, date = NULL, o.format = NULL)
x |
A dataframe with observations in the rows and at least two spatial position angles in the columns (see Details). Data can either come 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, |
long |
A vector with the longitude of each observation in decimal format. If all observations correspond to the same longitude, |
local.time |
A numeric vector with the approximate local time of each observation in decimal format. Hours 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 |
tz |
A vector with the time zone of each observation. If all observations correspond to the same time zone, |
Ahmes |
Logical. Do data come from 'Ahmes' 1.0? Defaults to |
ID |
An optional vector with the labels of the observations. Defaults to |
pitch |
A vector with pitch angles in degrees. See details. |
roll |
A vector with roll rotation angles in degrees. See details. |
horiz |
Logical. Set the position of the start (zero, 0) of pitch, roll and tilt angle data. |
tilt.ang |
A vector with tilt angles in degrees. Tilt is calculated from |
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 |
A character indicating the date format in the input data. It is similar to the argument |
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 of 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).
Agustina Ventre-Lespiaucq and Silvia Santamaria Bueno.
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.
## Example with an 'Ahmes'-type input data(olea) star_olea<-star(olea,lat=40,long=4,tz=2,Ahmes=TRUE) # Add results to the original dataset olea1<-fixfile(olea) # Fix the original dataset olea2<-cbind(olea1,as.data.frame(star_olea)) # Example with an input different to 'Ahmes' data data(olive) star_olive<-star(olive,lat=olive$latitude,long=olive$longitude, local.time=olive$hour,tz=olive$tz, Ahmes=FALSE, ID=olive$leafID,tilt.ang=olive$tilt,horiz=TRUE, course=olive$course,date=olive$date) # Add results to the original dataset. olive2<-cbind(olive,as.data.frame(star_olive)) # Since it does not # come from 'Ahmes', # it is not necessary # to run fixfile(). ## Input date formats. The three examples give the same result. # 1. With Julian date julian_olive<-star(olive,lat=olive$latitude,long=olive$longitude, local.time=olive$hour,tz=olive$tz, Ahmes=FALSE,ID=olive$leafID,tilt.ang=olive$tilt,horiz=TRUE, course=olive$course,date=25) # January 25th # 2. With standard date std_olive<-star(olive,lat=olive$latitude,long=olive$longitude, local.time=olive$hour,tz=olive$tz, Ahmes=FALSE,ID=olive$leafID,tilt.ang=olive$tilt,horiz=TRUE, course=olive$course,date="2017/01/25") # January 25th 2017. # Date should be quoted. o.format is not needed. # 3. With non-standard date nonstd_olive<-star(olive,lat=olive$latitude,long=olive$longitude, local.time=olive$hour,tz=olive$tz, Ahmes=FALSE, ID=olive$leafID,tilt.ang=olive$tilt,horiz=TRUE, course=olive$course,date="25/01/2017",o.format="%d/%m/%Y") # January 25th 2017. Date should be quoted. o.format is necessary. # star()## Example with an 'Ahmes'-type input data(olea) star_olea<-star(olea,lat=40,long=4,tz=2,Ahmes=TRUE) # Add results to the original dataset olea1<-fixfile(olea) # Fix the original dataset olea2<-cbind(olea1,as.data.frame(star_olea)) # Example with an input different to 'Ahmes' data data(olive) star_olive<-star(olive,lat=olive$latitude,long=olive$longitude, local.time=olive$hour,tz=olive$tz, Ahmes=FALSE, ID=olive$leafID,tilt.ang=olive$tilt,horiz=TRUE, course=olive$course,date=olive$date) # Add results to the original dataset. olive2<-cbind(olive,as.data.frame(star_olive)) # Since it does not # come from 'Ahmes', # it is not necessary # to run fixfile(). ## Input date formats. The three examples give the same result. # 1. With Julian date julian_olive<-star(olive,lat=olive$latitude,long=olive$longitude, local.time=olive$hour,tz=olive$tz, Ahmes=FALSE,ID=olive$leafID,tilt.ang=olive$tilt,horiz=TRUE, course=olive$course,date=25) # January 25th # 2. With standard date std_olive<-star(olive,lat=olive$latitude,long=olive$longitude, local.time=olive$hour,tz=olive$tz, Ahmes=FALSE,ID=olive$leafID,tilt.ang=olive$tilt,horiz=TRUE, course=olive$course,date="2017/01/25") # January 25th 2017. # Date should be quoted. o.format is not needed. # 3. With non-standard date nonstd_olive<-star(olive,lat=olive$latitude,long=olive$longitude, local.time=olive$hour,tz=olive$tz, Ahmes=FALSE, ID=olive$leafID,tilt.ang=olive$tilt,horiz=TRUE, course=olive$course,date="25/01/2017",o.format="%d/%m/%Y") # January 25th 2017. Date should be quoted. o.format is necessary. # star()
This is a version of star() function that only works with the output of 'Ahmes' 1.0. This function calculates the percentage of potential exposure of flat, tilted surfaces to direct solar radiation. It is equivalent to the ratio of the surface projected area to total surface area, but instead of using area data it uses spatial position angles (pitch, roll and course or tilt and course), geographical coordinates, hour and date information. This function implements equation 3 in Escribano-Rocafort et al. (2014).
star.app(x, lat, long, tz)star.app(x, lat, long, tz)
x |
Output of 'Ahmes' 1.0, a .csv file. |
lat |
A vector with the latitude of each observation in decimal format. If all observations correspond to the same latitude, |
long |
A vector with the longitude of each observation in decimal format. If all observations correspond to the same longitude, |
tz |
A vector with the time zone of each observation. If all observations correspond to the same time zone, |
This function calls fixfile internally before calculating STAR. However, it does not modify the original dataset. To have a permanent fixed version of the data, use new.file<-fixfile(your.data). If using new.file within the package, be aware that the argument Ahmes should be set to FALSE.
Agustina Ventre-Lespiaucq and Silvia Santamaria Bueno.
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.
data(olea) starapp_olea<-star.app(olea,lat=40,long=4,tz=2) ## Add results to the original dataset olea1<-fixfile(olea) ## Fix the original dataset olea2<-cbind(olea1,as.data.frame(starapp_olea)) #star.app()data(olea) starapp_olea<-star.app(olea,lat=40,long=4,tz=2) ## Add results to the original dataset olea1<-fixfile(olea) ## Fix the original dataset olea2<-cbind(olea1,as.data.frame(starapp_olea)) #star.app()
Calculate the tilt angle of a tilted surface from pitch and roll angles.
tilt(x, Ahmes = F, ID = NULL, pitch, roll, horiz = T)tilt(x, Ahmes = F, ID = NULL, pitch, roll, horiz = T)
x |
A dataframe with observations in the rows and at least two spatial position angles in the columns. Data can come either from 'Ahmes' 1.0 or from measurements performed with traditional instrumentation. |
Ahmes |
Logical. Do data come from 'Ahmes'? Defaults to FALSE. |
ID |
An optional vector with the labels of the observations. Defaults to |
pitch |
A vector with pitch angles in degrees. See details. |
roll |
A vector with roll angles in degrees. See details. |
horiz |
Logical. Set the position of the start (zero, 0) of pitch, roll and tilt angle data. |
The output of tilt() is a matrix with two columns "tilt.raw" and "tilt". "tilt.raw" contains tilt values relative to the zenith. "tilt" contains tilt values relative to the horizon. The latter are used in the equations of the star() family. When horiz = T, "tilt" = "tilt.raw".
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 180 refers to the flat vertical surface and 90 refers to the flat horizontal surface.
roll values span from 0 to 180 degrees.
For a graphical explanation, see Fig. 2 in Escribano-Rocafort et al. (2014).
Agustina Ventre-Lespiaucq and Silvia Santamaria Bueno.
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.
tropical Posada, J.M., Lechowicz, M.J., Kitajima, K. (2009). Optimal photosynthetic use of light by tropical tree crowns achieved by adjustment of individual leaf angles and nitrogen content. Annals of Botany, 103: 795-805. doi:10.1093/aob/mcn265.
# Data comes from 'Ahmes' data(olea) tilt_olea<-tilt(olea,Ahmes=TRUE) # Data comes from other sources data(tropical) tropi_tilt<-tilt(tropical,pitch=tropical$pitch,roll=tropical$roll,horiz=TRUE) tropical2<-cbind(tropical,as.data.frame(tropi_tilt)) # When horiz = TRUE, tilt.raw = tilt! data(guava) tilt_guava<-tilt(guava,pitch=guava$pitch,roll=guava$roll,horiz=FALSE) # horiz = FALSE #tilt()# Data comes from 'Ahmes' data(olea) tilt_olea<-tilt(olea,Ahmes=TRUE) # Data comes from other sources data(tropical) tropi_tilt<-tilt(tropical,pitch=tropical$pitch,roll=tropical$roll,horiz=TRUE) tropical2<-cbind(tropical,as.data.frame(tropi_tilt)) # When horiz = TRUE, tilt.raw = tilt! data(guava) tilt_guava<-tilt(guava,pitch=guava$pitch,roll=guava$roll,horiz=FALSE) # horiz = FALSE #tilt()
The tropical data frame has 41 rows and 4 columns
tropicaltropical
This data frame contains the following columns:
species A code for each species (letters) and individuals (numbers)
environment Factor with three levels of exposure to solar radiation.
pitch Pitch angle in degrees.
roll Roll angle in degrees.
These data are a subset of leaf angle data in Posada et al. (2009) measured with a compass and a protractor. Contains measurements of two leaf position angles of 41 leaves in two individuals of (Castilla elastica) and one of (Ficus insipida), each leaf in a row. The format of the data is an example of a field-data table handled by 'leafSTAR'.
tropical Posada, J.M., Lechowicz, M.J., Kitajima, K. (2009) Optimal photosynthetic use of light by tropical tree crowns achieved by adjustment of individual leaf angles and nitrogen content. Annals of Botany, 103: 795-805. doi:10.1093/aob/mcn265.