FAT Forensics

FAT Forensics: A Python Toolbox for Implementing and Deploying Fairness, Accountability and Transparency Algorithms in Predictive Systems - Published in JOSS (2020)

https://github.com/fat-forensics/fat-forensics

Keywords

Scientific Fields

Repository

Modular Python Toolbox for Fairness, Accountability and Transparency Forensics

README.rst

.. -*- mode: rst -*-

=============  ================================================================
Software       |Licence|_ |GitHubRelease|_ |PyPi|_ |Python35|_
Docs           |Homepage|_
CI             |GitHubTests|_ |GitHubDocs|_ |Codecov|_
Try it         |Binder|_
Contact        |MailingList|_ |Gitter|_
Cite           |BibTeX|_ |JOSS|_ |ZENODO|_
=============  ================================================================

.. |Licence| image:: https://img.shields.io/github/license/fat-forensics/fat-forensics.svg
.. _Licence: https://github.com/fat-forensics/fat-forensics/blob/master/LICENCE

.. |GitHubRelease| image:: https://img.shields.io/github/release/fat-forensics/fat-forensics.svg
.. _GitHubRelease: https://github.com/fat-forensics/fat-forensics/releases

.. |PyPi| image:: https://img.shields.io/pypi/v/fat-forensics.svg
.. _PyPi: https://pypi.org/project/fat-forensics/

.. |Python35| image:: https://img.shields.io/badge/python-3.5-blue.svg
.. _Python35: https://badge.fury.io/py/fat-forensics

.. .. |ReadTheDocs| image:: https://readthedocs.org/projects/fat-forensics/badge/?version=latest&style=flat
.. .. _ReadTheDocs: https://fat-forensics.readthedocs.io/en/latest/

.. |Homepage| image:: https://img.shields.io/badge/homepage-read-green.svg
.. _Homepage: https://fat-forensics.org
.. What about wiki?

.. |GitHubTests| image:: https://github.com/fat-forensics/fat-forensics/actions/workflows/tests.yml/badge.svg
.. _GitHubTests: https://github.com/fat-forensics/fat-forensics/actions/workflows/tests.yml
.. |GitHubDocs| image:: https://github.com/fat-forensics/fat-forensics/actions/workflows/docs.yml/badge.svg
.. _GitHubDocs: https://github.com/fat-forensics/fat-forensics/actions/workflows/docs.yml

.. .. |CircleCI| image:: https://circleci.com/gh/fat-forensics/fat-forensics/tree/master.svg?style=shield
.. .. _CircleCI: https://circleci.com/gh/fat-forensics/fat-forensics/tree/master

.. |Codecov| image:: https://codecov.io/gh/fat-forensics/fat-forensics/branch/master/graph/badge.svg
.. _Codecov: https://codecov.io/gh/fat-forensics/fat-forensics

.. https://codeclimate.com/

.. https://requires.io/

.. |Binder| image:: https://mybinder.org/badge_logo.svg
.. _Binder: https://mybinder.org/v2/gh/fat-forensics/fat-forensics-doc/master?filepath=notebooks

.. |MailingList| image:: https://img.shields.io/badge/mailing%20list-Google%20Groups-green.svg
.. _MailingList: https://groups.google.com/forum/#!forum/fat-forensics

.. |Gitter| image:: https://img.shields.io/gitter/room/fat-forensics/FAT-Forensics.svg
.. _Gitter: https://gitter.im/fat-forensics

.. |BibTeX| image:: https://img.shields.io/badge/cite-BibTeX-blue.svg
.. _BibTeX: https://fat-forensics.org/getting_started/cite.html

.. |JOSS| image:: https://joss.theoj.org/papers/10.21105/joss.01904/status.svg
.. _JOSS: https://doi.org/10.21105/joss.01904

.. |ZENODO| image:: https://zenodo.org/badge/DOI/10.5281/zenodo.3833199.svg
.. _ZENODO: https://doi.org/10.5281/zenodo.3833199

============================================================================
FAT Forensics: Algorithmic Fairness, Accountability and Transparency Toolbox
============================================================================

