artlib

Adaptive Resonance Theory (ART) is a cognitive and neural network model that explains how the brain learns to recognize patterns while maintaining stability in the face of new, potentially conflicting information. ART networks are known for their ability to perform unsupervised learning and adaptively categorize data without forgetting previously learned patterns, a feature known as “plasticity-stability balance.”.

The ART modules provided here support classification, clustering, and reinforcement learning tasks by dynamically adjusting to incoming data streams. They also offer advanced capabilities, including hierarchical clustering, topological clustering, data fusion, and regression, enabling flexible exploration of complex data structures.

Adaptive Resonance Theory

Submodules

• artlib.biclustering
• artlib.common
• artlib.cvi
• artlib.elementary
• artlib.fusion
• artlib.hierarchical
• artlib.optimized
• artlib.reinforcement
• artlib.supervised
• artlib.topological

Classes

BaseART	Generic implementation of Adaptive Resonance Theory (ART)
BaseARTMAP	Generic implementation of Adaptive Resonance Theory MAP (ARTMAP)
ART1	ART1 for Binary Clustering.
ART2A	ART2-A for Clustering.
BayesianART	Bayesian ART for Clustering.
EllipsoidART	Ellipsoid ART for Clustering.
GaussianART	Gaussian ART for Clustering.
FuzzyART	Fuzzy ART for Clustering.
BinaryFuzzyART	Fuzzy ART optimized for binary input data.
HypersphereART	Hypersphere ART for Clustering.
QuadraticNeuronART	Quadratic Neuron ART for Clustering.
iCVIFuzzyART	ICVI Fuzzy Art For Clustering.
CVIART	CVI Art Classification.
ARTMAP	ARTMAP for Classification and Regression.
SimpleARTMAP	SimpleARTMAP for Classification.
SMART	SMART for Hierachical Clustering.
DeepARTMAP	DeepARTMAP for Hierachical Supervised and Unsupervised Learning.
FusionART	Fusion ART for Data Fusion and Regression.
FALCON	FALCON for Reinforcement Learning.
TD_FALCON	TD-FALCON for Reinforcement Learning.
BARTMAP	BARTMAP for Biclustering.
TopoART	Topo ART for Topological Clustering.
DualVigilanceART	Dual Vigilance ART for Clustering.
BinaryFuzzyARTMAP	Factory for generating optimized BinaryFuzzyARTMAP models using various
FuzzyARTMAP	Factory for generating optimized FuzzyARTMAP models using various backends.
HypersphereARTMAP	Factory for generating optimized HypersphereARTMAP models using various
GaussianARTMAP	Factory for generating optimized GaussianARTMAP models using various backends.

Functions

normalize(→ Tuple[numpy.ndarray, numpy.ndarray, ...)	Normalize data column-wise between 0 and 1.
complement_code(→ numpy.ndarray)	Complement code the data.
de_complement_code(→ numpy.ndarray)	Find the centroid of complement coded data.
de_normalize(→ numpy.ndarray)	Restore column-wise normalized data to original scale.
VAT() → Tuple[numpy.ndarray, numpy.ndarray])	Visual Assessment of Cluster Tendency (VAT) algorithm.

Package Contents

class artlib.BaseART(params: Dict)

Bases: sklearn.base.BaseEstimator, sklearn.base.ClusterMixin

Generic implementation of Adaptive Resonance Theory (ART)

data_format = 'default'

params

sample_counter_ = 0

weight_sample_counter_: List[int] = []

d_min_ = None

d_max_ = None

is_fitted_ = False

labels_

__getattr__(key)

__setattr__(key, value)

get_params(deep: bool = True) → Dict

Parameters:

deep (bool, default=True) – If True, will return the parameters for this class and contained subobjects that are estimators.

Returns:

Parameter names mapped to their values.

Return type:

dict

set_params(**params)

Set the parameters of this estimator.

Specific redefinition of sklearn.BaseEstimator.set_params for ART classes.

Parameters:

**params (dict) – Estimator parameters.

Returns:

self – Estimator instance.

Return type:

object

set_data_bounds(lower_bounds: numpy.ndarray, upper_bounds: numpy.ndarray)

Manually set the data bounds for normalization.

Parameters:

• lower_bounds (np.ndarray) – The lower bounds for each column.

• upper_bounds (np.ndarray) – The upper bounds for each column.

find_data_bounds(*data_batches: list[numpy.ndarray]) → Tuple[numpy.ndarray, numpy.ndarray]

Automatically find the data bounds for normalization from a list of data batches.

Parameters:

*data_batches (list[np.ndarray]) – Batches of data to be presented to the model

Returns:

Lower and upper bounds for data.

Return type:

tuple[np.ndarray, np.ndarray]

prepare_data(X: numpy.ndarray) → numpy.ndarray

Prepare data for clustering.

Parameters:

X (np.ndarray) – The dataset.

Returns:

Normalized data.

Return type:

np.ndarray

restore_data(X: numpy.ndarray) → numpy.ndarray

Restore data to state prior to preparation.

Parameters:

X (np.ndarray) – The dataset.

Returns:

Restored data.

Return type:

np.ndarray

property n_clusters: int

Get the current number of clusters.

Returns:

The number of clusters.

Return type:

int

static validate_params(params: Dict)

Abstractmethod:

Validate clustering parameters.

Parameters:

params (dict) – Dictionary containing parameters for the algorithm.

check_dimensions(X: numpy.ndarray)

Check the data has the correct dimensions.

Parameters:

X (np.ndarray) – The dataset.

validate_data(X: numpy.ndarray)

Validates the data prior to clustering.

Parameters: - X: data set

abstract category_choice(i: numpy.ndarray, w: numpy.ndarray, params: Dict) → Tuple[float, Dict | None]

Get the activation of the cluster.

Parameters:

• i (np.ndarray) – Data sample.

• w (np.ndarray) – Cluster weight or information.

• params (dict) – Dictionary containing parameters for the algorithm.

Returns:

Cluster activation and cache used for later processing.

Return type:

tuple

abstract match_criterion(i: numpy.ndarray, w: numpy.ndarray, params: Dict, cache: Dict | None = None) → Tuple[float, Dict | None]

Get the match criterion of the cluster.

Parameters:

• i (np.ndarray) – Data sample.

• w (np.ndarray) – Cluster weight or information.

• params (dict) – Dictionary containing parameters for the algorithm.

• cache (dict, optional) – Cache containing values from previous calculations.

Returns:

Cluster match criterion and cache used for later processing.

Return type:

tuple

match_criterion_bin(i: numpy.ndarray, w: numpy.ndarray, params: Dict, cache: Dict | None = None, op: Callable = operator.ge) → Tuple[bool, Dict]

Get the binary match criterion of the cluster.

Parameters:

• i (np.ndarray) – Data sample.

• w (np.ndarray) – Cluster weight or information.

• params (dict) – Dictionary containing parameters for the algorithm.

• cache (dict, optional) – Cache containing values from previous calculations.

Returns:

Binary match criterion and cache used for later processing.

Return type:

tuple

abstract update(i: numpy.ndarray, w: numpy.ndarray, params: Dict, cache: Dict | None = None) → numpy.ndarray

Get the updated cluster weight.

Parameters:

• i (np.ndarray) – Data sample.

• w (np.ndarray) – Cluster weight or information.

• params (dict) – Dictionary containing parameters for the algorithm.

• cache (dict, optional) – Cache containing values from previous calculations.

Returns:

Updated cluster weight.

Return type:

np.ndarray

abstract new_weight(i: numpy.ndarray, params: Dict) → numpy.ndarray

Generate a new cluster weight.

Parameters:

• i (np.ndarray) – Data sample.

• params (dict) – Dictionary containing parameters for the algorithm.

Returns:

Updated cluster weight.

Return type:

np.ndarray

add_weight(new_w: numpy.ndarray)

Add a new cluster weight.

Parameters:

new_w (np.ndarray) – New cluster weight to add.

set_weight(idx: int, new_w: numpy.ndarray)

Set the value of a cluster weight.

Parameters:

• idx (int) – Index of cluster to update.

• new_w (np.ndarray) – New cluster weight.

_match_tracking(cache: List[Dict] | Dict, epsilon: float, params: List[Dict] | Dict, method: Literal['MT+', 'MT-', 'MT0', 'MT1', 'MT~']) → bool

Perform match tracking using the specified method.

Parameters:

• cache (dict) – Cached match criterion value.

• epsilon (float) – Small adjustment factor for match tracking.

• params (dict) – Parameters

• method (Literal["MT+", "MT-", "MT0", "MT1", "MT~"]) – Match tracking method to apply.

Returns:

Whether to continue searching for a match.

Return type:

bool

static _match_tracking_operator(method: Literal['MT+', 'MT-', 'MT0', 'MT1', 'MT~']) → Callable

_set_params(new_params)

_deep_copy_params() → Dict

step_fit(x: numpy.ndarray, match_reset_func: Callable | None = None, match_tracking: Literal['MT+', 'MT-', 'MT0', 'MT1', 'MT~'] = 'MT+', epsilon: float = 0.0) → int

Fit the model to a single sample.

Parameters:

• x (np.ndarray) – Data sample.

• match_reset_func (callable, optional) – A callable that influences cluster creation.

• match_tracking ({"MT+", "MT-", "MT0", "MT1", "MT~"}, default="MT+") – Method for resetting match criterion.

• epsilon (float, default=0.0) – Epsilon value used for adjusting match criterion.

Returns:

Cluster label of the input sample.

Return type:

int

step_pred(x) → int

Predict the label for a single sample.

Parameters:

x (np.ndarray) – Data sample.

Returns:

Cluster label of the input sample.

Return type:

int

pre_step_fit(X: numpy.ndarray)

Undefined function called prior to each sample fit. Useful for cluster pruning.

Parameters:

X (np.ndarray) – The dataset.

post_step_fit(X: numpy.ndarray)

Undefined function called after each sample fit. Useful for cluster pruning.

Parameters:

X (np.ndarray) – The dataset.

post_fit(X: numpy.ndarray)

Undefined function called after fit. Useful for cluster pruning.

Parameters:

X (np.ndarray) – The dataset.

fit(X: numpy.ndarray, y: numpy.ndarray | None = None, match_reset_func: Callable | None = None, max_iter=1, match_tracking: Literal['MT+', 'MT-', 'MT0', 'MT1', 'MT~'] = 'MT+', epsilon: float = 0.0, verbose: bool = False, leave_progress_bar: bool = True)

Fit the model to the data.

Parameters:

• X (np.ndarray) – The dataset.

• y (np.ndarray, optional) – Not used. For compatibility.

• match_reset_func (callable, optional) – A callable that influences cluster creation.

• max_iter (int, default=1) – Number of iterations to fit the model on the same dataset.

• match_tracking ({"MT+", "MT-", "MT0", "MT1", "MT~"}, default="MT+") – Method for resetting match criterion.

• epsilon (float, default=0.0) – Epsilon value used for adjusting match criterion.

• verbose (bool, default=False) – If True, displays progress of the fitting process.

• leave_progress_bar (bool, default=True) – If True, leaves thge progress of the fitting process. Only used when verbose=True

partial_fit(X: numpy.ndarray, match_reset_func: Callable | None = None, match_tracking: Literal['MT+', 'MT-', 'MT0', 'MT1', 'MT~'] = 'MT+', epsilon: float = 0.0)

Iteratively fit the model to the data.

Parameters:

• X (np.ndarray) – The dataset.

• match_reset_func (callable, optional) – A callable that influences cluster creation.

• match_tracking ({"MT+", "MT-", "MT0", "MT1", "MT~"}, default="MT+") – Method for resetting match criterion.

• epsilon (float, default=0.0) – Epsilon value used for adjusting match criterion.

fit_gif(X: numpy.ndarray, y: numpy.ndarray | None = None, match_reset_func: Callable | None = None, max_iter=1, match_tracking: Literal['MT+', 'MT-', 'MT0', 'MT1', 'MT~'] = 'MT+', epsilon: float = 0.0, verbose: bool = False, leave_progress_bar: bool = True, ax: matplotlib.axes.Axes | None = None, filename: str | None = None, colors: artlib.common.utils.IndexableOrKeyable | None = None, n_cluster_estimate: int = 20, fps: int = 5, final_hold_secs: float = 0.0, **kwargs)

Fit the model to the data and make a gif of the process.

Parameters:

• X (np.ndarray) – The dataset.

• y (np.ndarray, optional) – Not used. For compatibility.

• match_reset_func (callable, optional) – A callable that influences cluster creation.

• max_iter (int, default=1) – Number of iterations to fit the model on the same dataset.

• match_tracking ({"MT+", "MT-", "MT0", "MT1", "MT~"}, default="MT+") – Method for resetting match criterion.

• epsilon (float, default=0.0) – Epsilon value used for adjusting match criterion.

• verbose (bool, default=False) – If True, displays progress of the fitting process.

• leave_progress_bar (bool, default=True) – If True, leaves thge progress of the fitting process. Only used when verbose=True

• ax (matplotlib.axes.Axes, optional) – Figure axes.

• colors (IndexableOrKeyable, optional) – Colors to use for each cluster.

• n_cluster_estimate (int, default=20) – estimate of number of clusters. Used for coloring plot.

• fps (int, default=5) – gif frames per second

• final_hold_secs (float, default=0.0) – seconds to hold the final frame (n_final_frames=ceil(final_hold_secs * fps))

• **kwargs (dict) – see :func: artlib.common.BaseART.visualize

predict(X: numpy.ndarray, clip: bool = False) → numpy.ndarray

Predict labels for the data.

Parameters:

• X (np.ndarray) – The dataset.

• clip (bool) – clip the input values to be between the previously seen data limits

Returns:

Labels for the data.

Return type:

np.ndarray

shrink_clusters(shrink_ratio: float = 0.1)

Shrink the clusters by a specified ratio.

Parameters:

shrink_ratio (float, optional) – The ratio by which to shrink the clusters. Must be between 0 and 1. Default is 0.1.

Returns:

self – Returns the instance with shrunken clusters.

Return type:

object

abstract plot_cluster_bounds(ax: matplotlib.axes.Axes, colors: artlib.common.utils.IndexableOrKeyable, linewidth: int = 1)

