% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/shape-sensitivity.R
\name{janusplot_shape_sensitivity}
\alias{janusplot_shape_sensitivity}
\title{Shape-recognition sensitivity study}
\usage{
janusplot_shape_sensitivity(
  shapes = NULL,
  n_grid = c(50L, 100L, 200L, 500L),
  sigma_grid = c(0.02, 0.05, 0.1, 0.2, 0.4),
  n_rep = 200L,
  cutoffs = janusplot_shape_cutoffs(),
  parallel = FALSE,
  seed = 2026L,
  verbose = interactive()
)
}
\arguments{
\item{shapes}{Character vector of ground-truth names from
\code{\link[=janusplot_shape_sensitivity_shapes]{janusplot_shape_sensitivity_shapes()}}. Default \code{NULL} → all 14.}

\item{n_grid}{Integer vector of sample sizes. Default
\code{c(50L, 100L, 200L, 500L)}.}

\item{sigma_grid}{Numeric vector of noise levels (fraction of the
y-range). Default \code{c(0.02, 0.05, 0.10, 0.20, 0.40)}.}

\item{n_rep}{Integer. Replicates per cell. Default \code{200L}.}

\item{cutoffs}{Named list of classification thresholds; see
\code{\link[=janusplot_shape_cutoffs]{janusplot_shape_cutoffs()}}.}

\item{parallel}{Logical. If \code{TRUE} and \code{future.apply} is installed,
dispatch replicates in parallel. The caller is responsible for
configuring \code{future::plan()} (e.g. \code{future::plan(future::multisession)}).}

\item{seed}{Integer. Base seed — each fit uses \code{seed + row_index}
so results are reproducible and cell-permutation-invariant.}

\item{verbose}{Logical. Print progress messages to the console.
Default is \code{interactive()}.}
}
\value{
A data frame with one row per fit. Columns:
\describe{
\item{\code{truth}}{Ground-truth shape name.}
\item{\code{n}}{Sample size for this fit.}
\item{\code{sigma}}{Noise level for this fit.}
\item{\code{seed}}{RNG seed used.}
\item{\code{predicted}}{Classifier output at the fine (24-category) level.}
\item{\code{correct}}{Logical — does \code{predicted == truth}?}
\item{\code{archetype_truth}}{Expected archetype for \code{truth}.}
\item{\code{archetype_pred}}{Archetype of \code{predicted}.}
\item{\code{archetype_correct}}{Logical — archetype-level correctness.}
\item{\code{monotonicity_index}}{Monotonicity index \code{M} (see
\code{\link[=janusplot_shape_metrics]{janusplot_shape_metrics()}}).}
\item{\code{convexity_index}}{Convexity index \code{C} (see
\code{\link[=janusplot_shape_metrics]{janusplot_shape_metrics()}}).}
\item{\code{n_turn}, \code{n_inflect}}{Recovered turning-point and
inflection counts.}
\item{\code{error}}{\code{"gam_fit_failed"} when \code{mgcv::gam()} errored;
\code{NA} otherwise.}
}
}
\description{
\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#experimental}{\figure{lifecycle-experimental.svg}{options: alt='[Experimental]'}}}{\strong{[Experimental]}}

Run a full-factorial sensitivity sweep for the janusplot 24-category
shape classifier. For each combination of ground-truth shape, sample
size \code{n}, noise level \code{sigma}, and replicate, the sweep:
\enumerate{
\item Generates \code{n} points from the noiseless canonical curve on
\verb{[0, 1]} + Gaussian noise with SD = \code{sigma} (fraction of the
y-range, so signal-to-noise is comparable across shapes).
\item Fits \code{mgcv::gam(y ~ s(x), method = "REML")}.
\item Runs \code{\link[=janusplot_shape_metrics]{janusplot_shape_metrics()}} to classify the fitted smooth.
\item Records correctness at both the fine (24-category) and
archetype (7-family) levels.
}

The function is the package-native implementation of
\code{simulation/scripts/scenario_4_shape_recognition.R}. A small
precomputed dataset is shipped as \link{shape_sensitivity_demo} for
downstream examples without requiring users to re-run the sweep.
}
\examples{
# Tiny-run smoke test (< 2 seconds): 3 shapes x 2 n x 2 sigma x 5 reps.
res <- janusplot_shape_sensitivity(
  shapes     = c("linear_up", "u_shape", "wave"),
  n_grid     = c(100L, 200L),
  sigma_grid = c(0.05, 0.20),
  n_rep      = 5L,
  verbose    = FALSE
)
head(res)
janusplot_shape_sensitivity_summary(res, level = "archetype")
}
\seealso{
\code{\link[=janusplot_shape_sensitivity_summary]{janusplot_shape_sensitivity_summary()}},
\code{\link[=janusplot_shape_sensitivity_plot]{janusplot_shape_sensitivity_plot()}},
\code{\link[=janusplot_shape_sensitivity_shapes]{janusplot_shape_sensitivity_shapes()}}, \link{shape_sensitivity_demo}.

Other shape-sensitivity: 
\code{\link{janusplot_shape_sensitivity_plot}()},
\code{\link{janusplot_shape_sensitivity_shapes}()},
\code{\link{janusplot_shape_sensitivity_summary}()}
}
\concept{shape-sensitivity}
