braintools.metric module#

Metrics and Loss Functions for Neural Networks.

This module provides loss functions and metrics for training neural networks: classification, regression, ranking, pairwise similarity and label smoothing.

The neural-activity measures that used to live here (spike-train metrics, LFP analysis and correlation/synchrony measures) moved to braintools.analysis in 0.4; see “Moved to braintools.analysis” below.

Key Features:

  • Classification Losses: Binary and multi-class cross-entropy, hinge loss, focal loss

  • Regression Losses: MSE, MAE, Huber loss, cosine similarity

  • Ranking Losses: Softmax ranking loss for learning to rank

  • Pairwise Metrics: Cosine similarity for pairwise comparisons

Quick Start - Classification:

import jax.numpy as jnp
from braintools.metric import softmax_cross_entropy, sigmoid_focal_loss

# Multi-class classification
logits = jnp.array([[2.0, 1.0, 0.1], [0.5, 2.5, 0.3]])
labels = jnp.array([[1.0, 0.0, 0.0], [0.0, 1.0, 0.0]])
loss = softmax_cross_entropy(logits, labels)

# Binary classification with focal loss
predictions = jnp.array([0.9, 0.1, 0.7])
targets = jnp.array([1.0, 0.0, 1.0])
focal_loss = sigmoid_focal_loss(predictions, targets)

Quick Start - Regression:

import jax.numpy as jnp
from braintools.metric import squared_error, huber_loss

predictions = jnp.array([1.5, 2.3, 3.1])
targets = jnp.array([1.0, 2.0, 3.0])

# Mean squared error
mse = squared_error(predictions, targets)

# Huber loss (robust to outliers)
huber = huber_loss(predictions, targets, delta=1.0)

Classification Losses:

import jax.numpy as jnp
from braintools.metric import (
    sigmoid_binary_cross_entropy,
    softmax_cross_entropy_with_integer_labels,
    hinge_loss,
    multiclass_hinge_loss,
    kl_divergence,
    sigmoid_focal_loss
)

# Binary cross-entropy
logits = jnp.array([2.0, -1.0, 0.5])
labels = jnp.array([1.0, 0.0, 1.0])
bce = sigmoid_binary_cross_entropy(logits, labels)

# Multi-class with integer labels
logits = jnp.array([[2.0, 1.0, 0.1], [0.5, 2.5, 0.3]])
labels = jnp.array([0, 1])  # Class indices
ce = softmax_cross_entropy_with_integer_labels(logits, labels)

# Hinge loss for SVM-style classification
predictions = jnp.array([0.9, -0.5, 0.3])
targets = jnp.array([1.0, -1.0, 1.0])
hinge = hinge_loss(predictions, targets)

# KL divergence
p = jnp.array([0.5, 0.3, 0.2])
q = jnp.array([0.4, 0.4, 0.2])
kl = kl_divergence(p, q)

# Focal loss for imbalanced datasets
predictions = jnp.array([0.9, 0.1, 0.6])
targets = jnp.array([1.0, 0.0, 1.0])
focal = sigmoid_focal_loss(predictions, targets, alpha=0.25, gamma=2.0)

Regression Losses:

import jax.numpy as jnp
from braintools.metric import (
    squared_error,
    absolute_error,
    l1_loss,
    l2_loss,
    huber_loss,
    log_cosh,
    cosine_similarity,
    cosine_distance
)

predictions = jnp.array([1.5, 2.3, 3.1, 4.2])
targets = jnp.array([1.0, 2.0, 3.0, 4.0])

# Various regression losses
mse = squared_error(predictions, targets)
mae = absolute_error(predictions, targets)
l1 = l1_loss(predictions, targets)
l2 = l2_loss(predictions, targets)
huber = huber_loss(predictions, targets, delta=1.0)
log_cosh_loss = log_cosh(predictions, targets)

# Cosine similarity/distance
x = jnp.array([[1.0, 2.0, 3.0], [4.0, 5.0, 6.0]])
y = jnp.array([[1.0, 2.0, 3.0], [7.0, 8.0, 9.0]])
similarity = cosine_similarity(x, y)
distance = cosine_distance(x, y)

Advanced: Fenchel-Young Losses:

import jax.numpy as jnp
from jax.scipy.special import logsumexp
from braintools.metric import make_fenchel_young_loss

# ``max_fun`` is applied over the last axis via ``jnp.vectorize`` with
# signature ``(n)->()``, so it must map a 1-D score vector to a scalar.
# ``logsumexp`` recovers the softmax cross-entropy Fenchel-Young loss.
loss_fn = make_fenchel_young_loss(max_fun=logsumexp)
scores = jnp.array([[2.0, 1.0, 3.0], [1.5, 2.5, 1.0]])
targets = jnp.array([[1.0, 0.0, 0.0], [0.0, 1.0, 0.0]])
loss = loss_fn(scores, targets)

Ranking Losses:

import jax.numpy as jnp
from braintools.metric import ranking_softmax_loss

