.. index:: single: classifier_common
.. _classifier_common/0:

.. rst-class:: right

**category**

``classifier_common``
=====================

Shared predicates for classifier diagnostics, dataset validation, mixed-feature distance calculations, and export.

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

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

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


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

| **Remarks:**
|    (none)

| **Inherited public predicates:**
|     :ref:`classifier_protocol/0::check_classifier/1`  :ref:`options_protocol/0::check_option/1`  :ref:`options_protocol/0::check_options/1`  :ref:`classifier_protocol/0::classifier_options/2`  :ref:`options_protocol/0::default_option/1`  :ref:`options_protocol/0::default_options/1`  :ref:`classifier_protocol/0::diagnostic/2`  :ref:`classifier_protocol/0::diagnostics/2`  :ref:`classifier_protocol/0::export_to_clauses/4`  :ref:`classifier_protocol/0::export_to_file/4`  :ref:`classifier_protocol/0::learn/2`  :ref:`classifier_protocol/0::learn/3`  :ref:`options_protocol/0::option/2`  :ref:`options_protocol/0::option/3`  :ref:`classifier_protocol/0::predict/3`  :ref:`classifier_protocol/0::print_classifier/1`  :ref:`classifier_protocol/0::valid_classifier/1`  :ref:`options_protocol/0::valid_option/1`  :ref:`options_protocol/0::valid_options/1`  

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

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

(no local declarations; see entity ancestors if any)

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

.. index:: classifier_diagnostics_data/2
.. _classifier_common/0::classifier_diagnostics_data/2:

``classifier_diagnostics_data/2``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Hook predicate that importing classifier implementations must define in order to expose diagnostics metadata.

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

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


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

.. index:: classifier_export_template/4
.. _classifier_common/0::classifier_export_template/4:

``classifier_export_template/4``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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

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

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


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

.. index:: classifier_term_template/2
.. _classifier_common/0::classifier_term_template/2:

``classifier_term_template/2``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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

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

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


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

.. index:: print_classifier_template/1
.. _classifier_common/0::print_classifier_template/1:

``print_classifier_template/1``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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

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

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


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

.. index:: valid_attribute_names/1
.. _classifier_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_class_values/1
.. _classifier_common/0::valid_class_values/1:

``valid_class_values/1``
^^^^^^^^^^^^^^^^^^^^^^^^

True when a list of class values is a non-empty proper list of distinct atoms.

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

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


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

.. index:: valid_feature_types/2
.. _classifier_common/0::valid_feature_types/2:

``valid_feature_types/2``
^^^^^^^^^^^^^^^^^^^^^^^^^

True when a list of feature type tags is non-empty and each tag belongs to the given allowed set.

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

| **Template:**
|    ``valid_feature_types(FeatureTypes,AllowedTypes)``
| **Mode and number of proofs:**
|    ``valid_feature_types(+list,+list)`` - ``zero_or_one``


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

.. index:: valid_discrete_values/1
.. _classifier_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_linear_encoders/1
.. _classifier_common/0::valid_linear_encoders/1:

``valid_linear_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_linear_encoders(Encoders)``
| **Mode and number of proofs:**
|    ``valid_linear_encoders(+list(compound))`` - ``zero_or_one``


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

.. index:: dataset_attributes/2
.. _classifier_common/0::dataset_attributes/2:

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

Collects the declared dataset attributes and their value domains.

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

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


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

.. index:: dataset_examples/2
.. _classifier_common/0::dataset_examples/2:

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

Collects the dataset training examples as ``Id-Class-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_non_empty/2
.. _classifier_common/0::check_examples_non_empty/2:

``check_examples_non_empty/2``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Checks that a training example collection is not empty.

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

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


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

.. index:: check_examples/2
.. _classifier_common/0::check_examples/2:

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

Checks that a training dataset is non-empty, that all example classes belong to the declared class values, and that provided attribute bindings use declared attributes with values matching the declared domains. Missing attribute bindings are allowed.

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

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