Undefined function for visualizing the bounds of each cluster.

Parameters:

• ax (matplotlib.axes.Axes) – Figure axes.

• colors (IndexableOrKeyable) – Colors to use for each cluster.

• linewidth (int, default=1) – Width of boundary line.

abstract get_cluster_centers() → List[numpy.ndarray]

Undefined function for getting centers of each cluster. Used for regression.

Returns:

Cluster centroids.

Return type:

list of np.ndarray

visualize(X: numpy.ndarray, y: numpy.ndarray, ax: matplotlib.axes.Axes | None = None, marker_size: int = 10, linewidth: int = 1, colors: artlib.common.utils.IndexableOrKeyable | None = None)

Visualize the clustering of the data.

Parameters:

• X (np.ndarray) – The dataset.

• y (np.ndarray) – Sample labels.

• ax (matplotlib.axes.Axes, optional) – Figure axes.

• marker_size (int, default=10) – Size used for data points.

• linewidth (int, default=1) – Width of boundary line.

• colors (IndexableOrKeyable, optional) – Colors to use for each cluster.

class artlib.BaseARTMAP

Bases: sklearn.base.BaseEstimator, sklearn.base.ClassifierMixin, sklearn.base.ClusterMixin

Generic implementation of Adaptive Resonance Theory MAP (ARTMAP)

map: dict[int, int]

set_params(**params)

Set the parameters of this estimator.

Specific redefinition of sklearn.BaseEstimator.set_params for ARTMAP classes.

Parameters:

**params (dict) – Estimator parameters.

Returns:

self – Estimator instance.

Return type:

object

map_a2b(y_a: numpy.ndarray | int) → numpy.ndarray | int

Map an a-side label to a b-side label.

Parameters:

y_a (Union[np.ndarray, int]) – Side A label(s).

Returns:

Side B cluster label(s).

Return type:

Union[np.ndarray, int]

abstract validate_data(X: numpy.ndarray, y: numpy.ndarray)

Validate the data prior to clustering.

Parameters:

• X (np.ndarray) – Dataset A.

• y (np.ndarray) – Dataset B.

abstract fit(X: numpy.ndarray, y: numpy.ndarray, max_iter=1, match_tracking: Literal['MT+', 'MT-', 'MT0', 'MT1', 'MT~'] = 'MT+', epsilon: float = 1e-10)

Fit the model to the data.

Parameters:

• X (np.ndarray) – Dataset A.

• y (np.ndarray) – Dataset B.

• max_iter (int, optional) – Number of iterations to fit the model on the same dataset.

• match_tracking ({"MT+", "MT-", "MT0", "MT1", "MT~"}, optional) – Method for resetting match criterion.

• epsilon (float, optional) – Epsilon value used for adjusting match criterion, by default 1e-10.

abstract partial_fit(X: numpy.ndarray, y: numpy.ndarray, match_tracking: Literal['MT+', 'MT-', 'MT0', 'MT1', 'MT~'] = 'MT+', epsilon: float = 1e-10)

Partial fit the model to the data.

Parameters:

• X (np.ndarray) – Dataset A.

• y (np.ndarray) – Dataset B.

• match_tracking ({"MT+", "MT-", "MT0", "MT1", "MT~"}, optional) – Method for resetting match criterion.

• epsilon (float, optional) – Epsilon value used for adjusting match criterion, by default 1e-10.

abstract predict(X: numpy.ndarray, clip: bool = False) → numpy.ndarray

Predict labels for the data.

Parameters:

• X (np.ndarray) – Dataset A.

• clip (bool) – clip the input values to be between the previously seen data limits

Returns:

B-side labels for the data.

Return type:

np.ndarray

abstract predict_ab(X: numpy.ndarray, clip: bool = False) → tuple[numpy.ndarray, numpy.ndarray]

Predict labels for the data, both A-side and B-side.

Parameters:

• X (np.ndarray) – Dataset A.

• clip (bool) – clip the input values to be between the previously seen data limits

Returns:

A-side labels for the data, B-side labels for the data.

Return type:

tuple[np.ndarray, np.ndarray]

abstract plot_cluster_bounds(ax: matplotlib.axes.Axes, colors: artlib.common.utils.IndexableOrKeyable, linewidth: int = 1)

Visualize the bounds of each cluster.

Parameters:

• ax (matplotlib.axes.Axes) – Figure axes.

• colors (IndexableOrKeyable) – Colors to use for each cluster.

• linewidth (int, optional) – Width of boundary line, by default 1.

abstract visualize(X: numpy.ndarray, y: numpy.ndarray, ax: matplotlib.axes.Axes | None = None, marker_size: int = 10, linewidth: int = 1, colors: artlib.common.utils.IndexableOrKeyable | None = None)

Visualize the clustering of the data.

Parameters:

• X (np.ndarray) – Dataset.

• y (np.ndarray) – Sample labels.

• ax (matplotlib.axes.Axes, optional) – Figure axes, by default None.

• marker_size (int, optional) – Size used for data points, by default 10.

• linewidth (int, optional) – Width of boundary line, by default 1.

• colors (IndexableOrKeyable, optional) – Colors to use for each cluster, by default None.

artlib.normalize(data: numpy.ndarray, d_max: numpy.ndarray | None = None, d_min: numpy.ndarray | None = None) → Tuple[numpy.ndarray, numpy.ndarray, numpy.ndarray]

Normalize data column-wise between 0 and 1.

Parameters:

• data (np.ndarray) – 2D array of dataset (rows = samples, columns = features).

• d_max (np.ndarray, optional) – Maximum values for each column.

• d_min (np.ndarray, optional) – Minimum values for each column.

Returns:

• np.ndarray – Normalized data.

• np.ndarray – Maximum values for each column.

• np.ndarray – Minimum values for each column.

artlib.complement_code(data: numpy.ndarray) → numpy.ndarray

Complement code the data.

Parameters:

data (np.ndarray) – Dataset.

Returns:

complement coded data.

Return type:

np.ndarray

artlib.de_complement_code(data: numpy.ndarray) → numpy.ndarray

Find the centroid of complement coded data.

Parameters:

data (np.ndarray) – Dataset.

Returns:

De-complement coded data.

Return type:

np.ndarray

artlib.de_normalize(data: numpy.ndarray, d_max: numpy.ndarray, d_min: numpy.ndarray) → numpy.ndarray

Restore column-wise normalized data to original scale.

Parameters:

• data (np.ndarray) – Normalized data.

• d_max (np.ndarray) – Maximum values for each column.

• d_min (np.ndarray) – Minimum values for each column.

Returns:

De-normalized data.

Return type:

np.ndarray

artlib.VAT(data: numpy.ndarray, distance_metric: Callable | None = lambda X: ...) → Tuple[numpy.ndarray, numpy.ndarray]

Visual Assessment of Cluster Tendency (VAT) algorithm.

VAT was originally designed as a visualization tool for clustering behavior of data. When the VAT-reordered distance matrix is plotted as an image, clusters will appear in visually distinct groups along the diagonal. However, it has since been discovered that the reordering significantly improves the results of order-dependent clustering methods like ART. It is therefore recommended to pre-process data with VAT prior to presentation when possible.

Parameters:

• data (np.ndarray) – Input dataset as a 2D numpy array where each row is a sample.

• distance_metric (callable, optional) – Callable function to calculate pairwise distances. Defaults to Euclidean distance using pdist. If None, assumes data is a pre-computed distance matrix.

Returns:

• Reordered distance matrix reflecting cluster structure.

• Reordered list of indices indicating the optimal clustering order.

Return type:

Tuple[np.ndarray, np.ndarray]

class artlib.ART1(rho: float, L: float)

Bases: artlib.common.BaseART.BaseART

ART1 for Binary Clustering.

This module implements ART1 as first published in: [1].

ART1 is exclusively for clustering binary data.

prepare_data(X: numpy.ndarray) → numpy.ndarray

Prepare data for clustering.

Parameters:

X (np.ndarray) – Dataset.

Returns:

Normalized and complement coded data.

Return type:

np.ndarray

restore_data(X: numpy.ndarray) → numpy.ndarray

Restore data to its state prior to preparation.

Parameters:

X (np.ndarray) – Dataset.

Returns:

Restored data.

Return type:

np.ndarray

static validate_params(params: dict)

Validate clustering parameters.

Parameters:

params (dict) – Dictionary containing parameters for the algorithm.

validate_data(X: numpy.ndarray)

Validate the data prior to clustering.

Parameters:

X (np.ndarray) – The dataset.

category_choice(i: numpy.ndarray, w: numpy.ndarray, params: dict) → tuple[float, dict | None]

Get the activation of the cluster.

Parameters:

• i (np.ndarray) – Data sample.

• w (np.ndarray) – Cluster weight or information.

• params (dict) – Dictionary containing parameters for the algorithm.

Returns:

• float – Cluster activation.

• dict, optional – Cache used for later processing.

match_criterion(i: numpy.ndarray, w: numpy.ndarray, params: dict, cache: dict | None = None) → Tuple[float, Dict | None]

Get the match criterion of the cluster.

Parameters:

• i (np.ndarray) – Data sample.

• w (np.ndarray) – Cluster weight or information.

• params (dict) – Dictionary containing parameters for the algorithm.

• cache (dict, optional) – Cache containing values from previous calculations.

Returns:

• float – Cluster match criterion.

• dict – Cache used for later processing.

update(i: numpy.ndarray, w: numpy.ndarray, params: dict, cache: dict | None = None) → numpy.ndarray

Get the updated cluster weight.

Parameters:

• i (np.ndarray) – Data sample.

• w (np.ndarray) – Cluster weight or information.

• params (dict) – Dictionary containing parameters for the algorithm.

• cache (dict, optional) – Cache containing values from previous calculations.

Returns:

Updated cluster weight.

Return type:

np.ndarray

new_weight(i: numpy.ndarray, params: dict) → numpy.ndarray

Generate a new cluster weight.

Parameters:

• i (np.ndarray) – Data sample.

• params (dict) – Dictionary containing parameters for the algorithm.

Returns:

Updated cluster weight.

Return type:

np.ndarray

get_cluster_centers() → List[numpy.ndarray]

Get the centers of each cluster, used for regression.

Returns:

Cluster centroids.

Return type:

list of np.ndarray

class artlib.ART2A(rho: float, alpha: float, beta: float)

Bases: artlib.common.BaseART.BaseART

ART2-A for Clustering.

This module implements ART2-A as first published in: [2], [3]

ART2-A is similar to ART1 but designed for analog data. This method is implemented for historical purposes and is not recommended for use.

static validate_params(params: dict)

Validate clustering parameters.

Parameters:

params (dict) – Dictionary containing parameters for the algorithm.

check_dimensions(X: numpy.ndarray)

Check that the data has the correct dimensions.

Parameters:

X (np.ndarray) – The dataset.

category_choice(i: numpy.ndarray, w: numpy.ndarray, params: dict) → tuple[float, dict | None]

Get the activation of the cluster.

Parameters:

• i (np.ndarray) – Data sample.

• w (np.ndarray) – Cluster weight or information.

• params (dict) – Dictionary containing parameters for the algorithm.

Returns:

• float – Cluster activation.

• dict, optional – Cache used for later processing.

match_criterion(i: numpy.ndarray, w: numpy.ndarray, params: dict, cache: dict | None = None) → tuple[float, dict | None]

Get the match criterion of the cluster.

Parameters:

• i (np.ndarray) – Data sample.

• w (np.ndarray) – Cluster weight or information.

• params (dict) – Dictionary containing parameters for the algorithm.

• cache (dict, optional) – Cache containing values from previous calculations.

Returns:

• float – Cluster match criterion.

• dict – Cache used for later processing.

update(i: numpy.ndarray, w: numpy.ndarray, params: dict, cache: dict | None = None) → numpy.ndarray

Get the updated cluster weight.

Parameters:

• i (np.ndarray) – Data sample.

• w (np.ndarray) – Cluster weight or information.

• params (dict) – Dictionary containing parameters for the algorithm.

• cache (dict, optional) – Cache containing values from previous calculations.

Returns:

Updated cluster weight.

Return type:

np.ndarray

new_weight(i: numpy.ndarray, params: dict) → numpy.ndarray

Generate a new cluster weight.

Parameters:

• i (np.ndarray) – Data sample.

• params (dict) – Dictionary containing parameters for the algorithm.

Returns:

Updated cluster weight.

Return type:

np.ndarray

get_cluster_centers() → List[numpy.ndarray]

Get the centers of each cluster, used for regression.

Returns:

Cluster centroids.

Return type:

list of np.ndarray

class artlib.BayesianART(rho: float, cov_init: numpy.ndarray)

Bases: artlib.common.BaseART.BaseART

Bayesian ART for Clustering.

This module implements Bayesian ART as first published in: [4].

Bayesian ART clusters data in Bayesian Distributions (Hyper-ellipsoids) and is similar to GaussianART but differs in that it allows arbitrary rotation of the hyper-ellipsoid.

pi2

static validate_params(params: dict)

Validate clustering parameters.

Parameters:

params (dict) – Dictionary containing parameters for the algorithm.

check_dimensions(X: numpy.ndarray)

Check that the data has the correct dimensions.

Parameters:

X (np.ndarray) – The dataset.

category_choice(i: numpy.ndarray, w: numpy.ndarray, params: dict) → tuple[float, dict | None]

Get the activation of the cluster.

Parameters:

• i (np.ndarray) – Data sample.

• w (np.ndarray) – Cluster weight or information.

• params (dict) – Dictionary containing parameters for the algorithm.

Returns:

• float – Cluster activation.

• dict, optional – Cache used for later processing.

match_criterion(i: numpy.ndarray, w: numpy.ndarray, params: dict, cache: dict | None = None) → Tuple[float, Dict | None]

Get the match criterion of the cluster.

Parameters:

• i (np.ndarray) – Data sample.

• w (np.ndarray) – Cluster weight or information.

• params (dict) – Dictionary containing parameters for the algorithm.

• cache (dict, optional) – Cache containing values from previous calculations.

Returns:

• float – Cluster match criterion.

• dict – Cache used for later processing.

