Type:	Package
Title:	Distribution-Free Goodness-of-Fit Testing for Regression
Version:	1.1
Depends:	R (≥ 4.4)
Imports:	calculus, clue, lme4, methods
Suggests:	knitr, rmarkdown
VignetteBuilder:	knitr, rmarkdown
Date:	2025-07-01
Maintainer:	Jesse Miller <mill9116@umn.edu>
Description:	Implements the distribution-free goodness-of-fit regression test for the mean structure of parametric models introduced in Khmaladze (2021) <doi:10.1007/s10463-021-00786-3>. The test is implemented for general functions with minimal distributional assumptions as well as common models (e.g., lm, glm) with the usual assumptions.
License:	GPL-3
NeedsCompilation:	no
Packaged:	2025-06-30 22:31:17 UTC; Jesse
Author:	Jesse Miller [aut, cre]
Repository:	CRAN
Date/Publication:	2025-07-02 09:00:12 UTC

Distribution-Free Goodness-of-Fit Testing for Regression

Description

Implements the distribution-free goodness-of-fit regression test for the mean structure of parametric models introduced in Khmaladze (2021) <doi:10.1007/s10463-021-00786-3>. The test is implemented for general functions with minimal distributional assumptions as well as common models (e.g., lm, glm) with the usual assumptions.

Details

The DESCRIPTION file:

Index of help topics:

asymptotics             Convenience function for exploring asymptotic
                        behavior and sample size adequacy
coef.distfreereg        Extract estimated parameters from 'distfreereg'
                        objects
compare                 Compare the simulated statistic distribution
                        with the observed statistic distribution used
                        in distribution-free parametric regression
                        testing
confint.distfreereg     Calculate confidence intervals with a
                        'distfreereg' object
distfreereg             Distribution-free parametric regression testing
distfreereg-package     Distribution-Free Goodness-of-Fit Testing for
                        Regression
fitted.distfreereg      Extract fitted values from 'distfreereg'
                        objects
formula.distfreereg     Extract formulas from 'distfreereg' objects
ks.test.compare         Formally compare observed and simulated
                        statistics from a 'compare' object
plot.compare            Summary and diagnostic plots for 'compare'
                        objects
plot.distfreereg        Summary and diagnostic plots for 'distfreereg'
                        objects
predict.distfreereg     Generate predicted values from 'distfreereg'
                        objects
print.compare           Printing 'compare' objects
print.distfreereg       Printing 'distfreereg' objects
rejection               Compute rejection rates of a distribution-free
                        test from a 'compare' object
residuals.distfreereg   Extract residuals from 'distfreereg' objects
update.distfreereg      Update 'distfreereg' objects
vcov.distfreereg        Calculate parameter covariance matrices from
                        'distfreereg' objects

Further information is available in the following vignettes:

Author(s)

