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` clusterer_protocol
Extends:
`public` options
Uses:
format
list
population
type
Remarks:
(none)
Inherited public predicates:
check_clusterer/1 check_option/1 check_options/1 cluster/3 clusterer_options/2 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 print_clusterer/1 valid_clusterer/1 valid_option/1 valid_options/1

## Public predicates

(no local declarations; see entity ancestors if any)

## Protected predicates

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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