Package 'MoonShineR'

Create a plot from the illuminance prediction data frame

Description

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

• • For more information about MoonShine, including stand-alone scheduler scripts and MoonShineP, see https://lokpoon.github.io/MoonShine_manual/overview.html.

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 returned by predict_lux().
illuminance_type_plot	character. Choose one type of illuminance to plot. See options below. Default is "total_illuminance_all".
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. If TRUE, , shows daytime portions of the plotted line in gray; FALSE disables this masking. Default is TRUE.
plot_eclipse_red_mask	logical. If TRUE, adds red shading during lunar eclipses to warn that predicted illuminance may be overestimated because eclipse-related dimming is not modeled; FALSE disables the shading. Default is TRUE.
plot_twilight	character. Select the twilight interval to shade gray: "astro" for astronomical twilight (longest), "nautic" for nautical twilight (intermediate), "civil" for civil twilight (shortest), or "none" to disable twilight shading. Default is "astro".
vertical_time_label	logical. If TRUE, rotate date–time labels vertically.
time_label_interval_hr	numeric. Interval between date–time labels, in hours.
time_label_shift_hr	numeric. Shift the x-axis start time by the specified number of hours to improve the placement of date–time labels. Negative values move the start time earlier than the first data point, leaving space at the left edge of the plot.

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.

• These option names correspond to the column names in the data frame generated by predict_lux().

Notes:

• Moonlight and sunlight illuminance differ by several orders of magnitude. Depending on the selected illuminance_type_plot, users may need to adjust plot_y_max or set it to "AUTO".

• 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 is shaded in light gray. The plot_twilight argument allows users to select astronomical, nautical, or civil twilight, or disable twilight shading.

Examples

# Plot a data frame generated by predict_lux(), named moonlight_output.
# First create a set predictions with predict_lux().
moonlight_output <- predict_lux(latitude = -4.21528, longitude = -69.94056, site_elev = 0,
                    time_zone = "EST", date_start = "2023-03-03", time_start = "18:00:00",
                    duration_day = 5.5, time_interval_minutes = 20, darksky_value = 0.0008,
                    output_directory = NULL, export_table = FALSE)

# Plot the combined illuminance of moonlight, twilight, and sunlight.
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 = -10)

---

Predict moonlight, sunlight, and twilight ground illuminance

Description

• predict_lux() predicts ground illuminance from moonlight, sunlight, and/or twilight (in lux) for a specified geographical location and time period. It returns a data frame and automatically displays a plot of the predictions. Optional export of the data frame as a CSV file is available.

• The occurrence of lunar eclipses during the simulated period is reported in a console message. The reduction in illuminance during lunar eclipses is not modeled.

• To generate LED control schedules for use with MoonShineP, download the stand-alone MoonShineR Moonlight scheduler or Sunlight/twilight scheduler scripts from the main MoonShine GitHub repository: https://github.com/Crampton-Lab/MoonShine. These scripts are not included in the CRAN package.

• The stand-alone scheduler scripts also provide additional simulation features, including the obstruction of direct moonlight by trees or ridgelines and attenuation by passing clouds.

• For further documentation on MoonShineR, the scheduler scripts, and MoonShineP, see https://lokpoon.github.io/MoonShine_manual/overview.html.

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 above sea level (default 0). The elevation correction applies to moonlight predictions but not to sunlight or twilight predictions. Elevation for a given location can be obtained from https://www.dcode.fr/earth-elevation.
time_zone	character. Time zone for the specified location (e.g., "EST" for a fixed UTC-5 offset). Set time_zone consistently with the date and time being simulated. To list recognized time zones in R, enter OlsonNames(). A fixed-offset zone avoids daylight saving time changes, whereas a location-based zone such as "America/New_York" applies them; choose according to the intended interpretation of local time.
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 Time interval between successive illuminance predictions, in minutes. For example, 5 calculates illuminance every 5 minutes. Smaller intervals require more computation time. Default is 5.
darksky_value	numeric. A baseline illuminance (in lux) added to the model to represent other approximately constant nocturnal light sources (e.g., starlight and airglow). Default is 0.0008. Set it to zero to omit this background component.
output_directory	character. Directory for exported output files. If export_table = FALSE, no CSV table is exported.
export_table	logical. If TRUE, export the output data frame as a CSV file to output_directory; if FALSE, do not export the table. Default is FALSE.
show_progress	logical. If TRUE, display a progress bar; FALSE disables it. 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:

• The output reports astronomical quantities and predicted illuminance for each time step.

• datetime POSIXct. Date and time in "YYYY-MM-DD hh:mm:ss".

• phase_angle numeric. Lunar phase angle, in degrees.

• fraction numeric. Illuminated fraction of the moon.

• Z_moon numeric. Lunar zenith distance, in degrees (angular distance from directly overhead). Values greater than 90 indicate that the moon is below the horizon.

• distance numeric. Earth–moon distance, in km.

• sun_altitude numeric. Altitude of the sun above the horizon, in degrees. Negative values indicate that the sun is below the horizon.

• "moon_final_lux" numeric. Predicted moonlight illuminance plus darksky_value, for both daytime and nighttime.

• "moon_final_lux_nighttime" numeric. Predicted moonlight illuminance at night; no value is reported during daytime (sun_altitude > 0).

• "moonlight_twilight_nighttime" numeric. Sum of moonlight and twilight illuminance at night; no value is reported during daytime (sun_altitude > 0).

• "twilight" numeric. Twilight illuminance (sun_altitude < 0).

• "sunlight" numeric. Sunlight illuminance (sun_altitude > 0).

• "sunlight_twilight" numeric. Sum of sunlight and twilight illuminance.

• "total_illuminance_all" numeric. Sum of moonlight, twilight, and sunlight illuminance.

• "eclipse" logical. Indicator for a lunar eclipse, including penumbral eclipses.

Attribution

• Astronomical quantities 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 (3rd ed.). Athlone 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–748.

• 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-1039.

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

• Poon, L., Jenks, I. T., & Crampton, W. G. R. (2024). MoonShine: A software-hardware system for simulating moonlight ground illuminance and re-creating artificial moonlight cycles in a laboratory environment. Methods in Ecology and Evolution, 15, 701–715. doi:10.1111/2041-210X.14299

• 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 5.5 days starting on 2023-03-03 at 6 pm (UTC -5).

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

moonlight_output # Display the completed data frame.

---