Package {Rita}

Anderson-Darling Test

Description

This function computes the one-sample Anderson-Darling test statistic and p-value for fit to a normal distribution.

Usage

ADTest(data, alpha = 0.05, j = 1)

Arguments

Details

An adjusted statistic provided by D'agostino & Stephens (1986) is used, where the mean and variance of the population are treated as unknown. D'agostino & Stephen's (1986) text provides the equations used to obtain the function's p-values.

The modified statistic follows Table 4.7, Case 3, and the p-value follows Table 4.9. Log-CDF and log-survival probabilities are evaluated directly. Standardization uses centered, scaled coordinates. Constant observations, fewer than two non-missing observations, or infinite observations terminate testing with an error. Missing values (NA and NaN) are omitted before calculating the statistic, preserving the existing behavior. This computational requirement does not establish small-sample calibration.

At the approximation breakpoints, 0.20 uses the first formula, 0.34 uses the second, and 0.60 uses the fourth. The statistic and p-value are rounded to three decimals; significance uses the unrounded p-value and alpha / j. The legacy final polynomial remains unchanged pending a separate tail-policy decision. Extrapolation to extreme statistics can yield invalid p-values, including values above one; the returned p-value and significance flag must not be interpreted as calibrated inference in that regime.

Value

An object including the test statistic, p-value, and a significance flag (list)

Precision metadata

Successful computed results also carry a rita_test attribute with the unrounded statistic and p.value, n_tested, precision, calibration and details. It records existing computations without rerunning the test. Legacy list elements, warning behavior and decisions are unchanged. Unsupported or undefined results retain their existing sentinel/NA representation and may lack this attribute. See rita_analysis for reporting conventions.

References

D'agostino, R. B., & Stephens, M. A. (1986). Goodness-of-fit-techniques (Vol. 68). CRC press.

Examples

values <- rnorm(100)
x <- ADTest(data = values)

D'agostino Pearson Omnibus Test

Description

This function computes the D'agostino Pearson omnibus test using adjusted Fisher- Pearson skewness and kurtosis estimators.

Usage

DPTest(data, alpha = 0.05, j = 1, warn = T)

Arguments

Details

The adjusted coefficients use the sample standard deviation in centered, scaled coordinates. They are converted to moment ratios using equations 24-25 of D'Agostino, Belanger and D'Agostino (1990), before constructing the skewness and kurtosis statistics. The omnibus p-value uses the upper tail of a chi-square distribution with two degrees of freedom. The legacy minimum sample size of 8 is retained; the cited kurtosis approximation is intended for N >= 20, so results for N = 8 through 19 issue a warning when warn = TRUE. This range is retained for compatibility, not as a claim of reliable omnibus p-value calibration. The statistic and p-value are returned rounded to three decimal places; significance uses the unrounded p-value.

The kurtosis transform uses a signed real cube root. If the transform's denominator is zero, the observations are constant, or intermediate results are nonfinite, the named statistic, p-value and significance flag are returned as NA, with a warning when warn = TRUE. Missing values (NA and NaN) are omitted before determining sample size, preserving the existing behavior. Infinite observations yield the NA result. A finite statistic alone does not establish calibration for extreme data.

Value

An object including the test statistic, p-value, and a significance flag (list)

Precision metadata

Successful computed results also carry a rita_test attribute with the unrounded statistic and p.value, n_tested, precision, calibration and details. It records existing computations without rerunning the test. Legacy list elements, warning behavior and decisions are unchanged. Unsupported or undefined results retain their existing sentinel/NA representation and may lack this attribute. See rita_analysis for reporting conventions.

References

D'agostino, R. B., & Stephens, M. A. (1986). Goodness-of-fit-techniques (Vol. 68). CRC press.

D'Agostino, R. B., Belanger, A., & D'Agostino, R. B., Jr. (1990). A Suggestion for Using Powerful and Informative Tests of Normality. The American Statistician, 44(4), 316-321. https://doi.org/10.2307/2684359

Shreve, Joni N. and Donna Dea Holland . 2018. SAS® Certification Prep Guide: Statistical Business Analysis Using SAS®9. Cary, NC: SAS Institute Inc.

Examples

values <- rnorm(100)
x <- DPTest(data = values)

Jarque-Bera Test

Description

Tests normality using the adjusted Fisher-Pearson skewness and excess kurtosis.

Usage

JBTest(data, alpha = 0.05, j = 1, N_Sample = 10000, warn = T)

Arguments

Details

With n usable observations and adjusted coefficients G1 and G2, the statistic is (n/6) * (G1^2 + G2^2/4). Both coefficients use the sample standard deviation. NA and NaN are omitted. Numeric matrices and arrays are flattened. Infinite observations and undefined variance for supported sizes signal errors. Below four observations the test terminates with its legacy failure result.

