compute_field_photoperiod: Compute photoperiod across an FVCOM mesh

In edwardlavender/fvcom.tbx: An R Toolbox for the Unstructured Grid Finite Volume Community Ocean Model (FVCOM)

Compute photoperiod across an FVCOM mesh

Description

This function computes photoperiod as an environmental field across an spatial mesh.

Usage

compute_field_photoperiod(
  date,
  nodexy,
  interval = c("dawn", "dusk"),
  units = "hours"
)

Arguments

date	A vector of dates (see Date) for which photoperiod will be calculated.
nodexy	A dataframe containing decimal coordinates (in latitude/longitude) at which photoperiod is calculated. The dataframe should have two columns: 'x' and 'y'. See dat_nodexy for an example.
interval	A character vector with two elements which define the specific sunrise and sunset phases (in that order) between which photoperiod is calculated. This is passed to the keep argument of getSunlightTimes where further details are provided. The default option is to calculate the duration between dawn and dusk in each location on each day.
units	A character input which defines the units of the time difference. This is passed to difftime. Options are: "auto", "secs", "mins", "hours", "days" or "weeks".

Details

At specified locations (taken from nodexy) and on specified dates (taken from date), photoperiod is calculated as the number of time units (e.g. hours) between two discrete sunlight times (e.g. dawn and dusk), defined by the user and calculated by getSunlightTimes. For very long sequences of dates/locations, the function may take several minutes.

Value

Unlike other compute_field_*() functions, photoperiod is only defined on each day (not for each hour of the day). Therefore, rather than returning an array, the function returns a dataframe with the date ('date'), the location ('lat' and 'lon'), the times of the user-specified interval (e.g., 'dawn' and 'dusk') and the photoperiod ('photoperiod') in user-specified units. The dataframe is ordered by date.

Author(s)

Edward Lavender

Examples

#### Example (1): Compute photoperiod as the number of hours between dawn and dusk:
field_photoperiod <-
  compute_field_photoperiod(date = as.Date(c("2016-03-01", "2016-03-02")),
                           nodexy = dat_nodexy,
                            interval = c("dawn", "dusk"),
                            units = "hours")
utils::head(field_photoperiod)

#### Example (2): Compute photoperiod as the number of days between dawn and dusk
field_photoperiod <-
  compute_field_photoperiod(date = as.Date(c("2016-03-01", "2016-03-02")),
                            nodexy = dat_nodexy,
                            interval = c("dawn", "dusk"),
                            units = "days")
utils::head(field_photoperiod)

#### Example (3): Compute photoperiod as the number of days between sunrise and sunset:
field_photoperiod <-
 compute_field_photoperiod(date = as.Date(c("2016-03-01", "2016-03-02")),
                            nodexy = dat_nodexy,
                            interval = c("sunrise", "sunset"),
                            units = "days")
utils::head(field_photoperiod)

edwardlavender/fvcom.tbx documentation built on Nov. 26, 2022, 10:28 p.m.