Version: 1.0.0
Title: Moment-Matching Approximation for t-Distribution Differences
Description: Implements the moment-matching approximation for differences of non-standardized t-distributed random variables in both univariate and multivariate settings. The package provides density, distribution function, quantile function, and random generation for the approximated distributions of t-differences. The methodology establishes the univariate approximated distributions through the systematic matching of the first, second, and fourth moments, and extends it to multivariate cases, considering both scenarios of independent components and the more general multivariate t-distributions with arbitrary dependence structures. Methods build on the classical moment-matching approximation method (e.g., Casella and Berger (2024) <doi:10.1201/9781003456285>).
License: MIT + file LICENSE
Encoding: UTF-8
RoxygenNote: 7.3.3
Depends: R (≥ 3.5.0)
Imports: stats, mvtnorm
Suggests: testthat (≥ 3.0.0), knitr, rmarkdown
VignetteBuilder: knitr
NeedsCompilation: no
Packaged: 2026-01-23 17:36:41 UTC; API18340
Author: Yusuke Yamaguchi [aut, cre]
Maintainer: Yusuke Yamaguchi <yamagubed@gmail.com>
Repository: CRAN
Date/Publication: 2026-01-27 21:30:17 UTC

Moment-Matching Approximation for General Multivariate t-Differences

Description

Approximates the distribution of differences between two independent multivariate t-distributed random vectors with arbitrary covariance structure.

Usage

mm_tdiff_multivariate_general(mu1, Sigma1, nu1, mu2, Sigma2, nu2)

Arguments

mu1

Location vector of first distribution (length p)

Sigma1

Scale matrix of first distribution (p x p, positive definite)

nu1

Degrees of freedom of first distribution (must be > 4)

mu2

Location vector of second distribution (length p)

Sigma2

Scale matrix of second distribution (p x p, positive definite)

nu2

Degrees of freedom of second distribution (must be > 4)

Details

This function handles the general case where components may be correlated within each multivariate t-distribution. The approximation uses a single scalar degrees of freedom parameter to capture the overall tail behavior.

Note: For high dimensions with heterogeneous component behaviors, consider using mm_tdiff_multivariate_independent instead.

Value

An S3 object of class "mm_tdiff_multivariate_general" containing:

mu_diff

Location vector of difference

Sigma_star

Scale matrix

nu_star

Degrees of freedom (scalar)

method

Character string "multivariate_general"

Examples

Sigma1 <- matrix(c(1, 0.3, 0.3, 1), 2, 2)
Sigma2 <- matrix(c(1.5, 0.5, 0.5, 1.2), 2, 2)
result <- mm_tdiff_multivariate_general(
  mu1 = c(0, 1), Sigma1 = Sigma1, nu1 = 10,
  mu2 = c(0, 0), Sigma2 = Sigma2, nu2 = 15
)
print(result)


Moment-Matching Approximation for Multivariate t-Differences (Independent)

Description

Approximates the distribution of differences between two independent p-dimensional vectors with independent t-distributed components.

Usage

mm_tdiff_multivariate_independent(mu1, sigma1, nu1, mu2, sigma2, nu2)

Arguments

mu1

Location vector of first distribution (length p)

sigma1

Scale vector of first distribution (length p, all > 0)

nu1

Degrees of freedom vector of first distribution (length p, all > 4)

mu2

Location vector of second distribution (length p)

sigma2

Scale vector of second distribution (length p, all > 0)

nu2

Degrees of freedom vector of second distribution (length p, all > 4)

Details

This function applies the univariate moment-matching approximation component-wise when all components are mutually independent. Each component difference Zj = X1j - X2j is approximated independently using the univariate method.

This approach is optimal for:

Value

An S3 object of class "mm_tdiff_multivariate_independent" containing:

mu_diff

Location vector of difference

sigma_star

Vector of scale parameters

nu_star

Vector of degrees of freedom

p

Dimension of the vectors

method

Character string "multivariate_independent"

See Also

mm_tdiff_multivariate_general for correlated components

Examples

result <- mm_tdiff_multivariate_independent(
  mu1 = c(0, 1), sigma1 = c(1, 1.5), nu1 = c(10, 12),
  mu2 = c(0, 0), sigma2 = c(1.2, 1), nu2 = c(15, 20)
)
print(result)


Moment-Matching Approximation for Univariate t-Differences

Description

Approximates the distribution of the difference between two independent non-standardized t-distributed random variables using the moment-matching method.

Usage

mm_tdiff_univariate(mu1, sigma1, nu1, mu2, sigma2, nu2)

Arguments

mu1

Location parameter of first distribution

sigma1

Scale parameter of first distribution (must be > 0)

nu1

Degrees of freedom of first distribution (must be > 4)

mu2

Location parameter of second distribution