For 4 <= n < 2000 each of N_Sample independent standard-normal samples of size n is standardized using its own mean and sample SD. The Monte Carlo upper-tail p-value is (1 + exceedances)/(N_Sample + 1), counting ties as exceedances. Use set.seed() before calling to reproduce the simulation in the same R RNG configuration. Simulation advances the caller's RNG stream. For n >= 2000 the reference is chi-square with two degrees of freedom. Calibration assumes independent observations from a continuous normal model.

The significance flag uses the unrounded p-value and the strict threshold alpha/j. With 10000 replicates the minimum Monte Carlo p-value is 1/10001, and the approximate simulation standard error at p=0.05 is 0.00218. Small thresholds may require a larger simulation count.

Value

A three-element list of named scalars for the statistic, p-value (both rounded to three decimals), and significance flag. For a simulated result the monte_carlo attribute records n, n_sim, exceedances, min_p and the unrounded p.value. A displayed zero can represent a positive probability below 0.0005. For n < 4 the return is list(rep("F", 3)).

Precision metadata

Successful computed results also carry a rita_test attribute with the unrounded statistic and p.value, n_tested, precision, calibration and details. It records existing computations without rerunning the test. Legacy list elements, warning behavior and decisions are unchanged. Unsupported or undefined results retain their existing sentinel/NA representation and may lack this attribute. See rita_analysis for reporting conventions.

References

Jarque, C. M. and Bera, A. K. (1980). Efficient tests for normality, homoscedasticity and serial independence of regression residuals. Economics Letters, 6(3), pp. 255-259.

Shreve, Joni N. and Donna Dea Holland. 2018. SAS® Certification Prep Guide: Statistical Business Analysis Using SAS®9. Cary, NC: SAS Institute Inc.

Examples

set.seed(42)
x <- JBTest(qnorm(ppoints(40)), warn = FALSE)
attr(x, "monte_carlo")$p.value

Kolmogorov-Smirnov-Lilliefors Test

Description

This function computes the Lilliefors variant of the one-sample Kolmogorov-Smirnov test.

Usage

KSLTest(data, alpha = 0.05, j = 1, warn = T,
  method = "molin-abdi", n_sim = 100000)

Arguments

Details

The default method = "molin-abdi" retains Molin & Abdi's (1998) polynomial and legacy clipping of output outside [0,1]. Clipped values are not exact probabilities; clipping does not imply that the true p-value is below .001 or above .99. No automatic method switch is performed.

Select method = "monte-carlo" as an explicit alternative to clipping. Each of n_sim independent standard-normal samples has the same usable size as data; its mean and sample SD are re-estimated before computing the same D. The upper-tail p-value is (1 + count(D_sim >= D_obs)) / (n_sim + 1). This is normal-null simulation, not resampling the observed data. Use set.seed() before calling for reproducibility; simulation advances R's RNG.

At least four finite, nonconstant observations are required after omitting NA/NaN. Inputs must be numeric vectors. Centering/scaling avoids overflow and underflow where the input differences remain representable. Ties are accepted for statistic calculation; continuous-normal calibration is not established for rounded/discretized observations.

Monte Carlo p-values are returned without three-decimal rounding so that small positive estimates are not reported as zero. The minimum estimate is 1/(n_sim+1), a resolution limit, not proof of the true probability. The monte_carlo attribute records usable n, n_sim, exceedances, unrounded D, resolution, ties, and a 95 percent exact binomial interval for the null tail probability conditional on the observed statistic. That interval describes simulation uncertainty, not robustness to model misspecification. Small alpha/j thresholds may need substantially more simulation. Default-method output retains three-decimal rounding and the legacy three-element list.

Value

An object including the test statistic, p-value, and a significance flag (list)

Precision metadata

Successful computed results also carry a rita_test attribute with the unrounded statistic and p.value, n_tested, precision, calibration and details. It records existing computations without rerunning the test. Legacy list elements, warning behavior and decisions are unchanged. Unsupported or undefined results retain their existing sentinel/NA representation and may lack this attribute. See rita_analysis for reporting conventions.

References

Lilliefors, H.W. (1967). On the Kolmogorov-Smirnov Test for Normality with Mean and Variance Unknown. Journal of the American Statistical Association, 62, 399-402.

Molin, P., & Abdi, H. (1998). New Tables and numerical approximation for the KolmogorovSmirnov/Lillierfors/Van Soest test of normality.

Examples

values <- rnorm(100)
x <- KSLTest(data = values)
set.seed(2026)
mc <- KSLTest(values, method = "monte-carlo", n_sim = 999)
attr(mc, "monte_carlo") # Increase n_sim for precise tail inference.

Master Normality Testing Function

Description

This is a master function to call the appropriate test(s) to be used in the 'Rita' function.

Usage

MasterTest(c, data, alpha = 0.05, j = 1, ...)

Arguments

Value

An results object specific to the test designated with the 'c' argument (list)

Examples

values <- rnorm(100)
x <- MasterTest(c = "shapiro-wilk", data = values)
set.seed(2026)
mc <- MasterTest("ksl", values, method = "monte-carlo", n_sim = 999)

Master Transformation Function

Description

