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.
braintools.analysis.spike:firing_rate,victor_purpura_distance,van_rossum_distance,spike_train_synchrony,burst_synchrony_index,phase_locking_value,spike_time_tiling_coefficient,correlation_index,cross_correlationbraintools.analysis.spectral:power_spectral_density,coherence_analysis,phase_amplitude_coupling,theta_gamma_coupling,spectral_entropy,lfp_phase_coherencebraintools.analysis.field:unitary_LFP,current_source_densitybraintools.analysis.population:voltage_fluctuation,functional_connectivity,functional_connectivity_dynamicsbraintools.analysis.stats:matrix_correlation,weighted_correlation
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_indexandcross_correlationare inbraintools.analysis.spike;power_spectral_density,coherence_analysis,phase_amplitude_coupling,theta_gamma_coupling,spectral_entropyandlfp_phase_coherenceare inbraintools.analysis.spectral;unitary_LFPandcurrent_source_densityare inbraintools.analysis.field;voltage_fluctuation,functional_connectivityandfunctional_connectivity_dynamicsare inbraintools.analysis.population;matrix_correlationandweighted_correlationare inbraintools.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.
Compute element-wise sigmoid cross entropy given logits and labels. |
|
Compute the hinge loss for binary classification. |
|
Compute the binary perceptron loss. |
|
Compute the softmax cross entropy between logits and labels. |
|
Compute softmax cross entropy between logits and integer labels. |
|
Compute multiclass hinge loss for classification. |
|
Compute multiclass perceptron loss for classification. |
|
Compute PolyLoss cross entropy between logits and labels. |
|
Compute the Kullback-Leibler divergence (relative entropy) loss. |
|
Compute KL divergence when both predictions and targets are in log-space. |
|
Compute a convex version of the Kullback-Leibler divergence loss. |
|
Compute Connectionist Temporal Classification (CTC) loss. |
|
Compute CTC loss and forward probabilities for sequence alignment. |
|
Compute sigmoid focal loss for addressing class imbalance. |
|
Compute negative log likelihood loss for classification. |
Fenchel-Young Loss#
Generalized convex losses derived from Fenchel-Young duality for structured prediction problems.
Create a Fenchel-Young loss function from a max function. |
Ranking Losses#
Losses for ordered prediction tasks including pairwise and list-wise ranking setups.
Compute ranking softmax loss for learning-to-rank applications. |
Regression Losses#
Continuous-valued error metrics for fitting neural or behavioral signals.
Compute element-wise squared error between predictions and targets. |
|
Compute element-wise absolute error between predictions and targets. |
|
Measure the mean absolute error (MAE) between each element in the logits \(x\) and the targets \(y\). |
|
Creates a criterion that measures the mean absolute error (MAE) between each element in the input \(x\) and target \(y\). |
|
Calculate the L2 loss for a set of predictions. |
|
Compute the L2 norm of the difference between predictions and targets. |
|
Compute vector or matrix norm with gradient-safe lower bound. |
|
Compute Huber loss combining L1 and L2 properties for robust regression. |
|
Calculate the log-cosh loss for a set of predictions. |
|
Compute cosine similarity between predicted and target vectors. |
|
Compute the cosine distance between targets and predictions. |
Pairwise Metrics#
Pairwise distance and similarity matrices between sets of samples.
Compute the pairwise cosine similarity matrix between samples in |
|
Compute the pairwise cosine distance matrix between samples in |
Smoothing Losses#
Regularizers that promote smooth trajectories or label distributions over time.
Apply label smoothing regularization to one-hot encoded labels. |