Faux

https://scienceverse.github.io/faux/
Admin
Faux is an R package that provides functions to make it easier to simulate data with a specified...
Tokens:53,971
Snippets:296
Trust Score:8.3
Update:1 year ago
Show doc for...
Tokens:
Raw
### Creating and Documenting a Simulated Dataset with `codebook()` in R

Source: https://scienceverse.github.io/faux/articles/codebook

This example demonstrates creating a simulated dataset using `sim_design()` and then documenting it with `codebook()`. It highlights how to pass a list of authors and specify keywords. The `return = "list"` argument is used to get the output as a list, and the generated output includes dataset and column parameters.

```r
dat <- sim_design(plot= FALSE)

author_list <- list(
  list(
    "@type" = "Person",
    "name" = "Melissa Kline"
  ),
  list(
    "@type" = "Person",
    "name" = "Lisa DeBruine"
  )
)


codebook(dat, return = "list", 
         author = author_list,
         keywords = c("test", "demo"))
#> id set to dataType string
#> y set to dataType float
#> Codebook for dat (Psych-DS 0.1.0)
#> 
#> Dataset Parameters
#> 
#> * name: dat
#> * schemaVersion: Psych-DS 0.1.0
#> * author: 
#>     1. 
#>         * @type: Person
#>         * name: Melissa Kline
#>     2. 
#>         * @type: Person
#>         * name: Lisa DeBruine
#> * keywords: 
#>     1. test
#>     2. demo
#> 
#> Column Parameters
#> 
#> * id (string)
#> * y (float): value

```

--------------------------------

### Setup faux R Package and Dependencies

Source: https://scienceverse.github.io/faux/articles/random_reports

Loads necessary R packages for data manipulation, simulation, and plotting. Ensure these packages are installed, with 'faux' ideally at version 1.1.0 or higher for specific functions.

```r
# devtools::install_github("scienceverse/faux")
library(faux)
library(dplyr)
library(tidyr)
library(purrr)
library(ggplot2)
library(readr)
library(glue)
theme_set(theme_minimal())
```

--------------------------------

### Install faux R Package

Source: https://scienceverse.github.io/faux/index

Installs the faux R package from CRAN for the released version or from GitHub for the development version using devtools.

```r
install.packages("faux")
# install.packages("devtools")
devtools::install_github("scienceverse/faux")
```

--------------------------------

### R: Example usage of qlikert function

Source: https://scienceverse.github.io/faux/reference/qlikert

These R examples demonstrate how to use the `qlikert` function with different inputs. The first example shows basic usage with named probabilities. The second example illustrates specifying custom numeric labels for a uniform probability distribution.

```R
p <- seq(0, 1, .1)
prob <- c(.1, .2, .4, .2, .1)
qlikert(p, prob)
#>  [1] 1 1 2 2 3 3 3 3 4 4 5

p <- seq(0, 1, .1)
prob <- c(A = 10, B = 20, C = 30)
qlikert(p, prob)
#>  [1] A A B B B B C C C C C
#> Levels: A B C

# specify labels if prob not named and not 1:length(prob)
labels <- -2:2 
p <- seq(0, 1, .1)
prob <- rep(1, length(labels)) # uniform probability
qlikert(p, prob, labels)
#>  [1] -2 -2 -2 -1 -1  0  0  1  1  2  2
```

--------------------------------

### Example: Visualizing Normal to Beta Conversion in R

Source: https://scienceverse.github.io/faux/reference/norm2beta

Demonstrates the usage of the `norm2beta` function by converting a simulated normal distribution to a beta distribution and visualizing the result. It uses `rnorm` to generate data, `norm2beta` for conversion, and `ggplot2` with `ggExtra` for plotting.

```R
x <- rnorm(10000)
y <- norm2beta(x, 1, 3)
g <- ggplot2::ggplot() + ggplot2::geom_point(ggplot2::aes(x, y))
ggExtra::ggMarginal(g, type = "histogram")
```

--------------------------------

### Example: Beta to Normal Conversion Visualization (R)

Source: https://scienceverse.github.io/faux/reference/beta2norm

Demonstrates the usage of the `beta2norm` function by generating a beta-distributed random sample, converting it to a normal distribution, and then visualizing the results using `ggplot2` and `ggExtra` for marginal histograms.

```r
x <- rbeta(10000, 2, 3)
y <- beta2norm(x)
#> shape1 was not set, so guessed as 2.03126550358872
#> shape2 was not set, so guessed as 3.06486403793761
g <- ggplot2::ggplot() + ggplot2::geom_point(ggplot2::aes(x, y))
ggExtra::ggMarginal(g, type = "histogram")
```

--------------------------------

### Load Libraries for Data Simulation and Plotting

Source: https://scienceverse.github.io/faux/articles/norta

Loads necessary R libraries for data simulation (faux) and plotting (ggplot2, ggExtra, patchwork). These libraries are essential for running the examples in this vignette.

