.. index:: single: regressor_common
.. _regressor_common/0:

.. rst-class:: right

**category**

``regressor_common``
====================

Shared predicates for regressor learning defaults, diagnostics, validation, dataset validation, export, and pretty-print helpers.

| **Availability:** 
|    ``logtalk_load(regression_protocols(loader))``

| **Author:** Paulo Moura
| **Version:** 1:1:1
| **Date:** 2026-06-14

| **Compilation flags:**
|    ``static``


| **Implements:**
|    ``public`` :ref:`regressor_protocol <regressor_protocol/0>`
| **Extends:**
|    ``public`` :ref:`options <options/0>`
| **Uses:**
|    :ref:`format <format/0>`
|    :ref:`linear_algebra <linear_algebra/0>`
|    :ref:`list <list/0>`
|    :ref:`numberlist <numberlist/0>`
|    :ref:`population <population/0>`
|    :ref:`type <type/0>`

| **Remarks:**
|    (none)

| **Inherited public predicates:**
|     :ref:`options_protocol/0::check_option/1`  :ref:`options_protocol/0::check_options/1`  :ref:`regressor_protocol/0::check_regressor/1`  :ref:`options_protocol/0::default_option/1`  :ref:`options_protocol/0::default_options/1`  :ref:`regressor_protocol/0::diagnostic/2`  :ref:`regressor_protocol/0::diagnostics/2`  :ref:`regressor_protocol/0::export_to_clauses/4`  :ref:`regressor_protocol/0::export_to_file/4`  :ref:`regressor_protocol/0::learn/2`  :ref:`regressor_protocol/0::learn/3`  :ref:`options_protocol/0::option/2`  :ref:`options_protocol/0::option/3`  :ref:`regressor_protocol/0::predict/3`  :ref:`regressor_protocol/0::print_regressor/1`  :ref:`regressor_protocol/0::regressor_options/2`  :ref:`options_protocol/0::valid_option/1`  :ref:`options_protocol/0::valid_options/1`  :ref:`regressor_protocol/0::valid_regressor/1`  

.. contents::
   :local:
   :backlinks: top

Public predicates
-----------------

(no local declarations; see entity ancestors if any)

Protected predicates
--------------------

.. index:: regressor_diagnostics_data/2
.. _regressor_common/0::regressor_diagnostics_data/2:

``regressor_diagnostics_data/2``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Default hook predicate for exposing diagnostics metadata from a regressor term. Importing implementations may override it when using a non-standard regressor representation.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``regressor_diagnostics_data(Regressor,Diagnostics)``
| **Mode and number of proofs:**
|    ``regressor_diagnostics_data(+compound,-list(compound))`` - ``one``


------------

.. index:: regressor_export_template/4
.. _regressor_common/0::regressor_export_template/4:

``regressor_export_template/4``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Hook predicate that importing regressor implementations must define in order to expose the exported regressor template for a given functor.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``regressor_export_template(Dataset,Regressor,Functor,Template)``
| **Mode and number of proofs:**
|    ``regressor_export_template(+object_identifier,+compound,+atom,-callable)`` - ``one``


------------

.. index:: regressor_term_template/2
.. _regressor_common/0::regressor_term_template/2:

``regressor_term_template/2``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Hook predicate that importing regressor implementations must define in order to expose the learned regressor term template used by pretty-printing helpers.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``regressor_term_template(Regressor,Template)``
| **Mode and number of proofs:**
|    ``regressor_term_template(+compound,-callable)`` - ``one``


------------

.. index:: dataset_attributes/2
.. _regressor_common/0::dataset_attributes/2:

``dataset_attributes/2``
^^^^^^^^^^^^^^^^^^^^^^^^

Collects the dataset attribute declarations as `Attribute-Values` pairs.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``dataset_attributes(Dataset,Attributes)``
| **Mode and number of proofs:**
|    ``dataset_attributes(+object_identifier,-list(pair))`` - ``one``


------------

.. index:: dataset_examples/2
.. _regressor_common/0::dataset_examples/2:

``dataset_examples/2``
^^^^^^^^^^^^^^^^^^^^^^

Collects the dataset examples as `example(Id, TargetValue, AttributeValues)` terms.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``dataset_examples(Dataset,Examples)``
| **Mode and number of proofs:**
|    ``dataset_examples(+object_identifier,-list(compound))`` - ``one``