This is a master function used to perform the appropriate transformation(s) within the 'Rita' function.

Usage

MasterXform(c, data)

Arguments

Value

Output from the appropriate subfunction (list)

Examples

values <- rnorm(100)
x <- MasterXform(c = "log", data = values)

Rita

Description

R Exploratory Data Analysis (REDA; pronounced "rita") summarizes an input dataset by the M, SD + 5-number summary + third and fourth moments and visualizes the data according to an algorithm or as specified by the user. In addition, Rita will provide the results of one or several normality tests. Lastly, Rita normalizes the dataset with several methods and provides visualizations of the best performing method to the user.

Usage

Rita(data, test = 1, xform = 1, alpha = 0.05, j = 1, autoPlot = T,
  histPlot = F, densPlot = F, stripPlot = F, violinPlot = F,
  xformPlot = F, return = T, seed = NULL, sw_large_n = "subsample",
  sw_subsample_n = 5000, ksl_method = "molin-abdi", ksl_n_sim = 100000,
  plot_profile = "compact", plots_per_page = 3, display_plots = TRUE)

Arguments

Details

Any rows with missing values (NAs) are removed for calculation purposes; if desired, incomplete records should be imputed or removed with subsetting prior to calling Rita. In addition, note that any columns not numeric type or coercible to numeric are excluded from analysis, as are any numeric columns with 2 distinct values or less. Columns are coerced independently. Numeric values are preserved, and factors are interpreted by their labels. Complex-valued columns are rejected.

Descriptive skewness and excess kurtosis use adjusted Fisher-Pearson coefficients with sample SD. Cleaning reports original missingness, values made missing by numeric coercion, excluded variables and reasons, omitted rows, and retained dimensions. All-missing and uniform columns are excluded before complete-case omission; columns with two or fewer distinct values are excluded afterward. This order determines the retained observations. Variables excluded after complete-case filtering may still have caused row omissions. Such rows are not recovered. Users should select and prepare their analytical variables before calling Rita; no imputation or variable-specific complete-case samples are introduced.

Normality tests evaluate the selected transformation, not every candidate. The full-data QQ-correlation selection criterion is unchanged. Reusing rows removes random-subset differences; it does not validate p-values after fitted or data-selected transformations. SW subsampling uses the caller's RNG by default and the same retained row indices for all tested variables; identical starting RNG states/usable row order reproduce the subset across calls. Returned sw_sampling indices refer to original rows, with complete_case_indices identifying positions after row omission. All-tests, subsampling, and explicit simulation calls also return a normality_tests attribute containing test results and any sampling/calibration metadata. The two-element data/plots list is preserved. SW unavailability is reported with NA entries and a reason; other tests are not substituted.

Value

An unnamed two-element list containing the selected transformed dataset for each variable (or cleaned data when return = FALSE) and the specified plots. The additive rita_plotting attribute retains plot-ready observations; see rita_plotting. Compact/QQ return a list of trellis pages; full and manual modes retain their historical nested collections.

Structured result retention

Every successful call also has a rita_analysis attribute containing settings, cleaning records, unrounded original-scale descriptives, transformation selection information and all requested test results. See rita_analysis for its schema. The existing two list elements and conditional normality_tests and sw_sampling attributes are preserved. Test wrappers add rita_test metadata with values retained before display rounding, a status, and a decision. Invalid numerical results are unavailable for inference. The wrapper's original numerical elements and significance flag remain available for diagnostics.

Examples

values <- rnorm(100)
x <- Rita(data = values, test = "shapiro-wilk", xform = "rankit")
analysis <- attr(x, "rita_analysis")
analysis$cleaning$retained_rows
analysis$tests[[1]][["shapiro-wilk"]]$p.value
# Generate compact pages without displaying; retrieve and print deliberately.
fit <- Rita(mtcars, display_plots=FALSE)
print(fit[[2]][[1]])
# Reuse saved observations; no tests, transformations or selection are rerun.
full <- RitaPlots(fit, "full")
qq <- RitaPlots(fit, "qq", plots_per_page=2)
# Historical manual flags; no automatic profile or display.
manual <- Rita(mtcars, autoPlot=FALSE, histPlot=TRUE, display_plots=FALSE)
# No generated plots, but plotting data remain available.
no_plots <- Rita(mtcars, autoPlot=FALSE)
attr(no_plots, "rita_plotting")$data[[1]]$original_rows

Regenerate Rita plots from retained observations

Description

Builds lattice plots without rerunning cleaning, transformations, selection or normality tests. The input must be a Rita result with rita_plotting metadata.

Usage

RitaPlots(result, plot_profile = "compact", plots_per_page = 3,
  display_plots = FALSE)

Arguments

Value

A list of lattice trellis pages (compact/QQ), or the historical nested plot collection (full). See rita_plotting for metadata and RNG details.

Examples

fit <- Rita(mtcars, xform="rankit", autoPlot=FALSE)
pages <- RitaPlots(fit, "qq")
print(pages[[1]])