FAT Forensics (``fatf``) is a Python toolbox for evaluating fairness,
accountability and transparency of predictive systems. It is built on top of
SciPy_ and NumPy_, and is distributed under the 3-Clause BSD license (new BSD).

FAT Forensics implements the state of the art *fairness*, *accountability* and
*transparency* (FAT) algorithms for the three main components of any data
modelling pipeline: *data* (raw data and features), predictive *models* and
model *predictions*. We envisage two main use cases for the package, each
supported by distinct features implemented to support it: an interactive
*research mode* aimed at researchers who may want to use it for an exploratory
analysis and a *deployment mode* aimed at practitioners who may want to use it
for monitoring FAT aspects of a predictive system.

Please visit the project's web site `https://fat-forensics.org`_ for more
details.

Installation
============

Dependencies
------------

FAT Forensics requires **Python 3.5** or higher and the following dependencies:

+------------+------------+
| Package    | Version    |
+============+============+
| NumPy_     | >=1.10.0   |
+------------+------------+
| SciPy_     | >=0.13.3   |
+------------+------------+

In addition, some of the modules require *optional* dependencies:

+--------------------------------------------------------------+------------------+------------+
| ``fatf`` module                                              | Package          | Version    |
+==============================================================+==================+============+
| ``fatf.transparency.predictions.surrogate_explainers``       |                  |            |
+--------------------------------------------------------------+                  |            |
| ``fatf.transparency.predictions.surrogate_image_explainers`` |                  |            |
+--------------------------------------------------------------+                  |            |
| ``fatf.transparency.sklearn``                                | `scikit-learn`_  | >=0.19.2   |
+--------------------------------------------------------------+                  |            |
| ``fatf.utils.data.feature_selection.sklearn``                |                  |            |
+--------------------------------------------------------------+------------------+------------+
| ``fatf.transparency.predictions.surrogate_image_explainers`` |                  |            |
+--------------------------------------------------------------+                  |            |
| ``fatf.utils.data.occlusion``                                | `scikit-image`_  | >=0.17.0   |
+--------------------------------------------------------------+                  |            |
| ``fatf.utils.data.segmentation``                             |                  |            |
+--------------------------------------------------------------+------------------+------------+
| ``fatf.transparency.predictions.surrogate_image_explainers`` |                  |            |
+--------------------------------------------------------------+                  |            |
| ``fatf.utils.data.occlusion``                                | `Pillow`_        | >=8.4.0    |
+--------------------------------------------------------------+                  |            |
| ``fatf.utils.data.segmentation``                             |                  |            |
+--------------------------------------------------------------+------------------+------------+
| ``fatf.vis``                                                 | matplotlib_      | >=3.0.0    |
+--------------------------------------------------------------+------------------+------------+

User Installation
-----------------

The easies way to install FAT Forensics is via ``pip``::

   pip install fat-forensics

which will only installed the required dependencies. If you want to install the
package together with all the auxiliary dependencies please consider using the
``[all]`` option::

   pip install fat-forensics[all]

The documentation provides more detailed `installation instructions `_.

Changelog
=========

See the changelog_ for a development history and project milestones.

Development
===========

We welcome new contributors of all experience levels. The
`Development Guide `_ has detailed information about contributing
code, documentation, tests and more. Some basic development instructions are
included below.

Important Links
---------------

* Project's web site and documentation: `https://fat-forensics.org`_.
* Official source code repository:
  `https://github.com/fat-forensics/fat-forensics`_.
* FAT Forensics releases: `https://pypi.org/project/fat-forensics`_.
* Issue tracker: `https://github.com/fat-forensics/fat-forensics/issues`_.

Source Code
-----------

You can check out the latest FAT Forensics source code via git with the
command::

   git clone https://github.com/fat-forensics/fat-forensics.git

Contributing
------------

To learn more about contributing to FAT Forensics, please see our
`Contributing Guide `_.

Testing
-------

You can launch the test suite from the root directory of this repository with::

   make test-with-code-coverage