------------

.. index:: check_examples/2
.. _regressor_common/0::check_examples/2:

``check_examples/2``
^^^^^^^^^^^^^^^^^^^^

Validates that the collected examples list is non-empty, only contains numeric targets, and only uses declared attributes without duplicate bindings.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``check_examples(Dataset,Examples)``
| **Mode and number of proofs:**
|    ``check_examples(+object_identifier,+list)`` - ``one_or_error``

| **Exceptions:**
|    Examples is the empty list:
|        ``domain_error(non_empty_dataset,Dataset)``
|    An example target is not numeric:
|        ``type_error(number,Target)``
|    An example repeats a declared attribute binding:
|        ``domain_error(attribute_occurrences,Attribute)``
|    An example contains an undeclared attribute binding:
|        ``domain_error(declared_attribute,Attribute)``


------------

.. index:: print_regressor_template/1
.. _regressor_common/0::print_regressor_template/1:

``print_regressor_template/1``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Pretty-printing helper predicate used by importing regressor implementations to show the learned regressor term template.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``print_regressor_template(Regressor)``
| **Mode and number of proofs:**
|    ``print_regressor_template(+compound)`` - ``one``


------------

.. index:: base_regressor_diagnostics/6
.. _regressor_common/0::base_regressor_diagnostics/6:

``base_regressor_diagnostics/6``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Builds common diagnostics metadata terms for a learned regressor and appends regressor-specific diagnostics terms.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``base_regressor_diagnostics(Model,Target,TrainingExampleCount,Options,ExtraDiagnostics,Diagnostics)``
| **Mode and number of proofs:**
|    ``base_regressor_diagnostics(+atom,+atom,+integer,+list(compound),+list(compound),-list(compound))`` - ``one``


------------

.. index:: valid_attribute_names/1
.. _regressor_common/0::valid_attribute_names/1:

``valid_attribute_names/1``
^^^^^^^^^^^^^^^^^^^^^^^^^^^

True when a list of attribute names is a proper list of distinct atoms.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``valid_attribute_names(AttributeNames)``
| **Mode and number of proofs:**
|    ``valid_attribute_names(+list(atom))`` - ``zero_or_one``


------------

.. index:: valid_attribute_declarations/1
.. _regressor_common/0::valid_attribute_declarations/1:

``valid_attribute_declarations/1``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

True when a list of attribute declarations is a proper list of distinct ``Attribute-Values`` pairs where values are either ``continuous`` or a valid discrete value list.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``valid_attribute_declarations(Attributes)``
| **Mode and number of proofs:**
|    ``valid_attribute_declarations(+list(pair))`` - ``zero_or_one``


------------

.. index:: valid_discrete_values/1
.. _regressor_common/0::valid_discrete_values/1:

``valid_discrete_values/1``
^^^^^^^^^^^^^^^^^^^^^^^^^^^

True when a list of categorical values is non-empty, contains only nonvar terms, and has no duplicates.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``valid_discrete_values(Values)``
| **Mode and number of proofs:**
|    ``valid_discrete_values(+list)`` - ``zero_or_one``


------------

.. index:: valid_regression_encoders/1
.. _regressor_common/0::valid_regression_encoders/1:

``valid_regression_encoders/1``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

True when a list of encoders only contains valid ``continuous/3`` or ``categorical/2`` encoder terms with distinct attributes.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``valid_regression_encoders(Encoders)``
| **Mode and number of proofs:**
|    ``valid_regression_encoders(+list(compound))`` - ``zero_or_one``


------------

.. index:: valid_regressor_options/1
.. _regressor_common/0::valid_regressor_options/1:

``valid_regressor_options/1``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

True when a list of options is structurally valid for the receiving regressor implementation.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``valid_regressor_options(Options)``
| **Mode and number of proofs:**
|    ``valid_regressor_options(+list(compound))`` - ``zero_or_one``


------------

.. index:: valid_regressor_metadata/2
.. _regressor_common/0::valid_regressor_metadata/2:

``valid_regressor_metadata/2``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

True when diagnostics metadata contains the expected model term and records a structurally valid effective options list.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``valid_regressor_metadata(Model,Diagnostics)``
| **Mode and number of proofs:**
|    ``valid_regressor_metadata(+atom,+list(compound))`` - ``zero_or_one``


------------

