Repository files navigation

Theskylight package returns sky illuminance parameters for both the sun andthe moon, for a given date/time and location. In addition, ancillaryparameters such as sun and moon azimuth and altitude are provided. The code isan almost verbatim transcription of the work by Janiczek and DeYoung (1987),published in the US Naval observatory circular. An online copy of thismanuscripts can be found on the internet archive(https://archive.org/details/DTIC_ADA182110).

Very few adjustments to the original code where made to ensure equivalency inresults. As such, most of the naming of the subroutines and variables wasretained. However, some changes were made to the main routine and subroutinesto ensure vectorization of the code to speed up batch processing of data.

With time more detailed information will be added to all functions, includingreferences to subroutine functions and more transparent variable names, whilelimiting variable recycling (a common practice in the original code base).The code delivers equivalent results with the programme certification valuespublished in Table A of Janiczek and DeYoung (1987), as such all originallimitations remain (see below).

Hufkens, K. et al. (2023) ‘Evaluating the effects of moonlight on the vertical flight profiles of three western palaearctic swifts’. Royal Society Proceedings B. doi: 10.1098/rspb.2023.0957, in addition reference the original work by Janiczek and DeYoung (1987, see below)

The sky illuminance model by Janiczek and DeYoung (1987) inskylight has some limitations:

• Design specifications aimed for 0.5 degrees in angle, or two minutes of times. Last digits should be considered uncertain by one unit.
• At latitudes less than 60 degrees, the model should agree with more refined calculations to within one or two minutes of time. For latitudes above this value the model can produce errors of up to four minutes.
• In some circumstances calculated illuminance values might differ from real lightlevels of a factor 10 or more.
• Strong coherence and proper time keeping is required, there is a strong requirementto provide dates in GMT, corrections based upon latitude (not civil time zone) shouldbe executed before processing. No warnings are provided.

Yet, overall the model should provide a fast approximation where more computationally expensive models would only provide marginal benefits for most applications.For a full description of the model I refer to Janiczek and DeYoung (1987).

To install the current stable release use a CRAN repository:

install.packages("skylight")library("skylight")

To install the development releases of the package run the followingcommands:

if(!require(remotes)){install.packages("remotes")}remotes::install_github("bluegreen-labs/skylight")library("skylight")

Vignettes are not rendered by default, if you want to include additionaldocumentation please use:

if(!require(remotes)){install.packages("remotes")}remotes::install_github("bluegreen-labs/skylight",build_vignettes=TRUE)library("skylight")

skylight values can be calculated for a single point and date using the below call. This will generate a data frame with model values.

# load the librarylibrary(skylight)# calculate sky illuminance values for# a single date/time and locationdf<- skylight(longitude=-135.8,latitude=-23.4,date= as.POSIXct("1986-12-18 21:00:00",tz="GMT"),sky_condition=1    )

The skylight function is vectorized, so you can provide vectors of input parameters instead of using a loop and the above function call.

# Generate a dataset with 15 minute values# for approximately two monthsinput<-data.frame(longitude=0,latitude=50,date=  as.POSIXct("2020-06-18 00:00:00",tz="GMT")+ seq(0,60*24*3600,900),sky_conditions=1)# calculate sky illuminance values for# a single date/time and locationdf<- skylight(input$longitude,input$latitude,input$date,1    )# previous results are of the same dimension (rows)# as the input data and can be bound together# for easy plottinginput<- cbind(input,df)

Plotting this data results in

skylight supports piped data frames with appropriatedly named columns as inputto the function. This allows for fast processing of large data frames, with theadded advantage that input parameters are returned with the calculated data.

Note that you need a data frame with the three most basic parameters:

• longitude
• latitude
• datenamed as such (all lower case). The function will complain if it doesn'tfind the required column names. Also note that due to the priority of thepiped construction over the other parameters all parameters should be namedwhen calling the function in a conventional way.

# recreating the data frame with parameters# as beforeinput<-data.frame(longitude=0,latitude=50,date=  as.POSIXct("2020-06-18 00:00:00",tz="GMT")+ seq(0,1*24*3600,1800),sky_condition=1)# but now using the piped approach to calculate# all valuesdf<-input|> skylight()

The current code, using the vectorized piped approach, is sufficiently fast tosupport larger data sets. For example a more advanced cloud cover correction isdescribed in the vignettes and taking this analysis as inspiration animationsof illuminance can be made (as shown below).

Theskylight package is distributed under a AGPLv3 license, while the skylight model code resides in the public domain made available by Janiczek and DeYoung (1987). The logo is in part based upon Emoji One v2.0 iconography.

• Janiczek and DeYoung (1997).Computer Programs for Sun andMoon Illuminance With Contingent Tables and Diagrams,US Naval observatory circular nr. 171, 1987