Struct FocalLoss 

pub struct FocalLoss { /* private fields */ }

Focal loss function.

The focal loss is designed to address class imbalance problems by down-weighting easy examples and focusing training on hard examples. For a single class, the focal loss is defined as: FL(p_t) = -α_t * (1 - p_t)^γ * log(p_t) where p_t is the model’s estimated probability for the true class.

Examples

use scirs2_neural::losses::FocalLoss;
use scirs2_neural::losses::Loss;
use scirs2_core::ndarray::{Array, arr2};

let focal = FocalLoss::new(2.0, Some(0.25), 1e-10);
// Predictions and targets for a 3-class problem
let predictions = arr2(&[
    [0.7, 0.2, 0.1],  // First sample, class probabilities
    [0.3, 0.6, 0.1]   // Second sample, class probabilities
]).into_dyn();
let targets = arr2(&[
    [1.0, 0.0, 0.0],  // First sample, true class is 0
    [0.0, 1.0, 0.0]   // Second sample, true class is 1
]).into_dyn();
// Forward pass to calculate loss
let loss = focal.forward(&predictions, &targets).unwrap();
// Backward pass to calculate gradients
let gradients = focal.backward(&predictions, &targets).unwrap();

Implementations

impl FocalLoss

pub fn new(gamma: f64, alpha: Option<f64>, epsilon: f64) -> Self

Create a new focal loss function with a single alpha value for all classes

Arguments

• gamma - Focusing parameter, gamma >= 0. Higher gamma means more focus on misclassified examples.
• alpha - Optional weighting factor, typically between 0 and 1.
• epsilon - Small value to add to predictions to avoid log(0)

Examples found in repository

examples/loss_functions_example.rs (line 40)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    println!("Loss functions example");
    // Mean Squared Error example
    println!("\n--- Mean Squared Error Example ---");
    let mse = MeanSquaredError::new();
    // Create sample data for regression
    let predictions = Array::from_vec(vec![1.0, 2.0, 3.0]).into_dyn();
    let targets = Array::from_vec(vec![1.5, 1.8, 2.5]).into_dyn();
    // Calculate loss
    let loss = mse.forward(&predictions, &targets)?;
    println!("Predictions: {predictions:?}");
    println!("Targets: {targets:?}");
    println!("MSE Loss: {loss:.4}");
    // Calculate gradients
    let gradients = mse.backward(&predictions, &targets)?;
    println!("MSE Gradients: {gradients:?}");
    // Cross-Entropy Loss example
    println!("\n--- Cross-Entropy Loss Example ---");
    let ce = CrossEntropyLoss::new(1e-10);
    // Create sample data for multi-class classification
    let predictions = Array::from_shape_vec(IxDyn(&[2, 3]), vec![0.7, 0.2, 0.1, 0.3, 0.6, 0.1])?;
    let targets = Array::from_shape_vec(IxDyn(&[2, 3]), vec![1.0, 0.0, 0.0, 0.0, 1.0, 0.0])?;
    let loss = ce.forward(&predictions, &targets)?;
    println!("Predictions (probabilities):");
    println!("{predictions:?}");
    println!("Targets (one-hot):");
    println!("{targets:?}");
    println!("Cross-Entropy Loss: {loss:.4}");
    let gradients = ce.backward(&predictions, &targets)?;
    println!("Cross-Entropy Gradients:");
    println!("{gradients:?}");
    // Focal Loss example
    println!("\n--- Focal Loss Example ---");
    let focal = FocalLoss::new(2.0, Some(0.25), 1e-10);
    // Create sample data for imbalanced classification
    let loss = focal.forward(&predictions, &targets)?;
    println!("Focal Loss (gamma=2.0, alpha=0.25): {loss:.4}");
    let _gradients = focal.backward(&predictions, &targets)?;
    println!("Focal Loss Gradients:");
    // Contrastive Loss example
    println!("\n--- Contrastive Loss Example ---");
    let contrastive = ContrastiveLoss::new(1.0);
    // Create sample data for similarity learning
    // Embedding pairs (batch_size x 2 x embedding_dim)
    let embeddings = Array::from_shape_vec(
        IxDyn(&[2, 2, 3]),
        vec![
            0.1, 0.2, 0.3, // First pair, first embedding
            0.1, 0.3, 0.3, // First pair, second embedding (similar)
            0.5, 0.5, 0.5, // Second pair, first embedding
            0.9, 0.8, 0.7, // Second pair, second embedding (dissimilar)
        ],
    )?;
    // Labels: 1 for similar pairs, 0 for dissimilar
    let labels = Array::from_shape_vec(IxDyn(&[2, 1]), vec![1.0, 0.0])?;
    let loss = contrastive.forward(&embeddings, &labels)?;
    println!("Embeddings (batch_size x 2 x embedding_dim):");
    println!("{embeddings:?}");
    println!("Labels (1 for similar, 0 for dissimilar):");
    println!("{labels:?}");
    println!("Contrastive Loss (margin=1.0): {loss:.4}");
    let gradients = contrastive.backward(&embeddings, &labels)?;
    println!("Contrastive Loss Gradients (first few):");
    let gradient_slice = gradients.slice(scirs2_core::ndarray::s![0, .., 0]);
    println!("{gradient_slice:?}");
    // Triplet Loss example
    println!("\n--- Triplet Loss Example ---");
    let triplet = TripletLoss::new(0.5);
    // Create sample data for triplet learning
    // Embedding triplets (batch_size x 3 x embedding_dim)
    let triplet_embeddings = Array3::from_shape_vec(
        (2, 3, 3),
        vec![
            0.1, 0.2, 0.3, // First triplet, anchor
            0.1, 0.3, 0.3, // First triplet, positive
            0.5, 0.5, 0.5, // First triplet, negative
            0.6, 0.6, 0.6, // Second triplet, anchor
            0.5, 0.6, 0.6, // Second triplet, positive
            0.1, 0.1, 0.1, // Second triplet, negative
        ],
    )?
    .into_dyn();
    // Dummy labels (not used by triplet loss)
    let dummy_labels = Array::zeros(IxDyn(&[2, 1]));
    let loss = triplet.forward(&triplet_embeddings, &dummy_labels)?;
    println!("Embeddings (batch_size x 3 x embedding_dim):");
    println!("  - First dimension: batch size");
    println!("  - Second dimension: [anchor, positive, negative]");
    println!("  - Third dimension: embedding components");
    println!("Triplet Loss (margin=0.5): {loss:.4}");
    let _gradients = triplet.backward(&triplet_embeddings, &dummy_labels)?;
    println!("Triplet Loss Gradients (first few):");
    Ok(())
}

pub fn with_class_weights( gamma: f64, alpha_perclass: Vec<f64>, epsilon: f64, ) -> Self

Create a focal loss with class-specific alpha weights

• alpha_per_class - Vector of weighting factors, one per class

Trait Implementations

impl Clone for FocalLoss

fn clone(&self) -> FocalLoss

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for FocalLoss

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for FocalLoss

fn default() -> Self

Returns the “default value” for a type.

impl<F: Float + Debug> Loss<F> for FocalLoss

fn forward( &self, predictions: &Array<F, IxDyn>, targets: &Array<F, IxDyn>, ) -> Result<F>

Calculate the loss between predictions and targets

fn backward( &self, predictions: &Array<F, IxDyn>, targets: &Array<F, IxDyn>, ) -> Result<Array<F, IxDyn>>

Calculate the gradient of the loss with respect to the predictions This method computes ∂Loss/∂predictions, which is used in backpropagation to update the model parameters.