Package {prime}

PRIME: Proportional Inclusive Marginal Effects

Description

The prime package implements the proportional inclusive marginal effects of Cho and Joseph (2026), which estimates model-free variable importance measures from noisy input-output data. It also contains a screening method that can be used for model-free variable selection.

Details

PRIME estimates explained-variance subset values with local-linear neighborhoods, constructs a BIC-gated ridge-start candidate set, applies paired querywise forward and backward calibration, and evaluates proportional marginal effects (Herin et al. 2024) from noise-adjusted risks on the retained coordinates.

The main interface is prime(), which runs coordinate selection, subset-value estimation, and proportional allocation. The supporting interface is prime_screen() for coordinate selection and diagnostic traces without the allocation step. Use summary(fit) or summary(screen) for a concise result summary, and plot(fit) to display variable importance.

Exact subset enumeration grows exponentially with the retained dimension. The ambient dimension affects screening, while the selected dimension determines the final allocation cost. Twinning (Vakayil and Joseph 2022) option is provided to reduce the cost with large-scale data. Fitted objects have concise print, summary, and plot methods.

Acknowledgments

This research is supported by a U.S. National Science Foundation grant DMS-2310637.

Author(s)

Youngseo Cho and V. Roshan Joseph

References

Herin, M., Il Idrissi, M., Chabridon, V., and Iooss, B. (2024). Proportional marginal effects for global sensitivity analysis. SIAM/ASA Journal on Uncertainty Quantification, 12(2), 667–692. doi:10.1137/22M153032X.

Cho, Y. and Joseph, V. R. (2026). Measuring Variable Importance Using Proportional Inclusive Marginal Effects. arXiv:2610.17053. doi:10.48550/arXiv.2610.17053.

Vakayil, A. and Joseph, V. R. (2022). “Data Twinning”. Statistical Analysis and Data Mining: The ASA Data Science Journal, 15, 598-610.

See Also

prime, plot.prime_fit, prime_screen

Plot PRIME Variable Importance

Description

Displays PRIME importance from a fitted result. Retained coordinates are highlighted and excluded coordinates remain visible at zero.

Usage

## S3 method for class 'prime_fit'
plot(x, y = NULL, max_display = 20L,
  main = NULL, xlab = "PRIME importance",
  col = "#087F8C", zero_col = "#A5ADB4", ...)

Arguments

Value

The fitted object, invisibly.

See Also

prime

Examples

set.seed(5)
X <- matrix(runif(960, -1, 1), nrow = 120)
colnames(X) <- paste0("X", seq_len(ncol(X)))
y <- X[, 1] - X[, 2] + X[, 5]^2 + rnorm(120, sd = 0.08)

obj <- prime(X, y)
plot(obj)

Proportional Inclusive Marginal Effects

Description

Estimates Proportional Inclusive Marginal Effects of Cho and Joseph (2026).

Usage

prime(X, y, rescale = TRUE, twin_r = NULL, lambda = 1e-6,
  neighbor_eps = 0, query_block_size = 256L)

Arguments

Details

The function executes BIC-gated ridge-start screening, query-calibrated forward and backward reduction, and proportional allocation (Herin et al. 2024) on the retained total-effect set function. Please see Cho and Joseph (2026) for details.

Exact allocation requires 2^d subset values and d2^{d-1} projection edges for d retained coordinates. The edge-index capacity is checked before subset evaluation; dimensions 28 and above are rejected by the current 32-bit projection indices. Lower dimensions can still be costly in memory and runtime.

Search builds an index in each evaluated coordinate subset and retains all observations in its neighborhood pool. If observations are equally distant from a query point, exact search orders them by their original row numbers. This tie-breaking rule can choose different neighbors from earlier versions that used the FNN package. Query contributions are retained for at most two subset fits; allocation caches scalar risks. Setting neighbor_eps > 0 makes approximation explicit in settings. The default preserves exact distances and the neighborhood size rule.

For retained dimension d, the local neighborhood size is

K_d=\left\lceil\max\{1.5\sqrt n,\,3d\}\right\rceil,

subject to the local-fit feasibility cap. The local nugget is applied to slopes only. Every observation is used as a query by default; Data Twinning reduces the outer query average without removing observations from the neighbor pool.

Exact allocation evaluates 2^d subset values and therefore scales exponentially with the retained dimension.

Use summary(fit) to see retained coordinates, importance estimates, explained variation, and projection diagnostics.

Value

An object of class prime_fit with components:

• call: matched function call;

• effects: full-length, zero-padded PRIME allocation;

• reduced_effects: allocation on retained coordinates;

• selected and selected_names: retained coordinates;

• screen: complete prime_screen result;

• subset_values: raw and projected subset values with complement and noise-adjusted risks;

• signal, noise_floor, and risk_full: estimated explained variation and full retained-set risk;

• projection: monotone-projection diagnostics;

• settings: fixed numerical and statistical settings.

If screening retains no coordinate, effects is a zero vector and subset_values is NULL, indicating that a normalized allocation is unavailable.

References

Herin, M., Il Idrissi, M., Chabridon, V., and Iooss, B. (2024). Proportional marginal effects for global sensitivity analysis. SIAM/ASA Journal on Uncertainty Quantification, 12(2), 667–692.

Cho, Y. and Joseph, V. R. (2026). Measuring Variable Importance Using Proportional Inclusive Marginal Effects. arXiv:2610.17053. doi:10.48550/arXiv.2610.17053.

See Also

plot.prime_fit, prime_screen

Examples

set.seed(5)
X <- matrix(runif(960, -1, 1), nrow = 120)
colnames(X) <- paste0("X", seq_len(ncol(X)))
y <- X[, 1] - X[, 2] + X[, 5]^2 + rnorm(120, sd = 0.08)

