| Type: | Package |
| Title: | Predicting Moonlight Intensity for a Given Time and Location |
| Version: | 0.1.1 |
| Description: | Tools for predicting moonlight intensity on the ground based on the position of the moon, atmospheric conditions, and other factors. Provides functions to calculate moonlight intensity and related statistics for ecological and behavioral research, offering more accurate estimates than simple moon phase calculations. The underlying model is described in Smielak (2023) <doi:10.1007/s00265-022-03287-2>. |
| License: | GPL-3 |
| Encoding: | UTF-8 |
| RoxygenNote: | 7.3.2 |
| Depends: | R (≥ 3.5.0) |
| Imports: | suncalc, lubridate |
| Suggests: | testthat (≥ 3.0.0) |
| Config/testthat/edition: | 3 |
| URL: | https://github.com/msmielak/moonlit |
| BugReports: | https://github.com/msmielak/moonlit/issues |
| NeedsCompilation: | no |
| Packaged: | 2026-03-02 19:59:47 UTC; admin |
| Author: | Michal Smielak 
[aut, cre] |
| Maintainer: | Michal Smielak <michalsmielak@gmail.com> |
| Repository: | CRAN |
| Date/Publication: | 2026-03-06 13:50:02 UTC |
Calculate moonlight intensity
Description
This function predicts moonlight intensity on the ground for any given place and time, based on the location, position of the moon and number of correction factors
Usage
calculateMoonlightIntensity(lat, lon, date, e)
Arguments
lat |
Latitude, numerical decimal |
lon |
Longitude, numerical decimal |
date |
Date time as POSIXct with the local time zone. If needed use as.POSIXct(date, tz=timezone) |
e |
Extinction coefficient - a single numerical value depending on the altitude. Average extinction coefficients (magnitude per air mass) are as follows: At sea level: 0.28; at 500m asl: 0.24; at 1000m asl: 0.21; at 2000m asl: 0.16 |
Value
A data frame with the following columns:
night |
Logical, TRUE when sun is below the horizon |
sunAltDegrees |
Solar altitude in degrees |
moonlightModel |
Predicted moonlight illumination, relative to an "average" full moon |
twilightModel |
Predicted twilight illumination in lux |
illumination |
Combined moon and twilight intensity, in lux |
moonPhase |
Lunar phase as a numerical value (% of moon face illuminated) |
Examples
lat <- 52.2297
lon <- 21.0122
date <- as.POSIXct("2023-06-15 22:00:00", tz = "Europe/Warsaw")
result <- calculateMoonlightIntensity(lat, lon, date, e = 0.21)
Calculate nightly moonlight statistics
Description
Calculate nightly moonlight statistics
Usage
calculateMoonlightStatistics(lat, lon, date, e, t, timezone)
Arguments
lat |
latitude, numerical decimal |
lon |
longitude, numerical decimal |
date |
date time as POSIXct with the local time zone. If needed use as.POSIXct(date, tz=timezone) |
e |
extinction coefficient - a single numerical value depending on the altitude. Average extinction coefficients (magnitude per air mass) are as follows: (At sea level: 0.28; at 500m asl: 0.24; at 1000m asl: 0.21; at 2000m asl: 0.16) |
t |
sampling interval. It is used in seq() function so the same values are accepted: A character string, containing one of "sec", "min", "hour". This can optionally be preceded by a (positive or negative) integer and a space, or followed by "s". Example: "15 mins", "3 hour" etc. |
timezone |
time zone of the data usually in the format "Continent/City", i.e. for Poland: "Europe/Warsaw" |
Value
A data frame with one row per input record and the following columns:
sunset |
Time of sunset for the night the record belongs to |
sunrise |
Time of sunrise for the night the record belongs to |
date |
Original date-time from the input |
meanMoonlightIntensity |
Mean nightly moonlight illumination |
maxMoonlightIntensity |
Maximum nightly moonlight illumination |
minMoonlightIntensity |
Minimum nightly moonlight illumination |
meanMoonPhase |
Mean nightly moon phase (fraction of disc illuminated) |
maxMoonPhase |
Maximum nightly moon phase |
minMoonPhase |
Minimum nightly moon phase |
Examples
lat <- 52.2297
lon <- 21.0122
date <- as.POSIXct("2023-06-15 22:00:00", tz = "Europe/Warsaw")
result <- calculateMoonlightStatistics(lat, lon, date, e = 0.21,
t = "30 mins",
timezone = "Europe/Warsaw")
Calculate extinction coefficient based on elevation of the observer
Description
Calculate extinction coefficient based on elevation of the observer
Usage
elevExtCoeff(elev)
Arguments
elev |
elevation in meters asl |
Value
A single numeric value: the estimated extinction coefficient for the given elevation.
Examples
# Extinction coefficient at sea level
suppressWarnings(elevExtCoeff(0))
# Extinction coefficient at 1000 m asl (e.g. approximate for many study sites)
suppressWarnings(elevExtCoeff(1000))