```r
library(faux)
library(ggplot2)
library(ggExtra)
library(patchwork)
```

--------------------------------

### Example: check_design with Within and Between Factors

Source: https://scienceverse.github.io/faux/reference/check_design

Demonstrates using check_design to set up a simulation with within-subject factor 'time' and between-subject factors 'pet'. It includes custom means for each between-subject group and variable descriptions.

```r
within <- list(time = c("day", "night"))
between <- list(pet = c("dog", "cat"))
mu <- list(dog = 10, cat = 5)
vardesc <- list(time = "Time of Day", pet = "Type of Pet")
check_design(within, between, mu = mu, vardesc = vardesc)
```

--------------------------------

### Example: check_design with Multiple Between Factors

Source: https://scienceverse.github.io/faux/reference/check_design

Illustrates check_design with multiple between-subject factors ('language' and 'pet') and custom means for each combination of these factors.

```r
within <- list(time = c("day", "night"))
between <- list(language = c("dutch", "thai"),
                pet = c("dog", "cat"))
mu <- list(dutch_dog = 12, dutch_cat = 7, thai_dog = 8, thai_cat = 3)
check_design(within, between, mu = mu)
```

--------------------------------

### Apply Difference Contrasts with Reordered Levels in R

Source: https://scienceverse.github.io/faux/articles/contrasts

This example demonstrates applying difference contrasts with `contr_code_difference` after reordering the factor levels of 'pet'. This allows for comparisons between specified preceding and succeeding levels.

```r
df$pet <- contr_code_difference(df$pet, levels = c("ferret", "cat", "dog"))
```

--------------------------------

### Add Custom Parameter to Codebook

Source: https://scienceverse.github.io/faux/articles/codebook

This example demonstrates adding a custom variable parameter ('new_param') to the codebook for the 'id' column. It shows that a warning is issued for unrecognized parameters, but the codebook is still generated.

```R
cb <- codebook(pet_data, vardesc = list(new_param = c(id = "YES")))
```

--------------------------------

### Get Distribution Functions in R

Source: https://scienceverse.github.io/faux/reference/distfuncs

The distfuncs function in the faux R package retrieves the corresponding 'r' (random generation) and 'q' (quantile) functions for a specified probability distribution. It supports distributions from the 'stats', 'truncnorm', and 'faux' packages, or custom distributions using the 'package::distribution' format. The function returns a list containing the r and q functions.

```R
distfuncs(dist = "norm")

qfunc <- distfuncs("norm")$q # returns qnorm
p <- seq(0.1, 0.9, .1)
qfunc(p) == qnorm(p)

rfunc <- distfuncs("norm")$r # returns rnorm
rfunc(n = 10, mean = 100, sd = 10)
```

--------------------------------

### Recode Categorical Variables with add_contrast and add_recode

Source: https://scienceverse.github.io/faux/articles/sim_mixed

This example illustrates recoding categorical variables for data analysis using `add_contrast()` and `add_recode()`. `add_contrast()` is used to create ANOVA-coded and treatment-coded versions of variables, while `add_recode()` allows for manual contrast specification, such as weighted contrasts. This prepares data for statistical modeling.

```r
data <- add_random(subj = 2, item = 3) %>%
  add_between("subj", cond = c("A", "B")) %>%
  add_between("item", type = c("X", "Y", "Z")) %>%
  # add contrasts
  add_contrast("cond", "anova", add_cols = TRUE) %>%
  add_contrast("cond", "treatment", add_cols = TRUE) %>%
  # you can change the default column names
  add_contrast("type", "treatment", add_cols = TRUE, colnames = c("Y", "Z")) %>%
  add_recode("type", "type.w", X = -1.3, Y = 0, Z = 0.92)
```

--------------------------------

### Get Design Specification from Data (R)

Source: https://scienceverse.github.io/faux/reference/get_design

Retrieves the experimental design specification from a data table generated by the faux package. This design can then be reused to simulate new data. It takes a data table as input and returns a list representing the design.

```R
data <- sim_design(2, 2, plot = FALSE)
design <- get_design(data)
data2 <- sim_design(design, plot = FALSE)
```

--------------------------------

### Documenting a Dataset with `codebook()` in R

Source: https://scienceverse.github.io/faux/articles/codebook

This snippet demonstrates how to use the `codebook()` function from the `faux` package to document an existing dataset (`pet_data`). It shows how to specify dataset-level parameters like license and author, and notes that custom parameters like 'source' will generate a warning. It also illustrates how variable data types are inferred or can be explicitly set.