fit <- prime(X, y)
fit$selected_names
round(fit$effects, 3)
summary(fit)
plot(fit)

Allocate Precomputed Subset Values

Description

Projects supplied subset values onto the set of nonnegative monotone set functions and evaluates the canonical proportional-value extension by ratio-potential recursion.

Usage

prime_allocate(subset_values, zero_tolerance = sqrt(.Machine$double.eps))

Arguments

Details

The first value is set to zero. The full-set value must be nonnegative and is preserved. Positive-full games are normalized internally, then their allocations and projected values are returned in the supplied units. Ratio potentials are evaluated in log space. A zero-full game projects to zero and returns zero allocations. Input ratios that overflow or underflow during normalization are rejected with a numerical-range error.

The projection convergence tolerance does not snap positive values to zero. The relative null threshold affects only proper nonempty subsets; the empty and full endpoints stay fixed. Thus a threshold of one or greater produces the unanimity game when the full-set value is positive. Projection diagnostics report violations in the supplied game units.

Computation and storage scale exponentially with dimension d. Subset masks permit at most 30 coordinates. The current exact projection also requires its d2^{d-1} Hasse edges to fit 32-bit integer indices, which rejects dimensions 28 and above before projection. Passing this representation check does not guarantee practical memory use or runtime.

Value

A named numeric allocation. The importance values sum to the projected full-set value. Attributes contain:

• projected_values: the nonnegative monotone projection after applying the relative null threshold, in the supplied game units;

• projection: iteration count, convergence flag, and maximum remaining violation.

References

Herin, M., Il Idrissi, M., Chabridon, V., and Iooss, B. (2024). Proportional marginal effects for global sensitivity analysis. SIAM/ASA Journal on Uncertainty Quantification, 12(2), 667–692. doi:10.1137/22M153032X.

Examples

values <- c(0, 0.25, 0.60, 1)
allocation <- prime_allocate(values)
allocation
attr(allocation, "projected_values")

Nonparametric variable selection

Description

This function implements the nonparametric model-free variable selection technique in Cho and Joseph (2026).

Usage

prime_screen(X, y, rescale = TRUE, twin_r = NULL, lambda = 1e-6,
  neighbor_eps = 0, query_block_size = 256L)

Arguments

Details

It constructs a response-relevant candidate set from a BIC-selected prefix of a standardized ridge ordering and a query-calibrated local-linear forward path, and then applies sequential query-calibrated backward reduction. Please see Cho and Joseph (2026) for details.

Search builds an index in each evaluated coordinate subset and retains all observations in its neighbor pool. If observations are equally distant from a query point, exact search orders them by their original row numbers. This tie-breaking rule can choose different neighbors from earlier versions that used the FNN package. Query contributions are retained for at most two subset fits; allocation caches scalar risks. Setting neighbor_eps > 0 makes approximation explicit in settings. The default preserves exact distances and the neighborhood size rule.

The ridge ordering is searched through \lceil1.5\log\{\max(2,p)\}\rceil coordinates, including the intercept-only model, and BIC selects the initial prefix. The local path adds the coordinate with the largest explained-variance gain when its paired querywise calibrated gain is positive. Backward reduction sequentially removes zero calibrated deletion losses and recomputes all projected neighborhoods after every removal.

Ridge ranking and BIC use a centered unit-variance response internally. The reported BIC omits the response-scale constant shared by all candidate models; ridge-path RSS remains in original response units. Paired comparison scales are computed in response-variance units and returned in original units, avoiding overflow or underflow of their empirical variances under changes of units.

Use summary(screen) to see the ridge seed, forward path, retained coordinates, and backward-reduction counts.

Value

An object of class prime_screen with components:

• call: matched function call;

• candidates and candidate_names: inclusive forward set;

• selected and selected_names: backward-cleaned set;

• forward: ridge seed, local path, stopping reason, and trace;

• backward: retained set and deletion-comparison trace;

• settings: neighborhood, query, nugget, and calibration rules.

References

Cho, Y. and Joseph, V. R. (2026). Measuring Variable Importance Using Proportional Inclusive Marginal Effects. arXiv:2610.17053. doi:10.48550/arXiv.2610.17053.

See Also

prime

Examples

set.seed(5)
X <- matrix(runif(960, -1, 1), nrow = 120)
colnames(X) <- paste0("X", seq_len(ncol(X)))
y <- X[, 1] - X[, 2] + X[, 5]^2 + rnorm(120, sd = 0.08)

screen <- prime_screen(X, y)
screen$selected_names
summary(screen)
screen$forward$trace
screen$backward$trace

Summarize a Fitted PRIME Result

Description

Builds and prints a structured summary of a complete PRIME fit.

Usage

## S3 method for class 'prime_fit'
summary(object, ...)

## S3 method for class 'summary_prime_fit'
print(x, digits = 4L, ...)

Arguments

Value

summary.prime_fit() returns a structured list containing the matched call, sample and predictor dimensions, candidate and retained coordinates, a PRIME importance estimate matrix, explained fraction, allocation total, projection diagnostics, and settings. The print method returns this object invisibly.

See Also

prime, plot.prime_fit

Summarize PRIME Screening

Description

Builds and prints a structured summary of the PRIME forward and backward selection stages.

Usage

## S3 method for class 'prime_screen'
summary(object, ...)

## S3 method for class 'summary_prime_screen'
print(x, ...)

Arguments

Value

summary.prime_screen() returns a structured list containing the matched call, sample and predictor dimensions, ridge seed, local path, candidate and retained coordinates, stopping reason, backward evaluation and deletion counts, and settings. The print method returns this object invisibly.

See Also

prime_screen, summary.prime_fit