Jesse Miller [aut, cre] (ORCID: <https://orcid.org/0009-0005-9465-7461>)

Maintainer: Jesse Miller <mill9116@umn.edu>

Convenience function for exploring asymptotic behavior and sample size adequacy

Description

This is a convenience function that calls compare using object to create the true and test model specifications.

Usage

	asymptotics(object, ...)

Arguments

Details

An important step in implementing distfreereg is determining the plausibility that the sample size of a data set is adequate to produce the desired asymptotic behavior of the simulated statistics. This can be done by calling compare with the appropriate argument values. Because of the importance of this step, this convenience function automates that call using a single argument, namely the object of class distfreereg in question.

Value

Object of class compare.

Warning

The fitted model in object is assumed to be the true model, not an estimation of the true model. Further, the simulation of values requires assuming a particular error distribution. See the "Warnings" section in compare's documentation for details.

Author(s)

Jesse Miller

See Also

distfreereg, compare

Extract estimated parameters from distfreereg objects

Description

This is a coef method for objects of class distfreereg. It extracts the estimated parameters from a model in a distfreereg object.

Usage

	## S3 method for class 'distfreereg'
coef(object, ...)

Arguments

Value

Numeric vector of estimated model parameters.

Author(s)

Jesse Miller

See Also

distfreereg, vcov.distfreereg, confint.distfreereg

Compare the simulated statistic distribution with the observed statistic distribution used in distribution-free parametric regression testing

Description

Simulate response data repeatedly with true_mean as the mean and true_covariance as the covariance structure, each time running distfreereg on the simulated data. The observed statistics and p-values are saved, as are the simulated statistics from the first replication.

See the Comparing Distributions with the distfreereg Package vignette for an introduction.

Usage

	compare(true_mean, true_method = NULL, true_method_args = NULL, true_covariance,
	true_X = NULL, true_data = NULL, theta = NULL, n = NULL, reps = 1e3,
	prog = reps/10, simulate_args = NULL, err_dist_fun = NULL,
	err_dist_args = NULL, keep = NULL, manual = NULL, update_args = NULL,
	global_override = NULL, ...)

Arguments

Details

This function allows the user to explore the asymptotic behavior of the distributions involved in the test conducted by distfreereg. If the sample size is large enough and the true covariance matrix of the errors is known or is estimated well enough, then the observed and simulated statistics have nearly the same distribution. How large the sample size must be depends on the details of the situation. This function can be used to determine how large the sample size must be to obtain approximately equal distributions, and to estimate the power of the test against a specific alternative.

The user specifies a particular true model which is used to generate outcome values. There are three cases:

• When true_mean is a function, this function determines the mean of the outcome values and err_dist_fun is used to generate errors. The error-generating function will usually include an element of true_covariance as an argument, and in that case must accept the appropriate class of object. For example, if the true covariance is a list of matrices corresponding to a block-diagonal covariance matrix, then err_dist_fun must accept such a list as an argument.

• When true_mean is an nls object, or when it is a formula and true_method is "nls", the function determined by the formula (in the model call or user-specified, respectively) is used to determine the mean function, and err_dist_fun generates the errors.

• When true_mean is a model object that is not an nls object, or a formula and method is not "nls", then simulate is used to generate outcome values.

If none of these cases apply to true_mean, then compare() cannot be used. (E.g., true_mean cannot be a glm object fitted using a "quasi" family, because simulate does not work for that family.)

The user also specifies arguments to pass to distfreereg, most notably a model to test comprising a mean function test_mean and a covariance structure specified by covariance. For each repetition, compare sends the simulated data, as Y or as part of data, to distfreereg.

The true_covariance argument specifies the covariance structure that is available to err_dist_fun for generating errors. The needs of err_dist_fun can vary (for example, the default function uses SqrtSigma to generate multivariate normal errors), so any one of the elements Sigma, SqrtSigma, P, and Q (defined in the documentation of distfreereg) can be specified. Any element needed by err_dist_fun is calculated automatically if not supplied.

The value of err_dist_fun must be a function whose output is a numeric matrix with n rows and reps columns. Each column is used as the vector of errors in one repetition. The error function's arguments can include the special values n, reps, Sigma, SqrtSigma, P, and Q. These arguments are automatically assigned their corresponding values from the values passed to compare. For example, the default value rmvnorm uses SqrtSigma to generate multivariate normal values with mean 0 and covariance Sigma.

The argument keep is useful for diagnosing problems, but caution should be used lest a very large object be created. It is often sufficient to save the distfreereg objects from only the first few replications.

For more specialized needs, the manual argument allows the calculation and saving of objects during each repetition. For example, using manual = function(x) residuals(x) will save the (raw) residuals from each repetition.

The first repetition creates a distfreereg object. During each subsequent repetition, this object is passed to update.distfreereg to create a new object. The update_args argument can be used to modify this call.

If necessary, global_override can be used to pass an override argument to distfreereg in each repetition. For example, using gobal_override = list(theta_hat = theta) forces the estimated parameter vector used in the test in each call to be the true parameter vector theta.

Value

An object of class compare with the following components:

Warnings

The generation of new outcome values requires specifying an error distribution. The default behavior when true_mean is a function, an nls object, or a formula with method equal to "nls" is to use a multivariate normal error distribution, but different error-generating functions can be defined by the user. When true_mean is a model object that is not an nls object, or a formula and method is not "nls", then the errors are generated using simulate and are therefore distributed according to that function's specifications.

In short, the asymptotic behavior is determined for a specific (true) error distribution, even though the test itself is distribution-free.

Note

Some of the processing of the elements of true_covariance is analogous to the processing of covariance by distfreereg. Any values of solve_tol and symmetric specified in distfreereg's control argument are used by compare to similar effect in processing true_covariance.

Support for glm objects is limited to those created using a family that has a simulate element.

The presence of call in the value allows a compare object to be passed to update.

Author(s)

Jesse Miller

See Also

asymptotics, distfreereg, rejection, plot.compare, ks.test.compare

Examples

set.seed(20240201)
n <- 100
func <- function(X, theta) theta[1] + theta[2]*X[,1]
Sig <- rWishart(1, df = n, Sigma = diag(n))[,,1]
theta <- c(2,5)
X <- matrix(rexp(n, rate = 1))
# In practice, 'reps' should be much larger
cdfr <- compare(true_mean = func, true_X = X, true_covariance = list(Sigma = Sig),
                test_mean = func, X = X, covariance = list(Sigma = Sig),
                reps = 10, prog = Inf, theta = theta, theta_init = rep(1, length(theta)))

cdfr$p

Calculate confidence intervals with a distfreereg object

Description

This is a confint method for objects of class distfreereg. It calculates confidence intervals for the estimated parameters of a model in a distfreereg object.

Usage

	## S3 method for class 'distfreereg'
confint(object, parm, level = 0.95, ...)

Arguments

Details

When object contains a model object (either in the test_mean or model element), then this model is sent to confint. Otherwise, object is sent to confint.default.

Value

The output from the appropriate confint method.

Note

If object was created by calling distfreereg.default directly, there is no estimated parameter vector, and therefore confint.distfreereg does not apply.

Author(s)

Jesse Miller

See Also

distfreereg, vcov.distfreereg, confint

Distribution-free parametric regression testing

Description

Conduct distribution-free parametric regression testing using the process introduced in Khmaladze (2021). A parametric model for the conditional mean (specified by test_mean) is checked against the data by fitting the model, transforming the resulting residuals, and then calculating a statistic on the empirical partial sum process of the transformed residuals. The statistic's null distribution can be simulated in a straight-forward way, thereby producing a p-value.

Using f to denote the mean function being tested, the specific test has the following null and alternative hypotheses:

H_0\colon\ \exists\theta\in\Theta\subseteq\mathbb R^p \mathrel{\bigl|} \textrm{E}(Y| X)=f(X;\theta) \quad\hbox{against}\quad H_1\colon\ \forall\theta\in\Theta\subseteq\mathbb R^p \mathrel{\bigl|} \textrm{E}(Y| X)\neq f(X;\theta).

This assumes a known or adequately accurately estimated covariance matrix. See the An Introduction to the distfreereg Package vignette for an introduction.

Usage

	distfreereg(test_mean, ordering = "simplex", group = TRUE,
	stat = c("KS", "CvM"), B = 1e4, control = NULL, override = NULL, verbose = TRUE,
	...)

	## Default S3 method:
distfreereg(test_mean = NULL, ordering = "simplex", group = TRUE,
	stat = c("KS", "CvM"), B = 1e4, control = NULL, override = NULL, verbose = TRUE,
	..., Y, X = NULL, covariance, J, fitted_values)

	## S3 method for class 'formula'
distfreereg(test_mean, ordering = "simplex", group = TRUE,
	stat = c("KS", "CvM"), B = 1e4, control = NULL, override = NULL, verbose = TRUE,
	..., data, method, method_args = NULL)

	## S3 method for class 'function'
distfreereg(test_mean, ordering = "simplex", group = TRUE,
	stat = c("KS", "CvM"), B = 1e4, control = NULL, override = NULL, verbose = TRUE,
	..., Y, X = NULL, covariance, theta_init)

	## S3 method for class 'glm'
distfreereg(test_mean, ordering = "simplex", group = TRUE,
	stat = c("KS", "CvM"), B = 1e4, control = NULL, override = NULL, verbose = TRUE,
	...)

	## S3 method for class 'lm'
distfreereg(test_mean, ordering = "simplex", group = TRUE,
	stat = c("KS", "CvM"), B = 1e4, control = NULL, override = NULL, verbose = TRUE,
	...)

	## S3 method for class 'lmerMod'
distfreereg(test_mean, ordering = "simplex", group = TRUE,
	stat = c("KS", "CvM"), B = 1e4, control = NULL, override = NULL, verbose = TRUE,
	...)

	## S3 method for class 'nls'
distfreereg(test_mean, ordering = "simplex", group = TRUE,
	stat = c("KS", "CvM"), B = 1e4, control = NULL, override = NULL, verbose = TRUE,
	...)

Arguments

Details

This function implements distribution-free parametric regression testing. The model is specified by a mean structure and a covariance structure.

The mean structure is specified by the argument test_mean. This can be an object of class function, formula, glm, lm, lmerMod, or nls. It can also be NULL.

If test_mean is a function, then it must have one or two arguments: either theta only, or theta and either X (uppercase) or x (lowercase). An uppercase X is interpreted in the function definition as a matrix, while a lowercase x is interpreted as a vector. (See examples and this vignette.) The primary reason to use a lowercase x is to allow for a function definition using an R function that is not vectorized. In general, an uppercase X should be preferred for speed.

If test_mean is a formula, then it must be a formula that can be passed to glm, lm, lmer, or nls, and the data argument must be specified. The appropriate model is created and is then sent to distfreereg() for method dispatch.

The function method estimates parameter values, and then uses those to evaluate the Jacobian of the mean function and to calculate fitted values.

All of these methods create a Jacobian matrix and a vector of fitted values. These, along with the covariance structure, are sent the default method. The default method also allows the user to implement the algorithm even when the mean structure is not specified in R, as long as the Jacobian, fitted values, and covariance structure can be imported. (This is useful if a particularly complicated function is defined in another language and cannot easily be copied into R.)

The covariance structure for Y|X must be specified using the covariance argument for the function and default methods. For other methods, the covariance is estimated automatically.

Any element of covariance can be a numeric matrix, a list of numeric matrices, or a numeric vector. If it is a vector, its length must be either 1 or the sample size. This option is mathematically equivalent to setting a covariance list element to a diagonal matrix with the specified value(s) along the diagonal. Using vectors, when possible, is more efficient than using the corresponding matrix. If an element of covariance is a list of numeric matrices, then these matrices are interpreted as the blocks of a block diagonal matrix.

Internally, distfreereg() only needs Q, so some efficiency can be gained by supplying that directly when available. When Q is not specified, it is calculated using whichever element is specified. When more than one of the other elements are specified, Q is calculated using the least expensive path, with no warning given if the specified elements are incompatible. (For example, if both Sigma and SqrtSigma elements are supplied to covariance, then Q is calculated using SqrtSigma with no attempt to verify that SqrtSigma is the matrix square root ofSigma.)

The override argument is used primarily by update.distfreereg to avoid unnecessary and potentially computationally expensive recomputation. This update method imports appropriate values automatically from a previously created object of class distfreereg, and therefore validation is not always done. Use manually with caution.

The res_order element of override must be a vector of integers from 1 to n (the sample size) that determines the order of the residuals to use when forming the empitical partial sum process. Elements of the vector can be repeated, in which case the residuals corresponding to matching res_order values are grouped when group is TRUE.

Value

An object of class distfreereg with the following components:

Warnings

Methods for model objects (e.g., lm objects) are intended to be used with objects created using a data argument that contains all variables used by the model. This data argument is assumed to be defined in the same environment as the model object, and this is assumed to be the environment in which distfreereg() is called.

Consistency between test_mean and theta_init is verified only indirectly. Uninformative errors can occur when, for example, theta_init does not have the correct length. The most common error message that arises in this case is "f_out cannot have NA values", which occurs when theta_init is too short. To be safe, always define test_mean to use every element of theta.

No verification of consistency is done when multiple elements of coviariance are specified. For example, if P and Sigma are both specified, then the code will use only one of these, and will not verify that P is the inverse of Sigma.

When using the control argument element optimization_fun to specify an optimization function other than optim, the verification that theta_hat_name actually matches the name of an element of the optimization function's output is done only after the optimization has been done. If this optimization will likely take a long time, it is important to verify the value of theta_hat_name before running distfreereg().

The default values of sym_tol and sym_tol1 are intended to check for substantial asymmetry such as would be caused by the user inputting the wrong matrix. Therefore, they do not check for symmetry with high precision. In particular, these default values are orders of magnitude larger than the default values in isSymmetric.

Non-null values for weights argument in glm are not supported.

Author(s)

Jesse Miller

References

Khmaladze, Estate V. Distribution-free testing in linear and parametric regression, 2021-03, Annals of the Institute of Statistical Mathematics, Vol. 73, No. 6, p. 1063–1087. doi:10.1007/s10463-021-00786-3

See Also

coef.distfreereg, confint.distfreereg, fitted.distfreereg, formula.distfreereg, plot.distfreereg, predict.distfreereg, print.distfreereg, residuals.distfreereg, update.distfreereg, vcov.distfreereg

Examples

set.seed(20240218)
n <- 1e2
func <- function(X, theta) X[,1]^theta[1] + theta[2]*X[,2]
Sig <- runif(n, min = 1, max = 3)
theta <- c(2,5)
X <- matrix(runif(2*n, min = 1, max = 5), nrow = n)
Y <- X[,1]^theta[1] + theta[2]*X[,2] + rnorm(n, sd = sqrt(Sig))
(dfr <- distfreereg(Y = Y, X = X, test_mean = func,
                    covariance = list(Sigma = Sig),
                    theta_init = c(1,1)))

# Same test with lowercase "x" for reference; use uppercase whenever possible
func_lower <- function(x, theta) x[1]^theta[1] + theta[2]*x[2]
(dfr_lower <- distfreereg(Y = Y, X = X, test_mean = func_lower,
                          covariance = list(Sigma = Sig),
                          theta_init = c(1,1)))

Extract fitted values from distfreereg objects

Description

This is a fitted method for objects of class distfreereg.

Usage

	## S3 method for class 'distfreereg'
fitted(object, ...)

Arguments

Value

Numeric vector of fitted values.

Author(s)

Jesse Miller

See Also

distfreereg

Extract formulas from distfreereg objects

Description

This is a formula method for objects of class distfreereg. It extracts the formula from a model in a distfreereg object.

Usage

	## S3 method for class 'distfreereg'
formula(x, ...)

Arguments

Value

Formula extracted from x$test_mean, or NULL if such a formula cannot be extracted.

Author(s)

Jesse Miller

See Also

distfreereg

Formally compare observed and simulated statistics from a compare object

Description

This is a ks.test method for objects of class compare. It performs a two-sample Kolmogorov–Smirnov test to compare the observed and simulated statistics in an object of class compare.

Usage

	## S3 method for class 'compare'
ks.test(x, ..., stat = NULL)

Arguments

Details

When stat is NULL, the default value is the first statistic appearing in the observed_stats element of object.

Value

A list of the form specified in ks.test.

Author(s)

Jesse Miller

See Also

compare, distfreereg, ks.test

Examples

# In practice, set "reps" larger than 200.
set.seed(20240201)
n <- 100
func <- function(X, theta) theta[1] + theta[2]*X[,1]
Sig <- rWishart(1, df = n, Sigma = diag(n))[,,1]
theta <- c(2,5)
X <- matrix(rexp(n, rate = 1))
cdfr <- compare(true_mean = func, true_X = X, true_covariance = list(Sigma = Sig),
                test_mean = func, X = X, covariance = list(Sigma = Sig), reps = 200,
                prog = Inf, theta = theta, theta_init = rep(1, length(theta)))

ks.test(cdfr)
ks.test(cdfr, stat = "CvM")

Summary and diagnostic plots for compare objects

Description

This is a plot method for objects of class compare. It automates the creation of four summary and diagnostic plots for compare objects. See the Plotting with the distfreereg Package vignette for examples.

Usage

	## S3 method for class 'compare'
plot(x, y, ..., which = "cdf", stat = NULL, hlines = NULL, curve_args = NULL,
	confband_args = FALSE, density_args = NULL, poly = NULL, legend = NULL,
	qqline = NULL)

Arguments

Details

This function produces a plot of a type specified by which. The values plotted depend on whether or not y is present and the value of which. When y is present, the plots compare the observed statistics in x and the observed statistics in y. When y is missing, the plots compare the observed and simulated statistics in x. (The exception is when which is "qqp", which is only available when y is missing.)

When which is "cdf" or "dens", the plotting region and associated labels, tick marks, etc., are created by an initial call to plot. The curves themselves are drawn with lines. The arguments specified in ... are passed to the initial call to plot.

Value

The values used to create the curves (or points, in the case of a Q–Q plot) are returned invisibly. The details depend on the value of which:

• cdf: A list with two or four elements, all lists. The first two sub-lists contain the x- and y-values cdf curves. If confidence bands are plotted, then two additional elements are included with output from the confidence band calculations, including elements w, cb_lower, and cb_upper, which contain, respectively, the x-coordinates for both the upper and lower bounds of the band, the y-coordinates for the lower band, and the y-coordinates for the upper band.

• dens: A list with two or four elements, all lists. The first two sub-lists contain x- and y-values for the density curves. If confidence bands are plotted, then two additional sub-lists are supplied, with contents identical to what is described for "cdf".

• qq, qqp: The output of qqplot.

For "cdf" and "dens", the names of the elements of the returned list depend on whether or not a value for the argument y was supplied.

Author(s)

Jesse Miller

References

Flegal, James M. et al. Simultaneous confidence bands for (Markov chain) Monte Carlo simulations, forthcoming.

See Also

distfreereg, compare

Summary and diagnostic plots for distfreereg objects

Description

This is a plot method for objects of class distfreereg. It automates the creation of three summary and diagnostic plots for distfreereg objects. See the Plotting with the distfreereg Package vignette for examples.

Usage

	## S3 method for class 'distfreereg'
plot(x, which = "dens", stat = NULL, density_args = NULL, polygon_args = NULL,
	confband_args = NULL, abline_args = NULL, shade_col = rgb(1,0,0,0.5),
	text_args = NULL, ...)

Arguments

Details

This function produces one of three specified plots, depending on the value of which.

When which is "dens", a plot of the estimated density of the simulated statistics is produced, including a vertical line at the value of the observed test statistic with the p-value displayed.

The default placement of the p-value text is on the left side of the line indicating the statistic value. Specifically, the default values of x and y passed to text are the statistic value itself and the midpoint between zero and the maximum value of the density curve. The default value passed to adj is c(1,0.5), meaning that the text is aligned to the left of the value (x,y) and centered vertically on it. (The default value for the text itself, which can be modified via the label argument of text, includes a space on the left and the right for padding so the text does not overlap the vertical line itself.) To align the text so it appears on the right side (for example, to avoid overlapping the density curve), use text_args = list(adj = c(0,0.5)). See documentation for text for details on this and other arguments.

When which is "residuals", a time-series-like plot is produced showing transformed residuals in the order given by x$res_order. In the case that the null hypothesis is rejected, this plot can help determine where (in terms of the linearly ordered covariates) a discrepancy between the model and the data occurs.

When which is "epsp", a plot of the empirical partial sum process is produced; that is, the y-values are

y_j = {1\over\sqrt{n}}\sum_{i=1}^j\hat e_i

where \hat e_i is the ith transformed residual in the order given by x$res_order. Similar to the case when which is "residuals", this plot can help determine where (in terms of the linearly ordered covariates) a discrepancy between the model and the data occurs.

Value

When which is "dens", the values used to create the density plot are returned invisibly in a list with two named elements, x and y. If the confidence band is plotted, then it is included as an element named confband.

For other values of which, nothing is returned.

Author(s)

Jesse Miller

References

Flegal, James M. et al. Simultaneous confidence bands for (Markov chain) Monte Carlo simulations, forthcoming.

See Also

distfreereg

Generate predicted values from distfreereg objects

Description

This is a predict method for objects of class distfreereg.

Usage

	## S3 method for class 'distfreereg'
predict(object, ...)

Arguments

Details

When object$test_mean is a model object ("lm", "glm", or "nls"), object$test_mean is sent to predict for method dispatch. When object$test_mean is of class "formula", object$model is sent to predict.

Value

Numeric vector of predicted values.

Author(s)

Jesse Miller

See Also

distfreereg

Printing compare objects

Description

This is a print method for objects of class compare.

Usage

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

Arguments

Details

This function prints a useful summary of the compare object x.

Value

No return value (NULL).

Author(s)

Jesse Miller

See Also

compare

Printing distfreereg objects

Description

This is a print method for objects of class distfreereg.

Usage

	## S3 method for class 'distfreereg'
print(x, ..., digits = 3, col_sep = 2, show_params = TRUE)

Arguments

Details

This function prints a useful summary of the distfreereg object x.

Value

No return value (NULL).

Author(s)

Jesse Miller

See Also

distfreereg

Compute rejection rates of a distribution-free test from a compare object

Description

Compute the rejection rates of the tests simulated in a compare object. Specifically, this function estimates the rejection rates of the tests conducted with specified statistics of the hypothesis that the mean function is test_mean when the true mean function is true_mean.

Usage

	rejection(object, alpha = 0.05, stat = names(object[["observed_stats"]]), ...)

Arguments

Value

Data frame containing estimated rejection rates and associated Monte Carlo standard errors, with one row for each combination of stat and alpha elements.

Warning

The reported Monte Carlo standard error does not account for the uncertainty of the estimation of the 1-\alpha quantiles of the distribution of simulated statistics. The number of Monte Carlo simulations should be large enough to make this estimate sufficiently accurate that it can be considered known for practical purposes. The standard errors of estimated quantiles can be calculated using the mcmcse package.

Author(s)

Jesse Miller

See Also

distfreereg, compare

Examples

# In practice, set "reps" much larger than 20.
set.seed(20240201)
n <- 100
func <- function(X, theta) theta[1] + theta[2]*X[,1]
Sig <- rWishart(1, df = n, Sigma = diag(n))[,,1]
theta <- c(2,5)
X <- matrix(rexp(n, rate = 1))
cdfr <- compare(true_mean = func, true_X = X, true_covariance = list(Sigma = Sig),
                test_mean = func, X = X, covariance = list(Sigma = Sig), reps = 20,
                prog = Inf, theta = theta, theta_init = rep(1, length(theta)))

rejection(cdfr)
rejection(cdfr, stat = "CvM")
rejection(cdfr, alpha = c(0.1, 0.2))

Extract residuals from distfreereg objects

Description

This is a residuals method for objects of class distfreereg. It can extract any of the three available types of residuals.

Usage

	## S3 method for class 'distfreereg'
residuals(object, ..., type = "raw")

Arguments

Value

Numeric vector of residuals.

Author(s)

Jesse Miller

See Also

distfreereg

Update distfreereg objects

Description

This is an update method for objects of class distfreereg. The method takes advantage of the override argument of distfreereg to prevent unnecessary recalculation of potentially computationally expensive objects.

Usage

	## S3 method for class 'distfreereg'
update(object, ..., smart = TRUE, envir = parent.frame())

Arguments

Details

This function updates an object of class distfreereg. By default, it does so "intelligently" in the sense that it does not unnecessarily recompute elements that are already saved in object. For example, if a new value for covariance is not included in ..., then the value of covariance saved in object is automatically passed to the new call, preventing recalculating Q. If a new value of covariance is specified, then all objects dependent on that (e.g., \hat\theta) are recomputed.

In particular, the simulated samples depend on the data and function only through the number of observations, the covariates (if any), and the dimension of the parameter space of the function. If none of these change, then the updated object reuses the simulated samples from the supplied object.

The price paid for this efficiency is a potentially "large" value of call in the updated object.

Value

An updated object of class distfreereg.

Note

The usual behavior of update is to create an updated call and then evaluate that call. This is what update.distfreereg does, as well, but some of the updated elements are drawn from object itself for use as override values. In general, an object created by update.distfreereg is not identical to the object created by distfreereg using corresponding arguments, because the call values will differ.

Author(s)

Jesse Miller

See Also

distfreereg

Examples

set.seed(20240218)
n <- 1e2
func <- function(X, theta) X[,1]^theta[1] + theta[2]*X[,2]
Sig <- runif(n, min = 1, max = 3)
theta <- c(2,5)
X <- matrix(runif(2*n, min = 1, max = 5), nrow = n)
Y <- X[,1]^theta[1] + theta[2]*X[,2] + rnorm(n, sd = sqrt(Sig))
dfr_1 <- distfreereg(Y = Y, X = X, test_mean = func,
                     covariance = list(Sigma = Sig),
                     theta_init = c(1,1))

func_updated <- function(X, theta) X[,1]^theta[1] + theta[2]*X[,2]^2
dfr_2 <- update(dfr_1, test_mean = func_updated)

Calculate parameter covariance matrices from distfreereg objects

Description

This is a vcov method for objects of class distfreereg. It calculates an estimated covariance matrix of the estimated parameters in a model from a distfreereg object.

Usage

	## S3 method for class 'distfreereg'
vcov(object, ..., jacobian_args, hessian_args)

Arguments

Details

When the test_mean element of object is of class function, the covariance matrix is estimated using the method described in section 5.3 of Van der Vaart (2007). Otherwise, test_mean is of a class that has its own method for vcov, which is used to calculate the output.

Value

Named numeric matrix equal to the estimated covariance matrix of the parameter estimates from object.

Warning

This calculation can be computationally intensive when the sample size is large and object$test_mean is a function.

Note

If object was created by calling distfreereg.default directly, there is no estimated parameter vector, and therefore vcov.distfreereg does not apply.

Author(s)

Jesse Miller

References

Vaart, A. W. Asymptotic statistics, 2007, Cambridge series on statistical and probabilistic mathematics, Cambridge University Press.

See Also

distfreereg, confint.distfreereg