match_criterion_bin(i: numpy.ndarray, w: numpy.ndarray, params: dict, cache: dict | None = None, op: Callable = operator.ge) → tuple[bool, dict]

Get the binary match criterion of the cluster.

Parameters:

• i (np.ndarray) – Data sample.

• w (np.ndarray) – Cluster weight or information.

• params (dict) – Dictionary containing parameters for the algorithm.

• cache (dict, optional) – Cache containing values from previous calculations.

• op (callable, optional) – Operator for comparison, by default operator.ge.

Returns:

• bool – Binary match criterion.

• dict – Cache used for later processing.

_match_tracking(cache: List[Dict] | Dict, epsilon: float, params: List[Dict] | Dict, method: Literal['MT+', 'MT-', 'MT0', 'MT1', 'MT~']) → bool

Adjust match tracking based on the method and epsilon value.

Parameters:

• cache (dict) – Cache containing intermediate results, including the match criterion.

• epsilon (float) – Adjustment factor for the match criterion.

• params (dict) – Dictionary containing algorithm parameters.

• method ({"MT+", "MT-", "MT0", "MT1", "MT~"}) – Match tracking method to use.

Returns:

True if match tracking continues, False otherwise.

Return type:

bool

update(i: numpy.ndarray, w: numpy.ndarray, params: dict, cache: dict | None = None) → numpy.ndarray

Get the updated cluster weight.

Parameters:

• i (np.ndarray) – Data sample.

• w (np.ndarray) – Cluster weight or information.

• params (dict) – Dictionary containing parameters for the algorithm.

• cache (dict, optional) – Cache containing values from previous calculations.

Returns:

Updated cluster weight.

Return type:

np.ndarray

new_weight(i: numpy.ndarray, params: dict) → numpy.ndarray

Generate a new cluster weight.

Parameters:

• i (np.ndarray) – Data sample.

• params (dict) – Dictionary containing parameters for the algorithm.

Returns:

Updated cluster weight.

Return type:

np.ndarray

get_cluster_centers() → List[numpy.ndarray]

Get the centers of each cluster, used for regression.

Returns:

Cluster centroids.

Return type:

list of np.ndarray

plot_cluster_bounds(ax: matplotlib.axes.Axes, colors: Iterable, linewidth: int = 1)

Visualize the bounds of each cluster.

Parameters:

• ax (matplotlib.axes.Axes) – Figure axes.

• colors (IndexableOrKeyable) – Colors to use for each cluster.

• linewidth (int, optional) – Width of boundary line, by default 1.

class artlib.EllipsoidART(rho: float, alpha: float, beta: float, mu: float, r_hat: float)

Bases: artlib.common.BaseART.BaseART

Ellipsoid ART for Clustering.

This module implements Ellipsoid ART as first published in: [5], [6].

Ellipsoid ART clusters data in Hyper-ellipsoids. It is highly sensitive to sample presentation order as the second sample will determine the orientation of the principal axes.

static validate_params(params: dict)

Validate clustering parameters.

Parameters:

params (dict) – Dictionary containing parameters for the algorithm.

static category_distance(i: numpy.ndarray, centroid: numpy.ndarray, major_axis: numpy.ndarray, params: dict) → float

Calculate the distance between a sample and the cluster centroid.

Parameters:

• i (np.ndarray) – Data sample.

• centroid (np.ndarray) – Centroid of the cluster.

• major_axis (np.ndarray) – Major axis of the cluster.

• params (dict) – Dictionary containing parameters for the algorithm.

Returns:

Distance between the sample and the cluster centroid.

Return type:

float

category_choice(i: numpy.ndarray, w: numpy.ndarray, params: dict) → tuple[float, dict | None]

Get the activation of the cluster.

Parameters:

• i (np.ndarray) – Data sample.

• w (np.ndarray) – Cluster weight or information.

• params (dict) – Dictionary containing parameters for the algorithm.

Returns:

• float – Cluster activation.

• dict, optional – Cache used for later processing.

match_criterion(i: numpy.ndarray, w: numpy.ndarray, params: dict, cache: dict | None = None) → Tuple[float, Dict | None]

Get the match criterion of the cluster.

Parameters:

• i (np.ndarray) – Data sample.

• w (np.ndarray) – Cluster weight or information.

• params (dict) – Dictionary containing parameters for the algorithm.

• cache (dict, optional) – Cache containing values from previous calculations.

Returns:

• float – Cluster match criterion.

• dict – Cache used for later processing.

update(i: numpy.ndarray, w: numpy.ndarray, params: dict, cache: dict | None = None) → numpy.ndarray

Get the updated cluster weight.

Parameters:

• i (np.ndarray) – Data sample.

• w (np.ndarray) – Cluster weight or information.

• params (dict) – Dictionary containing parameters for the algorithm.

• cache (dict, optional) – Cache containing values from previous calculations.

Returns:

Updated cluster weight.

Return type:

np.ndarray

new_weight(i: numpy.ndarray, params: dict) → numpy.ndarray

Generate a new cluster weight.

Parameters:

• i (np.ndarray) – Data sample.

• params (dict) – Dictionary containing parameters for the algorithm.

Returns:

New cluster weight.

Return type:

np.ndarray

get_2d_ellipsoids() → List[Tuple[numpy.ndarray, float, float, float]]

Get the 2D ellipsoids for visualization.

Returns:

Each tuple contains the centroid, width, height, and angle of an ellipsoid.

Return type:

list of tuple

get_cluster_centers() → List[numpy.ndarray]

Get the centers of each cluster, used for regression.

Returns:

Cluster centroids.

Return type:

list of np.ndarray

plot_cluster_bounds(ax: matplotlib.axes.Axes, colors: artlib.common.utils.IndexableOrKeyable, linewidth: int = 1)

Visualize the bounds of each cluster.

Parameters:

• ax (matplotlib.axes.Axes) – Figure axes.

• colors (IndexableOrKeyable) – Colors to use for each cluster.

• linewidth (int, optional) – Width of boundary line, by default 1.

class artlib.GaussianART(rho: float, sigma_init: numpy.ndarray, alpha: float = 1e-10)

Bases: artlib.common.BaseART.BaseART

Gaussian ART for Clustering.

This module implements Gaussian ART as first published in: [7].

Guassian ART clusters data in Gaussian Distributions (Hyper-ellipsoids) and is similar to BayesianART but differs in that the hyper-ellipsoid always have their principal axes square to the coordinate frame. It is also faster than BayesianART.

static validate_params(params: dict)

Validate clustering parameters.

Parameters:

params (dict) – Dictionary containing parameters for the algorithm.

category_choice(i: numpy.ndarray, w: numpy.ndarray, params: dict) → tuple[float, dict | None]

Get the activation of the cluster.

Parameters:

• i (np.ndarray) – Data sample.

• w (np.ndarray) – Cluster weight or information.

• params (dict) – Dictionary containing parameters for the algorithm.

Returns:

• float – Cluster activation.

• dict, optional – Cache used for later processing.

match_criterion(i: numpy.ndarray, w: numpy.ndarray, params: dict, cache: dict | None = None) → Tuple[float, Dict | None]

Get the match criterion of the cluster.

Parameters:

• i (np.ndarray) – Data sample.

• w (np.ndarray) – Cluster weight or information.

• params (dict) – Dictionary containing parameters for the algorithm.

• cache (dict, optional) – Cache containing values from previous calculations.

Returns:

• float – Cluster match criterion.

• dict – Cache used for later processing.

update(i: numpy.ndarray, w: numpy.ndarray, params: dict, cache: dict | None = None) → numpy.ndarray

Get the updated cluster weight.

Parameters:

• i (np.ndarray) – Data sample.

• w (np.ndarray) – Cluster weight or information.

• params (dict) – Dictionary containing parameters for the algorithm.

• cache (dict, optional) – Cache containing values from previous calculations.

Returns:

Updated cluster weight.

Return type:

np.ndarray

new_weight(i: numpy.ndarray, params: dict) → numpy.ndarray

Generate a new cluster weight.

Parameters:

• i (np.ndarray) – Data sample.

• params (dict) – Dictionary containing parameters for the algorithm.

Returns:

New cluster weight.

Return type:

np.ndarray

get_cluster_centers() → List[numpy.ndarray]

Get the centers of each cluster, used for regression.

Returns:

Cluster centroids.

Return type:

list of np.ndarray

plot_cluster_bounds(ax: matplotlib.axes.Axes, colors: Iterable, linewidth: int = 1)

Visualize the bounds of each cluster.

Parameters:

• ax (matplotlib.axes.Axes) – Figure axes.

• colors (IndexableOrKeyable) – Colors to use for each cluster.

• linewidth (int, optional) – Width of boundary line, by default 1.

class artlib.FuzzyART(rho: float, alpha: float, beta: float)

Bases: artlib.common.BaseART.BaseART

Fuzzy ART for Clustering.

This module implements Fuzzy ART as first published in: [8].

Fuzzy ART is a hyper-box based clustering method that is exceptionally fast and explainable.

prepare_data(X: numpy.ndarray) → numpy.ndarray

Prepare data for clustering.

Parameters:

X (np.ndarray) – Dataset.

Returns:

Normalized and complement coded data.

Return type:

np.ndarray

restore_data(X: numpy.ndarray) → numpy.ndarray

Restore data to its state prior to preparation.

Parameters:

X (np.ndarray) – Dataset.

Returns:

Restored data.

Return type:

np.ndarray

static validate_params(params: dict)

Validate clustering parameters.

Parameters:

params (dict) – Dictionary containing parameters for the algorithm.

check_dimensions(X: numpy.ndarray)

Check that the data has the correct dimensions.

Parameters:

X (np.ndarray) – Dataset.

validate_data(X: numpy.ndarray)

Validate the data prior to clustering.

Parameters:

X (np.ndarray) – Dataset.

category_choice(i: numpy.ndarray, w: numpy.ndarray, params: dict) → tuple[float, dict | None]

Get the activation of the cluster.

Parameters:

• i (np.ndarray) – Data sample.

• w (np.ndarray) – Cluster weight or information.

• params (dict) – Dictionary containing parameters for the algorithm.

Returns:

• float – Cluster activation.

• dict, optional – Cache used for later processing.

match_criterion(i: numpy.ndarray, w: numpy.ndarray, params: dict, cache: dict | None = None) → Tuple[float, Dict | None]

Get the match criterion of the cluster.

Parameters:

• i (np.ndarray) – Data sample.

• w (np.ndarray) – Cluster weight or information.

• params (dict) – Dictionary containing parameters for the algorithm.

• cache (dict, optional) – Cache containing values from previous calculations.

Returns:

• float – Cluster match criterion.

• dict – Cache used for later processing.

update(i: numpy.ndarray, w: numpy.ndarray, params: dict, cache: dict | None = None) → numpy.ndarray

Get the updated cluster weight.

Parameters:

• i (np.ndarray) – Data sample.

• w (np.ndarray) – Cluster weight or information.

• params (dict) – Dictionary containing parameters for the algorithm.

• cache (dict, optional) – Cache containing values from previous calculations.

Returns:

Updated cluster weight.

Return type:

np.ndarray

new_weight(i: numpy.ndarray, params: dict) → numpy.ndarray

Generate a new cluster weight.

Parameters:

• i (np.ndarray) – Data sample.

• params (dict) – Dictionary containing parameters for the algorithm.

Returns:

New cluster weight.

Return type:

np.ndarray

get_bounding_boxes(n: int | None = None) → List[tuple[list[int], list[int]]]

Get the bounding boxes for each cluster.

Parameters:

n (int, optional) – Dimensions of the bounding box.

Returns:

List of bounding boxes.

Return type:

list

get_cluster_centers() → List[numpy.ndarray]

Get the centers of each cluster, used for regression.

Returns:

Cluster centroids.

Return type:

list of np.ndarray

shrink_clusters(shrink_ratio: float = 0.1)

Shrink the clusters by adjusting the bounding box.

Parameters:

shrink_ratio (float, optional) – The ratio by which to shrink the clusters, by default 0.1.

Returns:

Self after shrinking the clusters.

Return type:

FuzzyART

plot_cluster_bounds(ax: matplotlib.axes.Axes, colors: Iterable, linewidth: int = 1)

Visualize the bounds of each cluster.

Parameters:

• ax (matplotlib.axes.Axes) – Figure axes.

• colors (IndexableOrKeyable) – Colors to use for each cluster.

• linewidth (int, optional) – Width of boundary line, by default 1.

class artlib.BinaryFuzzyART(rho: float)

Bases: artlib.elementary.FuzzyART.FuzzyART

Fuzzy ART optimized for binary input data.

w_count_cache: List[int] = []

prepare_data(X: numpy.ndarray) → numpy.ndarray

Prepare data for clustering.

Parameters:

X (np.ndarray) – Dataset.

Returns:

Normalized and complement coded data.

Return type:

np.ndarray

restore_data(X: numpy.ndarray) → numpy.ndarray

Restore data to its state prior to preparation.

Parameters:

X (np.ndarray) – Dataset.

Returns:

Restored data.

Return type:

np.ndarray

static validate_params(params: dict)

Validate clustering parameters.

Parameters:

params (dict) – Dictionary containing parameters for the algorithm.

validate_data(X: numpy.ndarray)

Validate the data prior to clustering.

Parameters:

X (np.ndarray) – Dataset.

category_choice(i: numpy.ndarray, w: numpy.ndarray, params: dict) → tuple[int, dict | None]

Get the activation of the cluster using optimized binary operations.

match_criterion(i: numpy.ndarray, w: numpy.ndarray, params: dict, cache: dict | None = None) → Tuple[float, Dict | None]

Get the match criterion using optimized binary operations.

match_criterion_bin(i: numpy.ndarray, w: numpy.ndarray, params: Dict, cache: Dict | None = None, op: Callable = operator.ge) → Tuple[bool, Dict]

Get the binary match criterion of the cluster.

Parameters:

• i (np.ndarray) – Data sample.

• w (np.ndarray) – Cluster weight or information.

• params (dict) – Dictionary containing parameters for the algorithm.

• cache (dict, optional) – Cache containing values from previous calculations.

Returns:

Binary match criterion and cache used for later processing.

Return type:

tuple

set_weight(idx: int, new_w: numpy.ndarray, cache: dict | None = None)

