📊 Metrics API Reference

Welcome to the KerasFactory Metrics documentation! All metrics are designed to work exclusively with Keras 3 and provide specialized statistical measurements for model analysis and anomaly detection tasks.

What You'll Find Here

Each metric includes detailed documentation with: - ✨ Complete parameter descriptions with types and defaults - 🎯 Usage examples showing real-world applications - ⚡ Best practices and performance considerations - 🎨 When to use guidance for each metric - 🔧 Implementation notes for developers

Ready-to-Use Metrics

These metrics provide specialized implementations for statistical analysis that you can use out-of-the-box or integrate into your models.

Keras 3 Compatible

All metrics are built on top of Keras base classes and are fully compatible with Keras 3.

📊 Statistical Metrics

📈 Median

Calculates the median of predicted values, providing a robust measure of central tendency less sensitive to outliers.

kerasfactory.metrics.Median

Median(name: str = 'median', **kwargs: Any)

A custom Keras metric that calculates the median of the predicted values.

This class is a custom implementation of a Keras metric, which calculates the median of the predicted values during model training. The median is a robust measure of central tendency that is less sensitive to outliers compared to the mean, making it particularly useful for anomaly detection tasks.

Attributes:

Name	Type	Description
values	Variable	A trainable weight that stores the calculated median.

Example

import keras
from kerasfactory.metrics import Median

# Create metric
median_metric = Median(name="prediction_median")

# Update with predictions
predictions = keras.ops.random.normal((100, 10))
median_metric.update_state(predictions)

# Get result
median_value = median_metric.result()
print(f"Median: {median_value}")

Initializes the Median metric with a given name.

Parameters:

Name	Type	Description	Default
name	str	The name of the metric. Defaults to 'median'.	'median'
**kwargs	Any	Additional keyword arguments passed to the parent class.	{}

Source code in kerasfactory/metrics/median.py

def __init__(self, name: str = "median", **kwargs: Any) -> None:
    """Initializes the Median metric with a given name.

    Args:
        name (str, optional): The name of the metric. Defaults to 'median'.
        **kwargs: Additional keyword arguments passed to the parent class.
    """
    super().__init__(name=name, **kwargs)
    self.values = self.add_weight(name="values", initializer="zeros")

    logger.debug(f"Initialized Median metric with name: {name}")

Functions

update_state

update_state(y_pred: keras.KerasTensor) -> None

Updates the state of the metric with the median of the predicted values.

Parameters:

Name	Type	Description	Default
y_pred	KerasTensor	The predicted values.	required

Source code in kerasfactory/metrics/median.py

def update_state(self, y_pred: keras.KerasTensor) -> None:
    """Updates the state of the metric with the median of the predicted values.

    Args:
        y_pred (KerasTensor): The predicted values.
    """
    # Calculate median using Keras operations
    sorted_values = ops.sort(y_pred, axis=0)
    n = ops.shape(sorted_values)[0]
    mid = n // 2

    if n % 2 == 0:
        median = (sorted_values[mid - 1] + sorted_values[mid]) / 2
    else:
        median = sorted_values[mid]

    # Ensure median is a scalar
    median = ops.cast(median, dtype="float32")
    if median.shape != ():
        median = ops.mean(median)  # Take mean if it's not a scalar

    self.values.assign(median)

result

result() -> keras.KerasTensor

Returns the current state of the metric, i.e., the current median.

Returns:

Name	Type	Description
KerasTensor	KerasTensor	The current median.

Source code in kerasfactory/metrics/median.py

def result(self) -> keras.KerasTensor:
    """Returns the current state of the metric, i.e., the current median.

    Returns:
        KerasTensor: The current median.
    """
    return self.values

from_config classmethod

from_config(config: dict[str, Any]) -> Median

Creates a new instance of the metric from its config.

Parameters:

Name	Type	Description	Default
config	dict	A dictionary containing the configuration of the metric.	required

