clearskies: Clear Sky Models

# This file was generated by Rcpp::compileAttributes
# Generator token: 10BE3573-1514-4C36-9D1C-5A225CD40393

#' Calculate line length variability.
#'
#' Line length variability is one of the five criterion used for detecting
#' clear points. It is defined as:
#' \deqn{
#' L = \sum_{i=1}^{n} \sqrt{ (GHI_{i+1} + GHI_{i})^2 + (t_{i+1} +
#' t_{i})^2 }
#' }
#' where \eqn{t} is the time series, and \eqn{GHI} is measured irradiance.
#'
#' @param x Numeric vector of measured irradiance.
#'
#' @section References:
#' Global Horizontal Irradiance Clear Sky Models: Implementation and Analysis,
#' Reno et al, 2012, pp. 30.
#'
#' @name L
#'
#' @keywords internal
NULL

#' Normalized standard deviation of the slope between sequential points.
#'
#' The normalized standard deviation of the slope (sigma) is one of the five
#' criterion for detecting clear points. It is defined as follows:
#' \deqn{
#' \sigma = \frac{1}{ {\overline{GHI}} }
#' \sqrt{ \frac{1}{n-1} \sum_{i=1}^{n-1} (s_{i} {\overline{s}})^2 }
#' }
#' where \eqn{ {\overline{GHI}} } is the mean of the measured irradiance
#' values, \eqn{ s_{i} = GHI_{i+1} - GHI_{i} } and \eqn{ {\overline{s}} } is the
#' sample standard deviation of \eqn{s}.
#'
#' @param x Numeric vector of measured irradiance.
#'
#' @section References:
#' Global Horizontal Irradiance Clear Sky Models: Implementation and Analysis,
#' Reno et al, 2012, pp. 30.
#'
#' @name sigma
#'
#' @keywords internal
NULL

#' Maximum deviation of the measured irradiance from the clear sky slope.
#'
#' The maximum deviation of the measured irradiance from the clear sky slope is
#' one of five criterion for detecting clear points. It is defined as follows:
#' \deqn{
#' S = max\{|s_{i}-d_{i}|\}
#' }
#' where \eqn{ s_{i} = GHI_{i+1} - GHI_{i} } and \eqn{ d_{i} = y_{i+1} - y_{i}
#' }. \eqn{GHI} denotes the measured irradiance and \eqn{y} denotes the
#' predicted irradiance from a clear sky model.
#'
#' @param x Numeric vector of measured irradiance.
#' @param cs Numeric vector of predicted irradiance. Should be the same
#' length as x, however this condition is not checked.
#'
#' @section References:
#' Global Horizontal Irradiance Clear Sky Models: Implementation and Analysis,
#' Reno et al, 2012, pp. 31.
#'
#' @name S
#'
#' @keywords internal
NULL

#' Calculate five clear sky criterion.
#'
#' @param x Numeric vector of measured irradiance.
#' @param cs Numeric vector of predicted irradiance. Should be the same
#' length as x, however this condition is not checked.
#'
#' @name calculate_criterion
#'
#' @keywords internal
NULL

#' Check if all criterion are within their respective threshold values.
#'
#' @param criterion List of clear sky criterion.
#' @param thresholds List of vectors, each vector containing the threshold
#' values for their respective clear sky criteria.
#'
#' @return If all criterion are within their threshold ranges, inclusive,
#' returns true.
#'
#' Note: Clear sky criterion from \emph{criterion} are compared to values in
#' \emph{thresholds} by index, not name.
#'
#' @name evaluate_criterion
#'
#' @keywords internal
NULL

#' Clear sky detection
#'
#' Determine clear points using a rolling window and five clear sky criterion.
#'
#' A point is declared clear if it is determined to be clear at least once.
#'
#' @param x Numeric vector of measured irradiance values.
#' @param cs Numeric vector of predicted irradiance from a clear sky model.
#' @param thresholds List of vectors, each vector containing the threshold
#' values for their respective clear sky criteria. Each vector must have length
#' greater than or equal to two, with the minimum and maximum values in the
#' vector being used as thresholds. The list must be arranged in the following
#' order:
#' \enumerate{
#'     \item Mean
#'     \item Max
#'     \item Line length
#'     \item Sigma
#'     \item Maximum deviation from clear sky slope
#' }
#' @param window_len Length of window, in minutes, used in calculating
#' criterion. Must be a positive integer.
#'
#' @return A logical vector of the same length as x, TRUE indicates the
#' point is clear.
#' @return A logical vector of the same length as x. TRUE indicates that the
#' corresponding measured irradiance value in x is clear.
#'
#' @section References:
#' Global Horizontal Irradiance Clear Sky Models: Implementation and Analysis,
#' Reno et al, 2012, pp. 28-36.
#'
clear_pts <- function(x, cs, thresholds, window_len) {
    .Call('clearskies_clear_pts', PACKAGE = 'clearskies', x, cs, thresholds, window_len)
}

#' Root mean squared error
#'
#' Calculate root mean squared error.
#'
#' @param x Numeric vector.
#' @param y Numeric vector.
#'
#' @return Square root of the mean squared error between x and y.
#'
#' @export
rmse <- function(x, y) {
    .Call('clearskies_rmse', PACKAGE = 'clearskies', x, y)
}

#' Helper function for calculating solar irradiance in clear sky models.
#'
#' @param dayofyear Day of year to calculate solar irradiance for. May be a
#' vector.
#' @param times Length of return vector. Passed to \emph{rep}.
#'
#' @return A vector of earth radius values of length times.
#'
#' @keywords internal
exrad <- function(dayofyear, times) {
    .Call('clearskies_exrad', PACKAGE = 'clearskies', dayofyear, times)
}

#' Calculate the zenith angle.
#'
#' @param dayofyear Numeric vector containing the day of year(s),
#' for which the zenith angle should be calculated.
#' @param year Numeric vector containing the year(s) for which the zenith
#' angle sould be calculated.
#' @param tz UTC Offset. Ex: Eastern Standard Time = -5.
#' @param latitude Latitude of the location at which the zenith angle is to
#' be calculated.
#' @param longitude Longitude of the location at which the zenith angle is to
#' be calculated.
#' @param interval Number of minutes between zenith angle calculations. Defaults to
#' (every minute). Must be an integer between 1 and 60, inclusive.
#'
#' @return A single vector of the zenith angles at each interval throughout the
#' specified time period
#' (i.e. a vector of length (60 * 24 / interval) * number of days).
#'
#' @details
#' zenith is vectorized over both dayofyear and year, with the shorter vector
#' being recycled as usual.
#'
#' @keywords internal
zenith <- function(dayofyear, year, tz, latitude, longitude, interval = 1L) {
    .Call('clearskies_zenith', PACKAGE = 'clearskies', dayofyear, year, tz, latitude, longitude, interval)
}