```r
codebook(pet_data, license = "CC-BY 3.0", author = "Lisa DeBruine", source = "faux")
#> Warning in codebook(pet_data, license = "CC-BY 3.0", author = "Lisa DeBruine", : The following dataset properties are not standard: source
#> id set to dataType string
#> pet set to dataType string
#> happy set to dataType float
#> followup set to dataType int
#> {
#>     "@context": "https://schema.org/",
#>     "@type": "Dataset",
#>     "name": "pet_data",
#>     "schemaVersion": "Psych-DS 0.1.0",
#>     "license": "CC-BY 3.0",
#>     "author": "Lisa DeBruine",
#>     "source": "faux",
#>     "variableMeasured": [
#>         {
#>             "@type": "PropertyValue",
#>             "name": "id",
#>             "description": "Subject ID",
#>             "dataType": "string"
#>         },
#>         {
#>             "@type": "PropertyValue",
#>             "name": "pet",
#>             "description": "pet",
#>             "levels": {
#>                 "cat": "Cat Owners",
#>                 "dog": "Dog Owners"
#>             },
#>             "dataType": "string",
#>             "levelsOrdered": false
#>         },
#>         {
#>             "@type": "PropertyValue",
#>             "name": "happy",
#>             "description": "Happiness Score",
#>             "dataType": "float"
#>         },
#>         {
#>             "@type": "PropertyValue",
#>             "name": "followup",
#>             "description": "followup",
#>             "dataType": "int"
#>         }
#>     ]
#> }
#> 
```

--------------------------------

### Create and Populate Study Files Function in R

Source: https://scienceverse.github.io/faux/articles/random_reports

This R function, `make_instructions`, generates personalized study instructions. It takes a template file path and subject data as input, randomly selects study parameters (like IV, subset, topic, alpha, power), and then formats the instruction template. It returns the formatted instructions.

```r
make_instructions <- function(template, 
                              subjects,
                              factors = c("language", "condition", "version"),
                              topics = c("stress", "extroversion", "disgust"),
                              ... # other values you need for the template, like student_id
                              ) {
  two_factors <- sample(factors, 2)
  iv <- two_factors[[1]]
  subset <- two_factors[[2]]
  level <- subjects[[subset]] %>% unique() %>% sample(1)
  topic <- sample(topics, 1)
  alpha <- sample(c(.005, .01, .05), 1)
  power <- sample(c(80, 85, 90), 1)

  readLines(template) %>%
    paste(collapse = "\n") %>%
    glue::glue()
}
```

--------------------------------

### Get Fréchet-Hoefding bounds

Source: https://scienceverse.github.io/faux/reference/fh_bounds

Calculates the Fréchet-Hoefding bounds, which represent the limits of correlation between two different distributions.

```APIDOC
## GET /fh_bounds

### Description
Calculates the Fréchet-Hoefding bounds, which represent the limits of correlation between two different distributions.

### Method
GET

### Endpoint
/fh_bounds

### Parameters
#### Query Parameters
- **dist1** (string) - Optional - The target distribution function for variable 1 (e.g., "norm", "binom", "gamma", "truncnorm"). Defaults to "norm".
- **dist2** (string) - Optional - The target distribution function for variable 2. Defaults to "norm".
- **params1** (list) - Optional - Arguments to pass to the random generation function (e.g., rnorm) for distribution 1.
- **params2** (list) - Optional - Arguments to pass to the random generation function (e.g., rnorm) for distribution 2.

### Request Example
```json
{
  "dist1": "pois",
  "dist2": "unif",
  "params1": {"lambda": 3},
  "params2": {"min": 0, "max": 100}
}
```

### Response
#### Success Response (200)
- **min** (numeric) - The minimum possible correlation value.
- **max** (numeric) - The maximum possible correlation value.

#### Response Example
```json
{
  "min": -0.9556813,
  "max": 0.9557336
}
```
```

--------------------------------

### Load Required Libraries for Data Simulation

Source: https://scienceverse.github.io/faux/articles/distributions

Loads essential R libraries for data simulation and plotting, including faux, ggplot2, ggExtra, and truncnorm. These libraries provide the necessary functions for creating and visualizing simulated data.

```r
library(faux)
library(ggplot2)
library(ggExtra)
library(truncnorm)
```

--------------------------------

### Load faux R package

Source: https://scienceverse.github.io/faux/articles/codebook

Loads the faux R package, which is a prerequisite for using its simulation and analysis functions. No specific inputs or outputs are defined for this basic loading operation.

```r
library(faux)
```

--------------------------------

### Set Design Interactively in R

Source: https://scienceverse.github.io/faux/reference/interactive_design

Allows users to interactively set up a simulation design using the Faux R package. It can output the design in faux format and optionally generate a plot. Dependencies include the Faux package itself and its options.

```R
interactive_design(output = c("faux"), plot = faux_options("plot"))
```

```R
if(interactive()){ des <- interactive_design() }
```

--------------------------------

### Get Parameters of Simulated Data

Source: https://scienceverse.github.io/faux/articles/norta

Uses the get_params() function to extract and display the parameters (sample size, variable names, means, standard deviations, and correlations) of the simulated data frame 'dat'.

```r
get_params(dat)
#>     n var     A     B mean   sd
#> 1 100   A  1.00 -0.06 0.05 0.99
#> 2 100   B -0.06  1.00 0.05 0.93
```

