| Name | EthicML JSON |
| Version |
1.3.0
JSON |
| download |
| home_page | https://github.com/wearepal/EthicML |
| Summary | EthicML is a library for performing and assessing algorithmic fairness. Unlike other libraries, EthicML isn't an education tool, but rather a researcher's toolkit. |
| upload_time | 2023-11-11 13:12:59 |
| maintainer | |
| docs_url | None |
| author | PAL |
| requires_python | >=3.10,<3.13 |
| license | |
| keywords |
ml
fairness
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# EthicML: A featureful framework for developing fair algorithms
[](http://mypy-lang.org/)
EthicML is a library for performing and assessing __algorithmic fairness__.
Unlike other libraries, EthicML isn't an education tool, but rather a __researcher__'s toolkit.
Other algorthimic fairness packages are useful, but given that we primarily do research,
a lot of the work we do doesn't fit into some nice box.
For example, we might want to use a 'fair' pre-processing method on the data before training a classifier on it.
We may still be experimenting and only want part of the framework to execute,
or we may want to do hyper-parameter optimization.
Whilst other frameworks can be modified to do these tasks,
you end up with hacked-together approaches that don't lend themselves to be built on in the future.
Because of this, we built EthicML, a fairness toolkit for researchers.
Features include:
- Support for multiple sensitive attributes
- Vision datasets
- Codebase typed with mypy
- Tested code
- Reproducible results
### Why not use XXX?
There are an increasing number of other options,
IBM's fair-360, Aequitas, EthicalML/XAI, Fairness-Comparison and others.
They're all great at what they do, they're just not right for us.
We will however be influenced by them.
Where appropriate, we even subsume some of these libraries.
## Installation
EthicML requires Python >= 3.8.
To install EthicML, just do
```
pip3 install ethicml
```
If you want to use the method by Agarwal et al., you have to explicitly install _all_ dependencies:
```
pip3 install 'ethicml[all]'
```
(The quotes are needed in `zsh` and will also work in `bash`.)
**Attention**: In order to use all features of EthicML, PyTorch needs to be installed separately.
We are not including PyTorch as a requirement of EthicML,
because there are many different versions for different systems.
## Documentation
The documentation can be found here: https://wearepal.ai/EthicML/
## Design Principles
```mermaid
flowchart LR
A(Datasets) -- load --> B(Data tuples);
B --> C[evaluate_models];
G(Algorithms) --> C;
C --> D(Metrics);
```
Keep things simple.
### The Triplet
Given that we're considering fairness, the base of the toolbox is the triplet {x, s, y}
- X - Features
- S - Sensitive Label
- Y - Class Label
__Developer note__: All methods must assume S and Y are multi-class.
We use a DataTuple class to contain the triplet
```python
triplet = DataTuple(x: pandas.DataFrame, s: pandas.DataFrame, y: pandas.DataFrame)
```
In addition, we have a variation: the TestTuple which contains the pair
```python
pair = TestTuple(x: pandas.DataFrame, s: pandas.DataFrame)
```
This is to reduce the risk of a user accidentally evaluating performance on their training set.
Using dataframes may be a little inefficient,
but given the amount of splicing on conditions that we're doing, it feels worth it.
### Separation of Methods
We purposefully keep pre, during and post algorithm methods separate. This is because they have different return types.
```python
pre_algorithm.run(train: DataTuple, test: TestTuple) # -> Tuple[DataTuple, TestTuple]
in_algorithm.run(train: DataTuple, test: TestTuple) # -> Prediction
post_algorithm.run(train_prediction: Prediction, train: DataTuple, test_prediction: Prediction, test: TestTuple) # -> Prediction
```
where `Prediction` holds a pandas.Series of the class label.
In the case of a "soft" output, `SoftPrediction` extends `Prediction` and provides a mapping from
"soft" to "hard" labels.
See the documentation for more details.
### General Rules of Thumb
- Mutable data structures are bad.
- At the very least, functions should be Typed.
- Readability > Efficiency.
- Warnings must be addressed.
- Always write tests first.
## Future Plans
The aim is to make EthicML operate on 2 levels.
1. We want a high-level API so that a user can define a new model or metric, then get publication-ready
results in just a couple of lines of code.
2. We understand that truly ground-breaking work sometimes involves tearing up the rulebook.
Therefore, we want to also expose a lower-level API so that a user can make use of as much, or little of the library
as is suitable for them.
We've built everything with this philosophy in mind, but acknowledge that we still have a way to go.
# Contributing
If you're interest in this research area, we'd love to have you aboard.
For more details check out [CONTRIBUTING.md](./CONTRIBUTING.md).
Whether your skills are in coding-up papers you've read, writing tutorials, or designing a logo, please reach out.
## Development
Install development dependencies with `pip install -e .[dev]`
To use the pre-commit hooks run `pre-commit install`
Raw data
{
"_id": null,
"home_page": "https://github.com/wearepal/EthicML",
"name": "EthicML",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.10,<3.13",
"maintainer_email": "",
"keywords": "ml,fairness",
"author": "PAL",
"author_email": "info@wearepal.ai",
"download_url": "https://files.pythonhosted.org/packages/db/43/6558499e29f6dcfc60e29f9a683f9430a801fbb85ca1db5ecc767c311a49/ethicml-1.3.0.tar.gz",
"platform": null,
"description": "# EthicML: A featureful framework for developing fair algorithms\n\n[](http://mypy-lang.org/)\n\n\n\n\nEthicML is a library for performing and assessing __algorithmic fairness__.\nUnlike other libraries, EthicML isn't an education tool, but rather a __researcher__'s toolkit.\n\nOther algorthimic fairness packages are useful, but given that we primarily do research,\na lot of the work we do doesn't fit into some nice box.\nFor example, we might want to use a 'fair' pre-processing method on the data before training a classifier on it.\nWe may still be experimenting and only want part of the framework to execute,\nor we may want to do hyper-parameter optimization.\nWhilst other frameworks can be modified to do these tasks,\nyou end up with hacked-together approaches that don't lend themselves to be built on in the future.\nBecause of this, we built EthicML, a fairness toolkit for researchers.\n\nFeatures include:\n- Support for multiple sensitive attributes\n- Vision datasets\n- Codebase typed with mypy\n- Tested code\n- Reproducible results\n\n### Why not use XXX?\n\nThere are an increasing number of other options,\nIBM's fair-360, Aequitas, EthicalML/XAI, Fairness-Comparison and others.\nThey're all great at what they do, they're just not right for us.\nWe will however be influenced by them.\nWhere appropriate, we even subsume some of these libraries.\n\n## Installation\n\nEthicML requires Python >= 3.8.\nTo install EthicML, just do\n```\npip3 install ethicml\n```\n\nIf you want to use the method by Agarwal et al., you have to explicitly install _all_ dependencies:\n```\npip3 install 'ethicml[all]'\n```\n(The quotes are needed in `zsh` and will also work in `bash`.)\n\n**Attention**: In order to use all features of EthicML, PyTorch needs to be installed separately.\nWe are not including PyTorch as a requirement of EthicML,\nbecause there are many different versions for different systems.\n\n## Documentation\n\nThe documentation can be found here: https://wearepal.ai/EthicML/\n\n## Design Principles\n\n```mermaid\nflowchart LR\n A(Datasets) -- load --> B(Data tuples);\n B --> C[evaluate_models];\n G(Algorithms) --> C;\n C --> D(Metrics);\n```\n\nKeep things simple.\n\n### The Triplet\n\nGiven that we're considering fairness, the base of the toolbox is the triplet {x, s, y}\n\n- X - Features\n- S - Sensitive Label\n- Y - Class Label\n\n__Developer note__: All methods must assume S and Y are multi-class.\n\nWe use a DataTuple class to contain the triplet\n\n```python\ntriplet = DataTuple(x: pandas.DataFrame, s: pandas.DataFrame, y: pandas.DataFrame)\n```\n\nIn addition, we have a variation: the TestTuple which contains the pair\n```python\npair = TestTuple(x: pandas.DataFrame, s: pandas.DataFrame)\n```\nThis is to reduce the risk of a user accidentally evaluating performance on their training set.\n\nUsing dataframes may be a little inefficient,\nbut given the amount of splicing on conditions that we're doing, it feels worth it.\n\n### Separation of Methods\n\nWe purposefully keep pre, during and post algorithm methods separate. This is because they have different return types.\n\n```python\npre_algorithm.run(train: DataTuple, test: TestTuple) # -> Tuple[DataTuple, TestTuple]\nin_algorithm.run(train: DataTuple, test: TestTuple) # -> Prediction\npost_algorithm.run(train_prediction: Prediction, train: DataTuple, test_prediction: Prediction, test: TestTuple) # -> Prediction\n```\nwhere `Prediction` holds a pandas.Series of the class label.\nIn the case of a \"soft\" output, `SoftPrediction` extends `Prediction` and provides a mapping from\n\"soft\" to \"hard\" labels.\nSee the documentation for more details.\n\n### General Rules of Thumb\n\n- Mutable data structures are bad.\n- At the very least, functions should be Typed.\n- Readability > Efficiency.\n- Warnings must be addressed.\n- Always write tests first.\n\n## Future Plans\n\nThe aim is to make EthicML operate on 2 levels.\n\n1. We want a high-level API so that a user can define a new model or metric, then get publication-ready\nresults in just a couple of lines of code.\n2. We understand that truly ground-breaking work sometimes involves tearing up the rulebook.\nTherefore, we want to also expose a lower-level API so that a user can make use of as much, or little of the library\nas is suitable for them.\n\nWe've built everything with this philosophy in mind, but acknowledge that we still have a way to go.\n\n# Contributing\n\nIf you're interest in this research area, we'd love to have you aboard.\nFor more details check out [CONTRIBUTING.md](./CONTRIBUTING.md).\nWhether your skills are in coding-up papers you've read, writing tutorials, or designing a logo, please reach out.\n\n## Development\nInstall development dependencies with `pip install -e .[dev]`\n\nTo use the pre-commit hooks run `pre-commit install`\n",
"bugtrack_url": null,
"license": "",
"summary": "EthicML is a library for performing and assessing algorithmic fairness. Unlike other libraries, EthicML isn't an education tool, but rather a researcher's toolkit.",
"version": "1.3.0",
"project_urls": {
"Homepage": "https://github.com/wearepal/EthicML",
"Repository": "https://github.com/wearepal/EthicML"
},
"split_keywords": [
"ml",
"fairness"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "ae98207e9776732175d262f38411d519347a820c066fa01cbc845e99aa909c84",
"md5": "2e2ef8eddc3e03cd6d0444677654b0c9",
"sha256": "5d6c4602890442968e30048a9eca46fbc030cde698cbe595710962b904e41c22"
},
"downloads": -1,
"filename": "ethicml-1.3.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "2e2ef8eddc3e03cd6d0444677654b0c9",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10,<3.13",
"size": 38041973,
"upload_time": "2023-11-11T13:12:40",
"upload_time_iso_8601": "2023-11-11T13:12:40.304853Z",
"url": "https://files.pythonhosted.org/packages/ae/98/207e9776732175d262f38411d519347a820c066fa01cbc845e99aa909c84/ethicml-1.3.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "db436558499e29f6dcfc60e29f9a683f9430a801fbb85ca1db5ecc767c311a49",
"md5": "b3fd20245c174527013e4b3b2310dd4b",
"sha256": "d10a56de3c629220c7ede9c2533308ed58414547331b917be2b5050134acd3b2"
},
"downloads": -1,
"filename": "ethicml-1.3.0.tar.gz",
"has_sig": false,
"md5_digest": "b3fd20245c174527013e4b3b2310dd4b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10,<3.13",
"size": 37557709,
"upload_time": "2023-11-11T13:12:59",
"upload_time_iso_8601": "2023-11-11T13:12:59.481440Z",
"url": "https://files.pythonhosted.org/packages/db/43/6558499e29f6dcfc60e29f9a683f9430a801fbb85ca1db5ecc767c311a49/ethicml-1.3.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-11-11 13:12:59",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "wearepal",
"github_project": "EthicML",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "ethicml"
}