Shapiro-Wilk Test

Description

This function is a wrapper for shapiro.test() from the stats package. Options added include an ability to toggle a Bonferonni correction for significance, a corresponding significance flag, and reorganized output to facilitate integration with the Rita package.

Usage

SWTest(data, alpha = 0.05, j = 1, warn = T,
  large_n = "subsample", subsample_n = 5000)

Arguments

Details

With 3 to 5000 usable observations, the ordinary stats::shapiro.test is performed. Larger samples use a random subsample WITHOUT replacement by default. Select large_n = "error" to terminate instead of sampling. No other test is substituted. With fewer than three usable observations, the existing termination sentinel is returned. NA/NaN are omitted before checking sample size; remaining observations must be finite.

Subsampling advances R's RNG without resetting it; use set.seed() before calling. It tests only the selected subset and different subsets can produce different results. Under iid normal sampling it avoids artificial duplicates from replacement; the underlying Shapiro-Wilk p-value remains an approximation. Existing ties in the data are not removed. The sampling attribute records original, usable and analyzed sizes, original-input indices, and a random-subsample method label, even when warn=FALSE. Reuse those observation indices when comparing transformations. Rita's sw_large_n option shares one set across selected transformations in a call. Significance uses the unrounded p-value against alpha/j; displayed values retain three-decimal rounding.

Value

An object including the test statistic, p-value, and a significance flag (list)

Precision metadata

Successful computed results also carry a rita_test attribute with the unrounded statistic and p.value, n_tested, precision, calibration and details. It records existing computations without rerunning the test. Legacy list elements, warning behavior and decisions are unchanged. Unsupported or undefined results retain their existing sentinel/NA representation and may lack this attribute. See rita_analysis for reporting conventions.

References

Patrick Royston (1982). An extension of Shapiro and Wilk's W test for normality to large samples. Applied Statistics, 31, 115–124. 10.2307/2347973

Patrick Royston (1982). Algorithm AS 181: The W test for Normality. Applied Statistics, 31, 176–180. 10.2307/2347986

Patrick Royston (1995). Remark AS R94: A remark on Algorithm AS 181: The W test for normality. Applied Statistics, 44, 547–551. 10.2307/2986146

Examples

values <- rnorm(100)
x <- SWTest(data = values)
set.seed(2026)
large_values <- rnorm(6000)
sampled <- SWTest(large_values, warn = FALSE)
attr(sampled, "sampling")[c("original_n", "analyzed_n")]

Arcsine Transformation

Description

This function transforms the scale, if needed, to values of unity. Then, the data is transformed by taking the arcsine of the square root. Per the recommendations of Osborne(2002), data points are left-anchored at 0 to maximize the efficacy of the square-root transformation used enroute to the arcsine.

Usage

arcsineXform(sample)

Arguments

Details

Negative minima are first shifted to zero. If the resulting maximum exceeds 1, values are divided by that maximum. The minimum of these bounded values is then subtracted before applying asin(sqrt(.)), even when the original input already consists of valid positive proportions. This is Rita's intentional reanchoring convention. Equivalent scaled arithmetic avoids overflow while shifting extreme finite values.

Input must be nonempty and finite, with no NA or NaN. Numeric vectors, matrices, arrays and data frames are accepted; dimensions and names are retained. Bounds are computed over the whole input. Constants return zero.

Value

The arcsine-transformed data, retaining input dimensions and names

References

Osborne, J. W. (2002). Notes on the use of data transformations. Practical Assessment, Research and Evaluation, 9(1), 42-50.

Osborne, J. W. (2002). The Effects of Minimum Values on Data Transformations. Retrieved from https://files.eric.ed.gov/fulltext/ED463313.pdf

Examples

values <- rnorm(100)
x <- arcsineXform(values)

Chi-Square Test

Description

This function computes the chi-square test for normality.

Usage

chisqTest(data, alpha = 0.05, j = 1, df = NULL)

Arguments

Details

The number of cells is k = ceiling(2*n^(2/5)) (Moore, 1986). Numeric fitted-normal quantiles define equiprobable cells with infinite outer endpoints and expected count n/k, including empty cells. Mean and sample SD are fitted to all usable observations. Calculations use centered, scaled coordinates to avoid overflow; interval labels are never parsed. Cells are right-closed: a value exactly on an interior boundary enters the lower cell.

NA/NaN are omitted, and numeric matrices/arrays are flattened as in the legacy implementation. At least three finite observations with positive variance are required. This is a computational minimum, not a claim of calibration for small samples. Ties are accepted, but continuous-normal calibration does not account for rounding or discretization. Small expected cell counts can further impair the chi-square approximation; cells are not merged.

By default df=NULL selects the conventional k-3 chi-square approximation, with k determined after omitting missing observations. Explicit positive df overrides are honored. Ungrouped mean/SD fitting means this reference is not an exact null calibration (Moore, 1986, Sections 3.2.2 and 3.2.7). Neither k-3 nor k-1 provides a universal finite-sample p-value bound. Simulations found a 6.10 percent rejection rate at nominal 5 percent for n=40 (20000 normal samples), illustrating possible size distortion. Significance uses the unrounded upper-tail p-value against alpha/j; displayed values retain legacy rounding.