.. index:: valid_diagnostic_count/3
.. _regressor_common/0::valid_diagnostic_count/3:

``valid_diagnostic_count/3``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

True when diagnostics contains a count term with the given functor and integer value.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``valid_diagnostic_count(Functor,Diagnostics,Count)``
| **Mode and number of proofs:**
|    ``valid_diagnostic_count(+atom,+list(compound),+integer)`` - ``zero_or_one``


------------

.. index:: valid_linear_model_diagnostics/1
.. _regressor_common/0::valid_linear_model_diagnostics/1:

``valid_linear_model_diagnostics/1``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

True when diagnostics contains structurally valid linear-model optimization metadata terms for convergence, completed iterations, and final parameter delta.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``valid_linear_model_diagnostics(Diagnostics)``
| **Mode and number of proofs:**
|    ``valid_linear_model_diagnostics(+list(compound))`` - ``zero_or_one``


------------

.. index:: valid_encoded_rows/2
.. _regressor_common/0::valid_encoded_rows/2:

``valid_encoded_rows/2``
^^^^^^^^^^^^^^^^^^^^^^^^

True when encoded training rows match the feature count induced by the encoders and carry numeric targets.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``valid_encoded_rows(Encoders,Rows)``
| **Mode and number of proofs:**
|    ``valid_encoded_rows(+list(compound),+list)`` - ``zero_or_one``


------------

.. index:: encoded_feature_count/2
.. _regressor_common/0::encoded_feature_count/2:

``encoded_feature_count/2``
^^^^^^^^^^^^^^^^^^^^^^^^^^^

Counts the number of numeric features induced by a list of continuous and categorical encoders, including missing-value indicator features.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``encoded_feature_count(Encoders,FeatureCount)``
| **Mode and number of proofs:**
|    ``encoded_feature_count(+list(compound),-integer)`` - ``one``


------------

.. index:: continuous_stats/5
.. _regressor_common/0::continuous_stats/5:

``continuous_stats/5``
^^^^^^^^^^^^^^^^^^^^^^

Computes the mean and scaling factor used to encode a continuous attribute from the training examples according to the effective feature scaling option.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``continuous_stats(Attribute,Examples,Options,Mean,Scale)``
| **Mode and number of proofs:**
|    ``continuous_stats(+atom,+list(compound),+list(compound),-float,-positive_float)`` - ``one``


------------

.. index:: examples_to_rows/3
.. _regressor_common/0::examples_to_rows/3:

``examples_to_rows/3``
^^^^^^^^^^^^^^^^^^^^^^

Encodes dataset examples as numeric feature-vector and target pairs using a list of encoders.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``examples_to_rows(Examples,Encoders,Rows)``
| **Mode and number of proofs:**
|    ``examples_to_rows(+list(compound),+list(compound),-list(pair))`` - ``one``


------------

.. index:: encode_instance/3
.. _regressor_common/0::encode_instance/3:

``encode_instance/3``
^^^^^^^^^^^^^^^^^^^^^

Validates and encodes an attribute-value list as a numeric feature vector using a list of continuous and categorical encoders.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``encode_instance(Encoders,AttributeValues,Features)``
| **Mode and number of proofs:**
|    ``encode_instance(+list(compound),+list(pair),-list(float))`` - ``one``


------------

.. index:: fit_linear_model/7
.. _regressor_common/0::fit_linear_model/7:

``fit_linear_model/7``
^^^^^^^^^^^^^^^^^^^^^^

Builds linear-model encoders from the training dataset, encodes the examples, fits an ordinary least-squares bias plus weight vector using the linear_algebra least-squares solver, and returns solver diagnostics terms.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``fit_linear_model(Dataset,Options,Encoders,TrainingExampleCount,Bias,Weights,TrainingDiagnostics)``
| **Mode and number of proofs:**
|    ``fit_linear_model(+object_identifier,+list(compound),-list(compound),-integer,-float,-list(float),-list(compound))`` - ``one``


------------

.. index:: fit_ridge_model/7
.. _regressor_common/0::fit_ridge_model/7:

``fit_ridge_model/7``
^^^^^^^^^^^^^^^^^^^^^

