Package 'MoonShineR'

Create a plot from the illuminance prediction dataframe

Description

• plot_lux() plots the illuminance prediction dataframe generated by predict_lux().

• To learn more about MoonShineR, see https://lokpoon.github.io/software/

Usage

plot_lux(
  df = NULL,
  illuminance_type_plot = "total_illuminance_all",
  plot_y_max = 0.3,
  plot_daytime_gray_mask = TRUE,
  plot_eclipse_red_mask = TRUE,
  plot_twilight = "astro",
  vertical_time_label = TRUE,
  time_label_interval_hr = 24,
  time_label_shift_hr = 0
)

Arguments

df	data.frame. Data frame created by predict_lux().
illuminance_type_plot	character. Choose one type of illuminance to plot. See options in the next section. Default is "moon_final_lux_nighttime".
plot_y_max	numeric or "AUTO". Upper limit of the y-axis. Use "AUTO" to let ggplot choose the scale automatically. Default is 0.3.
plot_daytime_gray_mask	logical. TRUE to mask daytime plot line in gray. Affects both the plot in the plot window and the exported .pdf. FALSE to disable (plot line always black). Default is TRUE.
plot_eclipse_red_mask	logical. TRUE to add a red shade during times of lunar eclipse as a warning that those illuminance prediction might be overestimating. FALSE to disable (plot line always black). Default is TRUE.
plot_twilight	character. Set the twilight period to plot as a gray area. "astro" is astronomical twilight (longest). "nautic" is nautical twilight (intermediate). "civil" is civil twilight (shortest). "none" to disable plotting of twilight period. Default is "astro".
vertical_time_label	logical. Rotate datetime label to be vertical.
time_label_interval_hr	numeric. Set the datetime label in number of hours.
time_label_shift_hr	numeric. Shift the x-axis start time by certain number of hours for a more tidy datetime label. Use negative values to shift the start time to a time before the first data point (i.e., add a blank space to the left), as to avoid cutting out data.

Value

A ggplot object showing predicted ground illuminance through time. The type of illuminance plotted, corresponding to a specific combination of moonlight, sunlight, and twilight, depends on the illuminance_type_plot argument in the plot_lux() function and corresponds to one of the illuminance columns in the data frame produced by predict_lux().

illuminance_type_plot options:

• "moon_final_lux" plots only the illuminance of moonlight (plus the darksky_value) during both day and night.

• "moon_final_lux_nighttime" plots only the illuminance of moonlight at night (no value during daytime, when sun_altitude > 0 degrees)

• "moonlight_twilight_nighttime" plots the illuminance of moonlight plus twilight (no value during daytime, when sun_altitude > 0 degrees)

• "twilight" plots only the illuminance of twilight (defined as the light when sun_altitude < 0 degrees).

• "sunlight" plots only the illuminance of sunlight (defined as the light when sun_altitude > 0 degrees).

• "sunlight_twilight" plots only the sum of sunlight and twilight.

• "total_illuminance_all" plots all illuminance together, calculated as the sum of moonlight, twilight, and sunlight.

• Note: The above terms corresponding to the columns headers in the predict_lux() generated dataframe.

Notes:

• The magnitude of moonlight and sunlight illuminance diffsers immensely. So depending on the illuminance_type_plot selected, the user might want to manually adjust the plot_y_max.

• plot_daytime_gray_mask is TRUE by default to mask daytime illuminance in gray. This is particularly useful when plotting "moon_final_lux" to make it clear that moonlight during daytime should be ignored.

• Nighttime is always shaded in dark gray.

• Twilight period is shaded in light gray. The period of twilight can be adjusted with plot_twilight.

Examples

# Plot a predict_lux generated dataframe named moonlight_output

# First create a set of data with predict_lux()
moonlight_output <- predict_lux(latitude = -4.21528, longitude = -69.94056, site_elev = 0,
                    time_zone = "EST", date_start = "2023-02-27", time_start = "18:00:00",
                    duration_day = 10.5, time_interval_minutes = 30, darksky_value = 0.0008,
                    output_directory = NULL, export_table = FALSE)