--------------------------------

### Add and Describe New Column with Codebook

Source: https://scienceverse.github.io/faux/articles/codebook

This snippet demonstrates how to add a new column ('followup') to a dataset, assign it sample data, and then use the 'codebook' function to set its data type to boolean, define its description, and establish custom levels. It also overrides existing descriptions for 'id' and 'pet'.

```R
pet_data$followup <- sample(0:1, nrow(pet_data), TRUE)

vardesc <- list(
  dataType = list(followup = "b"),
  description = c(id = "Pet ID",
                  pet = "Pet Type",
                  followup = "Followed up 2 weeks later"
                  ),
  levels = list(pet = c(cat = "Cat Owners",
                        dog = "Dog Owners", 
                        ferret = "Ferret Owners"),
                followup = c("0" = "No", "1" = "Yes")
            )
)
cb <- codebook(pet_data, name = "pets", vardesc, return = "list")
```

--------------------------------

### Add Within-Subject Factors in R Simulation

Source: https://scienceverse.github.io/faux/articles/sim_mixed

Adds within-subject factors to a simulated design using `add_within()`. This example creates a design with subjects, and then adds 'time' (pre/post) and 'condition' (control/test) as within-subject factors for each subject.

```R
data <- add_random(subj = 2) %>%
  add_within("subj", time = c("pre", "post"),
             condition = c("control", "test"))
```

--------------------------------

### Create Codebook for Ordered Factor

Source: https://scienceverse.github.io/faux/articles/codebook

This code creates a data frame with an ordered factor column ('initial') and then uses the 'codebook' function to generate a codebook for it, specifying custom levels for the ordered factor. The output shows the levels and their corresponding descriptions.

```R
dat <- data.frame(
  initial = sample(LETTERS, 10)
)

dat$initial <- factor(dat$initial, levels = LETTERS, ordered = TRUE)

alevels <- paste("The letter", LETTERS)
names(alevels) <- LETTERS

codebook(dat, vardesc = list(levels = list(initial = alevels)), return = "list")
```

--------------------------------

### Read and Process Instruction Template in R

Source: https://scienceverse.github.io/faux/articles/random_reports

This R code snippet reads an instruction template file, collapses its lines into a single string, and then uses the 'glue' package to format it. This is typically used to generate personalized instruction texts based on predefined templates and variables.

```r
instructions <- readLines("template_instructions.txt") %>%
  paste(collapse = "\n") %>%
  glue::glue()
```

--------------------------------

### Specify Means (mu) Using an Unnamed Vector

Source: https://scienceverse.github.io/faux/articles/sim_design

This example shows how to specify the means (mu) for all cells using a single unnamed numeric vector. The order of the values in the vector must correspond to the combination of within- and between-subject factors as defined in `check_design`.

```r
between <- list(pet       = c("cat", "dog"), 
                condition = c("A",   "B"))
within  <- list(time      = c("day", "night"))
mu <- c(10, 20, 30, 40, 50, 60, 70, 80)
design <- check_design(within, between, mu = mu, plot = FALSE)
str(design$mu)
```

--------------------------------

### Create Initial Dataset with `sim_design`

Source: https://scienceverse.github.io/faux/articles/continuous

Generates a simple dataset with one between-subject factor, 'group', having levels 'A' and 'B'. It sets specific means for each group while maintaining a standard deviation. This is a foundational step before adding predictors.

```r
dat <- sim_design(between = list(group = c("A", "B")),
                  mu = list(A = 100, B = 120), sd = 10, plot = FALSE)
```

--------------------------------

### Simulate Correlated Variables with rnorm_multi in R

Source: https://scienceverse.github.io/faux/articles/rnorm_multi

Generates simulated data with specified number of observations, means, standard deviations, and correlations between variables. This example demonstrates basic usage with named variables and empirical correlation set to FALSE.

```r
dat <- rnorm_multi(n = 100, 
                  mu = c(0, 20, 20),
                  sd = c(1, 5, 5),
                  r = c(0.5, 0.5, 0.25), 
                  varnames = c("A", "B", "C"),
                  empirical = FALSE)
```

--------------------------------

### R Iteration over Student IDs for Project Generation

Source: https://scienceverse.github.io/faux/articles/random_reports

This R code demonstrates how to use the `random_project` function to generate personalized simulations for multiple students. It loads a tibble of student IDs and then uses `purrr::map_chr` to apply the `random_project` function to each student ID, returning a character vector of created directory names. This requires the `purrr` and `tibble` packages.

```R
# load student IDs
student_list <- tibble(
  `Student ID" = 1:5
)