Builds linear-model encoders from the training dataset, encodes the examples, fits a bias plus weight vector by solving the ridge normal equations with partial pivoting, and returns ridge-specific diagnostics terms.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``fit_ridge_model(Dataset,Options,Encoders,TrainingExampleCount,Bias,Weights,TrainingDiagnostics)``
| **Mode and number of proofs:**
|    ``fit_ridge_model(+object_identifier,+list(compound),-list(compound),-integer,-float,-list(float),-list(compound))`` - ``one``


------------

.. index:: valid_feature_labels/1
.. _regressor_common/0::valid_feature_labels/1:

``valid_feature_labels/1``
^^^^^^^^^^^^^^^^^^^^^^^^^^

True when a list of regression-tree feature labels only contains valid ``feature/2`` terms.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``valid_feature_labels(FeatureLabels)``
| **Mode and number of proofs:**
|    ``valid_feature_labels(+list(compound))`` - ``zero_or_one``


------------

.. index:: valid_regression_tree/2
.. _regressor_common/0::valid_regression_tree/2:

``valid_regression_tree/2``
^^^^^^^^^^^^^^^^^^^^^^^^^^^

True when a regression tree only contains valid ``leaf/1`` and ``node/5`` terms using feature indexes within bounds.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``valid_regression_tree(Tree,FeatureCount)``
| **Mode and number of proofs:**
|    ``valid_regression_tree(+compound,+positive_integer)`` - ``zero_or_one``


------------

Private predicates
------------------

.. index:: check_attribute_declarations/1
.. _regressor_common/0::check_attribute_declarations/1:

``check_attribute_declarations/1``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Checks that dataset attribute declarations use distinct attribute names and valid value domains.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``check_attribute_declarations(Attributes)``
| **Mode and number of proofs:**
|    ``check_attribute_declarations(+list(pair))`` - ``one_or_error``

| **Exceptions:**
|    An attribute is declared more than once or uses an invalid value domain:
|        ``domain_error(attribute_declarations,Attribute)``


------------

.. index:: known_attribute_values/3
.. _regressor_common/0::known_attribute_values/3:

``known_attribute_values/3``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Collects the known numeric values for a continuous attribute from the training examples, skipping omitted and variable values.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``known_attribute_values(Examples,Attribute,Values)``
| **Mode and number of proofs:**
|    ``known_attribute_values(+list(compound),+atom,-list(number))`` - ``one``


------------

.. index:: check_attribute_bindings/2
.. _regressor_common/0::check_attribute_bindings/2:

``check_attribute_bindings/2``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Checks that an attribute-value list contains only declared attributes and does not repeat any declared attribute; omitted declared attributes are allowed and treated as missing values.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``check_attribute_bindings(AttributeNames,AttributeValues)``
| **Mode and number of proofs:**
|    ``check_attribute_bindings(+list(atom),+list(pair))`` - ``one``


------------

.. index:: check_declared_attribute_bindings/2
.. _regressor_common/0::check_declared_attribute_bindings/2:

``check_declared_attribute_bindings/2``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Checks that no declared attribute appears more than once in an attribute-value list.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``check_declared_attribute_bindings(AttributeNames,AttributeValues)``
| **Mode and number of proofs:**
|    ``check_declared_attribute_bindings(+list(atom),+list(pair))`` - ``one``


------------

.. index:: check_undeclared_attribute_bindings/2
.. _regressor_common/0::check_undeclared_attribute_bindings/2:

``check_undeclared_attribute_bindings/2``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Checks that every attribute occurring in an attribute-value list is declared.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``check_undeclared_attribute_bindings(AttributeValues,AttributeNames)``
| **Mode and number of proofs:**
|    ``check_undeclared_attribute_bindings(+list(pair),+list(atom))`` - ``one``


------------

.. index:: attribute_occurrences/4
.. _regressor_common/0::attribute_occurrences/4:

``attribute_occurrences/4``
^^^^^^^^^^^^^^^^^^^^^^^^^^^

Counts the number of times an attribute occurs in an attribute-value list.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``attribute_occurrences(AttributeValues,Attribute,Count0,Count)``
| **Mode and number of proofs:**
|    ``attribute_occurrences(+list(pair),+atom,+integer,-integer)`` - ``one``


------------

.. index:: declared_attribute_names/2
.. _regressor_common/0::declared_attribute_names/2:

``declared_attribute_names/2``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Collects the declared attribute names from dataset attribute declarations.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``declared_attribute_names(Attributes,AttributeNames)``
| **Mode and number of proofs:**
|    ``declared_attribute_names(+list(pair),-list(atom))`` - ``one``


