.. _auto_linear_regression:

*LINEAR REGRESSION*
===================

Fits a polynomial regression model (order 1–5 or auto-selected) of a dependent scalar variable against an independent scalar variable. Optionally scans the fitted curve over a user-defined range to find the independent value that minimizes or maximizes the dependent response.

When to use
-----------

Tagged: ``curve_fit``, ``linear_regression``, ``optimization``, ``polynomial_regression``, ``r2``, ``regression``, ``simulation``.

Inputs
------

.. list-table::
   :header-rows: 1
   :widths: 20 20 20 20 20 20

   * - Label
     - ID
     - Type
     - Default
     - Required
     - Description
   * - Independent
     - independent
     - scalar
     - —
     - ✓
     - Name or column reference of the independent (predictor) variable; must resolve to a numeric scalar series.
   * - Dependent
     - dependent
     - scalar
     - —
     - ✓
     - Name or column reference of the dependent (response) variable to be regressed against the independent variable; must resolve to a numeric scalar series.
   * - Optimize
     - optimize
     - select
     - no
     - 
     - Whether to scan the fitted polynomial for an optimum value within [minimum, maximum]; default 'no' skips the optimisation step.
   * - Minimum
     - minimum
     - scalar
     - —
     - ✓
     - Lower bound of the independent-variable search range used during optimisation; ignored when 'optimize' is 'no'.
   * - Maximum
     - maximum
     - scalar
     - —
     - ✓
     - Upper bound of the independent-variable search range used during optimisation; ignored when 'optimize' is 'no'.
   * - Step
     - step
     - scalar
     - 0.0001
     - ✓
     - Step size for the grid scan over [minimum, maximum] during optimisation; default 0.0001 — reduce only if finer resolution is needed, as smaller values increase compute time.
   * - Objective
     - objective
     - select
     - minimize
     - 
     - Direction of optimisation: 'minimize' finds the independent value yielding the lowest predicted response, 'maximize' finds the highest; default is 'minimize'.
   * - Order
     - order
     - select
     - 1
     - 
     - Polynomial degree of the regression fit (1 = linear, 2–5 = higher-order polynomial); select 'auto' to let the worker choose the best-fitting degree via cross-validation; default is 1.

Outputs
-------

.. list-table::
   :header-rows: 1
   :widths: 20 20 20 20

   * - Label
     - ID
     - Type
     - Description
   * - R2 of the Fit
     - r2
     - scalar
     - Coefficient of determination (R²) of the polynomial fit; dimensionless scalar in [0, 1], where values closer to 1 indicate a better fit.
   * - Optimum value
     - optimum_independent
     - scalar
     - Independent-variable value within [minimum, maximum] at which the fitted polynomial is minimized or maximized according to the chosen objective; only meaningful when 'optimize' is 'yes'.
   * - Independents
     - independents
     - keyvalue
     - Key-value map of the independent variable data points used in the regression, keyed by index or original label.
   * - Dependents
     - dependents
     - keyvalue
     - Key-value map of the dependent variable data points used in the regression, keyed by index or original label.
   * - Error vs Dependents
     - idc
     - vector
     - Vector of residual errors (predicted minus actual dependent values) plotted against the dependent variable, useful for diagnosing fit quality and heteroscedasticity.

Disciplines
-----------

- ai_ml.supervised.regression
- data.curve.transform
- design_exploration.optimization

.. raw:: html

   <hr style="margin-top:2em">
   <p style="font-size:11px;color:#888">
   Auto-generated from <code>platform</code> schema. Worker id: <code>linear_regression</code>. Schema hash: <code>e772e64f1278</code>. Hand-curated docs in <code>workerexamples/</code> override this page when present.
   </p>