Returns:

Name	Type	Description
Median	Median	A new instance of the metric.

Source code in kerasfactory/metrics/median.py

@classmethod
def from_config(cls, config: dict[str, Any]) -> "Median":
    """Creates a new instance of the metric from its config.

    Args:
        config (dict): A dictionary containing the configuration of the metric.

    Returns:
        Median: A new instance of the metric.
    """
    return cls(**config)

📉 StandardDeviation

Calculates the standard deviation of predicted values, useful for tracking prediction variability and uncertainty.

kerasfactory.metrics.StandardDeviation

StandardDeviation(
    name: str = "standard_deviation", **kwargs: Any
)

A custom Keras metric that calculates the standard deviation of the predicted values.

This class is a custom implementation of a Keras metric, which calculates the standard deviation of the predicted values during model training. It's particularly useful for anomaly detection tasks where you need to track the variability of model predictions.

Attributes:

Name	Type	Description
values	Variable	A trainable weight that stores the calculated standard deviation.

Example

import keras
from kerasfactory.metrics import StandardDeviation

# Create metric
std_metric = StandardDeviation(name="prediction_std")

# Update with predictions
predictions = keras.ops.random.normal((100, 10))
std_metric.update_state(predictions)

# Get result
std_value = std_metric.result()
print(f"Standard deviation: {std_value}")

Initializes the StandardDeviation metric with a given name.

Parameters:

Name	Type	Description	Default
name	str	The name of the metric. Defaults to 'standard_deviation'.	'standard_deviation'
**kwargs	Any	Additional keyword arguments passed to the parent class.	{}

Source code in kerasfactory/metrics/standard_deviation.py

def __init__(self, name: str = "standard_deviation", **kwargs: Any) -> None:
    """Initializes the StandardDeviation metric with a given name.

    Args:
        name (str, optional): The name of the metric. Defaults to 'standard_deviation'.
        **kwargs: Additional keyword arguments passed to the parent class.
    """
    super().__init__(name=name, **kwargs)
    self.values = self.add_weight(name="values", initializer="zeros")

    logger.debug(f"Initialized StandardDeviation metric with name: {name}")

Functions

update_state

update_state(y_pred: keras.KerasTensor) -> None

Updates the state of the metric with the standard deviation of the predicted values.

Parameters:

Name	Type	Description	Default
y_pred	KerasTensor	The predicted values.	required

Source code in kerasfactory/metrics/standard_deviation.py

def update_state(self, y_pred: keras.KerasTensor) -> None:
    """Updates the state of the metric with the standard deviation of the predicted values.

    Args:
        y_pred (KerasTensor): The predicted values.
    """
    self.values.assign(ops.cast(ops.std(y_pred), dtype="float32"))

result

result() -> keras.KerasTensor

Returns the current state of the metric, i.e., the current standard deviation.

Returns:

Name	Type	Description
KerasTensor	KerasTensor	The current standard deviation.

Source code in kerasfactory/metrics/standard_deviation.py

def result(self) -> keras.KerasTensor:
    """Returns the current state of the metric, i.e., the current standard deviation.

    Returns:
        KerasTensor: The current standard deviation.
    """
    return self.values

from_config classmethod

from_config(config: dict[str, Any]) -> StandardDeviation

Creates a new instance of the metric from its config.

Parameters:

Name	Type	Description	Default
config	dict	A dictionary containing the configuration of the metric.	required

Returns:

Name	Type	Description
StandardDeviation	StandardDeviation	A new instance of the metric.

Source code in kerasfactory/metrics/standard_deviation.py

@classmethod
def from_config(cls, config: dict[str, Any]) -> "StandardDeviation":
    """Creates a new instance of the metric from its config.

    Args:
        config (dict): A dictionary containing the configuration of the metric.

    Returns:
        StandardDeviation: A new instance of the metric.
    """
    return cls(**config)