Value

An object including the test statistic, p-value, and a significance flag (list)

Precision metadata

Successful computed results also carry a rita_test attribute with the unrounded statistic and p.value, n_tested, precision, calibration and details. It records existing computations without rerunning the test. Legacy list elements, warning behavior and decisions are unchanged. Unsupported or undefined results retain their existing sentinel/NA representation and may lack this attribute. See rita_analysis for reporting conventions.

References

Moore, D.S., (1986) Tests of the chi-squared type. In: D'agostino, R.B. and Stephens, M.A., eds.: Goodness-of-Fit Techniques. Marcel Dekker, New York.

Examples

values <- rnorm(100)
x <- chisqTest(data = values)
k <- ceiling(2 * length(values)^(2/5))
approximate <- chisqTest(values, df = k - 3) # Explicit approximation, not exact.

Inverse/Reciprocal Transformation

Description

This function imputes minimum values per the recommendations of Osborne (2002) and reflects the input (multiplies by -1), anchors its minimum at 1, and takes the reciprocal.

Usage

inverseXform(sample)

Arguments

Details

Computes 1 / ((max(sample) - sample) + 1). Reflection preserves score direction; the minimum of the reflected data is anchored at 1 before taking reciprocals. Centering precedes the unit offset, with equivalent scaled arithmetic when the intermediate difference would overflow.

Input must be nonempty and finite, with no NA or NaN. Numeric vectors, matrices, arrays and data frames are accepted; dimensions and names are retained. The maximum is taken over the whole input. Constants return one.

Value

The reciprocal-transformed data, retaining input dimensions and names

References

Osborne, J. W. (2002). Notes on the use of data transformations. Practical Assessment, Research and Evaluation, 9(1), 42-50.

Osborne, J. W. (2002). The Effects of Minimum Values on Data Transformations. Retrieved from https://files.eric.ed.gov/fulltext/ED463313.pdf

Examples

values <- rnorm(100)
x <- inverseXform(values)

Adjusted Fisher-Pearson Excess Sample Kurtosis

Description

Adjusted Fisher-Pearson Excess Sample Kurtosis

Usage

kurtCoeff(data, sd)

Arguments

Value

The kurtosis value (scalar)

References

Shreve, Joni N. and Donna Dea Holland . 2018. SAS® Certification Prep Guide: Statistical Business Analysis Using SAS®9. Cary, NC: SAS Institute Inc.

Examples

values <- rnorm(100)
x <- kurtCoeff(data = values, sd = sd(values))

Logarithmic Transformation

Description

This function imputes minimum values per the recommendations of Osborne (2002) and subsequently transforms the data to a base-10 logarithmic scale.

Usage

logXform(sample)

Arguments

Details

Computes log10((sample - min(sample)) + 1), including when all values are already positive. Centering precedes the unit offset to retain the minimum-1 anchor at large locations. Opposite-sign extremes use equivalent scaled arithmetic to avoid intermediate overflow.

Input must be nonempty and finite, with no NA or NaN. Numeric vectors, matrices, arrays and data frames are accepted; dimensions and names are retained. Anchoring uses the minimum over the whole input. Constants return zero. Rita() performs its own complete-case cleaning before calling transformations.

Value

The log-transformed data, retaining input dimensions and names

References

Osborne, J. W. (2002). Notes on the use of data transformations. Practical Assessment, Research and Evaluation, 9(1), 42-50.

Osborne, J. W. (2002). The Effects of Minimum Values on Data Transformations. Retrieved from https://files.eric.ed.gov/fulltext/ED463313.pdf

Examples

values <- rnorm(100)
x <- logXform(values)

Logit/Log-Odds Transformation

Description

This function transforms data via the logit/log-odds transformation.

Usage

logitXform(
  sample, divisor = 2,
  input = c("auto", "counts", "proportions", "percentages", "continuous")
)

Arguments

Details

The input mode determines preprocessing. With input = "auto", nonnegative values summing to 100 are divided by 100. Otherwise, nonnegative values summing to 1 are retained, and other nonnegative values whose maximum is at least 1 are divided by that maximum. Signed data use the continuous rule below. This preserves legacy automatic scaling but cannot infer whether values represent frequencies or continuous scores.

With input = "counts", nonnegative frequencies are divided by their total, which must be positive. With input = "proportions", values must lie in [0,1] and are retained; they need not sum to 1. With input = "percentages", values must lie in [0,100] and are divided by 100, regardless of their total. With input = "continuous", negative minima are shifted to zero, then values are divided by their maximum only if it exceeds 1. Equivalent scaled arithmetic avoids overflow. Counts in a matrix or data frame use a single total over all entries, not separate column totals.