sigma2

Scale parameter of second distribution (must be > 0)

nu2

Degrees of freedom of second distribution (must be > 4)

Details

For two independent non-standardized t-distributed random variables:

The difference Z = X1 - X2 is approximated as: Z ~ t(mu1 - mu2, sigma_star^2, nu_star)

where the effective parameters are computed through moment matching:

The method requires nu1 > 4 and nu2 > 4 for the existence of fourth moments. The approximation quality improves as degrees of freedom increase and approaches exactness as nu -> infinity (normal limit).

Value

An S3 object of class "mm_tdiff_univariate" containing:

mu_diff

Location parameter of difference (mu1 - mu2)

sigma_star

Scale parameter

nu_star

Degrees of freedom

input_params

List of input parameters for reference

method

Character string "univariate"

References

Yamaguchi, Y., Homma, G., Maruo, K., & Takeda, K. Moment-Matching Approximation for Difference of Non-Standardized t-Distributed Variables. (unpublished).

See Also

dtdiff, ptdiff, qtdiff, rtdiff for density, distribution function, quantile function, and random generation respectively

Examples

# Example 1: Different scale parameters
result <- mm_tdiff_univariate(
  mu1 = 0, sigma1 = 1, nu1 = 10,
  mu2 = 0, sigma2 = 1.5, nu2 = 15
)
print(result)

# Example 2: Equal parameters (special case)
result_equal <- mm_tdiff_univariate(
  mu1 = 5, sigma1 = 2, nu1 = 20,
  mu2 = 3, sigma2 = 2, nu2 = 20
)
print(result_equal)


Distribution Functions for Multivariate Approximated t-Difference

Description

Distribution Functions for Multivariate Approximated t-Difference

Usage

dmvtdiff(x, mm_result, log = FALSE)

pmvtdiff(q, mm_result, lower.tail = TRUE)

rmvtdiff(n, mm_result)

Arguments

x

Matrix of quantiles (n x p) or vector for single point

mm_result

Result from mm_tdiff_multivariate_general()

log

Logical; if TRUE, returns log density

q

Vector of quantiles (length p) for cumulative probability

lower.tail

Logical; if TRUE (default), probabilities are P(X <= x)

n

Number of observations

Details

These functions implement the distribution functions for the approximated multivariate t-difference based on Theorem 3 from the paper.

**Note on degrees of freedom:**

Value

For dmvtdiff: Numeric vector of density values. For pmvtdiff: Numeric scalar of cumulative probability. For rmvtdiff: Matrix of random samples (n x p).

Examples

# Setup
Sigma1 <- matrix(c(1, 0.3, 0.3, 1), 2, 2)
Sigma2 <- matrix(c(1.5, 0.5, 0.5, 1.2), 2, 2)
result <- mm_tdiff_multivariate_general(
  mu1 = c(0, 1), Sigma1 = Sigma1, nu1 = 10,
  mu2 = c(0, 0), Sigma2 = Sigma2, nu2 = 15
)

# Density at a point
dmvtdiff(c(0, 1), result)

# Density at multiple points
x_mat <- matrix(c(0, 1, -1, 0.5), nrow = 2, byrow = TRUE)
dmvtdiff(x_mat, result)

# Cumulative probability
pmvtdiff(c(0, 1), result)

# Random samples
samples <- rmvtdiff(100, result)
head(samples)


Distribution Functions for Approximated t-Difference

Description

Distribution Functions for Approximated t-Difference

Usage

dtdiff(x, mm_result)

ptdiff(q, mm_result)

qtdiff(p, mm_result)

rtdiff(n, mm_result)

Arguments

x, q

Vector of quantiles

mm_result

Result from mm_tdiff_univariate()

p

Vector of probabilities

n

Number of observations

Value

For dtdiff: Numeric vector of density values. For ptdiff: Numeric vector of cumulative probabilities. For qtdiff: Numeric vector of quantiles. For rtdiff: Numeric vector of random samples from the approximated t-difference distribution.

Examples

result <- mm_tdiff_univariate(0, 1, 10, 0, 1.5, 15)
dtdiff(0, result)
ptdiff(0, result)
qtdiff(c(0.025, 0.975), result)
samples <- rtdiff(100, result)

Validate Moment-Matching Approximation

Description

Validates the approximation quality by comparing moments of the approximated distribution with the theoretical moments.

Usage

validate_approximation(mm_result, n_sim = 10000, seed = NULL)

Arguments

mm_result

Result from any mm_tdiff function

n_sim

Number of simulations for validation (default: 10000)

seed

Random seed for reproducibility

Value

A list containing validation metrics

Examples

result <- mm_tdiff_univariate(0, 1, 10, 0, 1.5, 15)
validation <- validate_approximation(result)
print(validation)