To run the tests you will need to have version 3.9.1 of ``pytest`` installed.
This package, together with other development dependencies, can be also
installed with::

   pip install -r requirements-dev.txt

or with::

   pip install fat-forensics[dev]

See the *Testing* section of the `Development Guide `_ page for
more information.

    Please note that the ``make test-with-code-coverage`` command will test the
    version of the package in the local ``fatf`` directory and not the one
    installed since the pytest command is preceded by ``PYTHONPATH=./``. If
    you want to test the installed version, consider using the command from the
    ``Makefile`` without the ``PYTHONPATH`` variable.

    To control the randomness during the tests the ``Makefile`` sets the random
    seed to ``42`` by preceding each test command with ``FATF_SEED=42``, which
    sets the environment variable responsible for that. More information about
    the setup of the *Testing Environment* is available on the
    `development `_ web page in the documentation.

Submitting a Pull Request
-------------------------

Before opening a Pull Request, please have a look at the
`Contributing `_ page to make sure that your code complies with
our guidelines.

Help and Support
================

For help please have a look at our
`documentation web page `_, especially the
`Getting Started `_ page.

Communication
-------------

You can reach out to us at:

* our gitter_ channel for code-related development discussion; and
* our `mailing list`_ for discussion about the project's future and the
  direction of the development.

More information about the communication can be found in our documentation
on the `main page `_ and
on the
`develop page `_.

Citation
--------

If you use FAT Forensics in a scientific publication, we would appreciate
citations! Information on how to cite use is available on the
`citation `_ web page in
our documentation.

Acknowledgements
================
This project is the result of a collaborative research agreement between Thales
and the University of Bristol with the initial funding provided by Thales.

.. _SciPy: https://scipy.org/
.. _NumPy: https://www.numpy.org/
.. _scikit-learn: https://scikit-learn.org/stable/
.. _matplotlib: https://matplotlib.org/
.. _scikit-image: https://scikit-image.org/
.. _Pillow: https://pillow.readthedocs.io/
.. _`https://fat-forensics.org`: https://fat-forensics.org
.. _inst: https://fat-forensics.org/getting_started/install_deps_os.html#installation-instructions
.. _changelog: https://fat-forensics.org/changelog.html
.. _dev_guide: https://fat-forensics.org/development.html
.. _`https://github.com/fat-forensics/fat-forensics`: https://github.com/fat-forensics/fat-forensics
.. _`https://pypi.org/project/fat-forensics`: https://pypi.org/project/fat-forensics
.. _`https://github.com/fat-forensics/fat-forensics/issues`: https://github.com/fat-forensics/fat-forensics/issues
.. _contrib_guide: https://fat-forensics.org/development.html#contributing-code
.. _dev_testing: https://fat-forensics.org/development.html#testing
.. _dev_testing_env: https://fat-forensics.org/development.html#testing-environment
.. _getting_started: https://fat-forensics.org/getting_started/index.html
.. _gitter: https://gitter.im/fat-forensics
.. _`mailing list`: https://groups.google.com/forum/#!forum/fat-forensics

Owner

JOSS Publication

FAT Forensics: A Python Toolbox for Implementing and Deploying Fairness, Accountability and Transparency Algorithms in Predictive Systems

Published

May 19, 2020

DOI

10.21105/joss.01904

Volume 5, Issue 49, Page 1904

Authors

Kacper Sokol
Department of Computer Science, University of Bristol

Alexander Hepburn
Department of Engineering Mathematics, University of Bristol

Rafael Poyiadzi
Department of Engineering Mathematics, University of Bristol

Matthew Clifford
Department of Engineering Mathematics, University of Bristol

Raul Santos-Rodriguez
Department of Engineering Mathematics, University of Bristol

Peter Flach
Department of Computer Science, University of Bristol

Editor

Ariel Rokem

Tags

Fairness Accountability Transparency Artificial Intelligence Machine Learning Software Python Toolbox

View PDF Review Thread Software Archive

GitHub Events

Committers

Last synced: 5 months ago

Issues and Pull Requests

Last synced: 4 months ago

Packages