Set the value of a cluster weight.

Parameters:

• idx (int) – Index of cluster to update.

• new_w (np.ndarray) – New cluster weight.

• cache (Optional[dict]) – cache of values created during training step

update(i: numpy.ndarray, w: numpy.ndarray, params: dict, cache: dict | None = None) → numpy.ndarray

Get the updated cluster weight using optimized binary operations.

add_weight(new_w: numpy.ndarray)

Add a new cluster weight.

Parameters:

new_w (np.ndarray) – New cluster weight to add.

step_pred(x) → int

Predict the label for a single sample.

Parameters:

x (np.ndarray) – Data sample.

Returns:

Cluster label of the input sample.

Return type:

int

_match_tracking_integer(cache: List[Dict] | Dict, epsilon: int, params: List[Dict] | Dict, method: Literal['MT+', 'MT-', 'MT0', 'MT1', 'MT~']) → bool

Perform match tracking using the specified method.

Parameters:

• cache (dict) – Cached match criterion value.

• epsilon (float) – Small adjustment factor for match tracking.

• params (dict) – Parameters

• method (Literal["MT+", "MT-", "MT0", "MT1", "MT~"]) – Match tracking method to apply.

Returns:

Whether to continue searching for a match.

Return type:

bool

step_fit(x: numpy.ndarray, match_reset_func: Callable | None = None, match_tracking: Literal['MT+', 'MT-', 'MT0', 'MT1', 'MT~'] = 'MT+', epsilon: float = 0.0) → int

Fit the model to a single sample.

Parameters:

• x (np.ndarray) – Data sample.

• match_reset_func (callable, optional) – A callable that influences cluster creation.

• match_tracking ({"MT+", "MT-", "MT0", "MT1", "MT~"}, default="MT+") – Method for resetting match criterion.

• epsilon (float, default=0.0) – Epsilon value used for adjusting match criterion. Rounded up to nearest int

Returns:

Cluster label of the input sample.

Return type:

int

class artlib.HypersphereART(rho: float, alpha: float, beta: float, r_hat: float)

Bases: artlib.common.BaseART.BaseART

Hypersphere ART for Clustering.

This module implements Ellipsoid ART as first published in: [9].

Hyperpshere ART clusters data in Hyper-spheres similar to k-means with a dynamic k.

static validate_params(params: dict)

Validate clustering parameters.

Parameters:

params (dict) – Dictionary containing parameters for the algorithm.

static category_distance(i: numpy.ndarray, centroid: numpy.ndarray, radius: float, params) → float

Compute the category distance between a data sample and a centroid.

Parameters:

• i (np.ndarray) – Data sample.

• centroid (np.ndarray) – Cluster centroid.

• radius (float) – Cluster radius.

• params (dict) – Dictionary containing parameters for the algorithm.

Returns:

Category distance.

Return type:

float

category_choice(i: numpy.ndarray, w: numpy.ndarray, params: dict) → tuple[float, dict | None]

Get the activation of the cluster.

Parameters:

• i (np.ndarray) – Data sample.

• w (np.ndarray) – Cluster weight or information.

• params (dict) – Dictionary containing parameters for the algorithm.

Returns:

• float – Cluster activation.

• dict, optional – Cache used for later processing.

match_criterion(i: numpy.ndarray, w: numpy.ndarray, params: dict, cache: dict | None = None) → tuple[float, dict | None]

Get the match criterion of the cluster.

Parameters:

• i (np.ndarray) – Data sample.

• w (np.ndarray) – Cluster weight or information.

• params (dict) – Dictionary containing parameters for the algorithm.

• cache (dict, optional) – Cache containing values from previous calculations.

Returns:

• float – Cluster match criterion.

• dict – Cache used for later processing.

update(i: numpy.ndarray, w: numpy.ndarray, params: dict, cache: dict | None = None) → numpy.ndarray

Get the updated cluster weight.

Parameters:

• i (np.ndarray) – Data sample.

• w (np.ndarray) – Cluster weight or information.

• params (dict) – Dictionary containing parameters for the algorithm.

• cache (dict, optional) – Cache containing values from previous calculations.

Returns:

Updated cluster weight.

Return type:

np.ndarray

new_weight(i: numpy.ndarray, params: dict) → numpy.ndarray

Generate a new cluster weight.

Parameters:

• i (np.ndarray) – Data sample.

• params (dict) – Dictionary containing parameters for the algorithm.

Returns:

New cluster weight.

Return type:

np.ndarray

get_cluster_centers() → List[numpy.ndarray]

Get the centers of each cluster, used for regression.

Returns:

Cluster centroids.

Return type:

list of np.ndarray

plot_cluster_bounds(ax: matplotlib.axes.Axes, colors: Iterable, linewidth: int = 1)

Visualize the bounds of each cluster.

Parameters:

• ax (matplotlib.axes.Axes) – Figure axes.

• colors (IndexableOrKeyable) – Colors to use for each cluster.

• linewidth (int, optional) – Width of boundary line, by default 1.

class artlib.QuadraticNeuronART(rho: float, s_init: float, lr_b: float, lr_w: float, lr_s: float)

Bases: artlib.common.BaseART.BaseART

Quadratic Neuron ART for Clustering.

This module implements Quadratic Neuron ART as first published in: [10], [11].

Quadratic Neuron ART clusters data in Hyper-ellipsoid by utilizing a quadratic neural network for activation and resonance.

static validate_params(params: dict)

Validate clustering parameters.

Parameters:

params (dict) – Dictionary containing parameters for the algorithm.

category_choice(i: numpy.ndarray, w: numpy.ndarray, params: dict) → tuple[float, dict | None]

Get the activation of the cluster.

Parameters:

• i (np.ndarray) – Data sample.

• w (np.ndarray) – Cluster weight or information.

• params (dict) – Dictionary containing parameters for the algorithm.

Returns:

• float – Cluster activation.

• dict, optional – Cache used for later processing.

match_criterion(i: numpy.ndarray, w: numpy.ndarray, params: dict, cache: dict | None = None) → Tuple[float, Dict | None]

Get the match criterion of the cluster.

Parameters:

• i (np.ndarray) – Data sample.

• w (np.ndarray) – Cluster weight or information.

• params (dict) – Dictionary containing parameters for the algorithm.

• cache (dict, optional) – Cache containing values from previous calculations.

Returns:

• float – Cluster match criterion.

• dict – Cache used for later processing.

update(i: numpy.ndarray, w: numpy.ndarray, params: dict, cache: dict | None = None) → numpy.ndarray

Get the updated cluster weight.

Parameters:

• i (np.ndarray) – Data sample.

• w (np.ndarray) – Cluster weight or information.

• params (dict) – Dictionary containing parameters for the algorithm.

• cache (dict, optional) – Cache containing values from previous calculations.

Returns:

Updated cluster weight, cache used for later processing.

Return type:

np.ndarray

new_weight(i: numpy.ndarray, params: dict) → numpy.ndarray

Generate a new cluster weight.

Parameters:

• i (np.ndarray) – Data sample.

• params (dict) – Dictionary containing parameters for the algorithm.

Returns:

New cluster weight.

Return type:

np.ndarray

get_cluster_centers() → List[numpy.ndarray]

Get the centers of each cluster, used for regression.

Returns:

Cluster centroids.

Return type:

list of np.ndarray

plot_cluster_bounds(ax: matplotlib.axes.Axes, colors: Iterable, linewidth: int = 1)

Visualize the bounds of each cluster.

Parameters:

• ax (matplotlib.axes.Axes) – Figure axes.

• colors (IndexableOrKeyable) – Colors to use for each cluster.

• linewidth (int, optional) – Width of boundary line, by default 1.

class artlib.iCVIFuzzyART(rho: float, alpha: float, beta: float, validity: int, offline: bool = True)

Bases: artlib.elementary.FuzzyART.FuzzyART

ICVI Fuzzy Art For Clustering.

CALINSKIHARABASZ = 1

offline = True

iCVI_match(x, w, c_, params, cache)

Apply iCVI (incremental Cluster Validity Index) matching criteria.

Parameters:

• x (np.ndarray) – Data sample.

• w (np.ndarray) – Cluster weight.

• c (int) – Cluster index.

• params (dict) – Dictionary containing algorithm parameters.

• cache (dict) – Cache used for storing intermediate results.

Returns:

True if the new criterion value is better than the previous one, False otherwise.

Return type:

bool

fit(X: numpy.ndarray, y: numpy.ndarray | None = None, match_reset_func: Callable | None = None, max_iter=1, match_tracking: Literal['MT+', 'MT-', 'MT0', 'MT1', 'MT~'] = 'MT+', epsilon: float = 0.0)

Fit the model to the data.

Parameters:

• X (np.ndarray) – The dataset.

• y (np.ndarray, optional) – Not used. For compatibility.

• match_reset_func (callable, optional) – A callable accepting the data sample, a cluster weight, the params dict, and the cache dict. Returns True if the cluster is valid for the sample, False otherwise.

• max_iter (int, optional) – Number of iterations to fit the model on the same dataset, by default 1.

• match_tracking ({"MT+", "MT-", "MT0", "MT1", "MT~"}, optional) – Method for resetting match criterion.

• epsilon (float, optional) – Epsilon value used for adjusting match criterion, by default 0.0.

class artlib.CVIART(base_module: artlib.common.BaseART.BaseART, validity: int)

Bases: artlib.common.BaseART.BaseART

CVI Art Classification.

Expanded version of Art that uses Cluster Validity Indicies to help with cluster selection. PBM is not implemented, can be seen here. git.mst.edu/acil-group/CVI-Fuzzy-ART/-/blob/master/PBM_index.m?ref_type=heads

Note, the default step_fit function in base ART evaluates the matching function even if the other criteria has failed. This means it could run slower then it would otherwise.

CALINSKIHARABASZ = 1

DAVIESBOULDIN = 2

SILHOUETTE = 3

base_module

validate_params(params: dict)

Validate clustering parameters.

Parameters:

params (dict) – Dictionary containing parameters for the algorithm.

prepare_data(X: numpy.ndarray) → numpy.ndarray

Prepare data for clustering.

Parameters:

X (np.ndarray) – Dataset to be normalized.

Returns:

Normalized data.

Return type:

np.ndarray

restore_data(X: numpy.ndarray) → numpy.ndarray

Restore data to state prior to preparation.

Parameters:

X (np.ndarray) – Dataset to be restored.

Returns:

Restored data.

Return type:

np.ndarray

property W: List

Get the base module weights.

Returns:

base module weights

Return type:

list of np.ndarray

property labels_: numpy.ndarray

Get the base module labels.

Returns:

base module labels

Return type:

np.ndarray

CVI_match(x, w, c_, params, extra, cache)

Evaluate the cluster validity index (CVI) for a match.

Parameters:

• x (np.ndarray) – Data sample.

• w (np.ndarray) – Cluster weight information.

• c (int) – Cluster index.

• params (dict) – Parameters for the algorithm.

• extra (dict) – Extra information including index and validity type.

• cache (dict) – Cache containing values from previous calculations.

Returns:

True if the new validity score improves the clustering, False otherwise.

Return type:

bool

_match_tracking(cache: dict, epsilon: float, params: dict, method: Literal['MT+', 'MT-', 'MT0', 'MT1', 'MT~']) → bool

Adjust the vigilance parameter (rho) based on the match tracking method.

Parameters:

• cache (dict) – Cache containing match criterion.

• epsilon (float) – Epsilon value for adjusting the vigilance parameter.

• params (dict) – Parameters for the algorithm.

• method ({"MT+", "MT-", "MT0", "MT1", "MT~"}) – Method for resetting match criterion.

Returns:

True if further matching is required, False otherwise.

Return type:

bool

_set_params(new_params)

_deep_copy_params() → dict

fit(X: numpy.ndarray, y: numpy.ndarray | None = None, match_reset_func: Callable | None = None, max_iter=1, match_tracking: Literal['MT+', 'MT-', 'MT0', 'MT1', 'MT~'] = 'MT+', epsilon: float = 0.0)

Fit the model to the data.

Parameters:

• X (np.ndarray) – The dataset.

• y (np.ndarray, optional) – Not used. For compatibility.

• match_reset_func (callable, optional) – A callable accepting the data sample, a cluster weight, the params dict, and the cache dict. Returns True if the cluster is valid for the sample, False otherwise.

• max_iter (int, optional) – Number of iterations to fit the model on the same dataset, by default 1.

• match_tracking ({"MT+", "MT-", "MT0", "MT1", "MT~"}, optional) – Method for resetting match criterion.

• epsilon (float, optional) – Epsilon value used for adjusting match criterion, by default 0.0.

pre_step_fit(X: numpy.ndarray)

Preprocessing step before fitting each sample.

Parameters:

X (np.ndarray) – The dataset.

post_step_fit(X: numpy.ndarray)

Postprocessing step after fitting each sample.

Parameters:

X (np.ndarray) – The dataset.

abstract step_fit(x: numpy.ndarray, match_reset_func: Callable | None = None, match_tracking: Literal['MT+', 'MT-', 'MT0', 'MT1', 'MT~'] = 'MT+', epsilon: float = 0.0) → int

Fit the model to a single sample.

Parameters:

• x (np.ndarray) – Data sample.

• match_reset_func (callable, optional) – A callable accepting the data sample, a cluster weight, the params dict, and the cache dict. Returns True if the cluster is valid for the sample, False otherwise.

• match_tracking ({"MT+", "MT-", "MT0", "MT1", "MT~"}, optional) – Method for resetting match criterion.

• epsilon (float, optional) – Epsilon value used for adjusting match criterion, by default 0.0.

Returns:

Cluster label of the input sample.

Return type:

int

step_pred(x: numpy.ndarray) → int

Predict the label for a single sample.

Parameters:

x (np.ndarray) – Data sample.

Returns:

Cluster label of the input sample.

Return type:

int

get_cluster_centers() → List[numpy.ndarray]

Get the centers of the clusters.

Returns:

Cluster centroids.

Return type:

list of np.ndarray

plot_cluster_bounds(ax: matplotlib.axes.Axes, colors: Iterable, linewidth: int = 1)

Plot the boundaries of each cluster.

Parameters:

• ax (matplotlib.axes.Axes) – Figure axes.