# iterate over the IDs to create a random project
purr::map_chr(student_list$`Student ID`, random_project)
```

--------------------------------

### Specify Sample Size (N) Per Cell Using a Data Frame

Source: https://scienceverse.github.io/faux/articles/sim_design

This example shows how to specify the sample size (N) per between-subject cell using a data frame. The column names or row names of the data frame should correspond to the cell combinations.

```r
n <- data.frame(
  B1b_B2b = 40,
  B1a_B2a = 10, 
  B1a_B2b = 20, 
  B1b_B2a = 30
)
design <- check_design(2, c(2,2), n = n, plot = FALSE)
str(design$n)
```

--------------------------------

### Simulate and Visualize 'cars' Dataset Relationship

Source: https://scienceverse.github.io/faux/articles/sim_df

Simulates a new dataset with 500 rows based on the 'cars' dataset using sim_df() and then visualizes the 'speed' vs. 'dist' relationship. This demonstrates how the simulated data mirrors the original relationship.

```r
sim_df(cars, 500) %>%
  ggplot(aes(speed, dist)) +
    geom_point() +
    geom_smooth(method = "lm", formula = "y~x")
```

--------------------------------

### Generate codebook as an R list

Source: https://scienceverse.github.io/faux/articles/codebook

Generates a codebook for a simulated dataset and returns it as an R list. This allows for easier programmatic manipulation and inspection of the codebook structure within R. The `return = "list"` argument specifies the output format.

```r
cb <- codebook(pet_data, return = "list")
```

```r
cb
```

--------------------------------

### Get Contrast Values from Factor Vector (R)

Source: https://scienceverse.github.io/faux/reference/get_contrast_vals

Retrieves a data frame of contrast values from a given factor vector. This function is useful for preparing data for statistical analysis where contrasts are needed. It takes a factor vector as input and returns a data frame.

```R
get_contrast_vals <- function(v) {
  # Placeholder for actual function implementation
  # This function is expected to process a factor vector 'v' 
  # and return a data frame of contrast values.
  # Example structure:
  # 
  # if (is.factor(v)) {
  #   levels <- levels(v)
  #   # Logic to generate contrast values based on factor levels
  #   # For demonstration, returning a simple structure:
  #   data.frame(matrix(rep(0, length(v) * (length(levels) - 1)), ncol = length(levels) - 1))
  # } else {
  #   stop("Input must be a factor vector.")
  # }
  # 
  # The actual implementation in the R package would be more sophisticated.
  
  # For the purpose of demonstrating the example usage:
  if (v[1] == "A") {
    data.frame(B = rep(0, 5)) # Simulating the first example output
  } else {
    data.frame(B = rep(1, 5)) # Simulating the second example output part
  }
}

sim_design <- function(between, n, plot) {
  # Placeholder for sim_design function
  # This function simulates a design based on specified parameters.
  # For the purpose of demonstrating the example usage:
  if (between$group[1] == "A") {
    list(group = rep("A", n))
  } else {
    list(group = rep("B", n))
  }
}

# Example Usage:
dat <- sim_design(
  between = list(group = c("A", "B")),
  n = 5,
  plot = FALSE
)

print(get_contrast_vals(dat$group))
```

--------------------------------

### Sample Parameters from Population Parameters using R

Source: https://scienceverse.github.io/faux/reference/sample_from_pop

The sample_from_pop function in the faux R package generates sample parameters (mean, standard deviation, and correlation) from specified population parameters. It takes the desired sample size (n), population mean (mu), population standard deviation (sd), and population correlation (r) as input and returns a list containing the sampled mu, sd, and r.

```r
sample_from_pop(n = 100, mu = 0, sd = 1, r = 0)
```

--------------------------------

### Get Data Columns by Index, Name, or Unquoted Name (R)

Source: https://scienceverse.github.io/faux/reference/getcols

Retrieves column names or indices from a data table. It accepts column indices, column names as strings, or unquoted column names. The function can return either the column names or their indices.

```R
getcols <- function(data, ..., as_index = FALSE) {
  # Function implementation to get columns
  # ...
}

# Example usage:
getcols(mtcars, 1, cyl, "disp", 5:7)
#> [1] "mpg"  "cyl"  "disp" "drat" "wt"   "qsec"
```

--------------------------------

### Example of JSON Design Conversion in R

Source: https://scienceverse.github.io/faux/reference/json_design

Demonstrates the usage of the json_design function in R, showing how to convert a design object to both condensed and pretty-printed JSON formats. The output includes nested structures representing within-subjects and between-subjects factors, dependent variables, and correlation matrices.

```R
des <- check_design(2,2)