# Proceed to plotting
plot_lux(df = moonlight_output, illuminance_type_plot = "total_illuminance_all",
         plot_y_max = 0.3,  plot_daytime_gray_mask = TRUE, plot_eclipse_red_mask = TRUE,
         plot_twilight = "astro", vertical_time_label = TRUE, time_label_interval_hr = 24,
         time_label_shift_hr = -1)

---

Predict moonlight, sunlight, and twilight ground illuminance

Description

• predict_lux() predicts moonlight, sunlight, and/or twilight ground illumination (in lux) for any defined geographical location and time period. It creates a data.frame output and automatically plot to the console. Automatic export of the table (.csv) is optional.

• The presence of lunar eclipse during the simulated period is also reported as a console message. The illuminance reduction during lunar eclipse is not modeled.

• To create a moonlight or sunlight LED schedule for light re-creation using MoonShineP, user need to download the R script version of the MoonShineR: Moonlight scheduler or MoonShineR: Sunlight/twilight scheduler from GitHub repository: see https://github.com/Crampton-Lab/MoonShine

• The R script version also have other simulation features, such as simulating the blocking of direct moonlight from horizon obstructions (e.g., tree line or ridgeline), and attenuation by random passing clouds.

• To learn more about MoonShineR, see https://lokpoon.github.io/software/

Usage

predict_lux(
  latitude = NULL,
  longitude = NULL,
  site_elev = 0,
  time_zone = NULL,
  date_start = NULL,
  time_start = "00:00:00",
  duration_day = NULL,
  time_interval_minutes = 5,
  darksky_value = 8e-04,
  output_directory = NULL,
  export_table = FALSE,
  show_progress = TRUE
)

Arguments

latitude	numeric. Latitude in decimal degrees (e.g., -4.21528).
longitude	numeric. Longitude in decimal degrees (e.g., -69.94056).
site_elev	numeric. Site elevation in meters (e.g., 0 is sea level). Default is 0. Elevation correction only applies to moonlight but not sunlight and twilight. Site elevation of a coordinate location can be obtained from https://www.dcode.fr/earth-elevation.
time_zone	character. Time zone for the location set (e.g., "EST"). Remember to change time_zone to correspond it to the location set. For a list of time zone names, enter OlsonNames(tzdir = NULL) in R console. Use a time zone without DST to avoid confusion (e.g., use "EST" instead of "America/New_York").
date_start	character. Starting date of the simulation ("YYYY-MM-DD").
time_start	character. Starting time of the simulation ("hh:mm:ss"). Default is "00:00:00".
duration_day	numeric. Duration of the simulation in days.
time_interval_minutes	numeric.The temporal resolution of the simulation in minutes. E.g., 5 calculates the illuminance every 5 minutes. Using small time interval requires longer computation time. Default is 5.
darksky_value	numeric. A baseline illuminance (in lux) added to the model to represent other constant nocturnal light sources (e.g., starlight and airglow). Default is 0.0008. Change it to zero if a completely dark sky is preferred.
output_directory	character. Directory to save the output table (.csv) and plot (.pdf). Ignore output_directory if the export options are turned OFF (i.e., export_table = FALSE).
export_table	logical. TRUE to export output .csv table to the output_directory. FALSE to disable. Default is FALSE.
show_progress	logical. TRUE to show a progress bar. FALSE to disable. Default is TRUE.

Value

A data frame containing predicted ground illuminance values for each time step, based on different combinations of moonlight, sunlight, and twilight. Other columns include various astronomical values.

Columns found in the output data.frame/.csv table:

• A series of astronomical and illuminance values are reported for every time stamp. In explanation,

• datetime POSIXct. Datetime in "YYYY-MM-DD hh:mm:ss".

• phase_angle numeric. Phase angle of the moon in degree angle.

• fraction numeric. Illuminated fraction of the moon.

