% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/4_4_textWordPrediction.R
\name{textWordPrediction}
\alias{textWordPrediction}
\title{Compute word-level prediction scores for plotting with textProjectionPlot().}
\usage{
textWordPrediction(
  words,
  word_types_embeddings = word_types_embeddings_df,
  x,
  y = NULL,
  n_models = 25,
  n_permutations = 10000,
  seed = 1003,
  case_insensitive = TRUE,
  text_remove = "[()]",
  ...
)
}
\arguments{
\item{words}{Character vector **or** single-column tibble of
free-text responses (one per participant).}

\item{word_types_embeddings}{Word-type embeddings from \code{\link{textEmbed}}
- specifically the `$word_types` component. These
are *decontextualised*: one fixed vector per
unique word type.}

\item{x}{Numeric vector (or single-column tibble) of the
outcome variable to project words onto the x-axis
(e.g., a well-being scale score).}

\item{y}{Optional numeric vector for a second outcome to
project onto the y-axis. Default \code{NULL}.}

\item{n_models}{Number of null ridge regression models to fit,
each trained on a *different* permuted x vector.
Each null fit produces genuine cross-validated
out-of-sample null scores - one per word.
Determines p-value resolution: the minimum
non-trivial p-value step is approximately
\code{1/n_models} (e.g., 0.04 with 25 models,
which is just below alpha = 0.05). Default \code{25}.}

\item{n_permutations}{Number of bootstrap samples drawn from the
\code{n_models} null scores to smooth the null
distribution. Does not require additional model
fits. Set to \code{0} to skip p-values entirely.
Default \code{10000}.}

\item{seed}{Integer seed for reproducibility. Default 1003.}

\item{case_insensitive}{Logical. If \code{TRUE} (default), word matching
ignores capitalisation.}

\item{text_remove}{Regex pattern for characters to strip before
processing (e.g., brackets). Default
\code{"[()]"}.}

\item{...}{Additional arguments forwarded to
\code{\link{textTrainRegression}}.}
}
\value{
A named list:
\describe{
  \item{model_x}{The fitted \code{textTrainRegression} model for the x-axis.}
  \item{model_y}{(Only if `y` is supplied) Fitted model for the y-axis.}
  \item{word_data}{A tibble with one row per unique word containing:
    \code{words}, \code{n} (frequency), \code{word_mean_value_x},
    \code{x_plotted} (embedding-based prediction), \code{p_values_x}; plus
    the y-equivalents when `y` is provided.}
}
The comment attribute on the output stores a human-readable description of
all call parameters for reproducibility.
}
\description{
For each unique word in `words` the function:
\enumerate{
  \item Computes the **mean value of `x`** (and optionally `y`) across all
        participants whose response contained that word.
  \item Looks up the **decontextualised embedding** for that word from
        `word_types_embeddings`.
  \item Trains a **ridge regression** model: embedding -> mean x score. The
        out-of-sample predictions become the `x_plotted` plotting coordinate,
        allowing generalisation to words unseen in training.
  \item Optionally computes **permutation-based p-values** (see
        `n_permutations`) by shuffling `x` labels and building a null
        distribution of prediction scores.
}

The returned `word_data` tibble has column names that match the expectations
of \code{\link{textProjectionPlot}}: `x_plotted` (and `y_plotted`) for coordinates
and `p_values_x` (and `p_values_y`) for significance.
}
\examples{
\dontrun{
library(text)

# --- Step 1: embed the text column (produces text-level + word-type embeddings)
embeddings <- textEmbed(Language_based_assessment_data_8["harmonywords"])

# --- Step 2: run textWordPrediction
result <- textWordPrediction(
  words                 = Language_based_assessment_data_8$harmonywords,
  word_types_embeddings = embeddings$word_types,
  x                     = Language_based_assessment_data_8$hilstotal,
  n_models              = 5,      # 5 real fits with different CV seeds
  n_permutations        = 10000,  # 5 x 10 000 = 50 000 total null samples
  seed                  = 1003
)

# --- Step 3: inspect word-level scores
result$word_data

# --- Step 4: pass directly to textProjectionPlot
textProjectionPlot(result)
}

}
\seealso{
\code{\link{textProjection}}, \code{\link{textProjectionPlot}},
         \code{\link{textTrainRegression}}
}
