check_night: Check if it is night at a given time and place

In adokter/birdRad: Biological Analysis and Visualization of Weather Radar Data

Check if it is night at a given time and place

Description

Checks if it is night (TRUE/FALSE) for a combination of latitude, longitude, date and sun elevation. When used on a bioRad object (pvol, vp, vpts, vpi) this information is extracted from the bioRad object directly.

Usage

check_night(x, ..., elev = -0.268, offset = 0)

## Default S3 method:
check_night(x, lon, lat, ..., tz = "UTC", elev = -0.268, offset = 0)

## S3 method for class 'vp'
check_night(x, ..., elev = -0.268, offset = 0)

## S3 method for class 'list'
check_night(x, ..., elev = -0.268, offset = 0)

## S3 method for class 'vpts'
check_night(x, ..., elev = -0.268, offset = 0)

## S3 method for class 'vpi'
check_night(x, ..., elev = -0.268, offset = 0)

## S3 method for class 'pvol'
check_night(x, ..., elev = -0.268, offset = 0)

Arguments

x	A pvol, vp, vpts, vpi object, a POSIXct date or a string interpretable by base::as.POSIXct().
...	Optional lat, lon arguments.
elev	Numeric (vector). Sun elevation in degrees defining nighttime. May also be a numeric vector of length two, with first element giving sunset elevation, and second element sunrise elevation.
offset	Numeric (vector). Time duration in seconds by which to shift the start and end of nighttime. May also be a numeric vector of length two, with first element added to moment of sunset and second element added to moment of sunrise.
lon	Numeric. Longitude, in decimal degrees.
lat	Numeric. Latitude, in decimal degrees.
tz	Character. Time zone. Ignored when date already has an associated time zone.

Details

check_night() evaluates to FALSE when the sun has a higher elevation than parameter elev, otherwise TRUE.

Approximate astronomical formula are used, therefore the day/night transition may be off by a few minutes.

The angular diameter of the sun is about 0.536 degrees, therefore the moment of sunrise/sunset corresponds to half that elevation at -0.268 degrees. Approximate astronomical formula are used, therefore the day/night transition may be off by a few minutes.

offset can be used to shift the moment of sunset and sunrise by a temporal offset, for example, offset = c(600,-900) will assume nighttime starts 600 seconds after sunset (as defined by elev) and stops 900 seconds before sunrise.

Value

TRUE when night, FALSE when day, NA if unknown (either datetime or geographic location missing). For vpts a vector of TRUE/FALSE values is returned.

Examples

# Check if it is night at UTC midnight in the Netherlands on January 1st:
check_night("2016-01-01 00:00", 5, 53)

# Check on bioRad objects directly:
check_night(example_vp)

check_night(example_vpts)

# Select nighttime profiles that are between 3 hours after sunset
# and 2 hours before sunrise:
index <- check_night(example_vpts, offset = c(3,-2)*3600)
example_vpts[index]

adokter/birdRad documentation built on Nov. 5, 2024, 10:27 p.m.