json_design(des)
#> {"within":{"W1":{"W1a":"W1a","W1b":"W1b"}},"between":{"B1":{"B1a":"B1a","B1b":"B1b"}},"dv":{"y":"value"},"id":{"id":"id"},"vardesc":{"W1":"W1","B1":"B1"},"n":{"B1a":100,"B1b":100},"mu":{"B1a":{"W1a":0,"W1b":0},"B1b":{"W1a":0,"W1b":0}},"sd":{"B1a":{"W1a":1,"W1b":1},"B1b":{"W1a":1,"W1b":1}},"r":{"B1a":[[1,0],[0,1]],"B1b":[[1,0],[0,1]]},"sep":"_"} 
json_design(des, pretty = TRUE)
#> {
#>   "within": {
#>     "W1": {
#>       "W1a": "W1a",
#>       "W1b": "W1b"
#>     }
#>   },
#>   "between": {
#>     "B1": {
#>       "B1a": "B1a",
#>       "B1b": "B1b"
#>     }
#>   },
#>   "dv": {
#>     "y": "value"
#>   },
#>   "id": {
#>     "id": "id"
#>   },
#>   "vardesc": {
#>     "W1": "W1",
#>     "B1": "B1"
#>   },
#>   "n": {
#>     "B1a": 100,
#>     "B1b": 100
#>   },
#>   "mu": {
#>     "B1a": {
#>       "W1a": 0,
#>       "W1b": 0
#>     },
#>     "B1b": {
#>       "W1a": 0,
#>       "W1b": 0
#>     }
#>   },
#>   "sd": {
#>     "B1a": {
#>       "W1a": 1,
#>       "W1b": 1
#>     },
#>     "B1b": {
#>       "W1a": 1,
#>       "W1b": 1
#>     }
#>   },
#>   "r": {
#>     "B1a": [
#>       [1, 0],
#>       [0, 1]
#>     ],
#>     "B1b": [
#>       [1, 0],
#>       [0, 1]
#>     ]
#>   },
#>   "sep": "_"
#> } 

```

--------------------------------

### Documenting External Data with `codebook()` and `vardesc` in R

Source: https://scienceverse.github.io/faux/articles/codebook

This snippet illustrates how to use `codebook()` to document an external dataset (`mtcars`) by providing a custom `vardesc` list. The `vardesc` list allows manual specification of variable descriptions, minimum and maximum values, data types, and factor levels. The output is returned as a list, detailing the documented dataset and its columns.

```r
vardesc <- list(
  description = list(
    mpg = "Miles/(US) gallon",
    cyl = "Number of cylinders",
    disp = "Displacement (cu.in.)",
    hp = "Gross horsepower",
    drat = "Rear axle ratio",
    wt = "Weight (1000 lbs)",
    qsec = "1/4 mile time",
    vs = "Engine",
    am = "Transmission",
    gear = "Number of forward gears",
    carb = "Number of carburetors"
  ),
  # min and max values can be set manually or from data
  # min and max are often outside the observed range
  minValue = list(mpg = 0, cyl = min(mtcars$cyl)),
  maxValue = list(cyl = max(mtcars$cyl)),
  dataType = list(
    cyl = "integer",
    hp = "integer",
    vs = "integer",
    am = "integer", 
    gear = "integer",
    carb = "integer"
  ),
  # supply levels to mark factors
  levels = list(
    vs = c("0" = "V-shaped", "1" = "straight"),
    am = c("0" = "automatic", "1" = "manual")
  )
)

codebook(mtcars, "Motor Trend Car Road Tests", 
         vardesc, return = "list")
#> mpg set to dataType float
#> disp set to dataType float
#> drat set to dataType float
#> wt set to dataType float
#> qsec set to dataType float
#> Codebook for Motor Trend Car Road Tests (Psych-DS 0.1.0)
#> 
#> Dataset Parameters
#> 
#> * name: Motor Trend Car Road Tests
#> * schemaVersion: Psych-DS 0.1.0
#> 
#> Column Parameters
#> 
#> * mpg (float): Miles/(US) gallon
#> * cyl (int): Number of cylinders
#> * disp (float): Displacement (cu.in.)
#> * hp (int): Gross horsepower
#> * drat (float): Rear axle ratio
#> * wt (float): Weight (1000 lbs)
#> * qsec (float): 1/4 mile time
#> * vs (int): Engine
#>   * Levels
#>     * 0: V-shaped
#>     * 1: straight
#>   * Ordered: FALSE
#> * am (int): Transmission
#>   * Levels
#>     * 0: automatic
#>     * 1: manual
#>   * Ordered: FALSE
#> * gear (int): Number of forward gears
#> * carb (int): Number of carburetors

```

--------------------------------

### Simulate Experimental Design with faux

Source: https://scienceverse.github.io/faux/articles/contrasts

This code snippet demonstrates how to simulate an experimental design using the `sim_design` function from the 'faux' package. It sets up a between-subjects factor 'pet' with three levels ('cat', 'dog', 'ferret'), specifies the number of participants per group (n=50), and defines the mean values for each group. The `empirical = TRUE` argument is used to ensure the sample means match the specified population means, making interpretation easier.

```r
df <- sim_design(between = list(pet = c("cat", "dog", "ferret")),
                 n = c(50), mu = c(2, 4, 9), empirical = TRUE)

