| Title: | Predicting Moonlight Intensity for a Given Time and Location |
|---|---|
| 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>. |
| Authors: | Michal Smielak [aut, cre] (ORCID: <https://orcid.org/0000-0002-3585-9945>) |
| Maintainer: | Michal Smielak <[email protected]> |
| License: | GPL-3 |
| Version: | 0.1.1 |
| Built: | 2026-06-06 10:02:39 UTC |
| Source: | https://github.com/msmielak/moonlit |
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
calculateMoonlightIntensity(lat, lon, date, e)calculateMoonlightIntensity(lat, lon, date, e)
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 |
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) |
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)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
calculateMoonlightStatistics(lat, lon, date, e, t, timezone)calculateMoonlightStatistics(lat, lon, date, e, t, timezone)
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" |
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 |
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")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
elevExtCoeff(elev)elevExtCoeff(elev)
elev |
elevation in meters asl |
A single numeric value: the estimated extinction coefficient for the given elevation.
# Extinction coefficient at sea level suppressWarnings(elevExtCoeff(0)) # Extinction coefficient at 1000 m asl (e.g. approximate for many study sites) suppressWarnings(elevExtCoeff(1000))# Extinction coefficient at sea level suppressWarnings(elevExtCoeff(0)) # Extinction coefficient at 1000 m asl (e.g. approximate for many study sites) suppressWarnings(elevExtCoeff(1000))