jaspFormula: JASP Formulas

In jasp-stats/jaspBase: JASP Base

JASP Formulas

Description

These functions provide support to stats::formula in R syntax. They are used to internally parse formula objects. These functions are not intended for direct use.

jaspFormula is used to parse R formulas. makeJaspFormula is a convenience function that is used for generating R formulas from list objects. jaspFormulaRhs is another convenience function that is used in tandem with makeJaspFormula.

Usage

jaspFormula(formula, data)

makeJaspFormula(..., response = NULL, data)

jaspFormulaRhs(terms = NULL, group = NULL, intercept = TRUE, correlated = TRUE)

Arguments

formula	A formula object.
data	A data frame.
...	Terms added to the rhs of the formula. Use jaspFormulaRhs to create the terms.
response	A character giving the names of response variables (on the lhs of the formula).
terms	A character giving the names or terms on the rhs of the formula.
group	A character giving the name of the grouping variable for the random effects.
intercept	Logical. Should intercept be included?
correlated	Logical. Should random effects be correlated?
x	Object of class "jaspFormula".

Details

The formulas in JASP follow the same rules as in stats::formula, but have some functionality removed. Specifically, it is not possible to use stats::offset in a formula. Analyses that allow including stats::offset in the model have specialized argument for that purpose. It is also not possible to use variable transformations in a formula. Thus, instead of transforming variables using formulas, transform the variables before entering them in the analysis.

For specification of the random effects, lme4::lme4-package syntax is used. There is a difference in how JASP parses whether or not are random effects correlated: Under each random grouping factor, if some but not all terms are correlated, the output correlated is still set to TRUE. The "correlations" attribute contains the full correlation structure.

Value

A list of class "jaspFormula" is returned, with the following elements:

• formula The original formula object.

• lhs A vector of column names included on the left hand-side of the formula.

• rhs A List of fixed and random terms that appear on the right hand-side of the formula.

The elements of the fixed terms are:

• vars A character vector of model terms.

• intercept Logical. If TRUE, intercept is included, if FALSE, intercept it not included.

The random is itself a list of length equal to the number of random factors. Each element is a list that contains the same elements as fixed, plus the following elements:

• correlated Logical. Are the terms correlated? Can contain an attribute named "correlations" that holds the entire correlation structure in case a mixture of correlated and uncorrelated terms is used.

• group The name of the random group factor.

Examples

# Each successive `jaspFormula` and `makeJaspFormula` give the same result

if (FALSE) {
# standard lm-style formulas with interaction
jaspFormula(mpg ~ cyl * disp, mtcars)
makeJaspFormula(
  data = mtcars, response = "mpg",
  jaspFormulaRhs(terms = c("cyl", "disp", "cyl:disp"))
  )


# convert to json
jsonlite::toJSON(jaspFormula(mpg ~ (cyl * disp | am), mtcars), force = TRUE, pretty = TRUE)

# exclude intercept
jaspFormula(mpg ~  0 + cyl * disp, mtcars)
jaspFormula(mpg ~ -1 + cyl * disp, mtcars)
makeJaspFormula(
  data = mtcars, response = "mpg",
  jaspFormulaRhs(terms = "cyl * disp", intercept = FALSE)
  )

# combine multiple columns on the lhs and multiple columns on the rhs (without interaction)
jaspFormula(cbind(mpg, disp) ~ cyl + gear, mtcars)
makeJaspFormula(
  data = mtcars, response = c("mpg", "disp"),
  jaspFormulaRhs(terms = c("cyl", "gear"))
  )

# non-syntactic column names
df <- data.frame(x = rlnorm(10))
df[["log(x)"]] <- log(df$x)
df[["a b ~ y <- gamma("]] <- rnorm(10)
jaspFormula(`a b ~ y <- gamma(` ~ `log(x)`, df)
makeJaspFormula(
  data = df, response = "`a b ~ y <- gamma(`",
  jaspFormulaRhs("`log(x)`")
  )

# lme4 syntax for mixed models
jaspFormula(mpg ~ disp*hp + (0 + disp + hp | cyl) + (1 | carb), mtcars)
makeJaspFormula(
  data = mtcars, response = "mpg",
  # fixed effects
  jaspFormulaRhs(terms = "disp*hp"),
  # random effects by cyl
  jaspFormulaRhs(terms = c("disp", "hp"), group = "cyl", intercept = FALSE),
  # random intercept by carb
  jaspFormulaRhs(group = "carb")
)

# uncorrelated intercept and slopes
jaspFormula(mpg ~ disp + (1 + disp + hp || cyl), mtcars)
makeJaspFormula(
  data = mtcars, response = "mpg",
  jaspFormulaRhs("disp"),
  jaspFormulaRhs(c("disp", "hp"), group = "cyl", correlated = FALSE)
)

jaspFormula(mpg ~ disp + (1 | cyl) + (0 + disp | cyl) + (0 + hp | cyl), mtcars)
makeJaspFormula(
  data = mtcars, response = "mpg",
  jaspFormulaRhs("disp"),
  jaspFormulaRhs(group = "cyl"), # intercept
  jaspFormulaRhs("disp", "cyl", intercept = FALSE),
  jaspFormulaRhs("hp",   "cyl", intercept = FALSE)
)


# THESE EXAMPLES SHOW HOW JASP FORMULA DEVIATES FROM THE STANDARD BEHAVIOR OF FORMULAS

if(interactive()) {
  # It is not possible to use variable transformations in the formula
  jaspFormula(mpg + disp ~ cyl, mtcars)
  makeJaspFormula(data = mtcars, response = "mpg + disp", jaspFormulaRhs("cyl"))

  jaspFormula(mpg ~ exp(disp),  mtcars)
  makeJaspFormula(data = mtcars, response = "mpg", jaspFormulaRhs("exp(disp)"))

  # It is not possible to use `offset`
  jaspFormula(mpg ~ offset(disp) + cyl, mtcars)
  makeJaspFormula(data = mtcars, response = "mpg", jaspFormulaRhs("offset(disp)"))
}

# Specify mixture of correlated and uncorrelated random terms;
# disp and hp are allowed to covary, as well as the random intercept and drat.
# In this case the output gives $rhs$random$cyl$correlated == TRUE,
# the actual correlation structure can be accessed from the "correlations" attribute.
result <- jaspFormula(mpg ~ disp + (0 + disp + hp | cyl) + (1 + drat | cyl), mtcars)
isTRUE(result$rhs$random$cyl$correlated)
attr(result$rhs$random$cyl$correlated, "correlations")

makeJaspFormula(
  data = mtcars, response = "mpg",
  jaspFormulaRhs(terms = "disp"),
  jaspFormulaRhs(terms = c("disp", "hp"), group = "cyl", intercept = FALSE, correlated = TRUE),
  jaspFormulaRhs(terms = "drat",          group = "cyl", intercept = TRUE,  correlated = TRUE)
)

}

jasp-stats/jaspBase documentation built on April 5, 2025, 3:46 p.m.