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

Description Usage Arguments Details Value Examples

View source: R/check_night.R

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
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

pvol, vp, vpts, vpi, or a date inheriting from class POSIXct or a string interpretable by as.POSIXct.

...

optional lat,lon arguments.

elev

numeric. Sun elevation in degrees defining night time. May also be a numeric vector of length two, with first element giving sunset elevation, and second element sunrise elevation.

offset

numeric. Time duration in seconds by which to shift the start and end of night time. 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

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.

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.

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
# 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]

bioRad documentation built on July 1, 2020, 10:18 p.m.