% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/team_roster.R
\name{team_roster}
\alias{team_roster}
\title{Add team assignments to a roster}
\usage{
team_roster(
  roster,
  size,
  name = NULL,
  by = NULL,
  col = "team",
  pad = TRUE,
  shuffle = TRUE,
  seed = NULL
)
}
\arguments{
\item{roster}{Data frame. Course roster with one row per student.}

\item{size}{Integer. Target (maximum) team size. Within each group members are
split into \code{ceiling(n / size)} teams of as-equal-as-possible size. An error
is thrown if a group has fewer than \code{size} members.}

\item{name}{Character. A glue template for the team / repo name, used as-is if
supplied. May reference any column of \code{roster} as well as \code{team_id} (the
within-group team number). If \code{NULL} (default) the template is
\code{"team{team_id}"}, or \code{"{group}-team{team_id}"} when \code{by} is set.}

\item{by}{Character. Optional column name(s) in \code{roster} to form teams within
(e.g. a lab section). If \code{NULL} (default) teams are formed across the whole roster.}

\item{col}{Character. Name of the output column to add. Default \code{"team"}.}

\item{pad}{Logical or integer. Zero-padding applied to \code{team_id} before it is
substituted into \code{name}. \code{TRUE} (default) pads to a consistent width based on
the largest team number, \code{FALSE} leaves it as an integer, or supply an integer
for a fixed width.}

\item{shuffle}{Logical. Should members be randomly assigned to teams? Default \code{TRUE}.}

\item{seed}{Integer. Optional random seed for reproducible assignments.}
}
\value{
The \code{roster} data frame with \code{team_id} and \code{col} columns added.
}
\description{
\code{team_roster()} adds a team (or repo) name column to a roster data frame by
randomly grouping members into teams of a target \code{size}. Teams may be formed
within groups (e.g. lab sections) via \code{by}, and names are built from a
\link[glue:glue_data]{glue} template that can reference any column of \code{roster}
together with the generated \code{team_id}. When \code{by} is supplied and no \code{name} is
given, the grouping column(s) are folded into the default name so team names
stay unique across groups.
}
\examples{
\dontrun{
roster = readr::read_csv(system.file("roster.csv", package = "ghclass"))

# Teams of 4 across the whole roster -> "team01", "team02", ...
team_roster(roster, size = 4)

# Teams of 4 within each lab section, group folded into the default name
team_roster(roster, size = 4, by = "section", seed = 20250901)

# Custom name template (used exactly as written)
team_roster(
  roster, size = 4, by = "section",
  name = "hw1_lab{section}_team{team_id}", seed = 20250901
)
}

}
