class_docstr: FocalLoss is an extension of BCEWithLogitsLoss that down-weights loss from
  high confidence correct predictions.
  
  Reimplementation of the Focal Loss described in:
  
      - ["Focal Loss for Dense Object Detection"](https://arxiv.org/abs/1708.02002), T. Lin et al., ICCV 2017
      - "AnatomyNet: Deep learning for fast and fully automated whole-volume segmentation of head and neck anatomy",
        Zhu et al., Medical Physics 2018
  
  Example:
      >>> import torch
      >>> from monai.losses import FocalLoss
      >>> from torch.nn import BCEWithLogitsLoss
      >>> shape = B, N, *DIMS = 2, 3, 5, 7, 11
      >>> input = torch.rand(*shape)
      >>> target = torch.rand(*shape)
      >>> # Demonstrate equivalence to BCE when gamma=0
      >>> fl_g0_criterion = FocalLoss(reduction='none', gamma=0)
      >>> fl_g0_loss = fl_g0_criterion(input, target)
      >>> bce_criterion = BCEWithLogitsLoss(reduction='none')
      >>> bce_loss = bce_criterion(input, target)
      >>> assert torch.allclose(fl_g0_loss, bce_loss)
      >>> # Demonstrate "focus" by setting gamma > 0.
      >>> fl_g2_criterion = FocalLoss(reduction='none', gamma=2)
      >>> fl_g2_loss = fl_g2_criterion(input, target)
      >>> # Mark easy and hard cases
      >>> is_easy = (target > 0.7) & (input > 0.7)
      >>> is_hard = (target > 0.7) & (input < 0.3)
      >>> easy_loss_g0 = fl_g0_loss[is_easy].mean()
      >>> hard_loss_g0 = fl_g0_loss[is_hard].mean()
      >>> easy_loss_g2 = fl_g2_loss[is_easy].mean()
      >>> hard_loss_g2 = fl_g2_loss[is_hard].mean()
      >>> # Gamma > 0 causes the loss function to "focus" on the hard
      >>> # cases.  IE, easy cases are downweighted, so hard cases
      >>> # receive a higher proportion of the loss.
      >>> hard_to_easy_ratio_g2 = hard_loss_g2 / easy_loss_g2
      >>> hard_to_easy_ratio_g0 = hard_loss_g0 / easy_loss_g0
      >>> assert hard_to_easy_ratio_g2 > hard_to_easy_ratio_g0
class_docstr_tok: ["FocalLoss","is","an","extension","of","BCEWithLogitsLoss","that","down-weights","loss","from","high","confidence","correct","predictions",".","Reimplementation","of","the","Focal","Loss","described","in",":","-","[","``","Focal","Loss","for","Dense","Object","Detection","''","]","(","https",":","\/\/arxiv.org\/abs\/1708.02002",")",",","T.","Lin","et","al.",",","ICCV","2017","-","``","AnatomyNet",":","Deep","learning","for","fast","and","fully","automated","whole-volume","segmentation","of","head","and","neck","anatomy","''",",","Zhu","et","al.",",","Medical","Physics","2018","Example",":",">",">",">","import","torch",">",">",">","from","monai.losses","import","FocalLoss",">",">",">","from","torch.nn","import","BCEWithLogitsLoss",">",">",">","shape","=","B",",","N",",","*","DIMS","=","2",",","3",",","5",",","7",",","11",">",">",">","input","=","torch.rand","(","*","shape",")",">",">",">","target","=","torch.rand","(","*","shape",")",">",">",">","#","Demonstrate","equivalence","to","BCE","when","gamma=0",">",">",">","fl_g0_criterion","=","FocalLoss","(","reduction='none","'",",","gamma=0",")",">",">",">","fl_g0_loss","=","fl_g0_criterion","(","input",",","target",")",">",">",">","bce_criterion","=","BCEWithLogitsLoss","(","reduction='none","'",")",">",">",">","bce_loss","=","bce_criterion","(","input",",","target",")",">",">",">","assert","torch.allclose","(","fl_g0_loss",",","bce_loss",")",">",">",">","#","Demonstrate","``","focus","''","by","setting","gamma",">","0",".",">",">",">","fl_g2_criterion","=","FocalLoss","(","reduction='none","'",",","gamma=2",")",">",">",">","fl_g2_loss","=","fl_g2_criterion","(","input",",","target",")",">",">",">","#","Mark","easy","and","hard","cases",">",">",">","is_easy","=","(","target",">","0.7",")","&","(","input",">","0.7",")",">",">",">","is_hard","=","(","target",">","0.7",")","&","(","input","<","0.3",")",">",">",">","easy_loss_g0","=","fl_g0_loss","[","is_easy","]",".mean","(",")",">",">",">","hard_loss_g0","=","fl_g0_loss","[","is_hard","]",".mean","(",")",">",">",">","easy_loss_g2","=","fl_g2_loss","[","is_easy","]",".mean","(",")",">",">",">","hard_loss_g2","=","fl_g2_loss","[","is_hard","]",".mean","(",")",">",">",">","#","Gamma",">","0","causes","the","loss","function","to","``","focus","''","on","the","hard",">",">",">","#","cases",".","IE",",","easy","cases","are","downweighted",",","so","hard","cases",">",">",">","#","receive","a","higher","proportion","of","the","loss",".",">",">",">","hard_to_easy_ratio_g2","=","hard_loss_g2","\/","easy_loss_g2",">",">",">","hard_to_easy_ratio_g0","=","hard_loss_g0","\/","easy_loss_g0",">",">",">","assert","hard_to_easy_ratio_g2",">","hard_to_easy_ratio_g0"]
docstr: Args:
      include_background: if False, channel index 0 (background category) is excluded from the loss calculation.
          If False, `alpha` is invalid when using softmax.
      to_onehot_y: whether to convert the label `y` into the one-hot format. Defaults to False.
      gamma: value of the exponent gamma in the definition of the Focal loss. Defaults to 2.
      alpha: value of the alpha in the definition of the alpha-balanced Focal loss.
          The value should be in [0, 1]. Defaults to None.
      weight: weights to apply to the voxels of each class. If None no weights are applied.
          The input can be a single value (same weight for all classes), a sequence of values (the length
          of the sequence should be the same as the number of classes. If not ``include_background``,
          the number of classes should not include the background category class 0).
          The value/values should be no less than 0. Defaults to None.
      reduction: {``"none"``, ``"mean"``, ``"sum"``}
          Specifies the reduction to apply to the output. Defaults to ``"mean"``.
  
          - ``"none"``: no reduction will be applied.
          - ``"mean"``: the sum of the output will be divided by the number of elements in the output.
          - ``"sum"``: the output will be summed.
  
      use_softmax: whether to use softmax to transform the original logits into probabilities.
          If True, softmax is used. If False, sigmoid is used. Defaults to False.
  
  Example:
      >>> import torch
      >>> from monai.losses import FocalLoss
      >>> pred = torch.tensor([[1, 0], [0, 1], [1, 0]], dtype=torch.float32)
      >>> grnd = torch.tensor([[0], [1], [0]], dtype=torch.int64)
      >>> fl = FocalLoss(to_onehot_y=True)
      >>> fl(pred, grnd)
docstr_tok: ["Args",":","include_background",":","if","False",",","channel","index","0","(","background","category",")","is","excluded","from","the","loss","calculation",".","If","False",",","`","alpha","`","is","invalid","when","using","softmax",".","to_onehot_y",":","whether","to","convert","the","label","`","y","`","into","the","one-hot","format",".","Defaults","to","False",".","gamma",":","value","of","the","exponent","gamma","in","the","definition","of","the","Focal","loss",".","Defaults","to","2.","alpha",":","value","of","the","alpha","in","the","definition","of","the","alpha-balanced","Focal","loss",".","The","value","should","be","in","[","0",",","1","]",".","Defaults","to","None",".","weight",":","weights","to","apply","to","the","voxels","of","each","class",".","If","None","no","weights","are","applied",".","The","input","can","be","a","single","value","(","same","weight","for","all","classes",")",",","a","sequence","of","values","(","the","length","of","the","sequence","should","be","the","same","as","the","number","of","classes",".","If","not","``","include_background","``",",","the","number","of","classes","should","not","include","the","background","category","class","0",")",".","The","value\/values","should","be","no","less","than","0",".","Defaults","to","None",".","reduction",":","{","``","``","none","''","``",",","``","``","mean","''","``",",","``","``","sum","''","``","}","Specifies","the","reduction","to","apply","to","the","output",".","Defaults","to","``","``","mean","''","``",".","-","``","``","none","''","``",":","no","reduction","will","be","applied",".","-","``","``","mean","''","``",":","the","sum","of","the","output","will","be","divided","by","the","number","of","elements","in","the","output",".","-","``","``","sum","''","``",":","the","output","will","be","summed",".","use_softmax",":","whether","to","use","softmax","to","transform","the","original","logits","into","probabilities",".","If","True",",","softmax","is","used",".","If","False",",","sigmoid","is","used",".","Defaults","to","False",".","Example",":",">",">",">","import","torch",">",">",">","from","monai.losses","import","FocalLoss",">",">",">","pred","=","torch.tensor","(","[","[","1",",","0","]",",","[","0",",","1","]",",","[","1",",","0","]","]",",","dtype=torch.float32",")",">",">",">","grnd","=","torch.tensor","(","[","[","0","]",",","[","1","]",",","[","0","]","]",",","dtype=torch.int64",")",">",">",">","fl","=","FocalLoss","(","to_onehot_y=True",")",">",">",">","fl","(","pred",",","grnd",")"]
code: def __init__(
      self,
      include_background: bool = True,
      to_onehot_y: bool = False,
      gamma: float = 2.0,
      alpha: float | None = None,
      weight: Sequence[float]
      | float
      | int
      | torch.Tensor
      | None = None,
      reduction: LossReduction | str = LossReduction.MEAN,
      use_softmax: bool = False,
  ) -> None:
      """
      Args:
          include_background: if False, channel index 0 (background category) is excluded from the loss calculation.
              If False, `alpha` is invalid when using softmax.
          to_onehot_y: whether to convert the label `y` into the one-hot format. Defaults to False.
          gamma: value of the exponent gamma in the definition of the Focal loss. Defaults to 2.
          alpha: value of the alpha in the definition of the alpha-balanced Focal loss.
              The value should be in [0, 1]. Defaults to None.
          weight: weights to apply to the voxels of each class. If None no weights are applied.
              The input can be a single value (same weight for all classes), a sequence of values (the length
              of the sequence should be the same as the number of classes. If not ``include_background``,
              the number of classes should not include the background category class 0).
              The value/values should be no less than 0. Defaults to None.
          reduction: {``"none"``, ``"mean"``, ``"sum"``}
              Specifies the reduction to apply to the output. Defaults to ``"mean"``.
  
              - ``"none"``: no reduction will be applied.
              - ``"mean"``: the sum of the output will be divided by the number of elements in the output.
              - ``"sum"``: the output will be summed.
  
          use_softmax: whether to use softmax to transform the original logits into probabilities.
              If True, softmax is used. If False, sigmoid is used. Defaults to False.
  
      Example:
          >>> import torch
          >>> from monai.losses import FocalLoss
          >>> pred = torch.tensor([[1, 0], [0, 1], [1, 0]], dtype=torch.float32)
          >>> grnd = torch.tensor([[0], [1], [0]], dtype=torch.int64)
          >>> fl = FocalLoss(to_onehot_y=True)
          >>> fl(pred, grnd)
      """
      super().__init__(reduction=LossReduction(reduction).value)
      self.include_background = include_background
      self.to_onehot_y = to_onehot_y
      self.gamma = gamma
      self.alpha = alpha
      self.weight = weight
      self.use_softmax = use_softmax
      weight = torch.as_tensor(weight) if weight is not None else None
      self.register_buffer("class_weight", weight)
      self.class_weight: None | torch.Tensor
  
file_path: MONAI/monai/losses/focal_loss.py
imports: from __future__ import annotations
  import warnings
  from collections.abc import Sequence
  from typing import Optional
  import torch
  import torch.nn.functional
  from torch.nn.modules.loss import _Loss
  from monai.networks import one_hot
  from monai.utils import LossReduction
label_desc: Use image node_id 1 to create a new FocalLoss object from inherited base classes: _Loss with example: obj = FocalLoss(include_background, to_onehot_y, gamma, alpha, weight, reduction, use_softmax)