Finds the noncentrality parameters of a noncentral chi square distribution
that bracket an observed chi square value with the requested tail
probabilities, giving a confidence interval on the population noncentrality
parameter. Together with ci_nc_t and
ci_nc_F, this is one of the low-level noncentral
distribution workhorses on which the ci_* confidence interval
functions are built; most analyses reach it through those functions rather
than calling it directly.
The function was conf_limits_nc_chisq() in earlier builds of DMAR and is
conf.limits.nc.chisq() in MBESS; it is named into the ci_* family because a
confidence interval is what it computes.
ci_nc_chisq(
chi_square = NULL,
conf_level = 0.95,
df = NULL,
alpha_lower = NULL,
alpha_upper = NULL,
tol = 1e-09,
verbose = TRUE,
...
)A data.frame with one row per confidence limit and the columns:
Either "lower_limit" or "upper_limit".
The noncentrality parameter at that limit. 0 when alpha_lower = 0 or the lower limit is unattainable; Inf when alpha_upper = 0; NA when the observed chi_square is so small that even at \(\lambda = 0\) the lower-tail probability is already at or below alpha_upper, so the upper limit is undefined (a warning is issued).
(verbose = TRUE) The probability \(P(X \le \mathtt{chi\_square})\) that an observation from the noncentral chi square distribution centered at the row's limit falls at or below the observed chi_square.
(verbose = TRUE) The complementary probability \(P(X \ge \mathtt{chi\_square})\). By construction this equals alpha_lower on the lower_limit row and \(1 - \mathtt{alpha\_upper}\) on the upper_limit row.
The observed chi square value
The desired degree of confidence for a symmetric interval
The degrees of freedom
The proportion of values beyond the lower limit (cannot be used with conf_level)
The proportion of values beyond the upper limit (cannot be used with conf_level)
The convergence tolerance passed to uniroot
If TRUE (the default), the returned data frame additionally reports the achieved tail probabilities at each limit; if FALSE, only term and value are returned
Additional arguments forwarded to uniroot
Ken Kelley [email protected]
Each confidence limit is the noncentrality parameter \(\lambda \ge 0\) of a
noncentral chi square distribution with df degrees of freedom whose
appropriate tail at the observed chi_square contains the requested
probability:
the lower limit satisfies \(P(X \ge \mathtt{chi\_square}) = \mathtt{alpha\_lower}\);
the upper limit satisfies \(P(X \le \mathtt{chi\_square}) = \mathtt{alpha\_upper}\).
The two conditions run in opposite directions in \(\lambda\): the
lower-tail probability \(P(X \le \mathtt{chi\_square})\) is continuous
and strictly decreasing in the noncentrality parameter, so the upper-tail
probability \(P(X \ge \mathtt{chi\_square})\) is continuous and strictly
increasing in it. The lower limit is the \(\lambda\) at which the upper
tail has grown to alpha_lower, and the upper limit is the
\(\lambda\) at which the lower tail has shrunk to alpha_upper.
Each is therefore the unique non-negative root of a one-dimensional
equation, and both are located with uniroot on the
decreasing lower-tail scale; extendInt is used to widen the search
bracket if needed.
Because the noncentrality parameter is bounded below by zero, the lower limit
is set to zero whenever the observed chi_square is smaller than the
alpha_lower critical value of the central chi square distribution
(i.e., the data is consistent with \(\lambda = 0\) at the requested
confidence level). A warning is issued in that case, and the achieved
probabilities reported in the output reflect the actual values at
\(\lambda = 0\).
Symmetrically, when the observed chi_square is so small that even
at \(\lambda = 0\) the lower-tail probability is already at or below
alpha_upper, no \(\lambda \ge 0\) places as much as
alpha_upper mass at or below chi_square; the upper limit is
undefined and is returned as NA, with a warning.
Cumming, G., & Finch, S. (2001). A primer on the understanding, use, and calculation of confidence intervals that are based on central and noncentral distributions. Educational and Psychological Measurement, 61(4), 532--574. tools:::Rd_expr_doi("10.1177/0013164401614002")
Kelley, K. (2007). Confidence intervals for standardized effect sizes: Theory, application, and implementation. Journal of Statistical Software, 20(8), 1--24. tools:::Rd_expr_doi("10.18637/jss.v020.i08")
ci_nc_t, ci_nc_F, stats::pchisq(), stats::qchisq(), uniroot
Other noncentral distribution confidence intervals:
ci_nc_F(),
ci_nc_t()
# A typical call to the function.
ci_nc_chisq(chi_square = 30, conf_level = .95, df = 15)
# A one-sided (upper) confidence interval.
ci_nc_chisq(chi_square = 30, alpha_lower = 0, alpha_upper = .05,
conf_level = NULL, df = 15)
Run the code above in your browser using DataLab