% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/fd_compute.R
\name{fd_compute}
\alias{fd_compute}
\title{Compute features from featdelta definitions on in-memory data}
\usage{
fd_compute(
  data,
  defs,
  key,
  compute_envir = NULL,
  compute_strict = TRUE,
  verbose = FALSE,
  return_report = FALSE
)
}
\arguments{
\item{data}{A data frame/tibble containing the raw input variables used to
compute features.}

\item{defs}{A \code{featdelta_defs} object created by \code{fd_define()}.}

\item{key}{Character scalar naming the primary key column in \code{data}.}

\item{compute_envir}{Optional environment. If supplied, it overrides the
stored evaluation environment for expression-based steps.}

\item{compute_strict}{Logical. If \code{TRUE}, any failed step causes the overall
compute call to error after the per-step report is assembled. If \code{FALSE},
failed column steps return \code{NA} columns, and failed block steps return
\code{NA} columns only when \code{output_names} are known in advance.}

\item{verbose}{Logical. If \code{TRUE}, print progress messages and a short
summary.}

\item{return_report}{Logical. If \code{TRUE}, return a list with elements
\code{data} and \code{report}. If \code{FALSE}, return only the computed data frame and
attach the report as \code{attr(x, "fd_report")}.}
}
\value{
Either:
\itemize{
\item a data frame with class \code{"featdelta_features"} and attached report
attribute, or
\item a list \verb{\{data, report\}} with class
\code{"featdelta_compute_result"} when \code{return_report = TRUE}
}

The output preserves row order and row count relative to \code{data}.
}
\description{
Evaluates a \code{featdelta_defs} object created by \code{fd_define()} against an
in-memory data frame/tibble and returns a feature data frame containing the
key column plus computed feature columns.
}
\details{
\code{fd_compute()} is the package's pure in-memory execution step. It does not
access the database and does not use the featdelta context system.

Definition steps are evaluated sequentially in the order stored in \code{defs}.
This means later steps may depend on columns created by earlier steps in the
same compute call.

Guardrails implemented by \code{fd_compute()} are compute-specific:
\itemize{
\item validate the structure of the supplied defs object
\item validate result type and row alignment for each step
\item preserve 1:1 row alignment with the input data
\item reject output-name collisions with \code{key} and previously produced names
\item attach a per-step computation report
}

Guardrails that belong at definition time, such as malformed construction of
individual definition steps, should be handled by \code{fd_define()}.

Supported definition step types are:
\itemize{
\item ordinary single-column steps
\item \code{fd_block()} multi-column steps
}

For single-column steps, the result must be a supported vector-like output.

For block steps:
\itemize{
\item the result must be a \code{data.frame}
\item the number of rows must match \code{nrow(data)}
\item returned column names must be non-empty and unique
\item returned names must not collide with \code{key}
\item returned names must not collide with feature names already produced
earlier in the same compute run
}

If a block declares \code{expected_names}, then:
\itemize{
\item returned names must be a subset of \code{expected_names}
\item missing expected names are added as \code{NA}
\item final output order follows \code{expected_names}
}

Because definitions are evaluated sequentially, later steps may use:
\itemize{
\item raw input columns from \code{data}
\item columns produced by earlier single-column steps
\item columns produced by earlier block steps
}

Reordering or removing earlier steps may therefore break downstream
definitions. When evaluation fails with "object not found"-style errors,
\code{fd_compute()} augments the message with likely reasons.
}
\examples{
raw_df <- mtcars
raw_df$car_id <- seq_len(nrow(raw_df))

defs <- fd_define(
  hp_per_cyl = hp / cyl,
  engine_ratios = fd_block({
    data.frame(
      disp_per_cyl = disp / cyl,
      wt_per_hp = wt / hp
    )
  }),
  double_ratio = disp_per_cyl * 2
)

out <- fd_compute(
  data = raw_df,
  defs = defs,
  key = "car_id",
  compute_strict = TRUE
)

head(out)

}
\concept{featdelta compute helpers}