------------

.. index:: encoder_attribute_names/2
.. _regressor_common/0::encoder_attribute_names/2:

``encoder_attribute_names/2``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Collects the declared attribute names from a list of regression encoders.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``encoder_attribute_names(Encoders,AttributeNames)``
| **Mode and number of proofs:**
|    ``encoder_attribute_names(+list(compound),-list(atom))`` - ``one``


------------

.. index:: encode_instance_checked/3
.. _regressor_common/0::encode_instance_checked/3:

``encode_instance_checked/3``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Encodes an already validated attribute-value list as a numeric feature vector using a list of continuous and categorical encoders.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``encode_instance_checked(Encoders,AttributeValues,Features)``
| **Mode and number of proofs:**
|    ``encode_instance_checked(+list(compound),+list(pair),-list(float))`` - ``one``


------------

.. index:: valid_linear_model_convergence/1
.. _regressor_common/0::valid_linear_model_convergence/1:

``valid_linear_model_convergence/1``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

True when a linear-model optimization stop reason is recognized.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``valid_linear_model_convergence(Convergence)``
| **Mode and number of proofs:**
|    ``valid_linear_model_convergence(+atom)`` - ``zero_or_one``


------------

.. index:: normalize_continuous/4
.. _regressor_common/0::normalize_continuous/4:

``normalize_continuous/4``
^^^^^^^^^^^^^^^^^^^^^^^^^^

Normalizes a continuous value using a stored mean and scale.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``normalize_continuous(Value,Mean,Scale,Feature)``
| **Mode and number of proofs:**
|    ``normalize_continuous(+number,+float,+positive_float,-float)`` - ``one``


------------

.. index:: check_categorical_value/3
.. _regressor_common/0::check_categorical_value/3:

``check_categorical_value/3``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Validates that a categorical value is declared for an attribute.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``check_categorical_value(Attribute,Values,Value)``
| **Mode and number of proofs:**
|    ``check_categorical_value(+atom,+list,+nonvar)`` - ``one``


------------

.. index:: one_hot_encode/4
.. _regressor_common/0::one_hot_encode/4:

``one_hot_encode/4``
^^^^^^^^^^^^^^^^^^^^

Encodes a declared categorical value using reference-level dummy coding plus a trailing missing-value indicator feature set to zero.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``one_hot_encode(Values,Value,Encoded,Tail)``
| **Mode and number of proofs:**
|    ``one_hot_encode(+list,+nonvar,-list(float),+list(float))`` - ``one``


------------

.. index:: missing_one_hot_encode/3
.. _regressor_common/0::missing_one_hot_encode/3:

``missing_one_hot_encode/3``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Encodes a missing categorical value as reference-level dummy zeroes plus a trailing missing-value indicator feature set to one.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``missing_one_hot_encode(Values,Encoded,Tail)``
| **Mode and number of proofs:**
|    ``missing_one_hot_encode(+list,-list(float),+list(float))`` - ``one``


------------

.. index:: zero_vector_from_values/3
.. _regressor_common/0::zero_vector_from_values/3:

``zero_vector_from_values/3``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Creates a zero vector with one element per supplied categorical value slot.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``zero_vector_from_values(Values,Zeroes,Tail)``
| **Mode and number of proofs:**
|    ``zero_vector_from_values(+list,-list(float),+list(float))`` - ``one``


------------

.. index:: build_linear_encoders/4
.. _regressor_common/0::build_linear_encoders/4:

``build_linear_encoders/4``
^^^^^^^^^^^^^^^^^^^^^^^^^^^

Builds the encoder list used by linear models from dataset attribute declarations, training examples, and the effective feature scaling option.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``build_linear_encoders(Attributes,Examples,Options,Encoders)``
| **Mode and number of proofs:**
|    ``build_linear_encoders(+list(pair),+list(compound),+list(compound),-list(compound))`` - ``one``


------------

.. index:: train_linear_model/6
.. _regressor_common/0::train_linear_model/6:

``train_linear_model/6``
^^^^^^^^^^^^^^^^^^^^^^^^