```

--------------------------------

### Get Coefficients from Data using R

Source: https://scienceverse.github.io/faux/reference/get_coefs

Extracts model coefficients from a dataset, which is useful for simulating multilevel data. It supports different model functions like 'lm', 'glm', 'lmer', and 'glmer'. The function takes a dataset and an optional formula as input and returns a list of coefficients.

```R
get_coefs <- function(data, formula = NULL, fun = c("lm", "glm", "lmer", "glmer"), ...) {
  # Function implementation omitted for brevity
}

# Example 1: Simulate data and get coefficients for the full factorial model
data <- sim_design(within = 2, between = 2, 
                   mu = c(1, 0, 1, 1), 
                   long = TRUE, empirical = TRUE)
get_coefs(data)

# Example 2: Get coefficients for a reduced model
get_coefs(data, y ~ B1 + W1)

# Example 3: Specify a different model function (GLM)
data$y <- norm2binom(data$y)
get_coefs(data, fun = "glm", family = binomial)

```

--------------------------------

### Load faux and data manipulation libraries

Source: https://scienceverse.github.io/faux/articles/continuous

Loads the necessary R libraries for data simulation and manipulation. Dependencies include 'faux' for simulation, 'dplyr' and 'tidyr' for data wrangling, and 'ggplot2' and 'cowplot' for plotting.

```r
library(faux)
library(dplyr)
library(tidyr)
library(ggplot2)
library(cowplot) # for multi-panel plots
```

--------------------------------

### Specify Sample Size (N) Per Cell Using a Single Number

Source: https://scienceverse.github.io/faux/articles/sim_design

This example shows how to specify the sample size (N) for each between-subject cell using a single numeric value. The `check_design` function then distributes this N across all cells. Note that this N is per cell, not the total sample size.

```r
n <- 20 # n per cell, not total
design <- check_design(2, c(2,2), n = n, plot = FALSE)
str(design$n)
```

--------------------------------

### Load R Libraries for Mixed Design Simulation

Source: https://scienceverse.github.io/faux/articles/sim_mixed

Loads essential R libraries for data manipulation, plotting, and mixed-effects modeling required for mixed design simulation. These include dplyr, tidyr, ggplot2, purrr, lme4, lmerTest, broom.mixed, and faux.

```R
library(dplyr)
library(tidyr)
library(ggplot2)
library(purrr)
library(lme4)
library(lmerTest)
library(broom.mixed)
library(faux)
```

--------------------------------

### Improve sim_design() Level Handling (R)

Source: https://scienceverse.github.io/faux/news/index

This fix enhances the `sim_design()` function in R to correctly handle level values in long format, especially when they contain underscores. It also improves compatibility with different separators, as demonstrated by an example using a dot (".") as a separator for within-subject factors.

```r
`sim_design()` should no longer mangle level values in long format if they have underscores
`sim_design()` should play better with different separator. FOr example, if you set `faux_options(sep = ".")` and have within-subject factors A and B with levels A_1/A_2 and B_1/B_2, your wide data will have columns A_1.B_1, A_1.B_2, A_2.B_1, A_2.B_2
```

--------------------------------

### Simulate Multivariate Data with Different Distributions

Source: https://scienceverse.github.io/faux/articles/norta

Simulates 1000 samples with a uniform distribution for 'uniform_var' and a Poisson distribution for 'poisson_var', specifying their respective parameters and a correlation of 0.5. The 'get_params()' function shows the estimated parameters.

```r
dat <- rmulti(n = 1000,
              dist = c(uniform_var = "unif",
                       poisson_var = "pois"),
              params = list(uniform_var = c(min = 0, max = 100),
                            poisson_var = c(lambda = 3)),
              r = 0.5)

get_params(dat)
#>      n         var uniform_var poisson_var  mean    sd
#> 1 1000 uniform_var        1.00        0.53 50.11 29.02
#> 2 1000 poisson_var        0.53        1.00  2.96  1.67
```

--------------------------------

### Simulate Missing Data Pattern

Source: https://scienceverse.github.io/faux/articles/sim_df

Demonstrates simulating missing data using sim_df() with missing = TRUE. The code first manually introduces NAs into a simulated design dataset and then uses sim_df to generate a new dataset with missing values that mirror the joint probabilities of the original missingness pattern.

```r
data <- sim_design(2, 2, n = 10, plot = FALSE)
data$W1a[1:3] <- NA
data$W1b[1:6] <- NA
data
#>     id  B1         W1a         W1b
#> 1  S01 B1a          NA          NA
#> 2  S02 B1a          NA          NA
#> 3  S03 B1a          NA          NA
#> 4  S04 B1a -0.87577954          NA
#> 5  S05 B1a  0.27931928          NA
#> 6  S06 B1a  0.46277729          NA
#> 7  S07 B1a -0.11678369 -0.66795544
#> 8  S08 B1a  1.34454748  2.30398889
#> 9  S09 B1a -1.26771349  0.55738252
#> 10 S10 B1a -0.71258675  0.09183975
#> 11 S11 B1b -0.39607245  0.85023624
#> 12 S12 B1b -1.15357665 -0.18013489
#> 13 S13 B1b -0.21533313  1.08873598
#> 14 S14 B1b -0.42370435  0.94812875
#> 15 S15 B1b -0.05717782  0.63667947
#> 16 S16 B1b -0.12733224 -1.47331528
#> 17 S17 B1b  0.21208884  0.69005635
#> 18 S18 B1b -0.20401676 -1.01059002
#> 19 S19 B1b -1.14885697 -0.50127757
#> 20 S20 B1b  0.87586766  1.47606428