After preprocessing, endpoint substitution follows emudrak (2014): epsilon is half the smallest strictly positive proportion. Only 0 and 1 are replaced, by epsilon and 1-epsilon respectively, before qlogis() is applied. The rule can reverse observation order and can produce a constant result. In particular, c(0,1) gives c(0,0). No recursive retry or perturbation is used.

Inputs must contain nonempty finite numeric observations without NA or NaN. Numeric matrices, arrays and data frames are flattened in column-major order. All-zero proportions have no positive value from which to define epsilon and raise an error. Endpoint substitutions that cannot be represented strictly inside (0,1), or positive proportions that underflow to zero during preprocessing, also raise an error. Constants strictly inside (0,1) are valid. Rita() and MasterXform() use the default automatic mode. For known counts, convert to proportions before calling those higher-level functions. Rita() retains its existing complete-case cleaning and variable-eligibility rules.

Value

The logit-transformed data (vector)

References

Stevens, S., Valderas, J. M., Doran, T., Perera, R., & Kontopantelis, E. (2016). Analysing indicators of performance, satisfaction, or safety using empirical logit transformation. bmj, 352.

Osborne, J. W. (2002). Notes on the use of data transformations. Practical Assessment, Research and Evaluation, 9(1), 42-50.

Osborne, J. W. (2002). The Effects of Minimum Values on Data Transformations. Retrieved from https://files.eric.ed.gov/fulltext/ED463313.pdf

Warton, D. I., & Hui, F. K. (2011). The arcsine is asinine: the analysis of proportions in ecology. Ecology, 92(1), 3-10.

emudrak (2014). Empirical logit transformation on percentage data. Cross Validated, answer 110037 to question 109702, July 30.

Examples

values <- rnorm(100)
x <- logitXform(values)
logitXform(c(10,20,30), input = "counts")
logitXform(c(0,0.1,0.99,1), input = "proportions")

Converts Sample Standard Deviations into Population Equivalents

Description

This function converts a sample standard deviation (SD) input into the population equivalent. This code is vectorized to convert several sample standard deviations for univariate distributions of identical sample-sizes, if desired.

Usage

popSD(s, n)

Arguments

Value

The population SD(s) (vector)

References

Ruscio, J. (2021). Fundamentals of research design and statistical analysis. Ewing, NJ: The College of New Jersey, Psychology Department.

Examples

values <- rnorm(100)
x <- popSD(s = sd(values),n = 100)

Rankit Transformation

Description

This function transforms data via the Rankit, a member of the families of 'rank-based normalization methods' and 'empirical normal quantile transformations' employed in both the social sciences and quantitative genetics.

Usage

rankitXform(sample)

Arguments

Details

Uses qnorm((rank(sample) - 0.5) / length(sample)) with R's default average ranks for ties. The original order is retained. The existing rank() defaults also rank NA and NaN last, in their order of occurrence, rather than omitting them. Infinite values are ranked as extreme observations. Rita() applies its own complete-case cleaning before this function is called.

Value

The Rankit-transformed data (vector)

References

Soloman, S. R., & Sawilowsky, S. S. (2009). Impact of rank-based normalizing transformations on the accuracy of test scores. Journal of Modern Applied Statistical Methods, 8(2), 9.

Peng, B., Robert, K. Y., DeHoff, K. L., & Amos, C. I. (2007, December). Normalizing a large number of quantitative traits using empirical normal quantile transformation. In BMC proceedings (Vol. 1, No. 1, p. S156). BioMed Central. doi: 10.1186/1753-6561-1-s1-s156

Bliss, C. I., Greenwood, M. L., & White, E. S. (1956). A rankit analysis of paired comparisons for measuring the effect of sprays on flavor. Biometrics, 12(4), 381-403.

Examples

values <- rnorm(100)
x <- rankitXform(values)

Retained Rita Analysis Metadata

Description

Structured records retained by Rita and precision metadata supplied by its test wrappers.

Details

The additive rita_analysis attribute is present on every successful Rita() call. Its schema_version is integer 1. All indices are one-based. No S3 class is added. The first two positional return elements keep their existing meanings.

settings contains canonical test and transformation names, alpha, j, threshold, seed, return_transformed, plotting flags, and active SW/KSL options. Inactive SW or KSL settings are NULL. A NULL seed means the caller's RNG stream was used; no copy of the caller's full RNG state is retained.

cleaning contains input_rows, input_columns, final_rows, final_columns, retained_columns (original positions), retained_rows and omitted_rows (original row positions). Its variables data frame has one row per original input column: original_position, variable, missing_original, missing_coercion, missing_total, considered_for_complete_cases, exclusion_stage, exclusion_reason and retained. Missingness fields are counts, not observation-level masks. Exclusion stages are before-complete-cases or after-complete-cases, with NA for retained variables. The considered_for_complete_cases flag separates early-excluded missingness from missingness relevant to the actual row filter. Counts include NA and NaN. Metadata records the executed cleaning sequence. Later exclusions never recover rows and do not alter the common complete-case sample.

