.. index:: single: clusterer_common .. _clusterer_common/0: .. rst-class:: right **category** ``clusterer_common`` ==================== Shared predicates for clusterer learning defaults, export, and common dataset and encoding helpers. | **Availability:** | ``logtalk_load(clustering_protocols(loader))`` | **Author:** Paulo Moura | **Version:** 1:0:0 | **Date:** 2026-04-30 | **Compilation flags:** | ``static`` | **Implements:** | ``public`` :ref:`clusterer_protocol ` | **Extends:** | ``public`` :ref:`options ` | **Uses:** | :ref:`format ` | :ref:`list ` | :ref:`population ` | :ref:`type ` | **Remarks:** | (none) | **Inherited public predicates:** |  :ref:`clusterer_protocol/0::check_clusterer/1`  :ref:`options_protocol/0::check_option/1`  :ref:`options_protocol/0::check_options/1`  :ref:`clusterer_protocol/0::cluster/3`  :ref:`clusterer_protocol/0::clusterer_options/2`  :ref:`options_protocol/0::default_option/1`  :ref:`options_protocol/0::default_options/1`  :ref:`clusterer_protocol/0::diagnostic/2`  :ref:`clusterer_protocol/0::diagnostics/2`  :ref:`clusterer_protocol/0::export_to_clauses/4`  :ref:`clusterer_protocol/0::export_to_file/4`  :ref:`clusterer_protocol/0::learn/2`  :ref:`clusterer_protocol/0::learn/3`  :ref:`options_protocol/0::option/2`  :ref:`options_protocol/0::option/3`  :ref:`clusterer_protocol/0::print_clusterer/1`  :ref:`clusterer_protocol/0::valid_clusterer/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:: dataset_attributes/2 .. _clusterer_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:: valid_attribute_names/1 .. _clusterer_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_continuous_encoders/1 .. _clusterer_common/0::valid_continuous_encoders/1: ``valid_continuous_encoders/1`` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ True when a list of encoders only contains valid continuous encoder terms with distinct attributes. | **Compilation flags:** | ``static`` | **Template:** | ``valid_continuous_encoders(Encoders)`` | **Mode and number of proofs:** | ``valid_continuous_encoders(+list(compound))`` - ``zero_or_one`` ------------ .. index:: valid_discrete_encoders/1 .. _clusterer_common/0::valid_discrete_encoders/1: ``valid_discrete_encoders/1`` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ True when a list of encoders only contains valid discrete encoder terms with distinct attributes. | **Compilation flags:** | ``static`` | **Template:** | ``valid_discrete_encoders(Encoders)`` | **Mode and number of proofs:** | ``valid_discrete_encoders(+list(compound))`` - ``zero_or_one`` ------------ .. index:: valid_mixed_encoders/1 .. _clusterer_common/0::valid_mixed_encoders/1: ``valid_mixed_encoders/1`` ^^^^^^^^^^^^^^^^^^^^^^^^^^ True when a list of encoders only contains valid continuous or discrete encoder terms with distinct attributes. | **Compilation flags:** | ``static`` | **Template:** | ``valid_mixed_encoders(Encoders)`` | **Mode and number of proofs:** | ``valid_mixed_encoders(+list(compound))`` - ``zero_or_one`` ------------ .. index:: valid_mixed_vectors/2 .. _clusterer_common/0::valid_mixed_vectors/2: ``valid_mixed_vectors/2`` ^^^^^^^^^^^^^^^^^^^^^^^^^ True when all vectors conform to the given continuous or discrete encoder specifications. | **Compilation flags:** | ``static`` | **Template:** | ``valid_mixed_vectors(Encoders,Vectors)`` | **Mode and number of proofs:** | ``valid_mixed_vectors(+list(compound),+list)`` - ``zero_or_one`` ------------ .. index:: valid_clusterer_metadata/3 .. _clusterer_common/0::valid_clusterer_metadata/3: ``valid_clusterer_metadata/3`` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ True when diagnostics metadata contains the expected model term and records the given effective options. | **Compilation flags:** | ``static`` | **Template:** | ``valid_clusterer_metadata(Model,Options,Diagnostics)`` | **Mode and number of proofs:** | ``valid_clusterer_metadata(+atom,+list(compound),+list(compound))`` - ``zero_or_one`` ------------ .. index:: valid_diagnostic_count/3 .. _clusterer_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_diagnostic_choice/3 .. _clusterer_common/0::valid_diagnostic_choice/3: ``valid_diagnostic_choice/3`` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ True when diagnostics contains a term with the given functor and a value selected from the allowed choices. | **Compilation flags:** | ``static`` | **Template:** | ``valid_diagnostic_choice(Functor,Diagnostics,Choices)`` | **Mode and number of proofs:** | ``valid_diagnostic_choice(+atom,+list(compound),+list)`` - ``zero_or_one`` ------------ .. index:: check_continuous_attributes/1 .. _clusterer_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 .. _clusterer_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/3 .. _clusterer_common/0::check_examples/3: ``check_examples/3`` ^^^^^^^^^^^^^^^^^^^^ Checks that a continuous training dataset is non-empty and that all example values are numeric. | **Compilation flags:** | ``static`` | **Template:** | ``check_examples(Dataset,AttributeNames,Examples)`` | **Mode and number of proofs:** | ``check_examples(+object_identifier,+list(atom),+list)`` - ``one`` ------------ .. index:: check_example_values/2 .. _clusterer_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 .. _clusterer_common/0::check_example_attributes/2: ``check_example_attributes/2`` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Checks that a single example contains exactly the declared attributes and that all values are numeric. | **Compilation flags:** | ``static`` | **Template:** | ``check_example_attributes(AttributeNames,AttributeValues)`` | **Mode and number of proofs:** | ``check_example_attributes(+list(atom),+list(pair))`` - ``one`` ------------ .. index:: check_attribute_bindings/2 .. _clusterer_common/0::check_attribute_bindings/2: ``check_attribute_bindings/2`` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Checks that an attribute-value list contains each declared attribute exactly once and no undeclared attributes. | **Compilation flags:** | ``static`` | **Template:** | ``check_attribute_bindings(AttributeNames,AttributeValues)`` | **Mode and number of proofs:** | ``check_attribute_bindings(+list(atom),+list(pair))`` - ``one`` ------------ .. index:: attribute_value/3 .. _clusterer_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 .. _clusterer_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:: known_attribute_values/3 .. _clusterer_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 .. _clusterer_common/0::examples_to_rows/3: ``examples_to_rows/3`` ^^^^^^^^^^^^^^^^^^^^^^ Encodes training examples into `Id-Features` rows using the object-local or imported encoder implementation. | **Compilation flags:** | ``static`` | **Template:** | ``examples_to_rows(Examples,Encoders,Rows)`` | **Mode and number of proofs:** | ``examples_to_rows(+list,+list(compound),-list(pair))`` - ``one`` ------------ .. index:: encode_instance/3 .. _clusterer_common/0::encode_instance/3: ``encode_instance/3`` ^^^^^^^^^^^^^^^^^^^^^ Encodes an instance using the learned continuous attribute encoders after checking that it contains exactly the declared attributes. | **Compilation flags:** | ``static`` | **Template:** | ``encode_instance(Encoders,AttributeValues,Features)`` | **Mode and number of proofs:** | ``encode_instance(+list(compound),+list(pair),-list(number))`` - ``one`` ------------ .. index:: check_encoded_attribute_bindings/2 .. _clusterer_common/0::check_encoded_attribute_bindings/2: ``check_encoded_attribute_bindings/2`` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Checks that an attribute-value list contains each attribute described by the encoders exactly once and no undeclared attributes. | **Compilation flags:** | ``static`` | **Template:** | ``check_encoded_attribute_bindings(Encoders,AttributeValues)`` | **Mode and number of proofs:** | ``check_encoded_attribute_bindings(+list(compound),+list(pair))`` - ``one`` ------------ .. index:: normalize_continuous/4 .. _clusterer_common/0::normalize_continuous/4: ``normalize_continuous/4`` ^^^^^^^^^^^^^^^^^^^^^^^^^^ Normalizes a continuous value using the learned centering and scaling parameters. | **Compilation flags:** | ``static`` | **Template:** | ``normalize_continuous(Value,Mean,Scale,Feature)`` | **Mode and number of proofs:** | ``normalize_continuous(+number,+number,+number,-number)`` - ``one`` ------------ .. index:: check_cluster_count/2 .. _clusterer_common/0::check_cluster_count/2: ``check_cluster_count/2`` ^^^^^^^^^^^^^^^^^^^^^^^^^ Checks that the requested cluster count does not exceed the number of examples. | **Compilation flags:** | ``static`` | **Template:** | ``check_cluster_count(K,Count)`` | **Mode and number of proofs:** | ``check_cluster_count(+integer,+integer)`` - ``one`` ------------ .. index:: take_first_k/3 .. _clusterer_common/0::take_first_k/3: ``take_first_k/3`` ^^^^^^^^^^^^^^^^^^ Collects the first `K` vectors from `Id-Vector` rows. | **Compilation flags:** | ``static`` | **Template:** | ``take_first_k(K,Rows,Vectors)`` | **Mode and number of proofs:** | ``take_first_k(+integer,+list,-list)`` - ``one`` ------------ .. index:: remove_candidate/3 .. _clusterer_common/0::remove_candidate/3: ``remove_candidate/3`` ^^^^^^^^^^^^^^^^^^^^^^ Removes the first matching `Id-Vector` candidate from a candidate list. | **Compilation flags:** | ``static`` | **Template:** | ``remove_candidate(Candidate,Candidates,RemainingCandidates)`` | **Mode and number of proofs:** | ``remove_candidate(+pair,+list(pair),-list(pair))`` - ``one`` ------------ .. index:: clusterer_diagnostics_data/2 .. _clusterer_common/0::clusterer_diagnostics_data/2: ``clusterer_diagnostics_data/2`` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Hook predicate that importing clusterer implementations must define in order to expose diagnostics metadata. | **Compilation flags:** | ``static`` | **Template:** | ``clusterer_diagnostics_data(Clusterer,Diagnostics)`` | **Mode and number of proofs:** | ``clusterer_diagnostics_data(+compound,-list(compound))`` - ``one`` ------------ Private predicates ------------------ (no local declarations; see entity ancestors if any) Operators --------- (none)