Finds the noncentrality parameters of a noncentral F-distribution
that bracket an observed F-value with the requested tail
probabilities, giving a confidence interval on the population noncentrality
parameter. Together with ci_nc_t and
ci_nc_chisq, this is one of the low-level
noncentral distribution workhorses on which the ci_* confidence
interval functions (e.g., ci_pvaf, ci_snr,
ci_R2) are built; most analyses reach it through those
functions rather than calling it directly.
The function was conf_limits_ncf() in earlier builds of DMAR and is
conf.limits.ncf() in MBESS; it is named into the ci_* family because a
confidence interval is what it computes.
ci_nc_F(
F_value = NULL,
conf_level = 0.95,
df_1 = NULL,
df_2 = 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 on the upper_limit row when the observed F_value is so small that even at \(\lambda = 0\) the lower-tail probability is already at or below alpha_upper, leaving the upper noncentrality limit undefined (a warning is issued).
(verbose = TRUE) The probability \(P(F \le \mathtt{F\_value})\) that an F-statistic from the noncentral F-distribution centered at the row's limit falls at or below the observed F_value.
(verbose = TRUE) The complementary probability \(P(F \ge \mathtt{F\_value})\). By construction this equals alpha_lower on the lower_limit row and \(1 - \mathtt{alpha\_upper}\) on the upper_limit row.
The observed F-value
The desired degree of confidence for a symmetric interval
The numerator degrees of freedom
The denominator 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 F-distribution with df_1 and df_2 degrees of
freedom whose appropriate tail at the observed F_value contains the
requested probability:
the lower limit satisfies \(P(F \ge \mathtt{F\_value}) = \mathtt{alpha\_lower}\);
the upper limit satisfies \(P(F \le \mathtt{F\_value}) = \mathtt{alpha\_upper}\).
The two conditions run in opposite directions in \(\lambda\): the
lower-tail probability \(P(F \le \mathtt{F\_value})\) is continuous and
strictly decreasing in the noncentrality parameter, so the upper-tail
probability \(P(F \ge \mathtt{F\_value})\) 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 F_value is smaller than the
alpha_lower critical value of the central F-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\) rather
than the requested alpha_lower. The warning carries the condition
class dmar_nc_F_clamp, so a caller that inverts the noncentral
F repeatedly can muffle or deduplicate it by class.
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")
ss_aipe_R2, ci_R2, ci_nc_t, ci_nc_chisq, stats::pf(), stats::qf(), uniroot
Other noncentral distribution confidence intervals:
ci_nc_chisq(),
ci_nc_t()
ci_nc_F(F_value = 5, conf_level = .95, df_1 = 5, df_2 = 100)
# A one-sided (upper) confidence interval.
ci_nc_F(F_value = 5, conf_level = NULL, df_1 = 5, df_2 = 100,
alpha_lower = 0, alpha_upper = .05)
Run the code above in your browser using DataLab