• colors (IndexableOrKeyable) – Colors to use for each cluster.

• linewidth (int, optional) – Width of boundary line, by default 1.

class artlib.ARTMAP(module_a: artlib.common.BaseART.BaseART, module_b: artlib.common.BaseART.BaseART)

Bases: artlib.supervised.SimpleARTMAP.SimpleARTMAP

ARTMAP for Classification and Regression.

This module implements ARTMAP as first published in: [12].

ARTMAP accepts two BaseART modules A and B which cluster the dependent channel (samples) and the independent channel (labels) respectively while linking them with a many-to-one mapping. If your labels are integers, use SimpleARTMAP for a faster and more direct implementation. ARTMAP also provides the ability to fit a regression model to data and specific functions have been implemented to allow this. However, FusionART provides substantially better fit for regression problems which are not monotonic.

module_b

get_params(deep: bool = True) → dict

Get the parameters of the ARTMAP model.

Parameters:

deep (bool, optional) – If True, will return the parameters for this class and contained subobjects that are estimators.

Returns:

Parameter names mapped to their values.

Return type:

dict

property labels_a: numpy.ndarray

Get the labels generated by the A-side ART module.

Returns:

Labels for the A-side data (independent channel).

Return type:

np.ndarray

property labels_b: numpy.ndarray

Get the labels generated by the B-side ART module.

Returns:

Labels for the B-side data (dependent channel).

Return type:

np.ndarray

property labels_ab: Dict[str, numpy.ndarray]

Get the labels generated by both the A-side and B-side ART modules.

Returns:

Dictionary containing both A-side and B-side labels.

Return type:

dict

validate_data(X: numpy.ndarray, y: numpy.ndarray)

Validate the input data prior to clustering.

Parameters:

• X (np.ndarray) – Data set A (independent channel).

• y (np.ndarray) – Data set B (dependent channel).

prepare_data(X: numpy.ndarray, y: numpy.ndarray | None = None) → numpy.ndarray | Tuple[numpy.ndarray, numpy.ndarray]

Prepare data for clustering by normalizing and transforming.

Parameters:

• X (np.ndarray) – Data set A (independent channel).

• y (np.ndarray) – Data set B (dependent channel).

Returns:

Normalized data for both channels.

Return type:

tuple of np.ndarray

restore_data(X: numpy.ndarray, y: numpy.ndarray | None = None) → numpy.ndarray | Tuple[numpy.ndarray, numpy.ndarray]

Restore data to its original state before preparation.

Parameters:

• X (np.ndarray) – Data set A (independent channel).

• y (np.ndarray) – Data set B (dependent channel).

Returns:

Restored data for both channels.

Return type:

tuple of np.ndarray

fit(X: numpy.ndarray, y: numpy.ndarray, max_iter=1, match_tracking: Literal['MT+', 'MT-', 'MT0', 'MT1', 'MT~'] = 'MT+', epsilon: float = 1e-10, verbose: bool = False, leave_progress_bar: bool = True)

Fit the ARTMAP model to the data.

Parameters:

• X (np.ndarray) – Data set A (independent channel).

• y (np.ndarray) – Data set B (dependent channel).

• max_iter (int, optional) – Number of iterations to fit the model on the same data set.

• match_tracking ({"MT+", "MT-", "MT0", "MT1", "MT~"}, optional) – Method for resetting the vigilance parameter when match criterion fails.

• epsilon (float, optional) – Small increment to modify the vigilance parameter.

• verbose (bool, default=False) – If True, displays a progress bar during training.

• leave_progress_bar (bool, default=True) – If True, leaves thge progress of the fitting process. Only used when verbose=True

Returns:

self – Fitted ARTMAP model.

Return type:

ARTMAP

partial_fit(X: numpy.ndarray, y: numpy.ndarray, match_tracking: Literal['MT+', 'MT-', 'MT0', 'MT1', 'MT~'] = 'MT+', epsilon: float = 1e-10)

Partially fit the ARTMAP model to the data.

Parameters:

• X (np.ndarray) – Data set A (independent channel).

• y (np.ndarray) – Data set B (dependent channel).

• match_tracking ({"MT+", "MT-", "MT0", "MT1", "MT~"}, optional) – Method for resetting the vigilance parameter when match criterion fails.

• epsilon (float, optional) – Small increment to modify the vigilance parameter.

Returns:

self – Partially fitted ARTMAP model.

Return type:

ARTMAP

predict(X: numpy.ndarray, clip: bool = False) → numpy.ndarray

Predict the labels for the given data.

Parameters:

• X (np.ndarray) – Data set A (independent channel).

• clip (bool) – clip the input values to be between the previously seen data limits

Returns:

Predicted labels for data set B (dependent channel).

Return type:

np.ndarray

predict_ab(X: numpy.ndarray, clip: bool = False) → tuple[numpy.ndarray, numpy.ndarray]

Predict both A-side and B-side labels for the given data.

Parameters:

• X (np.ndarray) – Data set A (independent channel).

• clip (bool) – clip the input values to be between the previously seen data limits

Returns:

A labels and B labels for the data.

Return type:

tuple of np.ndarray

predict_regression(X: numpy.ndarray, clip: bool = False) → numpy.ndarray

Predict values for the given data using cluster centers. Note: ARTMAP is not recommended for regression. Use FusionART for regression tasks.

Parameters:

• X (np.ndarray) – Data set A (independent channel).

• clip (bool) – clip the input values to be between the previously seen data limits

Returns:

Predicted values using cluster centers.

Return type:

np.ndarray

class artlib.SimpleARTMAP(module_a: artlib.common.BaseART.BaseART)

Bases: artlib.common.BaseARTMAP.BaseARTMAP

SimpleARTMAP for Classification.

This module implements SimpleARTMAP as first published in: [13].

SimpleARTMAP is a special case of ARTMAP specifically for classification. It allows the clustering of data samples while enforcing a many-to-one mapping from sample clusters to labels. It accepts an instantiated BaseART module and dynamically adapts the vigilance function to prevent resonance when the many-to-one mapping is violated. This enables SimpleARTMAP to identify discrete clusters belonging to each category label.

module_a

match_reset_func(i: numpy.ndarray, w: numpy.ndarray, cluster_a, params: dict, extra: dict, cache: dict | None = None) → bool

Permits external factors to influence cluster creation.

Parameters:

• i (np.ndarray) – Data sample.

• w (np.ndarray) – Cluster weight / info.

• cluster_a (int) – A-side cluster label.

• params (dict) – Parameters for the algorithm.

• extra (dict) – Additional parameters, including “cluster_b”.

• cache (dict, optional) – Values cached from previous calculations.

Returns:

True if the match is permitted, False otherwise.

Return type:

bool

get_params(deep: bool = True) → dict

Get parameters of the model.

Parameters:

deep (bool, default=True) – If True, will return the parameters for this class and contained subobjects that are estimators.

Returns:

Parameter names mapped to their values.

Return type:

dict

validate_data(X: numpy.ndarray, y: numpy.ndarray) → tuple[numpy.ndarray, numpy.ndarray]

Validate data prior to clustering.

Parameters:

• X (np.ndarray) – Data set A.

• y (np.ndarray) – Data set B.

Returns:

The validated datasets X and y.

Return type:

tuple[np.ndarray, np.ndarray]

prepare_data(X: numpy.ndarray, y: numpy.ndarray | None = None) → numpy.ndarray | Tuple[numpy.ndarray, numpy.ndarray]

Prepare data for clustering.

Parameters:

• X (np.ndarray) – Data set.

• y (Optional[np.ndarray]) – Data set B. Not used in SimpleARTMAP

Returns:

Prepared data.

Return type:

np.ndarray

restore_data(X: numpy.ndarray, y: numpy.ndarray | None = None) → numpy.ndarray | Tuple[numpy.ndarray, numpy.ndarray]

Restore data to state prior to preparation.

Parameters:

X (np.ndarray) – Data set.

Returns:

Restored data.

Return type:

np.ndarray

step_fit(x: numpy.ndarray, c_b: int, match_tracking: Literal['MT+', 'MT-', 'MT0', 'MT1', 'MT~'] = 'MT+', epsilon: float = 1e-10) → int

Fit the model to a single sample.

Parameters:

• x (np.ndarray) – Data sample for side A.

• c_b (int) – Side B label.

• match_tracking (Literal, default="MT+") – Method to reset the match.

• epsilon (float, default=1e-10) – Small value to adjust the vigilance.

Returns:

Side A cluster label.

Return type:

int

fit(X: numpy.ndarray, y: numpy.ndarray, max_iter=1, match_tracking: Literal['MT+', 'MT-', 'MT0', 'MT1', 'MT~'] = 'MT+', epsilon: float = 1e-10, verbose: bool = False, leave_progress_bar: bool = True)

Fit the model to the data.

Parameters:

• X (np.ndarray) – Data set A.

• y (np.ndarray) – Data set B.

• max_iter (int, default=1) – Number of iterations to fit the model on the same data set.

• match_tracking (Literal, default="MT+") – Method to reset the match.

• epsilon (float, default=1e-10) – Small value to adjust the vigilance.

• verbose (bool, default=False) – If True, displays a progress bar during training.

• leave_progress_bar (bool, default=True) – If True, leaves thge progress of the fitting process. Only used when verbose=True

Returns:

self – The fitted model.

Return type:

SimpleARTMAP

fit_predict(X: numpy.ndarray, y: numpy.ndarray, max_iter=1, match_tracking: Literal['MT+', 'MT-', 'MT0', 'MT1', 'MT~'] = 'MT+', epsilon: float = 1e-10, verbose: bool = False, leave_progress_bar: bool = True)

Fit the model to the data and return the labels. Need to define this or ClusterMixin could cause issues.

Parameters:

• X (np.ndarray) – Data set A.

• y (np.ndarray) – Data set B.

• max_iter (int, default=1) – Number of iterations to fit the model on the same data set.

• match_tracking (Literal, default="MT+") – Method to reset the match.

• epsilon (float, default=1e-10) – Small value to adjust the vigilance.

• verbose (bool, default=False) – If True, displays a progress bar during training.

• leave_progress_bar (bool, default=True) – If True, leaves thge progress of the fitting process. Only used when verbose=True

Returns:

The labels (same as y).

Return type:

np.ndarray

fit_gif(X: numpy.ndarray, y: numpy.ndarray, match_tracking: Literal['MT+', 'MT-', 'MT0', 'MT1', 'MT~'] = 'MT+', epsilon: float = 1e-10, verbose: bool = False, leave_progress_bar: bool = True, ax: matplotlib.axes.Axes | None = None, filename: str | None = None, fps: int = 5, final_hold_secs: float = 0.0, colors: artlib.common.utils.IndexableOrKeyable | None = None, n_class_estimate: int | None = None, max_iter: int = 1, **kwargs)

Fit the model while recording the learning process as an animated GIF.

The routine iterates over the training data, calling step_fit() for each sample, and captures intermediate plots by repeatedly invoking visualize(). All frames are written to a GIF file (via matplotlib.animation.PillowWriter), allowing an intuitive, frame‑by‑frame view of how clusters form and adjust over time.

Parameters:

• X (np.ndarray) – Independent‑channel samples (side A), shape (n_samples, n_features).

• y (np.ndarray) – Target labels (side B), shape (n_samples,).

• match_tracking ({"MT+", "MT-", "MT0", "MT1", "MT~"}, default="MT+") – Strategy used by the ART module to reset its match criterion.

• epsilon (float, default=1e‑10) – Small positive constant added to the vigilance when match_tracking triggers a reset.

• verbose (bool, default=False) – If True, displays a tqdm progress bar for each epoch.

• leave_progress_bar (bool, default=True) – If True, leaves the progress bar visible after completion (only relevant when verbose is True).

• ax (matplotlib.axes.Axes, optional) – Existing axes on which to draw frames. If None, a new figure and axes are created.

• filename (str, optional) – Output path for the GIF. Defaults to "fit_gif_supervised_<ClassName>.gif" if None.

• fps (int, default=5) – Frames per second in the resulting GIF.

• final_hold_secs (float, default=0.0) – Extra seconds to hold the final frame (duplicates the last plot ceil(final_hold_secs * fps) times).

• colors (array‑like, optional) – Sequence of colors to use for each class when plotting. If None, a rainbow colormap is generated.

• n_class_estimate (int, optional) – Expected number of distinct classes. Only used when colors is None to size the autogenerated colormap.

• max_iter (int, default=1) – Number of complete passes over (X, y).

• **kwargs – Additional keyword arguments forwarded to visualize() (e.g., marker_size, linewidth).

Returns:

self – The fitted estimator (identical object, returned for chaining).

Return type:

SimpleARTMAP

Notes

• Generates a GIF file as a side‑effect. The estimator itself is updated exactly as in fit(); only plotting calls and file I/O are added.

• For reproducible colors across different runs, supply an explicit colors array rather than relying on the rainbow colormap.

partial_fit(X: numpy.ndarray, y: numpy.ndarray, match_tracking: Literal['MT+', 'MT-', 'MT0', 'MT1', 'MT~'] = 'MT+', epsilon: float = 1e-10)

Partial fit the model to the data.

Parameters:

• X (np.ndarray) – Data set A.

• y (np.ndarray) – Data set B.

• match_tracking (Literal, default="MT+") – Method to reset the match.

• epsilon (float, default=1e-10) – Small value to adjust the vigilance.

Returns:

self – The partially fitted model.

Return type:

SimpleARTMAP

property labels_a: numpy.ndarray

Get labels from side A (module A).

Returns:

Labels from module A.

Return type:

np.ndarray

property labels_b: numpy.ndarray

Get labels from side B.

Returns:

Labels from side B.

Return type:

np.ndarray

property labels_ab: Dict[str, numpy.ndarray]

Get labels from both A-side and B-side.

Returns:

A dictionary with keys “A” and “B” containing labels from sides A and B, respectively.

Return type:

dict

property n_clusters: int

Get the number of clusters in side A.

Returns:

Number of clusters.

Return type:

int

property n_clusters_a: int

Get the number of clusters in side A.

Returns:

Number of clusters in side A.

Return type:

int

property n_clusters_b: int

Get the number of clusters in side B.

