% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/analyze.R
\name{analyze_by_attributes}
\alias{analyze_by_attributes}
\title{Analyze Survey Responses by Attributes}
\usage{
analyze_by_attributes(
  survey,
  attribute_file = NULL,
  scale_points,
  attribute_cols,
  emp_id_col = NULL,
  min_group_size = 5,
  plot = FALSE
)
}
\arguments{
\item{survey}{A \code{glint_survey} object or data frame. If attributes have
already been joined via \code{join_attributes()}, \code{attribute_file} can
be omitted.}

\item{attribute_file}{Optional. A file path (character string) or data frame
containing employee attributes to join. If \code{NULL} (default), the
survey must already contain the columns named in \code{attribute_cols}.}

\item{scale_points}{Integer specifying the number of scale points (2-11)}

\item{attribute_cols}{Character vector of column names to group by
(e.g., \code{c("Department", "Gender", "Tenure Group")})}

\item{emp_id_col}{Character string specifying the employee ID column name
in both the survey data and the attribute data}

\item{min_group_size}{Integer specifying the minimum number of employees
required for a group to be included in results (default: 5)}

\item{plot}{Logical. If \code{TRUE}, prints a faceted dot plot of Glint
Scores by attribute group (one facet per question) and returns the data
invisibly. When multiple \code{attribute_cols} are supplied, only the first
is plotted. Requires \pkg{ggplot2}. Default: \code{FALSE}.}
}
\value{
A tibble with one row per attribute-group-question combination
containing:
\describe{
\item{attribute columns}{Values for each attribute grouping variable}
\item{group_size}{Number of employees in this attribute group}
\item{question, mean, sd, n_responses, n_skips, n_total}{
Descriptive statistics for this group on this question}
\item{pct_favorable, pct_neutral, pct_unfavorable}{Favorability
percentages for this group on this question}
}
When \code{plot = TRUE}, the same tibble is returned invisibly after
printing the plot.
}
\description{
Aggregates survey responses by employee attributes (e.g., Department,
Gender, Tenure) and calculates the same metrics as \code{summarize_survey()}
for each attribute group combination. Only groups meeting the minimum size
threshold are included in the results.
}
\details{
Attributes can be supplied in two ways:
\enumerate{
\item Pass \code{attribute_file} (a file path or data frame) and the join
is performed internally on each call.
\item Pre-join attributes once with \code{join_attributes()} and pass the
enriched survey directly — omit \code{attribute_file} entirely. This is
more efficient when calling \code{analyze_by_attributes()} multiple times
or when you want to filter the data before analysis.
}
}
\examples{
survey_path <- system.file("extdata", "survey_export.csv", package = "vivaglint")
attr_file <- system.file("extdata", "employee_attributes.csv", package = "vivaglint")
survey <- read_glint_survey(survey_path, emp_id_col = "EMP ID")

# Option 1: provide attribute_file directly
results <- analyze_by_attributes(
  survey,
  attribute_file = attr_file,
  scale_points = 5,
  attribute_cols = "Department",
  emp_id_col = "EMP ID",
  min_group_size = 2
)

# Option 2: pre-join with join_attributes(), then omit attribute_file
survey_enriched <- join_attributes(survey, attr_file, emp_id_col = "EMP ID")
results <- analyze_by_attributes(survey_enriched, scale_points = 5,
                                 attribute_cols = "Department",
                                 emp_id_col = "EMP ID",
                                 min_group_size = 2)

# With dot plot
if (requireNamespace("ggplot2", quietly = TRUE)) {
  analyze_by_attributes(survey_enriched, scale_points = 5,
                        attribute_cols = "Department",
                        emp_id_col = "EMP ID", plot = TRUE,
                        min_group_size = 2)
}
}
