skylight use

Koen Hufkens

2023-11-04

# check version number
process <- as.numeric(version$major) + as.numeric(version$minor)/10 > 4.2

Single date/time and location

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 library
library(skylight)

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

print(df)
#>   sun_azimuth sun_altitude sun_illuminance moon_azimuth moon_altitude
#> 1         346      89.9565        123786.3          282     -61.99004
#>   moon_illuminance moon_fraction total_illuminance
#> 1     1.066142e-27      93.94848          123786.3

Multiple dates/times and/or locations

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 months
input <- data.frame(
  longitude = 0,
  latitude = 50,
  date =  as.POSIXct("2020-06-18 00:00:00", tz = "GMT") + seq(0, 29*24*3600, 1800),
  sky_condition = 1
)

# calculate sky illuminance values for
# a single date/time and location
df <- skylight(
      longitude = input$longitude,
      latitude = input$latitude,
      date = input$date,
      sky_condition = 1
    )

print(head(df))
#>   sun_azimuth sun_altitude sun_illuminance moon_azimuth moon_altitude
#> 1         360   -16.627692    2.872734e-05           40    -18.193474
#> 2           7   -16.349941    3.874383e-05           46    -14.953394
#> 3          14   -15.476415    9.949008e-05           52    -11.355126
#> 4          21   -14.029282    4.779034e-04           58     -7.453916
#> 5          28   -12.043200    4.163346e-03           64     -3.301080
#> 6          34    -9.561923    6.272634e-02           69      1.419424
#>   moon_illuminance moon_fraction total_illuminance
#> 1     7.503453e-14      10.64874      0.0005287273
#> 2     2.407014e-12      10.52276      0.0005387438
#> 3     1.189855e-10      10.39738      0.0005994902
#> 4     8.248541e-09      10.27262      0.0009779116
#> 5     6.409745e-07      10.14848      0.0046639867
#> 6     1.859100e-05      10.02496      0.0632449283

# previous results are of the same dimension (rows)
# as the input data and can be bound together
# for easy plotting
input <- cbind(input, df)
library(ggplot2)

ggplot(input) +
  geom_tile(
    aes(
      as.Date(date),
      as.numeric(format(date, "%H")) + as.numeric(format(date, "%M"))/60,
      fill = log(total_illuminance)
    )
  ) +
  scale_fill_viridis_c(
    option = "B"
  ) +
  labs(
    title = "Diurnal cycles of total illuminance",
    subtitle = "(including the effect of moon contributions)",
    y = "Hour",
    x = ""
  ) +
  theme(
    legend.position = "bottom"
  )

Condensing this figure to only the mean half hourly value for a full moon captures the contributions of both sun and moon to the diurnal profile.

Piped data workflow

skylight supports piped data frames with appropriatedly named columns as input to the function. This allows for fast processing of large data frames, with the added 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, date, named as such (all lower case). The function will complain if it doesn’t find the required column names. Also note that due to the priority of the piped construction over the other parameters all parameters should be named when calling the function in a conventional way.

# recreating the data frame with parameters
# as before
input <- 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 values

df <- input |> skylight()

print(head(df))
#>   longitude latitude                date sky_condition sun_azimuth sun_altitude
#> 1         0       50 2020-06-18 00:00:00             1         360   -16.627692
#> 2         0       50 2020-06-18 00:30:00             1           7   -16.349941
#> 3         0       50 2020-06-18 01:00:00             1          14   -15.476415
#> 4         0       50 2020-06-18 01:30:00             1          21   -14.029282
#> 5         0       50 2020-06-18 02:00:00             1          28   -12.043200
#> 6         0       50 2020-06-18 02:30:00             1          34    -9.561923
#>   sun_illuminance moon_azimuth moon_altitude moon_illuminance moon_fraction
#> 1    2.872734e-05           40    -18.193474     7.503453e-14      10.64874
#> 2    3.874383e-05           46    -14.953394     2.407014e-12      10.52276
#> 3    9.949008e-05           52    -11.355126     1.189855e-10      10.39738
#> 4    4.779034e-04           58     -7.453916     8.248541e-09      10.27262
#> 5    4.163346e-03           64     -3.301080     6.409745e-07      10.14848
#> 6    6.272634e-02           69      1.419424     1.859100e-05      10.02496
#>   total_illuminance
#> 1      0.0005287273
#> 2      0.0005387438
#> 3      0.0005994902
#> 4      0.0009779116
#> 5      0.0046639867
#> 6      0.0632449283