% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/awkreader_v2.R
\name{aggregated.fread}
\alias{aggregated.fread}
\title{Fast Stream Aggregation of Delimited Files via AWK}
\usage{
aggregated.fread(
  the.files,
  value.code = "data",
  delim = ",",
  file.pattern = NULL,
  recursive = FALSE,
  num.batches = 1,
  num.files.per.batch = 1000,
  summarize.with = NULL,
  return.as = "result",
  group.by = NULL,
  path.to.awk = "awk",
  file.header = "file",
  include.filename = FALSE,
  skip = 0,
  show.warnings = TRUE,
  nrows = Inf,
  sample.size.median = -1,
  return.data.table = TRUE
)
}
\arguments{
\item{the.files}{A character vector containing paths to the targeted delimited text datasets.}

\item{value.code}{A internal character tracking string for code generation mappings. Defaults to \code{"data"}.}

\item{delim}{A character string defining the field separator delimiter within files. Defaults to \code{","}.}

\item{file.pattern}{Optional character string to filter file names when \code{the.files} contains directory paths. Accepts simple extensions (e.g., \code{"csv"} or \code{".csv"}),
wildcards (e.g., \code{"*.csv"}), or regular expressions (e.g., \code{"\\.csv$"}). Default is \code{NULL} (includes all files).}

\item{recursive}{Logical. Should directory searches recurse into subdirectories when \code{the.files} contains directory paths? Default is \code{FALSE}.}

\item{num.batches}{An integer defining the processing grouping structure. Defaults to \code{1}.}

\item{num.files.per.batch}{An integer specifying the maximum threshold of files targeted per concurrent process execution loop. Defaults to \code{1000}.}

\item{summarize.with}{A named list specifying operations and target columns. Names must match supported functions:
\code{"sum"}, \code{"mean"}, or \code{"sd"}. Elements can include raw columns or functional call strings like \code{"sqrt(price)"}. Defaults to \code{NULL}.}

\item{return.as}{A character string defining what data is returned to the environment. Options include \code{"result"} (aggregated dataset), \code{"code"} (generated AWK commands), or \code{"all"} (a combined list of both). Defaults to \code{"result"}.}

\item{group.by}{A character vector or list containing column names to act as the aggregation grouping dimensions. Defaults to \code{NULL}.}

\item{path.to.awk}{A character string declaring the binary location execution path. Defaults to \code{"awk"}.}

\item{file.header}{A character string tracking column identification titles when filenames are tracked. Defaults to \code{"file"}.}

\item{include.filename}{A logical value indicating whether the tracking origin file string column should append to final structures. Defaults to \code{FALSE}.}

\item{skip}{An integer, list, or character regex pattern. Controls metadata/line skipping configuration routines before row parsing evaluations trigger. Defaults to \code{0}.}

\item{show.warnings}{A logical value determining whether underlying structural data warnings should surface during operation execution cycles. Defaults to \code{TRUE}.}

\item{nrows}{A numeric ceiling threshold limiting output aggregation allocations. Defaults to \code{Inf}.}

\item{sample.size.median}{Integer. Maximum number of observations per group used to compute streaming medians via the P-Square algorithm. A positive integer caps the sample size per group for
faster execution on large datasets. Set to \code{-1} (default) or \code{0} to compute across all rows without sampling.}

\item{return.data.table}{A logical value. If \code{TRUE}, returns a \code{data.table} object; otherwise, reverts the format to a standard base \code{data.frame}. Defaults to \code{TRUE}.}
}
\value{
Depending on the configuration argument passed to \code{return.as}, returns either a
\code{data.table} (\code{data.frame} if \code{return.data.table = FALSE}), a character vector representing full
system executable command configurations, or a combined metadata list package object.
}
\description{
High-performance aggregation and streaming of multiple tabular data files using an
optimized AWK engine pipeline. This function parses columns, groups multi-file inputs,
and calculates summarizations (like \code{sum()}, \code{mean()}, and \code{sd()}) natively in the shell
before pulling structured aggregates back into R. It safely evaluates scalar mathematical transformations
passed as strings (e.g., \code{"sqrt(col)"}).
}
\examples{
\donttest{
# Create a sample CSV file using base R mtcars dataset
tmp_file <- tempfile(fileext = ".csv")
write.csv(mtcars, tmp_file, row.names = FALSE)

# Aggregate data over multiple columns grouped by cylinders
agg_res <- aggregated.fread(
  the.files = tmp_file,
  group.by = "cyl",
  summarize.with = list(
    mean = list("hp", "mpg"),
    sd = "wt"
  ),
  return.as = "all"
)
print(agg_res$result)

# Clean up temporary file
unlink(tmp_file)
}
}