# Ranking loss for learning to rank
scores = jnp.array([[2.0, 1.0, 3.0], [1.0, 0.5, 1.5]])
labels = jnp.array([[1.0, 0.0, 0.0], [0.0, 0.0, 1.0]])
loss = ranking_softmax_loss(scores, labels)

Utilities:

import jax.numpy as jnp
from braintools.metric import smooth_labels

# Label smoothing for regularization
labels = jnp.array([[1.0, 0.0, 0.0], [0.0, 1.0, 0.0]])
smoothed = smooth_labels(labels, alpha=0.1)

Moved to braintools.analysis:

The following names still resolve in braintools.metric but are deprecated aliases: calling one emits a BraintoolsDeprecationWarning, and they will be removed in 1.0. Use the new locations instead.

raster_plot is deprecated as well; braintools.spike.SpikeTrains.from_dense replaces it.

# Before (deprecated)
from braintools.metric import firing_rate

# After
from braintools.analysis.spike import firing_rate

Loss functions and metrics for training neural networks: classification, regression, ranking, pairwise similarity and label smoothing.

Note

Moved to braintools.analysis. In 0.4 the spike-train, LFP and correlation measures moved out of this module (see braintools.analysis module):

  • firing_rate, victor_purpura_distance, van_rossum_distance, spike_train_synchrony, burst_synchrony_index, phase_locking_value, spike_time_tiling_coefficient, correlation_index and cross_correlation are in braintools.analysis.spike;

  • power_spectral_density, coherence_analysis, phase_amplitude_coupling, theta_gamma_coupling, spectral_entropy and lfp_phase_coherence are in braintools.analysis.spectral;

  • unitary_LFP and current_source_density are in braintools.analysis.field;

  • voltage_fluctuation, functional_connectivity and functional_connectivity_dynamics are in braintools.analysis.population;

  • matrix_correlation and weighted_correlation are in braintools.analysis.stats.

The old braintools.metric.<name> names still work but emit a BraintoolsDeprecationWarning when called, and will be removed in 1.0. braintools.metric.raster_plot is deprecated as well; use braintools.spike.SpikeTrains.from_dense instead.

Classification Losses#

Objective functions for training classifiers on neural or behavioral labels.

sigmoid_binary_cross_entropy

Compute element-wise sigmoid cross entropy given logits and labels.

hinge_loss

Compute the hinge loss for binary classification.

perceptron_loss

Compute the binary perceptron loss.

softmax_cross_entropy

Compute the softmax cross entropy between logits and labels.

softmax_cross_entropy_with_integer_labels

Compute softmax cross entropy between logits and integer labels.

multiclass_hinge_loss

Compute multiclass hinge loss for classification.

multiclass_perceptron_loss

Compute multiclass perceptron loss for classification.

poly_loss_cross_entropy

Compute PolyLoss cross entropy between logits and labels.

kl_divergence

Compute the Kullback-Leibler divergence (relative entropy) loss.

kl_divergence_with_log_targets

Compute KL divergence when both predictions and targets are in log-space.

convex_kl_divergence

Compute a convex version of the Kullback-Leibler divergence loss.

ctc_loss

Compute Connectionist Temporal Classification (CTC) loss.

ctc_loss_with_forward_probs

Compute CTC loss and forward probabilities for sequence alignment.

sigmoid_focal_loss

Compute sigmoid focal loss for addressing class imbalance.

nll_loss

Compute negative log likelihood loss for classification.

Fenchel-Young Loss#

Generalized convex losses derived from Fenchel-Young duality for structured prediction problems.

make_fenchel_young_loss

Create a Fenchel-Young loss function from a max function.

Ranking Losses#

Losses for ordered prediction tasks including pairwise and list-wise ranking setups.

ranking_softmax_loss

Compute ranking softmax loss for learning-to-rank applications.

Regression Losses#

Continuous-valued error metrics for fitting neural or behavioral signals.

squared_error

Compute element-wise squared error between predictions and targets.

absolute_error

Compute element-wise absolute error between predictions and targets.

l1_loss

Measure the mean absolute error (MAE) between each element in the logits \(x\) and the targets \(y\).

L1Loss

Creates a criterion that measures the mean absolute error (MAE) between each element in the input \(x\) and target \(y\).

l2_loss

Calculate the L2 loss for a set of predictions.

l2_norm

Compute the L2 norm of the difference between predictions and targets.

safe_norm

Compute vector or matrix norm with gradient-safe lower bound.

huber_loss

Compute Huber loss combining L1 and L2 properties for robust regression.

log_cosh

Calculate the log-cosh loss for a set of predictions.

cosine_similarity

Compute cosine similarity between predicted and target vectors.

cosine_distance

Compute the cosine distance between targets and predictions.

Pairwise Metrics#

Pairwise distance and similarity matrices between sets of samples.

pairwise_cosine_similarity

Compute the pairwise cosine similarity matrix between samples in X and Y.

pairwise_cosine_distance

Compute the pairwise cosine distance matrix between samples in X and Y.

Smoothing Losses#

Regularizers that promote smooth trajectories or label distributions over time.

smooth_labels

Apply label smoothing regularization to one-hot encoded labels.