Returns:

Number of clusters in side B.

Return type:

int

step_pred(x: numpy.ndarray) → tuple[int, int]

Predict the label for a single sample.

Parameters:

x (np.ndarray) – Data sample for side A.

Returns:

Side A cluster label, side B cluster label.

Return type:

tuple[int, int]

predict(X: numpy.ndarray, clip: bool = False) → numpy.ndarray

Predict labels for the data.

Parameters:

• X (np.ndarray) – Data set A.

• clip (bool) – clip the input values to be between the previously seen data limits

Returns:

B labels for the data.

Return type:

np.ndarray

predict_ab(X: numpy.ndarray, clip: bool = False) → tuple[numpy.ndarray, numpy.ndarray]

Predict labels for the data, both A-side and B-side.

Parameters:

• X (np.ndarray) – Data set A.

• clip (bool) – clip the input values to be between the previously seen data limits

Returns:

A labels for the data, B labels for the data.

Return type:

tuple[np.ndarray, np.ndarray]

plot_cluster_bounds(ax: matplotlib.axes.Axes, colors: artlib.common.utils.IndexableOrKeyable, linewidth: int = 1)

Visualize the cluster boundaries.

Parameters:

• ax (Axes) – Figure axes.

• colors (IndexableOrKeyable) – Colors to use for each cluster.

• linewidth (int, default=1) – Width of boundary lines.

visualize(X: numpy.ndarray, y: numpy.ndarray, ax: matplotlib.axes.Axes | None = None, marker_size: int = 10, linewidth: int = 1, colors: artlib.common.utils.IndexableOrKeyable | None = None)

Visualize the clustering of the data.

Parameters:

• X (np.ndarray) – Data set.

• y (np.ndarray) – Sample labels.

• ax (Optional[Axes], default=None) – Figure axes.

• marker_size (int, default=10) – Size used for data points.

• linewidth (int, default=1) – Width of boundary lines.

• colors (Optional[Iterable], default=None) – Colors to use for each cluster.

class artlib.SMART(base_ART_class: Type, rho_values: list[float] | numpy.ndarray, base_params: dict, **kwargs)

Bases: artlib.hierarchical.DeepARTMAP.DeepARTMAP

SMART for Hierachical Clustering.

This module implements SMART as first published in: [14]

SMART accepts an uninstantiated BaseART class and hierarchically clusters data in a divisive fashion by using a set of vigilance values that monotonically increase in their restrictiveness. SMART is a special case of DeepARTMAP, which forms the backbone of this class, where all channels receive the same data.

rho_values

prepare_data(X: numpy.ndarray | list[numpy.ndarray], y: numpy.ndarray | None = None) → numpy.ndarray | Tuple[list[numpy.ndarray], numpy.ndarray | None]

Prepare data for clustering.

Parameters:

X (np.ndarray) – The dataset to prepare.

Returns:

Prepared data.

Return type:

np.ndarray

restore_data(X: numpy.ndarray | list[numpy.ndarray], y: numpy.ndarray | None = None) → numpy.ndarray | Tuple[list[numpy.ndarray], numpy.ndarray | None]

Restore data to its original form before preparation.

Parameters:

X (np.ndarray) – The dataset to restore.

Returns:

Restored data.

Return type:

np.ndarray

fit(X: numpy.ndarray, y: numpy.ndarray | None = None, max_iter=1, match_tracking: Literal['MT+', 'MT-', 'MT0', 'MT1', 'MT~'] = 'MT+', epsilon: float = 0.0)

Fit the SMART model to the data.

Parameters:

• X (np.ndarray) – The dataset to fit the model on.

• y (np.ndarray, optional) – Not used, present for compatibility.

• max_iter (int, optional) – The number of iterations to run the model on the data.

• match_tracking ({"MT+", "MT-", "MT0", "MT1", "MT~"}, optional) – The match reset method to use when adjusting vigilance.

• epsilon (float, optional) – A small value to adjust vigilance during match tracking.

Returns:

Fitted SMART model.

Return type:

SMART

partial_fit(X: numpy.ndarray, y: numpy.ndarray | None = None, match_tracking: Literal['MT+', 'MT-', 'MT0', 'MT1', 'MT~'] = 'MT+', epsilon: float = 0.0)

Partial fit the SMART model to the data.

Parameters:

• X (np.ndarray) – The dataset to partially fit the model on.

• y (np.ndarray, optional) – Not used, present for compatibility.

• match_tracking ({"MT+", "MT-", "MT0", "MT1", "MT~"}, optional) – The match reset method to use when adjusting vigilance.

• epsilon (float, optional) – A small value to adjust vigilance during match tracking.

Returns:

Partially fitted SMART model.

Return type:

SMART

plot_cluster_bounds(ax: matplotlib.axes.Axes, colors: artlib.common.utils.IndexableOrKeyable, linewidth: int = 1)

Visualize the cluster boundaries.

Parameters:

• ax (Axes) – The matplotlib axes on which to plot the cluster boundaries.

• colors (IndexableOrKeyable) – The colors to use for each cluster.

• linewidth (int, optional) – The width of the boundary lines.

Return type:

None

visualize(X: numpy.ndarray, y: numpy.ndarray, ax: matplotlib.axes.Axes | None = None, marker_size: int = 10, linewidth: int = 1, colors: artlib.common.utils.IndexableOrKeyable | None = None)

Visualize the clustering of the data with cluster boundaries.

Parameters:

• X (np.ndarray) – The dataset to visualize.

• y (np.ndarray) – The cluster labels for the data points.

• ax (Axes, optional) – The matplotlib axes on which to plot the visualization.

• marker_size (int, optional) – The size of the data points in the plot.

• linewidth (int, optional) – The width of the cluster boundary lines.

• colors (IndexableOrKeyable, optional) – The colors to use for each cluster.

Return type:

None

class artlib.DeepARTMAP(modules: list[artlib.common.BaseART.BaseART])

Bases: sklearn.base.BaseEstimator, sklearn.base.ClassifierMixin, sklearn.base.ClusterMixin

DeepARTMAP for Hierachical Supervised and Unsupervised Learning.

This module implements DeepARTMAP, a generalization of the ARTMAP class [12] that allows an arbitrary number of data channels to be divisively clustered. DeepARTMAP support both supervised and unsupervised modes. If only two ART modules are provided, DeepARTMAP reverts to standard ARTMAP where the first module is the A-module and the second module is the B-module. DeepARTMAP does not currently have a direct citation and is an original creation of this library.

modules

layers: list[artlib.common.BaseARTMAP.BaseARTMAP] = []

is_supervised: bool | None = None

get_params(deep: bool = True) → dict

Get parameters for this estimator.

Parameters:

deep (bool, optional, default=True) – If True, will return the parameters for this class and contained subobjects that are estimators.

Returns:

Parameter names mapped to their values.

Return type:

dict

set_params(**params)

Set the parameters of this estimator.

Parameters:

**params (dict) – Estimator parameters.

Returns:

self – The estimator instance.

Return type:

DeepARTMAP

property labels_: numpy.ndarray

Get the labels from the first layer.

Returns:

The labels from the first ART layer.

Return type:

np.ndarray

property labels_deep_: numpy.ndarray

Get the deep labels from all layers.

Returns:

Deep labels from all ART layers concatenated together.

Return type:

np.ndarray

property n_modules: int

Get the number of ART modules.

Returns:

The number of ART modules.

Return type:

int

property n_layers: int

Get the number of layers.

Returns:

The number of layers in DeepARTMAP.

Return type:

int

map_deep(level: int, y_a: numpy.ndarray | int) → numpy.ndarray | int

Map a label from one arbitrary level to the highest (B) level.

Parameters:

• level (int) – The level from which the label is taken.

• y_a (np.ndarray or int) – The cluster label(s) at the input level.

Returns:

The cluster label(s) at the highest level (B).

Return type:

np.ndarray or int

validate_data(X: list[numpy.ndarray], y: numpy.ndarray | None = None)

Validate the data before clustering.

Parameters:

• X (list of np.ndarray) – The input data sets for each module.

• y (np.ndarray, optional) – The corresponding labels, by default None.

Raises:

AssertionError – If the input data is inconsistent or does not match the expected format.

prepare_data(X: numpy.ndarray | list[numpy.ndarray], y: numpy.ndarray | None = None) → numpy.ndarray | Tuple[list[numpy.ndarray], numpy.ndarray | None]

Prepare the data for clustering.

Parameters:

• X (list of np.ndarray) – The input data set for each module.

• y (np.ndarray, optional) – The corresponding labels, by default None.

Returns:

The prepared data set and labels (if any).

Return type:

tuple of (list of np.ndarray, np.ndarray)

restore_data(X: numpy.ndarray | list[numpy.ndarray], y: numpy.ndarray | None = None) → numpy.ndarray | Tuple[list[numpy.ndarray], numpy.ndarray | None]

Restore the data to its original state before preparation.

Parameters:

• X (list of np.ndarray) – The input data set for each module.

• y (np.ndarray, optional) – The corresponding labels, by default None.

Returns:

The restored data set and labels (if any).

Return type:

tuple of (list of np.ndarray, np.ndarray)

fit(X: list[numpy.ndarray], y: numpy.ndarray | None = None, max_iter=1, match_tracking: Literal['MT+', 'MT-', 'MT0', 'MT1', 'MT~'] = 'MT+', epsilon: float = 0.0)

Fit the DeepARTMAP model to the data.

Parameters:

• X (list of np.ndarray) – The input data sets for each module.

• y (np.ndarray, optional) – The corresponding labels for supervised learning, by default None.

• max_iter (int, optional) – The number of iterations to fit the model, by default 1.

• match_tracking ({"MT+", "MT-", "MT0", "MT1", "MT~"}, optional) – The method to reset vigilance if a mismatch occurs, by default “MT+”.

• epsilon (float, optional) – A small adjustment factor for match tracking, by default 0.0.

Returns:

The fitted DeepARTMAP model.

Return type:

DeepARTMAP

partial_fit(X: list[numpy.ndarray], y: numpy.ndarray | None = None, match_tracking: Literal['MT+', 'MT-', 'MT0', 'MT1', 'MT~'] = 'MT+', epsilon: float = 0.0)

Partially fit the DeepARTMAP model to the data.

Parameters:

• X (list of np.ndarray) – The input data sets for each module.

• y (np.ndarray, optional) – The corresponding labels for supervised learning, by default None.

• match_tracking ({"MT+", "MT-", "MT0", "MT1", "MT~"}, optional) – The method to reset vigilance if a mismatch occurs, by default “MT+”.

• epsilon (float, optional) – A small adjustment factor for match tracking, by default 0.0.

Returns:

The partially fitted DeepARTMAP model.

Return type:

DeepARTMAP

predict(X: numpy.ndarray | list[numpy.ndarray], clip: bool = False) → list[numpy.ndarray]

Predict the labels for the input data.

Parameters:

• X (np.ndarray or list of np.ndarray) – The input data set for prediction.

• clip (bool) – clip the input values to be between the previously seen data limits

Returns:

The predicted labels for each layer.

Return type:

list of np.ndarray

class artlib.FusionART(modules: List[artlib.common.BaseART.BaseART], gamma_values: List[float] | numpy.ndarray, channel_dims: List[int] | numpy.ndarray)

Bases: artlib.common.BaseART.BaseART

Fusion ART for Data Fusion and Regression.

This module implements Fusion ART as first described in: [15].

Fusion ART accepts an arbitrary number of ART modules, each assigned a different data channel. The activation and match functions for all ART modules are then fused such that all modules must be simultaneously active and resonant in order for a match to occur. This provides fine-grain control when clustering multi-channel or multi-modal data and allows for different geometries of clusters to be used for each channel. Fusion ART also allows for fitting regression models and specific functions have been implemented to allow this.

modules

n

channel_dims

_channel_indices = []

dim_

get_params(deep: bool = True) → Dict

Get the parameters of the FusionART model.

Parameters:

deep (bool, optional) – If True, will return parameters for this class and the contained sub-objects that are estimators (default is True).

Returns:

Parameter names mapped to their values.

Return type:

dict

property n_clusters: int

Return the number of clusters in the first ART module.

Returns:

The number of clusters.

Return type:

int

property W

Get the weights of all modules as a single array.

Returns:

Concatenated weights of all channels from the ART modules.

Return type:

list

static validate_params(params: Dict)

Validate clustering parameters.

Parameters:

params (dict) – The parameters for the FusionART model.

validate_data(X: numpy.ndarray)

Validate the input data for clustering.

Parameters:

X (np.ndarray) – The input dataset.

check_dimensions(X: numpy.ndarray)

Ensure that the input data has the correct dimensions.

Parameters:

X (np.ndarray) – The input dataset.

prepare_data(channel_data: List[numpy.ndarray], skip_channels: List[int] = []) → numpy.ndarray

Prepare the input data by processing each channel’s data through its respective ART module.

Parameters:

• channel_data (list of np.ndarray) – List of arrays, one for each channel.

• skip_channels (list of int, optional) – Channels to be skipped (default is []).

Returns:

Processed and concatenated data.

Return type:

np.ndarray

restore_data(X: numpy.ndarray, skip_channels: List[int] = []) → List[numpy.ndarray]

Restore data to its original state before preparation.

Parameters:

• X (np.ndarray) – The prepared data.

• skip_channels (list of int, optional) – Channels to be skipped (default is []).

Returns:

Restored data for each channel.

Return type:

np.ndarray

category_choice(i: numpy.ndarray, w: list, params: Dict, skip_channels: List[int] = []) → Tuple[float, Dict | None]

Get the activation of the cluster.

Parameters:

• i (np.ndarray) – The data sample.

• w (np.ndarray) – The cluster weight information.

• params (dict) – Parameters for the ART algorithm.

• skip_channels (list of int, optional) – Channels to be skipped (default is []).

Returns:

Cluster activation and cache for further processing.

Return type:

tuple

match_criterion(i: numpy.ndarray, w: list, params: Dict, cache: Dict | None = None, skip_channels: List[int] = []) → Tuple[float, Dict | None]

Get the match criterion for the cluster.

Parameters:

• i (np.ndarray) – The data sample.

• w (np.ndarray) – The cluster weight information.