Fits an ordinary least-squares linear model bias and weight vector from encoded rows by delegating the solve and rank estimation to the linear_algebra library and returns solver diagnostics terms.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``train_linear_model(Rows,FeatureCount,Options,Bias,Weights,TrainingDiagnostics)``
| **Mode and number of proofs:**
|    ``train_linear_model(+list(pair),+integer,+list(compound),-float,-list(float),-list(compound))`` - ``one``


------------

.. index:: rows_to_design_matrix/3
.. _regressor_common/0::rows_to_design_matrix/3:

``rows_to_design_matrix/3``
^^^^^^^^^^^^^^^^^^^^^^^^^^^

Transforms encoded training rows into a row-oriented design matrix with a leading intercept column and a target vector.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``rows_to_design_matrix(Rows,DesignMatrix,Targets)``
| **Mode and number of proofs:**
|    ``rows_to_design_matrix(+list(pair),-list(list(float)),-list(float))`` - ``one``


------------

.. index:: residual_sum_of_squares/4
.. _regressor_common/0::residual_sum_of_squares/4:

``residual_sum_of_squares/4``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Computes the residual sum of squares for encoded training rows and a learned intercept plus weight vector.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``residual_sum_of_squares(Rows,Bias,Weights,ResidualSumOfSquares)``
| **Mode and number of proofs:**
|    ``residual_sum_of_squares(+list(pair),+float,+list(float),-float)`` - ``one``


------------

.. index:: train_ridge_model/6
.. _regressor_common/0::train_ridge_model/6:

``train_ridge_model/6``
^^^^^^^^^^^^^^^^^^^^^^^

Fits a ridge model bias and weight vector from encoded rows by solving a direct weighted linear system and returns diagnostics terms describing the solve.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``train_ridge_model(Rows,FeatureCount,Options,Bias,Weights,TrainingDiagnostics)``
| **Mode and number of proofs:**
|    ``train_ridge_model(+list(pair),+integer,+list(compound),-float,-list(float),-list(compound))`` - ``one``


------------

.. index:: ridge_feature_statistics/3
.. _regressor_common/0::ridge_feature_statistics/3:

``ridge_feature_statistics/3``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Computes per-feature ridge penalty weights and active-feature flags from encoded training rows, dropping zero-variance columns from the direct solve.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``ridge_feature_statistics(Rows,PenaltyWeights,ActiveFlags)``
| **Mode and number of proofs:**
|    ``ridge_feature_statistics(+list(pair),-list(float),-list(atom))`` - ``one``


------------

.. index:: accumulate_feature_statistics/5
.. _regressor_common/0::accumulate_feature_statistics/5:

``accumulate_feature_statistics/5``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Accumulates per-feature sums and squared sums over encoded training rows.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``accumulate_feature_statistics(Rows,Sums0,SumSquares0,Sums,SumSquares)``
| **Mode and number of proofs:**
|    ``accumulate_feature_statistics(+list(pair),+list(float),+list(float),-list(float),-list(float))`` - ``one``


------------

.. index:: add_squared_vector/3
.. _regressor_common/0::add_squared_vector/3:

``add_squared_vector/3``
^^^^^^^^^^^^^^^^^^^^^^^^

Adds the element-wise squares of a feature vector to an accumulated vector.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``add_squared_vector(Features,AccumulatedSquares0,AccumulatedSquares)``
| **Mode and number of proofs:**
|    ``add_squared_vector(+list(float),+list(float),-list(float))`` - ``one``


------------

.. index:: feature_penalty_profiles/5
.. _regressor_common/0::feature_penalty_profiles/5:

``feature_penalty_profiles/5``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Builds ridge penalty weights and active-feature flags from per-feature sums and squared sums.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``feature_penalty_profiles(Sums,SumSquares,Count,PenaltyWeights,ActiveFlags)``
| **Mode and number of proofs:**
|    ``feature_penalty_profiles(+list(float),+list(float),+integer,-list(float),-list(atom))`` - ``one``


------------

.. index:: active_feature_count/2
.. _regressor_common/0::active_feature_count/2:

``active_feature_count/2``
^^^^^^^^^^^^^^^^^^^^^^^^^^

Counts the number of active encoded features retained for the direct ridge solve.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``active_feature_count(ActiveFlags,Count)``
| **Mode and number of proofs:**
|    ``active_feature_count(+list(atom),-integer)`` - ``one``


------------

.. index:: compress_rows/3
.. _regressor_common/0::compress_rows/3:

