protocol

# `clusterer_protocol`

Protocol for machine learning clusterers.

Availability:
`logtalk_load(clustering_protocols(loader))`
Author: Paulo Moura
Version: 1:0:0
Date: 2026-04-30
Compilation flags:
`static`
Dependencies:
(none)
Remarks:
(none)
Inherited public predicates:
(none)

## Public predicates

### `learn/3`

Learns a clusterer from the given dataset object using the specified options.

Compilation flags:
`static`
Template:
`learn(Dataset,Clusterer,Options)`
Mode and number of proofs:
`learn(+object_identifier,-compound,+list(compound))` - `one`

### `learn/2`

Learns a clusterer from the given dataset object using default options.

Compilation flags:
`static`
Template:
`learn(Dataset,Clusterer)`
Mode and number of proofs:
`learn(+object_identifier,-compound)` - `one`

### `cluster/3`

Assigns a new instance to a cluster using the learned clusterer. The instance is a list of `Attribute-Value` pairs.

Compilation flags:
`static`
Template:
`cluster(Clusterer,Instance,Cluster)`
Mode and number of proofs:
`cluster(+compound,+list,-ground)` - `one`

### `diagnostics/2`

Returns diagnostics and metadata associated with a learned clusterer in a representation-independent way.

Compilation flags:
`static`
Template:
`diagnostics(Clusterer,Diagnostics)`
Mode and number of proofs:
`diagnostics(+compound,-list(compound))` - `one`

### `check_clusterer/1`

Checks that a learned clusterer term is structurally valid for the receiving implementation. Throws an exception when the term is not a valid clusterer representation.

Compilation flags:
`static`
Template:
`check_clusterer(Clusterer)`
Mode and number of proofs:
`check_clusterer(@compound)` - `one_or_error`
Exceptions:
`Clusterer` is a variable:
`instantiation_error`
`Clusterer` is neither a variable nor a valid clusterer:
`domain_error(clusterer,Clusterer)`

### `valid_clusterer/1`

True when a learned clusterer term is structurally valid for the receiving implementation. Succeeds iff check_clusterer/1 succeeds without throwing an exception.

Compilation flags:
`static`
Template:
`valid_clusterer(Clusterer)`
Mode and number of proofs:
`valid_clusterer(@compound)` - `zero_or_one`

### `diagnostic/2`

Tests or enumerates individual diagnostics metadata terms for a learned clusterer.

Compilation flags:
`static`
Template:
`diagnostic(Clusterer,Diagnostic)`
Mode and number of proofs:
`diagnostic(+compound,?compound)` - `zero_or_more`

### `clusterer_options/2`

Returns the effective training options recorded in a learned clusterer diagnostics list.

Compilation flags:
`static`
Template:
`clusterer_options(Clusterer,Options)`
Mode and number of proofs:
`clusterer_options(+compound,-list(compound))` - `one`

### `export_to_clauses/4`

Converts a clusterer into a list of predicate clauses. `Functor` is the functor for the generated predicate clauses.

Compilation flags:
`static`
Template:
`export_to_clauses(Dataset,Clusterer,Functor,Clauses)`
Mode and number of proofs:
`export_to_clauses(+object_identifier,+compound,+callable,-list(clause))` - `one`

### `export_to_file/4`

Exports a clusterer to a file. `Functor` is the functor for the generated `Functor(Clusterer)` predicate clause.

Compilation flags:
`static`
Template:
`export_to_file(Dataset,Clusterer,Functor,File)`
Mode and number of proofs:
`export_to_file(+object_identifier,+compound,+callable,+atom)` - `one`

### `print_clusterer/1`

Prints a clusterer to the current output stream in a human-readable format.

Compilation flags:
`static`
Template:
`print_clusterer(Clusterer)`
Mode and number of proofs:
`print_clusterer(+compound)` - `one`

## Protected predicates

(none)

## Private predicates

(none)

## Operators

(none)

See also

clustering_dataset_protocol