• Z_moon numeric. Zenith distance of the moon in degree angle (i.e., the angle of separation from directly overhead). > 90 means the moon is below the horizon.

• distance numeric. The moon-Earth distance in km.

• sun_altitude numeric. The sun altitude (relative to the horizon) in degree angle. Negative value means the sun is below the horizon.

• "moon_final_lux" numeric. Only the illuminance of moonlight (plus the darksky_value) during both day and night.

• "moon_final_lux_nighttime" numeric. Only the illuminance of moonlight at night (no value during daytime, when sun_altitude > 0 degrees)

• "moonlight_twilight_nighttime" numeric. The illuminance of moonlight plus twilight (no value during daytime, when sun_altitude > 0 degrees)

• "twilight" numeric. Only the illuminance of twilight (defined as the light when sun_altitude < 0 degrees).

• "sunlight" numeric. Only the illuminance of sunlight (defined as the light when sun_altitude > 0 degrees).

• "sunlight_twilight" numeric. The sum of sunlight and twilight.

• "total_illuminance_all" numeric. All illuminance together, calculated as the sum of moonlight, twilight, and sunlight.

• "eclipse" logical. The presence of a lunar eclipse (all kinds), including penumbral lunar eclipse.

Attribution

• Astronomical values used in calculating ground illuminance are provided by the R package suncalc (Thieurmel & Elmarhraoui, 2022).

• Atmospheric pressure at elevation is provided by the R package RPMODEL (Stocker et al., 2020).

References

• Allen, C. W. (1976). Astrophysical quantities. Athelone Press.

• Austin, R. H., Phillips, B. F., & Webb, D. J. (1976). A method for calculating moonlight illuminance at the earth's surface. The Journal of Applied Ecology, 13(3), 741.

• Buratti, B. J., Hillier, J. K., & Wang, M. (1996). The lunar opposition surge: Observations by clementine. Icarus, 124(2), 490-499.

• Hanel, A., Posch, T., Ribas, S. J., Aube, M., Duriscoe, D., Jechow, A., Kollath, Z., Lolkema, D. E., Moore, C., Schmidt, N., Spoelstra, H., Wuchterl, G., & Kyba, C. C. M. (2018). Measuring night sky brightness: Methods and challenges. Journal of Quantitative Spectroscopy and Radiative Transfer, 205, 278-290.

• Krisciunas, K., & Schaefer, B. E. (1991). A model of the brightness of moonlight. Publications of the Astronomical Society of the Pacific, 103, 1033.

• Laue, E. G. (1970). The measurement of solar spectral irradiance at different terrestrial elevations. Solar Energy, 13(1), 43-57.

• Schaefer, B. E. (1990). Telescopic limiting magnitudes. Publications of the Astronomical Society of the Pacific, 102, 212.

• Seidelmann, P. K., United States Naval Observatory, & Great Britain (Eds.). (1992). Explanatory supplement to the Astronomical almanac (Rev. ed.). University Science Books.

• Stocker, B. D., Wang, H., Smith, N. G., Harrison, S. P., Keenan, T. F., Sandoval, D., Davis, T., & Prentice, I. C. (2020). P-model v1.0: An optimality-based light use efficiency model for simulating ecosystem gross primary production. Geoscientific Model Development, 13(3), 1545-1581.

• Thieurmel, B., & Elmarhraoui, A. (2022). suncalc: Compute sun position, sunlight phases, moon position and lunar phase. R package version 0.5.1. https://CRAN.R-project.org/package=suncalc

Examples

# Predict the nighttime moonlight illuminance in Leticia, Colombia,
# for 14 days starting on 2023-02-27 at 6pm.

moonlight_output <- predict_lux(latitude = -4.21528, longitude = -69.94056, site_elev = 0,
                    time_zone = "EST", date_start = "2023-02-27", time_start = "18:00:00",
                    duration_day = 2, time_interval_minutes = 15, darksky_value = 0.0008,
                    output_directory = NULL, export_table = FALSE, show_progress = TRUE)

moonlight_output #return completed data frame

---