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` regressor_protocol
Extends:
`public` options
Uses:
format
linear_algebra
list
numberlist
population
type
Remarks:
(none)
Inherited public predicates:
check_option/1 check_options/1 check_regressor/1 default_option/1 default_options/1 diagnostic/2 diagnostics/2 export_to_clauses/4 export_to_file/4 learn/2 learn/3 option/2 option/3 predict/3 print_regressor/1 regressor_options/2 valid_option/1 valid_options/1 valid_regressor/1

## Public predicates

(no local declarations; see entity ancestors if any)

## Protected predicates

### `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`

### `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`

### `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`

### `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`

### `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`

### `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)`

### `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`

### `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`

### `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`

### `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`

### `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`

### `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`

### `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`

### `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`

### `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`

### `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`

### `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`

### `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`

### `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`

### `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`

### `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`

### `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`

### `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`

### `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`

### `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

### `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)`

### `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`

### `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`

### `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`

### `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`

### `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`

### `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`

### `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`

### `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`

### `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`

### `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`

### `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`

### `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`

### `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`

### `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`

### `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`

### `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`

### `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`

### `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`

### `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`

### `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`

### `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`

### `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`

### `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`

### `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`

### `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`

### `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`

### `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`

### `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`

### `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`

### `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`

### `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`

### `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)`

### `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`

### `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)`

### `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`

### `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`

### `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)`

### `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`

### `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`

### `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)`

### `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`

### `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)