• params (dict) – Parameters for the ART algorithm.

• cache (dict, optional) – Cache for previous calculations (default is None).

• skip_channels (list of int, optional) – Channels to be skipped (default is []).

Returns:

max match_criterion across channels and the updated cache.

Return type:

tuple

match_criterion_bin(i: numpy.ndarray, w: list, params: Dict, cache: Dict | None = None, op: Callable = operator.ge, skip_channels: List[int] = []) → Tuple[bool, Dict]

Get the binary match criterion for the cluster.

Parameters:

• i (np.ndarray) – The data sample.

• w (np.ndarray) – The cluster weight information.

• params (dict) – Parameters for the ART algorithm.

• cache (dict, optional) – Cache for previous calculations (default is None).

• op (Callable, optional) – Operator for comparison (default is operator.ge).

• skip_channels (list of int, optional) – Channels to be skipped (default is []).

Returns:

Binary match criterion and cache for further processing.

Return type:

tuple

_match_tracking(cache: List[Dict] | Dict, epsilon: float, params: List[Dict] | Dict, method: Literal['MT+', 'MT-', 'MT0', 'MT1', 'MT~']) → bool

Perform match tracking for all channels using the specified method.

Parameters:

• cache (list of dict) – Cached match criterion values for each channel.

• epsilon (float) – Small adjustment factor for match tracking.

• params (list of dict) – Parameters for each channel module.

• method (Literal["MT+", "MT-", "MT0", "MT1", "MT~"]) – Match tracking method to apply.

Returns:

Whether to continue searching for a match across all channels.

Return type:

bool

_set_params(new_params: Dict)

Set the parameters for each module in FusionART.

Parameters:

new_params (list of dict) – A list of parameters for each module.

_deep_copy_params() → Dict

Create a deep copy of the parameters for each module.

Returns:

A dictionary with module indices as keys and their deep-copied parameters as values.

Return type:

dict

step_fit(x: numpy.ndarray, match_reset_func: Callable | None = None, match_tracking: Literal['MT+', 'MT-', 'MT0', 'MT1', 'MT~'] = 'MT+', epsilon: float = 0.0) → int

Fit the model to a single sample.

Parameters:

• x (np.ndarray) – Data sample.

• match_reset_func (callable, optional) – A callable that influences cluster creation.

• match_tracking ({"MT+", "MT-", "MT0", "MT1", "MT~"}, default="MT+") – Method for resetting match criterion.

• epsilon (float, default=0.0) – Epsilon value used for adjusting match criterion.

Returns:

Cluster label of the input sample.

Return type:

int

partial_fit(X: numpy.ndarray, match_reset_func: Callable | None = None, match_tracking: Literal['MT+', 'MT-', 'MT0', 'MT1', 'MT~'] = 'MT+', epsilon: float = 0.0)

Iteratively fit the model to the data.

Parameters:

• X (np.ndarray) – Input dataset.

• match_reset_func (callable, optional) – Function to reset the match criteria based on external factors.

• match_tracking (Literal["MT+", "MT-", "MT0", "MT1", "MT~"], optional) – Method for resetting match criteria (default is “MT+”).

• epsilon (float, optional) – Value to adjust the vigilance parameter (default is 0.0).

step_pred(x, skip_channels: List[int] = []) → int

Predict the label for a single sample.

Parameters:

• x (np.ndarray) – Input sample.

• skip_channels (list of int, optional) – Channels to skip (default is []).

Returns:

Predicted cluster label for the input sample.

Return type:

int

predict(X: numpy.ndarray, clip: bool = False, skip_channels: List[int] = []) → numpy.ndarray

Predict labels for the input data.

Parameters:

• X (np.ndarray) – Input dataset.

• clip (bool) – clip the input values to be between the previously seen data limits

• skip_channels (list of int, optional) – Channels to skip (default is []).

Returns:

Predicted labels for the input data.

Return type:

np.ndarray

update(i: numpy.ndarray, w: list, params: Dict, cache: Dict | None = None) → list

Update the cluster weight.

Parameters:

• i (np.ndarray) – Input data sample.

• w (np.ndarray) – Cluster weight information.

• params (dict) – Parameters for the ART algorithm.

• cache (dict, optional) – Cache for previous calculations (default is None).

Returns:

Updated cluster weight.

Return type:

list

new_weight(i: numpy.ndarray, params: Dict) → list

Generate a new cluster weight.

Parameters:

• i (np.ndarray) – Input data sample.

• params (dict) – Parameters for the ART algorithm.

Returns:

New cluster weight.

Return type:

list

add_weight(new_w: list)

Add a new cluster weight.

Parameters: - new_w: new cluster weight to add

set_weight(idx: int, new_w: list)

Set the value of a cluster weight.

Parameters: - idx: index of cluster to update - new_w: new cluster weight

get_cluster_centers() → List[numpy.ndarray]

Get the center points for each cluster.

Returns:

Center points of the clusters.

Return type:

list of np.ndarray

get_channel_centers(channel: int) → List[numpy.ndarray]

Get the center points of clusters for a specific channel.

Parameters:

channel (int) – The channel index.

Returns:

Cluster centers for the specified channel.

Return type:

list of np.ndarray

predict_regression(X: numpy.ndarray, clip: bool = False, target_channels: List[int] = [-1]) → numpy.ndarray | List[numpy.ndarray]

Predict regression values for the input data using the target channels.

Parameters:

• X (np.ndarray) – Input dataset.

• clip (bool) – clip the input values to be between the previously seen data limits

• target_channels (list of int, optional) – List of target channels to use for regression. If negative values are used, they are considered as channels counting backward from the last channel. By default, it uses the last channel (-1).

Returns:

Predicted regression values. If only one target channel is used, returns a single np.ndarray. If multiple target channels are used, returns a list of np.ndarray, one for each channel.

Return type:

Union[np.ndarray, list of np.ndarray]

join_channel_data(channel_data: List[numpy.ndarray], skip_channels: List[int] = []) → numpy.ndarray

Concatenate data from different channels into a single array.

Parameters:

• channel_data (list of np.ndarray) – Data from each channel.

• skip_channels (list of int, optional) – Channels to skip (default is []).

Returns:

Concatenated data.

Return type:

np.ndarray

split_channel_data(joined_data: numpy.ndarray, skip_channels: List[int] = []) → List[numpy.ndarray]

Split the concatenated data into its original channels.

Parameters:

• joined_data (np.ndarray) – Concatenated data from multiple channels.

• skip_channels (list of int, optional) – Channels to skip (default is []).

Returns:

Split data, one array for each channel.

Return type:

list of np.ndarray

class artlib.FALCON(state_art: artlib.common.BaseART.BaseART, action_art: artlib.common.BaseART.BaseART, reward_art: artlib.common.BaseART.BaseART, gamma_values: List[float] | numpy.ndarray = np.array([0.33, 0.33, 0.34]), channel_dims: List[int] | numpy.ndarray = list[int])

FALCON for Reinforcement Learning.

This module implements the reactive FALCON as first described in: [16].

FALCON is based on a FusionART backbone but only accepts 3 channels: State, Action, and Reward. Specific functions are implemented for getting optimal reward and action predictions.

fusion_art

prepare_data(states: numpy.ndarray, actions: numpy.ndarray, rewards: numpy.ndarray) → Tuple[numpy.ndarray, numpy.ndarray, numpy.ndarray]

Prepare data for clustering.

Parameters:

• states (np.ndarray) – The state data.

• actions (np.ndarray) – The action data.

• rewards (np.ndarray) – The reward data.

Returns:

Normalized state, action, and reward data.

Return type:

tuple of np.ndarray

restore_data(states: numpy.ndarray, actions: numpy.ndarray, rewards: numpy.ndarray) → Tuple[numpy.ndarray, numpy.ndarray, numpy.ndarray]

Restore data to its original form before preparation.

Parameters:

• states (np.ndarray) – The state data.

• actions (np.ndarray) – The action data.

• rewards (np.ndarray) – The reward data.

Returns:

Restored state, action, and reward data.

Return type:

tuple of np.ndarray

fit(states: numpy.ndarray, actions: numpy.ndarray, rewards: numpy.ndarray)

Fit the FALCON model to the data.

Parameters:

• states (np.ndarray) – The state data.

• actions (np.ndarray) – The action data.

• rewards (np.ndarray) – The reward data.

Returns:

The fitted FALCON model.

Return type:

FALCON

partial_fit(states: numpy.ndarray, actions: numpy.ndarray, rewards: numpy.ndarray)

Partially fit the FALCON model to the data.

Parameters:

• states (np.ndarray) – The state data.

• actions (np.ndarray) – The action data.

• rewards (np.ndarray) – The reward data.

Returns:

The partially fitted FALCON model.

Return type:

FALCON

get_actions_and_rewards(state: numpy.ndarray, action_space: numpy.ndarray | None = None) → Tuple[numpy.ndarray, numpy.ndarray]

Get possible actions and their associated rewards for a given state.

Parameters:

• state (np.ndarray) – The current state.

• action_space (np.ndarray, optional) – The available action space, by default None.

Returns:

The possible actions and their corresponding rewards.

Return type:

tuple of np.ndarray

get_action(state: numpy.ndarray, action_space: numpy.ndarray | None = None, optimality: Literal['min', 'max'] = 'max') → numpy.ndarray

Get the best action for a given state based on optimality.

Parameters:

• state (np.ndarray) – The current state.

• action_space (np.ndarray, optional) – The available action space, by default None.

• optimality ({"min", "max"}, optional) – Whether to choose the action with the minimum or maximum reward, by default “max”.

Returns:

The optimal action.

Return type:

np.ndarray

get_probabilistic_action(state: numpy.ndarray, action_space: numpy.ndarray | None = None, offset: float = 0.1, optimality: Literal['min', 'max'] = 'max') → numpy.ndarray

Get a probabilistic action for a given state based on reward distribution.

Parameters:

• state (np.ndarray) – The current state.

• action_space (np.ndarray, optional) – The available action space, by default None.

• offset (float, optional) – The reward offset to adjust probability distribution, by default 0.1.

• optimality ({"min", "max"}, optional) – Whether to prefer minimum or maximum rewards, by default “max”.

Returns:

The chosen action based on probability.

Return type:

np.ndarray

get_rewards(states: numpy.ndarray, actions: numpy.ndarray) → numpy.ndarray

Get the rewards for given states and actions.

Parameters:

• states (np.ndarray) – The state data.

• actions (np.ndarray) – The action data.

Returns:

The rewards corresponding to the given state-action pairs.

Return type:

np.ndarray

class artlib.TD_FALCON(state_art: artlib.common.BaseART.BaseART, action_art: artlib.common.BaseART.BaseART, reward_art: artlib.common.BaseART.BaseART, gamma_values: List[float] | numpy.ndarray = np.array([0.33, 0.33, 0.34]), channel_dims: List[int] | numpy.ndarray = list[int], td_alpha: float = 1.0, td_lambda: float = 1.0)

Bases: FALCON

TD-FALCON for Reinforcement Learning.

This module implements TD-FALCON as first described in: [17].

TD-FALCON is based on a FALCON backbone but includes specific function for temporal-difference learning. Currently, only SARSA is implemented and only FuzzyART base modules are supported.

td_alpha = 1.0

td_lambda = 1.0

abstract fit(states: numpy.ndarray, actions: numpy.ndarray, rewards: numpy.ndarray)

Fit the TD-FALCON model to the data.

Raises:

NotImplementedError – TD-FALCON can only be trained with partial fit.

calculate_SARSA(states: numpy.ndarray, actions: numpy.ndarray, rewards: numpy.ndarray, single_sample_reward: float | None = None)

Calculate the SARSA values for reinforcement learning.

Parameters:

• states (np.ndarray) – The state data.

• actions (np.ndarray) – The action data.

• rewards (np.ndarray) – The reward data.

• single_sample_reward (float, optional) – The reward for a single sample, if applicable, by default None.

Returns:

The state, action, and SARSA-adjusted reward data to be used for fitting.

Return type:

tuple of np.ndarray

partial_fit(states: numpy.ndarray, actions: numpy.ndarray, rewards: numpy.ndarray, single_sample_reward: float | None = None)

Partially fit the TD-FALCON model using SARSA.

Parameters:

• states (np.ndarray) – The state data.

• actions (np.ndarray) – The action data.

• rewards (np.ndarray) – The reward data.

• single_sample_reward (float, optional) – The reward for a single sample, if applicable, by default None.

Returns:

The partially fitted TD-FALCON model.

Return type:

TD_FALCON

class artlib.BARTMAP(module_a: artlib.common.BaseART.BaseART, module_b: artlib.common.BaseART.BaseART, eta: float)

Bases: sklearn.base.BaseEstimator, sklearn.base.BiclusterMixin

BARTMAP for Biclustering.

This class implements BARTMAP as first published in: [].

BARTMAP accepts two instantiated BaseART modules module_a and module_b which cluster the rows (samples) and columns (features) respectively. The features are clustered independently, but the samples are clustered by considering samples already within a row cluster as well as the candidate sample and enforcing a minimum correlation within the subset of features belonging to at least one of the feature clusters.

rows_: numpy.ndarray

columns_: numpy.ndarray

params

module_a

module_b

__getattr__(key)

__setattr__(key, value)

get_params(deep: bool = True) → dict

Get parameters for this estimator.

Parameters:

deep (bool, default=True) – If True, return the parameters for this estimator and contained subobjects that are estimators.

Returns:

Dictionary of parameter names mapped to their values.

Return type:

dict

set_params(**params)

Set the parameters of this estimator.

Specific redefinition of sklearn.BaseEstimator.set_params for ART classes.

Parameters:

**params (dict) – Estimator parameters as keyword arguments.

Returns:

self – The estimator instance.

Return type:

object

static validate_params(params: dict)

Validate clustering parameters.

Parameters:

params (dict) – Dictionary containing parameters for the algorithm.

property column_labels_: numpy.ndarray

Cluster labels for the columns.

Returns:

column_labels_ – Array of cluster labels assigned to each column.

Return type:

ndarray of shape (n_columns,)

property row_labels_: numpy.ndarray

Cluster labels for the rows.

Returns:

row_labels_ – Array of cluster labels assigned to each row.

