compute_field_sun_angle: Compute sun angle across an FVCOM mesh

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

Compute sun angle across an FVCOM mesh

Description

This function computes the sun angle across a spatial mesh on the dates/times specified. To calculate sun angle, the user must specify a dataframe containing node IDs and associated coordinates across which sun angle is evaluated. (Sun angle, a scalar variable, is computed at nodes for consistency with other FVCOM outputs.) Next, the user must specify the date and hours on that date for which to calculate sun angle. Finally, the user needs to specify whether or not sun angle should be returned in degrees or radians, the directory to save files (not required) and whether or not to print messages/progress to the console.

Usage

compute_field_sun_angle(
  nodexy,
  date,
  tz = "UTC",
  hours = 0:23,
  units = "degrees",
  sink_file = NULL,
  dir2save = NULL,
  iterative = FALSE,
  cl = NULL,
  pass2varlist = NULL,
  verbose = TRUE
)

Arguments

nodexy	A dataframe containing node ids and decimal coordinates (in latitude/longitude). The dataframe should have three columns: 'node_id', 'x' and 'y'. See dat_nodexy for an example.
date	A vector of dates (see Date) for which sun angle is to be calculated.
tz	A character vector specifying the time zone. The default is "UTC".
hours	A integer vector specifying the hours at which you want to calculate sun angle.
units	A character input defining the units ("degrees" or "radians") of sun angle.
sink_file	(optional) A character specifying the name of sun angle fields, if saved as files (see dir2save, below). If dir2save = TRUE and sink_file = NULL, date_name is used to define file names from inputted dates.
dir2save	(optional) A string specifying the directory in which to save sun angle files.
iterative	A logical input that defines whether or not to compute sun angle matrices iteratively for each date. The default option is FALSE but, for large sequences of dates and many nodes, an iterative implementation is necessary to avoid exhausting vector memory.
cl	(optional) A cluster objected created by the parallel package. This is only implemented if iterative = TRUE. If supplied, the algorithm (computing sun angle matrices and, if applicable, saving these to file) is implemented in parallel. Note that the connection with the cluster is stopped within the function.
pass2varlist	A list containing the names of exported objects. This may be required if cl is supplied. This is passed to the varlist argument of clusterExport. Exported objects must be located in the global environment.
verbose	A logical input specifying whether or not messages and a progress bar should be printed to the console. The default is TRUE.

Value

For each date, the function creates a matrix of hours x mesh cells containing sun angles. Matrices are either returned as a list or saved as .rds files, with one file per day (if dir2save = TRUE).

Author(s)

Edward Lavender

Source

This function is a wrapper for getSunlightPosition function.

Examples

#### Example (1): Calculate sun angles for one date and some sample nodes
sun_angle <-
  compute_field_sun_angle(
    nodexy = dat_nodexy,
    date = as.Date("2016-01-01"),
    tz = "UTC",
    hours = 0:23,
    units = "degrees",
    dir2save = NULL,
    verbose = TRUE
  )
# The function returns a list with one element (matrix) for each date
# ... with rows (hours) x columns (nodes)
utils::str(sun_angle)

#### Example (2): Implement algorithm iteratively over each date
# We're only specifying one example date here, but for demonstration purposes:
sun_angle <-
  compute_field_sun_angle(
    nodexy = dat_nodexy,
    date = as.Date("2016-01-01"),
    tz = "UTC",
    hours = 0:23,
    units = "degrees",
    dir2save = NULL,
    iterative = TRUE,
    verbose = TRUE
  )
utils::str(sun_angle)

#### Example (3): Implement iterations in parallel via cl argument
# Again, for demonstration purposes only:
sun_angle <-
  compute_field_sun_angle(
    nodexy = dat_nodexy,
    date = as.Date("2016-01-01"),
    tz = "UTC",
    hours = 0:23,
    units = "degrees",
    dir2save = NULL,
    iterative = TRUE,
    cl = parallel::makeCluster(2L),
    verbose = TRUE
  )
utils::str(sun_angle)

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