
Transform effect estimates and propagate uncertainty
transform_es.RdApplies a named scalar transformation or a supplied differentiable function.
The original object is retained; specialized variance conventions in
compute_es() are not silently substituted for delta-method propagation.
Usage
transform_es(
x,
transformation,
derivative = NULL,
V = NULL,
target_scale = NULL,
jacobian = NULL,
output_ids = NULL,
conf_level = NULL,
errors = c("collect", "stop")
)
# S3 method for class 'mars_es_transform'
print(x, ...)
# S3 method for class 'mars_es_transform'
as.data.frame(x, row.names = NULL, optional = FALSE, ...)Arguments
- x
A mars_es or mars_es_transform object.
- transformation
One of fisher_z, inverse_fisher, log, exp, logit, inverse_logit, or a function. Custom scalar functions are called once per estimate; with jacobian supplied, the function receives the full vector.
- derivative
Required analytic derivative function for a custom scalar transformation. Not used for named or multivariate transformations.
- V
Optional full sampling covariance matrix on the source scale. Defaults to x$sampling_covariance if available. An unnamed matrix follows source effect order; a named matrix must have both row/column effect IDs and is reordered to match. Its diagonal must agree with any finite source variances. It must be finite, symmetric and positive semidefinite.
- target_scale
Required label (or one label per output) for custom transformations. Named transformations derive labels from the source scale.
- jacobian
Optional analytic Jacobian function for a multivariate custom transformation. It returns an output-by-input matrix. A full V is required; missing covariances are never replaced with zeros.
- output_ids
Optional unique output IDs for a multivariate transformation. Scalar transformations retain source effect IDs.
- conf_level
Confidence level; defaults to the source setting or .95.
- errors
collect returns per-row diagnostics; stop fails on incomplete scalar results. Invalid function definitions or covariance matrices always fail.
- ...
Additional arguments passed to print.data.frame or as.data.frame.
- row.names, optional
Passed to as.data.frame.
Value
A mars_es_transform object with data (transformed estimates, variances and delta-Wald limits), original_result, provenance, diagnostics, settings, and sampling_covariance. Without a full source V, transformed marginal variances are available but sampling_covariance remains NULL.
Details
Scalar variance is \([f'(y_i)]^2v_i\). Multivariate covariance is \(DVD^T\). These are first-order approximations for nonlinear functions. A zero derivative is diagnosed rather than interpreted as zero uncertainty. No generic second- order or bootstrap correction is inferred. Named Fisher transforms require matching correlation/Fisher scales and never mix partial with semipartial r.
For example, transforming COR's variance gives \(1/(n-1)\), not the specialized ZCOR variance \(1/(n-3)\). Transforming SPCOR to Fisher z agrees with ZSPCOR's variance because both use the same semipartial delta formula. All returned intervals are symmetric delta-Wald intervals on the target scale; they differ from transforming source confidence endpoints. The display component of compute_es already provides endpoint back-transformations for interpretation.
Transformations requiring additional uncertain parameters must include those parameters in the input vector and their full covariance in V. The caller must justify cross-metric model assumptions; calculus does not establish them.
References
Oehlert, G. W. (1992). A note on the delta method. The American Statistician, 46(1), 27–29. doi:10.1080/00031305.1992.10475842 .
Examples
x <- compute_es(data.frame(r=.3, n=100), measure="COR",
design="independent_observations", input="correlation", r=r, n_total=n)
transform_es(x, "fisher_z")
#> Delta-method transformations:
#> effect_id yi vi sei ci_lb ci_ub scale
#> 1 0.3095196 0.01010101 0.1005038 0.1125358 0.5065034 fisher_z
#> source_scale status message
#> correlation ok