Estimators

sklearn-compatible TSK estimator wrappers.

All public estimator classes are re-exported from their respective sub-modules.

`ADATSKClassifier`

Bases: _BaseClassifierEstimator

TSK classifier with adaptive softmin antecedent (ADATSK).

The firing strength of each rule is computed with the Ada-softmin operator.

Reference

G. Xue, Q. Chang, J. Wang, K. Zhang and N. R. Pal, "An Adaptive Neuro-Fuzzy System With Integrated Feature Selection and Rule Extraction for High-Dimensional Classification Problems," in IEEE Transactions on Fuzzy Systems, vol. 31, no. 7, pp. 2167-2181, July 2023, doi: 10.1109/TFUZZ.2022.3220950.

Example

from highfis import ADATSKClassifier

clf = ADATSKClassifier(n_mfs=30, random_state=0)
clf.fit(X_train, y_train)

Initialise an ADATSK classifier.

Parameters:

Name	Type	Description	Default
`input_configs`	`list[InputConfig] \| None`	Per-feature :class:`InputConfig` list. Only `name` is used when `mf_init="kmeans"`.	`None`
`n_mfs`	`int`	Number of k-means clusters / grid MFs (default `5`).	`5`
`mf_init`	`str`	`"kmeans"` (default), `"minibatch_kmeans"`, `"fcm"`, or `"grid"`.	`'kmeans'`
`sigma_scale`	`float \| str`	Sigma scale factor. `1.0` recommended; Ada-softmin handles high-dimensional stability.	`1.0`
`random_state`	`int \| None`	Seed for k-means and weight initialisation.	`None`
`epochs`	`int`	Maximum training epochs (default `10`).	`10`
`learning_rate`	`float`	Adam learning rate (default `0.01`).	`0.01`
`verbose`	`bool \| int`	Print per-epoch progress.	`False`
`rule_base`	`str \| None`	`"coco"` or `"cartesian"`.	`None`
`batch_size`	`int \| None`	Mini-batch size (default `512`).	`512`
`shuffle`	`bool`	Reshuffle each epoch.	`True`
`ur_weight`	`float`	Uncertainty regularisation weight.	`0.0`
`ur_target`	`float \| None`	Uncertainty regularisation target.	`None`
`consequent_batch_norm`	`bool`	Batch normalisation on consequent layers.	`False`
`patience`	`int \| None`	Early-stopping patience (default `20`). Set to `None` to disable early stopping.	`20`
`restore_best`	`bool`	If `True` (default), restore the best validation model weights after training.	`True`
`weight_decay`	`float`	L2 weight decay for consequent parameters.	`1e-08`

Source code in highfis/estimators/_adaptive.py

def __init__(
    self,
    *,
    input_configs: list[InputConfig] | None = None,
    n_mfs: int = 5,
    mf_init: str = "kmeans",
    sigma_scale: float | str = 1.0,
    random_state: int | None = None,
    epochs: int = 10,
    learning_rate: float = 1e-2,
    verbose: bool | int = False,
    rule_base: str | None = None,
    batch_size: int | None = 512,
    shuffle: bool = True,
    ur_weight: float = 0.0,
    ur_target: float | None = None,
    consequent_batch_norm: bool = False,
    patience: int | None = 20,
    restore_best: bool = True,
    weight_decay: float = 1e-8,
) -> None:
    """Initialise an ADATSK classifier.

    Args:
        input_configs: Per-feature :class:`InputConfig` list. Only
            ``name`` is used when ``mf_init="kmeans"``.
        n_mfs: Number of k-means clusters / grid MFs (default ``5``).
        mf_init: ``"kmeans"`` (default), ``"minibatch_kmeans"``, ``"fcm"``, or ``"grid"``.
        sigma_scale: Sigma scale factor. ``1.0`` recommended; Ada-softmin
            handles high-dimensional stability.
        random_state: Seed for k-means and weight initialisation.
        epochs: Maximum training epochs (default ``10``).
        learning_rate: Adam learning rate (default ``0.01``).
        verbose: Print per-epoch progress.
        rule_base: ``"coco"`` or ``"cartesian"``.
        batch_size: Mini-batch size (default ``512``).
        shuffle: Reshuffle each epoch.
        ur_weight: Uncertainty regularisation weight.
        ur_target: Uncertainty regularisation target.
        consequent_batch_norm: Batch normalisation on consequent layers.
        patience: Early-stopping patience (default ``20``). Set to ``None`` to disable early stopping.
        restore_best: If ``True`` (default), restore the best validation
            model weights after training.
        weight_decay: L2 weight decay for consequent parameters.
    """
    super().__init__(
        input_configs=input_configs,
        n_mfs=n_mfs,
        mf_init=mf_init,
        sigma_scale=sigma_scale,
        random_state=random_state,
        epochs=epochs,
        learning_rate=learning_rate,
        verbose=verbose,
        rule_base=rule_base,
        batch_size=batch_size,
        shuffle=shuffle,
        ur_weight=ur_weight,
        ur_target=ur_target,
        consequent_batch_norm=consequent_batch_norm,
        patience=patience,
        restore_best=restore_best,
        weight_decay=weight_decay,
    )

`evaluate`

Compute classification evaluation metrics for the provided dataset.

Source code in highfis/estimators/_base.py

def evaluate(
    self,
    X: Any,
    y: Any,
    metrics: list[str] | None = None,
    sample_weight: Any | None = None,
) -> dict[str, float]:
    """Compute classification evaluation metrics for the provided dataset."""
    y_true = np.asarray(y)
    y_pred = self.predict(X)
    return compute_metrics(
        task="classification",
        y_true=y_true,
        y_pred=y_pred,
        sample_weight=sample_weight,
        metrics=metrics,
    )

`feature_importance`

Compute a normalized feature importance vector from consequent weights.

Source code in highfis/estimators/_base.py

def feature_importance(self) -> np.ndarray | None:
    """Compute a normalized feature importance vector from consequent weights."""
    check_is_fitted(self, "model_")
    weights = self.model_.get_consequent_weights()
    if weights is None:
        return None

    consequent_layer = self.model_.consequent_layer
    if hasattr(consequent_layer, "rule_feature_mask"):
        rule_feature_mask = cast(Tensor, consequent_layer.rule_feature_mask)
        weights = weights * rule_feature_mask.unsqueeze(1) if weights.ndim == 3 else weights * rule_feature_mask

    abs_weights = weights.abs()
    if abs_weights.ndim == 3:
        importance = abs_weights.mean(dim=(0, 1))
    elif abs_weights.ndim == 2:
        importance = abs_weights.mean(dim=0)
    else:
        raise ValueError("unsupported consequent weight shape for feature importance")

    return _normalize_importance(importance)

`fit`

Train the TSK classifier on labeled samples.

Validation data should be supplied using x_val and y_val when available.

Source code in highfis/estimators/_base.py

def fit(
    self,
    x: Any,
    y: Any,
    *,
    x_val: Any | None = None,
    y_val: Any | None = None,
) -> Self:
    """Train the TSK classifier on labeled samples.

    Validation data should be supplied using ``x_val`` and ``y_val``
    when available.
    """
    x_arr, y_arr = check_X_y(x, y)

    if self.random_state is not None:
        torch.manual_seed(int(self.random_state))

    le = LabelEncoder()
    y_idx = le.fit_transform(np.asarray(y_arr))

    input_mfs, feature_names, effective_rule_base = self._build_input_mfs(x_arr)

    self.n_features_in_ = x_arr.shape[1]
    self.feature_names_in_ = np.asarray(feature_names, dtype=object)
    self.classes_ = le.classes_
    self._label_encoder_ = le

    _device = torch.device(str(self.device))
    self.model_ = self._build_model(input_mfs, len(self.classes_), effective_rule_base).to(_device)

    y_t = torch.as_tensor(y_idx, dtype=torch.long, device=_device)

    # Prepare validation tensors if provided via fit.
    x_val_t: torch.Tensor | None = None
    y_val_t: torch.Tensor | None = None
    if (x_val is None) ^ (y_val is None):
        raise ValueError("x_val and y_val must be provided together")
    if x_val is not None and y_val is not None:
        x_v_arr, y_v_arr = check_X_y(x_val, y_val)
        x_val_t = self._as_tensor_x(x_v_arr, _device)
        y_val_idx = le.transform(np.asarray(y_v_arr))
        y_val_t = torch.as_tensor(y_val_idx, dtype=torch.long, device=_device)

    self.history_ = self.model_.fit(
        self._as_tensor_x(x_arr, _device),
        y_t,
        epochs=int(self.epochs),
        learning_rate=float(self.learning_rate),
        batch_size=self.batch_size,
        shuffle=bool(self.shuffle),
        ur_weight=float(self.ur_weight),
        ur_target=self.ur_target,
        verbose=self.verbose,
        x_val=x_val_t,
        y_val=y_val_t,
        patience=self.patience,
        restore_best=self.restore_best,
        weight_decay=float(self.weight_decay),
    )
    self.rule_base_ = effective_rule_base
    return self

`get_mf_params`

Return model membership function metadata after fitting.

Source code in highfis/estimators/_base.py

def get_mf_params(self) -> dict[str, list[dict[str, Any]]]:
    """Return model membership function metadata after fitting."""
    check_is_fitted(self, "model_")
    return self.model_.get_mf_params()

`inspect`

Return a structured summary of fitted model state and rule metadata.

Source code in highfis/estimators/_base.py

def inspect(self) -> dict[str, Any]:
    """Return a structured summary of fitted model state and rule metadata."""
    check_is_fitted(self, "model_")
    return {
        "n_rules": int(self.model_.n_rules),
        "n_inputs": int(self.model_.n_inputs),
        "feature_names": list(self.model_.input_names),
        "rule_base": self.rule_base_,
        "defuzzifier_type": type(self.model_.defuzzifier).__name__,
        "mf_params": self.get_mf_params(),
        "rule_table": self.model_.get_rule_table(),
    }

`load` `classmethod`

Load a persisted estimator created by save.

Source code in highfis/estimators/_base.py

@classmethod
def load(cls, path: str) -> Self:
    """Load a persisted estimator created by save."""
    checkpoint = load_checkpoint(path)
    validate_checkpoint_payload(checkpoint, expected_estimator_class=cls.__name__)

    params: dict[str, Any] = dict(checkpoint["estimator_params"])
    if params.get("input_configs") is not None:
        params["input_configs"] = [InputConfig(**c) for c in params["input_configs"]]
    estimator = cls(**params)
    model_init = checkpoint["model_init"]
    estimator.rule_base_ = model_init["rule_base"]
    estimator.model_ = estimator._build_model(
        deserialize_input_mfs(model_init["input_mfs_config"]),
        int(model_init["n_classes"]),
        str(model_init["rule_base"]),
    )
    estimator.model_.load_state_dict(checkpoint["model_state_dict"])
    estimator.model_.to(torch.device(str(estimator.device)))

    fitted = checkpoint["fitted_attrs"]
    estimator.n_features_in_ = int(fitted["n_features_in"])
    estimator.feature_names_in_ = np.asarray(fitted["feature_names_in"], dtype=object)
    estimator.classes_ = np.asarray(fitted["classes"], dtype=object)
    label_encoder = LabelEncoder()
    label_encoder.classes_ = estimator.classes_
    estimator._label_encoder_ = label_encoder
    estimator.history_ = cast(dict[str, Any], checkpoint.get("history", {}))
    return estimator

`predict`

Predict class labels for input samples.

Source code in highfis/estimators/_base.py

def predict(self, x: Any) -> np.ndarray:
    """Predict class labels for input samples."""
    proba = self.predict_proba(x)
    y_idx = np.argmax(proba, axis=1)
    return np.asarray(self._label_encoder_.inverse_transform(y_idx))

`predict_proba`

Predict class probabilities for input samples.

Source code in highfis/estimators/_base.py

def predict_proba(self, x: Any) -> np.ndarray:
    """Predict class probabilities for input samples."""
    check_is_fitted(self, "model_")
    x_arr = check_array(x)
    if x_arr.shape[1] != self.n_features_in_:
        raise ValueError(f"expected {self.n_features_in_} features, got {x_arr.shape[1]}")
    probs = cast(Any, self.model_).predict_proba(self._as_tensor_x(x_arr, torch.device(str(self.device))))
    return probs.detach().cpu().numpy()

`rule_activation`

Return normalized rule activations for the provided inputs.

Source code in highfis/estimators/_base.py

def rule_activation(self, X: Any) -> np.ndarray:
    """Return normalized rule activations for the provided inputs."""
    check_is_fitted(self, "model_")
    x_arr = check_array(X)
    if x_arr.shape[1] != self.n_features_in_:
        raise ValueError(f"expected {self.n_features_in_} features, got {x_arr.shape[1]}")

    was_training = self.model_.training
    try:
        self.model_.eval()
        with torch.no_grad():
            norm_w = self.model_.forward_antecedents(self._as_tensor_x(x_arr, torch.device(str(self.device))))
    finally:
        self.model_.train(was_training)

    return _to_numpy(norm_w)

`save`

Persist estimator configuration, model weights and fitted metadata.

Source code in highfis/estimators/_base.py

def save(self, path: str) -> None:
    """Persist estimator configuration, model weights and fitted metadata."""
    checkpoint = self._build_checkpoint_base(
        model_init={
            "input_mfs_config": serialize_input_mfs(self.model_.input_mfs),
            "n_classes": len(self.classes_),
            "rule_base": self.rule_base_,
        },
        fitted_attrs={
            "n_features_in": int(self.n_features_in_),
            "feature_names_in": self.feature_names_in_.tolist(),
            "classes": self.classes_.tolist(),
        },
    )
    save_checkpoint(path, checkpoint)

`score`

Return classification accuracy on the provided dataset.

Source code in highfis/estimators/_base.py

def score(self, X: Any, y: Any, sample_weight: Any = None) -> float:
    """Return classification accuracy on the provided dataset."""
    y_true = np.asarray(y)
    y_pred = self.predict(X)
    return float(accuracy_score(y_true, y_pred, sample_weight=sample_weight))

`ADATSKRegressor`

Bases: _BaseRegressorEstimator

TSK regressor with adaptive softmin antecedent (ADATSK).

The firing strength of each rule is computed with the Ada-softmin operator.

Reference

G. Xue, Q. Chang, J. Wang, K. Zhang and N. R. Pal, "An Adaptive Neuro-Fuzzy System With Integrated Feature Selection and Rule Extraction for High-Dimensional Classification Problems," in IEEE Transactions on Fuzzy Systems, vol. 31, no. 7, pp. 2167-2181, July 2023, doi: 10.1109/TFUZZ.2022.3220950.

Example

from highfis import ADATSKRegressor

reg = ADATSKRegressor(n_mfs=30, random_state=0)
reg.fit(X_train, y_train)

Initialise an ADATSK regressor.

Parameters:

Name	Type	Description	Default
`input_configs`	`list[InputConfig] \| None`	Per-feature :class:`InputConfig` list. Only `name` is used when `mf_init="kmeans"`.	`None`
`n_mfs`	`int`	Number of k-means clusters / grid MFs (default `5`).	`5`
`mf_init`	`str`	`"kmeans"` (default), `"minibatch_kmeans"`, `"fcm"`, or `"grid"`.	`'kmeans'`
`sigma_scale`	`float \| str`	Sigma scale factor. `1.0` recommended.	`1.0`
`random_state`	`int \| None`	Seed for k-means and weight initialisation.	`None`
`epochs`	`int`	Maximum training epochs (default `10`).	`10`
`learning_rate`	`float`	Adam learning rate (default `0.01`).	`0.01`
`verbose`	`bool \| int`	Print per-epoch progress.	`False`
`rule_base`	`str \| None`	`"coco"` or `"cartesian"`.	`None`
`batch_size`	`int \| None`	Mini-batch size (default `512`).	`512`
`shuffle`	`bool`	Reshuffle each epoch.	`True`
`ur_weight`	`float`	Uncertainty regularisation weight.	`0.0`
`ur_target`	`float \| None`	Uncertainty regularisation target.	`None`
`consequent_batch_norm`	`bool`	Batch normalisation on consequent layers.	`False`
`patience`	`int \| None`	Early-stopping patience (default `20`). Set to `None` to disable early stopping.	`20`
`restore_best`	`bool`	If `True` (default), restore the best validation model weights after training.	`True`
`weight_decay`	`float`	L2 weight decay for consequent parameters.	`1e-08`

Source code in highfis/estimators/_adaptive.py

def __init__(
    self,
    *,
    input_configs: list[InputConfig] | None = None,
    n_mfs: int = 5,
    mf_init: str = "kmeans",
    sigma_scale: float | str = 1.0,
    random_state: int | None = None,
    epochs: int = 10,
    learning_rate: float = 1e-2,
    verbose: bool | int = False,
    rule_base: str | None = None,
    batch_size: int | None = 512,
    shuffle: bool = True,
    ur_weight: float = 0.0,
    ur_target: float | None = None,
    consequent_batch_norm: bool = False,
    patience: int | None = 20,
    restore_best: bool = True,
    weight_decay: float = 1e-8,
) -> None:
    """Initialise an ADATSK regressor.

    Args:
        input_configs: Per-feature :class:`InputConfig` list. Only
            ``name`` is used when ``mf_init="kmeans"``.
        n_mfs: Number of k-means clusters / grid MFs (default ``5``).
        mf_init: ``"kmeans"`` (default), ``"minibatch_kmeans"``, ``"fcm"``, or ``"grid"``.
        sigma_scale: Sigma scale factor. ``1.0`` recommended.
        random_state: Seed for k-means and weight initialisation.
        epochs: Maximum training epochs (default ``10``).
        learning_rate: Adam learning rate (default ``0.01``).
        verbose: Print per-epoch progress.
        rule_base: ``"coco"`` or ``"cartesian"``.
        batch_size: Mini-batch size (default ``512``).
        shuffle: Reshuffle each epoch.
        ur_weight: Uncertainty regularisation weight.
        ur_target: Uncertainty regularisation target.
        consequent_batch_norm: Batch normalisation on consequent layers.
        patience: Early-stopping patience (default ``20``). Set to ``None`` to disable early stopping.
        restore_best: If ``True`` (default), restore the best validation
            model weights after training.
        weight_decay: L2 weight decay for consequent parameters.
    """
    super().__init__(
        input_configs=input_configs,
        n_mfs=n_mfs,
        mf_init=mf_init,
        sigma_scale=sigma_scale,
        random_state=random_state,
        epochs=epochs,
        learning_rate=learning_rate,
        verbose=verbose,
        rule_base=rule_base,
        batch_size=batch_size,
        shuffle=shuffle,
        ur_weight=ur_weight,
        ur_target=ur_target,
        consequent_batch_norm=consequent_batch_norm,
        patience=patience,
        restore_best=restore_best,
        weight_decay=weight_decay,
    )

`evaluate`

Compute regression evaluation metrics for the provided dataset.

Source code in highfis/estimators/_base.py

def evaluate(
    self,
    X: Any,
    y: Any,
    metrics: list[str] | None = None,
    sample_weight: Any | None = None,
) -> dict[str, float]:
    """Compute regression evaluation metrics for the provided dataset."""
    y_true = np.asarray(y)
    y_pred = self.predict(X)
    return compute_metrics(
        task="regression",
        y_true=y_true,
        y_pred=y_pred,
        sample_weight=sample_weight,
        metrics=metrics,
    )

`feature_importance`

Compute a normalized feature importance vector from consequent weights.

Source code in highfis/estimators/_base.py

def feature_importance(self) -> np.ndarray | None:
    """Compute a normalized feature importance vector from consequent weights."""
    check_is_fitted(self, "model_")
    weights = self.model_.get_consequent_weights()
    if weights is None:
        return None

    consequent_layer = self.model_.consequent_layer
    if hasattr(consequent_layer, "rule_feature_mask"):
        rule_feature_mask = cast(Tensor, consequent_layer.rule_feature_mask)
        weights = weights * rule_feature_mask.unsqueeze(1) if weights.ndim == 3 else weights * rule_feature_mask

    abs_weights = weights.abs()
    if abs_weights.ndim == 3:
        importance = abs_weights.mean(dim=(0, 1))
    elif abs_weights.ndim == 2:
        importance = abs_weights.mean(dim=0)
    else:
        raise ValueError("unsupported consequent weight shape for feature importance")

    return _normalize_importance(importance)

`fit`

Train the TSK regressor on labeled samples.

Validation data should be supplied using x_val and y_val when available.

Source code in highfis/estimators/_base.py

def fit(
    self,
    x: Any,
    y: Any,
    *,
    x_val: Any | None = None,
    y_val: Any | None = None,
) -> Self:
    """Train the TSK regressor on labeled samples.

    Validation data should be supplied using ``x_val`` and ``y_val``
    when available.
    """
    x_arr, y_arr = check_X_y(x, y)

    if self.random_state is not None:
        torch.manual_seed(int(self.random_state))

    input_mfs, feature_names, effective_rule_base = self._build_input_mfs(x_arr)

    self.n_features_in_ = x_arr.shape[1]
    self.feature_names_in_ = np.asarray(feature_names, dtype=object)

    _device = torch.device(str(self.device))
    self.model_ = self._build_regressor_model(input_mfs, effective_rule_base).to(_device)

    y_t = torch.as_tensor(np.asarray(y_arr, dtype=np.float32), dtype=torch.float32, device=_device)

    # Prepare validation tensors if provided via fit.
    x_val_t: torch.Tensor | None = None
    y_val_t: torch.Tensor | None = None
    if (x_val is None) ^ (y_val is None):
        raise ValueError("x_val and y_val must be provided together")
    if x_val is not None and y_val is not None:
        x_v_arr, y_v_arr = check_X_y(x_val, y_val)
        x_val_t = self._as_tensor_x(x_v_arr, _device)
        y_val_t = torch.as_tensor(np.asarray(y_v_arr, dtype=np.float32), dtype=torch.float32, device=_device)

    self.history_ = self.model_.fit(
        self._as_tensor_x(x_arr, _device),
        y_t,
        epochs=int(self.epochs),
        learning_rate=float(self.learning_rate),
        batch_size=self.batch_size,
        shuffle=bool(self.shuffle),
        ur_weight=float(self.ur_weight),
        ur_target=self.ur_target,
        verbose=self.verbose,
        x_val=x_val_t,
        y_val=y_val_t,
        patience=self.patience,
        restore_best=self.restore_best,
        weight_decay=float(self.weight_decay),
    )
    self.rule_base_ = effective_rule_base
    return self

`get_mf_params`

Return model membership function metadata after fitting.

Source code in highfis/estimators/_base.py

def get_mf_params(self) -> dict[str, list[dict[str, Any]]]:
    """Return model membership function metadata after fitting."""
    check_is_fitted(self, "model_")
    return self.model_.get_mf_params()

`inspect`

Return a structured summary of fitted model state and rule metadata.

Source code in highfis/estimators/_base.py

def inspect(self) -> dict[str, Any]:
    """Return a structured summary of fitted model state and rule metadata."""
    check_is_fitted(self, "model_")
    return {
        "n_rules": int(self.model_.n_rules),
        "n_inputs": int(self.model_.n_inputs),
        "feature_names": list(self.model_.input_names),
        "rule_base": self.rule_base_,
        "defuzzifier_type": type(self.model_.defuzzifier).__name__,
        "mf_params": self.get_mf_params(),
        "rule_table": self.model_.get_rule_table(),
    }

`load` `classmethod`

Load a persisted estimator created by save.

Source code in highfis/estimators/_base.py

@classmethod
def load(cls, path: str) -> Self:
    """Load a persisted estimator created by save."""
    checkpoint = load_checkpoint(path)
    validate_checkpoint_payload(checkpoint, expected_estimator_class=cls.__name__)

    params: dict[str, Any] = dict(checkpoint["estimator_params"])
    if params.get("input_configs") is not None:
        params["input_configs"] = [InputConfig(**c) for c in params["input_configs"]]
    estimator = cls(**params)
    model_init = checkpoint["model_init"]
    estimator.rule_base_ = model_init["rule_base"]
    estimator.model_ = estimator._build_regressor_model(
        deserialize_input_mfs(model_init["input_mfs_config"]),
        str(model_init["rule_base"]),
    )
    estimator.model_.load_state_dict(checkpoint["model_state_dict"])
    estimator.model_.to(torch.device(str(estimator.device)))

    fitted = checkpoint["fitted_attrs"]
    estimator.n_features_in_ = int(fitted["n_features_in"])
    estimator.feature_names_in_ = np.asarray(fitted["feature_names_in"], dtype=object)
    estimator.history_ = cast(dict[str, Any], checkpoint.get("history", {}))
    return estimator

`predict`

Predict continuous target values for input samples.

Source code in highfis/estimators/_base.py

def predict(self, x: Any) -> np.ndarray:
    """Predict continuous target values for input samples."""
    check_is_fitted(self, "model_")
    x_arr = check_array(x)
    if x_arr.shape[1] != self.n_features_in_:
        raise ValueError(f"expected {self.n_features_in_} features, got {x_arr.shape[1]}")
    preds = cast(Any, self.model_).predict(self._as_tensor_x(x_arr, torch.device(str(self.device))))
    return preds.detach().cpu().numpy()

`rule_activation`

Return normalized rule activations for the provided inputs.

Source code in highfis/estimators/_base.py

def rule_activation(self, X: Any) -> np.ndarray:
    """Return normalized rule activations for the provided inputs."""
    check_is_fitted(self, "model_")
    x_arr = check_array(X)
    if x_arr.shape[1] != self.n_features_in_:
        raise ValueError(f"expected {self.n_features_in_} features, got {x_arr.shape[1]}")

    was_training = self.model_.training
    try:
        self.model_.eval()
        with torch.no_grad():
            norm_w = self.model_.forward_antecedents(self._as_tensor_x(x_arr, torch.device(str(self.device))))
    finally:
        self.model_.train(was_training)

    return _to_numpy(norm_w)

`save`

Persist estimator configuration, model weights and fitted metadata.

Source code in highfis/estimators/_base.py

def save(self, path: str) -> None:
    """Persist estimator configuration, model weights and fitted metadata."""
    checkpoint = self._build_checkpoint_base(
        model_init={
            "input_mfs_config": serialize_input_mfs(self.model_.input_mfs),
            "rule_base": self.rule_base_,
        },
        fitted_attrs={
            "n_features_in": int(self.n_features_in_),
            "feature_names_in": self.feature_names_in_.tolist(),
        },
    )
    save_checkpoint(path, checkpoint)

`ADMTSKClassifier`

Bases: _BaseClassifierEstimator

ADMTSK classifier estimator with Composite GMF and adaptive Dombi lambda.

ADMTSK is an adaptive Dombi TSK fuzzy system designed for high-dimensional inference. It combines a Dombi T-norm antecedent with a positive lower-bound Composite Gaussian membership function (CGMF) and normalized first-order consequents.

Reference

G. Xue, L. Hu, J. Wang and S. Ablameyko, "ADMTSK: A High-Dimensional Takagi-Sugeno-Kang Fuzzy System Based on Adaptive Dombi T-Norm," in IEEE Transactions on Fuzzy Systems, vol. 33, no. 6, pp. 1767-1780, June 2025, doi: 10.1109/TFUZZ.2025.3535640.

Example

from highfis import ADMTSKClassifier

clf = ADMTSKClassifier()
clf.fit(X_train, y_train)

Initialize an ADMTSK classifier estimator.

Parameters:

Name	Type	Description	Default
`input_configs`	`list[InputConfig] \| None`	Optional list of per-feature input configurations.	`None`
`n_mfs`	`int`	Number of membership functions per input when using `mf_init="kmeans"`, `"minibatch_kmeans"`, or `"grid"`.	`5`
`mf_init`	`str`	Initialisation strategy for MFs: `"kmeans"` (default), `"minibatch_kmeans"`, `"fcm"`, or `"grid"`.	`'kmeans'`
`sigma_scale`	`float \| str`	Scale factor used to initialise Gaussian MF sigma values.	`1.0`
`random_state`	`int \| None`	Random seed for MF initialisation and weights.	`None`
`epochs`	`int`	Maximum number of training epochs.	`10`
`learning_rate`	`float`	Learning rate for the optimizer.	`0.01`
`verbose`	`bool \| int`	Verbosity level for training output.	`False`
`rule_base`	`str \| None`	Rule base strategy override, typically `"coco"` or `"cartesian"`.	`None`
`batch_size`	`int \| None`	Mini-batch size for training.	`512`
`shuffle`	`bool`	Whether to shuffle training data each epoch.	`True`
`ur_weight`	`float`	Uniform-rule regularisation weight.	`0.0`
`ur_target`	`float \| None`	Target average rule activation for uniform regularisation.	`None`
`consequent_batch_norm`	`bool`	If True, apply batch normalization to consequent inputs.	`False`
`pfrb_max_rules`	`int \| None`	Maximum number of rules for point-based FRB.	`None`
`patience`	`int \| None`	Early stopping patience. Use `None` to disable.	`20`
`restore_best`	`bool`	If True, restore the best validation weights.	`True`
`weight_decay`	`float`	Weight decay applied during training.	`1e-08`
`adaptive`	`bool`	If True, use adaptive lambda selection for Dombi T-norm.	`True`
`lambda_`	`float`	Fixed Dombi parameter when adaptive is False.	`1.0`
`lower_bound`	`float`	Lower bound used by Composite GMF.	`1.0 / math.e`
`k`	`float`	Heuristic constant used to compute adaptive lambda.	`10.0`

Raises:

Type	Description
`ValueError`	If estimator hyperparameters are invalid.

Source code in highfis/estimators/_dombi.py

def __init__(
    self,
    *,
    input_configs: list[InputConfig] | None = None,
    n_mfs: int = 5,
    mf_init: str = "kmeans",
    sigma_scale: float | str = 1.0,
    random_state: int | None = None,
    epochs: int = 10,
    learning_rate: float = 1e-2,
    verbose: bool | int = False,
    rule_base: str | None = None,
    batch_size: int | None = 512,
    shuffle: bool = True,
    ur_weight: float = 0.0,
    ur_target: float | None = None,
    consequent_batch_norm: bool = False,
    pfrb_max_rules: int | None = None,
    patience: int | None = 20,
    restore_best: bool = True,
    weight_decay: float = 1e-8,
    adaptive: bool = True,
    lambda_: float = 1.0,
    lower_bound: float = 1.0 / math.e,
    k: float = 10.0,
) -> None:
    """Initialize an ADMTSK classifier estimator.

    Args:
        input_configs: Optional list of per-feature input configurations.
        n_mfs: Number of membership functions per input when using
            ``mf_init="kmeans"``, ``"minibatch_kmeans"``, or ``"grid"``.
        mf_init: Initialisation strategy for MFs: ``"kmeans"`` (default),
            ``"minibatch_kmeans"``, ``"fcm"``, or ``"grid"``.
        sigma_scale: Scale factor used to initialise Gaussian MF sigma
            values.
        random_state: Random seed for MF initialisation and weights.
        epochs: Maximum number of training epochs.
        learning_rate: Learning rate for the optimizer.
        verbose: Verbosity level for training output.
        rule_base: Rule base strategy override, typically ``"coco"`` or
            ``"cartesian"``.
        batch_size: Mini-batch size for training.
        shuffle: Whether to shuffle training data each epoch.
        ur_weight: Uniform-rule regularisation weight.
        ur_target: Target average rule activation for uniform regularisation.
        consequent_batch_norm: If True, apply batch normalization to
            consequent inputs.
        pfrb_max_rules: Maximum number of rules for point-based FRB.
        patience: Early stopping patience. Use ``None`` to disable.
        restore_best: If True, restore the best validation weights.
        weight_decay: Weight decay applied during training.
        adaptive: If True, use adaptive lambda selection for Dombi T-norm.
        lambda_: Fixed Dombi parameter when adaptive is False.
        lower_bound: Lower bound used by Composite GMF.
        k: Heuristic constant used to compute adaptive lambda.

    Raises:
        ValueError: If estimator hyperparameters are invalid.
    """
    super().__init__(
        input_configs=input_configs,
        n_mfs=n_mfs,
        mf_init=mf_init,
        sigma_scale=sigma_scale,
        random_state=random_state,
        epochs=epochs,
        learning_rate=learning_rate,
        verbose=verbose,
        rule_base=rule_base,
        batch_size=batch_size,
        shuffle=shuffle,
        ur_weight=ur_weight,
        ur_target=ur_target,
        consequent_batch_norm=consequent_batch_norm,
        pfrb_max_rules=pfrb_max_rules,
        patience=patience,
        restore_best=restore_best,
        weight_decay=weight_decay,
    )
    self.adaptive = bool(adaptive)
    self.lambda_ = float(lambda_)
    self.lower_bound = float(lower_bound)
    self.k = float(k)

`evaluate`

Compute classification evaluation metrics for the provided dataset.

Source code in highfis/estimators/_base.py

def evaluate(
    self,
    X: Any,
    y: Any,
    metrics: list[str] | None = None,
    sample_weight: Any | None = None,
) -> dict[str, float]:
    """Compute classification evaluation metrics for the provided dataset."""
    y_true = np.asarray(y)
    y_pred = self.predict(X)
    return compute_metrics(
        task="classification",
        y_true=y_true,
        y_pred=y_pred,
        sample_weight=sample_weight,
        metrics=metrics,
    )

`feature_importance`

Compute a normalized feature importance vector from consequent weights.

Source code in highfis/estimators/_base.py

def feature_importance(self) -> np.ndarray | None:
    """Compute a normalized feature importance vector from consequent weights."""
    check_is_fitted(self, "model_")
    weights = self.model_.get_consequent_weights()
    if weights is None:
        return None

    consequent_layer = self.model_.consequent_layer
    if hasattr(consequent_layer, "rule_feature_mask"):
        rule_feature_mask = cast(Tensor, consequent_layer.rule_feature_mask)
        weights = weights * rule_feature_mask.unsqueeze(1) if weights.ndim == 3 else weights * rule_feature_mask

    abs_weights = weights.abs()
    if abs_weights.ndim == 3:
        importance = abs_weights.mean(dim=(0, 1))
    elif abs_weights.ndim == 2:
        importance = abs_weights.mean(dim=0)
    else:
        raise ValueError("unsupported consequent weight shape for feature importance")

    return _normalize_importance(importance)

`fit`

Train the TSK classifier on labeled samples.

Validation data should be supplied using x_val and y_val when available.

Source code in highfis/estimators/_base.py

def fit(
    self,
    x: Any,
    y: Any,
    *,
    x_val: Any | None = None,
    y_val: Any | None = None,
) -> Self:
    """Train the TSK classifier on labeled samples.

    Validation data should be supplied using ``x_val`` and ``y_val``
    when available.
    """
    x_arr, y_arr = check_X_y(x, y)

    if self.random_state is not None:
        torch.manual_seed(int(self.random_state))

    le = LabelEncoder()
    y_idx = le.fit_transform(np.asarray(y_arr))

    input_mfs, feature_names, effective_rule_base = self._build_input_mfs(x_arr)

    self.n_features_in_ = x_arr.shape[1]
    self.feature_names_in_ = np.asarray(feature_names, dtype=object)
    self.classes_ = le.classes_
    self._label_encoder_ = le

    _device = torch.device(str(self.device))
    self.model_ = self._build_model(input_mfs, len(self.classes_), effective_rule_base).to(_device)

    y_t = torch.as_tensor(y_idx, dtype=torch.long, device=_device)

    # Prepare validation tensors if provided via fit.
    x_val_t: torch.Tensor | None = None
    y_val_t: torch.Tensor | None = None
    if (x_val is None) ^ (y_val is None):
        raise ValueError("x_val and y_val must be provided together")
    if x_val is not None and y_val is not None:
        x_v_arr, y_v_arr = check_X_y(x_val, y_val)
        x_val_t = self._as_tensor_x(x_v_arr, _device)
        y_val_idx = le.transform(np.asarray(y_v_arr))
        y_val_t = torch.as_tensor(y_val_idx, dtype=torch.long, device=_device)

    self.history_ = self.model_.fit(
        self._as_tensor_x(x_arr, _device),
        y_t,
        epochs=int(self.epochs),
        learning_rate=float(self.learning_rate),
        batch_size=self.batch_size,
        shuffle=bool(self.shuffle),
        ur_weight=float(self.ur_weight),
        ur_target=self.ur_target,
        verbose=self.verbose,
        x_val=x_val_t,
        y_val=y_val_t,
        patience=self.patience,
        restore_best=self.restore_best,
        weight_decay=float(self.weight_decay),
    )
    self.rule_base_ = effective_rule_base
    return self

`get_mf_params`

Return model membership function metadata after fitting.

Source code in highfis/estimators/_base.py

def get_mf_params(self) -> dict[str, list[dict[str, Any]]]:
    """Return model membership function metadata after fitting."""
    check_is_fitted(self, "model_")
    return self.model_.get_mf_params()

`inspect`

Return a structured summary of fitted model state and rule metadata.

Source code in highfis/estimators/_base.py

def inspect(self) -> dict[str, Any]:
    """Return a structured summary of fitted model state and rule metadata."""
    check_is_fitted(self, "model_")
    return {
        "n_rules": int(self.model_.n_rules),
        "n_inputs": int(self.model_.n_inputs),
        "feature_names": list(self.model_.input_names),
        "rule_base": self.rule_base_,
        "defuzzifier_type": type(self.model_.defuzzifier).__name__,
        "mf_params": self.get_mf_params(),
        "rule_table": self.model_.get_rule_table(),
    }

`load` `classmethod`

Load a persisted estimator created by save.

Source code in highfis/estimators/_base.py

@classmethod
def load(cls, path: str) -> Self:
    """Load a persisted estimator created by save."""
    checkpoint = load_checkpoint(path)
    validate_checkpoint_payload(checkpoint, expected_estimator_class=cls.__name__)

    params: dict[str, Any] = dict(checkpoint["estimator_params"])
    if params.get("input_configs") is not None:
        params["input_configs"] = [InputConfig(**c) for c in params["input_configs"]]
    estimator = cls(**params)
    model_init = checkpoint["model_init"]
    estimator.rule_base_ = model_init["rule_base"]
    estimator.model_ = estimator._build_model(
        deserialize_input_mfs(model_init["input_mfs_config"]),
        int(model_init["n_classes"]),
        str(model_init["rule_base"]),
    )
    estimator.model_.load_state_dict(checkpoint["model_state_dict"])
    estimator.model_.to(torch.device(str(estimator.device)))

    fitted = checkpoint["fitted_attrs"]
    estimator.n_features_in_ = int(fitted["n_features_in"])
    estimator.feature_names_in_ = np.asarray(fitted["feature_names_in"], dtype=object)
    estimator.classes_ = np.asarray(fitted["classes"], dtype=object)
    label_encoder = LabelEncoder()
    label_encoder.classes_ = estimator.classes_
    estimator._label_encoder_ = label_encoder
    estimator.history_ = cast(dict[str, Any], checkpoint.get("history", {}))
    return estimator

`predict`

Predict class labels for input samples.

Source code in highfis/estimators/_base.py

def predict(self, x: Any) -> np.ndarray:
    """Predict class labels for input samples."""
    proba = self.predict_proba(x)
    y_idx = np.argmax(proba, axis=1)
    return np.asarray(self._label_encoder_.inverse_transform(y_idx))

`predict_proba`

Predict class probabilities for input samples.

Source code in highfis/estimators/_base.py

def predict_proba(self, x: Any) -> np.ndarray:
    """Predict class probabilities for input samples."""
    check_is_fitted(self, "model_")
    x_arr = check_array(x)
    if x_arr.shape[1] != self.n_features_in_:
        raise ValueError(f"expected {self.n_features_in_} features, got {x_arr.shape[1]}")
    probs = cast(Any, self.model_).predict_proba(self._as_tensor_x(x_arr, torch.device(str(self.device))))
    return probs.detach().cpu().numpy()

`rule_activation`

Return normalized rule activations for the provided inputs.

Source code in highfis/estimators/_base.py

def rule_activation(self, X: Any) -> np.ndarray:
    """Return normalized rule activations for the provided inputs."""
    check_is_fitted(self, "model_")
    x_arr = check_array(X)
    if x_arr.shape[1] != self.n_features_in_:
        raise ValueError(f"expected {self.n_features_in_} features, got {x_arr.shape[1]}")

    was_training = self.model_.training
    try:
        self.model_.eval()
        with torch.no_grad():
            norm_w = self.model_.forward_antecedents(self._as_tensor_x(x_arr, torch.device(str(self.device))))
    finally:
        self.model_.train(was_training)

    return _to_numpy(norm_w)

`save`

Persist estimator configuration, model weights and fitted metadata.

Source code in highfis/estimators/_base.py

def save(self, path: str) -> None:
    """Persist estimator configuration, model weights and fitted metadata."""
    checkpoint = self._build_checkpoint_base(
        model_init={
            "input_mfs_config": serialize_input_mfs(self.model_.input_mfs),
            "n_classes": len(self.classes_),
            "rule_base": self.rule_base_,
        },
        fitted_attrs={
            "n_features_in": int(self.n_features_in_),
            "feature_names_in": self.feature_names_in_.tolist(),
            "classes": self.classes_.tolist(),
        },
    )
    save_checkpoint(path, checkpoint)

`score`

Return classification accuracy on the provided dataset.

Source code in highfis/estimators/_base.py

def score(self, X: Any, y: Any, sample_weight: Any = None) -> float:
    """Return classification accuracy on the provided dataset."""
    y_true = np.asarray(y)
    y_pred = self.predict(X)
    return float(accuracy_score(y_true, y_pred, sample_weight=sample_weight))

`ADMTSKRegressor`

Bases: _BaseRegressorEstimator

ADMTSK regressor estimator with Composite GMF and adaptive Dombi lambda.

ADMTSK is an adaptive Dombi TSK fuzzy system designed for high-dimensional inference. It combines a Dombi T-norm antecedent with a positive lower-bound Composite Gaussian membership function (CGMF) and normalized first-order consequents.

Reference

G. Xue, L. Hu, J. Wang and S. Ablameyko, "ADMTSK: A High-Dimensional Takagi-Sugeno-Kang Fuzzy System Based on Adaptive Dombi T-Norm," in IEEE Transactions on Fuzzy Systems, vol. 33, no. 6, pp. 1767-1780, June 2025, doi: 10.1109/TFUZZ.2025.3535640.

Example

from highfis import ADMTSKRegressor

reg = ADMTSKRegressor()
reg.fit(X_train, y_train)

Initialize an ADMTSK regressor estimator.

Parameters:

Name	Type	Description	Default
`input_configs`	`list[InputConfig] \| None`	Optional list of per-feature input configurations.	`None`
`n_mfs`	`int`	Number of membership functions per input when using `mf_init="kmeans"`, `"minibatch_kmeans"`, or `"grid"`.	`5`
`mf_init`	`str`	Initialisation strategy for MFs: `"kmeans"` (default), `"minibatch_kmeans"`, `"fcm"`, or `"grid"`.	`'kmeans'`
`sigma_scale`	`float \| str`	Scale factor used to initialise Gaussian MF sigma values.	`1.0`
`random_state`	`int \| None`	Random seed for MF initialisation and weights.	`None`
`epochs`	`int`	Maximum number of training epochs.	`10`
`learning_rate`	`float`	Learning rate for the optimizer.	`0.01`
`verbose`	`bool \| int`	Verbosity level for training output.	`False`
`rule_base`	`str \| None`	Rule base strategy override, typically `"coco"` or `"cartesian"`.	`None`
`batch_size`	`int \| None`	Mini-batch size for training.	`512`
`shuffle`	`bool`	Whether to shuffle training data each epoch.	`True`
`ur_weight`	`float`	Uniform-rule regularisation weight.	`0.0`
`ur_target`	`float \| None`	Target average rule activation for uniform regularisation.	`None`
`consequent_batch_norm`	`bool`	If True, apply batch normalization to consequent inputs.	`False`
`patience`	`int \| None`	Early stopping patience. Use `None` to disable.	`20`
`restore_best`	`bool`	If True, restore the best validation weights.	`True`
`weight_decay`	`float`	Weight decay applied during training.	`1e-08`
`adaptive`	`bool`	If True, use adaptive lambda selection for Dombi T-norm.	`True`
`lambda_`	`float`	Fixed Dombi parameter when adaptive is False.	`1.0`
`lower_bound`	`float`	Lower bound used by Composite GMF.	`1.0 / math.e`
`k`	`float`	Heuristic constant used to compute adaptive lambda.	`10.0`

Raises:

Type	Description
`ValueError`	If estimator hyperparameters are invalid.

Source code in highfis/estimators/_dombi.py

def __init__(
    self,
    *,
    input_configs: list[InputConfig] | None = None,
    n_mfs: int = 5,
    mf_init: str = "kmeans",
    sigma_scale: float | str = 1.0,
    random_state: int | None = None,
    epochs: int = 10,
    learning_rate: float = 1e-2,
    verbose: bool | int = False,
    rule_base: str | None = None,
    batch_size: int | None = 512,
    shuffle: bool = True,
    ur_weight: float = 0.0,
    ur_target: float | None = None,
    consequent_batch_norm: bool = False,
    patience: int | None = 20,
    restore_best: bool = True,
    weight_decay: float = 1e-8,
    adaptive: bool = True,
    lambda_: float = 1.0,
    lower_bound: float = 1.0 / math.e,
    k: float = 10.0,
) -> None:
    """Initialize an ADMTSK regressor estimator.

    Args:
        input_configs: Optional list of per-feature input configurations.
        n_mfs: Number of membership functions per input when using
            ``mf_init="kmeans"``, ``"minibatch_kmeans"``, or ``"grid"``.
        mf_init: Initialisation strategy for MFs: ``"kmeans"`` (default),
            ``"minibatch_kmeans"``, ``"fcm"``, or ``"grid"``.
        sigma_scale: Scale factor used to initialise Gaussian MF sigma
            values.
        random_state: Random seed for MF initialisation and weights.
        epochs: Maximum number of training epochs.
        learning_rate: Learning rate for the optimizer.
        verbose: Verbosity level for training output.
        rule_base: Rule base strategy override, typically ``"coco"`` or
            ``"cartesian"``.
        batch_size: Mini-batch size for training.
        shuffle: Whether to shuffle training data each epoch.
        ur_weight: Uniform-rule regularisation weight.
        ur_target: Target average rule activation for uniform regularisation.
        consequent_batch_norm: If True, apply batch normalization to
            consequent inputs.
        patience: Early stopping patience. Use ``None`` to disable.
        restore_best: If True, restore the best validation weights.
        weight_decay: Weight decay applied during training.
        adaptive: If True, use adaptive lambda selection for Dombi T-norm.
        lambda_: Fixed Dombi parameter when adaptive is False.
        lower_bound: Lower bound used by Composite GMF.
        k: Heuristic constant used to compute adaptive lambda.

    Raises:
        ValueError: If estimator hyperparameters are invalid.
    """
    super().__init__(
        input_configs=input_configs,
        n_mfs=n_mfs,
        mf_init=mf_init,
        sigma_scale=sigma_scale,
        random_state=random_state,
        epochs=epochs,
        learning_rate=learning_rate,
        verbose=verbose,
        rule_base=rule_base,
        batch_size=batch_size,
        shuffle=shuffle,
        ur_weight=ur_weight,
        ur_target=ur_target,
        consequent_batch_norm=consequent_batch_norm,
        patience=patience,
        restore_best=restore_best,
        weight_decay=weight_decay,
    )
    self.adaptive = bool(adaptive)
    self.lambda_ = float(lambda_)
    self.lower_bound = float(lower_bound)
    self.k = float(k)

`evaluate`

Compute regression evaluation metrics for the provided dataset.

Source code in highfis/estimators/_base.py

def evaluate(
    self,
    X: Any,
    y: Any,
    metrics: list[str] | None = None,
    sample_weight: Any | None = None,
) -> dict[str, float]:
    """Compute regression evaluation metrics for the provided dataset."""
    y_true = np.asarray(y)
    y_pred = self.predict(X)
    return compute_metrics(
        task="regression",
        y_true=y_true,
        y_pred=y_pred,
        sample_weight=sample_weight,
        metrics=metrics,
    )

`feature_importance`

Compute a normalized feature importance vector from consequent weights.

Source code in highfis/estimators/_base.py

def feature_importance(self) -> np.ndarray | None:
    """Compute a normalized feature importance vector from consequent weights."""
    check_is_fitted(self, "model_")
    weights = self.model_.get_consequent_weights()
    if weights is None:
        return None

    consequent_layer = self.model_.consequent_layer
    if hasattr(consequent_layer, "rule_feature_mask"):
        rule_feature_mask = cast(Tensor, consequent_layer.rule_feature_mask)
        weights = weights * rule_feature_mask.unsqueeze(1) if weights.ndim == 3 else weights * rule_feature_mask

    abs_weights = weights.abs()
    if abs_weights.ndim == 3:
        importance = abs_weights.mean(dim=(0, 1))
    elif abs_weights.ndim == 2:
        importance = abs_weights.mean(dim=0)
    else:
        raise ValueError("unsupported consequent weight shape for feature importance")

    return _normalize_importance(importance)

`fit`

Train the TSK regressor on labeled samples.

Validation data should be supplied using x_val and y_val when available.

Source code in highfis/estimators/_base.py

def fit(
    self,
    x: Any,
    y: Any,
    *,
    x_val: Any | None = None,
    y_val: Any | None = None,
) -> Self:
    """Train the TSK regressor on labeled samples.

    Validation data should be supplied using ``x_val`` and ``y_val``
    when available.
    """
    x_arr, y_arr = check_X_y(x, y)

    if self.random_state is not None:
        torch.manual_seed(int(self.random_state))

    input_mfs, feature_names, effective_rule_base = self._build_input_mfs(x_arr)

    self.n_features_in_ = x_arr.shape[1]
    self.feature_names_in_ = np.asarray(feature_names, dtype=object)

    _device = torch.device(str(self.device))
    self.model_ = self._build_regressor_model(input_mfs, effective_rule_base).to(_device)

    y_t = torch.as_tensor(np.asarray(y_arr, dtype=np.float32), dtype=torch.float32, device=_device)

    # Prepare validation tensors if provided via fit.
    x_val_t: torch.Tensor | None = None
    y_val_t: torch.Tensor | None = None
    if (x_val is None) ^ (y_val is None):
        raise ValueError("x_val and y_val must be provided together")
    if x_val is not None and y_val is not None:
        x_v_arr, y_v_arr = check_X_y(x_val, y_val)
        x_val_t = self._as_tensor_x(x_v_arr, _device)
        y_val_t = torch.as_tensor(np.asarray(y_v_arr, dtype=np.float32), dtype=torch.float32, device=_device)

    self.history_ = self.model_.fit(
        self._as_tensor_x(x_arr, _device),
        y_t,
        epochs=int(self.epochs),
        learning_rate=float(self.learning_rate),
        batch_size=self.batch_size,
        shuffle=bool(self.shuffle),
        ur_weight=float(self.ur_weight),
        ur_target=self.ur_target,
        verbose=self.verbose,
        x_val=x_val_t,
        y_val=y_val_t,
        patience=self.patience,
        restore_best=self.restore_best,
        weight_decay=float(self.weight_decay),
    )
    self.rule_base_ = effective_rule_base
    return self

`get_mf_params`

Return model membership function metadata after fitting.

Source code in highfis/estimators/_base.py

def get_mf_params(self) -> dict[str, list[dict[str, Any]]]:
    """Return model membership function metadata after fitting."""
    check_is_fitted(self, "model_")
    return self.model_.get_mf_params()

`inspect`

Return a structured summary of fitted model state and rule metadata.

Source code in highfis/estimators/_base.py

def inspect(self) -> dict[str, Any]:
    """Return a structured summary of fitted model state and rule metadata."""
    check_is_fitted(self, "model_")
    return {
        "n_rules": int(self.model_.n_rules),
        "n_inputs": int(self.model_.n_inputs),
        "feature_names": list(self.model_.input_names),
        "rule_base": self.rule_base_,
        "defuzzifier_type": type(self.model_.defuzzifier).__name__,
        "mf_params": self.get_mf_params(),
        "rule_table": self.model_.get_rule_table(),
    }

`load` `classmethod`

Load a persisted estimator created by save.

Source code in highfis/estimators/_base.py

@classmethod
def load(cls, path: str) -> Self:
    """Load a persisted estimator created by save."""
    checkpoint = load_checkpoint(path)
    validate_checkpoint_payload(checkpoint, expected_estimator_class=cls.__name__)

    params: dict[str, Any] = dict(checkpoint["estimator_params"])
    if params.get("input_configs") is not None:
        params["input_configs"] = [InputConfig(**c) for c in params["input_configs"]]
    estimator = cls(**params)
    model_init = checkpoint["model_init"]
    estimator.rule_base_ = model_init["rule_base"]
    estimator.model_ = estimator._build_regressor_model(
        deserialize_input_mfs(model_init["input_mfs_config"]),
        str(model_init["rule_base"]),
    )
    estimator.model_.load_state_dict(checkpoint["model_state_dict"])
    estimator.model_.to(torch.device(str(estimator.device)))

    fitted = checkpoint["fitted_attrs"]
    estimator.n_features_in_ = int(fitted["n_features_in"])
    estimator.feature_names_in_ = np.asarray(fitted["feature_names_in"], dtype=object)
    estimator.history_ = cast(dict[str, Any], checkpoint.get("history", {}))
    return estimator

`predict`

Predict continuous target values for input samples.

Source code in highfis/estimators/_base.py

def predict(self, x: Any) -> np.ndarray:
    """Predict continuous target values for input samples."""
    check_is_fitted(self, "model_")
    x_arr = check_array(x)
    if x_arr.shape[1] != self.n_features_in_:
        raise ValueError(f"expected {self.n_features_in_} features, got {x_arr.shape[1]}")
    preds = cast(Any, self.model_).predict(self._as_tensor_x(x_arr, torch.device(str(self.device))))
    return preds.detach().cpu().numpy()

`rule_activation`

Return normalized rule activations for the provided inputs.

Source code in highfis/estimators/_base.py

def rule_activation(self, X: Any) -> np.ndarray:
    """Return normalized rule activations for the provided inputs."""
    check_is_fitted(self, "model_")
    x_arr = check_array(X)
    if x_arr.shape[1] != self.n_features_in_:
        raise ValueError(f"expected {self.n_features_in_} features, got {x_arr.shape[1]}")

    was_training = self.model_.training
    try:
        self.model_.eval()
        with torch.no_grad():
            norm_w = self.model_.forward_antecedents(self._as_tensor_x(x_arr, torch.device(str(self.device))))
    finally:
        self.model_.train(was_training)

    return _to_numpy(norm_w)

`save`

Persist estimator configuration, model weights and fitted metadata.

Source code in highfis/estimators/_base.py

def save(self, path: str) -> None:
    """Persist estimator configuration, model weights and fitted metadata."""
    checkpoint = self._build_checkpoint_base(
        model_init={
            "input_mfs_config": serialize_input_mfs(self.model_.input_mfs),
            "rule_base": self.rule_base_,
        },
        fitted_attrs={
            "n_features_in": int(self.n_features_in_),
            "feature_names_in": self.feature_names_in_.tolist(),
        },
    )
    save_checkpoint(path, checkpoint)

`ADPTSKClassifier`

Bases: _BaseClassifierEstimator

TSK classifier with ADP-softmin antecedent and Gaussian PIMF.

The firing strengths of each rule are computed with the ADP-softmin operator, and membership functions are wrapped as Gaussian PIMFs to preserve a positive infimum during high-dimensional training.

Reference

Ma, M., Qian, L., Zhang, Y., Fang, Q., & Xue, G. (2025). An adaptive double-parameter softmin based Takagi-Sugeno-Kang fuzzy system for high-dimensional data. Fuzzy Sets and Systems, 521, 109582. https://doi.org/10.1016/j.fss.2025.109582

Example

from highfis import ADPTSKClassifier

clf = ADPTSKClassifier()
clf.fit(X_train, y_train)

Initialise an ADPTSK classifier estimator.

Parameters:

Name	Type	Description	Default
`input_configs`	`list[InputConfig] \| None`	Optional list of :class:`InputConfig` instances, one per feature. Only `name` is used when `mf_init="kmeans"`.	`None`
`n_mfs`	`int`	Number of membership functions per feature or k-means clusters.	`3`
`mf_init`	`str`	Membership-function initialization strategy: `"kmeans"` (default), `"minibatch_kmeans"`, `"fcm"`, or `"grid"`.	`'kmeans'`
`sigma_scale`	`float \| str`	Scale factor for Gaussian MF sigma initialization.	`1.0`
`random_state`	`int \| None`	Seed for k-means and PyTorch weight initialization.	`None`
`epochs`	`int`	Maximum number of training epochs.	`10`
`learning_rate`	`float`	Initial learning rate for the Adam optimizer.	`0.01`
`verbose`	`bool \| int`	Verbosity level for training output.	`False`
`rule_base`	`str \| None`	Rule-base strategy, e.g. `"coco"` or `"cartesian"`.	`None`
`batch_size`	`int \| None`	Mini-batch size. `None` uses the full dataset.	`512`
`shuffle`	`bool`	Whether to shuffle training samples each epoch.	`True`
`ur_weight`	`float`	Uniform-rule regularization weight.	`0.0`
`ur_target`	`float \| None`	Target average rule activation for UR.	`None`
`consequent_batch_norm`	`bool`	Apply batch normalization to consequent linear layers.	`False`
`pfrb_max_rules`	`int \| None`	Maximum rules for point-based FRB when `rule_base="pfrb"`.	`None`
`patience`	`int \| None`	Early-stopping patience. `None` disables early stopping.	`20`
`restore_best`	`bool`	Restore the best validation model weights after training. stopping.	`True`
`weight_decay`	`float`	L2 weight decay coefficient for consequent parameters.	`1e-08`
`kappa`	`float`	ADPTSK `κ` parameter controlling the double-softmin geometry.	`690.0`
`xi`	`float`	ADPTSK `ξ` parameter controlling adaptive softmin sharpness.	`730.0`
`k`	`float`	Gaussian PIMF scaling constant used when wrapping the input MFs.	`1.0`
`eps`	`float \| None`	Optional lower bound for Gaussian PIMF values.	`None`

Source code in highfis/estimators/_adaptive.py

def __init__(
    self,
    *,
    input_configs: list[InputConfig] | None = None,
    n_mfs: int = 3,
    mf_init: str = "kmeans",
    sigma_scale: float | str = 1.0,
    random_state: int | None = None,
    epochs: int = 10,
    learning_rate: float = 1e-2,
    verbose: bool | int = False,
    rule_base: str | None = None,
    batch_size: int | None = 512,
    shuffle: bool = True,
    ur_weight: float = 0.0,
    ur_target: float | None = None,
    consequent_batch_norm: bool = False,
    pfrb_max_rules: int | None = None,
    patience: int | None = 20,
    restore_best: bool = True,
    weight_decay: float = 1e-8,
    kappa: float = 690.0,
    xi: float = 730.0,
    k: float = 1.0,
    eps: float | None = None,
) -> None:
    """Initialise an ADPTSK classifier estimator.

    Args:
        input_configs: Optional list of :class:`InputConfig` instances,
            one per feature. Only ``name`` is used when
            ``mf_init="kmeans"``.
        n_mfs: Number of membership functions per feature or k-means
            clusters.
        mf_init: Membership-function initialization strategy:
            ``"kmeans"`` (default), ``"minibatch_kmeans"``, ``"fcm"``,
            or ``"grid"``.
        sigma_scale: Scale factor for Gaussian MF sigma initialization.
        random_state: Seed for k-means and PyTorch weight initialization.
        epochs: Maximum number of training epochs.
        learning_rate: Initial learning rate for the Adam optimizer.
        verbose: Verbosity level for training output.
        rule_base: Rule-base strategy, e.g. ``"coco"`` or ``"cartesian"``.
        batch_size: Mini-batch size. ``None`` uses the full dataset.
        shuffle: Whether to shuffle training samples each epoch.
        ur_weight: Uniform-rule regularization weight.
        ur_target: Target average rule activation for UR.
        consequent_batch_norm: Apply batch normalization to consequent
            linear layers.
        pfrb_max_rules: Maximum rules for point-based FRB when
            ``rule_base="pfrb"``.
        patience: Early-stopping patience. ``None`` disables early stopping.
        restore_best: Restore the best validation model weights after
            training.
            stopping.
        weight_decay: L2 weight decay coefficient for consequent parameters.
        kappa: ADPTSK ``κ`` parameter controlling the double-softmin
            geometry.
        xi: ADPTSK ``ξ`` parameter controlling adaptive softmin sharpness.
        k: Gaussian PIMF scaling constant used when wrapping the input MFs.
        eps: Optional lower bound for Gaussian PIMF values.
    """
    super().__init__(
        input_configs=input_configs,
        n_mfs=n_mfs,
        mf_init=mf_init,
        sigma_scale=sigma_scale,
        random_state=random_state,
        epochs=epochs,
        learning_rate=learning_rate,
        verbose=verbose,
        rule_base=rule_base,
        batch_size=batch_size,
        shuffle=shuffle,
        ur_weight=ur_weight,
        ur_target=ur_target,
        consequent_batch_norm=consequent_batch_norm,
        pfrb_max_rules=pfrb_max_rules,
        patience=patience,
        restore_best=restore_best,
        weight_decay=weight_decay,
    )
    self.kappa = float(kappa)
    self.xi = float(xi)
    self.k = float(k)
    self.eps = eps

`evaluate`

Compute classification evaluation metrics for the provided dataset.

Source code in highfis/estimators/_base.py

def evaluate(
    self,
    X: Any,
    y: Any,
    metrics: list[str] | None = None,
    sample_weight: Any | None = None,
) -> dict[str, float]:
    """Compute classification evaluation metrics for the provided dataset."""
    y_true = np.asarray(y)
    y_pred = self.predict(X)
    return compute_metrics(
        task="classification",
        y_true=y_true,
        y_pred=y_pred,
        sample_weight=sample_weight,
        metrics=metrics,
    )

`feature_importance`

Compute a normalized feature importance vector from consequent weights.

Source code in highfis/estimators/_base.py

def feature_importance(self) -> np.ndarray | None:
    """Compute a normalized feature importance vector from consequent weights."""
    check_is_fitted(self, "model_")
    weights = self.model_.get_consequent_weights()
    if weights is None:
        return None

    consequent_layer = self.model_.consequent_layer
    if hasattr(consequent_layer, "rule_feature_mask"):
        rule_feature_mask = cast(Tensor, consequent_layer.rule_feature_mask)
        weights = weights * rule_feature_mask.unsqueeze(1) if weights.ndim == 3 else weights * rule_feature_mask

    abs_weights = weights.abs()
    if abs_weights.ndim == 3:
        importance = abs_weights.mean(dim=(0, 1))
    elif abs_weights.ndim == 2:
        importance = abs_weights.mean(dim=0)
    else:
        raise ValueError("unsupported consequent weight shape for feature importance")

    return _normalize_importance(importance)

`fit`

Train the TSK classifier on labeled samples.

Validation data should be supplied using x_val and y_val when available.

Source code in highfis/estimators/_base.py

def fit(
    self,
    x: Any,
    y: Any,
    *,
    x_val: Any | None = None,
    y_val: Any | None = None,
) -> Self:
    """Train the TSK classifier on labeled samples.

    Validation data should be supplied using ``x_val`` and ``y_val``
    when available.
    """
    x_arr, y_arr = check_X_y(x, y)

    if self.random_state is not None:
        torch.manual_seed(int(self.random_state))

    le = LabelEncoder()
    y_idx = le.fit_transform(np.asarray(y_arr))

    input_mfs, feature_names, effective_rule_base = self._build_input_mfs(x_arr)

    self.n_features_in_ = x_arr.shape[1]
    self.feature_names_in_ = np.asarray(feature_names, dtype=object)
    self.classes_ = le.classes_
    self._label_encoder_ = le

    _device = torch.device(str(self.device))
    self.model_ = self._build_model(input_mfs, len(self.classes_), effective_rule_base).to(_device)

    y_t = torch.as_tensor(y_idx, dtype=torch.long, device=_device)

    # Prepare validation tensors if provided via fit.
    x_val_t: torch.Tensor | None = None
    y_val_t: torch.Tensor | None = None
    if (x_val is None) ^ (y_val is None):
        raise ValueError("x_val and y_val must be provided together")
    if x_val is not None and y_val is not None:
        x_v_arr, y_v_arr = check_X_y(x_val, y_val)
        x_val_t = self._as_tensor_x(x_v_arr, _device)
        y_val_idx = le.transform(np.asarray(y_v_arr))
        y_val_t = torch.as_tensor(y_val_idx, dtype=torch.long, device=_device)

    self.history_ = self.model_.fit(
        self._as_tensor_x(x_arr, _device),
        y_t,
        epochs=int(self.epochs),
        learning_rate=float(self.learning_rate),
        batch_size=self.batch_size,
        shuffle=bool(self.shuffle),
        ur_weight=float(self.ur_weight),
        ur_target=self.ur_target,
        verbose=self.verbose,
        x_val=x_val_t,
        y_val=y_val_t,
        patience=self.patience,
        restore_best=self.restore_best,
        weight_decay=float(self.weight_decay),
    )
    self.rule_base_ = effective_rule_base
    return self

`get_mf_params`

Return model membership function metadata after fitting.

Source code in highfis/estimators/_base.py

def get_mf_params(self) -> dict[str, list[dict[str, Any]]]:
    """Return model membership function metadata after fitting."""
    check_is_fitted(self, "model_")
    return self.model_.get_mf_params()

`inspect`

Return a structured summary of fitted model state and rule metadata.

Source code in highfis/estimators/_base.py

def inspect(self) -> dict[str, Any]:
    """Return a structured summary of fitted model state and rule metadata."""
    check_is_fitted(self, "model_")
    return {
        "n_rules": int(self.model_.n_rules),
        "n_inputs": int(self.model_.n_inputs),
        "feature_names": list(self.model_.input_names),
        "rule_base": self.rule_base_,
        "defuzzifier_type": type(self.model_.defuzzifier).__name__,
        "mf_params": self.get_mf_params(),
        "rule_table": self.model_.get_rule_table(),
    }

`load` `classmethod`

Load a persisted estimator created by save.

Source code in highfis/estimators/_base.py

@classmethod
def load(cls, path: str) -> Self:
    """Load a persisted estimator created by save."""
    checkpoint = load_checkpoint(path)
    validate_checkpoint_payload(checkpoint, expected_estimator_class=cls.__name__)

    params: dict[str, Any] = dict(checkpoint["estimator_params"])
    if params.get("input_configs") is not None:
        params["input_configs"] = [InputConfig(**c) for c in params["input_configs"]]
    estimator = cls(**params)
    model_init = checkpoint["model_init"]
    estimator.rule_base_ = model_init["rule_base"]
    estimator.model_ = estimator._build_model(
        deserialize_input_mfs(model_init["input_mfs_config"]),
        int(model_init["n_classes"]),
        str(model_init["rule_base"]),
    )
    estimator.model_.load_state_dict(checkpoint["model_state_dict"])
    estimator.model_.to(torch.device(str(estimator.device)))

    fitted = checkpoint["fitted_attrs"]
    estimator.n_features_in_ = int(fitted["n_features_in"])
    estimator.feature_names_in_ = np.asarray(fitted["feature_names_in"], dtype=object)
    estimator.classes_ = np.asarray(fitted["classes"], dtype=object)
    label_encoder = LabelEncoder()
    label_encoder.classes_ = estimator.classes_
    estimator._label_encoder_ = label_encoder
    estimator.history_ = cast(dict[str, Any], checkpoint.get("history", {}))
    return estimator

`predict`

Predict class labels for input samples.

Source code in highfis/estimators/_base.py

def predict(self, x: Any) -> np.ndarray:
    """Predict class labels for input samples."""
    proba = self.predict_proba(x)
    y_idx = np.argmax(proba, axis=1)
    return np.asarray(self._label_encoder_.inverse_transform(y_idx))

`predict_proba`

Predict class probabilities for input samples.

Source code in highfis/estimators/_base.py

def predict_proba(self, x: Any) -> np.ndarray:
    """Predict class probabilities for input samples."""
    check_is_fitted(self, "model_")
    x_arr = check_array(x)
    if x_arr.shape[1] != self.n_features_in_:
        raise ValueError(f"expected {self.n_features_in_} features, got {x_arr.shape[1]}")
    probs = cast(Any, self.model_).predict_proba(self._as_tensor_x(x_arr, torch.device(str(self.device))))
    return probs.detach().cpu().numpy()

`rule_activation`

Return normalized rule activations for the provided inputs.

Source code in highfis/estimators/_base.py

def rule_activation(self, X: Any) -> np.ndarray:
    """Return normalized rule activations for the provided inputs."""
    check_is_fitted(self, "model_")
    x_arr = check_array(X)
    if x_arr.shape[1] != self.n_features_in_:
        raise ValueError(f"expected {self.n_features_in_} features, got {x_arr.shape[1]}")

    was_training = self.model_.training
    try:
        self.model_.eval()
        with torch.no_grad():
            norm_w = self.model_.forward_antecedents(self._as_tensor_x(x_arr, torch.device(str(self.device))))
    finally:
        self.model_.train(was_training)

    return _to_numpy(norm_w)

`save`

Persist estimator configuration, model weights and fitted metadata.

Source code in highfis/estimators/_base.py

def save(self, path: str) -> None:
    """Persist estimator configuration, model weights and fitted metadata."""
    checkpoint = self._build_checkpoint_base(
        model_init={
            "input_mfs_config": serialize_input_mfs(self.model_.input_mfs),
            "n_classes": len(self.classes_),
            "rule_base": self.rule_base_,
        },
        fitted_attrs={
            "n_features_in": int(self.n_features_in_),
            "feature_names_in": self.feature_names_in_.tolist(),
            "classes": self.classes_.tolist(),
        },
    )
    save_checkpoint(path, checkpoint)

`score`

Return classification accuracy on the provided dataset.

Source code in highfis/estimators/_base.py

def score(self, X: Any, y: Any, sample_weight: Any = None) -> float:
    """Return classification accuracy on the provided dataset."""
    y_true = np.asarray(y)
    y_pred = self.predict(X)
    return float(accuracy_score(y_true, y_pred, sample_weight=sample_weight))

`ADPTSKRegressor`

Bases: _BaseRegressorEstimator

TSK regressor with ADP-softmin antecedent and Gaussian PIMF.

The firing strengths of each rule are computed with the ADP-softmin operator, and membership functions are wrapped as Gaussian PIMFs to preserve a positive infimum during high-dimensional training.

Reference

Ma, M., Qian, L., Zhang, Y., Fang, Q., & Xue, G. (2025). An adaptive double-parameter softmin based Takagi-Sugeno-Kang fuzzy system for high-dimensional data. Fuzzy Sets and Systems, 521, 109582. https://doi.org/10.1016/j.fss.2025.109582

Example

from highfis import ADPTSKRegressor

reg = ADPTSKRegressor()
reg.fit(X_train, y_train)

Initialise an ADPTSK regressor estimator.

Parameters:

Name	Type	Description	Default
`input_configs`	`list[InputConfig] \| None`	Optional list of :class:`InputConfig` instances, one per feature. Only `name` is used when `mf_init="kmeans"`.	`None`
`n_mfs`	`int`	Number of membership functions per feature or k-means clusters.	`3`
`mf_init`	`str`	Membership-function initialization strategy: `"kmeans"` (default), `"minibatch_kmeans"`, `"fcm"`, or `"grid"`.	`'kmeans'`
`sigma_scale`	`float \| str`	Scale factor for Gaussian MF sigma initialization.	`1.0`
`random_state`	`int \| None`	Seed for k-means and PyTorch weight initialization.	`None`
`epochs`	`int`	Maximum number of training epochs.	`10`
`learning_rate`	`float`	Initial learning rate for the Adam optimizer.	`0.01`
`verbose`	`bool \| int`	Verbosity level for training output.	`False`
`rule_base`	`str \| None`	Rule-base strategy, e.g. `"coco"` or `"cartesian"`.	`None`
`batch_size`	`int \| None`	Mini-batch size. `None` uses the full dataset.	`512`
`shuffle`	`bool`	Whether to shuffle training samples each epoch.	`True`
`ur_weight`	`float`	Uniform-rule regularization weight.	`0.0`
`ur_target`	`float \| None`	Target average rule activation for UR.	`None`
`consequent_batch_norm`	`bool`	Apply batch normalization to consequent linear layers.	`False`
`pfrb_max_rules`	`int \| None`	Maximum rules for point-based FRB when `rule_base="pfrb"`.	`None`
`patience`	`int \| None`	Early-stopping patience. `None` disables early stopping.	`20`
`restore_best`	`bool`	Restore the best validation model weights after training. stopping.	`True`
`weight_decay`	`float`	L2 weight decay coefficient for consequent parameters.	`1e-08`
`kappa`	`float`	ADPTSK `κ` parameter controlling the double-softmin geometry.	`690.0`
`xi`	`float`	ADPTSK `ξ` parameter controlling adaptive softmin sharpness.	`730.0`
`k`	`float`	Gaussian PIMF scaling constant used when wrapping the input MFs.	`1.0`
`eps`	`float \| None`	Optional lower bound for Gaussian PIMF values.	`None`

Source code in highfis/estimators/_adaptive.py

def __init__(
    self,
    *,
    input_configs: list[InputConfig] | None = None,
    n_mfs: int = 3,
    mf_init: str = "kmeans",
    sigma_scale: float | str = 1.0,
    random_state: int | None = None,
    epochs: int = 10,
    learning_rate: float = 1e-2,
    verbose: bool | int = False,
    rule_base: str | None = None,
    batch_size: int | None = 512,
    shuffle: bool = True,
    ur_weight: float = 0.0,
    ur_target: float | None = None,
    consequent_batch_norm: bool = False,
    pfrb_max_rules: int | None = None,
    patience: int | None = 20,
    restore_best: bool = True,
    weight_decay: float = 1e-8,
    kappa: float = 690.0,
    xi: float = 730.0,
    k: float = 1.0,
    eps: float | None = None,
) -> None:
    """Initialise an ADPTSK regressor estimator.

    Args:
        input_configs: Optional list of :class:`InputConfig` instances,
            one per feature. Only ``name`` is used when
            ``mf_init="kmeans"``.
        n_mfs: Number of membership functions per feature or k-means
            clusters.
        mf_init: Membership-function initialization strategy:
            ``"kmeans"`` (default), ``"minibatch_kmeans"``, ``"fcm"``,
            or ``"grid"``.
        sigma_scale: Scale factor for Gaussian MF sigma initialization.
        random_state: Seed for k-means and PyTorch weight initialization.
        epochs: Maximum number of training epochs.
        learning_rate: Initial learning rate for the Adam optimizer.
        verbose: Verbosity level for training output.
        rule_base: Rule-base strategy, e.g. ``"coco"`` or ``"cartesian"``.
        batch_size: Mini-batch size. ``None`` uses the full dataset.
        shuffle: Whether to shuffle training samples each epoch.
        ur_weight: Uniform-rule regularization weight.
        ur_target: Target average rule activation for UR.
        consequent_batch_norm: Apply batch normalization to consequent
            linear layers.
        pfrb_max_rules: Maximum rules for point-based FRB when
            ``rule_base="pfrb"``.
        patience: Early-stopping patience. ``None`` disables early stopping.
        restore_best: Restore the best validation model weights after
            training.
            stopping.
        weight_decay: L2 weight decay coefficient for consequent parameters.
        kappa: ADPTSK ``κ`` parameter controlling the double-softmin
            geometry.
        xi: ADPTSK ``ξ`` parameter controlling adaptive softmin sharpness.
        k: Gaussian PIMF scaling constant used when wrapping the input MFs.
        eps: Optional lower bound for Gaussian PIMF values.
    """
    super().__init__(
        input_configs=input_configs,
        n_mfs=n_mfs,
        mf_init=mf_init,
        sigma_scale=sigma_scale,
        random_state=random_state,
        epochs=epochs,
        learning_rate=learning_rate,
        verbose=verbose,
        rule_base=rule_base,
        batch_size=batch_size,
        shuffle=shuffle,
        ur_weight=ur_weight,
        ur_target=ur_target,
        consequent_batch_norm=consequent_batch_norm,
        pfrb_max_rules=pfrb_max_rules,
        patience=patience,
        restore_best=restore_best,
        weight_decay=weight_decay,
    )
    self.kappa = float(kappa)
    self.xi = float(xi)
    self.k = float(k)
    self.eps = eps

`evaluate`

Compute regression evaluation metrics for the provided dataset.

Source code in highfis/estimators/_base.py

def evaluate(
    self,
    X: Any,
    y: Any,
    metrics: list[str] | None = None,
    sample_weight: Any | None = None,
) -> dict[str, float]:
    """Compute regression evaluation metrics for the provided dataset."""
    y_true = np.asarray(y)
    y_pred = self.predict(X)
    return compute_metrics(
        task="regression",
        y_true=y_true,
        y_pred=y_pred,
        sample_weight=sample_weight,
        metrics=metrics,
    )

`feature_importance`

Compute a normalized feature importance vector from consequent weights.

Source code in highfis/estimators/_base.py

def feature_importance(self) -> np.ndarray | None:
    """Compute a normalized feature importance vector from consequent weights."""
    check_is_fitted(self, "model_")
    weights = self.model_.get_consequent_weights()
    if weights is None:
        return None

    consequent_layer = self.model_.consequent_layer
    if hasattr(consequent_layer, "rule_feature_mask"):
        rule_feature_mask = cast(Tensor, consequent_layer.rule_feature_mask)
        weights = weights * rule_feature_mask.unsqueeze(1) if weights.ndim == 3 else weights * rule_feature_mask

    abs_weights = weights.abs()
    if abs_weights.ndim == 3:
        importance = abs_weights.mean(dim=(0, 1))
    elif abs_weights.ndim == 2:
        importance = abs_weights.mean(dim=0)
    else:
        raise ValueError("unsupported consequent weight shape for feature importance")

    return _normalize_importance(importance)

`fit`

Train the TSK regressor on labeled samples.

Validation data should be supplied using x_val and y_val when available.

Source code in highfis/estimators/_base.py

def fit(
    self,
    x: Any,
    y: Any,
    *,
    x_val: Any | None = None,
    y_val: Any | None = None,
) -> Self:
    """Train the TSK regressor on labeled samples.

    Validation data should be supplied using ``x_val`` and ``y_val``
    when available.
    """
    x_arr, y_arr = check_X_y(x, y)

    if self.random_state is not None:
        torch.manual_seed(int(self.random_state))

    input_mfs, feature_names, effective_rule_base = self._build_input_mfs(x_arr)

    self.n_features_in_ = x_arr.shape[1]
    self.feature_names_in_ = np.asarray(feature_names, dtype=object)

    _device = torch.device(str(self.device))
    self.model_ = self._build_regressor_model(input_mfs, effective_rule_base).to(_device)

    y_t = torch.as_tensor(np.asarray(y_arr, dtype=np.float32), dtype=torch.float32, device=_device)

    # Prepare validation tensors if provided via fit.
    x_val_t: torch.Tensor | None = None
    y_val_t: torch.Tensor | None = None
    if (x_val is None) ^ (y_val is None):
        raise ValueError("x_val and y_val must be provided together")
    if x_val is not None and y_val is not None:
        x_v_arr, y_v_arr = check_X_y(x_val, y_val)
        x_val_t = self._as_tensor_x(x_v_arr, _device)
        y_val_t = torch.as_tensor(np.asarray(y_v_arr, dtype=np.float32), dtype=torch.float32, device=_device)

    self.history_ = self.model_.fit(
        self._as_tensor_x(x_arr, _device),
        y_t,
        epochs=int(self.epochs),
        learning_rate=float(self.learning_rate),
        batch_size=self.batch_size,
        shuffle=bool(self.shuffle),
        ur_weight=float(self.ur_weight),
        ur_target=self.ur_target,
        verbose=self.verbose,
        x_val=x_val_t,
        y_val=y_val_t,
        patience=self.patience,
        restore_best=self.restore_best,
        weight_decay=float(self.weight_decay),
    )
    self.rule_base_ = effective_rule_base
    return self

`get_mf_params`

Return model membership function metadata after fitting.

Source code in highfis/estimators/_base.py

def get_mf_params(self) -> dict[str, list[dict[str, Any]]]:
    """Return model membership function metadata after fitting."""
    check_is_fitted(self, "model_")
    return self.model_.get_mf_params()

`inspect`

Return a structured summary of fitted model state and rule metadata.

Source code in highfis/estimators/_base.py

def inspect(self) -> dict[str, Any]:
    """Return a structured summary of fitted model state and rule metadata."""
    check_is_fitted(self, "model_")
    return {
        "n_rules": int(self.model_.n_rules),
        "n_inputs": int(self.model_.n_inputs),
        "feature_names": list(self.model_.input_names),
        "rule_base": self.rule_base_,
        "defuzzifier_type": type(self.model_.defuzzifier).__name__,
        "mf_params": self.get_mf_params(),
        "rule_table": self.model_.get_rule_table(),
    }

`load` `classmethod`

Load a persisted estimator created by save.

Source code in highfis/estimators/_base.py

@classmethod
def load(cls, path: str) -> Self:
    """Load a persisted estimator created by save."""
    checkpoint = load_checkpoint(path)
    validate_checkpoint_payload(checkpoint, expected_estimator_class=cls.__name__)

    params: dict[str, Any] = dict(checkpoint["estimator_params"])
    if params.get("input_configs") is not None:
        params["input_configs"] = [InputConfig(**c) for c in params["input_configs"]]
    estimator = cls(**params)
    model_init = checkpoint["model_init"]
    estimator.rule_base_ = model_init["rule_base"]
    estimator.model_ = estimator._build_regressor_model(
        deserialize_input_mfs(model_init["input_mfs_config"]),
        str(model_init["rule_base"]),
    )
    estimator.model_.load_state_dict(checkpoint["model_state_dict"])
    estimator.model_.to(torch.device(str(estimator.device)))

    fitted = checkpoint["fitted_attrs"]
    estimator.n_features_in_ = int(fitted["n_features_in"])
    estimator.feature_names_in_ = np.asarray(fitted["feature_names_in"], dtype=object)
    estimator.history_ = cast(dict[str, Any], checkpoint.get("history", {}))
    return estimator

`predict`

Predict continuous target values for input samples.

Source code in highfis/estimators/_base.py

def predict(self, x: Any) -> np.ndarray:
    """Predict continuous target values for input samples."""
    check_is_fitted(self, "model_")
    x_arr = check_array(x)
    if x_arr.shape[1] != self.n_features_in_:
        raise ValueError(f"expected {self.n_features_in_} features, got {x_arr.shape[1]}")
    preds = cast(Any, self.model_).predict(self._as_tensor_x(x_arr, torch.device(str(self.device))))
    return preds.detach().cpu().numpy()

`rule_activation`

Return normalized rule activations for the provided inputs.

Source code in highfis/estimators/_base.py

def rule_activation(self, X: Any) -> np.ndarray:
    """Return normalized rule activations for the provided inputs."""
    check_is_fitted(self, "model_")
    x_arr = check_array(X)
    if x_arr.shape[1] != self.n_features_in_:
        raise ValueError(f"expected {self.n_features_in_} features, got {x_arr.shape[1]}")

    was_training = self.model_.training
    try:
        self.model_.eval()
        with torch.no_grad():
            norm_w = self.model_.forward_antecedents(self._as_tensor_x(x_arr, torch.device(str(self.device))))
    finally:
        self.model_.train(was_training)

    return _to_numpy(norm_w)

`save`

Persist estimator configuration, model weights and fitted metadata.

Source code in highfis/estimators/_base.py

def save(self, path: str) -> None:
    """Persist estimator configuration, model weights and fitted metadata."""
    checkpoint = self._build_checkpoint_base(
        model_init={
            "input_mfs_config": serialize_input_mfs(self.model_.input_mfs),
            "rule_base": self.rule_base_,
        },
        fitted_attrs={
            "n_features_in": int(self.n_features_in_),
            "feature_names_in": self.feature_names_in_.tolist(),
        },
    )
    save_checkpoint(path, checkpoint)

`AYATSKClassifier`

Bases: _BaseClassifierEstimator

TSK classifier with an adaptive Yager T-norm in the antecedent.

AYATSK extends TSK by using an adaptive Yager T-norm aggregation and optional positive lower-bound membership functions to improve stability and performance in high-dimensional settings.

Reference

G. Xue, Y. Yang and J. Wang, "Adaptive Yager T-Norm-Based Takagi-Sugeno-Kang Fuzzy Systems," in IEEE Transactions on Systems, Man, and Cybernetics: Systems, vol. 55, no. 12, pp. 9802-9815, Dec. 2025, doi: 10.1109/TSMC.2025.3621346.

Example

from highfis import AYATSKClassifier

clf = AYATSKClassifier(n_mfs=30, random_state=0)
clf.fit(X_train, y_train)

Initialise an AYATSK classifier.

Parameters:

Name	Type	Description	Default
`input_configs`	`list[InputConfig] \| None`	Per-feature :class:`InputConfig` list. Only `name` is used when `mf_init="kmeans"`.	`None`
`n_mfs`	`int`	Number of k-means clusters / grid MFs (default `5`).	`5`
`mf_init`	`str`	`"kmeans"` (default), `"minibatch_kmeans"`, `"fcm"`, or `"grid"`.	`'kmeans'`
`sigma_scale`	`float \| str`	Sigma scale factor for k-means initialisation. `1.0` is recommended; the adaptive Yager T-norm handles high-dimensional stability internally.	`1.0`
`random_state`	`int \| None`	Seed for k-means and weight initialisation.	`None`
`epochs`	`int`	Maximum training epochs (default `10`).	`10`
`learning_rate`	`float`	Adam learning rate (default `0.01`).	`0.01`
`verbose`	`bool \| int`	Print per-epoch progress.	`False`
`rule_base`	`str \| None`	`"coco"` or `"cartesian"`. Defaults to `"coco"` for kmeans and `"cartesian"` for grid.	`None`
`batch_size`	`int \| None`	Mini-batch size (default `512`).	`512`
`shuffle`	`bool`	Reshuffle each epoch.	`True`
`ur_weight`	`float`	Uncertainty regularisation weight.	`0.0`
`ur_target`	`float \| None`	Uncertainty regularisation target.	`None`
`consequent_batch_norm`	`bool`	Batch normalisation on consequent layers.	`False`
`pfrb_max_rules`	`int \| None`	Maximum point-based FRB rules (unused by AYATSK).	`None`
`patience`	`int \| None`	Early-stopping patience (default `20`). Set to `None` to disable early stopping.	`20`
`restore_best`	`bool`	If `True` (default), restore the best validation model weights after training.	`True`
`weight_decay`	`float`	L2 weight decay for consequent parameters.	`1e-08`

Source code in highfis/estimators/_yager.py

def __init__(
    self,
    *,
    input_configs: list[InputConfig] | None = None,
    n_mfs: int = 5,
    mf_init: str = "kmeans",
    sigma_scale: float | str = 1.0,
    random_state: int | None = None,
    epochs: int = 10,
    learning_rate: float = 1e-2,
    verbose: bool | int = False,
    rule_base: str | None = None,
    batch_size: int | None = 512,
    shuffle: bool = True,
    ur_weight: float = 0.0,
    ur_target: float | None = None,
    consequent_batch_norm: bool = False,
    pfrb_max_rules: int | None = None,
    patience: int | None = 20,
    restore_best: bool = True,
    weight_decay: float = 1e-8,
) -> None:
    """Initialise an AYATSK classifier.

    Args:
        input_configs: Per-feature :class:`InputConfig` list. Only
            ``name`` is used when ``mf_init="kmeans"``.
        n_mfs: Number of k-means clusters / grid MFs (default ``5``).
        mf_init: ``"kmeans"`` (default), ``"minibatch_kmeans"``, ``"fcm"``, or ``"grid"``.
        sigma_scale: Sigma scale factor for k-means initialisation.
            ``1.0`` is recommended; the adaptive Yager T-norm handles
            high-dimensional stability internally.
        random_state: Seed for k-means and weight initialisation.
        epochs: Maximum training epochs (default ``10``).
        learning_rate: Adam learning rate (default ``0.01``).
        verbose: Print per-epoch progress.
        rule_base: ``"coco"`` or ``"cartesian"``. Defaults to
            ``"coco"`` for kmeans and ``"cartesian"`` for grid.
        batch_size: Mini-batch size (default ``512``).
        shuffle: Reshuffle each epoch.
        ur_weight: Uncertainty regularisation weight.
        ur_target: Uncertainty regularisation target.
        consequent_batch_norm: Batch normalisation on consequent layers.
        pfrb_max_rules: Maximum point-based FRB rules (unused by
            AYATSK).
        patience: Early-stopping patience (default ``20``). Set to ``None`` to disable early stopping.
        restore_best: If ``True`` (default), restore the best validation
            model weights after training.
        weight_decay: L2 weight decay for consequent parameters.
    """
    super().__init__(
        input_configs=input_configs,
        n_mfs=n_mfs,
        mf_init=mf_init,
        sigma_scale=sigma_scale,
        random_state=random_state,
        epochs=epochs,
        learning_rate=learning_rate,
        verbose=verbose,
        rule_base=rule_base,
        batch_size=batch_size,
        shuffle=shuffle,
        ur_weight=ur_weight,
        ur_target=ur_target,
        consequent_batch_norm=consequent_batch_norm,
        pfrb_max_rules=pfrb_max_rules,
        patience=patience,
        restore_best=restore_best,
        weight_decay=weight_decay,
    )

`evaluate`

Compute classification evaluation metrics for the provided dataset.

Source code in highfis/estimators/_base.py

def evaluate(
    self,
    X: Any,
    y: Any,
    metrics: list[str] | None = None,
    sample_weight: Any | None = None,
) -> dict[str, float]:
    """Compute classification evaluation metrics for the provided dataset."""
    y_true = np.asarray(y)
    y_pred = self.predict(X)
    return compute_metrics(
        task="classification",
        y_true=y_true,
        y_pred=y_pred,
        sample_weight=sample_weight,
        metrics=metrics,
    )

`feature_importance`

Compute a normalized feature importance vector from consequent weights.

Source code in highfis/estimators/_base.py

def feature_importance(self) -> np.ndarray | None:
    """Compute a normalized feature importance vector from consequent weights."""
    check_is_fitted(self, "model_")
    weights = self.model_.get_consequent_weights()
    if weights is None:
        return None

    consequent_layer = self.model_.consequent_layer
    if hasattr(consequent_layer, "rule_feature_mask"):
        rule_feature_mask = cast(Tensor, consequent_layer.rule_feature_mask)
        weights = weights * rule_feature_mask.unsqueeze(1) if weights.ndim == 3 else weights * rule_feature_mask

    abs_weights = weights.abs()
    if abs_weights.ndim == 3:
        importance = abs_weights.mean(dim=(0, 1))
    elif abs_weights.ndim == 2:
        importance = abs_weights.mean(dim=0)
    else:
        raise ValueError("unsupported consequent weight shape for feature importance")

    return _normalize_importance(importance)

`fit`

Train the TSK classifier on labeled samples.

Validation data should be supplied using x_val and y_val when available.

Source code in highfis/estimators/_base.py

def fit(
    self,
    x: Any,
    y: Any,
    *,
    x_val: Any | None = None,
    y_val: Any | None = None,
) -> Self:
    """Train the TSK classifier on labeled samples.

    Validation data should be supplied using ``x_val`` and ``y_val``
    when available.
    """
    x_arr, y_arr = check_X_y(x, y)

    if self.random_state is not None:
        torch.manual_seed(int(self.random_state))

    le = LabelEncoder()
    y_idx = le.fit_transform(np.asarray(y_arr))

    input_mfs, feature_names, effective_rule_base = self._build_input_mfs(x_arr)

    self.n_features_in_ = x_arr.shape[1]
    self.feature_names_in_ = np.asarray(feature_names, dtype=object)
    self.classes_ = le.classes_
    self._label_encoder_ = le

    _device = torch.device(str(self.device))
    self.model_ = self._build_model(input_mfs, len(self.classes_), effective_rule_base).to(_device)

    y_t = torch.as_tensor(y_idx, dtype=torch.long, device=_device)

    # Prepare validation tensors if provided via fit.
    x_val_t: torch.Tensor | None = None
    y_val_t: torch.Tensor | None = None
    if (x_val is None) ^ (y_val is None):
        raise ValueError("x_val and y_val must be provided together")
    if x_val is not None and y_val is not None:
        x_v_arr, y_v_arr = check_X_y(x_val, y_val)
        x_val_t = self._as_tensor_x(x_v_arr, _device)
        y_val_idx = le.transform(np.asarray(y_v_arr))
        y_val_t = torch.as_tensor(y_val_idx, dtype=torch.long, device=_device)

    self.history_ = self.model_.fit(
        self._as_tensor_x(x_arr, _device),
        y_t,
        epochs=int(self.epochs),
        learning_rate=float(self.learning_rate),
        batch_size=self.batch_size,
        shuffle=bool(self.shuffle),
        ur_weight=float(self.ur_weight),
        ur_target=self.ur_target,
        verbose=self.verbose,
        x_val=x_val_t,
        y_val=y_val_t,
        patience=self.patience,
        restore_best=self.restore_best,
        weight_decay=float(self.weight_decay),
    )
    self.rule_base_ = effective_rule_base
    return self

`get_mf_params`

Return model membership function metadata after fitting.

Source code in highfis/estimators/_base.py

def get_mf_params(self) -> dict[str, list[dict[str, Any]]]:
    """Return model membership function metadata after fitting."""
    check_is_fitted(self, "model_")
    return self.model_.get_mf_params()

`inspect`

Return a structured summary of fitted model state and rule metadata.

Source code in highfis/estimators/_base.py

def inspect(self) -> dict[str, Any]:
    """Return a structured summary of fitted model state and rule metadata."""
    check_is_fitted(self, "model_")
    return {
        "n_rules": int(self.model_.n_rules),
        "n_inputs": int(self.model_.n_inputs),
        "feature_names": list(self.model_.input_names),
        "rule_base": self.rule_base_,
        "defuzzifier_type": type(self.model_.defuzzifier).__name__,
        "mf_params": self.get_mf_params(),
        "rule_table": self.model_.get_rule_table(),
    }

`load` `classmethod`

Load a persisted estimator created by save.

Source code in highfis/estimators/_base.py

@classmethod
def load(cls, path: str) -> Self:
    """Load a persisted estimator created by save."""
    checkpoint = load_checkpoint(path)
    validate_checkpoint_payload(checkpoint, expected_estimator_class=cls.__name__)

    params: dict[str, Any] = dict(checkpoint["estimator_params"])
    if params.get("input_configs") is not None:
        params["input_configs"] = [InputConfig(**c) for c in params["input_configs"]]
    estimator = cls(**params)
    model_init = checkpoint["model_init"]
    estimator.rule_base_ = model_init["rule_base"]
    estimator.model_ = estimator._build_model(
        deserialize_input_mfs(model_init["input_mfs_config"]),
        int(model_init["n_classes"]),
        str(model_init["rule_base"]),
    )
    estimator.model_.load_state_dict(checkpoint["model_state_dict"])
    estimator.model_.to(torch.device(str(estimator.device)))

    fitted = checkpoint["fitted_attrs"]
    estimator.n_features_in_ = int(fitted["n_features_in"])
    estimator.feature_names_in_ = np.asarray(fitted["feature_names_in"], dtype=object)
    estimator.classes_ = np.asarray(fitted["classes"], dtype=object)
    label_encoder = LabelEncoder()
    label_encoder.classes_ = estimator.classes_
    estimator._label_encoder_ = label_encoder
    estimator.history_ = cast(dict[str, Any], checkpoint.get("history", {}))
    return estimator

`predict`

Predict class labels for input samples.

Source code in highfis/estimators/_base.py

def predict(self, x: Any) -> np.ndarray:
    """Predict class labels for input samples."""
    proba = self.predict_proba(x)
    y_idx = np.argmax(proba, axis=1)
    return np.asarray(self._label_encoder_.inverse_transform(y_idx))

`predict_proba`

Predict class probabilities for input samples.

Source code in highfis/estimators/_base.py

def predict_proba(self, x: Any) -> np.ndarray:
    """Predict class probabilities for input samples."""
    check_is_fitted(self, "model_")
    x_arr = check_array(x)
    if x_arr.shape[1] != self.n_features_in_:
        raise ValueError(f"expected {self.n_features_in_} features, got {x_arr.shape[1]}")
    probs = cast(Any, self.model_).predict_proba(self._as_tensor_x(x_arr, torch.device(str(self.device))))
    return probs.detach().cpu().numpy()

`rule_activation`

Return normalized rule activations for the provided inputs.

Source code in highfis/estimators/_base.py

def rule_activation(self, X: Any) -> np.ndarray:
    """Return normalized rule activations for the provided inputs."""
    check_is_fitted(self, "model_")
    x_arr = check_array(X)
    if x_arr.shape[1] != self.n_features_in_:
        raise ValueError(f"expected {self.n_features_in_} features, got {x_arr.shape[1]}")

    was_training = self.model_.training
    try:
        self.model_.eval()
        with torch.no_grad():
            norm_w = self.model_.forward_antecedents(self._as_tensor_x(x_arr, torch.device(str(self.device))))
    finally:
        self.model_.train(was_training)

    return _to_numpy(norm_w)

`save`

Persist estimator configuration, model weights and fitted metadata.

Source code in highfis/estimators/_base.py

def save(self, path: str) -> None:
    """Persist estimator configuration, model weights and fitted metadata."""
    checkpoint = self._build_checkpoint_base(
        model_init={
            "input_mfs_config": serialize_input_mfs(self.model_.input_mfs),
            "n_classes": len(self.classes_),
            "rule_base": self.rule_base_,
        },
        fitted_attrs={
            "n_features_in": int(self.n_features_in_),
            "feature_names_in": self.feature_names_in_.tolist(),
            "classes": self.classes_.tolist(),
        },
    )
    save_checkpoint(path, checkpoint)

`score`

Return classification accuracy on the provided dataset.

Source code in highfis/estimators/_base.py

def score(self, X: Any, y: Any, sample_weight: Any = None) -> float:
    """Return classification accuracy on the provided dataset."""
    y_true = np.asarray(y)
    y_pred = self.predict(X)
    return float(accuracy_score(y_true, y_pred, sample_weight=sample_weight))

`AYATSKRegressor`

Bases: _BaseRegressorEstimator

TSK regressor with an adaptive Yager T-norm in the antecedent.

AYATSK extends TSK by using an adaptive Yager T-norm aggregation and optional positive lower-bound membership functions to improve stability and performance in high-dimensional settings.

Reference

G. Xue, Y. Yang and J. Wang, "Adaptive Yager T-Norm-Based Takagi-Sugeno-Kang Fuzzy Systems," in IEEE Transactions on Systems, Man, and Cybernetics: Systems, vol. 55, no. 12, pp. 9802-9815, Dec. 2025, doi: 10.1109/TSMC.2025.3621346.

Example

from highfis import AYATSKRegressor

reg = AYATSKRegressor(n_mfs=30, random_state=0)
reg.fit(X_train, y_train)

Initialise an AYATSK regressor.

Parameters:

Name	Type	Description	Default
`input_configs`	`list[InputConfig] \| None`	Per-feature :class:`InputConfig` list. Only `name` is used when `mf_init="kmeans"`.	`None`
`n_mfs`	`int`	Number of k-means clusters / grid MFs (default `5`).	`5`
`mf_init`	`str`	`"kmeans"` (default), `"minibatch_kmeans"`, `"fcm"`, or `"grid"`.	`'kmeans'`
`sigma_scale`	`float \| str`	Sigma scale factor. `1.0` recommended.	`1.0`
`random_state`	`int \| None`	Seed for k-means and weight initialisation.	`None`
`epochs`	`int`	Maximum training epochs (default `10`).	`10`
`learning_rate`	`float`	Adam learning rate (default `0.01`).	`0.01`
`verbose`	`bool \| int`	Print per-epoch progress.	`False`
`rule_base`	`str \| None`	`"coco"` or `"cartesian"`.	`None`
`batch_size`	`int \| None`	Mini-batch size (default `512`).	`512`
`shuffle`	`bool`	Reshuffle each epoch.	`True`
`ur_weight`	`float`	Uncertainty regularisation weight.	`0.0`
`ur_target`	`float \| None`	Uncertainty regularisation target.	`None`
`consequent_batch_norm`	`bool`	Batch normalisation on consequent layers.	`False`
`patience`	`int \| None`	Early-stopping patience (default `20`). Set to `None` to disable early stopping.	`20`
`restore_best`	`bool`	If `True` (default), restore the best validation model weights after training.	`True`
`weight_decay`	`float`	L2 weight decay for consequent parameters.	`1e-08`

Source code in highfis/estimators/_yager.py

def __init__(
    self,
    *,
    input_configs: list[InputConfig] | None = None,
    n_mfs: int = 5,
    mf_init: str = "kmeans",
    sigma_scale: float | str = 1.0,
    random_state: int | None = None,
    epochs: int = 10,
    learning_rate: float = 1e-2,
    verbose: bool | int = False,
    rule_base: str | None = None,
    batch_size: int | None = 512,
    shuffle: bool = True,
    ur_weight: float = 0.0,
    ur_target: float | None = None,
    consequent_batch_norm: bool = False,
    patience: int | None = 20,
    restore_best: bool = True,
    weight_decay: float = 1e-8,
) -> None:
    """Initialise an AYATSK regressor.

    Args:
        input_configs: Per-feature :class:`InputConfig` list. Only
            ``name`` is used when ``mf_init="kmeans"``.
        n_mfs: Number of k-means clusters / grid MFs (default ``5``).
        mf_init: ``"kmeans"`` (default), ``"minibatch_kmeans"``, ``"fcm"``, or ``"grid"``.
        sigma_scale: Sigma scale factor. ``1.0`` recommended.
        random_state: Seed for k-means and weight initialisation.
        epochs: Maximum training epochs (default ``10``).
        learning_rate: Adam learning rate (default ``0.01``).
        verbose: Print per-epoch progress.
        rule_base: ``"coco"`` or ``"cartesian"``.
        batch_size: Mini-batch size (default ``512``).
        shuffle: Reshuffle each epoch.
        ur_weight: Uncertainty regularisation weight.
        ur_target: Uncertainty regularisation target.
        consequent_batch_norm: Batch normalisation on consequent layers.
        patience: Early-stopping patience (default ``20``). Set to ``None`` to disable early stopping.
        restore_best: If ``True`` (default), restore the best validation
            model weights after training.
        weight_decay: L2 weight decay for consequent parameters.
    """
    super().__init__(
        input_configs=input_configs,
        n_mfs=n_mfs,
        mf_init=mf_init,
        sigma_scale=sigma_scale,
        random_state=random_state,
        epochs=epochs,
        learning_rate=learning_rate,
        verbose=verbose,
        rule_base=rule_base,
        batch_size=batch_size,
        shuffle=shuffle,
        ur_weight=ur_weight,
        ur_target=ur_target,
        consequent_batch_norm=consequent_batch_norm,
        patience=patience,
        restore_best=restore_best,
        weight_decay=weight_decay,
    )

`evaluate`

Compute regression evaluation metrics for the provided dataset.

Source code in highfis/estimators/_base.py

def evaluate(
    self,
    X: Any,
    y: Any,
    metrics: list[str] | None = None,
    sample_weight: Any | None = None,
) -> dict[str, float]:
    """Compute regression evaluation metrics for the provided dataset."""
    y_true = np.asarray(y)
    y_pred = self.predict(X)
    return compute_metrics(
        task="regression",
        y_true=y_true,
        y_pred=y_pred,
        sample_weight=sample_weight,
        metrics=metrics,
    )

`feature_importance`

Compute a normalized feature importance vector from consequent weights.

Source code in highfis/estimators/_base.py

def feature_importance(self) -> np.ndarray | None:
    """Compute a normalized feature importance vector from consequent weights."""
    check_is_fitted(self, "model_")
    weights = self.model_.get_consequent_weights()
    if weights is None:
        return None

    consequent_layer = self.model_.consequent_layer
    if hasattr(consequent_layer, "rule_feature_mask"):
        rule_feature_mask = cast(Tensor, consequent_layer.rule_feature_mask)
        weights = weights * rule_feature_mask.unsqueeze(1) if weights.ndim == 3 else weights * rule_feature_mask

    abs_weights = weights.abs()
    if abs_weights.ndim == 3:
        importance = abs_weights.mean(dim=(0, 1))
    elif abs_weights.ndim == 2:
        importance = abs_weights.mean(dim=0)
    else:
        raise ValueError("unsupported consequent weight shape for feature importance")

    return _normalize_importance(importance)

`fit`

Train the TSK regressor on labeled samples.

Validation data should be supplied using x_val and y_val when available.

Source code in highfis/estimators/_base.py

def fit(
    self,
    x: Any,
    y: Any,
    *,
    x_val: Any | None = None,
    y_val: Any | None = None,
) -> Self:
    """Train the TSK regressor on labeled samples.

    Validation data should be supplied using ``x_val`` and ``y_val``
    when available.
    """
    x_arr, y_arr = check_X_y(x, y)

    if self.random_state is not None:
        torch.manual_seed(int(self.random_state))

    input_mfs, feature_names, effective_rule_base = self._build_input_mfs(x_arr)

    self.n_features_in_ = x_arr.shape[1]
    self.feature_names_in_ = np.asarray(feature_names, dtype=object)

    _device = torch.device(str(self.device))
    self.model_ = self._build_regressor_model(input_mfs, effective_rule_base).to(_device)

    y_t = torch.as_tensor(np.asarray(y_arr, dtype=np.float32), dtype=torch.float32, device=_device)

    # Prepare validation tensors if provided via fit.
    x_val_t: torch.Tensor | None = None
    y_val_t: torch.Tensor | None = None
    if (x_val is None) ^ (y_val is None):
        raise ValueError("x_val and y_val must be provided together")
    if x_val is not None and y_val is not None:
        x_v_arr, y_v_arr = check_X_y(x_val, y_val)
        x_val_t = self._as_tensor_x(x_v_arr, _device)
        y_val_t = torch.as_tensor(np.asarray(y_v_arr, dtype=np.float32), dtype=torch.float32, device=_device)

    self.history_ = self.model_.fit(
        self._as_tensor_x(x_arr, _device),
        y_t,
        epochs=int(self.epochs),
        learning_rate=float(self.learning_rate),
        batch_size=self.batch_size,
        shuffle=bool(self.shuffle),
        ur_weight=float(self.ur_weight),
        ur_target=self.ur_target,
        verbose=self.verbose,
        x_val=x_val_t,
        y_val=y_val_t,
        patience=self.patience,
        restore_best=self.restore_best,
        weight_decay=float(self.weight_decay),
    )
    self.rule_base_ = effective_rule_base
    return self

`get_mf_params`

Return model membership function metadata after fitting.

Source code in highfis/estimators/_base.py

def get_mf_params(self) -> dict[str, list[dict[str, Any]]]:
    """Return model membership function metadata after fitting."""
    check_is_fitted(self, "model_")
    return self.model_.get_mf_params()

`inspect`

Return a structured summary of fitted model state and rule metadata.

Source code in highfis/estimators/_base.py

def inspect(self) -> dict[str, Any]:
    """Return a structured summary of fitted model state and rule metadata."""
    check_is_fitted(self, "model_")
    return {
        "n_rules": int(self.model_.n_rules),
        "n_inputs": int(self.model_.n_inputs),
        "feature_names": list(self.model_.input_names),
        "rule_base": self.rule_base_,
        "defuzzifier_type": type(self.model_.defuzzifier).__name__,
        "mf_params": self.get_mf_params(),
        "rule_table": self.model_.get_rule_table(),
    }

`load` `classmethod`

Load a persisted estimator created by save.

Source code in highfis/estimators/_base.py

@classmethod
def load(cls, path: str) -> Self:
    """Load a persisted estimator created by save."""
    checkpoint = load_checkpoint(path)
    validate_checkpoint_payload(checkpoint, expected_estimator_class=cls.__name__)

    params: dict[str, Any] = dict(checkpoint["estimator_params"])
    if params.get("input_configs") is not None:
        params["input_configs"] = [InputConfig(**c) for c in params["input_configs"]]
    estimator = cls(**params)
    model_init = checkpoint["model_init"]
    estimator.rule_base_ = model_init["rule_base"]
    estimator.model_ = estimator._build_regressor_model(
        deserialize_input_mfs(model_init["input_mfs_config"]),
        str(model_init["rule_base"]),
    )
    estimator.model_.load_state_dict(checkpoint["model_state_dict"])
    estimator.model_.to(torch.device(str(estimator.device)))

    fitted = checkpoint["fitted_attrs"]
    estimator.n_features_in_ = int(fitted["n_features_in"])
    estimator.feature_names_in_ = np.asarray(fitted["feature_names_in"], dtype=object)
    estimator.history_ = cast(dict[str, Any], checkpoint.get("history", {}))
    return estimator

`predict`

Predict continuous target values for input samples.

Source code in highfis/estimators/_base.py

def predict(self, x: Any) -> np.ndarray:
    """Predict continuous target values for input samples."""
    check_is_fitted(self, "model_")
    x_arr = check_array(x)
    if x_arr.shape[1] != self.n_features_in_:
        raise ValueError(f"expected {self.n_features_in_} features, got {x_arr.shape[1]}")
    preds = cast(Any, self.model_).predict(self._as_tensor_x(x_arr, torch.device(str(self.device))))
    return preds.detach().cpu().numpy()

`rule_activation`

Return normalized rule activations for the provided inputs.

Source code in highfis/estimators/_base.py

def rule_activation(self, X: Any) -> np.ndarray:
    """Return normalized rule activations for the provided inputs."""
    check_is_fitted(self, "model_")
    x_arr = check_array(X)
    if x_arr.shape[1] != self.n_features_in_:
        raise ValueError(f"expected {self.n_features_in_} features, got {x_arr.shape[1]}")

    was_training = self.model_.training
    try:
        self.model_.eval()
        with torch.no_grad():
            norm_w = self.model_.forward_antecedents(self._as_tensor_x(x_arr, torch.device(str(self.device))))
    finally:
        self.model_.train(was_training)

    return _to_numpy(norm_w)

`save`

Persist estimator configuration, model weights and fitted metadata.

Source code in highfis/estimators/_base.py

def save(self, path: str) -> None:
    """Persist estimator configuration, model weights and fitted metadata."""
    checkpoint = self._build_checkpoint_base(
        model_init={
            "input_mfs_config": serialize_input_mfs(self.model_.input_mfs),
            "rule_base": self.rule_base_,
        },
        fitted_attrs={
            "n_features_in": int(self.n_features_in_),
            "feature_names_in": self.feature_names_in_.tolist(),
        },
    )
    save_checkpoint(path, checkpoint)

`DGALETSKClassifier`

Bases: FSREADATSKClassifier

DG-ALETSK classifier with ALE-softmin antecedent and double-group gates.

DG-ALETSK extends FSRE-ADATSK by replacing the adaptive softmin with the Adaptive Ln-Exp (ALE) softmin — a smoother variant with improved numerical stability. It also uses a zero-order consequent in the DG (data-guided) training phase and optionally converts to first-order after gate-based pruning.

Reference

G. Xue, J. Wang, B. Yuan and C. Dai, "DG-ALETSK: A High-Dimensional Fuzzy Approach With Simultaneous Feature Selection and Rule Extraction," in IEEE Transactions on Fuzzy Systems, vol. 31, no. 11, pp. 3866-3880, Nov. 2023, doi: 10.1109/TFUZZ.2023.3270445.

Example

from highfis import DGALETSKClassifier

clf = DGALETSKClassifier(n_mfs=30, use_en_frb=False, random_state=0)
clf.fit(X_train, y_train)

Initialise an FSRE-ADATSK classifier.

Parameters:

Name	Type	Description	Default
`lambda_init`	`float`	Accepted for API compatibility but not used by FSRE-ADATSK or DG-ALETSK. FSRE-ADATSK computes its adaptive softmin index directly from membership values; DG-ALETSK uses the fixed exponent `ξ = 700` per paper eq. 22. Default `1.0`.	`1.0`
`use_en_frb`	`bool`	If `True`, use the Enhanced FRB (En-FRB) whose size grows linearly with the number of features, allowing more candidate rules for the RE phase. Xue et al. (2023) activate En-FRB after the FS phase; set `False` (default) to keep the compact CoCo-FRB.	`False`
`input_configs`	`list[InputConfig] \| None`	Per-feature :class:`InputConfig` list. Only `name` is used when `mf_init="kmeans"`.	`None`
`n_mfs`	`int`	Number of k-means clusters / grid MFs (default `5`).	`5`
`mf_init`	`str`	`"kmeans"` (default), `"minibatch_kmeans"`, `"fcm"`, or `"grid"`.	`'kmeans'`
`sigma_scale`	`float \| str`	Sigma scale factor. `1.0` recommended.	`1.0`
`random_state`	`int \| None`	Seed for k-means and weight initialisation.	`None`
`epochs`	`int`	Maximum training epochs (default `10`).	`10`
`learning_rate`	`float`	Adam learning rate (default `0.01`).	`0.01`
`verbose`	`bool \| int`	Print per-epoch progress.	`False`
`rule_base`	`str \| None`	`"coco"` or `"cartesian"`.	`None`
`batch_size`	`int \| None`	Mini-batch size (default `512`).	`512`
`shuffle`	`bool`	Reshuffle each epoch.	`True`
`ur_weight`	`float`	Uncertainty regularisation weight.	`0.0`
`ur_target`	`float \| None`	Uncertainty regularisation target.	`None`
`consequent_batch_norm`	`bool`	Batch normalisation on consequent layers.	`False`
`patience`	`int \| None`	Early-stopping patience (default `20`). Set to `None` to disable early stopping.	`20`
`restore_best`	`bool`	If `True` (default), restore the best validation model weights after training.	`True`
`weight_decay`	`float`	L2 weight decay for consequent parameters.	`1e-08`

Raises:

Type	Description
`ValueError`	If `lambda_init <= 0`.

Source code in highfis/estimators/_fsre.py

def __init__(
    self,
    *,
    lambda_init: float = 1.0,
    use_en_frb: bool = False,
    input_configs: list[InputConfig] | None = None,
    n_mfs: int = 5,
    mf_init: str = "kmeans",
    sigma_scale: float | str = 1.0,
    random_state: int | None = None,
    epochs: int = 10,
    learning_rate: float = 1e-2,
    verbose: bool | int = False,
    rule_base: str | None = None,
    batch_size: int | None = 512,
    shuffle: bool = True,
    ur_weight: float = 0.0,
    ur_target: float | None = None,
    consequent_batch_norm: bool = False,
    patience: int | None = 20,
    restore_best: bool = True,
    weight_decay: float = 1e-8,
) -> None:
    """Initialise an FSRE-ADATSK classifier.

    Args:
        lambda_init: Accepted for API compatibility but not used by
            FSRE-ADATSK or DG-ALETSK.  FSRE-ADATSK computes its
            adaptive softmin index directly from membership values;
            DG-ALETSK uses the fixed exponent ``ξ = 700`` per
            paper eq. 22.  Default ``1.0``.
        use_en_frb: If ``True``, use the Enhanced FRB (En-FRB) whose
            size grows linearly with the number of features, allowing
            more candidate rules for the RE phase. Xue et al. (2023)
            activate En-FRB after the FS phase; set ``False`` (default)
            to keep the compact CoCo-FRB.
        input_configs: Per-feature :class:`InputConfig` list. Only
            ``name`` is used when ``mf_init="kmeans"``.
        n_mfs: Number of k-means clusters / grid MFs (default ``5``).
        mf_init: ``"kmeans"`` (default), ``"minibatch_kmeans"``, ``"fcm"``, or ``"grid"``.
        sigma_scale: Sigma scale factor. ``1.0`` recommended.
        random_state: Seed for k-means and weight initialisation.
        epochs: Maximum training epochs (default ``10``).
        learning_rate: Adam learning rate (default ``0.01``).
        verbose: Print per-epoch progress.
        rule_base: ``"coco"`` or ``"cartesian"``.
        batch_size: Mini-batch size (default ``512``).
        shuffle: Reshuffle each epoch.
        ur_weight: Uncertainty regularisation weight.
        ur_target: Uncertainty regularisation target.
        consequent_batch_norm: Batch normalisation on consequent layers.
        patience: Early-stopping patience (default ``20``). Set to ``None`` to disable early stopping.
        restore_best: If ``True`` (default), restore the best validation
            model weights after training.
        weight_decay: L2 weight decay for consequent parameters.

    Raises:
        ValueError: If ``lambda_init <= 0``.
    """
    if lambda_init <= 0.0:
        raise ValueError("lambda_init must be > 0")
    self.lambda_init = float(lambda_init)
    self.use_en_frb = bool(use_en_frb)
    super().__init__(
        input_configs=input_configs,
        n_mfs=n_mfs,
        mf_init=mf_init,
        sigma_scale=sigma_scale,
        random_state=random_state,
        epochs=epochs,
        learning_rate=learning_rate,
        verbose=verbose,
        rule_base=rule_base,
        batch_size=batch_size,
        shuffle=shuffle,
        ur_weight=ur_weight,
        ur_target=ur_target,
        consequent_batch_norm=consequent_batch_norm,
        patience=patience,
        restore_best=restore_best,
        weight_decay=weight_decay,
    )

`evaluate`

Compute classification evaluation metrics for the provided dataset.

Source code in highfis/estimators/_base.py

def evaluate(
    self,
    X: Any,
    y: Any,
    metrics: list[str] | None = None,
    sample_weight: Any | None = None,
) -> dict[str, float]:
    """Compute classification evaluation metrics for the provided dataset."""
    y_true = np.asarray(y)
    y_pred = self.predict(X)
    return compute_metrics(
        task="classification",
        y_true=y_true,
        y_pred=y_pred,
        sample_weight=sample_weight,
        metrics=metrics,
    )

`feature_importance`

Compute a normalized feature importance vector from consequent weights.

Source code in highfis/estimators/_base.py

def feature_importance(self) -> np.ndarray | None:
    """Compute a normalized feature importance vector from consequent weights."""
    check_is_fitted(self, "model_")
    weights = self.model_.get_consequent_weights()
    if weights is None:
        return None

    consequent_layer = self.model_.consequent_layer
    if hasattr(consequent_layer, "rule_feature_mask"):
        rule_feature_mask = cast(Tensor, consequent_layer.rule_feature_mask)
        weights = weights * rule_feature_mask.unsqueeze(1) if weights.ndim == 3 else weights * rule_feature_mask

    abs_weights = weights.abs()
    if abs_weights.ndim == 3:
        importance = abs_weights.mean(dim=(0, 1))
    elif abs_weights.ndim == 2:
        importance = abs_weights.mean(dim=0)
    else:
        raise ValueError("unsupported consequent weight shape for feature importance")

    return _normalize_importance(importance)

`fit`

Train the TSK classifier on labeled samples.

Validation data should be supplied using x_val and y_val when available.

Source code in highfis/estimators/_base.py

def fit(
    self,
    x: Any,
    y: Any,
    *,
    x_val: Any | None = None,
    y_val: Any | None = None,
) -> Self:
    """Train the TSK classifier on labeled samples.

    Validation data should be supplied using ``x_val`` and ``y_val``
    when available.
    """
    x_arr, y_arr = check_X_y(x, y)

    if self.random_state is not None:
        torch.manual_seed(int(self.random_state))

    le = LabelEncoder()
    y_idx = le.fit_transform(np.asarray(y_arr))

    input_mfs, feature_names, effective_rule_base = self._build_input_mfs(x_arr)

    self.n_features_in_ = x_arr.shape[1]
    self.feature_names_in_ = np.asarray(feature_names, dtype=object)
    self.classes_ = le.classes_
    self._label_encoder_ = le

    _device = torch.device(str(self.device))
    self.model_ = self._build_model(input_mfs, len(self.classes_), effective_rule_base).to(_device)

    y_t = torch.as_tensor(y_idx, dtype=torch.long, device=_device)

    # Prepare validation tensors if provided via fit.
    x_val_t: torch.Tensor | None = None
    y_val_t: torch.Tensor | None = None
    if (x_val is None) ^ (y_val is None):
        raise ValueError("x_val and y_val must be provided together")
    if x_val is not None and y_val is not None:
        x_v_arr, y_v_arr = check_X_y(x_val, y_val)
        x_val_t = self._as_tensor_x(x_v_arr, _device)
        y_val_idx = le.transform(np.asarray(y_v_arr))
        y_val_t = torch.as_tensor(y_val_idx, dtype=torch.long, device=_device)

    self.history_ = self.model_.fit(
        self._as_tensor_x(x_arr, _device),
        y_t,
        epochs=int(self.epochs),
        learning_rate=float(self.learning_rate),
        batch_size=self.batch_size,
        shuffle=bool(self.shuffle),
        ur_weight=float(self.ur_weight),
        ur_target=self.ur_target,
        verbose=self.verbose,
        x_val=x_val_t,
        y_val=y_val_t,
        patience=self.patience,
        restore_best=self.restore_best,
        weight_decay=float(self.weight_decay),
    )
    self.rule_base_ = effective_rule_base
    return self

`get_mf_params`

Return model membership function metadata after fitting.

Source code in highfis/estimators/_base.py

def get_mf_params(self) -> dict[str, list[dict[str, Any]]]:
    """Return model membership function metadata after fitting."""
    check_is_fitted(self, "model_")
    return self.model_.get_mf_params()

`inspect`

Return a structured summary of fitted model state and rule metadata.

Source code in highfis/estimators/_base.py

def inspect(self) -> dict[str, Any]:
    """Return a structured summary of fitted model state and rule metadata."""
    check_is_fitted(self, "model_")
    return {
        "n_rules": int(self.model_.n_rules),
        "n_inputs": int(self.model_.n_inputs),
        "feature_names": list(self.model_.input_names),
        "rule_base": self.rule_base_,
        "defuzzifier_type": type(self.model_.defuzzifier).__name__,
        "mf_params": self.get_mf_params(),
        "rule_table": self.model_.get_rule_table(),
    }

`load` `classmethod`

Load a persisted estimator created by save.

Source code in highfis/estimators/_base.py

@classmethod
def load(cls, path: str) -> Self:
    """Load a persisted estimator created by save."""
    checkpoint = load_checkpoint(path)
    validate_checkpoint_payload(checkpoint, expected_estimator_class=cls.__name__)

    params: dict[str, Any] = dict(checkpoint["estimator_params"])
    if params.get("input_configs") is not None:
        params["input_configs"] = [InputConfig(**c) for c in params["input_configs"]]
    estimator = cls(**params)
    model_init = checkpoint["model_init"]
    estimator.rule_base_ = model_init["rule_base"]
    estimator.model_ = estimator._build_model(
        deserialize_input_mfs(model_init["input_mfs_config"]),
        int(model_init["n_classes"]),
        str(model_init["rule_base"]),
    )
    estimator.model_.load_state_dict(checkpoint["model_state_dict"])
    estimator.model_.to(torch.device(str(estimator.device)))

    fitted = checkpoint["fitted_attrs"]
    estimator.n_features_in_ = int(fitted["n_features_in"])
    estimator.feature_names_in_ = np.asarray(fitted["feature_names_in"], dtype=object)
    estimator.classes_ = np.asarray(fitted["classes"], dtype=object)
    label_encoder = LabelEncoder()
    label_encoder.classes_ = estimator.classes_
    estimator._label_encoder_ = label_encoder
    estimator.history_ = cast(dict[str, Any], checkpoint.get("history", {}))
    return estimator

`predict`

Predict class labels for input samples.

Source code in highfis/estimators/_base.py

def predict(self, x: Any) -> np.ndarray:
    """Predict class labels for input samples."""
    proba = self.predict_proba(x)
    y_idx = np.argmax(proba, axis=1)
    return np.asarray(self._label_encoder_.inverse_transform(y_idx))

`predict_proba`

Predict class probabilities for input samples.

Source code in highfis/estimators/_base.py

def predict_proba(self, x: Any) -> np.ndarray:
    """Predict class probabilities for input samples."""
    check_is_fitted(self, "model_")
    x_arr = check_array(x)
    if x_arr.shape[1] != self.n_features_in_:
        raise ValueError(f"expected {self.n_features_in_} features, got {x_arr.shape[1]}")
    probs = cast(Any, self.model_).predict_proba(self._as_tensor_x(x_arr, torch.device(str(self.device))))
    return probs.detach().cpu().numpy()

`rule_activation`

Return normalized rule activations for the provided inputs.

Source code in highfis/estimators/_base.py

def rule_activation(self, X: Any) -> np.ndarray:
    """Return normalized rule activations for the provided inputs."""
    check_is_fitted(self, "model_")
    x_arr = check_array(X)
    if x_arr.shape[1] != self.n_features_in_:
        raise ValueError(f"expected {self.n_features_in_} features, got {x_arr.shape[1]}")

    was_training = self.model_.training
    try:
        self.model_.eval()
        with torch.no_grad():
            norm_w = self.model_.forward_antecedents(self._as_tensor_x(x_arr, torch.device(str(self.device))))
    finally:
        self.model_.train(was_training)

    return _to_numpy(norm_w)

`save`

Persist estimator configuration, model weights and fitted metadata.

Source code in highfis/estimators/_base.py

def save(self, path: str) -> None:
    """Persist estimator configuration, model weights and fitted metadata."""
    checkpoint = self._build_checkpoint_base(
        model_init={
            "input_mfs_config": serialize_input_mfs(self.model_.input_mfs),
            "n_classes": len(self.classes_),
            "rule_base": self.rule_base_,
        },
        fitted_attrs={
            "n_features_in": int(self.n_features_in_),
            "feature_names_in": self.feature_names_in_.tolist(),
            "classes": self.classes_.tolist(),
        },
    )
    save_checkpoint(path, checkpoint)

`score`

Return classification accuracy on the provided dataset.

Source code in highfis/estimators/_base.py

def score(self, X: Any, y: Any, sample_weight: Any = None) -> float:
    """Return classification accuracy on the provided dataset."""
    y_true = np.asarray(y)
    y_pred = self.predict(X)
    return float(accuracy_score(y_true, y_pred, sample_weight=sample_weight))

`DGALETSKRegressor`

Bases: FSREADATSKRegressor

DG-ALETSK regressor with ALE-softmin antecedent and double-group gates.

DG-ALETSK extends FSRE-ADATSK by replacing the adaptive softmin with the Adaptive Ln-Exp (ALE) softmin — a smoother variant with improved numerical stability. It also uses a zero-order consequent in the DG (data-guided) training phase and optionally converts to first-order after gate-based pruning.

Reference

G. Xue, J. Wang, B. Yuan and C. Dai, "DG-ALETSK: A High-Dimensional Fuzzy Approach With Simultaneous Feature Selection and Rule Extraction," in IEEE Transactions on Fuzzy Systems, vol. 31, no. 11, pp. 3866-3880, Nov. 2023, doi: 10.1109/TFUZZ.2023.3270445.

Example

from highfis import DGALETSKRegressor

reg = DGALETSKRegressor(n_mfs=30, use_en_frb=False, random_state=0)
reg.fit(X_train, y_train)

Initialise an FSRE-ADATSK regressor.

Parameters:

Name	Type	Description	Default
`lambda_init`	`float`	Accepted for API compatibility but not used by FSRE-ADATSK or DG-ALETSK. FSRE-ADATSK computes its adaptive softmin index directly from membership values; DG-ALETSK uses the fixed exponent `ξ = 700` per paper eq. 22. Default `1.0`.	`1.0`
`use_en_frb`	`bool`	If `True`, use the Enhanced FRB (En-FRB) for rule extraction. Default `False` keeps CoCo-FRB.	`False`
`input_configs`	`list[InputConfig] \| None`	Per-feature :class:`InputConfig` list. Only `name` is used when `mf_init="kmeans"`.	`None`
`n_mfs`	`int`	Number of k-means clusters / grid MFs (default `5`).	`5`
`mf_init`	`str`	`"kmeans"` (default), `"minibatch_kmeans"`, `"fcm"`, or `"grid"`.	`'kmeans'`
`sigma_scale`	`float \| str`	Sigma scale factor. `1.0` recommended.	`1.0`
`random_state`	`int \| None`	Seed for k-means and weight initialisation.	`None`
`epochs`	`int`	Maximum training epochs (default `10`).	`10`
`learning_rate`	`float`	Adam learning rate (default `0.01`).	`0.01`
`verbose`	`bool \| int`	Print per-epoch progress.	`False`
`rule_base`	`str \| None`	`"coco"` or `"cartesian"`.	`None`
`batch_size`	`int \| None`	Mini-batch size (default `512`).	`512`
`shuffle`	`bool`	Reshuffle each epoch.	`True`
`ur_weight`	`float`	Uncertainty regularisation weight.	`0.0`
`ur_target`	`float \| None`	Uncertainty regularisation target.	`None`
`consequent_batch_norm`	`bool`	Batch normalisation on consequent layers.	`False`
`patience`	`int \| None`	Early-stopping patience (default `20`). Set to `None` to disable early stopping.	`20`
`restore_best`	`bool`	If `True` (default), restore the best validation model weights after training.	`True`
`weight_decay`	`float`	L2 weight decay for consequent parameters.	`1e-08`

Raises:

Type	Description
`ValueError`	If `lambda_init <= 0`.

Source code in highfis/estimators/_fsre.py

def __init__(
    self,
    *,
    lambda_init: float = 1.0,
    use_en_frb: bool = False,
    input_configs: list[InputConfig] | None = None,
    n_mfs: int = 5,
    mf_init: str = "kmeans",
    sigma_scale: float | str = 1.0,
    random_state: int | None = None,
    epochs: int = 10,
    learning_rate: float = 1e-2,
    verbose: bool | int = False,
    rule_base: str | None = None,
    batch_size: int | None = 512,
    shuffle: bool = True,
    ur_weight: float = 0.0,
    ur_target: float | None = None,
    consequent_batch_norm: bool = False,
    patience: int | None = 20,
    restore_best: bool = True,
    weight_decay: float = 1e-8,
) -> None:
    """Initialise an FSRE-ADATSK regressor.

    Args:
        lambda_init: Accepted for API compatibility but not used by
            FSRE-ADATSK or DG-ALETSK.  FSRE-ADATSK computes its
            adaptive softmin index directly from membership values;
            DG-ALETSK uses the fixed exponent ``ξ = 700`` per
            paper eq. 22.  Default ``1.0``.
        use_en_frb: If ``True``, use the Enhanced FRB (En-FRB) for rule
            extraction. Default ``False`` keeps CoCo-FRB.
        input_configs: Per-feature :class:`InputConfig` list. Only
            ``name`` is used when ``mf_init="kmeans"``.
        n_mfs: Number of k-means clusters / grid MFs (default ``5``).
        mf_init: ``"kmeans"`` (default), ``"minibatch_kmeans"``, ``"fcm"``, or ``"grid"``.
        sigma_scale: Sigma scale factor. ``1.0`` recommended.
        random_state: Seed for k-means and weight initialisation.
        epochs: Maximum training epochs (default ``10``).
        learning_rate: Adam learning rate (default ``0.01``).
        verbose: Print per-epoch progress.
        rule_base: ``"coco"`` or ``"cartesian"``.
        batch_size: Mini-batch size (default ``512``).
        shuffle: Reshuffle each epoch.
        ur_weight: Uncertainty regularisation weight.
        ur_target: Uncertainty regularisation target.
        consequent_batch_norm: Batch normalisation on consequent layers.
        patience: Early-stopping patience (default ``20``). Set to ``None`` to disable early stopping.
        restore_best: If ``True`` (default), restore the best validation
            model weights after training.
        weight_decay: L2 weight decay for consequent parameters.

    Raises:
        ValueError: If ``lambda_init <= 0``.
    """
    if lambda_init <= 0.0:
        raise ValueError("lambda_init must be > 0")
    self.lambda_init = float(lambda_init)
    self.use_en_frb = bool(use_en_frb)
    super().__init__(
        input_configs=input_configs,
        n_mfs=n_mfs,
        mf_init=mf_init,
        sigma_scale=sigma_scale,
        random_state=random_state,
        epochs=epochs,
        learning_rate=learning_rate,
        verbose=verbose,
        rule_base=rule_base,
        batch_size=batch_size,
        shuffle=shuffle,
        ur_weight=ur_weight,
        ur_target=ur_target,
        consequent_batch_norm=consequent_batch_norm,
        patience=patience,
        restore_best=restore_best,
        weight_decay=weight_decay,
    )

`evaluate`

Compute regression evaluation metrics for the provided dataset.

Source code in highfis/estimators/_base.py

def evaluate(
    self,
    X: Any,
    y: Any,
    metrics: list[str] | None = None,
    sample_weight: Any | None = None,
) -> dict[str, float]:
    """Compute regression evaluation metrics for the provided dataset."""
    y_true = np.asarray(y)
    y_pred = self.predict(X)
    return compute_metrics(
        task="regression",
        y_true=y_true,
        y_pred=y_pred,
        sample_weight=sample_weight,
        metrics=metrics,
    )

`feature_importance`

Compute a normalized feature importance vector from consequent weights.

Source code in highfis/estimators/_base.py

def feature_importance(self) -> np.ndarray | None:
    """Compute a normalized feature importance vector from consequent weights."""
    check_is_fitted(self, "model_")
    weights = self.model_.get_consequent_weights()
    if weights is None:
        return None

    consequent_layer = self.model_.consequent_layer
    if hasattr(consequent_layer, "rule_feature_mask"):
        rule_feature_mask = cast(Tensor, consequent_layer.rule_feature_mask)
        weights = weights * rule_feature_mask.unsqueeze(1) if weights.ndim == 3 else weights * rule_feature_mask

    abs_weights = weights.abs()
    if abs_weights.ndim == 3:
        importance = abs_weights.mean(dim=(0, 1))
    elif abs_weights.ndim == 2:
        importance = abs_weights.mean(dim=0)
    else:
        raise ValueError("unsupported consequent weight shape for feature importance")

    return _normalize_importance(importance)

`fit`

Train the TSK regressor on labeled samples.

Validation data should be supplied using x_val and y_val when available.

Source code in highfis/estimators/_base.py

def fit(
    self,
    x: Any,
    y: Any,
    *,
    x_val: Any | None = None,
    y_val: Any | None = None,
) -> Self:
    """Train the TSK regressor on labeled samples.

    Validation data should be supplied using ``x_val`` and ``y_val``
    when available.
    """
    x_arr, y_arr = check_X_y(x, y)

    if self.random_state is not None:
        torch.manual_seed(int(self.random_state))

    input_mfs, feature_names, effective_rule_base = self._build_input_mfs(x_arr)

    self.n_features_in_ = x_arr.shape[1]
    self.feature_names_in_ = np.asarray(feature_names, dtype=object)

    _device = torch.device(str(self.device))
    self.model_ = self._build_regressor_model(input_mfs, effective_rule_base).to(_device)

    y_t = torch.as_tensor(np.asarray(y_arr, dtype=np.float32), dtype=torch.float32, device=_device)

    # Prepare validation tensors if provided via fit.
    x_val_t: torch.Tensor | None = None
    y_val_t: torch.Tensor | None = None
    if (x_val is None) ^ (y_val is None):
        raise ValueError("x_val and y_val must be provided together")
    if x_val is not None and y_val is not None:
        x_v_arr, y_v_arr = check_X_y(x_val, y_val)
        x_val_t = self._as_tensor_x(x_v_arr, _device)
        y_val_t = torch.as_tensor(np.asarray(y_v_arr, dtype=np.float32), dtype=torch.float32, device=_device)

    self.history_ = self.model_.fit(
        self._as_tensor_x(x_arr, _device),
        y_t,
        epochs=int(self.epochs),
        learning_rate=float(self.learning_rate),
        batch_size=self.batch_size,
        shuffle=bool(self.shuffle),
        ur_weight=float(self.ur_weight),
        ur_target=self.ur_target,
        verbose=self.verbose,
        x_val=x_val_t,
        y_val=y_val_t,
        patience=self.patience,
        restore_best=self.restore_best,
        weight_decay=float(self.weight_decay),
    )
    self.rule_base_ = effective_rule_base
    return self

`get_mf_params`

Return model membership function metadata after fitting.

Source code in highfis/estimators/_base.py

def get_mf_params(self) -> dict[str, list[dict[str, Any]]]:
    """Return model membership function metadata after fitting."""
    check_is_fitted(self, "model_")
    return self.model_.get_mf_params()

`inspect`

Return a structured summary of fitted model state and rule metadata.

Source code in highfis/estimators/_base.py

def inspect(self) -> dict[str, Any]:
    """Return a structured summary of fitted model state and rule metadata."""
    check_is_fitted(self, "model_")
    return {
        "n_rules": int(self.model_.n_rules),
        "n_inputs": int(self.model_.n_inputs),
        "feature_names": list(self.model_.input_names),
        "rule_base": self.rule_base_,
        "defuzzifier_type": type(self.model_.defuzzifier).__name__,
        "mf_params": self.get_mf_params(),
        "rule_table": self.model_.get_rule_table(),
    }

`load` `classmethod`

Load a persisted estimator created by save.

Source code in highfis/estimators/_base.py

@classmethod
def load(cls, path: str) -> Self:
    """Load a persisted estimator created by save."""
    checkpoint = load_checkpoint(path)
    validate_checkpoint_payload(checkpoint, expected_estimator_class=cls.__name__)

    params: dict[str, Any] = dict(checkpoint["estimator_params"])
    if params.get("input_configs") is not None:
        params["input_configs"] = [InputConfig(**c) for c in params["input_configs"]]
    estimator = cls(**params)
    model_init = checkpoint["model_init"]
    estimator.rule_base_ = model_init["rule_base"]
    estimator.model_ = estimator._build_regressor_model(
        deserialize_input_mfs(model_init["input_mfs_config"]),
        str(model_init["rule_base"]),
    )
    estimator.model_.load_state_dict(checkpoint["model_state_dict"])
    estimator.model_.to(torch.device(str(estimator.device)))

    fitted = checkpoint["fitted_attrs"]
    estimator.n_features_in_ = int(fitted["n_features_in"])
    estimator.feature_names_in_ = np.asarray(fitted["feature_names_in"], dtype=object)
    estimator.history_ = cast(dict[str, Any], checkpoint.get("history", {}))
    return estimator

`predict`

Predict continuous target values for input samples.

Source code in highfis/estimators/_base.py

def predict(self, x: Any) -> np.ndarray:
    """Predict continuous target values for input samples."""
    check_is_fitted(self, "model_")
    x_arr = check_array(x)
    if x_arr.shape[1] != self.n_features_in_:
        raise ValueError(f"expected {self.n_features_in_} features, got {x_arr.shape[1]}")
    preds = cast(Any, self.model_).predict(self._as_tensor_x(x_arr, torch.device(str(self.device))))
    return preds.detach().cpu().numpy()

`rule_activation`

Return normalized rule activations for the provided inputs.

Source code in highfis/estimators/_base.py

def rule_activation(self, X: Any) -> np.ndarray:
    """Return normalized rule activations for the provided inputs."""
    check_is_fitted(self, "model_")
    x_arr = check_array(X)
    if x_arr.shape[1] != self.n_features_in_:
        raise ValueError(f"expected {self.n_features_in_} features, got {x_arr.shape[1]}")

    was_training = self.model_.training
    try:
        self.model_.eval()
        with torch.no_grad():
            norm_w = self.model_.forward_antecedents(self._as_tensor_x(x_arr, torch.device(str(self.device))))
    finally:
        self.model_.train(was_training)

    return _to_numpy(norm_w)

`save`

Persist estimator configuration, model weights and fitted metadata.

Source code in highfis/estimators/_base.py

def save(self, path: str) -> None:
    """Persist estimator configuration, model weights and fitted metadata."""
    checkpoint = self._build_checkpoint_base(
        model_init={
            "input_mfs_config": serialize_input_mfs(self.model_.input_mfs),
            "rule_base": self.rule_base_,
        },
        fitted_attrs={
            "n_features_in": int(self.n_features_in_),
            "feature_names_in": self.feature_names_in_.tolist(),
        },
    )
    save_checkpoint(path, checkpoint)

`DGTSKClassifier`

Bases: _BaseClassifierEstimator

DG-TSK classifier with M-gate antecedent and point-based FRB (P-FRB).

DG-TSK uses a data-guided M-gate function to automatically select relevant features and rules.

Reference

Guangdong Xue, Jian Wang, Bingjie Zhang, Bin Yuan, Caili Dai, Double groups of gates based Takagi-Sugeno-Kang (DG-TSK) fuzzy system for simultaneous feature selection and rule extraction, Fuzzy Sets and Systems, Volume 469, 2023, 108627, ISSN 0165-0114, https://doi.org/10.1016/j.fss.2023.108627.

Example

from highfis import DGTSKClassifier

clf = DGTSKClassifier(n_mfs=30, use_en_frb=False, random_state=0)
clf.fit(X_train, y_train)

Initialise a DG-TSK classifier.

Parameters:

Name	Type	Description	Default
`use_en_frb`	`bool`	If `True`, use the Enhanced FRB (En-FRB) for rule extraction (P-FRB). Default `False` keeps CoCo-FRB.	`False`
`input_configs`	`list[InputConfig] \| None`	Per-feature :class:`InputConfig` list.	`None`
`n_mfs`	`int`	Number of k-means clusters / grid MFs (default `5`).	`5`
`mf_init`	`str`	`"kmeans"` (default), `"minibatch_kmeans"`, `"fcm"`, or `"grid"`.	`'kmeans'`
`sigma_scale`	`float \| str`	Sigma scale factor. `1.0` recommended.	`1.0`
`random_state`	`int \| None`	Seed for reproducibility.	`None`
`epochs`	`int`	Maximum training epochs (default `10`).	`10`
`learning_rate`	`float`	Adam learning rate (default `0.01`).	`0.01`
`verbose`	`bool \| int`	Print per-epoch progress.	`False`
`rule_base`	`str \| None`	`"coco"` or `"cartesian"`.	`None`
`batch_size`	`int \| None`	Mini-batch size (default `512`).	`512`
`shuffle`	`bool`	Reshuffle each epoch.	`True`
`ur_weight`	`float`	Uncertainty regularisation weight.	`0.0`
`ur_target`	`float \| None`	Uncertainty regularisation target.	`None`
`consequent_batch_norm`	`bool`	Batch normalisation on consequent layers.	`False`
`pfrb_max_rules`	`int \| None`	Maximum number of point-based FRB rules when `rule_base='pfrb'`. `None` uses all training samples.	`None`
`patience`	`int \| None`	Early-stopping patience (default `20`). Set to `None` to disable early stopping.	`20`
`restore_best`	`bool`	If `True` (default), restore the best validation model weights after training.	`True`
`weight_decay`	`float`	L2 weight decay for consequent parameters.	`1e-08`

Source code in highfis/estimators/_dg_tsk.py

def __init__(
    self,
    *,
    use_en_frb: bool = False,
    input_configs: list[InputConfig] | None = None,
    n_mfs: int = 5,
    mf_init: str = "kmeans",
    sigma_scale: float | str = 1.0,
    random_state: int | None = None,
    epochs: int = 10,
    learning_rate: float = 1e-2,
    verbose: bool | int = False,
    rule_base: str | None = None,
    batch_size: int | None = 512,
    shuffle: bool = True,
    ur_weight: float = 0.0,
    ur_target: float | None = None,
    consequent_batch_norm: bool = False,
    pfrb_max_rules: int | None = None,
    patience: int | None = 20,
    restore_best: bool = True,
    weight_decay: float = 1e-8,
) -> None:
    """Initialise a DG-TSK classifier.

    Args:
        use_en_frb: If ``True``, use the Enhanced FRB (En-FRB) for rule
            extraction (P-FRB). Default ``False`` keeps CoCo-FRB.
        input_configs: Per-feature :class:`InputConfig` list.
        n_mfs: Number of k-means clusters / grid MFs (default ``5``).
        mf_init: ``"kmeans"`` (default), ``"minibatch_kmeans"``, ``"fcm"``, or ``"grid"``.
        sigma_scale: Sigma scale factor. ``1.0`` recommended.
        random_state: Seed for reproducibility.
        epochs: Maximum training epochs (default ``10``).
        learning_rate: Adam learning rate (default ``0.01``).
        verbose: Print per-epoch progress.
        rule_base: ``"coco"`` or ``"cartesian"``.
        batch_size: Mini-batch size (default ``512``).
        shuffle: Reshuffle each epoch.
        ur_weight: Uncertainty regularisation weight.
        ur_target: Uncertainty regularisation target.
        consequent_batch_norm: Batch normalisation on consequent layers.
        pfrb_max_rules: Maximum number of point-based FRB rules when
            ``rule_base='pfrb'``. ``None`` uses all training samples.
        patience: Early-stopping patience (default ``20``). Set to ``None`` to disable early stopping.
        restore_best: If ``True`` (default), restore the best validation
            model weights after training.
        weight_decay: L2 weight decay for consequent parameters.
    """
    self.use_en_frb = bool(use_en_frb)
    super().__init__(
        input_configs=input_configs,
        n_mfs=n_mfs,
        mf_init=mf_init,
        sigma_scale=sigma_scale,
        random_state=random_state,
        epochs=epochs,
        learning_rate=learning_rate,
        verbose=verbose,
        rule_base=rule_base,
        batch_size=batch_size,
        shuffle=shuffle,
        ur_weight=ur_weight,
        ur_target=ur_target,
        consequent_batch_norm=consequent_batch_norm,
        pfrb_max_rules=pfrb_max_rules,
        patience=patience,
        restore_best=restore_best,
        weight_decay=weight_decay,
    )

`evaluate`

Compute classification evaluation metrics for the provided dataset.

Source code in highfis/estimators/_base.py

def evaluate(
    self,
    X: Any,
    y: Any,
    metrics: list[str] | None = None,
    sample_weight: Any | None = None,
) -> dict[str, float]:
    """Compute classification evaluation metrics for the provided dataset."""
    y_true = np.asarray(y)
    y_pred = self.predict(X)
    return compute_metrics(
        task="classification",
        y_true=y_true,
        y_pred=y_pred,
        sample_weight=sample_weight,
        metrics=metrics,
    )

`feature_importance`

Compute a normalized feature importance vector from consequent weights.

Source code in highfis/estimators/_base.py

def feature_importance(self) -> np.ndarray | None:
    """Compute a normalized feature importance vector from consequent weights."""
    check_is_fitted(self, "model_")
    weights = self.model_.get_consequent_weights()
    if weights is None:
        return None

    consequent_layer = self.model_.consequent_layer
    if hasattr(consequent_layer, "rule_feature_mask"):
        rule_feature_mask = cast(Tensor, consequent_layer.rule_feature_mask)
        weights = weights * rule_feature_mask.unsqueeze(1) if weights.ndim == 3 else weights * rule_feature_mask

    abs_weights = weights.abs()
    if abs_weights.ndim == 3:
        importance = abs_weights.mean(dim=(0, 1))
    elif abs_weights.ndim == 2:
        importance = abs_weights.mean(dim=0)
    else:
        raise ValueError("unsupported consequent weight shape for feature importance")

    return _normalize_importance(importance)

`fit`

Train the TSK classifier on labeled samples.

Validation data should be supplied using x_val and y_val when available.

Source code in highfis/estimators/_base.py

def fit(
    self,
    x: Any,
    y: Any,
    *,
    x_val: Any | None = None,
    y_val: Any | None = None,
) -> Self:
    """Train the TSK classifier on labeled samples.

    Validation data should be supplied using ``x_val`` and ``y_val``
    when available.
    """
    x_arr, y_arr = check_X_y(x, y)

    if self.random_state is not None:
        torch.manual_seed(int(self.random_state))

    le = LabelEncoder()
    y_idx = le.fit_transform(np.asarray(y_arr))

    input_mfs, feature_names, effective_rule_base = self._build_input_mfs(x_arr)

    self.n_features_in_ = x_arr.shape[1]
    self.feature_names_in_ = np.asarray(feature_names, dtype=object)
    self.classes_ = le.classes_
    self._label_encoder_ = le

    _device = torch.device(str(self.device))
    self.model_ = self._build_model(input_mfs, len(self.classes_), effective_rule_base).to(_device)

    y_t = torch.as_tensor(y_idx, dtype=torch.long, device=_device)

    # Prepare validation tensors if provided via fit.
    x_val_t: torch.Tensor | None = None
    y_val_t: torch.Tensor | None = None
    if (x_val is None) ^ (y_val is None):
        raise ValueError("x_val and y_val must be provided together")
    if x_val is not None and y_val is not None:
        x_v_arr, y_v_arr = check_X_y(x_val, y_val)
        x_val_t = self._as_tensor_x(x_v_arr, _device)
        y_val_idx = le.transform(np.asarray(y_v_arr))
        y_val_t = torch.as_tensor(y_val_idx, dtype=torch.long, device=_device)

    self.history_ = self.model_.fit(
        self._as_tensor_x(x_arr, _device),
        y_t,
        epochs=int(self.epochs),
        learning_rate=float(self.learning_rate),
        batch_size=self.batch_size,
        shuffle=bool(self.shuffle),
        ur_weight=float(self.ur_weight),
        ur_target=self.ur_target,
        verbose=self.verbose,
        x_val=x_val_t,
        y_val=y_val_t,
        patience=self.patience,
        restore_best=self.restore_best,
        weight_decay=float(self.weight_decay),
    )
    self.rule_base_ = effective_rule_base
    return self

`get_mf_params`

Return model membership function metadata after fitting.

Source code in highfis/estimators/_base.py

def get_mf_params(self) -> dict[str, list[dict[str, Any]]]:
    """Return model membership function metadata after fitting."""
    check_is_fitted(self, "model_")
    return self.model_.get_mf_params()

`inspect`

Return a structured summary of fitted model state and rule metadata.

Source code in highfis/estimators/_base.py

def inspect(self) -> dict[str, Any]:
    """Return a structured summary of fitted model state and rule metadata."""
    check_is_fitted(self, "model_")
    return {
        "n_rules": int(self.model_.n_rules),
        "n_inputs": int(self.model_.n_inputs),
        "feature_names": list(self.model_.input_names),
        "rule_base": self.rule_base_,
        "defuzzifier_type": type(self.model_.defuzzifier).__name__,
        "mf_params": self.get_mf_params(),
        "rule_table": self.model_.get_rule_table(),
    }

`load` `classmethod`

Load a persisted estimator created by save.

Source code in highfis/estimators/_base.py

@classmethod
def load(cls, path: str) -> Self:
    """Load a persisted estimator created by save."""
    checkpoint = load_checkpoint(path)
    validate_checkpoint_payload(checkpoint, expected_estimator_class=cls.__name__)

    params: dict[str, Any] = dict(checkpoint["estimator_params"])
    if params.get("input_configs") is not None:
        params["input_configs"] = [InputConfig(**c) for c in params["input_configs"]]
    estimator = cls(**params)
    model_init = checkpoint["model_init"]
    estimator.rule_base_ = model_init["rule_base"]
    estimator.model_ = estimator._build_model(
        deserialize_input_mfs(model_init["input_mfs_config"]),
        int(model_init["n_classes"]),
        str(model_init["rule_base"]),
    )
    estimator.model_.load_state_dict(checkpoint["model_state_dict"])
    estimator.model_.to(torch.device(str(estimator.device)))

    fitted = checkpoint["fitted_attrs"]
    estimator.n_features_in_ = int(fitted["n_features_in"])
    estimator.feature_names_in_ = np.asarray(fitted["feature_names_in"], dtype=object)
    estimator.classes_ = np.asarray(fitted["classes"], dtype=object)
    label_encoder = LabelEncoder()
    label_encoder.classes_ = estimator.classes_
    estimator._label_encoder_ = label_encoder
    estimator.history_ = cast(dict[str, Any], checkpoint.get("history", {}))
    return estimator

`predict`

Predict class labels for input samples.

Source code in highfis/estimators/_base.py

def predict(self, x: Any) -> np.ndarray:
    """Predict class labels for input samples."""
    proba = self.predict_proba(x)
    y_idx = np.argmax(proba, axis=1)
    return np.asarray(self._label_encoder_.inverse_transform(y_idx))

`predict_proba`

Predict class probabilities for input samples.

Source code in highfis/estimators/_base.py

def predict_proba(self, x: Any) -> np.ndarray:
    """Predict class probabilities for input samples."""
    check_is_fitted(self, "model_")
    x_arr = check_array(x)
    if x_arr.shape[1] != self.n_features_in_:
        raise ValueError(f"expected {self.n_features_in_} features, got {x_arr.shape[1]}")
    probs = cast(Any, self.model_).predict_proba(self._as_tensor_x(x_arr, torch.device(str(self.device))))
    return probs.detach().cpu().numpy()

`rule_activation`

Return normalized rule activations for the provided inputs.

Source code in highfis/estimators/_base.py

def rule_activation(self, X: Any) -> np.ndarray:
    """Return normalized rule activations for the provided inputs."""
    check_is_fitted(self, "model_")
    x_arr = check_array(X)
    if x_arr.shape[1] != self.n_features_in_:
        raise ValueError(f"expected {self.n_features_in_} features, got {x_arr.shape[1]}")

    was_training = self.model_.training
    try:
        self.model_.eval()
        with torch.no_grad():
            norm_w = self.model_.forward_antecedents(self._as_tensor_x(x_arr, torch.device(str(self.device))))
    finally:
        self.model_.train(was_training)

    return _to_numpy(norm_w)

`save`

Persist estimator configuration, model weights and fitted metadata.

Source code in highfis/estimators/_base.py

def save(self, path: str) -> None:
    """Persist estimator configuration, model weights and fitted metadata."""
    checkpoint = self._build_checkpoint_base(
        model_init={
            "input_mfs_config": serialize_input_mfs(self.model_.input_mfs),
            "n_classes": len(self.classes_),
            "rule_base": self.rule_base_,
        },
        fitted_attrs={
            "n_features_in": int(self.n_features_in_),
            "feature_names_in": self.feature_names_in_.tolist(),
            "classes": self.classes_.tolist(),
        },
    )
    save_checkpoint(path, checkpoint)

`score`

Return classification accuracy on the provided dataset.

Source code in highfis/estimators/_base.py

def score(self, X: Any, y: Any, sample_weight: Any = None) -> float:
    """Return classification accuracy on the provided dataset."""
    y_true = np.asarray(y)
    y_pred = self.predict(X)
    return float(accuracy_score(y_true, y_pred, sample_weight=sample_weight))

`DGTSKRegressor`

Bases: _BaseRegressorEstimator

DG-TSK regressor with M-gate antecedent and point-based FRB (P-FRB).

DG-TSK uses a data-guided M-gate function to automatically select relevant features and rules.

Reference

Guangdong Xue, Jian Wang, Bingjie Zhang, Bin Yuan, Caili Dai, Double groups of gates based Takagi-Sugeno-Kang (DG-TSK) fuzzy system for simultaneous feature selection and rule extraction, Fuzzy Sets and Systems, Volume 469, 2023, 108627, ISSN 0165-0114, https://doi.org/10.1016/j.fss.2023.108627.

Example

from highfis import DGTSKRegressor

reg = DGTSKRegressor(n_mfs=30, use_en_frb=False, random_state=0)
reg.fit(X_train, y_train)

Initialise a DG-TSK regressor.

Parameters:

Name	Type	Description	Default
`use_en_frb`	`bool`	If `True`, use the Enhanced FRB (En-FRB) for rule extraction (P-FRB). Default `False` keeps CoCo-FRB.	`False`
`input_configs`	`list[InputConfig] \| None`	Per-feature :class:`InputConfig` list.	`None`
`n_mfs`	`int`	Number of k-means clusters / grid MFs (default `5`).	`5`
`mf_init`	`str`	`"kmeans"` (default), `"minibatch_kmeans"`, `"fcm"`, or `"grid"`.	`'kmeans'`
`sigma_scale`	`float \| str`	Sigma scale factor. `1.0` recommended.	`1.0`
`random_state`	`int \| None`	Seed for reproducibility.	`None`
`epochs`	`int`	Maximum training epochs (default `10`).	`10`
`learning_rate`	`float`	Adam learning rate (default `0.01`).	`0.01`
`verbose`	`bool \| int`	Print per-epoch progress.	`False`
`rule_base`	`str \| None`	`"coco"` or `"cartesian"`.	`None`
`batch_size`	`int \| None`	Mini-batch size (default `512`).	`512`
`shuffle`	`bool`	Reshuffle each epoch.	`True`
`ur_weight`	`float`	Uncertainty regularisation weight.	`0.0`
`ur_target`	`float \| None`	Uncertainty regularisation target.	`None`
`consequent_batch_norm`	`bool`	Batch normalisation on consequent layers.	`False`
`pfrb_max_rules`	`int \| None`	Maximum number of point-based FRB rules when `rule_base='pfrb'`. `None` uses all training samples.	`None`
`patience`	`int \| None`	Early-stopping patience (default `20`). Set to `None` to disable early stopping.	`20`
`restore_best`	`bool`	If `True` (default), restore the best validation model weights after training.	`True`
`weight_decay`	`float`	L2 weight decay for consequent parameters.	`1e-08`

Source code in highfis/estimators/_dg_tsk.py

def __init__(
    self,
    *,
    use_en_frb: bool = False,
    input_configs: list[InputConfig] | None = None,
    n_mfs: int = 5,
    mf_init: str = "kmeans",
    sigma_scale: float | str = 1.0,
    random_state: int | None = None,
    epochs: int = 10,
    learning_rate: float = 1e-2,
    verbose: bool | int = False,
    rule_base: str | None = None,
    batch_size: int | None = 512,
    shuffle: bool = True,
    ur_weight: float = 0.0,
    ur_target: float | None = None,
    consequent_batch_norm: bool = False,
    pfrb_max_rules: int | None = None,
    patience: int | None = 20,
    restore_best: bool = True,
    weight_decay: float = 1e-8,
) -> None:
    """Initialise a DG-TSK regressor.

    Args:
        use_en_frb: If ``True``, use the Enhanced FRB (En-FRB) for rule
            extraction (P-FRB). Default ``False`` keeps CoCo-FRB.
        input_configs: Per-feature :class:`InputConfig` list.
        n_mfs: Number of k-means clusters / grid MFs (default ``5``).
        mf_init: ``"kmeans"`` (default), ``"minibatch_kmeans"``, ``"fcm"``, or ``"grid"``.
        sigma_scale: Sigma scale factor. ``1.0`` recommended.
        random_state: Seed for reproducibility.
        epochs: Maximum training epochs (default ``10``).
        learning_rate: Adam learning rate (default ``0.01``).
        verbose: Print per-epoch progress.
        rule_base: ``"coco"`` or ``"cartesian"``.
        batch_size: Mini-batch size (default ``512``).
        shuffle: Reshuffle each epoch.
        ur_weight: Uncertainty regularisation weight.
        ur_target: Uncertainty regularisation target.
        consequent_batch_norm: Batch normalisation on consequent layers.
        pfrb_max_rules: Maximum number of point-based FRB rules when
            ``rule_base='pfrb'``. ``None`` uses all training samples.
        patience: Early-stopping patience (default ``20``). Set to ``None`` to disable early stopping.
        restore_best: If ``True`` (default), restore the best validation
            model weights after training.
        weight_decay: L2 weight decay for consequent parameters.
    """
    self.use_en_frb = bool(use_en_frb)
    super().__init__(
        input_configs=input_configs,
        n_mfs=n_mfs,
        mf_init=mf_init,
        sigma_scale=sigma_scale,
        random_state=random_state,
        epochs=epochs,
        learning_rate=learning_rate,
        verbose=verbose,
        rule_base=rule_base,
        batch_size=batch_size,
        shuffle=shuffle,
        ur_weight=ur_weight,
        ur_target=ur_target,
        consequent_batch_norm=consequent_batch_norm,
        pfrb_max_rules=pfrb_max_rules,
        patience=patience,
        restore_best=restore_best,
        weight_decay=weight_decay,
    )

`evaluate`

Compute regression evaluation metrics for the provided dataset.

Source code in highfis/estimators/_base.py

def evaluate(
    self,
    X: Any,
    y: Any,
    metrics: list[str] | None = None,
    sample_weight: Any | None = None,
) -> dict[str, float]:
    """Compute regression evaluation metrics for the provided dataset."""
    y_true = np.asarray(y)
    y_pred = self.predict(X)
    return compute_metrics(
        task="regression",
        y_true=y_true,
        y_pred=y_pred,
        sample_weight=sample_weight,
        metrics=metrics,
    )

`feature_importance`

Compute a normalized feature importance vector from consequent weights.

Source code in highfis/estimators/_base.py

def feature_importance(self) -> np.ndarray | None:
    """Compute a normalized feature importance vector from consequent weights."""
    check_is_fitted(self, "model_")
    weights = self.model_.get_consequent_weights()
    if weights is None:
        return None

    consequent_layer = self.model_.consequent_layer
    if hasattr(consequent_layer, "rule_feature_mask"):
        rule_feature_mask = cast(Tensor, consequent_layer.rule_feature_mask)
        weights = weights * rule_feature_mask.unsqueeze(1) if weights.ndim == 3 else weights * rule_feature_mask

    abs_weights = weights.abs()
    if abs_weights.ndim == 3:
        importance = abs_weights.mean(dim=(0, 1))
    elif abs_weights.ndim == 2:
        importance = abs_weights.mean(dim=0)
    else:
        raise ValueError("unsupported consequent weight shape for feature importance")

    return _normalize_importance(importance)

`fit`

Train the TSK regressor on labeled samples.

Validation data should be supplied using x_val and y_val when available.

Source code in highfis/estimators/_base.py

def fit(
    self,
    x: Any,
    y: Any,
    *,
    x_val: Any | None = None,
    y_val: Any | None = None,
) -> Self:
    """Train the TSK regressor on labeled samples.

    Validation data should be supplied using ``x_val`` and ``y_val``
    when available.
    """
    x_arr, y_arr = check_X_y(x, y)

    if self.random_state is not None:
        torch.manual_seed(int(self.random_state))

    input_mfs, feature_names, effective_rule_base = self._build_input_mfs(x_arr)

    self.n_features_in_ = x_arr.shape[1]
    self.feature_names_in_ = np.asarray(feature_names, dtype=object)

    _device = torch.device(str(self.device))
    self.model_ = self._build_regressor_model(input_mfs, effective_rule_base).to(_device)

    y_t = torch.as_tensor(np.asarray(y_arr, dtype=np.float32), dtype=torch.float32, device=_device)

    # Prepare validation tensors if provided via fit.
    x_val_t: torch.Tensor | None = None
    y_val_t: torch.Tensor | None = None
    if (x_val is None) ^ (y_val is None):
        raise ValueError("x_val and y_val must be provided together")
    if x_val is not None and y_val is not None:
        x_v_arr, y_v_arr = check_X_y(x_val, y_val)
        x_val_t = self._as_tensor_x(x_v_arr, _device)
        y_val_t = torch.as_tensor(np.asarray(y_v_arr, dtype=np.float32), dtype=torch.float32, device=_device)

    self.history_ = self.model_.fit(
        self._as_tensor_x(x_arr, _device),
        y_t,
        epochs=int(self.epochs),
        learning_rate=float(self.learning_rate),
        batch_size=self.batch_size,
        shuffle=bool(self.shuffle),
        ur_weight=float(self.ur_weight),
        ur_target=self.ur_target,
        verbose=self.verbose,
        x_val=x_val_t,
        y_val=y_val_t,
        patience=self.patience,
        restore_best=self.restore_best,
        weight_decay=float(self.weight_decay),
    )
    self.rule_base_ = effective_rule_base
    return self

`get_mf_params`

Return model membership function metadata after fitting.

Source code in highfis/estimators/_base.py

def get_mf_params(self) -> dict[str, list[dict[str, Any]]]:
    """Return model membership function metadata after fitting."""
    check_is_fitted(self, "model_")
    return self.model_.get_mf_params()

`inspect`

Return a structured summary of fitted model state and rule metadata.

Source code in highfis/estimators/_base.py

def inspect(self) -> dict[str, Any]:
    """Return a structured summary of fitted model state and rule metadata."""
    check_is_fitted(self, "model_")
    return {
        "n_rules": int(self.model_.n_rules),
        "n_inputs": int(self.model_.n_inputs),
        "feature_names": list(self.model_.input_names),
        "rule_base": self.rule_base_,
        "defuzzifier_type": type(self.model_.defuzzifier).__name__,
        "mf_params": self.get_mf_params(),
        "rule_table": self.model_.get_rule_table(),
    }

`load` `classmethod`

Load a persisted estimator created by save.

Source code in highfis/estimators/_base.py

@classmethod
def load(cls, path: str) -> Self:
    """Load a persisted estimator created by save."""
    checkpoint = load_checkpoint(path)
    validate_checkpoint_payload(checkpoint, expected_estimator_class=cls.__name__)

    params: dict[str, Any] = dict(checkpoint["estimator_params"])
    if params.get("input_configs") is not None:
        params["input_configs"] = [InputConfig(**c) for c in params["input_configs"]]
    estimator = cls(**params)
    model_init = checkpoint["model_init"]
    estimator.rule_base_ = model_init["rule_base"]
    estimator.model_ = estimator._build_regressor_model(
        deserialize_input_mfs(model_init["input_mfs_config"]),
        str(model_init["rule_base"]),
    )
    estimator.model_.load_state_dict(checkpoint["model_state_dict"])
    estimator.model_.to(torch.device(str(estimator.device)))

    fitted = checkpoint["fitted_attrs"]
    estimator.n_features_in_ = int(fitted["n_features_in"])
    estimator.feature_names_in_ = np.asarray(fitted["feature_names_in"], dtype=object)
    estimator.history_ = cast(dict[str, Any], checkpoint.get("history", {}))
    return estimator

`predict`

Predict continuous target values for input samples.

Source code in highfis/estimators/_base.py

def predict(self, x: Any) -> np.ndarray:
    """Predict continuous target values for input samples."""
    check_is_fitted(self, "model_")
    x_arr = check_array(x)
    if x_arr.shape[1] != self.n_features_in_:
        raise ValueError(f"expected {self.n_features_in_} features, got {x_arr.shape[1]}")
    preds = cast(Any, self.model_).predict(self._as_tensor_x(x_arr, torch.device(str(self.device))))
    return preds.detach().cpu().numpy()

`rule_activation`

Return normalized rule activations for the provided inputs.

Source code in highfis/estimators/_base.py

def rule_activation(self, X: Any) -> np.ndarray:
    """Return normalized rule activations for the provided inputs."""
    check_is_fitted(self, "model_")
    x_arr = check_array(X)
    if x_arr.shape[1] != self.n_features_in_:
        raise ValueError(f"expected {self.n_features_in_} features, got {x_arr.shape[1]}")

    was_training = self.model_.training
    try:
        self.model_.eval()
        with torch.no_grad():
            norm_w = self.model_.forward_antecedents(self._as_tensor_x(x_arr, torch.device(str(self.device))))
    finally:
        self.model_.train(was_training)

    return _to_numpy(norm_w)

`save`

Persist estimator configuration, model weights and fitted metadata.

Source code in highfis/estimators/_base.py

def save(self, path: str) -> None:
    """Persist estimator configuration, model weights and fitted metadata."""
    checkpoint = self._build_checkpoint_base(
        model_init={
            "input_mfs_config": serialize_input_mfs(self.model_.input_mfs),
            "rule_base": self.rule_base_,
        },
        fitted_attrs={
            "n_features_in": int(self.n_features_in_),
            "feature_names_in": self.feature_names_in_.tolist(),
        },
    )
    save_checkpoint(path, checkpoint)

`DombiTSKClassifier`

Bases: _BaseClassifierEstimator

TSK classifier with a fixed Dombi T-norm in the antecedent.

DombiTSK extends TSK fuzzy inference by using a Dombi t-norm aggregation in antecedent evaluation while keeping first-order linear consequents.

Reference

G. Xue, L. Hu, J. Wang and S. Ablameyko, "ADMTSK: A High-Dimensional Takagi-Sugeno-Kang Fuzzy System Based on Adaptive Dombi T-Norm," in IEEE Transactions on Fuzzy Systems, vol. 33, no. 6, pp. 1767-1780, June 2025, doi: 10.1109/TFUZZ.2025.3535640.

Example

from highfis import DombiTSKClassifier

clf = DombiTSKClassifier(n_mfs=30, random_state=0)
clf.fit(X_train, y_train)

Initialise a DombiTSK classifier.

Parameters:

Name	Type	Description	Default
`input_configs`	`list[InputConfig] \| None`	Per-feature :class:`InputConfig` list. Only `name` is used when `mf_init="kmeans"`.	`None`
`n_mfs`	`int`	Number of k-means clusters / grid MFs (default `5`).	`5`
`mf_init`	`str`	`"kmeans"` (default), `"minibatch_kmeans"`, `"fcm"`, or `"grid"`.	`'kmeans'`
`sigma_scale`	`float \| str`	Sigma scale factor. `1.0` recommended; the Dombi T-norm handles high-dimensional stability without inflating sigma.	`1.0`
`random_state`	`int \| None`	Seed for k-means and weight initialisation.	`None`
`epochs`	`int`	Maximum training epochs (default `10`).	`10`
`learning_rate`	`float`	Adam learning rate (default `0.01`).	`0.01`
`verbose`	`bool \| int`	Print per-epoch progress.	`False`
`rule_base`	`str \| None`	`"coco"` or `"cartesian"`.	`None`
`batch_size`	`int \| None`	Mini-batch size (default `512`).	`512`
`shuffle`	`bool`	Reshuffle each epoch.	`True`
`ur_weight`	`float`	Uncertainty regularisation weight.	`0.0`
`ur_target`	`float \| None`	Uncertainty regularisation target.	`None`
`consequent_batch_norm`	`bool`	Batch normalisation on consequent layers.	`False`
`pfrb_max_rules`	`int \| None`	Maximum point-based FRB rules (unused by DombiTSK).	`None`
`patience`	`int \| None`	Early-stopping patience (default `20`). Set to `None` to disable early stopping.	`20`
`restore_best`	`bool`	If `True` (default), restore the best validation model weights after training.	`True`
`weight_decay`	`float`	L2 weight decay for consequent parameters.	`1e-08`

Source code in highfis/estimators/_dombi.py

def __init__(
    self,
    *,
    input_configs: list[InputConfig] | None = None,
    n_mfs: int = 5,
    mf_init: str = "kmeans",
    sigma_scale: float | str = 1.0,
    random_state: int | None = None,
    epochs: int = 10,
    learning_rate: float = 1e-2,
    verbose: bool | int = False,
    rule_base: str | None = None,
    batch_size: int | None = 512,
    shuffle: bool = True,
    ur_weight: float = 0.0,
    ur_target: float | None = None,
    consequent_batch_norm: bool = False,
    pfrb_max_rules: int | None = None,
    patience: int | None = 20,
    restore_best: bool = True,
    weight_decay: float = 1e-8,
) -> None:
    """Initialise a DombiTSK classifier.

    Args:
        input_configs: Per-feature :class:`InputConfig` list. Only
            ``name`` is used when ``mf_init="kmeans"``.
        n_mfs: Number of k-means clusters / grid MFs (default ``5``).
        mf_init: ``"kmeans"`` (default), ``"minibatch_kmeans"``, ``"fcm"``, or ``"grid"``.
        sigma_scale: Sigma scale factor. ``1.0`` recommended; the Dombi
            T-norm handles high-dimensional stability without inflating
            sigma.
        random_state: Seed for k-means and weight initialisation.
        epochs: Maximum training epochs (default ``10``).
        learning_rate: Adam learning rate (default ``0.01``).
        verbose: Print per-epoch progress.
        rule_base: ``"coco"`` or ``"cartesian"``.
        batch_size: Mini-batch size (default ``512``).
        shuffle: Reshuffle each epoch.
        ur_weight: Uncertainty regularisation weight.
        ur_target: Uncertainty regularisation target.
        consequent_batch_norm: Batch normalisation on consequent layers.
        pfrb_max_rules: Maximum point-based FRB rules (unused by
            DombiTSK).
        patience: Early-stopping patience (default ``20``). Set to ``None`` to disable early stopping.
        restore_best: If ``True`` (default), restore the best validation
            model weights after training.
        weight_decay: L2 weight decay for consequent parameters.
    """
    super().__init__(
        input_configs=input_configs,
        n_mfs=n_mfs,
        mf_init=mf_init,
        sigma_scale=sigma_scale,
        random_state=random_state,
        epochs=epochs,
        learning_rate=learning_rate,
        verbose=verbose,
        rule_base=rule_base,
        batch_size=batch_size,
        shuffle=shuffle,
        ur_weight=ur_weight,
        ur_target=ur_target,
        consequent_batch_norm=consequent_batch_norm,
        pfrb_max_rules=pfrb_max_rules,
        patience=patience,
        restore_best=restore_best,
        weight_decay=weight_decay,
    )

`evaluate`

Compute classification evaluation metrics for the provided dataset.

Source code in highfis/estimators/_base.py

def evaluate(
    self,
    X: Any,
    y: Any,
    metrics: list[str] | None = None,
    sample_weight: Any | None = None,
) -> dict[str, float]:
    """Compute classification evaluation metrics for the provided dataset."""
    y_true = np.asarray(y)
    y_pred = self.predict(X)
    return compute_metrics(
        task="classification",
        y_true=y_true,
        y_pred=y_pred,
        sample_weight=sample_weight,
        metrics=metrics,
    )

`feature_importance`

Compute a normalized feature importance vector from consequent weights.

Source code in highfis/estimators/_base.py

def feature_importance(self) -> np.ndarray | None:
    """Compute a normalized feature importance vector from consequent weights."""
    check_is_fitted(self, "model_")
    weights = self.model_.get_consequent_weights()
    if weights is None:
        return None

    consequent_layer = self.model_.consequent_layer
    if hasattr(consequent_layer, "rule_feature_mask"):
        rule_feature_mask = cast(Tensor, consequent_layer.rule_feature_mask)
        weights = weights * rule_feature_mask.unsqueeze(1) if weights.ndim == 3 else weights * rule_feature_mask

    abs_weights = weights.abs()
    if abs_weights.ndim == 3:
        importance = abs_weights.mean(dim=(0, 1))
    elif abs_weights.ndim == 2:
        importance = abs_weights.mean(dim=0)
    else:
        raise ValueError("unsupported consequent weight shape for feature importance")

    return _normalize_importance(importance)

`fit`

Train the TSK classifier on labeled samples.

Validation data should be supplied using x_val and y_val when available.

Source code in highfis/estimators/_base.py

def fit(
    self,
    x: Any,
    y: Any,
    *,
    x_val: Any | None = None,
    y_val: Any | None = None,
) -> Self:
    """Train the TSK classifier on labeled samples.

    Validation data should be supplied using ``x_val`` and ``y_val``
    when available.
    """
    x_arr, y_arr = check_X_y(x, y)

    if self.random_state is not None:
        torch.manual_seed(int(self.random_state))

    le = LabelEncoder()
    y_idx = le.fit_transform(np.asarray(y_arr))

    input_mfs, feature_names, effective_rule_base = self._build_input_mfs(x_arr)

    self.n_features_in_ = x_arr.shape[1]
    self.feature_names_in_ = np.asarray(feature_names, dtype=object)
    self.classes_ = le.classes_
    self._label_encoder_ = le

    _device = torch.device(str(self.device))
    self.model_ = self._build_model(input_mfs, len(self.classes_), effective_rule_base).to(_device)

    y_t = torch.as_tensor(y_idx, dtype=torch.long, device=_device)

    # Prepare validation tensors if provided via fit.
    x_val_t: torch.Tensor | None = None
    y_val_t: torch.Tensor | None = None
    if (x_val is None) ^ (y_val is None):
        raise ValueError("x_val and y_val must be provided together")
    if x_val is not None and y_val is not None:
        x_v_arr, y_v_arr = check_X_y(x_val, y_val)
        x_val_t = self._as_tensor_x(x_v_arr, _device)
        y_val_idx = le.transform(np.asarray(y_v_arr))
        y_val_t = torch.as_tensor(y_val_idx, dtype=torch.long, device=_device)

    self.history_ = self.model_.fit(
        self._as_tensor_x(x_arr, _device),
        y_t,
        epochs=int(self.epochs),
        learning_rate=float(self.learning_rate),
        batch_size=self.batch_size,
        shuffle=bool(self.shuffle),
        ur_weight=float(self.ur_weight),
        ur_target=self.ur_target,
        verbose=self.verbose,
        x_val=x_val_t,
        y_val=y_val_t,
        patience=self.patience,
        restore_best=self.restore_best,
        weight_decay=float(self.weight_decay),
    )
    self.rule_base_ = effective_rule_base
    return self

`get_mf_params`

Return model membership function metadata after fitting.

Source code in highfis/estimators/_base.py

def get_mf_params(self) -> dict[str, list[dict[str, Any]]]:
    """Return model membership function metadata after fitting."""
    check_is_fitted(self, "model_")
    return self.model_.get_mf_params()

`inspect`

Return a structured summary of fitted model state and rule metadata.

Source code in highfis/estimators/_base.py

def inspect(self) -> dict[str, Any]:
    """Return a structured summary of fitted model state and rule metadata."""
    check_is_fitted(self, "model_")
    return {
        "n_rules": int(self.model_.n_rules),
        "n_inputs": int(self.model_.n_inputs),
        "feature_names": list(self.model_.input_names),
        "rule_base": self.rule_base_,
        "defuzzifier_type": type(self.model_.defuzzifier).__name__,
        "mf_params": self.get_mf_params(),
        "rule_table": self.model_.get_rule_table(),
    }

`load` `classmethod`

Load a persisted estimator created by save.

Source code in highfis/estimators/_base.py

@classmethod
def load(cls, path: str) -> Self:
    """Load a persisted estimator created by save."""
    checkpoint = load_checkpoint(path)
    validate_checkpoint_payload(checkpoint, expected_estimator_class=cls.__name__)

    params: dict[str, Any] = dict(checkpoint["estimator_params"])
    if params.get("input_configs") is not None:
        params["input_configs"] = [InputConfig(**c) for c in params["input_configs"]]
    estimator = cls(**params)
    model_init = checkpoint["model_init"]
    estimator.rule_base_ = model_init["rule_base"]
    estimator.model_ = estimator._build_model(
        deserialize_input_mfs(model_init["input_mfs_config"]),
        int(model_init["n_classes"]),
        str(model_init["rule_base"]),
    )
    estimator.model_.load_state_dict(checkpoint["model_state_dict"])
    estimator.model_.to(torch.device(str(estimator.device)))

    fitted = checkpoint["fitted_attrs"]
    estimator.n_features_in_ = int(fitted["n_features_in"])
    estimator.feature_names_in_ = np.asarray(fitted["feature_names_in"], dtype=object)
    estimator.classes_ = np.asarray(fitted["classes"], dtype=object)
    label_encoder = LabelEncoder()
    label_encoder.classes_ = estimator.classes_
    estimator._label_encoder_ = label_encoder
    estimator.history_ = cast(dict[str, Any], checkpoint.get("history", {}))
    return estimator

`predict`

Predict class labels for input samples.

Source code in highfis/estimators/_base.py

def predict(self, x: Any) -> np.ndarray:
    """Predict class labels for input samples."""
    proba = self.predict_proba(x)
    y_idx = np.argmax(proba, axis=1)
    return np.asarray(self._label_encoder_.inverse_transform(y_idx))

`predict_proba`

Predict class probabilities for input samples.

Source code in highfis/estimators/_base.py

def predict_proba(self, x: Any) -> np.ndarray:
    """Predict class probabilities for input samples."""
    check_is_fitted(self, "model_")
    x_arr = check_array(x)
    if x_arr.shape[1] != self.n_features_in_:
        raise ValueError(f"expected {self.n_features_in_} features, got {x_arr.shape[1]}")
    probs = cast(Any, self.model_).predict_proba(self._as_tensor_x(x_arr, torch.device(str(self.device))))
    return probs.detach().cpu().numpy()

`rule_activation`

Return normalized rule activations for the provided inputs.

Source code in highfis/estimators/_base.py

def rule_activation(self, X: Any) -> np.ndarray:
    """Return normalized rule activations for the provided inputs."""
    check_is_fitted(self, "model_")
    x_arr = check_array(X)
    if x_arr.shape[1] != self.n_features_in_:
        raise ValueError(f"expected {self.n_features_in_} features, got {x_arr.shape[1]}")

    was_training = self.model_.training
    try:
        self.model_.eval()
        with torch.no_grad():
            norm_w = self.model_.forward_antecedents(self._as_tensor_x(x_arr, torch.device(str(self.device))))
    finally:
        self.model_.train(was_training)

    return _to_numpy(norm_w)

`save`

Persist estimator configuration, model weights and fitted metadata.

Source code in highfis/estimators/_base.py

def save(self, path: str) -> None:
    """Persist estimator configuration, model weights and fitted metadata."""
    checkpoint = self._build_checkpoint_base(
        model_init={
            "input_mfs_config": serialize_input_mfs(self.model_.input_mfs),
            "n_classes": len(self.classes_),
            "rule_base": self.rule_base_,
        },
        fitted_attrs={
            "n_features_in": int(self.n_features_in_),
            "feature_names_in": self.feature_names_in_.tolist(),
            "classes": self.classes_.tolist(),
        },
    )
    save_checkpoint(path, checkpoint)

`score`

Return classification accuracy on the provided dataset.

Source code in highfis/estimators/_base.py

def score(self, X: Any, y: Any, sample_weight: Any = None) -> float:
    """Return classification accuracy on the provided dataset."""
    y_true = np.asarray(y)
    y_pred = self.predict(X)
    return float(accuracy_score(y_true, y_pred, sample_weight=sample_weight))

`DombiTSKRegressor`

Bases: _BaseRegressorEstimator

TSK regressor with a fixed Dombi T-norm in the antecedent.

DombiTSK extends TSK fuzzy inference by using a Dombi t-norm aggregation in antecedent evaluation while keeping first-order linear consequents.

Reference

G. Xue, L. Hu, J. Wang and S. Ablameyko, "ADMTSK: A High-Dimensional Takagi-Sugeno-Kang Fuzzy System Based on Adaptive Dombi T-Norm," in IEEE Transactions on Fuzzy Systems, vol. 33, no. 6, pp. 1767-1780, June 2025, doi: 10.1109/TFUZZ.2025.3535640.

Example

from highfis import DombiTSKRegressor

reg = DombiTSKRegressor(n_mfs=30, random_state=0)
reg.fit(X_train, y_train)

Initialise a DombiTSK regressor.

Parameters:

Name	Type	Description	Default
`input_configs`	`list[InputConfig] \| None`	Per-feature :class:`InputConfig` list. Only `name` is used when `mf_init="kmeans"`.	`None`
`n_mfs`	`int`	Number of k-means clusters / grid MFs (default `5`).	`5`
`mf_init`	`str`	`"kmeans"` (default), `"minibatch_kmeans"`, `"fcm"`, or `"grid"`.	`'kmeans'`
`sigma_scale`	`float \| str`	Sigma scale factor. `1.0` recommended.	`1.0`
`random_state`	`int \| None`	Seed for k-means and weight initialisation.	`None`
`epochs`	`int`	Maximum training epochs (default `10`).	`10`
`learning_rate`	`float`	Adam learning rate (default `0.01`).	`0.01`
`verbose`	`bool \| int`	Print per-epoch progress.	`False`
`rule_base`	`str \| None`	`"coco"` or `"cartesian"`.	`None`
`batch_size`	`int \| None`	Mini-batch size (default `512`).	`512`
`shuffle`	`bool`	Reshuffle each epoch.	`True`
`ur_weight`	`float`	Uncertainty regularisation weight.	`0.0`
`ur_target`	`float \| None`	Uncertainty regularisation target.	`None`
`consequent_batch_norm`	`bool`	Batch normalisation on consequent layers.	`False`
`patience`	`int \| None`	Early-stopping patience (default `20`). Set to `None` to disable early stopping.	`20`
`restore_best`	`bool`	If `True` (default), restore the best validation model weights after training.	`True`
`weight_decay`	`float`	L2 weight decay for consequent parameters.	`1e-08`

Source code in highfis/estimators/_dombi.py

def __init__(
    self,
    *,
    input_configs: list[InputConfig] | None = None,
    n_mfs: int = 5,
    mf_init: str = "kmeans",
    sigma_scale: float | str = 1.0,
    random_state: int | None = None,
    epochs: int = 10,
    learning_rate: float = 1e-2,
    verbose: bool | int = False,
    rule_base: str | None = None,
    batch_size: int | None = 512,
    shuffle: bool = True,
    ur_weight: float = 0.0,
    ur_target: float | None = None,
    consequent_batch_norm: bool = False,
    patience: int | None = 20,
    restore_best: bool = True,
    weight_decay: float = 1e-8,
) -> None:
    """Initialise a DombiTSK regressor.

    Args:
        input_configs: Per-feature :class:`InputConfig` list. Only
            ``name`` is used when ``mf_init="kmeans"``.
        n_mfs: Number of k-means clusters / grid MFs (default ``5``).
        mf_init: ``"kmeans"`` (default), ``"minibatch_kmeans"``, ``"fcm"``, or ``"grid"``.
        sigma_scale: Sigma scale factor. ``1.0`` recommended.
        random_state: Seed for k-means and weight initialisation.
        epochs: Maximum training epochs (default ``10``).
        learning_rate: Adam learning rate (default ``0.01``).
        verbose: Print per-epoch progress.
        rule_base: ``"coco"`` or ``"cartesian"``.
        batch_size: Mini-batch size (default ``512``).
        shuffle: Reshuffle each epoch.
        ur_weight: Uncertainty regularisation weight.
        ur_target: Uncertainty regularisation target.
        consequent_batch_norm: Batch normalisation on consequent layers.
        patience: Early-stopping patience (default ``20``). Set to ``None`` to disable early stopping.
        restore_best: If ``True`` (default), restore the best validation
            model weights after training.
        weight_decay: L2 weight decay for consequent parameters.
    """
    super().__init__(
        input_configs=input_configs,
        n_mfs=n_mfs,
        mf_init=mf_init,
        sigma_scale=sigma_scale,
        random_state=random_state,
        epochs=epochs,
        learning_rate=learning_rate,
        verbose=verbose,
        rule_base=rule_base,
        batch_size=batch_size,
        shuffle=shuffle,
        ur_weight=ur_weight,
        ur_target=ur_target,
        consequent_batch_norm=consequent_batch_norm,
        patience=patience,
        restore_best=restore_best,
        weight_decay=weight_decay,
    )

`evaluate`

Compute regression evaluation metrics for the provided dataset.

Source code in highfis/estimators/_base.py

def evaluate(
    self,
    X: Any,
    y: Any,
    metrics: list[str] | None = None,
    sample_weight: Any | None = None,
) -> dict[str, float]:
    """Compute regression evaluation metrics for the provided dataset."""
    y_true = np.asarray(y)
    y_pred = self.predict(X)
    return compute_metrics(
        task="regression",
        y_true=y_true,
        y_pred=y_pred,
        sample_weight=sample_weight,
        metrics=metrics,
    )

`feature_importance`

Compute a normalized feature importance vector from consequent weights.

Source code in highfis/estimators/_base.py

def feature_importance(self) -> np.ndarray | None:
    """Compute a normalized feature importance vector from consequent weights."""
    check_is_fitted(self, "model_")
    weights = self.model_.get_consequent_weights()
    if weights is None:
        return None

    consequent_layer = self.model_.consequent_layer
    if hasattr(consequent_layer, "rule_feature_mask"):
        rule_feature_mask = cast(Tensor, consequent_layer.rule_feature_mask)
        weights = weights * rule_feature_mask.unsqueeze(1) if weights.ndim == 3 else weights * rule_feature_mask

    abs_weights = weights.abs()
    if abs_weights.ndim == 3:
        importance = abs_weights.mean(dim=(0, 1))
    elif abs_weights.ndim == 2:
        importance = abs_weights.mean(dim=0)
    else:
        raise ValueError("unsupported consequent weight shape for feature importance")

    return _normalize_importance(importance)

`fit`

Train the TSK regressor on labeled samples.

Validation data should be supplied using x_val and y_val when available.

Source code in highfis/estimators/_base.py

def fit(
    self,
    x: Any,
    y: Any,
    *,
    x_val: Any | None = None,
    y_val: Any | None = None,
) -> Self:
    """Train the TSK regressor on labeled samples.

    Validation data should be supplied using ``x_val`` and ``y_val``
    when available.
    """
    x_arr, y_arr = check_X_y(x, y)

    if self.random_state is not None:
        torch.manual_seed(int(self.random_state))

    input_mfs, feature_names, effective_rule_base = self._build_input_mfs(x_arr)

    self.n_features_in_ = x_arr.shape[1]
    self.feature_names_in_ = np.asarray(feature_names, dtype=object)

    _device = torch.device(str(self.device))
    self.model_ = self._build_regressor_model(input_mfs, effective_rule_base).to(_device)

    y_t = torch.as_tensor(np.asarray(y_arr, dtype=np.float32), dtype=torch.float32, device=_device)

    # Prepare validation tensors if provided via fit.
    x_val_t: torch.Tensor | None = None
    y_val_t: torch.Tensor | None = None
    if (x_val is None) ^ (y_val is None):
        raise ValueError("x_val and y_val must be provided together")
    if x_val is not None and y_val is not None:
        x_v_arr, y_v_arr = check_X_y(x_val, y_val)
        x_val_t = self._as_tensor_x(x_v_arr, _device)
        y_val_t = torch.as_tensor(np.asarray(y_v_arr, dtype=np.float32), dtype=torch.float32, device=_device)

    self.history_ = self.model_.fit(
        self._as_tensor_x(x_arr, _device),
        y_t,
        epochs=int(self.epochs),
        learning_rate=float(self.learning_rate),
        batch_size=self.batch_size,
        shuffle=bool(self.shuffle),
        ur_weight=float(self.ur_weight),
        ur_target=self.ur_target,
        verbose=self.verbose,
        x_val=x_val_t,
        y_val=y_val_t,
        patience=self.patience,
        restore_best=self.restore_best,
        weight_decay=float(self.weight_decay),
    )
    self.rule_base_ = effective_rule_base
    return self

`get_mf_params`

Return model membership function metadata after fitting.

Source code in highfis/estimators/_base.py

def get_mf_params(self) -> dict[str, list[dict[str, Any]]]:
    """Return model membership function metadata after fitting."""
    check_is_fitted(self, "model_")
    return self.model_.get_mf_params()

`inspect`

Return a structured summary of fitted model state and rule metadata.

Source code in highfis/estimators/_base.py

def inspect(self) -> dict[str, Any]:
    """Return a structured summary of fitted model state and rule metadata."""
    check_is_fitted(self, "model_")
    return {
        "n_rules": int(self.model_.n_rules),
        "n_inputs": int(self.model_.n_inputs),
        "feature_names": list(self.model_.input_names),
        "rule_base": self.rule_base_,
        "defuzzifier_type": type(self.model_.defuzzifier).__name__,
        "mf_params": self.get_mf_params(),
        "rule_table": self.model_.get_rule_table(),
    }

`load` `classmethod`

Load a persisted estimator created by save.

Source code in highfis/estimators/_base.py

@classmethod
def load(cls, path: str) -> Self:
    """Load a persisted estimator created by save."""
    checkpoint = load_checkpoint(path)
    validate_checkpoint_payload(checkpoint, expected_estimator_class=cls.__name__)

    params: dict[str, Any] = dict(checkpoint["estimator_params"])
    if params.get("input_configs") is not None:
        params["input_configs"] = [InputConfig(**c) for c in params["input_configs"]]
    estimator = cls(**params)
    model_init = checkpoint["model_init"]
    estimator.rule_base_ = model_init["rule_base"]
    estimator.model_ = estimator._build_regressor_model(
        deserialize_input_mfs(model_init["input_mfs_config"]),
        str(model_init["rule_base"]),
    )
    estimator.model_.load_state_dict(checkpoint["model_state_dict"])
    estimator.model_.to(torch.device(str(estimator.device)))

    fitted = checkpoint["fitted_attrs"]
    estimator.n_features_in_ = int(fitted["n_features_in"])
    estimator.feature_names_in_ = np.asarray(fitted["feature_names_in"], dtype=object)
    estimator.history_ = cast(dict[str, Any], checkpoint.get("history", {}))
    return estimator

`predict`

Predict continuous target values for input samples.

Source code in highfis/estimators/_base.py

def predict(self, x: Any) -> np.ndarray:
    """Predict continuous target values for input samples."""
    check_is_fitted(self, "model_")
    x_arr = check_array(x)
    if x_arr.shape[1] != self.n_features_in_:
        raise ValueError(f"expected {self.n_features_in_} features, got {x_arr.shape[1]}")
    preds = cast(Any, self.model_).predict(self._as_tensor_x(x_arr, torch.device(str(self.device))))
    return preds.detach().cpu().numpy()

`rule_activation`

Return normalized rule activations for the provided inputs.

Source code in highfis/estimators/_base.py

def rule_activation(self, X: Any) -> np.ndarray:
    """Return normalized rule activations for the provided inputs."""
    check_is_fitted(self, "model_")
    x_arr = check_array(X)
    if x_arr.shape[1] != self.n_features_in_:
        raise ValueError(f"expected {self.n_features_in_} features, got {x_arr.shape[1]}")

    was_training = self.model_.training
    try:
        self.model_.eval()
        with torch.no_grad():
            norm_w = self.model_.forward_antecedents(self._as_tensor_x(x_arr, torch.device(str(self.device))))
    finally:
        self.model_.train(was_training)

    return _to_numpy(norm_w)

`save`

Persist estimator configuration, model weights and fitted metadata.

Source code in highfis/estimators/_base.py

def save(self, path: str) -> None:
    """Persist estimator configuration, model weights and fitted metadata."""
    checkpoint = self._build_checkpoint_base(
        model_init={
            "input_mfs_config": serialize_input_mfs(self.model_.input_mfs),
            "rule_base": self.rule_base_,
        },
        fitted_attrs={
            "n_features_in": int(self.n_features_in_),
            "feature_names_in": self.feature_names_in_.tolist(),
        },
    )
    save_checkpoint(path, checkpoint)

`FSREADATSKClassifier`

Bases: _BaseClassifierEstimator

FSRE-ADATSK classifier with adaptive softmin antecedent and gated consequents.

FSRE-ADATSK (Feature Selection and Rule Extraction) extends ADATSK.

Reference

G. Xue, Q. Chang, J. Wang, K. Zhang and N. R. Pal, "An Adaptive Neuro-Fuzzy System With Integrated Feature Selection and Rule Extraction for High-Dimensional Classification Problems," in IEEE Transactions on Fuzzy Systems, vol. 31, no. 7, pp. 2167-2181, July 2023, doi: 10.1109/TFUZZ.2022.3220950.

Example

from highfis import FSREADATSKClassifier

clf = FSREADATSKClassifier()
clf.fit(X_train, y_train)

Initialise an FSRE-ADATSK classifier.

Parameters:

Name	Type	Description	Default
`lambda_init`	`float`	Accepted for API compatibility but not used by FSRE-ADATSK or DG-ALETSK. FSRE-ADATSK computes its adaptive softmin index directly from membership values; DG-ALETSK uses the fixed exponent `ξ = 700` per paper eq. 22. Default `1.0`.	`1.0`
`use_en_frb`	`bool`	If `True`, use the Enhanced FRB (En-FRB) whose size grows linearly with the number of features, allowing more candidate rules for the RE phase. Xue et al. (2023) activate En-FRB after the FS phase; set `False` (default) to keep the compact CoCo-FRB.	`False`
`input_configs`	`list[InputConfig] \| None`	Per-feature :class:`InputConfig` list. Only `name` is used when `mf_init="kmeans"`.	`None`
`n_mfs`	`int`	Number of k-means clusters / grid MFs (default `5`).	`5`
`mf_init`	`str`	`"kmeans"` (default), `"minibatch_kmeans"`, `"fcm"`, or `"grid"`.	`'kmeans'`
`sigma_scale`	`float \| str`	Sigma scale factor. `1.0` recommended.	`1.0`
`random_state`	`int \| None`	Seed for k-means and weight initialisation.	`None`
`epochs`	`int`	Maximum training epochs (default `10`).	`10`
`learning_rate`	`float`	Adam learning rate (default `0.01`).	`0.01`
`verbose`	`bool \| int`	Print per-epoch progress.	`False`
`rule_base`	`str \| None`	`"coco"` or `"cartesian"`.	`None`
`batch_size`	`int \| None`	Mini-batch size (default `512`).	`512`
`shuffle`	`bool`	Reshuffle each epoch.	`True`
`ur_weight`	`float`	Uncertainty regularisation weight.	`0.0`
`ur_target`	`float \| None`	Uncertainty regularisation target.	`None`
`consequent_batch_norm`	`bool`	Batch normalisation on consequent layers.	`False`
`patience`	`int \| None`	Early-stopping patience (default `20`). Set to `None` to disable early stopping.	`20`
`restore_best`	`bool`	If `True` (default), restore the best validation model weights after training.	`True`
`weight_decay`	`float`	L2 weight decay for consequent parameters.	`1e-08`

Raises:

Type	Description
`ValueError`	If `lambda_init <= 0`.

Source code in highfis/estimators/_fsre.py

def __init__(
    self,
    *,
    lambda_init: float = 1.0,
    use_en_frb: bool = False,
    input_configs: list[InputConfig] | None = None,
    n_mfs: int = 5,
    mf_init: str = "kmeans",
    sigma_scale: float | str = 1.0,
    random_state: int | None = None,
    epochs: int = 10,
    learning_rate: float = 1e-2,
    verbose: bool | int = False,
    rule_base: str | None = None,
    batch_size: int | None = 512,
    shuffle: bool = True,
    ur_weight: float = 0.0,
    ur_target: float | None = None,
    consequent_batch_norm: bool = False,
    patience: int | None = 20,
    restore_best: bool = True,
    weight_decay: float = 1e-8,
) -> None:
    """Initialise an FSRE-ADATSK classifier.

    Args:
        lambda_init: Accepted for API compatibility but not used by
            FSRE-ADATSK or DG-ALETSK.  FSRE-ADATSK computes its
            adaptive softmin index directly from membership values;
            DG-ALETSK uses the fixed exponent ``ξ = 700`` per
            paper eq. 22.  Default ``1.0``.
        use_en_frb: If ``True``, use the Enhanced FRB (En-FRB) whose
            size grows linearly with the number of features, allowing
            more candidate rules for the RE phase. Xue et al. (2023)
            activate En-FRB after the FS phase; set ``False`` (default)
            to keep the compact CoCo-FRB.
        input_configs: Per-feature :class:`InputConfig` list. Only
            ``name`` is used when ``mf_init="kmeans"``.
        n_mfs: Number of k-means clusters / grid MFs (default ``5``).
        mf_init: ``"kmeans"`` (default), ``"minibatch_kmeans"``, ``"fcm"``, or ``"grid"``.
        sigma_scale: Sigma scale factor. ``1.0`` recommended.
        random_state: Seed for k-means and weight initialisation.
        epochs: Maximum training epochs (default ``10``).
        learning_rate: Adam learning rate (default ``0.01``).
        verbose: Print per-epoch progress.
        rule_base: ``"coco"`` or ``"cartesian"``.
        batch_size: Mini-batch size (default ``512``).
        shuffle: Reshuffle each epoch.
        ur_weight: Uncertainty regularisation weight.
        ur_target: Uncertainty regularisation target.
        consequent_batch_norm: Batch normalisation on consequent layers.
        patience: Early-stopping patience (default ``20``). Set to ``None`` to disable early stopping.
        restore_best: If ``True`` (default), restore the best validation
            model weights after training.
        weight_decay: L2 weight decay for consequent parameters.

    Raises:
        ValueError: If ``lambda_init <= 0``.
    """
    if lambda_init <= 0.0:
        raise ValueError("lambda_init must be > 0")
    self.lambda_init = float(lambda_init)
    self.use_en_frb = bool(use_en_frb)
    super().__init__(
        input_configs=input_configs,
        n_mfs=n_mfs,
        mf_init=mf_init,
        sigma_scale=sigma_scale,
        random_state=random_state,
        epochs=epochs,
        learning_rate=learning_rate,
        verbose=verbose,
        rule_base=rule_base,
        batch_size=batch_size,
        shuffle=shuffle,
        ur_weight=ur_weight,
        ur_target=ur_target,
        consequent_batch_norm=consequent_batch_norm,
        patience=patience,
        restore_best=restore_best,
        weight_decay=weight_decay,
    )

`evaluate`

Compute classification evaluation metrics for the provided dataset.

Source code in highfis/estimators/_base.py

def evaluate(
    self,
    X: Any,
    y: Any,
    metrics: list[str] | None = None,
    sample_weight: Any | None = None,
) -> dict[str, float]:
    """Compute classification evaluation metrics for the provided dataset."""
    y_true = np.asarray(y)
    y_pred = self.predict(X)
    return compute_metrics(
        task="classification",
        y_true=y_true,
        y_pred=y_pred,
        sample_weight=sample_weight,
        metrics=metrics,
    )

`feature_importance`

Compute a normalized feature importance vector from consequent weights.

Source code in highfis/estimators/_base.py

def feature_importance(self) -> np.ndarray | None:
    """Compute a normalized feature importance vector from consequent weights."""
    check_is_fitted(self, "model_")
    weights = self.model_.get_consequent_weights()
    if weights is None:
        return None

    consequent_layer = self.model_.consequent_layer
    if hasattr(consequent_layer, "rule_feature_mask"):
        rule_feature_mask = cast(Tensor, consequent_layer.rule_feature_mask)
        weights = weights * rule_feature_mask.unsqueeze(1) if weights.ndim == 3 else weights * rule_feature_mask

    abs_weights = weights.abs()
    if abs_weights.ndim == 3:
        importance = abs_weights.mean(dim=(0, 1))
    elif abs_weights.ndim == 2:
        importance = abs_weights.mean(dim=0)
    else:
        raise ValueError("unsupported consequent weight shape for feature importance")

    return _normalize_importance(importance)

`fit`

Train the TSK classifier on labeled samples.

Validation data should be supplied using x_val and y_val when available.

Source code in highfis/estimators/_base.py

def fit(
    self,
    x: Any,
    y: Any,
    *,
    x_val: Any | None = None,
    y_val: Any | None = None,
) -> Self:
    """Train the TSK classifier on labeled samples.

    Validation data should be supplied using ``x_val`` and ``y_val``
    when available.
    """
    x_arr, y_arr = check_X_y(x, y)

    if self.random_state is not None:
        torch.manual_seed(int(self.random_state))

    le = LabelEncoder()
    y_idx = le.fit_transform(np.asarray(y_arr))

    input_mfs, feature_names, effective_rule_base = self._build_input_mfs(x_arr)

    self.n_features_in_ = x_arr.shape[1]
    self.feature_names_in_ = np.asarray(feature_names, dtype=object)
    self.classes_ = le.classes_
    self._label_encoder_ = le

    _device = torch.device(str(self.device))
    self.model_ = self._build_model(input_mfs, len(self.classes_), effective_rule_base).to(_device)

    y_t = torch.as_tensor(y_idx, dtype=torch.long, device=_device)

    # Prepare validation tensors if provided via fit.
    x_val_t: torch.Tensor | None = None
    y_val_t: torch.Tensor | None = None
    if (x_val is None) ^ (y_val is None):
        raise ValueError("x_val and y_val must be provided together")
    if x_val is not None and y_val is not None:
        x_v_arr, y_v_arr = check_X_y(x_val, y_val)
        x_val_t = self._as_tensor_x(x_v_arr, _device)
        y_val_idx = le.transform(np.asarray(y_v_arr))
        y_val_t = torch.as_tensor(y_val_idx, dtype=torch.long, device=_device)

    self.history_ = self.model_.fit(
        self._as_tensor_x(x_arr, _device),
        y_t,
        epochs=int(self.epochs),
        learning_rate=float(self.learning_rate),
        batch_size=self.batch_size,
        shuffle=bool(self.shuffle),
        ur_weight=float(self.ur_weight),
        ur_target=self.ur_target,
        verbose=self.verbose,
        x_val=x_val_t,
        y_val=y_val_t,
        patience=self.patience,
        restore_best=self.restore_best,
        weight_decay=float(self.weight_decay),
    )
    self.rule_base_ = effective_rule_base
    return self

`get_mf_params`

Return model membership function metadata after fitting.

Source code in highfis/estimators/_base.py

def get_mf_params(self) -> dict[str, list[dict[str, Any]]]:
    """Return model membership function metadata after fitting."""
    check_is_fitted(self, "model_")
    return self.model_.get_mf_params()

`inspect`

Return a structured summary of fitted model state and rule metadata.

Source code in highfis/estimators/_base.py

def inspect(self) -> dict[str, Any]:
    """Return a structured summary of fitted model state and rule metadata."""
    check_is_fitted(self, "model_")
    return {
        "n_rules": int(self.model_.n_rules),
        "n_inputs": int(self.model_.n_inputs),
        "feature_names": list(self.model_.input_names),
        "rule_base": self.rule_base_,
        "defuzzifier_type": type(self.model_.defuzzifier).__name__,
        "mf_params": self.get_mf_params(),
        "rule_table": self.model_.get_rule_table(),
    }

`load` `classmethod`

Load a persisted estimator created by save.

Source code in highfis/estimators/_base.py

@classmethod
def load(cls, path: str) -> Self:
    """Load a persisted estimator created by save."""
    checkpoint = load_checkpoint(path)
    validate_checkpoint_payload(checkpoint, expected_estimator_class=cls.__name__)

    params: dict[str, Any] = dict(checkpoint["estimator_params"])
    if params.get("input_configs") is not None:
        params["input_configs"] = [InputConfig(**c) for c in params["input_configs"]]
    estimator = cls(**params)
    model_init = checkpoint["model_init"]
    estimator.rule_base_ = model_init["rule_base"]
    estimator.model_ = estimator._build_model(
        deserialize_input_mfs(model_init["input_mfs_config"]),
        int(model_init["n_classes"]),
        str(model_init["rule_base"]),
    )
    estimator.model_.load_state_dict(checkpoint["model_state_dict"])
    estimator.model_.to(torch.device(str(estimator.device)))

    fitted = checkpoint["fitted_attrs"]
    estimator.n_features_in_ = int(fitted["n_features_in"])
    estimator.feature_names_in_ = np.asarray(fitted["feature_names_in"], dtype=object)
    estimator.classes_ = np.asarray(fitted["classes"], dtype=object)
    label_encoder = LabelEncoder()
    label_encoder.classes_ = estimator.classes_
    estimator._label_encoder_ = label_encoder
    estimator.history_ = cast(dict[str, Any], checkpoint.get("history", {}))
    return estimator

`predict`

Predict class labels for input samples.

Source code in highfis/estimators/_base.py

def predict(self, x: Any) -> np.ndarray:
    """Predict class labels for input samples."""
    proba = self.predict_proba(x)
    y_idx = np.argmax(proba, axis=1)
    return np.asarray(self._label_encoder_.inverse_transform(y_idx))

`predict_proba`

Predict class probabilities for input samples.

Source code in highfis/estimators/_base.py

def predict_proba(self, x: Any) -> np.ndarray:
    """Predict class probabilities for input samples."""
    check_is_fitted(self, "model_")
    x_arr = check_array(x)
    if x_arr.shape[1] != self.n_features_in_:
        raise ValueError(f"expected {self.n_features_in_} features, got {x_arr.shape[1]}")
    probs = cast(Any, self.model_).predict_proba(self._as_tensor_x(x_arr, torch.device(str(self.device))))
    return probs.detach().cpu().numpy()

`rule_activation`

Return normalized rule activations for the provided inputs.

Source code in highfis/estimators/_base.py

def rule_activation(self, X: Any) -> np.ndarray:
    """Return normalized rule activations for the provided inputs."""
    check_is_fitted(self, "model_")
    x_arr = check_array(X)
    if x_arr.shape[1] != self.n_features_in_:
        raise ValueError(f"expected {self.n_features_in_} features, got {x_arr.shape[1]}")

    was_training = self.model_.training
    try:
        self.model_.eval()
        with torch.no_grad():
            norm_w = self.model_.forward_antecedents(self._as_tensor_x(x_arr, torch.device(str(self.device))))
    finally:
        self.model_.train(was_training)

    return _to_numpy(norm_w)

`save`

Persist estimator configuration, model weights and fitted metadata.

Source code in highfis/estimators/_base.py

def save(self, path: str) -> None:
    """Persist estimator configuration, model weights and fitted metadata."""
    checkpoint = self._build_checkpoint_base(
        model_init={
            "input_mfs_config": serialize_input_mfs(self.model_.input_mfs),
            "n_classes": len(self.classes_),
            "rule_base": self.rule_base_,
        },
        fitted_attrs={
            "n_features_in": int(self.n_features_in_),
            "feature_names_in": self.feature_names_in_.tolist(),
            "classes": self.classes_.tolist(),
        },
    )
    save_checkpoint(path, checkpoint)

`score`

Return classification accuracy on the provided dataset.

Source code in highfis/estimators/_base.py

def score(self, X: Any, y: Any, sample_weight: Any = None) -> float:
    """Return classification accuracy on the provided dataset."""
    y_true = np.asarray(y)
    y_pred = self.predict(X)
    return float(accuracy_score(y_true, y_pred, sample_weight=sample_weight))

`FSREADATSKRegressor`

Bases: _BaseRegressorEstimator

FSRE-ADATSK regressor with adaptive softmin antecedent and gated consequents.

FSRE-ADATSK (Feature Selection and Rule Extraction) extends ADATSK.

Reference

G. Xue, Q. Chang, J. Wang, K. Zhang and N. R. Pal, "An Adaptive Neuro-Fuzzy System With Integrated Feature Selection and Rule Extraction for High-Dimensional Classification Problems," in IEEE Transactions on Fuzzy Systems, vol. 31, no. 7, pp. 2167-2181, July 2023, doi: 10.1109/TFUZZ.2022.3220950.

Example

from highfis import FSREADATSKRegressor

reg = FSREADATSKRegressor()
reg.fit(X_train, y_train)

Initialise an FSRE-ADATSK regressor.

Parameters:

Name	Type	Description	Default
`lambda_init`	`float`	Accepted for API compatibility but not used by FSRE-ADATSK or DG-ALETSK. FSRE-ADATSK computes its adaptive softmin index directly from membership values; DG-ALETSK uses the fixed exponent `ξ = 700` per paper eq. 22. Default `1.0`.	`1.0`
`use_en_frb`	`bool`	If `True`, use the Enhanced FRB (En-FRB) for rule extraction. Default `False` keeps CoCo-FRB.	`False`
`input_configs`	`list[InputConfig] \| None`	Per-feature :class:`InputConfig` list. Only `name` is used when `mf_init="kmeans"`.	`None`
`n_mfs`	`int`	Number of k-means clusters / grid MFs (default `5`).	`5`
`mf_init`	`str`	`"kmeans"` (default), `"minibatch_kmeans"`, `"fcm"`, or `"grid"`.	`'kmeans'`
`sigma_scale`	`float \| str`	Sigma scale factor. `1.0` recommended.	`1.0`
`random_state`	`int \| None`	Seed for k-means and weight initialisation.	`None`
`epochs`	`int`	Maximum training epochs (default `10`).	`10`
`learning_rate`	`float`	Adam learning rate (default `0.01`).	`0.01`
`verbose`	`bool \| int`	Print per-epoch progress.	`False`
`rule_base`	`str \| None`	`"coco"` or `"cartesian"`.	`None`
`batch_size`	`int \| None`	Mini-batch size (default `512`).	`512`
`shuffle`	`bool`	Reshuffle each epoch.	`True`
`ur_weight`	`float`	Uncertainty regularisation weight.	`0.0`
`ur_target`	`float \| None`	Uncertainty regularisation target.	`None`
`consequent_batch_norm`	`bool`	Batch normalisation on consequent layers.	`False`
`patience`	`int \| None`	Early-stopping patience (default `20`). Set to `None` to disable early stopping.	`20`
`restore_best`	`bool`	If `True` (default), restore the best validation model weights after training.	`True`
`weight_decay`	`float`	L2 weight decay for consequent parameters.	`1e-08`

Raises:

Type	Description
`ValueError`	If `lambda_init <= 0`.

Source code in highfis/estimators/_fsre.py

def __init__(
    self,
    *,
    lambda_init: float = 1.0,
    use_en_frb: bool = False,
    input_configs: list[InputConfig] | None = None,
    n_mfs: int = 5,
    mf_init: str = "kmeans",
    sigma_scale: float | str = 1.0,
    random_state: int | None = None,
    epochs: int = 10,
    learning_rate: float = 1e-2,
    verbose: bool | int = False,
    rule_base: str | None = None,
    batch_size: int | None = 512,
    shuffle: bool = True,
    ur_weight: float = 0.0,
    ur_target: float | None = None,
    consequent_batch_norm: bool = False,
    patience: int | None = 20,
    restore_best: bool = True,
    weight_decay: float = 1e-8,
) -> None:
    """Initialise an FSRE-ADATSK regressor.

    Args:
        lambda_init: Accepted for API compatibility but not used by
            FSRE-ADATSK or DG-ALETSK.  FSRE-ADATSK computes its
            adaptive softmin index directly from membership values;
            DG-ALETSK uses the fixed exponent ``ξ = 700`` per
            paper eq. 22.  Default ``1.0``.
        use_en_frb: If ``True``, use the Enhanced FRB (En-FRB) for rule
            extraction. Default ``False`` keeps CoCo-FRB.
        input_configs: Per-feature :class:`InputConfig` list. Only
            ``name`` is used when ``mf_init="kmeans"``.
        n_mfs: Number of k-means clusters / grid MFs (default ``5``).
        mf_init: ``"kmeans"`` (default), ``"minibatch_kmeans"``, ``"fcm"``, or ``"grid"``.
        sigma_scale: Sigma scale factor. ``1.0`` recommended.
        random_state: Seed for k-means and weight initialisation.
        epochs: Maximum training epochs (default ``10``).
        learning_rate: Adam learning rate (default ``0.01``).
        verbose: Print per-epoch progress.
        rule_base: ``"coco"`` or ``"cartesian"``.
        batch_size: Mini-batch size (default ``512``).
        shuffle: Reshuffle each epoch.
        ur_weight: Uncertainty regularisation weight.
        ur_target: Uncertainty regularisation target.
        consequent_batch_norm: Batch normalisation on consequent layers.
        patience: Early-stopping patience (default ``20``). Set to ``None`` to disable early stopping.
        restore_best: If ``True`` (default), restore the best validation
            model weights after training.
        weight_decay: L2 weight decay for consequent parameters.

    Raises:
        ValueError: If ``lambda_init <= 0``.
    """
    if lambda_init <= 0.0:
        raise ValueError("lambda_init must be > 0")
    self.lambda_init = float(lambda_init)
    self.use_en_frb = bool(use_en_frb)
    super().__init__(
        input_configs=input_configs,
        n_mfs=n_mfs,
        mf_init=mf_init,
        sigma_scale=sigma_scale,
        random_state=random_state,
        epochs=epochs,
        learning_rate=learning_rate,
        verbose=verbose,
        rule_base=rule_base,
        batch_size=batch_size,
        shuffle=shuffle,
        ur_weight=ur_weight,
        ur_target=ur_target,
        consequent_batch_norm=consequent_batch_norm,
        patience=patience,
        restore_best=restore_best,
        weight_decay=weight_decay,
    )

`evaluate`

Compute regression evaluation metrics for the provided dataset.

Source code in highfis/estimators/_base.py

def evaluate(
    self,
    X: Any,
    y: Any,
    metrics: list[str] | None = None,
    sample_weight: Any | None = None,
) -> dict[str, float]:
    """Compute regression evaluation metrics for the provided dataset."""
    y_true = np.asarray(y)
    y_pred = self.predict(X)
    return compute_metrics(
        task="regression",
        y_true=y_true,
        y_pred=y_pred,
        sample_weight=sample_weight,
        metrics=metrics,
    )

`feature_importance`

Compute a normalized feature importance vector from consequent weights.

Source code in highfis/estimators/_base.py

def feature_importance(self) -> np.ndarray | None:
    """Compute a normalized feature importance vector from consequent weights."""
    check_is_fitted(self, "model_")
    weights = self.model_.get_consequent_weights()
    if weights is None:
        return None

    consequent_layer = self.model_.consequent_layer
    if hasattr(consequent_layer, "rule_feature_mask"):
        rule_feature_mask = cast(Tensor, consequent_layer.rule_feature_mask)
        weights = weights * rule_feature_mask.unsqueeze(1) if weights.ndim == 3 else weights * rule_feature_mask

    abs_weights = weights.abs()
    if abs_weights.ndim == 3:
        importance = abs_weights.mean(dim=(0, 1))
    elif abs_weights.ndim == 2:
        importance = abs_weights.mean(dim=0)
    else:
        raise ValueError("unsupported consequent weight shape for feature importance")

    return _normalize_importance(importance)

`fit`

Train the TSK regressor on labeled samples.

Validation data should be supplied using x_val and y_val when available.

Source code in highfis/estimators/_base.py

def fit(
    self,
    x: Any,
    y: Any,
    *,
    x_val: Any | None = None,
    y_val: Any | None = None,
) -> Self:
    """Train the TSK regressor on labeled samples.

    Validation data should be supplied using ``x_val`` and ``y_val``
    when available.
    """
    x_arr, y_arr = check_X_y(x, y)

    if self.random_state is not None:
        torch.manual_seed(int(self.random_state))

    input_mfs, feature_names, effective_rule_base = self._build_input_mfs(x_arr)

    self.n_features_in_ = x_arr.shape[1]
    self.feature_names_in_ = np.asarray(feature_names, dtype=object)

    _device = torch.device(str(self.device))
    self.model_ = self._build_regressor_model(input_mfs, effective_rule_base).to(_device)

    y_t = torch.as_tensor(np.asarray(y_arr, dtype=np.float32), dtype=torch.float32, device=_device)

    # Prepare validation tensors if provided via fit.
    x_val_t: torch.Tensor | None = None
    y_val_t: torch.Tensor | None = None
    if (x_val is None) ^ (y_val is None):
        raise ValueError("x_val and y_val must be provided together")
    if x_val is not None and y_val is not None:
        x_v_arr, y_v_arr = check_X_y(x_val, y_val)
        x_val_t = self._as_tensor_x(x_v_arr, _device)
        y_val_t = torch.as_tensor(np.asarray(y_v_arr, dtype=np.float32), dtype=torch.float32, device=_device)

    self.history_ = self.model_.fit(
        self._as_tensor_x(x_arr, _device),
        y_t,
        epochs=int(self.epochs),
        learning_rate=float(self.learning_rate),
        batch_size=self.batch_size,
        shuffle=bool(self.shuffle),
        ur_weight=float(self.ur_weight),
        ur_target=self.ur_target,
        verbose=self.verbose,
        x_val=x_val_t,
        y_val=y_val_t,
        patience=self.patience,
        restore_best=self.restore_best,
        weight_decay=float(self.weight_decay),
    )
    self.rule_base_ = effective_rule_base
    return self

`get_mf_params`

Return model membership function metadata after fitting.

Source code in highfis/estimators/_base.py

def get_mf_params(self) -> dict[str, list[dict[str, Any]]]:
    """Return model membership function metadata after fitting."""
    check_is_fitted(self, "model_")
    return self.model_.get_mf_params()

`inspect`

Return a structured summary of fitted model state and rule metadata.

Source code in highfis/estimators/_base.py

def inspect(self) -> dict[str, Any]:
    """Return a structured summary of fitted model state and rule metadata."""
    check_is_fitted(self, "model_")
    return {
        "n_rules": int(self.model_.n_rules),
        "n_inputs": int(self.model_.n_inputs),
        "feature_names": list(self.model_.input_names),
        "rule_base": self.rule_base_,
        "defuzzifier_type": type(self.model_.defuzzifier).__name__,
        "mf_params": self.get_mf_params(),
        "rule_table": self.model_.get_rule_table(),
    }

`load` `classmethod`

Load a persisted estimator created by save.

Source code in highfis/estimators/_base.py

@classmethod
def load(cls, path: str) -> Self:
    """Load a persisted estimator created by save."""
    checkpoint = load_checkpoint(path)
    validate_checkpoint_payload(checkpoint, expected_estimator_class=cls.__name__)

    params: dict[str, Any] = dict(checkpoint["estimator_params"])
    if params.get("input_configs") is not None:
        params["input_configs"] = [InputConfig(**c) for c in params["input_configs"]]
    estimator = cls(**params)
    model_init = checkpoint["model_init"]
    estimator.rule_base_ = model_init["rule_base"]
    estimator.model_ = estimator._build_regressor_model(
        deserialize_input_mfs(model_init["input_mfs_config"]),
        str(model_init["rule_base"]),
    )
    estimator.model_.load_state_dict(checkpoint["model_state_dict"])
    estimator.model_.to(torch.device(str(estimator.device)))

    fitted = checkpoint["fitted_attrs"]
    estimator.n_features_in_ = int(fitted["n_features_in"])
    estimator.feature_names_in_ = np.asarray(fitted["feature_names_in"], dtype=object)
    estimator.history_ = cast(dict[str, Any], checkpoint.get("history", {}))
    return estimator

`predict`

Predict continuous target values for input samples.

Source code in highfis/estimators/_base.py

def predict(self, x: Any) -> np.ndarray:
    """Predict continuous target values for input samples."""
    check_is_fitted(self, "model_")
    x_arr = check_array(x)
    if x_arr.shape[1] != self.n_features_in_:
        raise ValueError(f"expected {self.n_features_in_} features, got {x_arr.shape[1]}")
    preds = cast(Any, self.model_).predict(self._as_tensor_x(x_arr, torch.device(str(self.device))))
    return preds.detach().cpu().numpy()

`rule_activation`

Return normalized rule activations for the provided inputs.

Source code in highfis/estimators/_base.py

def rule_activation(self, X: Any) -> np.ndarray:
    """Return normalized rule activations for the provided inputs."""
    check_is_fitted(self, "model_")
    x_arr = check_array(X)
    if x_arr.shape[1] != self.n_features_in_:
        raise ValueError(f"expected {self.n_features_in_} features, got {x_arr.shape[1]}")

    was_training = self.model_.training
    try:
        self.model_.eval()
        with torch.no_grad():
            norm_w = self.model_.forward_antecedents(self._as_tensor_x(x_arr, torch.device(str(self.device))))
    finally:
        self.model_.train(was_training)

    return _to_numpy(norm_w)

`save`

Persist estimator configuration, model weights and fitted metadata.

Source code in highfis/estimators/_base.py

def save(self, path: str) -> None:
    """Persist estimator configuration, model weights and fitted metadata."""
    checkpoint = self._build_checkpoint_base(
        model_init={
            "input_mfs_config": serialize_input_mfs(self.model_.input_mfs),
            "rule_base": self.rule_base_,
        },
        fitted_attrs={
            "n_features_in": int(self.n_features_in_),
            "feature_names_in": self.feature_names_in_.tolist(),
        },
    )
    save_checkpoint(path, checkpoint)

`HDFISMinClassifier`

Bases: _BaseClassifierEstimator

HDFIS-min classifier estimator with minimum T-norm antecedents.

HDFIS-min freezes antecedent membership parameters and uses a minimum T-norm aggregation in the antecedent, so that only consequent parameters are optimized during training. This matches the paper's observation that minimum-based high-dimensional inference is best handled by fixing the antecedent structure and training the rule consequents.

References

G. Xue, J. Wang, K. Zhang and N. R. Pal, "High-Dimensional Fuzzy Inference Systems," in IEEE Transactions on Systems, Man, and Cybernetics: Systems, vol. 54, no. 1, pp. 507-519, Jan. 2024, doi: 10.1109/TSMC.2023.3311475.

Example

from highfis import HDFISMinClassifier

clf = HDFISMinClassifier()
clf.fit(X_train, y_train)
preds = clf.predict(X_test)

Initialise an HDFIS-min classifier estimator.

Source code in highfis/estimators/_hdfis.py

def __init__(
    self,
    *,
    input_configs: list[InputConfig] | None = None,
    n_mfs: int = 5,
    mf_init: str = "kmeans",
    sigma_scale: float | str = 1.0,
    random_state: int | None = None,
    epochs: int = 10,
    learning_rate: float = 1e-2,
    verbose: bool | int = False,
    rule_base: str | None = None,
    batch_size: int | None = 512,
    shuffle: bool = True,
    ur_weight: float = 0.0,
    ur_target: float | None = None,
    consequent_batch_norm: bool = False,
    pfrb_max_rules: int | None = None,
    patience: int | None = 20,
    restore_best: bool = True,
    weight_decay: float = 1e-8,
) -> None:
    """Initialise an HDFIS-min classifier estimator."""
    super().__init__(
        input_configs=input_configs,
        n_mfs=n_mfs,
        mf_init=mf_init,
        sigma_scale=sigma_scale,
        random_state=random_state,
        epochs=epochs,
        learning_rate=learning_rate,
        verbose=verbose,
        rule_base=rule_base,
        batch_size=batch_size,
        shuffle=shuffle,
        ur_weight=ur_weight,
        ur_target=ur_target,
        consequent_batch_norm=consequent_batch_norm,
        pfrb_max_rules=pfrb_max_rules,
        patience=patience,
        restore_best=restore_best,
        weight_decay=weight_decay,
    )

`evaluate`

Compute classification evaluation metrics for the provided dataset.

Source code in highfis/estimators/_base.py

def evaluate(
    self,
    X: Any,
    y: Any,
    metrics: list[str] | None = None,
    sample_weight: Any | None = None,
) -> dict[str, float]:
    """Compute classification evaluation metrics for the provided dataset."""
    y_true = np.asarray(y)
    y_pred = self.predict(X)
    return compute_metrics(
        task="classification",
        y_true=y_true,
        y_pred=y_pred,
        sample_weight=sample_weight,
        metrics=metrics,
    )

`feature_importance`

Compute a normalized feature importance vector from consequent weights.

Source code in highfis/estimators/_base.py

def feature_importance(self) -> np.ndarray | None:
    """Compute a normalized feature importance vector from consequent weights."""
    check_is_fitted(self, "model_")
    weights = self.model_.get_consequent_weights()
    if weights is None:
        return None

    consequent_layer = self.model_.consequent_layer
    if hasattr(consequent_layer, "rule_feature_mask"):
        rule_feature_mask = cast(Tensor, consequent_layer.rule_feature_mask)
        weights = weights * rule_feature_mask.unsqueeze(1) if weights.ndim == 3 else weights * rule_feature_mask

    abs_weights = weights.abs()
    if abs_weights.ndim == 3:
        importance = abs_weights.mean(dim=(0, 1))
    elif abs_weights.ndim == 2:
        importance = abs_weights.mean(dim=0)
    else:
        raise ValueError("unsupported consequent weight shape for feature importance")

    return _normalize_importance(importance)

`fit`

Train the TSK classifier on labeled samples.

Validation data should be supplied using x_val and y_val when available.

Source code in highfis/estimators/_base.py

def fit(
    self,
    x: Any,
    y: Any,
    *,
    x_val: Any | None = None,
    y_val: Any | None = None,
) -> Self:
    """Train the TSK classifier on labeled samples.

    Validation data should be supplied using ``x_val`` and ``y_val``
    when available.
    """
    x_arr, y_arr = check_X_y(x, y)

    if self.random_state is not None:
        torch.manual_seed(int(self.random_state))

    le = LabelEncoder()
    y_idx = le.fit_transform(np.asarray(y_arr))

    input_mfs, feature_names, effective_rule_base = self._build_input_mfs(x_arr)

    self.n_features_in_ = x_arr.shape[1]
    self.feature_names_in_ = np.asarray(feature_names, dtype=object)
    self.classes_ = le.classes_
    self._label_encoder_ = le

    _device = torch.device(str(self.device))
    self.model_ = self._build_model(input_mfs, len(self.classes_), effective_rule_base).to(_device)

    y_t = torch.as_tensor(y_idx, dtype=torch.long, device=_device)

    # Prepare validation tensors if provided via fit.
    x_val_t: torch.Tensor | None = None
    y_val_t: torch.Tensor | None = None
    if (x_val is None) ^ (y_val is None):
        raise ValueError("x_val and y_val must be provided together")
    if x_val is not None and y_val is not None:
        x_v_arr, y_v_arr = check_X_y(x_val, y_val)
        x_val_t = self._as_tensor_x(x_v_arr, _device)
        y_val_idx = le.transform(np.asarray(y_v_arr))
        y_val_t = torch.as_tensor(y_val_idx, dtype=torch.long, device=_device)

    self.history_ = self.model_.fit(
        self._as_tensor_x(x_arr, _device),
        y_t,
        epochs=int(self.epochs),
        learning_rate=float(self.learning_rate),
        batch_size=self.batch_size,
        shuffle=bool(self.shuffle),
        ur_weight=float(self.ur_weight),
        ur_target=self.ur_target,
        verbose=self.verbose,
        x_val=x_val_t,
        y_val=y_val_t,
        patience=self.patience,
        restore_best=self.restore_best,
        weight_decay=float(self.weight_decay),
    )
    self.rule_base_ = effective_rule_base
    return self

`get_mf_params`

Return model membership function metadata after fitting.

Source code in highfis/estimators/_base.py

def get_mf_params(self) -> dict[str, list[dict[str, Any]]]:
    """Return model membership function metadata after fitting."""
    check_is_fitted(self, "model_")
    return self.model_.get_mf_params()

`inspect`

Return a structured summary of fitted model state and rule metadata.

Source code in highfis/estimators/_base.py

def inspect(self) -> dict[str, Any]:
    """Return a structured summary of fitted model state and rule metadata."""
    check_is_fitted(self, "model_")
    return {
        "n_rules": int(self.model_.n_rules),
        "n_inputs": int(self.model_.n_inputs),
        "feature_names": list(self.model_.input_names),
        "rule_base": self.rule_base_,
        "defuzzifier_type": type(self.model_.defuzzifier).__name__,
        "mf_params": self.get_mf_params(),
        "rule_table": self.model_.get_rule_table(),
    }

`load` `classmethod`

Load a persisted estimator created by save.

Source code in highfis/estimators/_base.py

@classmethod
def load(cls, path: str) -> Self:
    """Load a persisted estimator created by save."""
    checkpoint = load_checkpoint(path)
    validate_checkpoint_payload(checkpoint, expected_estimator_class=cls.__name__)

    params: dict[str, Any] = dict(checkpoint["estimator_params"])
    if params.get("input_configs") is not None:
        params["input_configs"] = [InputConfig(**c) for c in params["input_configs"]]
    estimator = cls(**params)
    model_init = checkpoint["model_init"]
    estimator.rule_base_ = model_init["rule_base"]
    estimator.model_ = estimator._build_model(
        deserialize_input_mfs(model_init["input_mfs_config"]),
        int(model_init["n_classes"]),
        str(model_init["rule_base"]),
    )
    estimator.model_.load_state_dict(checkpoint["model_state_dict"])
    estimator.model_.to(torch.device(str(estimator.device)))

    fitted = checkpoint["fitted_attrs"]
    estimator.n_features_in_ = int(fitted["n_features_in"])
    estimator.feature_names_in_ = np.asarray(fitted["feature_names_in"], dtype=object)
    estimator.classes_ = np.asarray(fitted["classes"], dtype=object)
    label_encoder = LabelEncoder()
    label_encoder.classes_ = estimator.classes_
    estimator._label_encoder_ = label_encoder
    estimator.history_ = cast(dict[str, Any], checkpoint.get("history", {}))
    return estimator

`predict`

Predict class labels for input samples.

Source code in highfis/estimators/_base.py

def predict(self, x: Any) -> np.ndarray:
    """Predict class labels for input samples."""
    proba = self.predict_proba(x)
    y_idx = np.argmax(proba, axis=1)
    return np.asarray(self._label_encoder_.inverse_transform(y_idx))

`predict_proba`

Predict class probabilities for input samples.

Source code in highfis/estimators/_base.py

def predict_proba(self, x: Any) -> np.ndarray:
    """Predict class probabilities for input samples."""
    check_is_fitted(self, "model_")
    x_arr = check_array(x)
    if x_arr.shape[1] != self.n_features_in_:
        raise ValueError(f"expected {self.n_features_in_} features, got {x_arr.shape[1]}")
    probs = cast(Any, self.model_).predict_proba(self._as_tensor_x(x_arr, torch.device(str(self.device))))
    return probs.detach().cpu().numpy()

`rule_activation`

Return normalized rule activations for the provided inputs.

Source code in highfis/estimators/_base.py

def rule_activation(self, X: Any) -> np.ndarray:
    """Return normalized rule activations for the provided inputs."""
    check_is_fitted(self, "model_")
    x_arr = check_array(X)
    if x_arr.shape[1] != self.n_features_in_:
        raise ValueError(f"expected {self.n_features_in_} features, got {x_arr.shape[1]}")

    was_training = self.model_.training
    try:
        self.model_.eval()
        with torch.no_grad():
            norm_w = self.model_.forward_antecedents(self._as_tensor_x(x_arr, torch.device(str(self.device))))
    finally:
        self.model_.train(was_training)

    return _to_numpy(norm_w)

`save`

Persist estimator configuration, model weights and fitted metadata.

Source code in highfis/estimators/_base.py

def save(self, path: str) -> None:
    """Persist estimator configuration, model weights and fitted metadata."""
    checkpoint = self._build_checkpoint_base(
        model_init={
            "input_mfs_config": serialize_input_mfs(self.model_.input_mfs),
            "n_classes": len(self.classes_),
            "rule_base": self.rule_base_,
        },
        fitted_attrs={
            "n_features_in": int(self.n_features_in_),
            "feature_names_in": self.feature_names_in_.tolist(),
            "classes": self.classes_.tolist(),
        },
    )
    save_checkpoint(path, checkpoint)

`score`

Return classification accuracy on the provided dataset.

Source code in highfis/estimators/_base.py

def score(self, X: Any, y: Any, sample_weight: Any = None) -> float:
    """Return classification accuracy on the provided dataset."""
    y_true = np.asarray(y)
    y_pred = self.predict(X)
    return float(accuracy_score(y_true, y_pred, sample_weight=sample_weight))

`HDFISMinRegressor`

Bases: _BaseRegressorEstimator

HDFIS-min regressor estimator with minimum T-norm antecedents.

HDFIS-min freezes antecedent membership parameters and uses a minimum T-norm aggregation in the antecedent, so that only consequent parameters are optimized during training. This design avoids the nondifferentiability of the minimum operator while preserving first-order TSK consequents.

References

G. Xue, J. Wang, K. Zhang and N. R. Pal, "High-Dimensional Fuzzy Inference Systems," in IEEE Transactions on Systems, Man, and Cybernetics: Systems, vol. 54, no. 1, pp. 507-519, Jan. 2024, doi: 10.1109/TSMC.2023.3311475.

Example

from highfis import HDFISMinRegressor

reg = HDFISMinRegressor()
reg.fit(X_train, y_train)
preds = reg.predict(X_test)

Initialise an HDFIS-min regressor estimator.

Source code in highfis/estimators/_hdfis.py

def __init__(
    self,
    *,
    input_configs: list[InputConfig] | None = None,
    n_mfs: int = 5,
    mf_init: str = "kmeans",
    sigma_scale: float | str = 1.0,
    random_state: int | None = None,
    epochs: int = 10,
    learning_rate: float = 1e-2,
    verbose: bool | int = False,
    rule_base: str | None = None,
    batch_size: int | None = 512,
    shuffle: bool = True,
    ur_weight: float = 0.0,
    ur_target: float | None = None,
    consequent_batch_norm: bool = False,
    patience: int | None = 20,
    restore_best: bool = True,
    weight_decay: float = 1e-8,
) -> None:
    """Initialise an HDFIS-min regressor estimator."""
    super().__init__(
        input_configs=input_configs,
        n_mfs=n_mfs,
        mf_init=mf_init,
        sigma_scale=sigma_scale,
        random_state=random_state,
        epochs=epochs,
        learning_rate=learning_rate,
        verbose=verbose,
        rule_base=rule_base,
        batch_size=batch_size,
        shuffle=shuffle,
        ur_weight=ur_weight,
        ur_target=ur_target,
        consequent_batch_norm=consequent_batch_norm,
        patience=patience,
        restore_best=restore_best,
        weight_decay=weight_decay,
    )

`evaluate`

Compute regression evaluation metrics for the provided dataset.

Source code in highfis/estimators/_base.py

def evaluate(
    self,
    X: Any,
    y: Any,
    metrics: list[str] | None = None,
    sample_weight: Any | None = None,
) -> dict[str, float]:
    """Compute regression evaluation metrics for the provided dataset."""
    y_true = np.asarray(y)
    y_pred = self.predict(X)
    return compute_metrics(
        task="regression",
        y_true=y_true,
        y_pred=y_pred,
        sample_weight=sample_weight,
        metrics=metrics,
    )

`feature_importance`

Compute a normalized feature importance vector from consequent weights.

Source code in highfis/estimators/_base.py

def feature_importance(self) -> np.ndarray | None:
    """Compute a normalized feature importance vector from consequent weights."""
    check_is_fitted(self, "model_")
    weights = self.model_.get_consequent_weights()
    if weights is None:
        return None

    consequent_layer = self.model_.consequent_layer
    if hasattr(consequent_layer, "rule_feature_mask"):
        rule_feature_mask = cast(Tensor, consequent_layer.rule_feature_mask)
        weights = weights * rule_feature_mask.unsqueeze(1) if weights.ndim == 3 else weights * rule_feature_mask

    abs_weights = weights.abs()
    if abs_weights.ndim == 3:
        importance = abs_weights.mean(dim=(0, 1))
    elif abs_weights.ndim == 2:
        importance = abs_weights.mean(dim=0)
    else:
        raise ValueError("unsupported consequent weight shape for feature importance")

    return _normalize_importance(importance)

`fit`

Train the TSK regressor on labeled samples.

Validation data should be supplied using x_val and y_val when available.

Source code in highfis/estimators/_base.py

def fit(
    self,
    x: Any,
    y: Any,
    *,
    x_val: Any | None = None,
    y_val: Any | None = None,
) -> Self:
    """Train the TSK regressor on labeled samples.

    Validation data should be supplied using ``x_val`` and ``y_val``
    when available.
    """
    x_arr, y_arr = check_X_y(x, y)

    if self.random_state is not None:
        torch.manual_seed(int(self.random_state))

    input_mfs, feature_names, effective_rule_base = self._build_input_mfs(x_arr)

    self.n_features_in_ = x_arr.shape[1]
    self.feature_names_in_ = np.asarray(feature_names, dtype=object)

    _device = torch.device(str(self.device))
    self.model_ = self._build_regressor_model(input_mfs, effective_rule_base).to(_device)

    y_t = torch.as_tensor(np.asarray(y_arr, dtype=np.float32), dtype=torch.float32, device=_device)

    # Prepare validation tensors if provided via fit.
    x_val_t: torch.Tensor | None = None
    y_val_t: torch.Tensor | None = None
    if (x_val is None) ^ (y_val is None):
        raise ValueError("x_val and y_val must be provided together")
    if x_val is not None and y_val is not None:
        x_v_arr, y_v_arr = check_X_y(x_val, y_val)
        x_val_t = self._as_tensor_x(x_v_arr, _device)
        y_val_t = torch.as_tensor(np.asarray(y_v_arr, dtype=np.float32), dtype=torch.float32, device=_device)

    self.history_ = self.model_.fit(
        self._as_tensor_x(x_arr, _device),
        y_t,
        epochs=int(self.epochs),
        learning_rate=float(self.learning_rate),
        batch_size=self.batch_size,
        shuffle=bool(self.shuffle),
        ur_weight=float(self.ur_weight),
        ur_target=self.ur_target,
        verbose=self.verbose,
        x_val=x_val_t,
        y_val=y_val_t,
        patience=self.patience,
        restore_best=self.restore_best,
        weight_decay=float(self.weight_decay),
    )
    self.rule_base_ = effective_rule_base
    return self

`get_mf_params`

Return model membership function metadata after fitting.

Source code in highfis/estimators/_base.py

def get_mf_params(self) -> dict[str, list[dict[str, Any]]]:
    """Return model membership function metadata after fitting."""
    check_is_fitted(self, "model_")
    return self.model_.get_mf_params()

`inspect`

Return a structured summary of fitted model state and rule metadata.

Source code in highfis/estimators/_base.py

def inspect(self) -> dict[str, Any]:
    """Return a structured summary of fitted model state and rule metadata."""
    check_is_fitted(self, "model_")
    return {
        "n_rules": int(self.model_.n_rules),
        "n_inputs": int(self.model_.n_inputs),
        "feature_names": list(self.model_.input_names),
        "rule_base": self.rule_base_,
        "defuzzifier_type": type(self.model_.defuzzifier).__name__,
        "mf_params": self.get_mf_params(),
        "rule_table": self.model_.get_rule_table(),
    }

`load` `classmethod`

Load a persisted estimator created by save.

Source code in highfis/estimators/_base.py

@classmethod
def load(cls, path: str) -> Self:
    """Load a persisted estimator created by save."""
    checkpoint = load_checkpoint(path)
    validate_checkpoint_payload(checkpoint, expected_estimator_class=cls.__name__)

    params: dict[str, Any] = dict(checkpoint["estimator_params"])
    if params.get("input_configs") is not None:
        params["input_configs"] = [InputConfig(**c) for c in params["input_configs"]]
    estimator = cls(**params)
    model_init = checkpoint["model_init"]
    estimator.rule_base_ = model_init["rule_base"]
    estimator.model_ = estimator._build_regressor_model(
        deserialize_input_mfs(model_init["input_mfs_config"]),
        str(model_init["rule_base"]),
    )
    estimator.model_.load_state_dict(checkpoint["model_state_dict"])
    estimator.model_.to(torch.device(str(estimator.device)))

    fitted = checkpoint["fitted_attrs"]
    estimator.n_features_in_ = int(fitted["n_features_in"])
    estimator.feature_names_in_ = np.asarray(fitted["feature_names_in"], dtype=object)
    estimator.history_ = cast(dict[str, Any], checkpoint.get("history", {}))
    return estimator

`predict`

Predict continuous target values for input samples.

Source code in highfis/estimators/_base.py

def predict(self, x: Any) -> np.ndarray:
    """Predict continuous target values for input samples."""
    check_is_fitted(self, "model_")
    x_arr = check_array(x)
    if x_arr.shape[1] != self.n_features_in_:
        raise ValueError(f"expected {self.n_features_in_} features, got {x_arr.shape[1]}")
    preds = cast(Any, self.model_).predict(self._as_tensor_x(x_arr, torch.device(str(self.device))))
    return preds.detach().cpu().numpy()

`rule_activation`

Return normalized rule activations for the provided inputs.

Source code in highfis/estimators/_base.py

def rule_activation(self, X: Any) -> np.ndarray:
    """Return normalized rule activations for the provided inputs."""
    check_is_fitted(self, "model_")
    x_arr = check_array(X)
    if x_arr.shape[1] != self.n_features_in_:
        raise ValueError(f"expected {self.n_features_in_} features, got {x_arr.shape[1]}")

    was_training = self.model_.training
    try:
        self.model_.eval()
        with torch.no_grad():
            norm_w = self.model_.forward_antecedents(self._as_tensor_x(x_arr, torch.device(str(self.device))))
    finally:
        self.model_.train(was_training)

    return _to_numpy(norm_w)

`save`

Persist estimator configuration, model weights and fitted metadata.

Source code in highfis/estimators/_base.py

def save(self, path: str) -> None:
    """Persist estimator configuration, model weights and fitted metadata."""
    checkpoint = self._build_checkpoint_base(
        model_init={
            "input_mfs_config": serialize_input_mfs(self.model_.input_mfs),
            "rule_base": self.rule_base_,
        },
        fitted_attrs={
            "n_features_in": int(self.n_features_in_),
            "feature_names_in": self.feature_names_in_.tolist(),
        },
    )
    save_checkpoint(path, checkpoint)

`HDFISProdClassifier`

Bases: _BaseClassifierEstimator

HDFIS-prod classifier estimator with dimension-dependent Gaussian MFs.

HDFIS-prod combines the standard product T-norm with a dimension-dependent Gaussian membership function (DMF) to avoid numeric underflow in very high-dimensional feature spaces while preserving first-order TSK consequents.

References

G. Xue, J. Wang, K. Zhang and N. R. Pal, "High-Dimensional Fuzzy Inference Systems," in IEEE Transactions on Systems, Man, and Cybernetics: Systems, vol. 54, no. 1, pp. 507-519, Jan. 2024, doi: 10.1109/TSMC.2023.3311475.

Example

from highfis import HDFISProdClassifier

clf = HDFISProdClassifier()
clf.fit(X_train, y_train)

Initialise an HDFIS-prod classifier estimator.

Parameters:

Name	Type	Description	Default
`input_configs`	`list[InputConfig] \| None`	Per-feature :class:`InputConfig` list.	`None`
`n_mfs`	`int`	Number of k-means clusters / grid MFs (default `5`).	`5`
`mf_init`	`str`	`"kmeans"` (default), `"minibatch_kmeans"`, `"fcm"`, or `"grid"`.	`'kmeans'`
`sigma_scale`	`float \| str`	Sigma scale factor. `1.0` recommended.	`1.0`
`random_state`	`int \| None`	Seed for reproducibility.	`None`
`epochs`	`int`	Maximum training epochs (default `10`).	`10`
`learning_rate`	`float`	Adam learning rate (default `0.01`).	`0.01`
`verbose`	`bool \| int`	Print per-epoch progress.	`False`
`rule_base`	`str \| None`	`"coco"` or `"cartesian"`.	`None`
`batch_size`	`int \| None`	Mini-batch size (default `512`).	`512`
`shuffle`	`bool`	Reshuffle each epoch.	`True`
`ur_weight`	`float`	Uncertainty regularisation weight.	`0.0`
`ur_target`	`float \| None`	Uncertainty regularisation target.	`None`
`consequent_batch_norm`	`bool`	Batch normalisation on consequent layers.	`False`
`pfrb_max_rules`	`int \| None`	Maximum number of point-based FRB rules when `rule_base='pfrb'`. `None` uses all training samples.	`None`
`patience`	`int \| None`	Early-stopping patience (default `20`). Set to `None` to disable early stopping.	`20`
`restore_best`	`bool`	Restore best validation weights after training.	`True`
`weight_decay`	`float`	L2 weight decay for consequent parameters.	`1e-08`
`xi`	`float`	Precision constant used to compute the DMF scale exponent \(\rho\) when rho is `None`. Must be greater than 1.	`745.0`
`rho`	`float \| None`	Scale exponent for the dimension-dependent Gaussian MF. When `None`, computed as `1 - log(xi) / log(D)`.	`None`

Source code in highfis/estimators/_hdfis.py

def __init__(
    self,
    *,
    input_configs: list[InputConfig] | None = None,
    n_mfs: int = 5,
    mf_init: str = "kmeans",
    sigma_scale: float | str = 1.0,
    random_state: int | None = None,
    epochs: int = 10,
    learning_rate: float = 1e-2,
    verbose: bool | int = False,
    rule_base: str | None = None,
    batch_size: int | None = 512,
    shuffle: bool = True,
    ur_weight: float = 0.0,
    ur_target: float | None = None,
    consequent_batch_norm: bool = False,
    pfrb_max_rules: int | None = None,
    patience: int | None = 20,
    restore_best: bool = True,
    weight_decay: float = 1e-8,
    xi: float = 745.0,
    rho: float | None = None,
) -> None:
    r"""Initialise an HDFIS-prod classifier estimator.

    Args:
        input_configs: Per-feature :class:`InputConfig` list.
        n_mfs: Number of k-means clusters / grid MFs (default ``5``).
        mf_init: ``"kmeans"`` (default), ``"minibatch_kmeans"``, ``"fcm"``, or ``"grid"``.
        sigma_scale: Sigma scale factor. ``1.0`` recommended.
        random_state: Seed for reproducibility.
        epochs: Maximum training epochs (default ``10``).
        learning_rate: Adam learning rate (default ``0.01``).
        verbose: Print per-epoch progress.
        rule_base: ``"coco"`` or ``"cartesian"``.
        batch_size: Mini-batch size (default ``512``).
        shuffle: Reshuffle each epoch.
        ur_weight: Uncertainty regularisation weight.
        ur_target: Uncertainty regularisation target.
        consequent_batch_norm: Batch normalisation on consequent layers.
        pfrb_max_rules: Maximum number of point-based FRB rules when
            ``rule_base='pfrb'``. ``None`` uses all training samples.
        patience: Early-stopping patience (default ``20``).
            Set to ``None`` to disable early stopping.
        restore_best: Restore best validation weights after training.
        weight_decay: L2 weight decay for consequent parameters.
        xi: Precision constant used to compute the DMF scale exponent
            $\rho$ when *rho* is ``None``. Must be greater than 1.
        rho: Scale exponent for the dimension-dependent Gaussian MF.
            When ``None``, computed as ``1 - log(xi) / log(D)``.
    """
    super().__init__(
        input_configs=input_configs,
        n_mfs=n_mfs,
        mf_init=mf_init,
        sigma_scale=sigma_scale,
        random_state=random_state,
        epochs=epochs,
        learning_rate=learning_rate,
        verbose=verbose,
        rule_base=rule_base,
        batch_size=batch_size,
        shuffle=shuffle,
        ur_weight=ur_weight,
        ur_target=ur_target,
        consequent_batch_norm=consequent_batch_norm,
        pfrb_max_rules=pfrb_max_rules,
        patience=patience,
        restore_best=restore_best,
        weight_decay=weight_decay,
    )
    self.xi = float(xi)
    self.rho = rho

`evaluate`

Compute classification evaluation metrics for the provided dataset.

Source code in highfis/estimators/_base.py

def evaluate(
    self,
    X: Any,
    y: Any,
    metrics: list[str] | None = None,
    sample_weight: Any | None = None,
) -> dict[str, float]:
    """Compute classification evaluation metrics for the provided dataset."""
    y_true = np.asarray(y)
    y_pred = self.predict(X)
    return compute_metrics(
        task="classification",
        y_true=y_true,
        y_pred=y_pred,
        sample_weight=sample_weight,
        metrics=metrics,
    )

`feature_importance`

Compute a normalized feature importance vector from consequent weights.

Source code in highfis/estimators/_base.py

def feature_importance(self) -> np.ndarray | None:
    """Compute a normalized feature importance vector from consequent weights."""
    check_is_fitted(self, "model_")
    weights = self.model_.get_consequent_weights()
    if weights is None:
        return None

    consequent_layer = self.model_.consequent_layer
    if hasattr(consequent_layer, "rule_feature_mask"):
        rule_feature_mask = cast(Tensor, consequent_layer.rule_feature_mask)
        weights = weights * rule_feature_mask.unsqueeze(1) if weights.ndim == 3 else weights * rule_feature_mask

    abs_weights = weights.abs()
    if abs_weights.ndim == 3:
        importance = abs_weights.mean(dim=(0, 1))
    elif abs_weights.ndim == 2:
        importance = abs_weights.mean(dim=0)
    else:
        raise ValueError("unsupported consequent weight shape for feature importance")

    return _normalize_importance(importance)

`fit`

Train the TSK classifier on labeled samples.

Validation data should be supplied using x_val and y_val when available.

Source code in highfis/estimators/_base.py

def fit(
    self,
    x: Any,
    y: Any,
    *,
    x_val: Any | None = None,
    y_val: Any | None = None,
) -> Self:
    """Train the TSK classifier on labeled samples.

    Validation data should be supplied using ``x_val`` and ``y_val``
    when available.
    """
    x_arr, y_arr = check_X_y(x, y)

    if self.random_state is not None:
        torch.manual_seed(int(self.random_state))

    le = LabelEncoder()
    y_idx = le.fit_transform(np.asarray(y_arr))

    input_mfs, feature_names, effective_rule_base = self._build_input_mfs(x_arr)

    self.n_features_in_ = x_arr.shape[1]
    self.feature_names_in_ = np.asarray(feature_names, dtype=object)
    self.classes_ = le.classes_
    self._label_encoder_ = le

    _device = torch.device(str(self.device))
    self.model_ = self._build_model(input_mfs, len(self.classes_), effective_rule_base).to(_device)

    y_t = torch.as_tensor(y_idx, dtype=torch.long, device=_device)

    # Prepare validation tensors if provided via fit.
    x_val_t: torch.Tensor | None = None
    y_val_t: torch.Tensor | None = None
    if (x_val is None) ^ (y_val is None):
        raise ValueError("x_val and y_val must be provided together")
    if x_val is not None and y_val is not None:
        x_v_arr, y_v_arr = check_X_y(x_val, y_val)
        x_val_t = self._as_tensor_x(x_v_arr, _device)
        y_val_idx = le.transform(np.asarray(y_v_arr))
        y_val_t = torch.as_tensor(y_val_idx, dtype=torch.long, device=_device)

    self.history_ = self.model_.fit(
        self._as_tensor_x(x_arr, _device),
        y_t,
        epochs=int(self.epochs),
        learning_rate=float(self.learning_rate),
        batch_size=self.batch_size,
        shuffle=bool(self.shuffle),
        ur_weight=float(self.ur_weight),
        ur_target=self.ur_target,
        verbose=self.verbose,
        x_val=x_val_t,
        y_val=y_val_t,
        patience=self.patience,
        restore_best=self.restore_best,
        weight_decay=float(self.weight_decay),
    )
    self.rule_base_ = effective_rule_base
    return self

`get_mf_params`

Return model membership function metadata after fitting.

Source code in highfis/estimators/_base.py

def get_mf_params(self) -> dict[str, list[dict[str, Any]]]:
    """Return model membership function metadata after fitting."""
    check_is_fitted(self, "model_")
    return self.model_.get_mf_params()

`inspect`

Return a structured summary of fitted model state and rule metadata.

Source code in highfis/estimators/_base.py

def inspect(self) -> dict[str, Any]:
    """Return a structured summary of fitted model state and rule metadata."""
    check_is_fitted(self, "model_")
    return {
        "n_rules": int(self.model_.n_rules),
        "n_inputs": int(self.model_.n_inputs),
        "feature_names": list(self.model_.input_names),
        "rule_base": self.rule_base_,
        "defuzzifier_type": type(self.model_.defuzzifier).__name__,
        "mf_params": self.get_mf_params(),
        "rule_table": self.model_.get_rule_table(),
    }

`load` `classmethod`

Load a persisted estimator created by save.

Source code in highfis/estimators/_base.py

@classmethod
def load(cls, path: str) -> Self:
    """Load a persisted estimator created by save."""
    checkpoint = load_checkpoint(path)
    validate_checkpoint_payload(checkpoint, expected_estimator_class=cls.__name__)

    params: dict[str, Any] = dict(checkpoint["estimator_params"])
    if params.get("input_configs") is not None:
        params["input_configs"] = [InputConfig(**c) for c in params["input_configs"]]
    estimator = cls(**params)
    model_init = checkpoint["model_init"]
    estimator.rule_base_ = model_init["rule_base"]
    estimator.model_ = estimator._build_model(
        deserialize_input_mfs(model_init["input_mfs_config"]),
        int(model_init["n_classes"]),
        str(model_init["rule_base"]),
    )
    estimator.model_.load_state_dict(checkpoint["model_state_dict"])
    estimator.model_.to(torch.device(str(estimator.device)))

    fitted = checkpoint["fitted_attrs"]
    estimator.n_features_in_ = int(fitted["n_features_in"])
    estimator.feature_names_in_ = np.asarray(fitted["feature_names_in"], dtype=object)
    estimator.classes_ = np.asarray(fitted["classes"], dtype=object)
    label_encoder = LabelEncoder()
    label_encoder.classes_ = estimator.classes_
    estimator._label_encoder_ = label_encoder
    estimator.history_ = cast(dict[str, Any], checkpoint.get("history", {}))
    return estimator

`predict`

Predict class labels for input samples.

Source code in highfis/estimators/_base.py

def predict(self, x: Any) -> np.ndarray:
    """Predict class labels for input samples."""
    proba = self.predict_proba(x)
    y_idx = np.argmax(proba, axis=1)
    return np.asarray(self._label_encoder_.inverse_transform(y_idx))

`predict_proba`

Predict class probabilities for input samples.

Source code in highfis/estimators/_base.py

def predict_proba(self, x: Any) -> np.ndarray:
    """Predict class probabilities for input samples."""
    check_is_fitted(self, "model_")
    x_arr = check_array(x)
    if x_arr.shape[1] != self.n_features_in_:
        raise ValueError(f"expected {self.n_features_in_} features, got {x_arr.shape[1]}")
    probs = cast(Any, self.model_).predict_proba(self._as_tensor_x(x_arr, torch.device(str(self.device))))
    return probs.detach().cpu().numpy()

`rule_activation`

Return normalized rule activations for the provided inputs.

Source code in highfis/estimators/_base.py

def rule_activation(self, X: Any) -> np.ndarray:
    """Return normalized rule activations for the provided inputs."""
    check_is_fitted(self, "model_")
    x_arr = check_array(X)
    if x_arr.shape[1] != self.n_features_in_:
        raise ValueError(f"expected {self.n_features_in_} features, got {x_arr.shape[1]}")

    was_training = self.model_.training
    try:
        self.model_.eval()
        with torch.no_grad():
            norm_w = self.model_.forward_antecedents(self._as_tensor_x(x_arr, torch.device(str(self.device))))
    finally:
        self.model_.train(was_training)

    return _to_numpy(norm_w)

`save`

Persist estimator configuration, model weights and fitted metadata.

Source code in highfis/estimators/_base.py

def save(self, path: str) -> None:
    """Persist estimator configuration, model weights and fitted metadata."""
    checkpoint = self._build_checkpoint_base(
        model_init={
            "input_mfs_config": serialize_input_mfs(self.model_.input_mfs),
            "n_classes": len(self.classes_),
            "rule_base": self.rule_base_,
        },
        fitted_attrs={
            "n_features_in": int(self.n_features_in_),
            "feature_names_in": self.feature_names_in_.tolist(),
            "classes": self.classes_.tolist(),
        },
    )
    save_checkpoint(path, checkpoint)

`score`

Return classification accuracy on the provided dataset.

Source code in highfis/estimators/_base.py

def score(self, X: Any, y: Any, sample_weight: Any = None) -> float:
    """Return classification accuracy on the provided dataset."""
    y_true = np.asarray(y)
    y_pred = self.predict(X)
    return float(accuracy_score(y_true, y_pred, sample_weight=sample_weight))

`HDFISProdRegressor`

Bases: _BaseRegressorEstimator

HDFIS-prod regressor estimator with dimension-dependent Gaussian MFs.

HDFIS-prod combines the standard product T-norm with a dimension-dependent Gaussian membership function (DMF) to avoid numeric underflow in very high-dimensional feature spaces while preserving first-order TSK consequents.

References

G. Xue, J. Wang, K. Zhang and N. R. Pal, "High-Dimensional Fuzzy Inference Systems," in IEEE Transactions on Systems, Man, and Cybernetics: Systems, vol. 54, no. 1, pp. 507-519, Jan. 2024, doi: 10.1109/TSMC.2023.3311475.

Example

from highfis import HDFISProdRegressor

reg = HDFISProdRegressor()
reg.fit(X_train, y_train)

Initialise an HDFIS-prod regressor estimator.

Parameters:

Name	Type	Description	Default
`input_configs`	`list[InputConfig] \| None`	Per-feature :class:`InputConfig` list.	`None`
`n_mfs`	`int`	Number of k-means clusters / grid MFs (default `5`).	`5`
`mf_init`	`str`	`"kmeans"` (default), `"minibatch_kmeans"`, `"fcm"`, or `"grid"`.	`'kmeans'`
`sigma_scale`	`float \| str`	Sigma scale factor. `1.0` recommended.	`1.0`
`random_state`	`int \| None`	Seed for reproducibility.	`None`
`epochs`	`int`	Maximum training epochs (default `10`).	`10`
`learning_rate`	`float`	Adam learning rate (default `0.01`).	`0.01`
`verbose`	`bool \| int`	Print per-epoch progress.	`False`
`rule_base`	`str \| None`	`"coco"` or `"cartesian"`.	`None`
`batch_size`	`int \| None`	Mini-batch size (default `512`).	`512`
`shuffle`	`bool`	Reshuffle each epoch.	`True`
`ur_weight`	`float`	Uncertainty regularisation weight.	`0.0`
`ur_target`	`float \| None`	Uncertainty regularisation target.	`None`
`consequent_batch_norm`	`bool`	Batch normalisation on consequent layers.	`False`
`patience`	`int \| None`	Early-stopping patience (default `20`). Set to `None` to disable early stopping.	`20`
`restore_best`	`bool`	Restore best validation weights after training.	`True`
`weight_decay`	`float`	L2 weight decay for consequent parameters.	`1e-08`
`xi`	`float`	Precision constant used to compute the DMF scale exponent \(\rho\) when rho is `None`. Must be greater than 1.	`745.0`
`rho`	`float \| None`	Scale exponent for the dimension-dependent Gaussian MF. When `None`, computed as `1 - log(xi) / log(D)`.	`None`

Source code in highfis/estimators/_hdfis.py

def __init__(
    self,
    *,
    input_configs: list[InputConfig] | None = None,
    n_mfs: int = 5,
    mf_init: str = "kmeans",
    sigma_scale: float | str = 1.0,
    random_state: int | None = None,
    epochs: int = 10,
    learning_rate: float = 1e-2,
    verbose: bool | int = False,
    rule_base: str | None = None,
    batch_size: int | None = 512,
    shuffle: bool = True,
    ur_weight: float = 0.0,
    ur_target: float | None = None,
    consequent_batch_norm: bool = False,
    patience: int | None = 20,
    restore_best: bool = True,
    weight_decay: float = 1e-8,
    xi: float = 745.0,
    rho: float | None = None,
) -> None:
    r"""Initialise an HDFIS-prod regressor estimator.

    Args:
        input_configs: Per-feature :class:`InputConfig` list.
        n_mfs: Number of k-means clusters / grid MFs (default ``5``).
        mf_init: ``"kmeans"`` (default), ``"minibatch_kmeans"``, ``"fcm"``, or ``"grid"``.
        sigma_scale: Sigma scale factor. ``1.0`` recommended.
        random_state: Seed for reproducibility.
        epochs: Maximum training epochs (default ``10``).
        learning_rate: Adam learning rate (default ``0.01``).
        verbose: Print per-epoch progress.
        rule_base: ``"coco"`` or ``"cartesian"``.
        batch_size: Mini-batch size (default ``512``).
        shuffle: Reshuffle each epoch.
        ur_weight: Uncertainty regularisation weight.
        ur_target: Uncertainty regularisation target.
        consequent_batch_norm: Batch normalisation on consequent layers.
        patience: Early-stopping patience (default ``20``).
            Set to ``None`` to disable early stopping.
        restore_best: Restore best validation weights after training.
        weight_decay: L2 weight decay for consequent parameters.
        xi: Precision constant used to compute the DMF scale exponent
            $\rho$ when *rho* is ``None``. Must be greater than 1.
        rho: Scale exponent for the dimension-dependent Gaussian MF.
            When ``None``, computed as ``1 - log(xi) / log(D)``.
    """
    super().__init__(
        input_configs=input_configs,
        n_mfs=n_mfs,
        mf_init=mf_init,
        sigma_scale=sigma_scale,
        random_state=random_state,
        epochs=epochs,
        learning_rate=learning_rate,
        verbose=verbose,
        rule_base=rule_base,
        batch_size=batch_size,
        shuffle=shuffle,
        ur_weight=ur_weight,
        ur_target=ur_target,
        consequent_batch_norm=consequent_batch_norm,
        patience=patience,
        restore_best=restore_best,
        weight_decay=weight_decay,
    )
    self.xi = float(xi)
    self.rho = rho

`evaluate`

Compute regression evaluation metrics for the provided dataset.

Source code in highfis/estimators/_base.py

def evaluate(
    self,
    X: Any,
    y: Any,
    metrics: list[str] | None = None,
    sample_weight: Any | None = None,
) -> dict[str, float]:
    """Compute regression evaluation metrics for the provided dataset."""
    y_true = np.asarray(y)
    y_pred = self.predict(X)
    return compute_metrics(
        task="regression",
        y_true=y_true,
        y_pred=y_pred,
        sample_weight=sample_weight,
        metrics=metrics,
    )

`feature_importance`

Compute a normalized feature importance vector from consequent weights.

Source code in highfis/estimators/_base.py

def feature_importance(self) -> np.ndarray | None:
    """Compute a normalized feature importance vector from consequent weights."""
    check_is_fitted(self, "model_")
    weights = self.model_.get_consequent_weights()
    if weights is None:
        return None

    consequent_layer = self.model_.consequent_layer
    if hasattr(consequent_layer, "rule_feature_mask"):
        rule_feature_mask = cast(Tensor, consequent_layer.rule_feature_mask)
        weights = weights * rule_feature_mask.unsqueeze(1) if weights.ndim == 3 else weights * rule_feature_mask

    abs_weights = weights.abs()
    if abs_weights.ndim == 3:
        importance = abs_weights.mean(dim=(0, 1))
    elif abs_weights.ndim == 2:
        importance = abs_weights.mean(dim=0)
    else:
        raise ValueError("unsupported consequent weight shape for feature importance")

    return _normalize_importance(importance)

`fit`

Train the TSK regressor on labeled samples.

Validation data should be supplied using x_val and y_val when available.

Source code in highfis/estimators/_base.py

def fit(
    self,
    x: Any,
    y: Any,
    *,
    x_val: Any | None = None,
    y_val: Any | None = None,
) -> Self:
    """Train the TSK regressor on labeled samples.

    Validation data should be supplied using ``x_val`` and ``y_val``
    when available.
    """
    x_arr, y_arr = check_X_y(x, y)

    if self.random_state is not None:
        torch.manual_seed(int(self.random_state))

    input_mfs, feature_names, effective_rule_base = self._build_input_mfs(x_arr)

    self.n_features_in_ = x_arr.shape[1]
    self.feature_names_in_ = np.asarray(feature_names, dtype=object)

    _device = torch.device(str(self.device))
    self.model_ = self._build_regressor_model(input_mfs, effective_rule_base).to(_device)

    y_t = torch.as_tensor(np.asarray(y_arr, dtype=np.float32), dtype=torch.float32, device=_device)

    # Prepare validation tensors if provided via fit.
    x_val_t: torch.Tensor | None = None
    y_val_t: torch.Tensor | None = None
    if (x_val is None) ^ (y_val is None):
        raise ValueError("x_val and y_val must be provided together")
    if x_val is not None and y_val is not None:
        x_v_arr, y_v_arr = check_X_y(x_val, y_val)
        x_val_t = self._as_tensor_x(x_v_arr, _device)
        y_val_t = torch.as_tensor(np.asarray(y_v_arr, dtype=np.float32), dtype=torch.float32, device=_device)

    self.history_ = self.model_.fit(
        self._as_tensor_x(x_arr, _device),
        y_t,
        epochs=int(self.epochs),
        learning_rate=float(self.learning_rate),
        batch_size=self.batch_size,
        shuffle=bool(self.shuffle),
        ur_weight=float(self.ur_weight),
        ur_target=self.ur_target,
        verbose=self.verbose,
        x_val=x_val_t,
        y_val=y_val_t,
        patience=self.patience,
        restore_best=self.restore_best,
        weight_decay=float(self.weight_decay),
    )
    self.rule_base_ = effective_rule_base
    return self

`get_mf_params`

Return model membership function metadata after fitting.

Source code in highfis/estimators/_base.py

def get_mf_params(self) -> dict[str, list[dict[str, Any]]]:
    """Return model membership function metadata after fitting."""
    check_is_fitted(self, "model_")
    return self.model_.get_mf_params()

`inspect`

Return a structured summary of fitted model state and rule metadata.

Source code in highfis/estimators/_base.py

def inspect(self) -> dict[str, Any]:
    """Return a structured summary of fitted model state and rule metadata."""
    check_is_fitted(self, "model_")
    return {
        "n_rules": int(self.model_.n_rules),
        "n_inputs": int(self.model_.n_inputs),
        "feature_names": list(self.model_.input_names),
        "rule_base": self.rule_base_,
        "defuzzifier_type": type(self.model_.defuzzifier).__name__,
        "mf_params": self.get_mf_params(),
        "rule_table": self.model_.get_rule_table(),
    }

`load` `classmethod`

Load a persisted estimator created by save.

Source code in highfis/estimators/_base.py

@classmethod
def load(cls, path: str) -> Self:
    """Load a persisted estimator created by save."""
    checkpoint = load_checkpoint(path)
    validate_checkpoint_payload(checkpoint, expected_estimator_class=cls.__name__)

    params: dict[str, Any] = dict(checkpoint["estimator_params"])
    if params.get("input_configs") is not None:
        params["input_configs"] = [InputConfig(**c) for c in params["input_configs"]]
    estimator = cls(**params)
    model_init = checkpoint["model_init"]
    estimator.rule_base_ = model_init["rule_base"]
    estimator.model_ = estimator._build_regressor_model(
        deserialize_input_mfs(model_init["input_mfs_config"]),
        str(model_init["rule_base"]),
    )
    estimator.model_.load_state_dict(checkpoint["model_state_dict"])
    estimator.model_.to(torch.device(str(estimator.device)))

    fitted = checkpoint["fitted_attrs"]
    estimator.n_features_in_ = int(fitted["n_features_in"])
    estimator.feature_names_in_ = np.asarray(fitted["feature_names_in"], dtype=object)
    estimator.history_ = cast(dict[str, Any], checkpoint.get("history", {}))
    return estimator

`predict`

Predict continuous target values for input samples.

Source code in highfis/estimators/_base.py

def predict(self, x: Any) -> np.ndarray:
    """Predict continuous target values for input samples."""
    check_is_fitted(self, "model_")
    x_arr = check_array(x)
    if x_arr.shape[1] != self.n_features_in_:
        raise ValueError(f"expected {self.n_features_in_} features, got {x_arr.shape[1]}")
    preds = cast(Any, self.model_).predict(self._as_tensor_x(x_arr, torch.device(str(self.device))))
    return preds.detach().cpu().numpy()

`rule_activation`

Return normalized rule activations for the provided inputs.

Source code in highfis/estimators/_base.py

def rule_activation(self, X: Any) -> np.ndarray:
    """Return normalized rule activations for the provided inputs."""
    check_is_fitted(self, "model_")
    x_arr = check_array(X)
    if x_arr.shape[1] != self.n_features_in_:
        raise ValueError(f"expected {self.n_features_in_} features, got {x_arr.shape[1]}")

    was_training = self.model_.training
    try:
        self.model_.eval()
        with torch.no_grad():
            norm_w = self.model_.forward_antecedents(self._as_tensor_x(x_arr, torch.device(str(self.device))))
    finally:
        self.model_.train(was_training)

    return _to_numpy(norm_w)

`save`

Persist estimator configuration, model weights and fitted metadata.

Source code in highfis/estimators/_base.py

def save(self, path: str) -> None:
    """Persist estimator configuration, model weights and fitted metadata."""
    checkpoint = self._build_checkpoint_base(
        model_init={
            "input_mfs_config": serialize_input_mfs(self.model_.input_mfs),
            "rule_base": self.rule_base_,
        },
        fitted_attrs={
            "n_features_in": int(self.n_features_in_),
            "feature_names_in": self.feature_names_in_.tolist(),
        },
    )
    save_checkpoint(path, checkpoint)

`HTSKClassifier`

Bases: _BaseClassifierEstimator

HTSK classifier for high-dimensional TSK inference.

HTSK replaces the standard product t-norm with a geometric mean over membership values and performs rule normalization in log-space.

References

Y. Cui, D. Wu and Y. Xu, "Curse of Dimensionality for TSK Fuzzy Neural Networks: Explanation and Solutions," 2021 International Joint Conference on Neural Networks (IJCNN), Shenzhen, China, 2021, pp. 1-8, doi: 10.1109/IJCNN52387.2021.9534265.

Example

from highfis import HTSKClassifier

clf = HTSKClassifier()
clf.fit(X_train, y_train)

Initialise an HTSK classifier.

Parameters:

Name	Type	Description	Default
`input_configs`	`list[InputConfig] \| None`	Per-feature :class:`InputConfig` list. Only `name` is used when `mf_init="kmeans"`.	`None`
`n_mfs`	`int`	Number of k-means clusters / grid MFs.	`3`
`mf_init`	`str`	`"kmeans"` (default), `"minibatch_kmeans"`, `"fcm"`, or `"grid"`.	`'kmeans'`
`sigma_scale`	`float \| str`	Sigma scale factor. `1.0` is recommended for HTSK.	`1.0`
`random_state`	`int \| None`	Seed for k-means and weight initialisation.	`None`
`epochs`	`int`	Maximum training epochs (default `10`).	`10`
`learning_rate`	`float`	Adam learning rate (default `0.01`).	`0.01`
`verbose`	`bool \| int`	Print per-epoch progress.	`False`
`rule_base`	`str \| None`	`"coco"` or `"cartesian"`. Defaults to `"coco"` for kmeans and `"cartesian"` for grid.	`None`
`batch_size`	`int \| None`	Mini-batch size (default `512`).	`512`
`shuffle`	`bool`	Reshuffle each epoch.	`True`
`ur_weight`	`float`	Uncertainty regularisation weight.	`0.0`
`ur_target`	`float \| None`	Uncertainty regularisation target.	`None`
`consequent_batch_norm`	`bool`	Batch normalisation on consequent layers.	`False`
`pfrb_max_rules`	`int \| None`	Maximum point-based FRB rules (unused by HTSK).	`None`
`patience`	`int \| None`	Early-stopping patience (default `20`). Set to `None` to disable early stopping.	`20`
`restore_best`	`bool`	If `True` (default), restore the best validation model weights after training.	`True`
`weight_decay`	`float`	L2 weight decay for consequent parameters.	`1e-08`

Source code in highfis/estimators/_htsk.py

def __init__(
    self,
    *,
    input_configs: list[InputConfig] | None = None,
    n_mfs: int = 3,
    mf_init: str = "kmeans",
    sigma_scale: float | str = 1.0,
    random_state: int | None = None,
    epochs: int = 10,
    learning_rate: float = 1e-2,
    verbose: bool | int = False,
    rule_base: str | None = None,
    batch_size: int | None = 512,
    shuffle: bool = True,
    ur_weight: float = 0.0,
    ur_target: float | None = None,
    consequent_batch_norm: bool = False,
    pfrb_max_rules: int | None = None,
    patience: int | None = 20,
    restore_best: bool = True,
    weight_decay: float = 1e-8,
) -> None:
    """Initialise an HTSK classifier.

    Args:
        input_configs: Per-feature :class:`InputConfig` list. Only
            ``name`` is used when ``mf_init="kmeans"``.
        n_mfs: Number of k-means clusters / grid MFs.
        mf_init: ``"kmeans"`` (default), ``"minibatch_kmeans"``, ``"fcm"``, or ``"grid"``.
        sigma_scale: Sigma scale factor. ``1.0`` is recommended for HTSK.
        random_state: Seed for k-means and weight initialisation.
        epochs: Maximum training epochs (default ``10``).
        learning_rate: Adam learning rate (default ``0.01``).
        verbose: Print per-epoch progress.
        rule_base: ``"coco"`` or ``"cartesian"``. Defaults to
            ``"coco"`` for kmeans and ``"cartesian"`` for grid.
        batch_size: Mini-batch size (default ``512``).
        shuffle: Reshuffle each epoch.
        ur_weight: Uncertainty regularisation weight.
        ur_target: Uncertainty regularisation target.
        consequent_batch_norm: Batch normalisation on consequent layers.
        pfrb_max_rules: Maximum point-based FRB rules (unused by HTSK).
        patience: Early-stopping patience (default ``20``). Set to ``None`` to disable early stopping.
        restore_best: If ``True`` (default), restore the best validation
            model weights after training.
        weight_decay: L2 weight decay for consequent parameters.
    """
    super().__init__(
        input_configs=input_configs,
        n_mfs=n_mfs,
        mf_init=mf_init,
        sigma_scale=sigma_scale,
        random_state=random_state,
        epochs=epochs,
        learning_rate=learning_rate,
        verbose=verbose,
        rule_base=rule_base,
        batch_size=batch_size,
        shuffle=shuffle,
        ur_weight=ur_weight,
        ur_target=ur_target,
        consequent_batch_norm=consequent_batch_norm,
        pfrb_max_rules=pfrb_max_rules,
        patience=patience,
        restore_best=restore_best,
        weight_decay=weight_decay,
    )

`evaluate`

Compute classification evaluation metrics for the provided dataset.

Source code in highfis/estimators/_base.py

def evaluate(
    self,
    X: Any,
    y: Any,
    metrics: list[str] | None = None,
    sample_weight: Any | None = None,
) -> dict[str, float]:
    """Compute classification evaluation metrics for the provided dataset."""
    y_true = np.asarray(y)
    y_pred = self.predict(X)
    return compute_metrics(
        task="classification",
        y_true=y_true,
        y_pred=y_pred,
        sample_weight=sample_weight,
        metrics=metrics,
    )

`feature_importance`

Compute a normalized feature importance vector from consequent weights.

Source code in highfis/estimators/_base.py

def feature_importance(self) -> np.ndarray | None:
    """Compute a normalized feature importance vector from consequent weights."""
    check_is_fitted(self, "model_")
    weights = self.model_.get_consequent_weights()
    if weights is None:
        return None

    consequent_layer = self.model_.consequent_layer
    if hasattr(consequent_layer, "rule_feature_mask"):
        rule_feature_mask = cast(Tensor, consequent_layer.rule_feature_mask)
        weights = weights * rule_feature_mask.unsqueeze(1) if weights.ndim == 3 else weights * rule_feature_mask

    abs_weights = weights.abs()
    if abs_weights.ndim == 3:
        importance = abs_weights.mean(dim=(0, 1))
    elif abs_weights.ndim == 2:
        importance = abs_weights.mean(dim=0)
    else:
        raise ValueError("unsupported consequent weight shape for feature importance")

    return _normalize_importance(importance)

`fit`

Train the TSK classifier on labeled samples.

Validation data should be supplied using x_val and y_val when available.

Source code in highfis/estimators/_base.py

def fit(
    self,
    x: Any,
    y: Any,
    *,
    x_val: Any | None = None,
    y_val: Any | None = None,
) -> Self:
    """Train the TSK classifier on labeled samples.

    Validation data should be supplied using ``x_val`` and ``y_val``
    when available.
    """
    x_arr, y_arr = check_X_y(x, y)

    if self.random_state is not None:
        torch.manual_seed(int(self.random_state))

    le = LabelEncoder()
    y_idx = le.fit_transform(np.asarray(y_arr))

    input_mfs, feature_names, effective_rule_base = self._build_input_mfs(x_arr)

    self.n_features_in_ = x_arr.shape[1]
    self.feature_names_in_ = np.asarray(feature_names, dtype=object)
    self.classes_ = le.classes_
    self._label_encoder_ = le

    _device = torch.device(str(self.device))
    self.model_ = self._build_model(input_mfs, len(self.classes_), effective_rule_base).to(_device)

    y_t = torch.as_tensor(y_idx, dtype=torch.long, device=_device)

    # Prepare validation tensors if provided via fit.
    x_val_t: torch.Tensor | None = None
    y_val_t: torch.Tensor | None = None
    if (x_val is None) ^ (y_val is None):
        raise ValueError("x_val and y_val must be provided together")
    if x_val is not None and y_val is not None:
        x_v_arr, y_v_arr = check_X_y(x_val, y_val)
        x_val_t = self._as_tensor_x(x_v_arr, _device)
        y_val_idx = le.transform(np.asarray(y_v_arr))
        y_val_t = torch.as_tensor(y_val_idx, dtype=torch.long, device=_device)

    self.history_ = self.model_.fit(
        self._as_tensor_x(x_arr, _device),
        y_t,
        epochs=int(self.epochs),
        learning_rate=float(self.learning_rate),
        batch_size=self.batch_size,
        shuffle=bool(self.shuffle),
        ur_weight=float(self.ur_weight),
        ur_target=self.ur_target,
        verbose=self.verbose,
        x_val=x_val_t,
        y_val=y_val_t,
        patience=self.patience,
        restore_best=self.restore_best,
        weight_decay=float(self.weight_decay),
    )
    self.rule_base_ = effective_rule_base
    return self

`get_mf_params`

Return model membership function metadata after fitting.

Source code in highfis/estimators/_base.py

def get_mf_params(self) -> dict[str, list[dict[str, Any]]]:
    """Return model membership function metadata after fitting."""
    check_is_fitted(self, "model_")
    return self.model_.get_mf_params()

`inspect`

Return a structured summary of fitted model state and rule metadata.

Source code in highfis/estimators/_base.py

def inspect(self) -> dict[str, Any]:
    """Return a structured summary of fitted model state and rule metadata."""
    check_is_fitted(self, "model_")
    return {
        "n_rules": int(self.model_.n_rules),
        "n_inputs": int(self.model_.n_inputs),
        "feature_names": list(self.model_.input_names),
        "rule_base": self.rule_base_,
        "defuzzifier_type": type(self.model_.defuzzifier).__name__,
        "mf_params": self.get_mf_params(),
        "rule_table": self.model_.get_rule_table(),
    }

`load` `classmethod`

Load a persisted estimator created by save.

Source code in highfis/estimators/_base.py

@classmethod
def load(cls, path: str) -> Self:
    """Load a persisted estimator created by save."""
    checkpoint = load_checkpoint(path)
    validate_checkpoint_payload(checkpoint, expected_estimator_class=cls.__name__)

    params: dict[str, Any] = dict(checkpoint["estimator_params"])
    if params.get("input_configs") is not None:
        params["input_configs"] = [InputConfig(**c) for c in params["input_configs"]]
    estimator = cls(**params)
    model_init = checkpoint["model_init"]
    estimator.rule_base_ = model_init["rule_base"]
    estimator.model_ = estimator._build_model(
        deserialize_input_mfs(model_init["input_mfs_config"]),
        int(model_init["n_classes"]),
        str(model_init["rule_base"]),
    )
    estimator.model_.load_state_dict(checkpoint["model_state_dict"])
    estimator.model_.to(torch.device(str(estimator.device)))

    fitted = checkpoint["fitted_attrs"]
    estimator.n_features_in_ = int(fitted["n_features_in"])
    estimator.feature_names_in_ = np.asarray(fitted["feature_names_in"], dtype=object)
    estimator.classes_ = np.asarray(fitted["classes"], dtype=object)
    label_encoder = LabelEncoder()
    label_encoder.classes_ = estimator.classes_
    estimator._label_encoder_ = label_encoder
    estimator.history_ = cast(dict[str, Any], checkpoint.get("history", {}))
    return estimator

`predict`

Predict class labels for input samples.

Source code in highfis/estimators/_base.py

def predict(self, x: Any) -> np.ndarray:
    """Predict class labels for input samples."""
    proba = self.predict_proba(x)
    y_idx = np.argmax(proba, axis=1)
    return np.asarray(self._label_encoder_.inverse_transform(y_idx))

`predict_proba`

Predict class probabilities for input samples.

Source code in highfis/estimators/_base.py

def predict_proba(self, x: Any) -> np.ndarray:
    """Predict class probabilities for input samples."""
    check_is_fitted(self, "model_")
    x_arr = check_array(x)
    if x_arr.shape[1] != self.n_features_in_:
        raise ValueError(f"expected {self.n_features_in_} features, got {x_arr.shape[1]}")
    probs = cast(Any, self.model_).predict_proba(self._as_tensor_x(x_arr, torch.device(str(self.device))))
    return probs.detach().cpu().numpy()

`rule_activation`

Return normalized rule activations for the provided inputs.

Source code in highfis/estimators/_base.py

def rule_activation(self, X: Any) -> np.ndarray:
    """Return normalized rule activations for the provided inputs."""
    check_is_fitted(self, "model_")
    x_arr = check_array(X)
    if x_arr.shape[1] != self.n_features_in_:
        raise ValueError(f"expected {self.n_features_in_} features, got {x_arr.shape[1]}")

    was_training = self.model_.training
    try:
        self.model_.eval()
        with torch.no_grad():
            norm_w = self.model_.forward_antecedents(self._as_tensor_x(x_arr, torch.device(str(self.device))))
    finally:
        self.model_.train(was_training)

    return _to_numpy(norm_w)

`save`

Persist estimator configuration, model weights and fitted metadata.

Source code in highfis/estimators/_base.py

def save(self, path: str) -> None:
    """Persist estimator configuration, model weights and fitted metadata."""
    checkpoint = self._build_checkpoint_base(
        model_init={
            "input_mfs_config": serialize_input_mfs(self.model_.input_mfs),
            "n_classes": len(self.classes_),
            "rule_base": self.rule_base_,
        },
        fitted_attrs={
            "n_features_in": int(self.n_features_in_),
            "feature_names_in": self.feature_names_in_.tolist(),
            "classes": self.classes_.tolist(),
        },
    )
    save_checkpoint(path, checkpoint)

`score`

Return classification accuracy on the provided dataset.

Source code in highfis/estimators/_base.py

def score(self, X: Any, y: Any, sample_weight: Any = None) -> float:
    """Return classification accuracy on the provided dataset."""
    y_true = np.asarray(y)
    y_pred = self.predict(X)
    return float(accuracy_score(y_true, y_pred, sample_weight=sample_weight))

`HTSKRegressor`

Bases: _BaseRegressorEstimator

HTSK regressor for high-dimensional TSK inference.

HTSK replaces the standard product t-norm with a geometric mean over membership values and performs rule normalization in log-space.

References

Y. Cui, D. Wu and Y. Xu, "Curse of Dimensionality for TSK Fuzzy Neural Networks: Explanation and Solutions," 2021 International Joint Conference on Neural Networks (IJCNN), Shenzhen, China, 2021, pp. 1-8, doi: 10.1109/IJCNN52387.2021.9534265.

Example

from highfis import HTSKRegressor

reg = HTSKRegressor()
reg.fit(X_train, y_train)

Initialise an HTSK regressor.

Parameters:

Name	Type	Description	Default
`input_configs`	`list[InputConfig] \| None`	Per-feature :class:`InputConfig` list. Only `name` is used when `mf_init="kmeans"`.	`None`
`n_mfs`	`int`	Number of k-means clusters / grid MFs.	`3`
`mf_init`	`str`	`"kmeans"` (default), `"minibatch_kmeans"`, `"fcm"`, or `"grid"`.	`'kmeans'`
`sigma_scale`	`float \| str`	Scale factor for sigma initialisation when `mf_init="kmeans"`. `1.0` is recommended for HTSK.	`1.0`
`random_state`	`int \| None`	Seed for k-means and weight initialisation.	`None`
`epochs`	`int`	Maximum training epochs (default `10`).	`10`
`learning_rate`	`float`	Adam learning rate (default `0.01`).	`0.01`
`verbose`	`bool \| int`	Print per-epoch progress.	`False`
`rule_base`	`str \| None`	`"coco"` or `"cartesian"`. Defaults to `"coco"` for kmeans and `"cartesian"` for grid.	`None`
`batch_size`	`int \| None`	Mini-batch size (default `512`).	`512`
`shuffle`	`bool`	Reshuffle each epoch.	`True`
`ur_weight`	`float`	Uncertainty regularisation weight.	`0.0`
`ur_target`	`float \| None`	Uncertainty regularisation target.	`None`
`consequent_batch_norm`	`bool`	Batch normalisation on consequent layers.	`False`
`pfrb_max_rules`	`int \| None`	Maximum point-based FRB rules (unused by HTSK).	`None`
`patience`	`int \| None`	Early-stopping patience (default `20`). Set to `None` to disable early stopping.	`20`
`restore_best`	`bool`	If `True` (default), restore the best validation model weights after training.	`True`
`weight_decay`	`float`	L2 weight decay for consequent parameters.	`1e-08`

Source code in highfis/estimators/_htsk.py

def __init__(
    self,
    *,
    input_configs: list[InputConfig] | None = None,
    n_mfs: int = 3,
    mf_init: str = "kmeans",
    sigma_scale: float | str = 1.0,
    random_state: int | None = None,
    epochs: int = 10,
    learning_rate: float = 1e-2,
    verbose: bool | int = False,
    rule_base: str | None = None,
    batch_size: int | None = 512,
    shuffle: bool = True,
    ur_weight: float = 0.0,
    ur_target: float | None = None,
    consequent_batch_norm: bool = False,
    pfrb_max_rules: int | None = None,
    patience: int | None = 20,
    restore_best: bool = True,
    weight_decay: float = 1e-8,
) -> None:
    """Initialise an HTSK regressor.

    Args:
        input_configs: Per-feature :class:`InputConfig` list. Only
            ``name`` is used when ``mf_init="kmeans"``.
        n_mfs: Number of k-means clusters / grid MFs.
        mf_init: ``"kmeans"`` (default), ``"minibatch_kmeans"``, ``"fcm"``, or ``"grid"``.
        sigma_scale: Scale factor for sigma initialisation when
            ``mf_init="kmeans"``. ``1.0`` is recommended for HTSK.
        random_state: Seed for k-means and weight initialisation.
        epochs: Maximum training epochs (default ``10``).
        learning_rate: Adam learning rate (default ``0.01``).
        verbose: Print per-epoch progress.
        rule_base: ``"coco"`` or ``"cartesian"``. Defaults to
            ``"coco"`` for kmeans and ``"cartesian"`` for grid.
        batch_size: Mini-batch size (default ``512``).
        shuffle: Reshuffle each epoch.
        ur_weight: Uncertainty regularisation weight.
        ur_target: Uncertainty regularisation target.
        consequent_batch_norm: Batch normalisation on consequent layers.
        pfrb_max_rules: Maximum point-based FRB rules (unused by HTSK).
        patience: Early-stopping patience (default ``20``). Set to ``None`` to disable early stopping.
        restore_best: If ``True`` (default), restore the best validation
            model weights after training.
        weight_decay: L2 weight decay for consequent parameters.
    """
    super().__init__(
        input_configs=input_configs,
        n_mfs=n_mfs,
        mf_init=mf_init,
        sigma_scale=sigma_scale,
        random_state=random_state,
        epochs=epochs,
        learning_rate=learning_rate,
        verbose=verbose,
        rule_base=rule_base,
        batch_size=batch_size,
        shuffle=shuffle,
        ur_weight=ur_weight,
        ur_target=ur_target,
        consequent_batch_norm=consequent_batch_norm,
        patience=patience,
        restore_best=restore_best,
        weight_decay=weight_decay,
    )

`evaluate`

Compute regression evaluation metrics for the provided dataset.

Source code in highfis/estimators/_base.py

def evaluate(
    self,
    X: Any,
    y: Any,
    metrics: list[str] | None = None,
    sample_weight: Any | None = None,
) -> dict[str, float]:
    """Compute regression evaluation metrics for the provided dataset."""
    y_true = np.asarray(y)
    y_pred = self.predict(X)
    return compute_metrics(
        task="regression",
        y_true=y_true,
        y_pred=y_pred,
        sample_weight=sample_weight,
        metrics=metrics,
    )

`feature_importance`

Compute a normalized feature importance vector from consequent weights.

Source code in highfis/estimators/_base.py

def feature_importance(self) -> np.ndarray | None:
    """Compute a normalized feature importance vector from consequent weights."""
    check_is_fitted(self, "model_")
    weights = self.model_.get_consequent_weights()
    if weights is None:
        return None

    consequent_layer = self.model_.consequent_layer
    if hasattr(consequent_layer, "rule_feature_mask"):
        rule_feature_mask = cast(Tensor, consequent_layer.rule_feature_mask)
        weights = weights * rule_feature_mask.unsqueeze(1) if weights.ndim == 3 else weights * rule_feature_mask

    abs_weights = weights.abs()
    if abs_weights.ndim == 3:
        importance = abs_weights.mean(dim=(0, 1))
    elif abs_weights.ndim == 2:
        importance = abs_weights.mean(dim=0)
    else:
        raise ValueError("unsupported consequent weight shape for feature importance")

    return _normalize_importance(importance)

`fit`

Train the TSK regressor on labeled samples.

Validation data should be supplied using x_val and y_val when available.

Source code in highfis/estimators/_base.py

def fit(
    self,
    x: Any,
    y: Any,
    *,
    x_val: Any | None = None,
    y_val: Any | None = None,
) -> Self:
    """Train the TSK regressor on labeled samples.

    Validation data should be supplied using ``x_val`` and ``y_val``
    when available.
    """
    x_arr, y_arr = check_X_y(x, y)

    if self.random_state is not None:
        torch.manual_seed(int(self.random_state))

    input_mfs, feature_names, effective_rule_base = self._build_input_mfs(x_arr)

    self.n_features_in_ = x_arr.shape[1]
    self.feature_names_in_ = np.asarray(feature_names, dtype=object)

    _device = torch.device(str(self.device))
    self.model_ = self._build_regressor_model(input_mfs, effective_rule_base).to(_device)

    y_t = torch.as_tensor(np.asarray(y_arr, dtype=np.float32), dtype=torch.float32, device=_device)

    # Prepare validation tensors if provided via fit.
    x_val_t: torch.Tensor | None = None
    y_val_t: torch.Tensor | None = None
    if (x_val is None) ^ (y_val is None):
        raise ValueError("x_val and y_val must be provided together")
    if x_val is not None and y_val is not None:
        x_v_arr, y_v_arr = check_X_y(x_val, y_val)
        x_val_t = self._as_tensor_x(x_v_arr, _device)
        y_val_t = torch.as_tensor(np.asarray(y_v_arr, dtype=np.float32), dtype=torch.float32, device=_device)

    self.history_ = self.model_.fit(
        self._as_tensor_x(x_arr, _device),
        y_t,
        epochs=int(self.epochs),
        learning_rate=float(self.learning_rate),
        batch_size=self.batch_size,
        shuffle=bool(self.shuffle),
        ur_weight=float(self.ur_weight),
        ur_target=self.ur_target,
        verbose=self.verbose,
        x_val=x_val_t,
        y_val=y_val_t,
        patience=self.patience,
        restore_best=self.restore_best,
        weight_decay=float(self.weight_decay),
    )
    self.rule_base_ = effective_rule_base
    return self

`get_mf_params`

Return model membership function metadata after fitting.

Source code in highfis/estimators/_base.py

def get_mf_params(self) -> dict[str, list[dict[str, Any]]]:
    """Return model membership function metadata after fitting."""
    check_is_fitted(self, "model_")
    return self.model_.get_mf_params()

`inspect`

Return a structured summary of fitted model state and rule metadata.

Source code in highfis/estimators/_base.py

def inspect(self) -> dict[str, Any]:
    """Return a structured summary of fitted model state and rule metadata."""
    check_is_fitted(self, "model_")
    return {
        "n_rules": int(self.model_.n_rules),
        "n_inputs": int(self.model_.n_inputs),
        "feature_names": list(self.model_.input_names),
        "rule_base": self.rule_base_,
        "defuzzifier_type": type(self.model_.defuzzifier).__name__,
        "mf_params": self.get_mf_params(),
        "rule_table": self.model_.get_rule_table(),
    }

`load` `classmethod`

Load a persisted estimator created by save.

Source code in highfis/estimators/_base.py

@classmethod
def load(cls, path: str) -> Self:
    """Load a persisted estimator created by save."""
    checkpoint = load_checkpoint(path)
    validate_checkpoint_payload(checkpoint, expected_estimator_class=cls.__name__)

    params: dict[str, Any] = dict(checkpoint["estimator_params"])
    if params.get("input_configs") is not None:
        params["input_configs"] = [InputConfig(**c) for c in params["input_configs"]]
    estimator = cls(**params)
    model_init = checkpoint["model_init"]
    estimator.rule_base_ = model_init["rule_base"]
    estimator.model_ = estimator._build_regressor_model(
        deserialize_input_mfs(model_init["input_mfs_config"]),
        str(model_init["rule_base"]),
    )
    estimator.model_.load_state_dict(checkpoint["model_state_dict"])
    estimator.model_.to(torch.device(str(estimator.device)))

    fitted = checkpoint["fitted_attrs"]
    estimator.n_features_in_ = int(fitted["n_features_in"])
    estimator.feature_names_in_ = np.asarray(fitted["feature_names_in"], dtype=object)
    estimator.history_ = cast(dict[str, Any], checkpoint.get("history", {}))
    return estimator

`predict`

Predict continuous target values for input samples.

Source code in highfis/estimators/_base.py

def predict(self, x: Any) -> np.ndarray:
    """Predict continuous target values for input samples."""
    check_is_fitted(self, "model_")
    x_arr = check_array(x)
    if x_arr.shape[1] != self.n_features_in_:
        raise ValueError(f"expected {self.n_features_in_} features, got {x_arr.shape[1]}")
    preds = cast(Any, self.model_).predict(self._as_tensor_x(x_arr, torch.device(str(self.device))))
    return preds.detach().cpu().numpy()

`rule_activation`

Return normalized rule activations for the provided inputs.

Source code in highfis/estimators/_base.py

def rule_activation(self, X: Any) -> np.ndarray:
    """Return normalized rule activations for the provided inputs."""
    check_is_fitted(self, "model_")
    x_arr = check_array(X)
    if x_arr.shape[1] != self.n_features_in_:
        raise ValueError(f"expected {self.n_features_in_} features, got {x_arr.shape[1]}")

    was_training = self.model_.training
    try:
        self.model_.eval()
        with torch.no_grad():
            norm_w = self.model_.forward_antecedents(self._as_tensor_x(x_arr, torch.device(str(self.device))))
    finally:
        self.model_.train(was_training)

    return _to_numpy(norm_w)

`save`

Persist estimator configuration, model weights and fitted metadata.

Source code in highfis/estimators/_base.py

def save(self, path: str) -> None:
    """Persist estimator configuration, model weights and fitted metadata."""
    checkpoint = self._build_checkpoint_base(
        model_init={
            "input_mfs_config": serialize_input_mfs(self.model_.input_mfs),
            "rule_base": self.rule_base_,
        },
        fitted_attrs={
            "n_features_in": int(self.n_features_in_),
            "feature_names_in": self.feature_names_in_.tolist(),
        },
    )
    save_checkpoint(path, checkpoint)

`InputConfig` `dataclass`

Per-feature configuration for Gaussian MF grid initialisation.

This dataclass controls how membership functions are placed on a single input feature when mf_init="grid". When mf_init="kmeans" only the name field is used; centres and sigmas are derived from k-means cluster centroids.

Attributes:

Name	Type	Description
`name`	`str`	Feature name. Used as the key in the membership-function dictionary passed to the underlying TSK model.
`n_mfs`	`int`	Number of Gaussian MFs to place on this feature. Must be `>= 1`.
`overlap`	`float`	Spacing factor between neighbouring MF centres. A larger value widens each MF (more overlap); `0.5` corresponds to roughly half-width overlap at the midpoint between centres.
`margin`	`float`	Fractional padding added to the observed feature range before centre placement. `0.10` extends each side of `[x_min, x_max]` by 10 percent so edge centres are not clipped to extreme values.

Example

from highfis.estimators import InputConfig

configs = [
    InputConfig(name="sepal_length", n_mfs=3),
    InputConfig(name="sepal_width", n_mfs=5, overlap=0.3),
]

`LogTSKClassifier`

Bases: _BaseClassifierEstimator

LogTSK classifier with inverse-log rule normalization.

LogTSK uses product antecedent aggregation and inverse-log normalization of log-domain rule strengths. The resulting rule weights are normalized with L1 normalization across rules, which makes the model scale-invariant in log-space and avoids the softmax saturation that occurs in high-dimensional inputs.

Reference

Y. Cui, D. Wu and Y. Xu, "Curse of Dimensionality for TSK Fuzzy Neural Networks: Explanation and Solutions," 2021 International Joint Conference on Neural Networks (IJCNN), pp. 1-8, doi: 10.1109/IJCNN52387.2021.9534265.

Example

from highfis import LogTSKClassifier

clf = LogTSKClassifier()
clf.fit(X_train, y_train)

Initialise a LogTSK classifier.

Parameters:

Name	Type	Description	Default
`input_configs`	`list[InputConfig] \| None`	Per-feature :class:`InputConfig` list.	`None`
`n_mfs`	`int`	Number of k-means clusters / grid MFs (default `5`).	`5`
`mf_init`	`str`	`"kmeans"` (default), `"minibatch_kmeans"`, `"fcm"`, or `"grid"`.	`'kmeans'`
`sigma_scale`	`float \| str`	Sigma scale factor. `1.0` is recommended (the log-space defuzzifier is scale-invariant).	`1.0`
`random_state`	`int \| None`	Seed for reproducibility.	`None`
`epochs`	`int`	Maximum training epochs (default `10`).	`10`
`learning_rate`	`float`	Adam learning rate (default `0.01`).	`0.01`
`verbose`	`bool \| int`	Print per-epoch progress.	`False`
`rule_base`	`str \| None`	`"coco"` or `"cartesian"`.	`None`
`batch_size`	`int \| None`	Mini-batch size (default `512`).	`512`
`shuffle`	`bool`	Reshuffle each epoch.	`True`
`ur_weight`	`float`	Uncertainty regularisation weight.	`0.0`
`ur_target`	`float \| None`	Uncertainty regularisation target.	`None`
`consequent_batch_norm`	`bool`	Batch normalisation on consequent layers.	`False`
`patience`	`int \| None`	Early-stopping patience (default `20`). Set to `None` to disable early stopping.	`20`
`restore_best`	`bool`	If `True` (default), restore the best validation model weights after training.	`True`
`weight_decay`	`float`	L2 weight decay for consequent parameters.	`1e-08`

Source code in highfis/estimators/_logtsk.py

def __init__(
    self,
    *,
    input_configs: list[InputConfig] | None = None,
    n_mfs: int = 5,
    mf_init: str = "kmeans",
    sigma_scale: float | str = 1.0,
    random_state: int | None = None,
    epochs: int = 10,
    learning_rate: float = 1e-2,
    verbose: bool | int = False,
    rule_base: str | None = None,
    batch_size: int | None = 512,
    shuffle: bool = True,
    ur_weight: float = 0.0,
    ur_target: float | None = None,
    consequent_batch_norm: bool = False,
    patience: int | None = 20,
    restore_best: bool = True,
    weight_decay: float = 1e-8,
) -> None:
    """Initialise a LogTSK classifier.

    Args:
        input_configs: Per-feature :class:`InputConfig` list.
        n_mfs: Number of k-means clusters / grid MFs (default ``5``).
        mf_init: ``"kmeans"`` (default), ``"minibatch_kmeans"``, ``"fcm"``, or ``"grid"``.
        sigma_scale: Sigma scale factor. ``1.0`` is recommended (the
            log-space defuzzifier is scale-invariant).
        random_state: Seed for reproducibility.
        epochs: Maximum training epochs (default ``10``).
        learning_rate: Adam learning rate (default ``0.01``).
        verbose: Print per-epoch progress.
        rule_base: ``"coco"`` or ``"cartesian"``.
        batch_size: Mini-batch size (default ``512``).
        shuffle: Reshuffle each epoch.
        ur_weight: Uncertainty regularisation weight.
        ur_target: Uncertainty regularisation target.
        consequent_batch_norm: Batch normalisation on consequent layers.
        patience: Early-stopping patience (default ``20``). Set to ``None`` to disable early stopping.
        restore_best: If ``True`` (default), restore the best validation
            model weights after training.
        weight_decay: L2 weight decay for consequent parameters.
    """
    super().__init__(
        input_configs=input_configs,
        n_mfs=n_mfs,
        mf_init=mf_init,
        sigma_scale=sigma_scale,
        random_state=random_state,
        epochs=epochs,
        learning_rate=learning_rate,
        verbose=verbose,
        rule_base=rule_base,
        batch_size=batch_size,
        shuffle=shuffle,
        ur_weight=ur_weight,
        ur_target=ur_target,
        consequent_batch_norm=consequent_batch_norm,
        patience=patience,
        restore_best=restore_best,
        weight_decay=weight_decay,
    )

`evaluate`

Compute classification evaluation metrics for the provided dataset.

Source code in highfis/estimators/_base.py

def evaluate(
    self,
    X: Any,
    y: Any,
    metrics: list[str] | None = None,
    sample_weight: Any | None = None,
) -> dict[str, float]:
    """Compute classification evaluation metrics for the provided dataset."""
    y_true = np.asarray(y)
    y_pred = self.predict(X)
    return compute_metrics(
        task="classification",
        y_true=y_true,
        y_pred=y_pred,
        sample_weight=sample_weight,
        metrics=metrics,
    )

`feature_importance`

Compute a normalized feature importance vector from consequent weights.

Source code in highfis/estimators/_base.py

def feature_importance(self) -> np.ndarray | None:
    """Compute a normalized feature importance vector from consequent weights."""
    check_is_fitted(self, "model_")
    weights = self.model_.get_consequent_weights()
    if weights is None:
        return None

    consequent_layer = self.model_.consequent_layer
    if hasattr(consequent_layer, "rule_feature_mask"):
        rule_feature_mask = cast(Tensor, consequent_layer.rule_feature_mask)
        weights = weights * rule_feature_mask.unsqueeze(1) if weights.ndim == 3 else weights * rule_feature_mask

    abs_weights = weights.abs()
    if abs_weights.ndim == 3:
        importance = abs_weights.mean(dim=(0, 1))
    elif abs_weights.ndim == 2:
        importance = abs_weights.mean(dim=0)
    else:
        raise ValueError("unsupported consequent weight shape for feature importance")

    return _normalize_importance(importance)

`fit`

Train the TSK classifier on labeled samples.

Validation data should be supplied using x_val and y_val when available.

Source code in highfis/estimators/_base.py

def fit(
    self,
    x: Any,
    y: Any,
    *,
    x_val: Any | None = None,
    y_val: Any | None = None,
) -> Self:
    """Train the TSK classifier on labeled samples.

    Validation data should be supplied using ``x_val`` and ``y_val``
    when available.
    """
    x_arr, y_arr = check_X_y(x, y)

    if self.random_state is not None:
        torch.manual_seed(int(self.random_state))

    le = LabelEncoder()
    y_idx = le.fit_transform(np.asarray(y_arr))

    input_mfs, feature_names, effective_rule_base = self._build_input_mfs(x_arr)

    self.n_features_in_ = x_arr.shape[1]
    self.feature_names_in_ = np.asarray(feature_names, dtype=object)
    self.classes_ = le.classes_
    self._label_encoder_ = le

    _device = torch.device(str(self.device))
    self.model_ = self._build_model(input_mfs, len(self.classes_), effective_rule_base).to(_device)

    y_t = torch.as_tensor(y_idx, dtype=torch.long, device=_device)

    # Prepare validation tensors if provided via fit.
    x_val_t: torch.Tensor | None = None
    y_val_t: torch.Tensor | None = None
    if (x_val is None) ^ (y_val is None):
        raise ValueError("x_val and y_val must be provided together")
    if x_val is not None and y_val is not None:
        x_v_arr, y_v_arr = check_X_y(x_val, y_val)
        x_val_t = self._as_tensor_x(x_v_arr, _device)
        y_val_idx = le.transform(np.asarray(y_v_arr))
        y_val_t = torch.as_tensor(y_val_idx, dtype=torch.long, device=_device)

    self.history_ = self.model_.fit(
        self._as_tensor_x(x_arr, _device),
        y_t,
        epochs=int(self.epochs),
        learning_rate=float(self.learning_rate),
        batch_size=self.batch_size,
        shuffle=bool(self.shuffle),
        ur_weight=float(self.ur_weight),
        ur_target=self.ur_target,
        verbose=self.verbose,
        x_val=x_val_t,
        y_val=y_val_t,
        patience=self.patience,
        restore_best=self.restore_best,
        weight_decay=float(self.weight_decay),
    )
    self.rule_base_ = effective_rule_base
    return self

`get_mf_params`

Return model membership function metadata after fitting.

Source code in highfis/estimators/_base.py

def get_mf_params(self) -> dict[str, list[dict[str, Any]]]:
    """Return model membership function metadata after fitting."""
    check_is_fitted(self, "model_")
    return self.model_.get_mf_params()

`inspect`

Return a structured summary of fitted model state and rule metadata.

Source code in highfis/estimators/_base.py

def inspect(self) -> dict[str, Any]:
    """Return a structured summary of fitted model state and rule metadata."""
    check_is_fitted(self, "model_")
    return {
        "n_rules": int(self.model_.n_rules),
        "n_inputs": int(self.model_.n_inputs),
        "feature_names": list(self.model_.input_names),
        "rule_base": self.rule_base_,
        "defuzzifier_type": type(self.model_.defuzzifier).__name__,
        "mf_params": self.get_mf_params(),
        "rule_table": self.model_.get_rule_table(),
    }

`load` `classmethod`

Load a persisted estimator created by save.

Source code in highfis/estimators/_base.py

@classmethod
def load(cls, path: str) -> Self:
    """Load a persisted estimator created by save."""
    checkpoint = load_checkpoint(path)
    validate_checkpoint_payload(checkpoint, expected_estimator_class=cls.__name__)

    params: dict[str, Any] = dict(checkpoint["estimator_params"])
    if params.get("input_configs") is not None:
        params["input_configs"] = [InputConfig(**c) for c in params["input_configs"]]
    estimator = cls(**params)
    model_init = checkpoint["model_init"]
    estimator.rule_base_ = model_init["rule_base"]
    estimator.model_ = estimator._build_model(
        deserialize_input_mfs(model_init["input_mfs_config"]),
        int(model_init["n_classes"]),
        str(model_init["rule_base"]),
    )
    estimator.model_.load_state_dict(checkpoint["model_state_dict"])
    estimator.model_.to(torch.device(str(estimator.device)))

    fitted = checkpoint["fitted_attrs"]
    estimator.n_features_in_ = int(fitted["n_features_in"])
    estimator.feature_names_in_ = np.asarray(fitted["feature_names_in"], dtype=object)
    estimator.classes_ = np.asarray(fitted["classes"], dtype=object)
    label_encoder = LabelEncoder()
    label_encoder.classes_ = estimator.classes_
    estimator._label_encoder_ = label_encoder
    estimator.history_ = cast(dict[str, Any], checkpoint.get("history", {}))
    return estimator

`predict`

Predict class labels for input samples.

Source code in highfis/estimators/_base.py

def predict(self, x: Any) -> np.ndarray:
    """Predict class labels for input samples."""
    proba = self.predict_proba(x)
    y_idx = np.argmax(proba, axis=1)
    return np.asarray(self._label_encoder_.inverse_transform(y_idx))

`predict_proba`

Predict class probabilities for input samples.

Source code in highfis/estimators/_base.py

def predict_proba(self, x: Any) -> np.ndarray:
    """Predict class probabilities for input samples."""
    check_is_fitted(self, "model_")
    x_arr = check_array(x)
    if x_arr.shape[1] != self.n_features_in_:
        raise ValueError(f"expected {self.n_features_in_} features, got {x_arr.shape[1]}")
    probs = cast(Any, self.model_).predict_proba(self._as_tensor_x(x_arr, torch.device(str(self.device))))
    return probs.detach().cpu().numpy()

`rule_activation`

Return normalized rule activations for the provided inputs.

Source code in highfis/estimators/_base.py

def rule_activation(self, X: Any) -> np.ndarray:
    """Return normalized rule activations for the provided inputs."""
    check_is_fitted(self, "model_")
    x_arr = check_array(X)
    if x_arr.shape[1] != self.n_features_in_:
        raise ValueError(f"expected {self.n_features_in_} features, got {x_arr.shape[1]}")

    was_training = self.model_.training
    try:
        self.model_.eval()
        with torch.no_grad():
            norm_w = self.model_.forward_antecedents(self._as_tensor_x(x_arr, torch.device(str(self.device))))
    finally:
        self.model_.train(was_training)

    return _to_numpy(norm_w)

`save`

Persist estimator configuration, model weights and fitted metadata.

Source code in highfis/estimators/_base.py

def save(self, path: str) -> None:
    """Persist estimator configuration, model weights and fitted metadata."""
    checkpoint = self._build_checkpoint_base(
        model_init={
            "input_mfs_config": serialize_input_mfs(self.model_.input_mfs),
            "n_classes": len(self.classes_),
            "rule_base": self.rule_base_,
        },
        fitted_attrs={
            "n_features_in": int(self.n_features_in_),
            "feature_names_in": self.feature_names_in_.tolist(),
            "classes": self.classes_.tolist(),
        },
    )
    save_checkpoint(path, checkpoint)

`score`

Return classification accuracy on the provided dataset.

Source code in highfis/estimators/_base.py

def score(self, X: Any, y: Any, sample_weight: Any = None) -> float:
    """Return classification accuracy on the provided dataset."""
    y_true = np.asarray(y)
    y_pred = self.predict(X)
    return float(accuracy_score(y_true, y_pred, sample_weight=sample_weight))

`LogTSKRegressor`

Bases: _BaseRegressorEstimator

LogTSK regressor with inverse-log rule normalization.

LogTSK uses product antecedent aggregation and inverse-log normalization of log-domain rule strengths. The resulting rule weights are normalized with L1 normalization across rules, which makes the model scale-invariant in log-space and avoids the softmax saturation that occurs in high-dimensional inputs.

Reference

Y. Cui, D. Wu and Y. Xu, "Curse of Dimensionality for TSK Fuzzy Neural Networks: Explanation and Solutions," 2021 International Joint Conference on Neural Networks (IJCNN), pp. 1-8, doi: 10.1109/IJCNN52387.2021.9534265.

Example

from highfis import LogTSKRegressor

reg = LogTSKRegressor()
reg.fit(X_train, y_train)

Initialise a LogTSK regressor.

Parameters:

Name	Type	Description	Default
`input_configs`	`list[InputConfig] \| None`	Per-feature :class:`InputConfig` list.	`None`
`n_mfs`	`int`	Number of k-means clusters / grid MFs (default `5`).	`5`
`mf_init`	`str`	`"kmeans"` (default), `"minibatch_kmeans"`, `"fcm"`, or `"grid"`.	`'kmeans'`
`sigma_scale`	`float \| str`	Sigma scale factor. `1.0` is recommended (the log-space defuzzifier is scale-invariant).	`1.0`
`random_state`	`int \| None`	Seed for reproducibility.	`None`
`epochs`	`int`	Maximum training epochs (default `10`).	`10`
`learning_rate`	`float`	Adam learning rate (default `0.01`).	`0.01`
`verbose`	`bool \| int`	Print per-epoch progress.	`False`
`rule_base`	`str \| None`	`"coco"` or `"cartesian"`.	`None`
`batch_size`	`int \| None`	Mini-batch size (default `512`).	`512`
`shuffle`	`bool`	Reshuffle each epoch.	`True`
`ur_weight`	`float`	Uncertainty regularisation weight.	`0.0`
`ur_target`	`float \| None`	Uncertainty regularisation target.	`None`
`consequent_batch_norm`	`bool`	Batch normalisation on consequent layers.	`False`
`patience`	`int \| None`	Early-stopping patience (default `20`). Set to `None` to disable early stopping.	`20`
`restore_best`	`bool`	If `True` (default), restore the best validation model weights after training.	`True`
`weight_decay`	`float`	L2 weight decay for consequent parameters.	`1e-08`

Source code in highfis/estimators/_logtsk.py

def __init__(
    self,
    *,
    input_configs: list[InputConfig] | None = None,
    n_mfs: int = 5,
    mf_init: str = "kmeans",
    sigma_scale: float | str = 1.0,
    random_state: int | None = None,
    epochs: int = 10,
    learning_rate: float = 1e-2,
    verbose: bool | int = False,
    rule_base: str | None = None,
    batch_size: int | None = 512,
    shuffle: bool = True,
    ur_weight: float = 0.0,
    ur_target: float | None = None,
    consequent_batch_norm: bool = False,
    patience: int | None = 20,
    restore_best: bool = True,
    weight_decay: float = 1e-8,
) -> None:
    """Initialise a LogTSK regressor.

    Args:
        input_configs: Per-feature :class:`InputConfig` list.
        n_mfs: Number of k-means clusters / grid MFs (default ``5``).
        mf_init: ``"kmeans"`` (default), ``"minibatch_kmeans"``, ``"fcm"``, or ``"grid"``.
        sigma_scale: Sigma scale factor. ``1.0`` is recommended (the
            log-space defuzzifier is scale-invariant).
        random_state: Seed for reproducibility.
        epochs: Maximum training epochs (default ``10``).
        learning_rate: Adam learning rate (default ``0.01``).
        verbose: Print per-epoch progress.
        rule_base: ``"coco"`` or ``"cartesian"``.
        batch_size: Mini-batch size (default ``512``).
        shuffle: Reshuffle each epoch.
        ur_weight: Uncertainty regularisation weight.
        ur_target: Uncertainty regularisation target.
        consequent_batch_norm: Batch normalisation on consequent layers.
        patience: Early-stopping patience (default ``20``). Set to ``None`` to disable early stopping.
        restore_best: If ``True`` (default), restore the best validation
            model weights after training.
        weight_decay: L2 weight decay for consequent parameters.
    """
    super().__init__(
        input_configs=input_configs,
        n_mfs=n_mfs,
        mf_init=mf_init,
        sigma_scale=sigma_scale,
        random_state=random_state,
        epochs=epochs,
        learning_rate=learning_rate,
        verbose=verbose,
        rule_base=rule_base,
        batch_size=batch_size,
        shuffle=shuffle,
        ur_weight=ur_weight,
        ur_target=ur_target,
        consequent_batch_norm=consequent_batch_norm,
        patience=patience,
        restore_best=restore_best,
        weight_decay=weight_decay,
    )

`evaluate`

Compute regression evaluation metrics for the provided dataset.

Source code in highfis/estimators/_base.py

def evaluate(
    self,
    X: Any,
    y: Any,
    metrics: list[str] | None = None,
    sample_weight: Any | None = None,
) -> dict[str, float]:
    """Compute regression evaluation metrics for the provided dataset."""
    y_true = np.asarray(y)
    y_pred = self.predict(X)
    return compute_metrics(
        task="regression",
        y_true=y_true,
        y_pred=y_pred,
        sample_weight=sample_weight,
        metrics=metrics,
    )

`feature_importance`

Compute a normalized feature importance vector from consequent weights.

Source code in highfis/estimators/_base.py

def feature_importance(self) -> np.ndarray | None:
    """Compute a normalized feature importance vector from consequent weights."""
    check_is_fitted(self, "model_")
    weights = self.model_.get_consequent_weights()
    if weights is None:
        return None

    consequent_layer = self.model_.consequent_layer
    if hasattr(consequent_layer, "rule_feature_mask"):
        rule_feature_mask = cast(Tensor, consequent_layer.rule_feature_mask)
        weights = weights * rule_feature_mask.unsqueeze(1) if weights.ndim == 3 else weights * rule_feature_mask

    abs_weights = weights.abs()
    if abs_weights.ndim == 3:
        importance = abs_weights.mean(dim=(0, 1))
    elif abs_weights.ndim == 2:
        importance = abs_weights.mean(dim=0)
    else:
        raise ValueError("unsupported consequent weight shape for feature importance")

    return _normalize_importance(importance)

`fit`

Train the TSK regressor on labeled samples.

Validation data should be supplied using x_val and y_val when available.

Source code in highfis/estimators/_base.py

def fit(
    self,
    x: Any,
    y: Any,
    *,
    x_val: Any | None = None,
    y_val: Any | None = None,
) -> Self:
    """Train the TSK regressor on labeled samples.

    Validation data should be supplied using ``x_val`` and ``y_val``
    when available.
    """
    x_arr, y_arr = check_X_y(x, y)

    if self.random_state is not None:
        torch.manual_seed(int(self.random_state))

    input_mfs, feature_names, effective_rule_base = self._build_input_mfs(x_arr)

    self.n_features_in_ = x_arr.shape[1]
    self.feature_names_in_ = np.asarray(feature_names, dtype=object)

    _device = torch.device(str(self.device))
    self.model_ = self._build_regressor_model(input_mfs, effective_rule_base).to(_device)

    y_t = torch.as_tensor(np.asarray(y_arr, dtype=np.float32), dtype=torch.float32, device=_device)

    # Prepare validation tensors if provided via fit.
    x_val_t: torch.Tensor | None = None
    y_val_t: torch.Tensor | None = None
    if (x_val is None) ^ (y_val is None):
        raise ValueError("x_val and y_val must be provided together")
    if x_val is not None and y_val is not None:
        x_v_arr, y_v_arr = check_X_y(x_val, y_val)
        x_val_t = self._as_tensor_x(x_v_arr, _device)
        y_val_t = torch.as_tensor(np.asarray(y_v_arr, dtype=np.float32), dtype=torch.float32, device=_device)

    self.history_ = self.model_.fit(
        self._as_tensor_x(x_arr, _device),
        y_t,
        epochs=int(self.epochs),
        learning_rate=float(self.learning_rate),
        batch_size=self.batch_size,
        shuffle=bool(self.shuffle),
        ur_weight=float(self.ur_weight),
        ur_target=self.ur_target,
        verbose=self.verbose,
        x_val=x_val_t,
        y_val=y_val_t,
        patience=self.patience,
        restore_best=self.restore_best,
        weight_decay=float(self.weight_decay),
    )
    self.rule_base_ = effective_rule_base
    return self

`get_mf_params`

Return model membership function metadata after fitting.

Source code in highfis/estimators/_base.py

def get_mf_params(self) -> dict[str, list[dict[str, Any]]]:
    """Return model membership function metadata after fitting."""
    check_is_fitted(self, "model_")
    return self.model_.get_mf_params()

`inspect`

Return a structured summary of fitted model state and rule metadata.

Source code in highfis/estimators/_base.py

def inspect(self) -> dict[str, Any]:
    """Return a structured summary of fitted model state and rule metadata."""
    check_is_fitted(self, "model_")
    return {
        "n_rules": int(self.model_.n_rules),
        "n_inputs": int(self.model_.n_inputs),
        "feature_names": list(self.model_.input_names),
        "rule_base": self.rule_base_,
        "defuzzifier_type": type(self.model_.defuzzifier).__name__,
        "mf_params": self.get_mf_params(),
        "rule_table": self.model_.get_rule_table(),
    }

`load` `classmethod`

Load a persisted estimator created by save.

Source code in highfis/estimators/_base.py

@classmethod
def load(cls, path: str) -> Self:
    """Load a persisted estimator created by save."""
    checkpoint = load_checkpoint(path)
    validate_checkpoint_payload(checkpoint, expected_estimator_class=cls.__name__)

    params: dict[str, Any] = dict(checkpoint["estimator_params"])
    if params.get("input_configs") is not None:
        params["input_configs"] = [InputConfig(**c) for c in params["input_configs"]]
    estimator = cls(**params)
    model_init = checkpoint["model_init"]
    estimator.rule_base_ = model_init["rule_base"]
    estimator.model_ = estimator._build_regressor_model(
        deserialize_input_mfs(model_init["input_mfs_config"]),
        str(model_init["rule_base"]),
    )
    estimator.model_.load_state_dict(checkpoint["model_state_dict"])
    estimator.model_.to(torch.device(str(estimator.device)))

    fitted = checkpoint["fitted_attrs"]
    estimator.n_features_in_ = int(fitted["n_features_in"])
    estimator.feature_names_in_ = np.asarray(fitted["feature_names_in"], dtype=object)
    estimator.history_ = cast(dict[str, Any], checkpoint.get("history", {}))
    return estimator

`predict`

Predict continuous target values for input samples.

Source code in highfis/estimators/_base.py

def predict(self, x: Any) -> np.ndarray:
    """Predict continuous target values for input samples."""
    check_is_fitted(self, "model_")
    x_arr = check_array(x)
    if x_arr.shape[1] != self.n_features_in_:
        raise ValueError(f"expected {self.n_features_in_} features, got {x_arr.shape[1]}")
    preds = cast(Any, self.model_).predict(self._as_tensor_x(x_arr, torch.device(str(self.device))))
    return preds.detach().cpu().numpy()

`rule_activation`

Return normalized rule activations for the provided inputs.

Source code in highfis/estimators/_base.py

def rule_activation(self, X: Any) -> np.ndarray:
    """Return normalized rule activations for the provided inputs."""
    check_is_fitted(self, "model_")
    x_arr = check_array(X)
    if x_arr.shape[1] != self.n_features_in_:
        raise ValueError(f"expected {self.n_features_in_} features, got {x_arr.shape[1]}")

    was_training = self.model_.training
    try:
        self.model_.eval()
        with torch.no_grad():
            norm_w = self.model_.forward_antecedents(self._as_tensor_x(x_arr, torch.device(str(self.device))))
    finally:
        self.model_.train(was_training)

    return _to_numpy(norm_w)

`save`

Persist estimator configuration, model weights and fitted metadata.

Source code in highfis/estimators/_base.py

def save(self, path: str) -> None:
    """Persist estimator configuration, model weights and fitted metadata."""
    checkpoint = self._build_checkpoint_base(
        model_init={
            "input_mfs_config": serialize_input_mfs(self.model_.input_mfs),
            "rule_base": self.rule_base_,
        },
        fitted_attrs={
            "n_features_in": int(self.n_features_in_),
            "feature_names_in": self.feature_names_in_.tolist(),
        },
    )
    save_checkpoint(path, checkpoint)

`MHTSKClassifier`

Bases: _BaseClassifierEstimator

Estimator for the multihead Takagi-Sugeno-Kang fuzzy system.

This estimator supports paper-derived automatic scale parameter resolution for head size and number of heads, and it optionally subsamples instances when building each head as described in the MHTSK paper.

MHTSK builds multiple sparse subantecedents from random feature subsets and jointly optimizes their rule consequents.

Reference

Z. Bian, Q. Chang, J. Wang and N. R. Pal, "Multihead Takagi-Sugeno-Kang Fuzzy System," in IEEE Transactions on Fuzzy Systems, vol. 33, no. 8, pp. 2561-2573, Aug. 2025, doi: 10.1109/TFUZZ.2025.3569227.

Example

from highfis import MHTSKClassifier

clf = MHTSKClassifier()
clf.fit(X_train, y_train)

Initialize a MHTSK classifier estimator.

Parameters:

Name	Type	Description	Default
`input_configs`	`list[InputConfig] \| None`	Optional list of per-feature input configurations. Only the feature names are used for FCM-based MHTSK head construction.	`None`
`n_mfs`	`int`	Number of FCM clusters per head (number of rules generated by each head).	`3`
`n_heads`	`int \| None`	Number of random heads. If `None`, this is resolved from `head_size` together with `fcr_target` or `h_value`.	`None`
`head_size`	`int \| None`	Number of features sampled per head. If `None`, defaults to `round(D * 0.02)` for `D <= 5000` and `round(D * 0.01)` for larger inputs.	`None`
`head_size_ratio`	`float \| None`	Alternative relative head size, as a fraction of the input dimension.	`None`
`fcm_m`	`float`	Fuzzification exponent for FCM cluster fitting.	`2.0`
`rule_sigma`	`float`	Gaussian sigma applied to rule antecedent membership functions.	`1.0`
`fcr_target`	`float`	Target feature coverage rate for randomly sampled heads.	`0.85`
`h_value`	`float \| None`	Paper-derived scale constant `H` used to compute the number of heads. When set, this overrides `fcr_target`.	`None`
`xi`	`float`	Numeric underflow threshold constant used to bound `head_size`.	`743.0`
`instance_sample_fraction`	`float`	Fraction of training instances sampled per head for FCM.	`0.8`
`rule_extraction`	`bool`	If `True`, perform post-fit rule extraction (MHTSK_RE).	`False`
`crcr_us`	`float`	Unsupervised cumulative rule contribution rate target used in extraction.	`0.5`
`crcr_s`	`float`	Supervised cumulative rule contribution rate target used in extraction.	`0.5`
`retrain_after_extraction`	`bool`	If `True`, retrain the extracted rule base after extraction.	`True`
`random_state`	`int \| None`	Random seed for reproducible head construction and FCM initialization.	`None`
`epochs`	`int`	Maximum number of training epochs.	`10`
`learning_rate`	`float`	Adam optimizer learning rate.	`0.01`
`verbose`	`bool \| int`	Verbosity level during training.	`False`
`batch_size`	`int \| None`	Mini-batch size for gradient descent.	`512`
`shuffle`	`bool`	Whether to shuffle training samples each epoch.	`True`
`ur_weight`	`float`	Weight of the uncertainty regularization term.	`0.0`
`ur_target`	`float \| None`	Target firing-level for uncertainty regularization.	`None`
`consequent_batch_norm`	`bool`	Apply batch normalization to the consequent layer inputs.	`False`
`patience`	`int \| None`	Early-stopping patience for validation.	`20`
`restore_best`	`bool`	Whether to restore the best validation model weights after training.	`True`
`weight_decay`	`float`	Weight decay coefficient for the optimizer.	`1e-08`

Source code in highfis/estimators/_mhtsk.py

def __init__(
    self,
    *,
    input_configs: list[InputConfig] | None = None,
    n_mfs: int = 3,
    n_heads: int | None = None,
    head_size: int | None = None,
    head_size_ratio: float | None = None,
    fcm_m: float = 2.0,
    rule_sigma: float = 1.0,
    fcr_target: float = 0.85,
    h_value: float | None = None,
    xi: float = 743.0,
    instance_sample_fraction: float = 0.8,
    rule_extraction: bool = False,
    crcr_us: float = 0.5,
    crcr_s: float = 0.5,
    retrain_after_extraction: bool = True,
    random_state: int | None = None,
    epochs: int = 10,
    learning_rate: float = 1e-2,
    verbose: bool | int = False,
    batch_size: int | None = 512,
    shuffle: bool = True,
    ur_weight: float = 0.0,
    ur_target: float | None = None,
    consequent_batch_norm: bool = False,
    patience: int | None = 20,
    restore_best: bool = True,
    weight_decay: float = 1e-8,
) -> None:
    """Initialize a MHTSK classifier estimator.

    Args:
        input_configs: Optional list of per-feature input configurations.
            Only the feature names are used for FCM-based MHTSK head construction.
        n_mfs: Number of FCM clusters per head (number of rules generated by each head).
        n_heads: Number of random heads. If ``None``, this is resolved from
            ``head_size`` together with ``fcr_target`` or ``h_value``.
        head_size: Number of features sampled per head. If ``None``, defaults to
            ``round(D * 0.02)`` for ``D <= 5000`` and ``round(D * 0.01)`` for larger inputs.
        head_size_ratio: Alternative relative head size, as a fraction of the input dimension.
        fcm_m: Fuzzification exponent for FCM cluster fitting.
        rule_sigma: Gaussian sigma applied to rule antecedent membership functions.
        fcr_target: Target feature coverage rate for randomly sampled heads.
        h_value: Paper-derived scale constant ``H`` used to compute the number of heads.
            When set, this overrides ``fcr_target``.
        xi: Numeric underflow threshold constant used to bound ``head_size``.
        instance_sample_fraction: Fraction of training instances sampled per head for FCM.
        rule_extraction: If ``True``, perform post-fit rule extraction (MHTSK_RE).
        crcr_us: Unsupervised cumulative rule contribution rate target used in extraction.
        crcr_s: Supervised cumulative rule contribution rate target used in extraction.
        retrain_after_extraction: If ``True``, retrain the extracted rule base after extraction.
        random_state: Random seed for reproducible head construction and FCM initialization.
        epochs: Maximum number of training epochs.
        learning_rate: Adam optimizer learning rate.
        verbose: Verbosity level during training.
        batch_size: Mini-batch size for gradient descent.
        shuffle: Whether to shuffle training samples each epoch.
        ur_weight: Weight of the uncertainty regularization term.
        ur_target: Target firing-level for uncertainty regularization.
        consequent_batch_norm: Apply batch normalization to the consequent layer inputs.
        patience: Early-stopping patience for validation.
        restore_best: Whether to restore the best validation model weights after training.
        weight_decay: Weight decay coefficient for the optimizer.
    """
    super().__init__(
        input_configs=input_configs,
        n_mfs=n_mfs,
        mf_init="fcm",
        sigma_scale=1.0,
        random_state=random_state,
        epochs=epochs,
        learning_rate=learning_rate,
        verbose=verbose,
        rule_base="custom",
        batch_size=batch_size,
        shuffle=shuffle,
        ur_weight=ur_weight,
        ur_target=ur_target,
        consequent_batch_norm=consequent_batch_norm,
        pfrb_max_rules=None,
        patience=patience,
        restore_best=restore_best,
        weight_decay=weight_decay,
    )
    self.n_heads = int(n_heads) if n_heads is not None else None
    self.head_size = int(head_size) if head_size is not None else None
    self.head_size_ratio = float(head_size_ratio) if head_size_ratio is not None else None
    self.fcm_m = float(fcm_m)
    self.rule_sigma = float(rule_sigma)
    self.fcr_target = float(fcr_target)
    self.h_value = float(h_value) if h_value is not None else None
    self.xi = float(xi)
    self.instance_sample_fraction = float(instance_sample_fraction)
    self.rule_extraction = bool(rule_extraction)
    self.crcr_us = float(crcr_us)
    self.crcr_s = float(crcr_s)
    self.retrain_after_extraction = bool(retrain_after_extraction)
    self._extracted_rule_indices_: list[int] | None = None

`evaluate`

Compute classification evaluation metrics for the provided dataset.

Source code in highfis/estimators/_base.py

def evaluate(
    self,
    X: Any,
    y: Any,
    metrics: list[str] | None = None,
    sample_weight: Any | None = None,
) -> dict[str, float]:
    """Compute classification evaluation metrics for the provided dataset."""
    y_true = np.asarray(y)
    y_pred = self.predict(X)
    return compute_metrics(
        task="classification",
        y_true=y_true,
        y_pred=y_pred,
        sample_weight=sample_weight,
        metrics=metrics,
    )

`feature_importance`

Compute a normalized feature importance vector from consequent weights.

Source code in highfis/estimators/_base.py

def feature_importance(self) -> np.ndarray | None:
    """Compute a normalized feature importance vector from consequent weights."""
    check_is_fitted(self, "model_")
    weights = self.model_.get_consequent_weights()
    if weights is None:
        return None

    consequent_layer = self.model_.consequent_layer
    if hasattr(consequent_layer, "rule_feature_mask"):
        rule_feature_mask = cast(Tensor, consequent_layer.rule_feature_mask)
        weights = weights * rule_feature_mask.unsqueeze(1) if weights.ndim == 3 else weights * rule_feature_mask

    abs_weights = weights.abs()
    if abs_weights.ndim == 3:
        importance = abs_weights.mean(dim=(0, 1))
    elif abs_weights.ndim == 2:
        importance = abs_weights.mean(dim=0)
    else:
        raise ValueError("unsupported consequent weight shape for feature importance")

    return _normalize_importance(importance)

`fit`

Train the MHTSK classifier and optionally extract rules.

After the base training step, if rule_extraction is enabled, the firing-strength matrix is used to select a compact rule subset via the CRCR criterion. When retrain_after_extraction is also set, a second training pass is performed on the reduced model.

Source code in highfis/estimators/_mhtsk.py

def fit(self, x: Any, y: Any, *, x_val: Any | None = None, y_val: Any | None = None) -> Self:
    """Train the MHTSK classifier and optionally extract rules.

    After the base training step, if ``rule_extraction`` is enabled, the
    firing-strength matrix is used to select a compact rule subset via the
    CRCR criterion.  When ``retrain_after_extraction`` is also set, a
    second training pass is performed on the reduced model.
    """
    x_arr, y_arr = check_X_y(x, y)
    super().fit(x, y, x_val=x_val, y_val=y_val)

    if not bool(self.rule_extraction):
        return self

    x_t = self._as_tensor_x(x_arr)
    self.model_.eval()
    with torch.no_grad():
        norm_w = self.model_.forward_antecedents(x_t)

    y_t = torch.as_tensor(self._label_encoder_.transform(np.asarray(y_arr)), dtype=torch.long)
    selected = _extract_mhtsk_rule_indices(norm_w, y_t, self.crcr_us, self.crcr_s)
    self._extracted_rule_indices_ = selected

    input_mfs = self.model_.input_mfs
    self._build_extracted_model(input_mfs, selected)

    if self.retrain_after_extraction:
        x_val_t: torch.Tensor | None = None
        y_val_t: torch.Tensor | None = None
        if x_val is not None and y_val is not None:
            x_v_arr, y_v_arr = check_X_y(x_val, y_val)
            x_val_t = self._as_tensor_x(x_v_arr)
            y_val_t = torch.as_tensor(
                self._label_encoder_.transform(np.asarray(y_v_arr)),
                dtype=torch.long,
            )
        self.history_ = self.model_.fit(
            x_t,
            y_t,
            epochs=int(self.epochs),
            learning_rate=float(self.learning_rate),
            batch_size=self.batch_size,
            shuffle=bool(self.shuffle),
            ur_weight=float(self.ur_weight),
            ur_target=self.ur_target,
            verbose=self.verbose,
            x_val=x_val_t,
            y_val=y_val_t,
            patience=self.patience,
            restore_best=self.restore_best,
            weight_decay=float(self.weight_decay),
        )
    return self

`get_mf_params`

Return model membership function metadata after fitting.

Source code in highfis/estimators/_base.py

def get_mf_params(self) -> dict[str, list[dict[str, Any]]]:
    """Return model membership function metadata after fitting."""
    check_is_fitted(self, "model_")
    return self.model_.get_mf_params()

`inspect`

Return a structured summary of fitted model state and rule metadata.

Source code in highfis/estimators/_base.py

def inspect(self) -> dict[str, Any]:
    """Return a structured summary of fitted model state and rule metadata."""
    check_is_fitted(self, "model_")
    return {
        "n_rules": int(self.model_.n_rules),
        "n_inputs": int(self.model_.n_inputs),
        "feature_names": list(self.model_.input_names),
        "rule_base": self.rule_base_,
        "defuzzifier_type": type(self.model_.defuzzifier).__name__,
        "mf_params": self.get_mf_params(),
        "rule_table": self.model_.get_rule_table(),
    }

`load` `classmethod`

Load a persisted estimator created by save.

Source code in highfis/estimators/_base.py

@classmethod
def load(cls, path: str) -> Self:
    """Load a persisted estimator created by save."""
    checkpoint = load_checkpoint(path)
    validate_checkpoint_payload(checkpoint, expected_estimator_class=cls.__name__)

    params: dict[str, Any] = dict(checkpoint["estimator_params"])
    if params.get("input_configs") is not None:
        params["input_configs"] = [InputConfig(**c) for c in params["input_configs"]]
    estimator = cls(**params)
    model_init = checkpoint["model_init"]
    estimator.rule_base_ = model_init["rule_base"]
    estimator.model_ = estimator._build_model(
        deserialize_input_mfs(model_init["input_mfs_config"]),
        int(model_init["n_classes"]),
        str(model_init["rule_base"]),
    )
    estimator.model_.load_state_dict(checkpoint["model_state_dict"])
    estimator.model_.to(torch.device(str(estimator.device)))

    fitted = checkpoint["fitted_attrs"]
    estimator.n_features_in_ = int(fitted["n_features_in"])
    estimator.feature_names_in_ = np.asarray(fitted["feature_names_in"], dtype=object)
    estimator.classes_ = np.asarray(fitted["classes"], dtype=object)
    label_encoder = LabelEncoder()
    label_encoder.classes_ = estimator.classes_
    estimator._label_encoder_ = label_encoder
    estimator.history_ = cast(dict[str, Any], checkpoint.get("history", {}))
    return estimator

`predict`

Predict class labels for input samples.

Source code in highfis/estimators/_base.py

def predict(self, x: Any) -> np.ndarray:
    """Predict class labels for input samples."""
    proba = self.predict_proba(x)
    y_idx = np.argmax(proba, axis=1)
    return np.asarray(self._label_encoder_.inverse_transform(y_idx))

`predict_proba`

Predict class probabilities for input samples.

Source code in highfis/estimators/_base.py

def predict_proba(self, x: Any) -> np.ndarray:
    """Predict class probabilities for input samples."""
    check_is_fitted(self, "model_")
    x_arr = check_array(x)
    if x_arr.shape[1] != self.n_features_in_:
        raise ValueError(f"expected {self.n_features_in_} features, got {x_arr.shape[1]}")
    probs = cast(Any, self.model_).predict_proba(self._as_tensor_x(x_arr, torch.device(str(self.device))))
    return probs.detach().cpu().numpy()

`rule_activation`

Return normalized rule activations for the provided inputs.

Source code in highfis/estimators/_base.py

def rule_activation(self, X: Any) -> np.ndarray:
    """Return normalized rule activations for the provided inputs."""
    check_is_fitted(self, "model_")
    x_arr = check_array(X)
    if x_arr.shape[1] != self.n_features_in_:
        raise ValueError(f"expected {self.n_features_in_} features, got {x_arr.shape[1]}")

    was_training = self.model_.training
    try:
        self.model_.eval()
        with torch.no_grad():
            norm_w = self.model_.forward_antecedents(self._as_tensor_x(x_arr, torch.device(str(self.device))))
    finally:
        self.model_.train(was_training)

    return _to_numpy(norm_w)

`save`

Persist estimator configuration, model weights and fitted metadata.

Source code in highfis/estimators/_base.py

def save(self, path: str) -> None:
    """Persist estimator configuration, model weights and fitted metadata."""
    checkpoint = self._build_checkpoint_base(
        model_init={
            "input_mfs_config": serialize_input_mfs(self.model_.input_mfs),
            "n_classes": len(self.classes_),
            "rule_base": self.rule_base_,
        },
        fitted_attrs={
            "n_features_in": int(self.n_features_in_),
            "feature_names_in": self.feature_names_in_.tolist(),
            "classes": self.classes_.tolist(),
        },
    )
    save_checkpoint(path, checkpoint)

`score`

Return classification accuracy on the provided dataset.

Source code in highfis/estimators/_base.py

def score(self, X: Any, y: Any, sample_weight: Any = None) -> float:
    """Return classification accuracy on the provided dataset."""
    y_true = np.asarray(y)
    y_pred = self.predict(X)
    return float(accuracy_score(y_true, y_pred, sample_weight=sample_weight))

`MHTSKRegressor`

Bases: _BaseRegressorEstimator

Estimator for the multihead Takagi-Sugeno-Kang fuzzy system.

The regressor uses the same MHTSK head construction and scale parameter strategy as the classifier. Rule extraction is currently implemented with an unsupervised scheme only, since regression does not provide class labels for the Mann-Whitney based selection used in classification.

MHTSK builds multiple sparse subantecedents from random feature subsets and jointly optimizes their rule consequents.

Reference

Z. Bian, Q. Chang, J. Wang and N. R. Pal, "Multihead Takagi-Sugeno-Kang Fuzzy System," in IEEE Transactions on Fuzzy Systems, vol. 33, no. 8, pp. 2561-2573, Aug. 2025, doi: 10.1109/TFUZZ.2025.3569227.

Example

from highfis import MHTSKRegressor

reg = MHTSKRegressor()
reg.fit(X_train, y_train)

Initialize a MHTSK regressor estimator.

Parameters:

Name	Type	Description	Default
`input_configs`	`list[InputConfig] \| None`	Optional list of per-feature input configurations. Only the feature names are used for FCM-based MHTSK head construction.	`None`
`n_mfs`	`int`	Number of FCM clusters per head (number of rules generated by each head).	`3`
`n_heads`	`int \| None`	Number of random heads. If `None`, this is resolved from `head_size` together with `fcr_target` or `h_value`.	`None`
`head_size`	`int \| None`	Number of features sampled per head. If `None`, defaults to `round(D * 0.02)` for `D <= 5000` and `round(D * 0.01)` for larger inputs.	`None`
`head_size_ratio`	`float \| None`	Alternative relative head size, as a fraction of the input dimension.	`None`
`fcm_m`	`float`	Fuzzification exponent for FCM cluster fitting.	`2.0`
`rule_sigma`	`float`	Gaussian sigma applied to rule antecedent membership functions.	`1.0`
`fcr_target`	`float`	Target feature coverage rate for randomly sampled heads.	`0.85`
`h_value`	`float \| None`	Paper-derived scale constant `H` used to compute the number of heads. When set, this overrides `fcr_target`.	`None`
`xi`	`float`	Numeric underflow threshold constant used to bound `head_size`.	`743.0`
`instance_sample_fraction`	`float`	Fraction of training instances sampled per head for FCM.	`0.8`
`rule_extraction`	`bool`	If `True`, perform post-fit rule extraction.	`False`
`crcr_us`	`float`	Unsupervised cumulative rule contribution rate target used in extraction.	`0.5`
`retrain_after_extraction`	`bool`	If `True`, retrain the extracted rule base after extraction.	`True`
`random_state`	`int \| None`	Random seed for reproducible head construction and FCM initialization.	`None`
`epochs`	`int`	Maximum number of training epochs.	`10`
`learning_rate`	`float`	Adam optimizer learning rate.	`0.01`
`verbose`	`bool \| int`	Verbosity level during training.	`False`
`batch_size`	`int \| None`	Mini-batch size for gradient descent.	`512`
`shuffle`	`bool`	Whether to shuffle training samples each epoch.	`True`
`ur_weight`	`float`	Weight of the uncertainty regularization term.	`0.0`
`ur_target`	`float \| None`	Target firing-level for uncertainty regularization.	`None`
`consequent_batch_norm`	`bool`	Apply batch normalization to the consequent layer inputs.	`False`
`patience`	`int \| None`	Early-stopping patience for validation.	`20`
`restore_best`	`bool`	Whether to restore the best validation model weights after training.	`True`
`weight_decay`	`float`	Weight decay coefficient for the optimizer.	`1e-08`

Notes

The regressor supports only unsupervised rule extraction via crcr_us because no label-based Mann-Whitney selection is available.

Source code in highfis/estimators/_mhtsk.py

def __init__(
    self,
    *,
    input_configs: list[InputConfig] | None = None,
    n_mfs: int = 3,
    n_heads: int | None = None,
    head_size: int | None = None,
    head_size_ratio: float | None = None,
    fcm_m: float = 2.0,
    rule_sigma: float = 1.0,
    fcr_target: float = 0.85,
    h_value: float | None = None,
    xi: float = 743.0,
    instance_sample_fraction: float = 0.8,
    rule_extraction: bool = False,
    crcr_us: float = 0.5,
    retrain_after_extraction: bool = True,
    random_state: int | None = None,
    epochs: int = 10,
    learning_rate: float = 1e-2,
    verbose: bool | int = False,
    batch_size: int | None = 512,
    shuffle: bool = True,
    ur_weight: float = 0.0,
    ur_target: float | None = None,
    consequent_batch_norm: bool = False,
    patience: int | None = 20,
    restore_best: bool = True,
    weight_decay: float = 1e-8,
) -> None:
    """Initialize a MHTSK regressor estimator.

    Args:
        input_configs: Optional list of per-feature input configurations.
            Only the feature names are used for FCM-based MHTSK head construction.
        n_mfs: Number of FCM clusters per head (number of rules generated by each head).
        n_heads: Number of random heads. If ``None``, this is resolved from
            ``head_size`` together with ``fcr_target`` or ``h_value``.
        head_size: Number of features sampled per head. If ``None``, defaults to
            ``round(D * 0.02)`` for ``D <= 5000`` and ``round(D * 0.01)`` for larger inputs.
        head_size_ratio: Alternative relative head size, as a fraction of the input dimension.
        fcm_m: Fuzzification exponent for FCM cluster fitting.
        rule_sigma: Gaussian sigma applied to rule antecedent membership functions.
        fcr_target: Target feature coverage rate for randomly sampled heads.
        h_value: Paper-derived scale constant ``H`` used to compute the number of heads.
            When set, this overrides ``fcr_target``.
        xi: Numeric underflow threshold constant used to bound ``head_size``.
        instance_sample_fraction: Fraction of training instances sampled per head for FCM.
        rule_extraction: If ``True``, perform post-fit rule extraction.
        crcr_us: Unsupervised cumulative rule contribution rate target used in extraction.
        retrain_after_extraction: If ``True``, retrain the extracted rule base after extraction.
        random_state: Random seed for reproducible head construction and FCM initialization.
        epochs: Maximum number of training epochs.
        learning_rate: Adam optimizer learning rate.
        verbose: Verbosity level during training.
        batch_size: Mini-batch size for gradient descent.
        shuffle: Whether to shuffle training samples each epoch.
        ur_weight: Weight of the uncertainty regularization term.
        ur_target: Target firing-level for uncertainty regularization.
        consequent_batch_norm: Apply batch normalization to the consequent layer inputs.
        patience: Early-stopping patience for validation.
        restore_best: Whether to restore the best validation model weights after training.
        weight_decay: Weight decay coefficient for the optimizer.

    Notes:
        The regressor supports only unsupervised rule extraction via
        ``crcr_us`` because no label-based Mann-Whitney selection is available.
    """
    super().__init__(
        input_configs=input_configs,
        n_mfs=n_mfs,
        mf_init="fcm",
        sigma_scale=1.0,
        random_state=random_state,
        epochs=epochs,
        learning_rate=learning_rate,
        verbose=verbose,
        rule_base="custom",
        batch_size=batch_size,
        shuffle=shuffle,
        ur_weight=ur_weight,
        ur_target=ur_target,
        consequent_batch_norm=consequent_batch_norm,
        pfrb_max_rules=None,
        patience=patience,
        restore_best=restore_best,
        weight_decay=weight_decay,
    )
    self.n_heads = int(n_heads) if n_heads is not None else None
    self.head_size = int(head_size) if head_size is not None else None
    self.head_size_ratio = float(head_size_ratio) if head_size_ratio is not None else None
    self.fcm_m = float(fcm_m)
    self.rule_sigma = float(rule_sigma)
    self.fcr_target = float(fcr_target)
    self.h_value = float(h_value) if h_value is not None else None
    self.xi = float(xi)
    self.instance_sample_fraction = float(instance_sample_fraction)
    self.rule_extraction = bool(rule_extraction)
    self.crcr_us = float(crcr_us)
    self.retrain_after_extraction = bool(retrain_after_extraction)
    self._extracted_rule_indices_: list[int] | None = None

`evaluate`

Compute regression evaluation metrics for the provided dataset.

Source code in highfis/estimators/_base.py

def evaluate(
    self,
    X: Any,
    y: Any,
    metrics: list[str] | None = None,
    sample_weight: Any | None = None,
) -> dict[str, float]:
    """Compute regression evaluation metrics for the provided dataset."""
    y_true = np.asarray(y)
    y_pred = self.predict(X)
    return compute_metrics(
        task="regression",
        y_true=y_true,
        y_pred=y_pred,
        sample_weight=sample_weight,
        metrics=metrics,
    )

`feature_importance`

Compute a normalized feature importance vector from consequent weights.

Source code in highfis/estimators/_base.py

def feature_importance(self) -> np.ndarray | None:
    """Compute a normalized feature importance vector from consequent weights."""
    check_is_fitted(self, "model_")
    weights = self.model_.get_consequent_weights()
    if weights is None:
        return None

    consequent_layer = self.model_.consequent_layer
    if hasattr(consequent_layer, "rule_feature_mask"):
        rule_feature_mask = cast(Tensor, consequent_layer.rule_feature_mask)
        weights = weights * rule_feature_mask.unsqueeze(1) if weights.ndim == 3 else weights * rule_feature_mask

    abs_weights = weights.abs()
    if abs_weights.ndim == 3:
        importance = abs_weights.mean(dim=(0, 1))
    elif abs_weights.ndim == 2:
        importance = abs_weights.mean(dim=0)
    else:
        raise ValueError("unsupported consequent weight shape for feature importance")

    return _normalize_importance(importance)

`fit`

Train the MHTSK regressor and optionally extract rules.

After the base training step, if rule_extraction is enabled, rules are selected via the unsupervised CRCR criterion on the firing-strength matrix. When retrain_after_extraction is also set, a second training pass is performed on the reduced model.

Source code in highfis/estimators/_mhtsk.py

def fit(self, x: Any, y: Any, *, x_val: Any | None = None, y_val: Any | None = None) -> Self:
    """Train the MHTSK regressor and optionally extract rules.

    After the base training step, if ``rule_extraction`` is enabled, rules
    are selected via the unsupervised CRCR criterion on the firing-strength
    matrix.  When ``retrain_after_extraction`` is also set, a second
    training pass is performed on the reduced model.
    """
    x_arr, y_arr = check_X_y(x, y)
    super().fit(x, y, x_val=x_val, y_val=y_val)

    if not bool(self.rule_extraction):
        return self

    x_t = self._as_tensor_x(x_arr)
    self.model_.eval()
    with torch.no_grad():
        norm_w = self.model_.forward_antecedents(x_t)

    selected = _extract_mhtsk_rule_indices_unsupervised(norm_w, self.crcr_us)
    self._extracted_rule_indices_ = selected

    input_mfs = self.model_.input_mfs
    self._build_extracted_model(input_mfs, selected)

    if self.retrain_after_extraction:
        y_t = torch.as_tensor(np.asarray(y_arr), dtype=torch.float32)
        x_val_t: torch.Tensor | None = None
        y_val_t: torch.Tensor | None = None
        if x_val is not None and y_val is not None:
            x_v_arr, y_v_arr = check_X_y(x_val, y_val)
            x_val_t = self._as_tensor_x(x_v_arr)
            y_val_t = torch.as_tensor(np.asarray(y_v_arr, dtype=np.float32), dtype=torch.float32)
        self.history_ = self.model_.fit(
            x_t,
            y_t,
            epochs=int(self.epochs),
            learning_rate=float(self.learning_rate),
            batch_size=self.batch_size,
            shuffle=bool(self.shuffle),
            ur_weight=float(self.ur_weight),
            ur_target=self.ur_target,
            verbose=self.verbose,
            x_val=x_val_t,
            y_val=y_val_t,
            patience=self.patience,
            restore_best=self.restore_best,
            weight_decay=float(self.weight_decay),
        )
    return self

`get_mf_params`

Return model membership function metadata after fitting.

Source code in highfis/estimators/_base.py

def get_mf_params(self) -> dict[str, list[dict[str, Any]]]:
    """Return model membership function metadata after fitting."""
    check_is_fitted(self, "model_")
    return self.model_.get_mf_params()

`inspect`

Return a structured summary of fitted model state and rule metadata.

Source code in highfis/estimators/_base.py

def inspect(self) -> dict[str, Any]:
    """Return a structured summary of fitted model state and rule metadata."""
    check_is_fitted(self, "model_")
    return {
        "n_rules": int(self.model_.n_rules),
        "n_inputs": int(self.model_.n_inputs),
        "feature_names": list(self.model_.input_names),
        "rule_base": self.rule_base_,
        "defuzzifier_type": type(self.model_.defuzzifier).__name__,
        "mf_params": self.get_mf_params(),
        "rule_table": self.model_.get_rule_table(),
    }

`load` `classmethod`

Load a persisted estimator created by save.

Source code in highfis/estimators/_base.py

@classmethod
def load(cls, path: str) -> Self:
    """Load a persisted estimator created by save."""
    checkpoint = load_checkpoint(path)
    validate_checkpoint_payload(checkpoint, expected_estimator_class=cls.__name__)

    params: dict[str, Any] = dict(checkpoint["estimator_params"])
    if params.get("input_configs") is not None:
        params["input_configs"] = [InputConfig(**c) for c in params["input_configs"]]
    estimator = cls(**params)
    model_init = checkpoint["model_init"]
    estimator.rule_base_ = model_init["rule_base"]
    estimator.model_ = estimator._build_regressor_model(
        deserialize_input_mfs(model_init["input_mfs_config"]),
        str(model_init["rule_base"]),
    )
    estimator.model_.load_state_dict(checkpoint["model_state_dict"])
    estimator.model_.to(torch.device(str(estimator.device)))

    fitted = checkpoint["fitted_attrs"]
    estimator.n_features_in_ = int(fitted["n_features_in"])
    estimator.feature_names_in_ = np.asarray(fitted["feature_names_in"], dtype=object)
    estimator.history_ = cast(dict[str, Any], checkpoint.get("history", {}))
    return estimator

`predict`

Predict continuous target values for input samples.

Source code in highfis/estimators/_base.py

def predict(self, x: Any) -> np.ndarray:
    """Predict continuous target values for input samples."""
    check_is_fitted(self, "model_")
    x_arr = check_array(x)
    if x_arr.shape[1] != self.n_features_in_:
        raise ValueError(f"expected {self.n_features_in_} features, got {x_arr.shape[1]}")
    preds = cast(Any, self.model_).predict(self._as_tensor_x(x_arr, torch.device(str(self.device))))
    return preds.detach().cpu().numpy()

`rule_activation`

Return normalized rule activations for the provided inputs.

Source code in highfis/estimators/_base.py

def rule_activation(self, X: Any) -> np.ndarray:
    """Return normalized rule activations for the provided inputs."""
    check_is_fitted(self, "model_")
    x_arr = check_array(X)
    if x_arr.shape[1] != self.n_features_in_:
        raise ValueError(f"expected {self.n_features_in_} features, got {x_arr.shape[1]}")

    was_training = self.model_.training
    try:
        self.model_.eval()
        with torch.no_grad():
            norm_w = self.model_.forward_antecedents(self._as_tensor_x(x_arr, torch.device(str(self.device))))
    finally:
        self.model_.train(was_training)

    return _to_numpy(norm_w)

`save`

Persist estimator configuration, model weights and fitted metadata.

Source code in highfis/estimators/_base.py

def save(self, path: str) -> None:
    """Persist estimator configuration, model weights and fitted metadata."""
    checkpoint = self._build_checkpoint_base(
        model_init={
            "input_mfs_config": serialize_input_mfs(self.model_.input_mfs),
            "rule_base": self.rule_base_,
        },
        fitted_attrs={
            "n_features_in": int(self.n_features_in_),
            "feature_names_in": self.feature_names_in_.tolist(),
        },
    )
    save_checkpoint(path, checkpoint)

`TSKClassifier`

Bases: _BaseClassifierEstimator

Vanilla TSK classifier with sum-based rule normalization.

The vanilla Takagi-Sugeno-Kang inference computes rule firing strengths with the product t-norm and normalizes them by their total sum.

References

T. Takagi and M. Sugeno, "Fuzzy identification of systems and its applications to modeling and control," in IEEE Transactions on Systems, Man, and Cybernetics, vol. SMC-15, no. 1, pp. 116-132, Jan.-Feb. 1985, doi: 10.1109/TSMC.1985.6313399.

Example

from highfis import TSKClassifier

clf = TSKClassifier(n_mfs=5, random_state=0)
clf.fit(X_train, y_train)

Initialise a vanilla TSK classifier.

Parameters:

Name	Type	Description	Default
`input_configs`	`list[InputConfig] \| None`	Per-feature :class:`InputConfig` list. Only `name` is used when `mf_init="kmeans"`.	`None`
`n_mfs`	`int`	Number of k-means clusters / grid MFs (default `5`).	`5`
`mf_init`	`str`	`"kmeans"` (default), `"minibatch_kmeans"`, `"fcm"`, or `"grid"`.	`'kmeans'`
`sigma_scale`	`float \| str`	Sigma scale factor. Use `"auto"` (= `sqrt(D)`) for high-dimensional data to mitigate softmax saturation (Cui et al., IJCNN 2021). `1.0` is appropriate for low- to medium-dimensional problems.	`1.0`
`random_state`	`int \| None`	Seed for k-means and weight initialisation.	`None`
`epochs`	`int`	Maximum training epochs (default `10`).	`10`
`learning_rate`	`float`	Adam learning rate (default `0.01`).	`0.01`
`verbose`	`bool \| int`	Print per-epoch progress.	`False`
`rule_base`	`str \| None`	`"coco"` or `"cartesian"`. Defaults to `"coco"` for kmeans and `"cartesian"` for grid.	`None`
`batch_size`	`int \| None`	Mini-batch size (default `512`).	`512`
`shuffle`	`bool`	Reshuffle each epoch.	`True`
`ur_weight`	`float`	Uncertainty regularisation weight.	`0.0`
`ur_target`	`float \| None`	Uncertainty regularisation target.	`None`
`consequent_batch_norm`	`bool`	Batch normalisation on consequent layers.	`False`
`pfrb_max_rules`	`int \| None`	Maximum point-based FRB rules (unused by TSK).	`None`
`patience`	`int \| None`	Early-stopping patience (default `20`). Set to `None` to disable early stopping.	`20`
`restore_best`	`bool`	If `True` (default), restore the best validation model weights after training.	`True`
`weight_decay`	`float`	L2 weight decay for consequent parameters.	`1e-08`

Source code in highfis/estimators/_htsk.py

def __init__(
    self,
    *,
    input_configs: list[InputConfig] | None = None,
    n_mfs: int = 5,
    mf_init: str = "kmeans",
    sigma_scale: float | str = 1.0,
    random_state: int | None = None,
    epochs: int = 10,
    learning_rate: float = 1e-2,
    verbose: bool | int = False,
    rule_base: str | None = None,
    batch_size: int | None = 512,
    shuffle: bool = True,
    ur_weight: float = 0.0,
    ur_target: float | None = None,
    consequent_batch_norm: bool = False,
    pfrb_max_rules: int | None = None,
    patience: int | None = 20,
    restore_best: bool = True,
    weight_decay: float = 1e-8,
) -> None:
    """Initialise a vanilla TSK classifier.

    Args:
        input_configs: Per-feature :class:`InputConfig` list. Only
            ``name`` is used when ``mf_init="kmeans"``.
        n_mfs: Number of k-means clusters / grid MFs (default ``5``).
        mf_init: ``"kmeans"`` (default), ``"minibatch_kmeans"``, ``"fcm"``, or ``"grid"``.
        sigma_scale: Sigma scale factor. Use ``"auto"`` (= ``sqrt(D)``)
            for high-dimensional data to mitigate softmax saturation
            (Cui et al., IJCNN 2021). ``1.0`` is appropriate for low-
            to medium-dimensional problems.
        random_state: Seed for k-means and weight initialisation.
        epochs: Maximum training epochs (default ``10``).
        learning_rate: Adam learning rate (default ``0.01``).
        verbose: Print per-epoch progress.
        rule_base: ``"coco"`` or ``"cartesian"``. Defaults to
            ``"coco"`` for kmeans and ``"cartesian"`` for grid.
        batch_size: Mini-batch size (default ``512``).
        shuffle: Reshuffle each epoch.
        ur_weight: Uncertainty regularisation weight.
        ur_target: Uncertainty regularisation target.
        consequent_batch_norm: Batch normalisation on consequent layers.
        pfrb_max_rules: Maximum point-based FRB rules (unused by TSK).
        patience: Early-stopping patience (default ``20``). Set to ``None`` to disable early stopping.
        restore_best: If ``True`` (default), restore the best validation
            model weights after training.
        weight_decay: L2 weight decay for consequent parameters.
    """
    super().__init__(
        input_configs=input_configs,
        n_mfs=n_mfs,
        mf_init=mf_init,
        sigma_scale=sigma_scale,
        random_state=random_state,
        epochs=epochs,
        learning_rate=learning_rate,
        verbose=verbose,
        rule_base=rule_base,
        batch_size=batch_size,
        shuffle=shuffle,
        ur_weight=ur_weight,
        ur_target=ur_target,
        consequent_batch_norm=consequent_batch_norm,
        pfrb_max_rules=pfrb_max_rules,
        patience=patience,
        restore_best=restore_best,
        weight_decay=weight_decay,
    )

`evaluate`

Compute classification evaluation metrics for the provided dataset.

Source code in highfis/estimators/_base.py

def evaluate(
    self,
    X: Any,
    y: Any,
    metrics: list[str] | None = None,
    sample_weight: Any | None = None,
) -> dict[str, float]:
    """Compute classification evaluation metrics for the provided dataset."""
    y_true = np.asarray(y)
    y_pred = self.predict(X)
    return compute_metrics(
        task="classification",
        y_true=y_true,
        y_pred=y_pred,
        sample_weight=sample_weight,
        metrics=metrics,
    )

`feature_importance`

Compute a normalized feature importance vector from consequent weights.

Source code in highfis/estimators/_base.py

def feature_importance(self) -> np.ndarray | None:
    """Compute a normalized feature importance vector from consequent weights."""
    check_is_fitted(self, "model_")
    weights = self.model_.get_consequent_weights()
    if weights is None:
        return None

    consequent_layer = self.model_.consequent_layer
    if hasattr(consequent_layer, "rule_feature_mask"):
        rule_feature_mask = cast(Tensor, consequent_layer.rule_feature_mask)
        weights = weights * rule_feature_mask.unsqueeze(1) if weights.ndim == 3 else weights * rule_feature_mask

    abs_weights = weights.abs()
    if abs_weights.ndim == 3:
        importance = abs_weights.mean(dim=(0, 1))
    elif abs_weights.ndim == 2:
        importance = abs_weights.mean(dim=0)
    else:
        raise ValueError("unsupported consequent weight shape for feature importance")

    return _normalize_importance(importance)

`fit`

Train the TSK classifier on labeled samples.

Validation data should be supplied using x_val and y_val when available.

Source code in highfis/estimators/_base.py

def fit(
    self,
    x: Any,
    y: Any,
    *,
    x_val: Any | None = None,
    y_val: Any | None = None,
) -> Self:
    """Train the TSK classifier on labeled samples.

    Validation data should be supplied using ``x_val`` and ``y_val``
    when available.
    """
    x_arr, y_arr = check_X_y(x, y)

    if self.random_state is not None:
        torch.manual_seed(int(self.random_state))

    le = LabelEncoder()
    y_idx = le.fit_transform(np.asarray(y_arr))

    input_mfs, feature_names, effective_rule_base = self._build_input_mfs(x_arr)

    self.n_features_in_ = x_arr.shape[1]
    self.feature_names_in_ = np.asarray(feature_names, dtype=object)
    self.classes_ = le.classes_
    self._label_encoder_ = le

    _device = torch.device(str(self.device))
    self.model_ = self._build_model(input_mfs, len(self.classes_), effective_rule_base).to(_device)

    y_t = torch.as_tensor(y_idx, dtype=torch.long, device=_device)

    # Prepare validation tensors if provided via fit.
    x_val_t: torch.Tensor | None = None
    y_val_t: torch.Tensor | None = None
    if (x_val is None) ^ (y_val is None):
        raise ValueError("x_val and y_val must be provided together")
    if x_val is not None and y_val is not None:
        x_v_arr, y_v_arr = check_X_y(x_val, y_val)
        x_val_t = self._as_tensor_x(x_v_arr, _device)
        y_val_idx = le.transform(np.asarray(y_v_arr))
        y_val_t = torch.as_tensor(y_val_idx, dtype=torch.long, device=_device)

    self.history_ = self.model_.fit(
        self._as_tensor_x(x_arr, _device),
        y_t,
        epochs=int(self.epochs),
        learning_rate=float(self.learning_rate),
        batch_size=self.batch_size,
        shuffle=bool(self.shuffle),
        ur_weight=float(self.ur_weight),
        ur_target=self.ur_target,
        verbose=self.verbose,
        x_val=x_val_t,
        y_val=y_val_t,
        patience=self.patience,
        restore_best=self.restore_best,
        weight_decay=float(self.weight_decay),
    )
    self.rule_base_ = effective_rule_base
    return self

`get_mf_params`

Return model membership function metadata after fitting.

Source code in highfis/estimators/_base.py

def get_mf_params(self) -> dict[str, list[dict[str, Any]]]:
    """Return model membership function metadata after fitting."""
    check_is_fitted(self, "model_")
    return self.model_.get_mf_params()

`inspect`

Return a structured summary of fitted model state and rule metadata.

Source code in highfis/estimators/_base.py

def inspect(self) -> dict[str, Any]:
    """Return a structured summary of fitted model state and rule metadata."""
    check_is_fitted(self, "model_")
    return {
        "n_rules": int(self.model_.n_rules),
        "n_inputs": int(self.model_.n_inputs),
        "feature_names": list(self.model_.input_names),
        "rule_base": self.rule_base_,
        "defuzzifier_type": type(self.model_.defuzzifier).__name__,
        "mf_params": self.get_mf_params(),
        "rule_table": self.model_.get_rule_table(),
    }

`load` `classmethod`

Load a persisted estimator created by save.

Source code in highfis/estimators/_base.py

@classmethod
def load(cls, path: str) -> Self:
    """Load a persisted estimator created by save."""
    checkpoint = load_checkpoint(path)
    validate_checkpoint_payload(checkpoint, expected_estimator_class=cls.__name__)

    params: dict[str, Any] = dict(checkpoint["estimator_params"])
    if params.get("input_configs") is not None:
        params["input_configs"] = [InputConfig(**c) for c in params["input_configs"]]
    estimator = cls(**params)
    model_init = checkpoint["model_init"]
    estimator.rule_base_ = model_init["rule_base"]
    estimator.model_ = estimator._build_model(
        deserialize_input_mfs(model_init["input_mfs_config"]),
        int(model_init["n_classes"]),
        str(model_init["rule_base"]),
    )
    estimator.model_.load_state_dict(checkpoint["model_state_dict"])
    estimator.model_.to(torch.device(str(estimator.device)))

    fitted = checkpoint["fitted_attrs"]
    estimator.n_features_in_ = int(fitted["n_features_in"])
    estimator.feature_names_in_ = np.asarray(fitted["feature_names_in"], dtype=object)
    estimator.classes_ = np.asarray(fitted["classes"], dtype=object)
    label_encoder = LabelEncoder()
    label_encoder.classes_ = estimator.classes_
    estimator._label_encoder_ = label_encoder
    estimator.history_ = cast(dict[str, Any], checkpoint.get("history", {}))
    return estimator

`predict`

Predict class labels for input samples.

Source code in highfis/estimators/_base.py

def predict(self, x: Any) -> np.ndarray:
    """Predict class labels for input samples."""
    proba = self.predict_proba(x)
    y_idx = np.argmax(proba, axis=1)
    return np.asarray(self._label_encoder_.inverse_transform(y_idx))

`predict_proba`

Predict class probabilities for input samples.

Source code in highfis/estimators/_base.py

def predict_proba(self, x: Any) -> np.ndarray:
    """Predict class probabilities for input samples."""
    check_is_fitted(self, "model_")
    x_arr = check_array(x)
    if x_arr.shape[1] != self.n_features_in_:
        raise ValueError(f"expected {self.n_features_in_} features, got {x_arr.shape[1]}")
    probs = cast(Any, self.model_).predict_proba(self._as_tensor_x(x_arr, torch.device(str(self.device))))
    return probs.detach().cpu().numpy()

`rule_activation`

Return normalized rule activations for the provided inputs.

Source code in highfis/estimators/_base.py

def rule_activation(self, X: Any) -> np.ndarray:
    """Return normalized rule activations for the provided inputs."""
    check_is_fitted(self, "model_")
    x_arr = check_array(X)
    if x_arr.shape[1] != self.n_features_in_:
        raise ValueError(f"expected {self.n_features_in_} features, got {x_arr.shape[1]}")

    was_training = self.model_.training
    try:
        self.model_.eval()
        with torch.no_grad():
            norm_w = self.model_.forward_antecedents(self._as_tensor_x(x_arr, torch.device(str(self.device))))
    finally:
        self.model_.train(was_training)

    return _to_numpy(norm_w)

`save`

Persist estimator configuration, model weights and fitted metadata.

Source code in highfis/estimators/_base.py

def save(self, path: str) -> None:
    """Persist estimator configuration, model weights and fitted metadata."""
    checkpoint = self._build_checkpoint_base(
        model_init={
            "input_mfs_config": serialize_input_mfs(self.model_.input_mfs),
            "n_classes": len(self.classes_),
            "rule_base": self.rule_base_,
        },
        fitted_attrs={
            "n_features_in": int(self.n_features_in_),
            "feature_names_in": self.feature_names_in_.tolist(),
            "classes": self.classes_.tolist(),
        },
    )
    save_checkpoint(path, checkpoint)

`score`

Return classification accuracy on the provided dataset.

Source code in highfis/estimators/_base.py

def score(self, X: Any, y: Any, sample_weight: Any = None) -> float:
    """Return classification accuracy on the provided dataset."""
    y_true = np.asarray(y)
    y_pred = self.predict(X)
    return float(accuracy_score(y_true, y_pred, sample_weight=sample_weight))

`TSKRegressor`

Bases: _BaseRegressorEstimator

Vanilla TSK regressor with sum-based rule normalization.

The vanilla Takagi-Sugeno-Kang inference computes rule firing strengths with the product t-norm and normalizes them by their total sum.

References

T. Takagi and M. Sugeno, "Fuzzy identification of systems and its applications to modeling and control," in IEEE Transactions on Systems, Man, and Cybernetics, vol. SMC-15, no. 1, pp. 116-132, Jan.-Feb. 1985, doi: 10.1109/TSMC.1985.6313399.

Example

from highfis import TSKRegressor

reg = TSKRegressor(n_mfs=30, random_state=0)
reg.fit(X_train, y_train)

Initialise a vanilla TSK regressor.

Parameters:

Name	Type	Description	Default
`input_configs`	`list[InputConfig] \| None`	Per-feature :class:`InputConfig` list. Only `name` is used when `mf_init="kmeans"`.	`None`
`n_mfs`	`int`	Number of k-means clusters / grid MFs (default `5`).	`5`
`mf_init`	`str`	`"kmeans"` (default), `"minibatch_kmeans"`, `"fcm"`, or `"grid"`.	`'kmeans'`
`sigma_scale`	`float \| str`	Sigma scale factor. Use `"auto"` (= `sqrt(D)`) to mitigate softmax saturation on high-dimensional data. `1.0` is appropriate for low-to-medium-dimensional problems.	`1.0`
`random_state`	`int \| None`	Seed for k-means and weight initialisation.	`None`
`epochs`	`int`	Maximum training epochs (default `10`).	`10`
`learning_rate`	`float`	Adam learning rate (default `0.01`).	`0.01`
`verbose`	`bool \| int`	Print per-epoch progress.	`False`
`rule_base`	`str \| None`	`"coco"` or `"cartesian"`. Defaults to `"coco"` for kmeans and `"cartesian"` for grid.	`None`
`batch_size`	`int \| None`	Mini-batch size (default `512`).	`512`
`shuffle`	`bool`	Reshuffle each epoch.	`True`
`ur_weight`	`float`	Uncertainty regularisation weight.	`0.0`
`ur_target`	`float \| None`	Uncertainty regularisation target.	`None`
`consequent_batch_norm`	`bool`	Batch normalisation on consequent layers.	`False`
`patience`	`int \| None`	Early-stopping patience (default `20`). Set to `None` to disable early stopping.	`20`
`restore_best`	`bool`	If `True` (default), restore the best validation model weights after training.	`True`
`weight_decay`	`float`	L2 weight decay for consequent parameters.	`1e-08`

Source code in highfis/estimators/_htsk.py

def __init__(
    self,
    *,
    input_configs: list[InputConfig] | None = None,
    n_mfs: int = 5,
    mf_init: str = "kmeans",
    sigma_scale: float | str = 1.0,
    random_state: int | None = None,
    epochs: int = 10,
    learning_rate: float = 1e-2,
    verbose: bool | int = False,
    rule_base: str | None = None,
    batch_size: int | None = 512,
    shuffle: bool = True,
    ur_weight: float = 0.0,
    ur_target: float | None = None,
    consequent_batch_norm: bool = False,
    patience: int | None = 20,
    restore_best: bool = True,
    weight_decay: float = 1e-8,
) -> None:
    """Initialise a vanilla TSK regressor.

    Args:
        input_configs: Per-feature :class:`InputConfig` list. Only
            ``name`` is used when ``mf_init="kmeans"``.
        n_mfs: Number of k-means clusters / grid MFs (default ``5``).
        mf_init: ``"kmeans"`` (default), ``"minibatch_kmeans"``, ``"fcm"``, or ``"grid"``.
        sigma_scale: Sigma scale factor. Use ``"auto"`` (= ``sqrt(D)``)
            to mitigate softmax saturation on high-dimensional data.
            ``1.0`` is appropriate for low-to-medium-dimensional problems.
        random_state: Seed for k-means and weight initialisation.
        epochs: Maximum training epochs (default ``10``).
        learning_rate: Adam learning rate (default ``0.01``).
        verbose: Print per-epoch progress.
        rule_base: ``"coco"`` or ``"cartesian"``. Defaults to
            ``"coco"`` for kmeans and ``"cartesian"`` for grid.
        batch_size: Mini-batch size (default ``512``).
        shuffle: Reshuffle each epoch.
        ur_weight: Uncertainty regularisation weight.
        ur_target: Uncertainty regularisation target.
        consequent_batch_norm: Batch normalisation on consequent layers.
        patience: Early-stopping patience (default ``20``). Set to ``None`` to disable early stopping.
        restore_best: If ``True`` (default), restore the best validation
            model weights after training.
        weight_decay: L2 weight decay for consequent parameters.
    """
    super().__init__(
        input_configs=input_configs,
        n_mfs=n_mfs,
        mf_init=mf_init,
        sigma_scale=sigma_scale,
        random_state=random_state,
        epochs=epochs,
        learning_rate=learning_rate,
        verbose=verbose,
        rule_base=rule_base,
        batch_size=batch_size,
        shuffle=shuffle,
        ur_weight=ur_weight,
        ur_target=ur_target,
        consequent_batch_norm=consequent_batch_norm,
        patience=patience,
        restore_best=restore_best,
        weight_decay=weight_decay,
    )

`evaluate`

Compute regression evaluation metrics for the provided dataset.

Source code in highfis/estimators/_base.py

def evaluate(
    self,
    X: Any,
    y: Any,
    metrics: list[str] | None = None,
    sample_weight: Any | None = None,
) -> dict[str, float]:
    """Compute regression evaluation metrics for the provided dataset."""
    y_true = np.asarray(y)
    y_pred = self.predict(X)
    return compute_metrics(
        task="regression",
        y_true=y_true,
        y_pred=y_pred,
        sample_weight=sample_weight,
        metrics=metrics,
    )

`feature_importance`

Compute a normalized feature importance vector from consequent weights.

Source code in highfis/estimators/_base.py

def feature_importance(self) -> np.ndarray | None:
    """Compute a normalized feature importance vector from consequent weights."""
    check_is_fitted(self, "model_")
    weights = self.model_.get_consequent_weights()
    if weights is None:
        return None

    consequent_layer = self.model_.consequent_layer
    if hasattr(consequent_layer, "rule_feature_mask"):
        rule_feature_mask = cast(Tensor, consequent_layer.rule_feature_mask)
        weights = weights * rule_feature_mask.unsqueeze(1) if weights.ndim == 3 else weights * rule_feature_mask

    abs_weights = weights.abs()
    if abs_weights.ndim == 3:
        importance = abs_weights.mean(dim=(0, 1))
    elif abs_weights.ndim == 2:
        importance = abs_weights.mean(dim=0)
    else:
        raise ValueError("unsupported consequent weight shape for feature importance")

    return _normalize_importance(importance)

`fit`

Train the TSK regressor on labeled samples.

Validation data should be supplied using x_val and y_val when available.

Source code in highfis/estimators/_base.py

def fit(
    self,
    x: Any,
    y: Any,
    *,
    x_val: Any | None = None,
    y_val: Any | None = None,
) -> Self:
    """Train the TSK regressor on labeled samples.

    Validation data should be supplied using ``x_val`` and ``y_val``
    when available.
    """
    x_arr, y_arr = check_X_y(x, y)

    if self.random_state is not None:
        torch.manual_seed(int(self.random_state))

    input_mfs, feature_names, effective_rule_base = self._build_input_mfs(x_arr)

    self.n_features_in_ = x_arr.shape[1]
    self.feature_names_in_ = np.asarray(feature_names, dtype=object)

    _device = torch.device(str(self.device))
    self.model_ = self._build_regressor_model(input_mfs, effective_rule_base).to(_device)

    y_t = torch.as_tensor(np.asarray(y_arr, dtype=np.float32), dtype=torch.float32, device=_device)

    # Prepare validation tensors if provided via fit.
    x_val_t: torch.Tensor | None = None
    y_val_t: torch.Tensor | None = None
    if (x_val is None) ^ (y_val is None):
        raise ValueError("x_val and y_val must be provided together")
    if x_val is not None and y_val is not None:
        x_v_arr, y_v_arr = check_X_y(x_val, y_val)
        x_val_t = self._as_tensor_x(x_v_arr, _device)
        y_val_t = torch.as_tensor(np.asarray(y_v_arr, dtype=np.float32), dtype=torch.float32, device=_device)

    self.history_ = self.model_.fit(
        self._as_tensor_x(x_arr, _device),
        y_t,
        epochs=int(self.epochs),
        learning_rate=float(self.learning_rate),
        batch_size=self.batch_size,
        shuffle=bool(self.shuffle),
        ur_weight=float(self.ur_weight),
        ur_target=self.ur_target,
        verbose=self.verbose,
        x_val=x_val_t,
        y_val=y_val_t,
        patience=self.patience,
        restore_best=self.restore_best,
        weight_decay=float(self.weight_decay),
    )
    self.rule_base_ = effective_rule_base
    return self

`get_mf_params`

Return model membership function metadata after fitting.

Source code in highfis/estimators/_base.py

def get_mf_params(self) -> dict[str, list[dict[str, Any]]]:
    """Return model membership function metadata after fitting."""
    check_is_fitted(self, "model_")
    return self.model_.get_mf_params()

`inspect`

Return a structured summary of fitted model state and rule metadata.

Source code in highfis/estimators/_base.py

def inspect(self) -> dict[str, Any]:
    """Return a structured summary of fitted model state and rule metadata."""
    check_is_fitted(self, "model_")
    return {
        "n_rules": int(self.model_.n_rules),
        "n_inputs": int(self.model_.n_inputs),
        "feature_names": list(self.model_.input_names),
        "rule_base": self.rule_base_,
        "defuzzifier_type": type(self.model_.defuzzifier).__name__,
        "mf_params": self.get_mf_params(),
        "rule_table": self.model_.get_rule_table(),
    }

`load` `classmethod`

Load a persisted estimator created by save.

Source code in highfis/estimators/_base.py

@classmethod
def load(cls, path: str) -> Self:
    """Load a persisted estimator created by save."""
    checkpoint = load_checkpoint(path)
    validate_checkpoint_payload(checkpoint, expected_estimator_class=cls.__name__)

    params: dict[str, Any] = dict(checkpoint["estimator_params"])
    if params.get("input_configs") is not None:
        params["input_configs"] = [InputConfig(**c) for c in params["input_configs"]]
    estimator = cls(**params)
    model_init = checkpoint["model_init"]
    estimator.rule_base_ = model_init["rule_base"]
    estimator.model_ = estimator._build_regressor_model(
        deserialize_input_mfs(model_init["input_mfs_config"]),
        str(model_init["rule_base"]),
    )
    estimator.model_.load_state_dict(checkpoint["model_state_dict"])
    estimator.model_.to(torch.device(str(estimator.device)))

    fitted = checkpoint["fitted_attrs"]
    estimator.n_features_in_ = int(fitted["n_features_in"])
    estimator.feature_names_in_ = np.asarray(fitted["feature_names_in"], dtype=object)
    estimator.history_ = cast(dict[str, Any], checkpoint.get("history", {}))
    return estimator

`predict`

Predict continuous target values for input samples.

Source code in highfis/estimators/_base.py

def predict(self, x: Any) -> np.ndarray:
    """Predict continuous target values for input samples."""
    check_is_fitted(self, "model_")
    x_arr = check_array(x)
    if x_arr.shape[1] != self.n_features_in_:
        raise ValueError(f"expected {self.n_features_in_} features, got {x_arr.shape[1]}")
    preds = cast(Any, self.model_).predict(self._as_tensor_x(x_arr, torch.device(str(self.device))))
    return preds.detach().cpu().numpy()

`rule_activation`

Return normalized rule activations for the provided inputs.

Source code in highfis/estimators/_base.py

def rule_activation(self, X: Any) -> np.ndarray:
    """Return normalized rule activations for the provided inputs."""
    check_is_fitted(self, "model_")
    x_arr = check_array(X)
    if x_arr.shape[1] != self.n_features_in_:
        raise ValueError(f"expected {self.n_features_in_} features, got {x_arr.shape[1]}")

    was_training = self.model_.training
    try:
        self.model_.eval()
        with torch.no_grad():
            norm_w = self.model_.forward_antecedents(self._as_tensor_x(x_arr, torch.device(str(self.device))))
    finally:
        self.model_.train(was_training)

    return _to_numpy(norm_w)

`save`

Persist estimator configuration, model weights and fitted metadata.

Source code in highfis/estimators/_base.py

def save(self, path: str) -> None:
    """Persist estimator configuration, model weights and fitted metadata."""
    checkpoint = self._build_checkpoint_base(
        model_init={
            "input_mfs_config": serialize_input_mfs(self.model_.input_mfs),
            "rule_base": self.rule_base_,
        },
        fitted_attrs={
            "n_features_in": int(self.n_features_in_),
            "feature_names_in": self.feature_names_in_.tolist(),
        },
    )
    save_checkpoint(path, checkpoint)

`feature_coverage_rate`

Compute the feature coverage rate (FCR) for MHTSK heads.

FCR is the expected proportion of original features that are selected at least once across n_heads random subsets of size head_size.

Source code in highfis/estimators/_base.py

def feature_coverage_rate(n_features: int, head_size: int, n_heads: int) -> float:
    """Compute the feature coverage rate (FCR) for MHTSK heads.

    FCR is the expected proportion of original features that are selected at
    least once across ``n_heads`` random subsets of size ``head_size``.
    """
    if n_features <= 0:
        raise ValueError("n_features must be > 0")
    if head_size <= 0 or head_size > n_features:
        raise ValueError("head_size must be between 1 and n_features")
    if n_heads < 0:
        raise ValueError("n_heads must be >= 0")

    return 1.0 - (1.0 - float(head_size) / float(n_features)) ** float(n_heads)

Estimators

ADATSKClassifier

evaluate

feature_importance

fit

get_mf_params

inspect

load classmethod

predict

predict_proba

rule_activation

save

score

ADATSKRegressor

evaluate

feature_importance

fit

get_mf_params

inspect

load classmethod

predict

rule_activation

save

ADMTSKClassifier

evaluate

feature_importance

fit

get_mf_params

inspect

load classmethod

predict

predict_proba

rule_activation

save

score

ADMTSKRegressor

evaluate

feature_importance

fit

get_mf_params

inspect

load classmethod

predict

rule_activation

save

ADPTSKClassifier

evaluate

feature_importance

fit

get_mf_params

inspect

load classmethod

predict

predict_proba

rule_activation

save

score

ADPTSKRegressor

evaluate

feature_importance

fit

get_mf_params

inspect

load classmethod

predict

rule_activation

save

AYATSKClassifier

evaluate

feature_importance

fit

get_mf_params

inspect

load classmethod

predict

predict_proba

rule_activation

save

score

AYATSKRegressor

`ADATSKClassifier`

`evaluate`

`feature_importance`

`fit`

`get_mf_params`

`inspect`

`load` `classmethod`

`predict`

`predict_proba`

`rule_activation`

`save`

`score`

`ADATSKRegressor`

`evaluate`

`feature_importance`

`fit`

`get_mf_params`

`inspect`

`load` `classmethod`

`predict`

`rule_activation`

`save`

`ADMTSKClassifier`

`evaluate`

`feature_importance`

`fit`

`get_mf_params`

`inspect`

`load` `classmethod`

`predict`

`predict_proba`

`rule_activation`

`save`

`score`

`ADMTSKRegressor`

`evaluate`

`feature_importance`

`fit`

`get_mf_params`

`inspect`

`load` `classmethod`

`predict`

`rule_activation`

`save`

`ADPTSKClassifier`

`evaluate`

`feature_importance`

`fit`

`get_mf_params`

`inspect`

`load` `classmethod`

`predict`

`predict_proba`

`rule_activation`

`save`

`score`

`ADPTSKRegressor`

`evaluate`

`feature_importance`

`fit`

`get_mf_params`

`inspect`

`load` `classmethod`

`predict`

`rule_activation`

`save`

`AYATSKClassifier`

`evaluate`

`feature_importance`

`fit`

`get_mf_params`

`inspect`

`load` `classmethod`

`predict`

`predict_proba`

`rule_activation`

`save`

`score`

`AYATSKRegressor`

`evaluate`