% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/write-by-group.R
\name{write_by_group}
\alias{write_by_group}
\title{Split a data frame by a grouping column and write each group to a CSV file}
\usage{
write_by_group(data, group_col, output_dir = NULL, manifest = FALSE)
}
\arguments{
\item{data}{A data frame or tibble to split and save.}

\item{group_col}{A string. The name of the column to group by.}

\item{output_dir}{A string or \code{NULL}. Path to the directory where output
files will be written. Created if it does not exist. If \code{NULL}, the
user must supply a path explicitly.}

\item{manifest}{A logical. Whether to write a \code{manifest.csv} file to
\code{output_dir} listing the output files, group values, and row counts.
Defaults to \code{FALSE}.}
}
\value{
Invisibly returns \code{output_dir}.
}
\description{
Splits a data frame by a single grouping column and writes each group to
a separate CSV file. Optionally writes a manifest file listing the output
files, their group values, and row counts.
}
\details{
Output filenames are derived from the group values of \code{group_col}.
Values are sanitized before use as filenames: converted to lowercase,
spaces and special characters replaced with \verb{_}, consecutive underscores
collapsed, and leading/trailing underscores stripped.

If \code{manifest = TRUE}, a \code{manifest.csv} is written to \code{output_dir}
containing three columns: \code{group_value}, \code{n_rows}, and \code{file_path}.

Note: \code{output_dir} has no default value. Always supply an explicit path
to avoid writing files to unexpected locations. Use \code{tempdir()} for
temporary output during testing or exploration.
}
\examples{
\donttest{
# Split a small data frame by group and write to a temp directory
data <- data.frame(
  species = c("Adelie", "Adelie", "Gentoo"),
  mass    = c(3750, 3800, 5000)
)
write_by_group(data, group_col = "species", output_dir = tempdir())

# Same but also write a manifest
write_by_group(data, group_col = "species",
               output_dir = tempdir(), manifest = TRUE)
}
}
