Metadata-Version: 2.4
Name: focal_ce_loss
Version: 0.0.3
Summary: A loss function for 
License: GPLv3
License-File: LICENSE
Keywords: Python,data visualization,open-source
Author: rpetras ricky@petras.us
Requires-Python: >=3.11
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: Other/Proprietary License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Dist: torch
Project-URL: Documentation, https://github.com/RPetras3/focal_ce_loss_funcs_pytorch/README.MD
Project-URL: Homepage, https://github.com/RPetras3/focal_ce_loss_funcs_pytorch
Project-URL: Issues, https://github.com/RPetras3/focal_ce_loss_funcs_pytorch/issues
Project-URL: PyPI, https://pypi.org/project/focal_ce_loss
Project-URL: Repository, https://github.com/RPetras3/focal_ce_loss_funcs_pytorch
Description-Content-Type: text/markdown

# Focal Cross Entropy Loss

A PyTorch-compatible implementation of the Focal Cross Entropy loss function, designed to address class imbalance by down-weighting easy examples and focusing training on hard negatives.

## Install

```text
pip install focal_ce_loss_funcs_pytorch
```

## Quick start

```python
from focal_ce_loss import FocalCELoss

criterion = FocalCELoss()
loss = criterion(inputs, targets)
```
### FocalCELoss

A PyTorch `nn.Module` implementing the Focal Cross Entropy loss.

```python
from focal_ce_loss import FocalCELoss

criterion = FocalCELoss(alpha=0.25, gamma=2.0, reduction="sum")

# Compute loss from logits and targets
loss = criterion(inputs, targets)
loss.backward()
```

**Parameters**
- `gamma`: focusing parameter; higher values down-weight easy examples more aggressively (default: `2.0`)
- `alpha`: optional class weight for additional class balancing (default: `0.25`)
- `reduction`: specifies the reduction to apply — `"mean"`, `"sum"`, or `"none"` (default: `"sum"`)
- `ignore_index`: target value to ignore during loss computation (default: `-100`)

**Methods**
- `forward(input, target)` — accepts a torch.Tensor of shape `(N, C)` and integer targets of shape `(N,)`; returns a scalar loss tensor (or per-sample tensor if `reduction="none"`)

**Inputs**
- `input`: `torch.Tensor` of shape `(N, C)`
- `target`: `torch.Tensor` of shape `(N,)`
`
**Example**

```python
import torch
from focal_ce_loss import FocalCELoss

inputs  = torch.randn(8, 10)          # batch of 8, 10 classes
targets = torch.randint(0, 10, (8,))  # ground-truth labels

criterion = FocalCELoss(gamma=2.0)
loss = criterion(inputs, targets)
loss.backward()
```

### BFCELoss

A PyTorch `nn.Module` implementing the Binary Focal Cross Entropy loss for binary classification tasks.

```python
from focal_ce_loss import BFCELoss

criterion = BFCELoss(alpha=0.25, gamma=2.0, reduction="sum")

# Compute loss from logits and binary targets
loss = criterion(inputs, targets)
loss.backward()
```

**Parameters**
- `gamma`: focusing parameter; higher values down-weight easy examples more aggressively (default: `2.0`)
- `alpha`: optional class weight for the positive class (default: `0.25`)
- `reduction`: specifies the reduction to apply — `"mean"`, `"sum"`, or `"none"` (default: `"mean"`)
- `ignore_index`: target value to ignore during loss computation (default: `-100`)

**Methods**
- `forward(input, target)` — accepts a torch.Tensor of shape `(N,)` or `(N, 1)` and binary targets of shape `(N,)`; returns a scalar loss tensor (or per-sample tensor if `reduction="none"`)

**Inputs**
- `input`: `torch.Tensor` of shape `(N,)` or `(N, 1)` of predicted probabilities with values in [0, 1].
- `target`: `torch.Tensor` of shape `(N,)` containing binary labels `{0, 1}`

**Example**

```python
import torch
from focal_ce_loss import BFCELoss

inputs  = torch.randn(8)           # batch of 8 logits
targets = torch.randint(0, 2, (8,)).float()  # binary ground-truth labels

criterion = BFCELoss(gamma=2.0, alpha=0.25)
loss = criterion(inputs, targets)
loss.backward()
```
