add r_crit()

Author: vlyubchich

DESCRIPTION

@@ -1,8 +1,8 @@
 Package: funtimes
 Type: Package
 Title: Functions for Time Series Analysis
-Version: 9.1
-Date: 2023-03-21
+Version: 9.2
+Date: 2023-04-28
 Authors@R: c(person("Vyacheslav", "Lyubchich", 
                     role = c("aut", "cre"),
                     comment = c(ORCID = "0000-0001-7936-4285"),

NAMESPACE

@@ -21,6 +21,7 @@ export(notrend.test)
 export(notrend_test)
 export(purity)
 export(q.tails)
+export(r_crit)
 export(sync.cluster)
 export(sync.test)
 export(sync_cluster)
@@ -58,6 +59,7 @@ importFrom(stats,na.omit)
 importFrom(stats,pnorm)
 importFrom(stats,predict)
 importFrom(stats,qnorm)
+importFrom(stats,qt)
 importFrom(stats,quantile)
 importFrom(stats,residuals)
 importFrom(stats,rnorm)

R/r_crit.R

@@ -0,0 +1,53 @@
+#' Critical Value for Correlation Coefficient
+#'
+#' Calculate critical value for correlation coefficient,
+#' for a given sample size and confidence level.
+#' If absolute value of an observed correlation coefficient is higher
+#' than the critical value, then the correlation is statistically significant
+#' with the specified confidence.
+#' This approach is
+#' identical to using textbook tables of critical values and
+#' alternative to calculating \eqn{p}-values.
+#'
+#' @details
+#' Using Student's \eqn{t}-distribution, the critical value is
+#' \deqn{r_{crit} = \frac{t}{\sqrt{n - 2 + t^2}},}
+#' where \eqn{t} is a quantile of \eqn{t}-distribution with
+#' \eqn{n - 2} degrees of freedom for probability \eqn{1 - (1 - conf.level)/2}.
+#'
+#' @param n sample size(s) used to calculate correlations.
+#' Values of \eqn{n < 4} are omitted.
+#' @param conf.level confidence level for calculating the critical value(s).
+#' Default is 0.95 (i.e., confidence of 95%).
+#' If length of the input is higher than 1, only the first element is used.
+#' @param method Method for calculating the critical values.
+#' Currently only the method based on \eqn{t}-distribution is used.
+#'
+#' @return A vector of critical values.
+#'
+#' @references
+#' \insertAllCited{}
+#'
+#' @seealso \code{\link[stats]{cor.test}}, \code{\link[stats]{cor}}
+#'
+#' @keywords correlation threshold
+#'
+#' @author Vyacheslav Lyubchich
+#'
+#' @importFrom stats qt
+#' @export
+#' @examples
+#' r_crit(120)
+#' r_crit(20:30, conf.level = 0.9)
+#'
+r_crit <- function(n,
+                   conf.level = 0.95,
+                   method = c("t")) {
+    if (any(n < 4)) {
+        warning("Values of n < 4 were omitted.")
+        n <- n[n >= 4]
+    }
+    alpha <- 1 - conf.level[1]
+    t2 <- qt(p = 1 - alpha/2, df = n - 2)^2
+    sqrt(t2 / (n - 2 + t2))
+}

README.md

@@ -18,7 +18,11 @@ library(funtimes)
 ## Future work
 
 - Remove defunct functions.
+- Describe the statistics in causality_pred()
 
+## Current GitHub version
+
+- Added new function `r_crit()` to compute critical values of correlations.
 
 ## CRAN version 9.1