==========
Focal Loss
==========

.. image:: https://img.shields.io/pypi/pyversions/focal-loss
    :target: https://pypi.org/project/focal-loss
    :alt: Python Version

.. image:: https://img.shields.io/pypi/v/focal-loss
    :target: https://pypi.org/project/focal-loss
    :alt: PyPI Package Version

.. image:: https://travis-ci.com/artemmavrin/focal-loss.svg?branch=master
    :target: https://travis-ci.com/artemmavrin/focal-loss
    :alt: Build Status

.. image:: https://codecov.io/gh/artemmavrin/focal-loss/branch/master/graph/badge.svg
    :target: https://codecov.io/gh/artemmavrin/focal-loss
    :alt: Code Coverage

.. image:: https://readthedocs.org/projects/focal-loss/badge/?version=latest
    :target: https://focal-loss.readthedocs.io/en/latest/?badge=latest
    :alt: Documentation Status

.. image:: https://img.shields.io/github/license/artemmavrin/focal-loss
    :target: https://github.com/artemmavrin/focal-loss/blob/master/LICENSE
    :alt: License

TensorFlow implementation of focal loss [1]_: a loss function generalizing
binary cross-entropy loss that penalizes hard-to-classify examples.

The ``focal_loss`` package provides a function ``binary_focal_loss`` and a class
``BinaryFocalLoss`` that can be used as stand-in replacements for
``tf.keras.losses`` functions and classes, respectively.

.. code-block:: python

    # Typical tf.keras API usage
    import tensorflow as tf
    from focal_loss import BinaryFocalLoss

    model = tf.keras.Model(...)
    model.compile(
        optimizer=...,
        loss=BinaryFocalLoss(gamma=2)
        metrics=...,
    )
    history = model.fit(...)

.. image:: docs/source/images/focal-loss.png
    :alt: Focal loss plot

Installation
------------

1.  Make sure that a CPU or GPU version of TensorFlow 2.0 or later is installed
    (see `this link <https://www.tensorflow.org/install>`__ for installation
    instructions).

2.  The ``focal_loss`` package can be installed using the
    `pip <https://pip.pypa.io/en/stable/>`__ utility. For the latest version,
    install directly from the package's
    `GitHub page <https://github.com/artemmavrin/focal-loss>`__:

    .. code-block:: bash

        pip install git+https://github.com/artemmavrin/focal-loss.git

    Alternatively, install the a recent release from the
    `Python Package Index (PyPI) <https://pypi.org/project/focal-loss>`__:

    .. code-block:: bash

        pip install focal-loss

    .. note::

        To install the project for development (e.g., to make changes to the
        source code), clone the project repository from GitHub and run
        :code:`make dev`:

        .. code-block:: bash

            git clone https://github.com/artemmavrin/focal-loss.git
            cd focal-loss
            make dev

        This will additionally install the requirements needed
        to run tests, check code coverage, and produce documentation.

References
----------

.. [1] T. Lin, P. Goyal, R. Girshick, K. He and P. Dollár. Focal loss for dense
    object detection. IEEE Transactions on Pattern Analysis and Machine
    Intelligence, 2018. (`DOI <https://doi.org/10.1109/TPAMI.2018.2858826>`__)
    (`arXiv preprint <https://arxiv.org/abs/1708.02002>`__)
