nsca_thresholds: Dual thresholds and the necessity-sufficiency interval

In NSCA: Necessary and Sufficient Condition Analysis

Dual thresholds and the necessity-sufficiency interval

Description

For every outcome level, reports the necessity and sufficiency thresholds and the direction-oriented distance between them.

Usage

nsca_thresholds(
  model,
  ceiling = NULL,
  x = NULL,
  scale = NULL,
  outcome_scale = NULL,
  convention = NULL,
  inequality = c("strict", "inclusive"),
  digits = 6L,
  legacy = FALSE,
  boundary = NULL
)

Arguments

model	An object returned by nsca_analysis().
ceiling	A single frontier technique, applied to both sides.
x	Optional condition names or positions.
scale, outcome_scale	Reporting scales, defaulting to those requested in nsca_analysis(). See SCAtools::sca_scales().
convention	"absolute" or "directional".
inequality	Strict or inclusive inequalities. Renamed from boundary in 0.4.0, which is reserved for the theoretical line an expected empty space is separated by.
digits	Significant digits in the formatted text.
legacy	Append the column names retired in 0.3.0 and 0.4.0 as duplicates. See nsca_legacy_names().
boundary	Deprecated. Former name of inequality.

Details

For a fixed outcome target, the necessity-sufficiency interval is the distance on the condition axis between the two thresholds: if a target requires at least 40 units of the condition but 70 units are enough for it, the interval runs from 40 to 70. It is not a confidence interval: it carries no statistical uncertainty.

necessity_sufficiency_interval and overlap_width are reported on scale, the same scale as the two threshold columns they are the distance between, so a row can be checked by subtraction. necessity_sufficiency_interval_actual and overlap_width_actual keep the same two quantities in the units of the data whatever scale is asked for, and threshold_gap_actual is the signed actual-unit gap the pair is split from. Before 0.4.3 the two unsuffixed columns held actual units on every scale, which put three columns of two different kinds in one printed row.

Under scale = "percentile" the reported column is a difference of ranks rather than a distance, so it reads as the share of cases lying between the two thresholds. That is a useful quantity, but it is not a width: equal percentile gaps in a dense and in a sparse part of the distribution stand for very different distances on the condition axis. For a normalised width that is comparable across studies use "percentage.range" or "sd".

The interval is also distinct from the component effect sizes. Effect sizes aggregate exclusion over the whole scope, whereas the interval is read at one outcome target, so large component effects do not guarantee a narrow interval at any particular level and a narrow interval at one target says nothing about the others. Reporting both, at several targets, is not redundant.

Value

A data frame with one row per condition and outcome level.

The three regions

Necessity and sufficiency answer different questions about the same outcome level, and together they cut the condition axis into three parts. For a high-X direction:

below necessity_threshold

The outcome level is out of reach.

between the two thresholds

It is admitted but not guaranteed. This is the admissible interval, and necessity_sufficiency_interval is its width. It is the horizontal cross-section, at one outcome level, of the region whose area admissible_region_share reports.

above sufficiency_threshold

The fitted frontier guarantees it.

For a low-X direction these inequalities reverse: values above the necessity threshold are out of reach and values below the sufficiency threshold are guaranteed. threshold_gap_actual is direction-oriented, so a positive value means an admitted interval in all four directions. A negative value is reported as "frontiers overlap" in threshold_status, with its magnitude in overlap_width and overlap_width_actual, rather than being silently truncated to zero: the two thresholds are then mutually incompatible at that level, which is a modelling problem and not a narrow admissible interval.

The interval collapses to zero exactly where the relation is deterministic at that level, reported as "exact correspondence": one X value is then both the minimum required and the sufficient level. An estimated interval of zero is consistent with exact correspondence but does not by itself establish it, and a small non-zero interval should be called near correspondence only when a substantively justified tolerance has been defined. A positive interval does not negate joint support; it indicates imperfect threshold correspondence. Neither NCA nor SCA alone can produce this table: each supplies one edge of the interval.

The two out-of-range markers read differently on the two sides, because their meaning inverts under contraposition. On the necessity side they keep their necessity reading, giving "no_minimum", "no_maximum" and "unattainable"; on the sufficiency side SCAtools supplies the sufficiency reading.

See Also

nsca_table(), nsca_analysis(), nsca_legacy_names()

Examples

set.seed(1)
x <- sort(runif(60))
dat <- data.frame(X = x, Y = pmin(pmax(x + rnorm(60, 0, 0.1), 0), 1))
fit <- nsca_analysis(dat, "X", "Y", ceilings = "ce_fdh")
nsca_thresholds(fit)

NSCA documentation built on Oct. 10, 2026, 5:08 p.m.