descriptives contains scale (original-cleaned), values (an unrounded data frame with statistics in rows and retained variables in columns), skewness and kurtosis convention labels. Undefined small-sample moments remain undefined.

selection is a list in retained-variable order. Each record contains original_position, variable, method (canonical transformation), mode (requested or automatic), criterion, score, candidates, tied_methods and tie_resolution. Automatic candidates is an ordered data frame of method and score. All exact maxima are listed in tied_methods; the first is selected. tie_resolution is unique-maximum or first-exact-maximum. Requested transformations have NULL candidates, empty tied_methods and not-applicable tie_resolution. Their score is still the already-computed QQ correlation squared. Scores use the full cleaned data and the existing candidate order and formula.

tests is a list in retained-variable order; each element is a named list of the requested canonical tests, with the same structure in single- and all-tests mode. Each test record contains original_position, variable, transformation, test, statistic_name, statistic, p.value, precision, usable_n, tested_n, alpha, j, threshold, significant, decision, status, reason, calibration, calibration_details, monte_carlo, sampling, warnings, limitations and result. The result field is the actual wrapper result, including its attributes, also used by the pre-existing normality_tests attribute where that attribute applies. Descriptive list names may repeat if input names repeat; original_position is the unambiguous identity.

statistic and p.value use the computed unrounded values supplied by rita_test. precision is unrounded-computation for usable numerical results and unavailable otherwise. decision is reject, do not reject, or unavailable. significant is NA when inference is unavailable. The raw legacy flag is in result[[3]] when present. Usable n describes the common cleaned sample. Tested n records the actual sample used for attempted computations, including failures and SW subsets. It is zero when the test did not run. No test is rerun to construct these fields.

status is computed, monte-carlo-floor (zero exceedances), approximation-boundary (clipped Molin-Abdi output), numerical-zero, invalid-numerical-result, or unavailable. A numerical zero may reflect underflow. An attempted numerical failure has status invalid-numerical-result and an informative reason. The original statistic and p.value remain available for diagnosis. The main console table masks invalid values and shows the decision as unavailable. Failure to reject does not establish normality. Nominal probabilities do not account for fitting or selecting a transformation on the same data.

calibration identifies stats-shapiro-wilk, molin-abdi, normal-null-monte-carlo, stephens-1986, chi-square-2, pearson-chi-square-approximation, or not-computed. calibration_details includes the raw Molin-Abdi probability and clipped flag, chi-square df where applicable, and Pearson cell count and expected frequency. monte_carlo retains the wrapper's existing replicate counts, exceedances, resolution and any available interval or other metadata; it is NULL for non-simulation methods. The plus-one resolution floor is not a bound on the true tail probability. sampling retains SW metadata with indices mapped to original rows, original_n describing the original input size, and complete_case_indices mapped to the cleaned sample. The nested result keeps the wrapper's original coordinate convention unchanged.

warnings records warning messages emitted during that individual test call without suppressing them. Global Rita warnings, such as shared subsampling, are not duplicated here. limitations separately records applicable qualifications, including subsampling, approximate calibration and small-sample restrictions. Existing method-specific numerical and calibration limitations remain.

The wrapper attribute rita_test contains statistic, p.value, n_tested, precision, calibration, details, status, reason and decision. The metadata decision is unavailable when the raw result is invalid. The legacy list elements keep their original rounding and flags. Small-sample sentinels may lack this attribute. A numerical zero or one alone does not establish an exact tail probability or approximation clipping.

See Also

Rita

Rita plotting profiles and retained plotting data

Description

Rita retains the original and selected transformed observations in an additive rita_plotting attribute. This is separate from the unchanged rita_analysis schema. Both positional return elements retain their meanings: data, followed by lattice plotting objects. No analysis-result class is added.

Details