Return type:

ndarray of shape (n_rows,)

property n_row_clusters: int

Number of row clusters.

Returns:

n_row_clusters – The number of clusters for the rows.

Return type:

int

property n_column_clusters: int

Number of column clusters.

Returns:

n_column_clusters – The number of clusters for the columns.

Return type:

int

_get_x_cb(x: numpy.ndarray, c_b: int)

Get the components of a vector belonging to a b-side cluster.

Parameters:

• x (np.ndarray) – A sample vector.

• c_b (int) – The b-side cluster label.

Returns:

The sample vector x filtered to include only features belonging to the b-side cluster c_b.

Return type:

np.ndarray

static _pearsonr(a: numpy.ndarray, b: numpy.ndarray) → float

Get the Pearson correlation between two vectors.

Parameters:

• a (np.ndarray) – A vector.

• b (np.ndarray) – Another vector.

Returns:

The Pearson correlation between the two vectors a and b.

Return type:

float

_average_pearson_corr(X: numpy.ndarray, k: int, c_b: int) → float

Get the average Pearson correlation for a sample across all features in cluster b.

Parameters:

• X (np.ndarray) – The dataset A.

• k (int) – The sample index.

• c_b (int) – The b-side cluster to check.

Returns:

The average Pearson correlation for the sample at index k across all features in cluster c_b.

Return type:

float

validate_data(X_a: numpy.ndarray, X_b: numpy.ndarray)

Validate the data prior to clustering.

Parameters:

• X_a (np.ndarray) – Dataset A, containing the samples.

• X_b (np.ndarray) – Dataset B, containing the features.

match_criterion_bin(X: numpy.ndarray, k: int, c_b: int, params: dict) → bool

Get the binary match criterion of the cluster.

Parameters:

• X (np.ndarray) – The dataset.

• k (int) – The sample index.

• c_b (int) – The b-side cluster to check.

• params (dict) – Dictionary containing parameters for the algorithm.

Returns:

Binary value indicating whether the cluster match criterion is met.

Return type:

bool

match_reset_func(i: numpy.ndarray, w: numpy.ndarray, cluster_a, params: dict, extra: dict, cache: dict | None = None) → bool

Permit external factors to influence cluster creation.

Parameters:

• i (np.ndarray) – Data sample.

• w (np.ndarray) – Cluster weight or information.

• cluster_a (int) – A-side cluster label.

• params (dict) – Dictionary containing parameters for the algorithm.

• extra (dict) – Additional parameters for the algorithm.

• cache (dict, optional) – Dictionary containing values cached from previous calculations.

Returns:

True if the match is permitted, otherwise False.

Return type:

bool

step_fit(X: numpy.ndarray, k: int) → int

Fit the model to a single sample.

Parameters:

• X (np.ndarray) – The dataset.

• k (int) – The sample index.

Returns:

The cluster label of the input sample.

Return type:

int

fit(X: numpy.ndarray, max_iter=1)

Fit the model to the data.

Parameters:

• X (np.ndarray) – The dataset to fit the model on.

• max_iter (int) – The number of iterations to fit the model on the same dataset.

visualize(cmap: matplotlib.colors.Colormap | None = None)

Visualize the clustering of the data.

Parameters:

cmap (matplotlib.colors.Colormap or str) – The colormap to use for visualization.

class artlib.TopoART(base_module: artlib.common.BaseART.BaseART, beta_lower: float, tau: int, phi: int)

Bases: artlib.common.BaseART.BaseART

Topo ART for Topological Clustering.

This module implements Topo ART as first published in: [18].

Topo ART clusters accepts an instantiated BaseART module and generates a topological clustering by recording the first and second resonant cluster relationships in an adjacency matrix. Further, it updates the second resonant cluster with a lower learning rate than the first, providing for a distributed learning model.

base_module

adjacency

_permanent_mask

static validate_params(params: dict)

Validate clustering parameters.

Parameters:

params (dict) – A dictionary containing parameters for the algorithm.

Raises:

AssertionError – If the required parameters are not provided or are invalid.

property W: List[numpy.ndarray]

Get the weight matrix of the base module.

Returns:

The weight matrix of the base ART module.

Return type:

list[np.ndarray]

validate_data(X: numpy.ndarray)

Validate the data prior to clustering.

Parameters:

X (np.ndarray) – The input dataset.

prepare_data(X: numpy.ndarray) → numpy.ndarray

Prepare data for clustering.

Parameters:

X (np.ndarray) – The input dataset.

Returns:

Prepared (normalized) data.

Return type:

np.ndarray

restore_data(X: numpy.ndarray) → numpy.ndarray

Restore data to the state prior to preparation.

Parameters:

X (np.ndarray) – The input dataset.

Returns:

Restored data.

Return type:

np.ndarray

category_choice(i: numpy.ndarray, w: numpy.ndarray, params: dict) → tuple[float, dict | None]

Get the activation of the cluster.

Parameters:

• i (np.ndarray) – Data sample.

• w (np.ndarray) – Cluster weight or information.

• params (dict) – Parameters for the algorithm.

Returns:

Cluster activation and cache used for later processing.

Return type:

tuple[float, Optional[dict]]

match_criterion(i: numpy.ndarray, w: numpy.ndarray, params: dict, cache: dict | None = None) → Tuple[float, Dict | None]

Get the match criterion of the cluster.

Parameters:

• i (np.ndarray) – Data sample.

• w (np.ndarray) – Cluster weight or information.

• params (dict) – Parameters for the algorithm.

• cache (dict, optional) – Values cached from previous calculations.

Returns:

Cluster match criterion and cache used for later processing.

Return type:

tuple[float, dict]

match_criterion_bin(i: numpy.ndarray, w: numpy.ndarray, params: dict, cache: dict | None = None, op: Callable = operator.ge) → tuple[bool, dict]

Get the binary match criterion of the cluster.

Parameters:

• i (np.ndarray) – Data sample.

• w (np.ndarray) – Cluster weight or information.

• params (dict) – Parameters for the algorithm.

• cache (dict, optional) – Values cached from previous calculations.

• op (Callable, default=operator.ge) – Comparison operator to use for the binary match criterion.

Returns:

Binary match criterion and cache used for later processing.

Return type:

tuple[bool, dict]

update(i: numpy.ndarray, w: numpy.ndarray, params: dict, cache: dict | None = None) → numpy.ndarray

Update the cluster weight.

Parameters:

• i (np.ndarray) – Data sample.

• w (np.ndarray) – Cluster weight or information.

• params (dict) – Parameters for the algorithm.

• cache (dict, optional) – Values cached from previous calculations.

Returns:

Updated cluster weight.

Return type:

np.ndarray

new_weight(i: numpy.ndarray, params: dict) → numpy.ndarray

Generate a new cluster weight.

Parameters:

• i (np.ndarray) – Data sample.

• params (dict) – Parameters for the algorithm.

Returns:

Newly generated cluster weight.

Return type:

np.ndarray

add_weight(new_w: numpy.ndarray)

Add a new cluster weight.

Parameters:

new_w (np.ndarray) – New cluster weight to add.

prune(X: numpy.ndarray)

Prune clusters based on the number of associated samples.

Parameters:

X (np.ndarray) – The input dataset.

post_step_fit(X: numpy.ndarray)

Perform post-fit operations, such as cluster pruning, after fitting each sample.

Parameters:

X (np.ndarray) – The input dataset.

_match_tracking(cache: List[Dict] | Dict, epsilon: float, params: List[Dict] | Dict, method: Literal['MT+', 'MT-', 'MT0', 'MT1', 'MT~']) → bool

Adjust the vigilance parameter based on match tracking methods.

Parameters:

• cache (dict) – Cached values from previous calculations.

• epsilon (float) – Adjustment factor for the vigilance parameter.

• params (dict) – Parameters for the algorithm.

• method (Literal["MT+", "MT-", "MT0", "MT1", "MT~"]) – Method to use for match tracking.

Returns:

True if the match tracking continues, False otherwise.

Return type:

bool

_set_params(new_params)

Set new parameters for the base module.

Parameters:

new_params (dict) – New parameters to set.

_deep_copy_params() → dict

Create a deep copy of the parameters.

Returns:

Deep copy of the parameters.

Return type:

dict

step_fit(x: numpy.ndarray, match_reset_func: Callable | None = None, match_tracking: Literal['MT+', 'MT-', 'MT0', 'MT1', 'MT~'] = 'MT+', epsilon: float = 0.0) → int

Fit the model to a single sample.

Parameters:

• x (np.ndarray) – Data sample.

• match_reset_func (Callable, optional) – Function to reset the match based on custom criteria.

• match_tracking (Literal["MT+", "MT-", "MT0", "MT1", "MT~"], default="MT+") – Method to reset the match.

• epsilon (float, default=0.0) – Adjustment factor for vigilance.

Returns:

Cluster label of the input sample.

Return type:

int

get_cluster_centers() → List[numpy.ndarray]

Get the centers of each cluster.

Returns:

Cluster centroids.

Return type:

List[np.ndarray]

plot_cluster_bounds(ax: matplotlib.axes.Axes, colors: artlib.common.utils.IndexableOrKeyable, linewidth: int = 1)

Visualize the boundaries of each cluster.

Parameters:

• ax (Axes) – Figure axes.

• colors (IndexableOrKeyable) – Colors to use for each cluster.

• linewidth (int, default=1) – Width of boundary lines.

class artlib.DualVigilanceART(base_module: artlib.common.BaseART.BaseART, rho_lower_bound: float)

Bases: artlib.common.BaseART.BaseART

Dual Vigilance ART for Clustering.

This module implements Dual Vigilance ART as first published in: [19].

Dual Vigilance ART allows a BaseART module to cluster with both an upper and lower vigilance value. The upper-vigilance value allows the BaseART module to cluster normally, however, data is simultaneously clustered using the lower vigilance level to combine multiple base ART categories into a single abstracted category. This permits clusters to be combined to form arbitrary shapes. For example if the BaseART module is FuzzyART, a Dual Vigilance Fuzzy ART clustering result would look like a series of hyper-boxes forming an arbitrary geometry.

base_module

rho_lower_bound

map: dict[int, int]

prepare_data(X: numpy.ndarray) → numpy.ndarray

Prepare data for clustering.

Parameters:

X (np.ndarray) – The dataset.

Returns:

Prepared data from the base module.

Return type:

np.ndarray

restore_data(X: numpy.ndarray) → numpy.ndarray

Restore data to its state prior to preparation.

Parameters:

X (np.ndarray) – The dataset.

Returns:

Restored data from the base module.

Return type:

np.ndarray

get_params(deep: bool = True) → dict

Get the parameters of the estimator.

Parameters:

deep (bool, optional) – If True, return the parameters for this class and contained subobjects that are estimators, by default True.

Returns:

Parameter names mapped to their values.

Return type:

dict

property n_clusters: int

Get the current number of clusters.

Returns:

The number of clusters.

Return type:

int

property dim_

Get the dimensionality of the data from the base module.

Returns:

Dimensionality of the data.

Return type:

int

property labels_

Get the labels from the base module.

Returns:

Labels for the data.

Return type:

np.ndarray

property W: List

Get the weights from the base module.

Returns:

Weights of the clusters.

Return type:

list of np.ndarray

check_dimensions(X: numpy.ndarray)

Check that the data has the correct dimensions.

Parameters:

X (np.ndarray) – The dataset.

validate_data(X: numpy.ndarray)

Validate the data prior to clustering.

Parameters:

X (np.ndarray) – The dataset.

static validate_params(params: dict)

Validate clustering parameters.

Parameters:

params (dict) – Dictionary containing parameters for the algorithm.

_match_tracking(cache: List[Dict] | Dict, epsilon: float, params: List[Dict] | Dict, method: Literal['MT+', 'MT-', 'MT0', 'MT1', 'MT~']) → bool

Adjust match tracking based on the method and epsilon value.

Parameters:

• cache (dict) – Cache containing intermediate results, including the match criterion.

• epsilon (float) – Adjustment factor for the match criterion.

• params (dict) – Dictionary containing algorithm parameters.

• method ({"MT+", "MT-", "MT0", "MT1", "MT~"}) – Match tracking method to use.

Returns:

True if match tracking continues, False otherwise.

Return type:

bool

_set_params(new_params)

_deep_copy_params() → dict

step_fit(x: numpy.ndarray, match_reset_func: Callable | None = None, match_tracking: Literal['MT+', 'MT-', 'MT0', 'MT1', 'MT~'] = 'MT+', epsilon: float = 0.0) → int

Fit the model to a single sample.

Parameters:

• x (np.ndarray) – Data sample.

• match_reset_func (callable, optional) – A callable accepting the data sample, a cluster weight, the params dict, and the cache dict. Returns True if the cluster is valid for the sample, False otherwise.

• match_tracking ({"MT+", "MT-", "MT0", "MT1", "MT~"}, optional) – Method for resetting match criterion, by default “MT+”.

• epsilon (float, optional) – Epsilon value used for adjusting match criterion, by default 0.0.

Returns:

Cluster label of the input sample.

Return type:

int

step_pred(x) → int

Predict the label for a single sample.

Parameters:

x (np.ndarray) – Data sample.

Returns:

Cluster label of the input sample.

Return type:

int

get_cluster_centers() → List[numpy.ndarray]

Get the centers of each cluster, used for regression.

Returns:

Cluster centroids.

Return type:

list of np.ndarray

plot_cluster_bounds(ax: matplotlib.axes.Axes, colors: artlib.common.utils.IndexableOrKeyable, linewidth: int = 1)

Visualize the bounds of each cluster.

Parameters:

• ax (matplotlib.axes.Axes) – Figure axes.

• colors (IndexableOrKeyable) – Colors to use for each cluster.

• linewidth (int, optional) – Width of boundary line, by default 1.

class artlib.BinaryFuzzyARTMAP

Factory for generating optimized BinaryFuzzyARTMAP models using various backends.

class artlib.FuzzyARTMAP

Factory for generating optimized FuzzyARTMAP models using various backends.

class artlib.HypersphereARTMAP

Factory for generating optimized HypersphereARTMAP models using various backends.

class artlib.GaussianARTMAP

Factory for generating optimized GaussianARTMAP models using various backends.