| **Exceptions:**
|    ``Examples`` is empty:
|        ``domain_error(non_empty_dataset,Dataset)``
|    ``Dataset`` class values declaration is invalid:
|        ``domain_error(class_values,ClassValues)``
|    An example class is not one of the declared class values:
|        ``domain_error(dataset_example_class,Class)``
|    An example attribute binding uses an undeclared attribute or a value outside the declared attribute domain:
|        ``domain_error(dataset_example_attribute_values,AttributeValues)``


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

.. index:: check_complete_examples/2
.. _classifier_common/0::check_complete_examples/2:

``check_complete_examples/2``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Checks that a training dataset is non-empty, that all example classes belong to the declared class values, and that each example contains every declared attribute exactly once with values matching the declared domains. Missing values represented using variables are allowed.

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

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

| **Exceptions:**
|    ``Examples`` is empty:
|        ``domain_error(non_empty_dataset,Dataset)``
|    ``Dataset`` class values declaration is invalid:
|        ``domain_error(class_values,ClassValues)``
|    An example class is not one of the declared class values:
|        ``domain_error(dataset_example_class,Class)``
|    An example attribute set is missing a declared attribute, contains a duplicate attribute, uses an undeclared attribute, or contains a non-variable value outside the declared attribute domain:
|        ``domain_error(dataset_example_attribute_values,AttributeValues)``


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

.. index:: check_complete_examples_nonvar/2
.. _classifier_common/0::check_complete_examples_nonvar/2:

``check_complete_examples_nonvar/2``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Checks that a training dataset is non-empty, that all example classes belong to the declared class values, and that each example contains every declared attribute exactly once with non-variable values matching the declared domains.

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

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

| **Exceptions:**
|    ``Examples`` is empty:
|        ``domain_error(non_empty_dataset,Dataset)``
|    ``Dataset`` class values declaration is invalid:
|        ``domain_error(class_values,ClassValues)``
|    An example class is not one of the declared class values:
|        ``domain_error(dataset_example_class,Class)``
|    An example attribute set is missing a declared attribute, contains a duplicate attribute, uses an undeclared attribute, contains a variable value, or contains a value outside the declared attribute domain:
|        ``domain_error(dataset_example_attribute_values,AttributeValues)``


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

.. index:: build_linear_encoders/4
.. _classifier_common/0::build_linear_encoders/4:

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

Builds linear-model encoders for continuous and categorical attributes. Continuous encoders optionally standardize features when ``FeatureScaling`` is true.

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

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


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

.. index:: examples_to_linear_rows/3
.. _classifier_common/0::examples_to_linear_rows/3:

``examples_to_linear_rows/3``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Encodes examples into ``Features-Class`` rows using the given linear encoders.

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

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


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

.. index:: encode_linear_instance/3
.. _classifier_common/0::encode_linear_instance/3:

``encode_linear_instance/3``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Encodes an instance into a numeric feature vector using the given linear encoders.

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

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


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

.. index:: linear_encoders_feature_count/2
.. _classifier_common/0::linear_encoders_feature_count/2:

``linear_encoders_feature_count/2``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Computes the number of numeric features produced by a set of linear encoders.

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

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


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

.. index:: valid_classifier_metadata/2
.. _classifier_common/0::valid_classifier_metadata/2:

``valid_classifier_metadata/2``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

True when diagnostics metadata contains the expected model term.

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

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


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

.. index:: valid_classifier_metadata/3
.. _classifier_common/0::valid_classifier_metadata/3:

``valid_classifier_metadata/3``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

True when diagnostics metadata contains the expected model term and records the given effective options.

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

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


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

.. index:: mixed_feature_distance/5
.. _classifier_common/0::mixed_feature_distance/5:

``mixed_feature_distance/5``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Computes a distance between two mixed-feature vectors using the given feature types and one of the supported metrics ``euclidean``, ``manhattan``, ``chebyshev``, ``cosine``, or ``minkowski(Order)``.

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

| **Template:**
|    ``mixed_feature_distance(Metric,FeatureTypes,Values1,Values2,Distance)``
| **Mode and number of proofs:**
|    ``mixed_feature_distance(+term,+list,+list,+list,-float)`` - ``one_or_error``

| **Exceptions:**
|    ``Metric`` is ``minkowski(Order)`` and ``Order`` is not a positive number:
|        ``domain_error(positive_number,Order)``


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

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

(no local declarations; see entity ancestors if any)

Operators
---------

(none)