With autoPlot=TRUE, plot_profile="compact" is the default. Each variable has an original histogram (using Rita's existing integer-valued feature detection) or density on the left and its selected transformed density on the right. Variables follow retained input-column order. Three variable pairs per page is the default; plots_per_page changes this. Both axes have panel-specific ranges; original and transformed units differ. Histograms show percent per bin; densities show density in the corresponding measurement units. No strip or violin plots are included in compact mode.

plot_profile="full" retains the historical repertoire and grouping: paired original/transformed main plots (integer-valued originals first), followed by original strip plots for at most 20 distinct values and 150 observations, otherwise violin/boxplots. It returns the historical two-group nested list, without pagination. Nine variables therefore yield 27 trellis objects in full mode versus three six-panel trellis pages in compact mode.

plot_profile="qq" uses the same pagination and variable/stage order as compact. Sorted observations are plotted against qnorm(ppoints(n)), with standard-normal theoretical quantiles. The dashed reference line joins the observed 25th and 75th percentiles (R quantile type 7) at the corresponding standard-normal quantiles. It is not a fitted least-squares line or a confidence envelope. The transformed panel labels the already-retained QQ-correlation-squared score. Better visual alignment does not establish normality or validate inference after selecting a transformation on the same observations.

Precedence is explicit: with autoPlot=TRUE, the selected profile controls plots and all five manual flags are ignored. With autoPlot=FALSE, the profile and pagination arguments are ignored, and only histPlot, densPlot, stripPlot, violinPlot, and xformPlot apply. The five historical groups (including empty groups) remain in position 2. With all flags FALSE, no plots are generated, but plotting data are still retained. display_plots=FALSE suppresses automatic drawing and keeps the console statistics and plot objects. For batch analysis, assign the result, for example fit <- Rita(mtcars, display_plots=FALSE). Printing the plot collection explicitly or through R's auto-printing can open the default graphics device.

RitaPlots(result, plot_profile, plots_per_page, display_plots=FALSE) builds another profile using saved observations, even after a no-plot call or a call with return=FALSE. It never reruns transformations, selection, normality tests or sampling. Density estimation and plotting coordinates are prepared as needed. Print an individual returned trellis object to draw or export it deliberately. For three pairs per page, a device approximately 10 by 10 inches is recommended. A 5-by-5-inch device uses fewer ticks and fits labels to the width of each strip. Long names may show their input column number and an abbreviated name. Use fewer pairs on shorter devices. Very narrow strips may abbreviate the transformation or show only the QQ score when space permits. Full labels and scores remain in rita_plotting.

Generation alone does not draw random numbers. Existing lattice rendering of jittered density rugs and strip plots may advance the caller's RNG, including on reprinting. Jitter is not redesigned here. Compact omits supplemental strips and changes plotting order, so its rendering-time RNG consumption can differ from full. QQ rendering consumes no RNG. Rita's explicit seed remains scoped to the Rita call; later printing or RitaPlots display is outside that scope. Plots use all cleaned observations, not just a Shapiro-Wilk random subsample.

Schema version 1

attr(result,"rita_plotting") is a list containing:

schema_version

Integer 1.

profile

Active profile: compact, full, qq or manual.

plots_per_page

Configured variables per page for compact/QQ; NULL otherwise.

display

Whether automatic drawing was requested.

data

One record per retained variable in input order.

Each data record contains original_position and variable, matching rita_analysis$selection; original_rows, matching rita_analysis$cleaning$retained_rows; numeric original and transformed vectors in that row order; canonical transformation; transformed_label; and the existing selection_score. stages is original then transformed. original_plot, transformed_plot, and supplemental_plot describe the existing feature-detection choices. qq documents probabilities, theoretical distribution and reference-line convention. These observations and conventions suffice to regenerate QQ coordinates deterministically. Original column position, not a possibly duplicated variable name, identifies a record.

Each compact/QQ trellis page also has a rita_panels attribute, ordered left to right, top to bottom. Records retain original position, variable, stage, transformation, type, original rows and observations. QQ panels additionally retain a coordinates data frame (original_row, theoretical, observed) and reference (intercept, slope). Tied observations remain individually identified in sorted order. Non-QQ coordinates/reference are NULL. Actual lattice panel arguments are constructed from these same observations.

Examples

fit <- Rita(mtcars, display_plots=FALSE)
length(fit[[2]]) # three compact pages
attr(fit,"rita_plotting")$data[[1]]$original
print(fit[[2]][[1]])
full <- RitaPlots(fit,"full")
qq <- RitaPlots(fit,"qq",plots_per_page=2)
attr(qq[[1]],"rita_panels")[[1]]$coordinates

Adjusted Fisher-Pearson Skewness Coefficient with Sample-size Correction Factor

Description

Adjusted Fisher-Pearson Skewness Coefficient with Sample-size Correction Factor

Usage

skewCoeff(data, sd)

Arguments

Value

The skewness value (scalar)

References

Shreve, Joni N. and Donna Dea Holland . 2018. SAS® Certification Prep Guide: Statistical Business Analysis Using SAS®9. Cary, NC: SAS Institute Inc.

Examples

values <- rnorm(100)
x <- skewCoeff(data = values,sd = sd(values))

Square-root Transformation

Description

This function left anchors the minimum value to 0 per the recommendations of Osborne (2002) and subsequently transforms the data by taking the square-root of each value.

Usage

squareXform(sample)

Arguments

Details

Computes sqrt(sample - min(sample)), including for positive input. Equivalent scaled arithmetic avoids overflow in the difference when the square root remains representable.

Input must be nonempty and finite, with no NA or NaN. Numeric vectors, matrices, arrays and data frames are accepted; dimensions and names are retained. The minimum is taken over the whole input. Constants return zero.

Value

The square-root-transformed data, retaining input dimensions and names

References

Osborne, J. W. (2002). Notes on the use of data transformations. Practical Assessment, Research and Evaluation, 9(1), 42-50.

Osborne, J. W. (2002). The Effects of Minimum Values on Data Transformations. Retrieved from https://files.eric.ed.gov/fulltext/ED463313.pdf

Examples

values <- rnorm(100)
x <- squareXform(values)