Skip to contents

Applies 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