``compress_rows/3``
^^^^^^^^^^^^^^^^^^^

Filters encoded training rows down to the active feature subset selected for the direct ridge solve.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``compress_rows(Rows,ActiveFlags,CompressedRows)``
| **Mode and number of proofs:**
|    ``compress_rows(+list(pair),+list(atom),-list(pair))`` - ``one``


------------

.. index:: compress_features/3
.. _regressor_common/0::compress_features/3:

``compress_features/3``
^^^^^^^^^^^^^^^^^^^^^^^

Filters a feature vector down to the active feature subset selected for the direct ridge solve.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``compress_features(Features,ActiveFlags,CompressedFeatures)``
| **Mode and number of proofs:**
|    ``compress_features(+list(float),+list(atom),-list(float))`` - ``one``


------------

.. index:: compress_vector/3
.. _regressor_common/0::compress_vector/3:

``compress_vector/3``
^^^^^^^^^^^^^^^^^^^^^

Filters a numeric vector down to the active positions selected for the direct ridge solve.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``compress_vector(Vector,ActiveFlags,CompressedVector)``
| **Mode and number of proofs:**
|    ``compress_vector(+list(float),+list(atom),-list(float))`` - ``one``


------------

.. index:: build_ridge_system/5
.. _regressor_common/0::build_ridge_system/5:

``build_ridge_system/5``
^^^^^^^^^^^^^^^^^^^^^^^^

Builds the regularized linear system for the intercept plus active ridge coefficients.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``build_ridge_system(Rows,PenaltyWeights,Regularization,Matrix,Vector)``
| **Mode and number of proofs:**
|    ``build_ridge_system(+list(pair),+list(float),+float,-list(list(float)),-list(float))`` - ``one``


------------

.. index:: accumulate_ridge_system/5
.. _regressor_common/0::accumulate_ridge_system/5:

``accumulate_ridge_system/5``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Accumulates the unregularized normal-equation matrix and target vector for a set of active encoded rows.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``accumulate_ridge_system(Rows,Matrix0,Vector0,Matrix,Vector)``
| **Mode and number of proofs:**
|    ``accumulate_ridge_system(+list(pair),+list(list(float)),+list(float),-list(list(float)),-list(float))`` - ``one``


------------

.. index:: add_outer_product/4
.. _regressor_common/0::add_outer_product/4:

``add_outer_product/4``
^^^^^^^^^^^^^^^^^^^^^^^

Adds the outer product of two vectors to an accumulated matrix.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``add_outer_product(Vector1,Vector2,Matrix0,Matrix)``
| **Mode and number of proofs:**
|    ``add_outer_product(+list(float),+list(float),+list(list(float)),-list(list(float)))`` - ``one``


------------

.. index:: regularize_ridge_matrix/4
.. _regressor_common/0::regularize_ridge_matrix/4:

``regularize_ridge_matrix/4``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Adds the ridge penalty weights to the feature-feature diagonal block of a linear system matrix.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``regularize_ridge_matrix(Matrix0,PenaltyWeights,Regularization,Matrix)``
| **Mode and number of proofs:**
|    ``regularize_ridge_matrix(+list(list(float)),+list(float),+float,-list(list(float)))`` - ``one``


------------

.. index:: solve_linear_system/4
.. _regressor_common/0::solve_linear_system/4:

``solve_linear_system/4``
^^^^^^^^^^^^^^^^^^^^^^^^^

Solves a square linear system using partial pivoting Gaussian elimination and returns the solver name.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``solve_linear_system(Matrix,Vector,Solution,Solver)``
| **Mode and number of proofs:**
|    ``solve_linear_system(+list(list(float)),+list(float),-list(float),-atom)`` - ``one_or_error``

| **Exceptions:**
|    The linear system is singular because a pivot coefficient becomes numerically zero:
|        ``evaluation_error(zero_divisor)``


------------

.. index:: augment_rows/3
.. _regressor_common/0::augment_rows/3:

``augment_rows/3``
^^^^^^^^^^^^^^^^^^

Pairs each matrix row with its corresponding right-hand-side value for elimination.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``augment_rows(Matrix,Vector,Rows)``
| **Mode and number of proofs:**
|    ``augment_rows(+list(list(float)),+list(float),-list(compound))`` - ``one``


------------

.. index:: triangularize/2
.. _regressor_common/0::triangularize/2:

``triangularize/2``
^^^^^^^^^^^^^^^^^^^

Transforms an augmented matrix into upper-triangular form using partial pivoting.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``triangularize(Rows0,UpperRows)``
| **Mode and number of proofs:**
|    ``triangularize(+list(compound),-list(compound))`` - ``one_or_error``

| **Exceptions:**
|    A pivot coefficient is numerically zero during elimination:
|        ``evaluation_error(zero_divisor)``


------------

.. index:: select_pivot_row/3
.. _regressor_common/0::select_pivot_row/3:

``select_pivot_row/3``
^^^^^^^^^^^^^^^^^^^^^^

Selects the pivot row with the largest leading magnitude and returns the remaining rows.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``select_pivot_row(Rows0,PivotRow,RemainingRows)``
| **Mode and number of proofs:**
|    ``select_pivot_row(+list(compound),-compound,-list(compound))`` - ``one``


------------

.. index:: leading_magnitude/2
.. _regressor_common/0::leading_magnitude/2:

``leading_magnitude/2``
^^^^^^^^^^^^^^^^^^^^^^^

Returns the absolute leading coefficient magnitude of an augmented row.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``leading_magnitude(Row,Magnitude)``
| **Mode and number of proofs:**
|    ``leading_magnitude(+compound,-float)`` - ``one``


------------

.. index:: ensure_non_zero/1
.. _regressor_common/0::ensure_non_zero/1:

``ensure_non_zero/1``
^^^^^^^^^^^^^^^^^^^^^

Checks that a pivot coefficient is numerically non-zero.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``ensure_non_zero(Value)``
| **Mode and number of proofs:**
|    ``ensure_non_zero(+float)`` - ``one_or_error``

| **Exceptions:**
|    A pivot coefficient is numerically zero:
|        ``evaluation_error(zero_divisor)``


------------

.. index:: eliminate_rows/5
.. _regressor_common/0::eliminate_rows/5:

``eliminate_rows/5``
^^^^^^^^^^^^^^^^^^^^

Eliminates the leading coefficient from remaining augmented rows using a pivot row.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``eliminate_rows(Pivot,PivotTail,PivotValue,Rows0,Rows)``
| **Mode and number of proofs:**
|    ``eliminate_rows(+float,+list(float),+float,+list(compound),-list(compound))`` - ``one``


------------

.. index:: scaled_row_difference/4
.. _regressor_common/0::scaled_row_difference/4:

``scaled_row_difference/4``
^^^^^^^^^^^^^^^^^^^^^^^^^^^

Subtracts a scaled pivot tail from another row tail.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``scaled_row_difference(PivotTail,RowTail,Factor,Difference)``
| **Mode and number of proofs:**
|    ``scaled_row_difference(+list(float),+list(float),+float,-list(float))`` - ``one``


------------

.. index:: back_substitution/2
.. _regressor_common/0::back_substitution/2:

``back_substitution/2``
^^^^^^^^^^^^^^^^^^^^^^^

Performs back-substitution on an upper-triangular augmented matrix.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``back_substitution(UpperRows,Solution)``
| **Mode and number of proofs:**
|    ``back_substitution(+list(compound),-list(float))`` - ``one_or_error``

| **Exceptions:**
|    A diagonal coefficient is numerically zero during back-substitution:
|        ``evaluation_error(zero_divisor)``


------------

.. index:: maximum_linear_system_residual/4
.. _regressor_common/0::maximum_linear_system_residual/4:

``maximum_linear_system_residual/4``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Computes the maximum absolute residual of a solved linear system.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``maximum_linear_system_residual(Matrix,Vector,Solution,MaximumResidual)``
| **Mode and number of proofs:**
|    ``maximum_linear_system_residual(+list(list(float)),+list(float),+list(float),-float)`` - ``one``


------------

.. index:: expand_weights/3
.. _regressor_common/0::expand_weights/3:

``expand_weights/3``
^^^^^^^^^^^^^^^^^^^^

Expands active ridge coefficients back to the full encoded feature vector, inserting zeroes for dropped zero-variance features.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``expand_weights(ActiveFlags,ActiveWeights,Weights)``
| **Mode and number of proofs:**
|    ``expand_weights(+list(atom),+list(float),-list(float))`` - ``one``


------------

Operators
---------

(none)

