Step 1: Turn Variables into States — step1

Standardizes numeric indicators and clusters each subject-time observation. The default method is Gaussian-mixture latent profile analysis (LPA); reproducible k-means, PAM, and hierarchical clustering are available through method. Clusters are ordered by their average standardized indicator level, then optionally given user-supplied labels.

Usage

step1_states(
  data,
  id = NULL,
  time = NULL,
  variables = NULL,
  n_states = "auto",
  labels = NULL,
  state_order = NULL,
  state_colors = NULL,
  state = "state",
  standardize = NULL,
  missing = NULL,
  time_levels = NULL,
  n_start = 25L,
  seed = 123L,
  method = c("lpa", "kmeans", "pam", "clara", "fanny", "diana", "ward.D2", "ward.D",
    "complete", "average", "single", "mcquitty", "median", "centroid"),
  lpa_model = "EEI"
)

Arguments

data: A data frame with one row per subject and time point.
id: Name of the subject identifier column. May be omitted when the data carry VaSSTra role metadata.
time: Name of the time or ordering column. May be omitted when the data carry VaSSTra role metadata.
variables: Character vector naming numeric state indicators. May be omitted when the data carry VaSSTra role metadata.
n_states: Number of states to estimate. One number fits exactly that count, several numbers (for example 2:4) compare those candidates with state_choices() and fit the recommended count, and "auto" (default) compares 2 through 6 — or simply matches labels when labels are supplied. Automatic comparison never selects a solution whose smallest state holds under 5 percent of the observations. Compared candidates are kept in diagnostics$selection and every automated choice is reported with a message.
labels: Optional unique labels, ordered from the lowest to the highest average standardized profile.
state_order: Optional character vector giving the order the states should appear in every plot. It must list the same labels rearranged; the state column is stored as a factor in this order. Defaults to the profile (discovery) order.
state_colors: Optional state palette stored on the result and reused by every plot. A named vector (matched by state) or one colour per state in state order.
state: Name of the state column created in the returned data.
standardize: How to z-score the indicators before clustering: "time" (default for ordinary data) standardizes within each time point, "subject" within each subject (removing every person's own mean and scale, so states reflect deviations from their baseline), "global" across the whole sample, and "none" leaves the raw values. Analysis-ready package data may provide its own default through metadata.
missing: One of "error" (default for ordinary data) or "median". Analysis-ready package data may provide its own default through metadata. Median imputation is performed within time point, with the global variable median as a fallback for an entirely missing time point.
time_levels: Explicit chronological time values. Required for character or unordered-factor time columns.
n_start: Number of random k-means starts.
seed: Reproducible random seed.
method: State-clustering method. Choose "lpa" (default, Gaussian-mixture latent profile analysis via mclust), a partitioning method — "kmeans", "pam", "clara" (a sampling-based PAM that scales to many observations), or "fanny" (fuzzy clustering, hardened to its nearest partition) — or a hierarchical method: "diana" (divisive) and the agglomerative linkages "ward.D2", "ward.D", "complete", "average", "single", "mcquitty", "median", and "centroid". The partitioning and hierarchical methods are selected by average silhouette; only "lpa" uses BIC.
lpa_model: Covariance model used only by method = "lpa". The default "EEI" corresponds to tidyLPA model 1: equal variances and zero covariances.

Value

A vasstra_states object. Its data element is the original data with a factor state column; profiles is a tidy state-by-indicator table.

Examples

set.seed(1)
data <- expand.grid(student = 1:12, course = 1:3)
level <- rep(c(2, 8, 16), length.out = nrow(data))
data$views <- level + rnorm(nrow(data), sd = 0.4)
data$duration <- level * 3 + rnorm(nrow(data), sd = 0.4)
states <- step1_states(
  data,
  id = "student",
  time = "course",
  variables = c("views", "duration"),
  labels = c("Low", "Average", "High")
)
#> Using n_states = 3 to match the supplied labels.
states
#> VaSSTra Step 1: Variables -> States
#>   36 rows | 12 subjects | 3 times | 3 states | lpa
#>   Average silhouette: 0.950
#>   State sizes: Low=12, Average=12, High=12