Package 'spantest' reference manual

Title:	Mean-Variance Spanning Tests
Description:	Provides a comprehensive suite of portfolio spanning tests for asset pricing, such as Huberman and Kandel (1987) <doi:10.1111/j.1540-6261.1987.tb03917.x>, Gibbons et al. (1989) <doi:10.2307/1913625>, Kempf and Memmel (2006) <doi:10.1007/BF03396737>, Pesaran and Yamagata (2024) <doi:10.1093/jjfinec/nbad002>, and Gungor and Luger (2016) <doi:10.1080/07350015.2015.1019510>.
Authors:	David Ardia [aut, cre] (ORCID: <https://orcid.org/0000-0003-2823-782X>), Benjamin Seguin [aut], Rosnel Sessinou [ctb], Richard Luger [ctb]
Maintainer:	David Ardia <[email protected]>
License:	GPL-3
Version:	1.1-3
Built:	2026-06-07 09:25:07 UTC
Source:	https://github.com/ardiad/spantest

Britten–Jones Tangency-Portfolio Spanning Test (1999)

Description

Tests whether the tangency (maximum Sharpe) portfolio of the augmented universe (benchmarks + test assets) is spanned by the benchmark assets alone. Following Britten–Jones (1999), the statistic arises from a regression of a constant on return differences and yields an $F$ test of the tangency-spanning restriction.

Usage

span_bj(R1, R2)
span_bj(R1, R2)

Arguments

R1

Numeric matrix of benchmark returns, dimension $T \times K$ .

R2

Numeric matrix of test-asset returns, dimension $T \times N$ .

Details

With X formed from pairwise differences, the reference distribution is $F_{N,\ T - ncol(X)}$ ; here ncol(X) = $K + N - 1$ . Finite-sample feasibility requires T - (K + N - 1) >= 1.

Value

A named list with components:

pval: P-value for the $F$ -statistic under the null.
stat: Britten–Jones $F$ -statistic.
H0: Null hypothesis description, "tangency portfolio spanned by benchmark".

References

Britten-Jones M (1999). “The Sampling Error in Estimates of Mean-Variance Efficient Portfolio Weights.” The Journal of Finance, 54(2), 655–671.

Examples

set.seed(321)
R1 <- matrix(rnorm(300), 100, 3)  # benchmarks: T=100, K=3
R2 <- matrix(rnorm(200), 100, 2)  # tests:      T=100, N=2
out <- span_bj(R1, R2)
out$stat; out$pval; out$H0

set.seed(321)
R1 <- matrix(rnorm(300), 100, 3)  # benchmarks: T=100, K=3
R2 <- matrix(rnorm(200), 100, 2)  # tests:      T=100, N=2
out <- span_bj(R1, R2)
out$stat; out$pval; out$H0

F1 Alpha-Spanning Test (Intercepts Only)

Description

Tests the null $H_0:\ \alpha = 0$ that the intercepts of the test assets are jointly zero when regressed on the benchmark assets, i.e., benchmarks span the mean of the test assets. This is the F1 test of Kan & Zhou (2012).

Usage

span_f1(R1, R2)
span_f1(R1, R2)

Arguments

R1

Numeric matrix of benchmark returns, dimension $T \times K$ .

R2

Numeric matrix of test-asset returns, dimension $T \times N$ .

Details

Under standard assumptions (i.i.d. returns, full-rank covariances), the reference distribution is $F_{N,\ T-K-N}$ . Finite-sample feasibility requires $T-K-N \ge 1$ .

Value

A named list with components:

pval: P-value for the $F$ -statistic under the null.
stat: F1 $F$ -statistic.
H0: Null hypothesis description, "alpha = 0".

References

Kan R, Zhou G (2012). “Tests of Mean-Variance Spanning.” Annals of Economics and Finance, 13(1), 145–193.

Examples

set.seed(123)
R1 <- matrix(rnorm(300), 100, 3)  # benchmarks: T=100, K=3
R2 <- matrix(rnorm(200), 100, 2)  # tests:      T=100, N=2
out <- span_f1(R1, R2)
out$stat; out$pval; out$H0

set.seed(123)
R1 <- matrix(rnorm(300), 100, 3)  # benchmarks: T=100, K=3
R2 <- matrix(rnorm(200), 100, 2)  # tests:      T=100, N=2
out <- span_f1(R1, R2)
out$stat; out$pval; out$H0

F2 Variance-Spanning Test (Slopes Only)

Description

Tests the null $H_0:\ \delta = 0$ that adding test assets does not improve the minimum-variance frontier spanned by the benchmarks (variance spanning). The statistic compares frontier-defining quantities of the augmented (benchmark + test) universe to those of the benchmark subset.

Usage

span_f2(R1, R2)
span_f2(R1, R2)

Arguments

R1

Numeric matrix of benchmark returns, dimension $T \times K$ .

R2

Numeric matrix of test-asset returns, dimension $T \times N$ .

Details

Under standard conditions (i.i.d. returns, full-rank covariances), the reference distribution is $F_{N,\ T-K-N+1}$ . Finite-sample feasibility requires $T-K-N+1 \ge 1$ .

Value

A named list with components:

pval: P-value for the $F$ -statistic under the null.
stat: F2 $F$ -statistic.
H0: Null hypothesis description, "delta = 0".

References

Kan R, Zhou G (2012). “Tests of Mean-Variance Spanning.” Annals of Economics and Finance, 13(1), 145–193.

Examples

set.seed(123)
R1 <- matrix(rnorm(300), 100, 3)  # benchmarks: T=100, K=3
R2 <- matrix(rnorm(200), 100, 2)  # tests:      T=100, N=2
out <- span_f2(R1, R2)
out$stat; out$pval; out$H0

set.seed(123)
R1 <- matrix(rnorm(300), 100, 3)  # benchmarks: T=100, K=3
R2 <- matrix(rnorm(200), 100, 2)  # tests:      T=100, N=2
out <- span_f2(R1, R2)
out$stat; out$pval; out$H0

Gungor–Luger Alpha-Only Spanning Test (2016)

Description

Tests the null $H_0:\ \alpha = 0$ that benchmark assets span the mean (intercepts) of the test assets. Following Gungor & Luger (2016), the procedure uses a Monte Carlo (MC) test based on an $F_{\max}$ statistic with residual sign-flip simulations, yielding Least-Favorable (LMC) and Balanced (BMC) MC p-values and a three-way decision rule.

Usage

span_gl_a(R1, R2, control = list())
span_gl_a(R1, R2, control = list())

Arguments

R1

Numeric matrix of benchmark returns, dimension $T \times N$ .

R2

Numeric matrix of test-asset returns, dimension $T \times K$ .

control

List of options:

totsim: Number of MC simulations (default 500).
pval_thresh: Significance level for decisions (default 0.05).
do_trace: Logical; print progress (default TRUE).

Details

Accept if pval_LMC > alpha; Reject if pval_BMC <= alpha; otherwise Inconclusive. The subseries sign-flip MC approach is robust to heteroskedasticity, serial dependence, and heavy tails, making it suitable for high-dimensional settings where classical alpha tests (e.g., GRS) may suffer from size distortions.

Value

A list with components:

pval_LMC: Least-Favorable MC p-value.
pval_BMC: Balanced MC p-value.
stat: Observed $F_{\max}$ statistic.
Decisions: Decision code: 1 = Accept, 0 = Reject, NA = Inconclusive.
Decisions_string: Text label: "Accept", "Reject", or "Inconclusive".
H0: Null hypothesis description, "alpha = 0".

References

Gungor S, Luger R (2016). “Multivariate Tests of Mean-Variance Efficiency and Spanning With a Large Number of Assets and Time-Varying Covariances.” Journal of Business & Economic Statistics, 34(2), 161–175.

Examples

set.seed(1234)
R1 <- matrix(rnorm(300), 100, 3)
R2 <- matrix(rnorm(200), 100, 2)
out <- span_gl_a(R1, R2, control = list(totsim = 100, do_trace = FALSE))
out$Decisions_string; out$pval_LMC; out$pval_BMC

set.seed(1234)
R1 <- matrix(rnorm(300), 100, 3)
R2 <- matrix(rnorm(200), 100, 2)
out <- span_gl_a(R1, R2, control = list(totsim = 100, do_trace = FALSE))
out$Decisions_string; out$pval_LMC; out$pval_BMC

Gungor–Luger Joint Mean–Variance Spanning Test (2016)

Description

Tests the joint null $H_0:\ \alpha = 0,\ \delta = 0$ that benchmark assets span both intercepts and slopes of the test assets, allowing for heteroskedasticity, serial dependence, and time-varying covariances. Following Gungor & Luger (2016), the procedure uses a Monte Carlo (MC) test based on an $F_{\max}$ statistic with residual sign-flip simulations, yielding Least-Favorable (LMC) and Balanced (BMC) MC p-values and a three-way decision rule.

Usage

span_gl_ad(R1, R2, control = list())
span_gl_ad(R1, R2, control = list())

Arguments

R1

Numeric matrix of benchmark returns, dimension $T \times N$ .

R2

Numeric matrix of test-asset returns, dimension $T \times K$ .

control

List of options:

totsim: Number of MC simulations (default 500).
pval_thresh: Significance level for decisions (default 0.05).
do_trace: Logical; print progress (default TRUE).

Details

LMC/BMC follow Gungor & Luger’s MC framework with residual sign-flip draws under the null. The rule is: Accept if pval_LMC > alpha; Reject if pval_BMC <= alpha; otherwise Inconclusive. This approach is robust in high-dimensional and time-varying volatility settings where classical joint spanning tests can be unreliable.

Value

A list with components:

pval_LMC: Least-Favorable MC p-value.
pval_BMC: Balanced MC p-value.
stat: Observed $F_{\max}$ statistic.
Decisions: Decision code: 1 = Accept, 0 = Reject, NA = Inconclusive.
Decisions_string: Text label: "Accept", "Reject", or "Inconclusive".
H0: Null hypothesis description, "alpha = 0 and delta = 0".

References

Examples

set.seed(123)
R1 <- matrix(rnorm(300), 100, 3)
R2 <- matrix(rnorm(200), 100, 2)
out <- span_gl_ad(R1, R2, control = list(totsim = 100, do_trace = FALSE))
out$Decisions_string; out$pval_LMC; out$pval_BMC

set.seed(123)
R1 <- matrix(rnorm(300), 100, 3)
R2 <- matrix(rnorm(200), 100, 2)
out <- span_gl_ad(R1, R2, control = list(totsim = 100, do_trace = FALSE))
out$Decisions_string; out$pval_LMC; out$pval_BMC

Gibbons–Ross–Shanken (GRS) Alpha Spanning Test (1989)

Description

Implements the GRS test of the joint null $H_0:\ \alpha = 0$ in the multivariate regression of test-asset returns on benchmark portfolios (with an intercept). The statistic assumes homoskedastic, normally distributed errors and is most reliable when $T$ is large relative to $K$ (benchmarks) and $N$ (test assets).

Usage

span_grs(R1, R2)
span_grs(R1, R2)

Arguments

R1

Numeric matrix of benchmark returns, dimension $T \times K$ .

R2

Numeric matrix of test-asset returns, dimension $T \times N$ .

Details

Under standard conditions, the reference distribution is $F_{N,\ T-N-K}$ . Finite-sample feasibility requires $T-N-K \ge 1$ .

Value

A named list with components:

pval: P-value for the $F$ -statistic under the null.
stat: GRS $F$ -statistic.
H0: Null hypothesis description, "alpha = 0".

References

Gibbons MR, Ross SA, Shanken J (1989). “A Test of the Efficiency of a Given Portfolio.” Econometrica, 57(5), 1121–1152.

Examples

set.seed(42)
R1 <- matrix(rnorm(300), 100, 3)  # benchmarks: T=100, K=3
R2 <- matrix(rnorm(200), 100, 2)  # tests:      T=100, N=2
out <- span_grs(R1, R2)
out$stat; out$pval; out$H0

set.seed(42)
R1 <- matrix(rnorm(300), 100, 3)  # benchmarks: T=100, K=3
R2 <- matrix(rnorm(200), 100, 2)  # tests:      T=100, N=2
out <- span_grs(R1, R2)
out$stat; out$pval; out$H0

Huberman–Kandel Joint Mean–Variance Spanning Test (1987)

Description

Tests the joint null $H_0:\ \alpha = 0,\ \delta = 0$ that the benchmark assets span the mean–variance frontier of the augmented (benchmark + test) universe. Following Huberman & Kandel (1987), the statistic compares the frontiers with and without the additional assets.

Usage

span_hk(R1, R2)
span_hk(R1, R2)

Arguments

R1

Numeric matrix of benchmark returns, dimension $T \times K$ .

R2

Numeric matrix of test-asset returns, dimension $T \times N$ .

Details

The test evaluates whether adding the test assets changes the efficient frontier implied by the benchmarks. Under standard regularity conditions, the statistic has an $F$ reference with $(2N,\ 2(T-K-N))$ degrees of freedom. Finite-sample feasibility requires $T-K-N \ge 1$ .

Value

A named list with components:

pval: P-value for the $F$ -statistic under the null.
stat: $F$ -statistic value.
H0: Null hypothesis description, "alpha = 0 and delta = 0".

References

Huberman G, Kandel S (1987). “Mean-Variance Spanning.” The Journal of Finance, 42(4), 873–888.

Examples

set.seed(123)
R1 <- matrix(rnorm(300), 100, 3)  # benchmarks: T=100, K=3
R2 <- matrix(rnorm(200), 100, 2)  # tests:      T=100, N=2
out <- span_hk(R1, R2)
out$stat; out$pval; out$H0

set.seed(123)
R1 <- matrix(rnorm(300), 100, 3)  # benchmarks: T=100, K=3
R2 <- matrix(rnorm(200), 100, 2)  # tests:      T=100, N=2
out <- span_hk(R1, R2)
out$stat; out$pval; out$H0

Kempf–Memmel GMVP Spanning Test

Description

Tests whether the Global Minimum Variance Portfolio (GMVP) of the combined (benchmark + test) universe equals the GMVP of the benchmark assets alone. Following Kempf & Memmel (2006), the null assesses whether adding new assets improves the minimum-variance frontier.

Usage

span_km(R1, R2)
span_km(R1, R2)

Arguments

R1

Numeric matrix of benchmark returns, dimension $T \times N$ .

R2

Numeric matrix of test-asset returns, dimension $T \times K$ .

Details

The null hypothesis $H_0$ is that augmenting the benchmark set with the test assets does not change the GMVP weights ( $\Delta = 0$ ), i.e., the GMVP of the full universe coincides with that of the benchmark subset. The test is implemented via a linear restriction on coefficients in an equivalent regression representation, yielding an $F$ -statistic.

Value

A named list with components:

pval: P-value for the F-statistic under the null.
stat: F-statistic value.
H0: Null hypothesis description, "GMVP(bmk) = GMVP(full)".

References

Kempf A, Memmel C (2006). “Estimating the Global Minimum Variance Portfolio.” Schmalenbach Business Review, 58(4), 332–348.

Examples

set.seed(123)
R1 <- matrix(rnorm(300), 100, 3)  # benchmarks: T=100, N=3
R2 <- matrix(rnorm(200), 100, 2)  # tests:      T=100, K=2
ans <- span_km(R1, R2)
ans$pval; ans$stat; ans$H0

set.seed(123)
R1 <- matrix(rnorm(300), 100, 3)  # benchmarks: T=100, N=3
R2 <- matrix(rnorm(200), 100, 2)  # tests:      T=100, K=2
ans <- span_km(R1, R2)
ans$pval; ans$stat; ans$H0

Pesaran–Yamagata Alpha Spanning Test (2024)

Description

Implements the Pesaran–Yamagata test for the joint null that all intercepts are zero in a multi-factor spanning regression with possible cross-sectional dependence across test assets.

Usage

span_py(R1, R2)
span_py(R1, R2)

Arguments

R1

Numeric matrix of benchmark returns, dimension $T \times K$ .

R2

Numeric matrix of test-asset returns, dimension $T \times N$ .

Details

The null hypothesis is that all intercepts are zero ( $\alpha = 0$ ), meaning the benchmark assets span the expected returns of the test assets. The statistic adjusts for cross-sectional dependence via the residual covariance and has an asymptotic $\mathcal{N}(0,1)$ reference under large $T,N$ . Finite-sample safeguards require $T-K-1 > 4$ .

Value

A named list with components:

pval: P-value under the standard normal reference distribution.
stat: Standardized test statistic.
H0: Null hypothesis description, "alpha = 0".

References

Pesaran MH, Yamagata T (2024). “Testing for alpha in linear factor pricing models with a large number of securities.” Journal of Financial Econometrics, 22(2), 407–460.

Examples

set.seed(123)
R1 <- matrix(rnorm(300), 100, 3)  # benchmarks: T=100, K=3
R2 <- matrix(rnorm(200), 100, 2)  # tests:      T=100, N=2
out <- span_py(R1, R2)
out$pval; out$stat; out$H0

set.seed(123)
R1 <- matrix(rnorm(300), 100, 3)  # benchmarks: T=100, K=3
R2 <- matrix(rnorm(200), 100, 2)  # tests:      T=100, N=2
out <- span_py(R1, R2)
out$pval; out$stat; out$H0

Package 'spantest'

Help Index

Britten–Jones Tangency-Portfolio Spanning Test (1999)

Description

Usage

Arguments

Details

Value

References

See Also

Examples

F1 Alpha-Spanning Test (Intercepts Only)

Description

Usage

Arguments

Details

Value

References

See Also

Examples

F2 Variance-Spanning Test (Slopes Only)

Description

Usage

Arguments

Details

Value

References

See Also

Examples

Gungor–Luger Alpha-Only Spanning Test (2016)

Description

Usage

Arguments

Details

Value

References

See Also

Examples

Gungor–Luger Joint Mean–Variance Spanning Test (2016)

Description

Usage

Arguments

Details

Value

References

See Also

Examples

Gibbons–Ross–Shanken (GRS) Alpha Spanning Test (1989)

Description

Usage

Arguments

Details

Value

References

See Also

Examples

Huberman–Kandel Joint Mean–Variance Spanning Test (1987)

Description

Usage

Arguments

Details

Value

References

See Also

Examples

Kempf–Memmel GMVP Spanning Test

Description

Usage

Arguments

Details

Value

References

See Also

Examples

Pesaran–Yamagata Alpha Spanning Test (2024)

Description

Usage

Arguments

Details

Value