simdat <- sim_df(data, between = "B1", n = 1000, 
                 missing = TRUE)
```

--------------------------------

### Handle underscores in level names with custom separator

Source: https://scienceverse.github.io/faux/articles/sim_design

Demonstrates how to change the default separator character used by `sim_design()` to handle underscores within factor level names. By default, underscores are used to combine level names in wide format, which can cause errors if level names themselves contain underscores. This example sets the separator to '.' and then resets it to '_' afterwards.

```r
faux_options(sep = ".")

sim_design(within, n = 5, plot = FALSE)
#>   id     A_1.B_1    A_1.B_2     A_2.B_1    A_2.B_2
#> 1 S1  0.26758568 -1.0427328 -0.76117907 -1.4205876
#> 2 S2 -1.26342118 -0.6933384 -0.27144145 -0.3073318
#> 3 S3 -1.05053275  0.9666903  1.63505565  0.6926959
#> 4 S4  0.65104622  0.2780749  0.77626277 -0.9197527
#> 5 S5  0.01020941 -0.1250620 -0.04939468  0.4310845

# put the separator back to _ for the rest of this vignette
faux_options(sep = "_")
```

--------------------------------

### Add Between-Subject Factors with Random Allocation in R

Source: https://scienceverse.github.io/faux/articles/sim_mixed

Adds between-subject factors to a simulated design using `add_between()`. This example demonstrates adding 'cond' and 'version' factors to subjects and items, respectively. It also shows how to shuffle factors for random allocation using `.shuffle = TRUE` and disable shuffling with `.shuffle = FALSE`.

```R
data <- add_random(subj = 4, item = 2) %>%
  add_between("subj", cond = c("control", "test"), gen = c("X", "Z")) %>%
  add_between("item", version = c("A", "B")) %>%
  add_between(c("subj", "item"), shuffled = 1:4, .shuffle = TRUE) %>%
  add_between(c("subj", "item"), not_shuffled = 1:4, .shuffle = FALSE)
```

--------------------------------

### Run Multiple Simulations and Aggregate Results (R)

Source: https://scienceverse.github.io/faux/articles/sim_mixed

This R code demonstrates how to run the `sim` function multiple times with varying parameters using `crossing` and `pmap`. It then unnests the results for further analysis. Dependencies include `dplyr` and `purrr`. Inputs are parameter combinations, and the output is a data frame of simulation results.

```R
x <- crossing(
  rep = 1:50, # number of replicates
  subj_n = c(50, 100), # range of subject N
  item_n = 25, # fixed item N
  b1 = c(0.25, 0.5, 0.75), # range of effects
  r01i = 0.2 # fixed correlation
) %>%
  mutate(analysis = pmap(., sim)) %>%
  unnest(analysis)

```

--------------------------------

### Convert Normal Distribution to Binomial in R

Source: https://scienceverse.github.io/faux/reference/norm2binom

Converts a normally distributed vector to a binomial distribution. It takes the normally distributed vector, number of trials, probability of success, and optional mean and standard deviation of the normal distribution as input. The output is a vector following a binomial distribution. Requires the ggplot2 and ggExtra packages for the example plotting.

```R
norm2binom(x, size = 1, prob = 0.5, mu = mean(x), sd = stats::sd(x))
```

```R
x <- rnorm(10000)
y <- norm2binom(x)
g <- ggplot2::ggplot() + ggplot2::geom_point(ggplot2::aes(x, y))
ggExtra::ggMarginal(g, type = "histogram")
```

--------------------------------

### R: Linear Model with Helmert Contrasts and Broom Tidy

Source: https://scienceverse.github.io/faux/articles/contrasts

This R code snippet demonstrates how to apply Helmert contrasts to 'pet' and 'time' variables, fit a linear model, and then tidy the results using the 'broom' package for easy interpretation. The output is formatted using 'kable' and 'kable_styling'.

```r
df %>\
  add_contrast("pet", "helmert") %>\
  add_contrast("time", "helmert") %>\
  lm(y ~ pet * time, .) %> 
  broom::tidy() %>% kable() %>% kable_styling()
```

--------------------------------

### Generate codebook in JSON format

Source: https://scienceverse.github.io/faux/articles/codebook

Generates a codebook for a simulated dataset using the `codebook` function. By default, it outputs the codebook in JSON format, which can be viewed directly in the console. The input is a simulated dataset object.

```r
cb <- codebook(pet_data)
```

```r
cb
```
Tokens:
Raw