.. index:: single: dimension_reducer_common
.. _dimension_reducer_common/0:

.. rst-class:: right

**category**

``dimension_reducer_common``
============================

Shared predicates for dimension reducer learning defaults, dataset helpers, transformation, export, and printing.

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

| **Author:** Paulo Moura
| **Version:** 1:0:0
| **Date:** 2026-05-07

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


| **Implements:**
|    ``public`` :ref:`dimension_reducer_protocol <dimension_reducer_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>`
|    :ref:`user <user/0>`

| **Remarks:**
|    (none)

| **Inherited public predicates:**
|     :ref:`dimension_reducer_protocol/0::check_dimension_reducer/1`  :ref:`options_protocol/0::check_option/1`  :ref:`options_protocol/0::check_options/1`  :ref:`options_protocol/0::default_option/1`  :ref:`options_protocol/0::default_options/1`  :ref:`dimension_reducer_protocol/0::diagnostic/2`  :ref:`dimension_reducer_protocol/0::diagnostics/2`  :ref:`dimension_reducer_protocol/0::dimension_reducer_options/2`  :ref:`dimension_reducer_protocol/0::export_to_clauses/4`  :ref:`dimension_reducer_protocol/0::export_to_file/4`  :ref:`dimension_reducer_protocol/0::learn/2`  :ref:`dimension_reducer_protocol/0::learn/3`  :ref:`options_protocol/0::option/2`  :ref:`options_protocol/0::option/3`  :ref:`dimension_reducer_protocol/0::print_dimension_reducer/1`  :ref:`dimension_reducer_protocol/0::transform/3`  :ref:`dimension_reducer_protocol/0::valid_dimension_reducer/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:: check_component_count/3
.. _dimension_reducer_common/0::check_component_count/3:

``check_component_count/3``
^^^^^^^^^^^^^^^^^^^^^^^^^^^

Checks that a requested component count does not exceed the supported maximum and returns the accepted count.

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

| **Template:**
|    ``check_component_count(RequestedComponentCount,MaxComponentCount,ComponentCount)``
| **Mode and number of proofs:**
|    ``check_component_count(+integer,+integer,-integer)`` - ``one``


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

.. index:: dimension_reducer_data/3
.. _dimension_reducer_common/0::dimension_reducer_data/3:

``dimension_reducer_data/3``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Default hook predicate for exposing the learned encoders and projection components from a reducer term. Importing implementations may override it when using a non-standard reducer representation.

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

| **Template:**
|    ``dimension_reducer_data(DimensionReducer,Encoders,Components)``
| **Mode and number of proofs:**
|    ``dimension_reducer_data(+compound,-list,-list)`` - ``one``


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

.. index:: dimension_reducer_diagnostics_data/2
.. _dimension_reducer_common/0::dimension_reducer_diagnostics_data/2:

``dimension_reducer_diagnostics_data/2``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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

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

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


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

.. index:: print_dimension_reducer_properties/1
.. _dimension_reducer_common/0::print_dimension_reducer_properties/1:

``print_dimension_reducer_properties/1``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Hook predicate that importing dimension reducer implementations must define in order to print the learned reducer in a human-readable form.

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

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


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

.. index:: example_attribute_values/2
.. _dimension_reducer_common/0::example_attribute_values/2:

``example_attribute_values/2``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Hook predicate that importing dimension reducer implementations must define in order to extract example attribute values from their local training example representation.

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

| **Template:**
|    ``example_attribute_values(Example,AttributeValues)``
| **Mode and number of proofs:**
|    ``example_attribute_values(+compound,-list(pair))`` - ``one``


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

.. index:: dataset_attributes/2
.. _dimension_reducer_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:: check_continuous_attributes/1
.. _dimension_reducer_common/0::check_continuous_attributes/1:

``check_continuous_attributes/1``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Checks that all declared dataset attributes are continuous.

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

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


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

.. index:: check_examples_non_empty/2
.. _dimension_reducer_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_example_values/2
.. _dimension_reducer_common/0::check_example_values/2:

``check_example_values/2``
^^^^^^^^^^^^^^^^^^^^^^^^^^

Checks that all example attribute values are present and numeric for the declared attributes.

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

| **Template:**
|    ``check_example_values(Examples,AttributeNames)``
| **Mode and number of proofs:**
|    ``check_example_values(+list,+list(atom))`` - ``one``


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

.. index:: check_example_attributes/2
.. _dimension_reducer_common/0::check_example_attributes/2:

``check_example_attributes/2``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Checks that a single example contains numeric values for all declared attributes.

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

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


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

.. index:: attribute_value/3
.. _dimension_reducer_common/0::attribute_value/3:

``attribute_value/3``
^^^^^^^^^^^^^^^^^^^^^

Looks up an attribute value in a list of `Attribute-Value` pairs.

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

| **Template:**
|    ``attribute_value(Attribute,AttributeValues,Value)``
| **Mode and number of proofs:**
|    ``attribute_value(+atom,+list(pair),-term)`` - ``one``


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

.. index:: build_encoders/4
.. _dimension_reducer_common/0::build_encoders/4:

``build_encoders/4``
^^^^^^^^^^^^^^^^^^^^

Builds continuous feature encoders by computing per-attribute centering and optional scaling statistics.

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

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


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

.. index:: base_dimension_reducer_diagnostics/6
.. _dimension_reducer_common/0::base_dimension_reducer_diagnostics/6:

``base_dimension_reducer_diagnostics/6``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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

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

| **Template:**
|    ``base_dimension_reducer_diagnostics(Model,AttributeNames,Components,Options,ExtraDiagnostics,Diagnostics)``
| **Mode and number of proofs:**
|    ``base_dimension_reducer_diagnostics(+atom,+list(atom),+list,+list(compound),+list(compound),-list(compound))`` - ``one``


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

.. index:: preprocessing_diagnostics/3
.. _dimension_reducer_common/0::preprocessing_diagnostics/3:

``preprocessing_diagnostics/3``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Builds shared preprocessing diagnostics metadata from an explicit centering flag and the effective training options.

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

| **Template:**
|    ``preprocessing_diagnostics(Center,Options,Preprocessing)``
| **Mode and number of proofs:**
|    ``preprocessing_diagnostics(+boolean,+list(compound),-list(compound))`` - ``one``


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

.. index:: iterative_dimension_reducer_diagnostics/11
.. _dimension_reducer_common/0::iterative_dimension_reducer_diagnostics/11:

``iterative_dimension_reducer_diagnostics/11``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Builds diagnostics metadata for reducers that report sample counts, iterative convergence terms, and optional leading or trailing reducer-specific diagnostics.

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

| **Template:**
|    ``iterative_dimension_reducer_diagnostics(Model,AttributeNames,Components,SampleCount,Options,LeadingDiagnostics,Convergence,Iterations,FinalDelta,TrailingDiagnostics,Diagnostics)``
| **Mode and number of proofs:**
|    ``iterative_dimension_reducer_diagnostics(+atom,+list(atom),+list,+integer,+list(compound),+list(compound),+term,+term,+term,+list(compound),-list(compound))`` - ``one``


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

.. index:: component_iteration_diagnostics/4
.. _dimension_reducer_common/0::component_iteration_diagnostics/4:

``component_iteration_diagnostics/4``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Extracts per-component convergence, iteration, and final-delta lists from component diagnostics records.

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

| **Template:**
|    ``component_iteration_diagnostics(ComponentDiagnostics,Convergences,IterationCounts,FinalDeltas)``
| **Mode and number of proofs:**
|    ``component_iteration_diagnostics(+list(compound),-list(atom),-list(integer),-list(number))`` - ``one``


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

.. index:: zero_vector_like/2
.. _dimension_reducer_common/0::zero_vector_like/2:

``zero_vector_like/2``
^^^^^^^^^^^^^^^^^^^^^^

Constructs a zero vector matching the length of the first vector in a list of vectors, or returns the empty list when the input is empty.

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

| **Template:**
|    ``zero_vector_like(Vectors,ZeroVector)``
| **Mode and number of proofs:**
|    ``zero_vector_like(+list(list(number)),-list(number))`` - ``one``


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

.. index:: basis_vector/3
.. _dimension_reducer_common/0::basis_vector/3:

``basis_vector/3``
^^^^^^^^^^^^^^^^^^

Constructs a canonical basis vector for the requested size and one-based index.

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

| **Template:**
|    ``basis_vector(Size,Index,Vector)``
| **Mode and number of proofs:**
|    ``basis_vector(+integer,+integer,-list(number))`` - ``one``


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

.. index:: initial_vectors/2
.. _dimension_reducer_common/0::initial_vectors/2:

``initial_vectors/2``
^^^^^^^^^^^^^^^^^^^^^

Constructs the default all-ones initial vector followed by canonical basis vectors for the requested size.

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

| **Template:**
|    ``initial_vectors(Size,Vectors)``
| **Mode and number of proofs:**
|    ``initial_vectors(+integer,-list(list(number)))`` - ``one``


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

.. index:: basis_initial_vectors/3
.. _dimension_reducer_common/0::basis_initial_vectors/3:

``basis_initial_vectors/3``
^^^^^^^^^^^^^^^^^^^^^^^^^^^

Constructs canonical basis vectors from the given one-based index up to the requested size.

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

| **Template:**
|    ``basis_initial_vectors(Index,Size,Vectors)``
| **Mode and number of proofs:**
|    ``basis_initial_vectors(+integer,+integer,-list(list(number)))`` - ``one``


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

.. index:: extract_components/5
.. _dimension_reducer_common/0::extract_components/5:

``extract_components/5``
^^^^^^^^^^^^^^^^^^^^^^^^

Extracts leading positive eigen-components from a numeric matrix using the shared symmetric eigensolver until the requested count or the configured tolerance is reached.

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

| **Template:**
|    ``extract_components(Matrix,Requested,Options,Components,Eigenvalues)``
| **Mode and number of proofs:**
|    ``extract_components(+list(list(number)),+integer,+list(compound),-list(list(number)),-list(number))`` - ``one``


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

.. index:: known_attribute_values/3
.. _dimension_reducer_common/0::known_attribute_values/3:

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

Collects the known numeric values for a given attribute across the training examples.

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

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


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

.. index:: examples_to_rows/3
.. _dimension_reducer_common/0::examples_to_rows/3:

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

Encodes a list of training examples into numeric feature rows using the importing reducer example hook and learned encoders.

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

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


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

.. index:: encode_instance/3
.. _dimension_reducer_common/0::encode_instance/3:

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

Encodes an instance using the learned continuous attribute encoders.

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

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


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

.. index:: encoder_attribute_names/2
.. _dimension_reducer_common/0::encoder_attribute_names/2:

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

Collects encoder attribute names preserving encoder order.

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

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


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

.. index:: project_components/4
.. _dimension_reducer_common/0::project_components/4:

``project_components/4``
^^^^^^^^^^^^^^^^^^^^^^^^

Projects encoded features onto the learned components and returns `component_N-Score` pairs.

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

| **Template:**
|    ``project_components(Components,Features,Index,ReducedInstance)``
| **Mode and number of proofs:**
|    ``project_components(+list(list(number)),+list(number),+integer,-list(pair))`` - ``one``


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

.. index:: valid_linear_encoders/1
.. _dimension_reducer_common/0::valid_linear_encoders/1:

``valid_linear_encoders/1``
^^^^^^^^^^^^^^^^^^^^^^^^^^^

True when a list of encoders only contains valid ``continuous/3`` 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:: valid_projection_components/2
.. _dimension_reducer_common/0::valid_projection_components/2:

``valid_projection_components/2``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

True when projection components are numeric vectors compatible with the encoder feature dimension.

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

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


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

.. index:: valid_dimension_reducer_metadata/1
.. _dimension_reducer_common/0::valid_dimension_reducer_metadata/1:

``valid_dimension_reducer_metadata/1``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

True when diagnostics metadata records the reducer model and effective training options.

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

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


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

.. index:: print_dimension_reducer_details/3
.. _dimension_reducer_common/0::print_dimension_reducer_details/3:

``print_dimension_reducer_details/3``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Prints the common diagnostics, encoders, and component-count lines used by reducer-specific pretty printers.

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

| **Template:**
|    ``print_dimension_reducer_details(Diagnostics,Encoders,Components)``
| **Mode and number of proofs:**
|    ``print_dimension_reducer_details(+list(compound),+list(compound),+list)`` - ``one``


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

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

(no local declarations; see entity ancestors if any)

Operators
---------

(none)

