Skip to content

Commit

Permalink
Merge branch 'master' into development
Browse files Browse the repository at this point in the history
  • Loading branch information
julianmendez committed Mar 8, 2024
2 parents 70bafaf + c6b6ac7 commit f312b37
Show file tree
Hide file tree
Showing 3 changed files with 200 additions and 91 deletions.
144 changes: 53 additions & 91 deletions docs/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,81 +17,45 @@ The fairness tiles are defined in [package tile][package-tile]
[package tool][package-tool] [(Scala translation)][package-tool-scala].


### Resource Allocation Scenarios
## Resource Allocation Scenarios

These are some of the implemented fairness tiles for resource allocation scenarios:

| Tile | Class |
|:----------------------------------------------------|:--------------------------------------------|
| all-actor <sub>*(a)*</sub> | [AllActorTile][all-actor-tile] |
| <sub>*(a)*</sub> received <sub>*(m)*</sub> | [ReceivedSigmaPTile][received-sigma-p-tile] |
| <sub>*(m)*</sub> all-equal <sub>*b*</sub> | [AllEqualTile][all-equal-tile] |
| <sub>*(a)*</sub> needed <sub>*(m)*</sub> | [NeededPTile][needed-p-tile] |
| <sub>*(m0), (m1)*</sub> all-at-least <sub>*b*</sub> | [AllAtLeastTile][all-at-least-tile] |
| equality <sub>*b*</sub> | [EqualityPipeline][equality-pipeline] |
| equity <sub>*b*</sub> | [EquityPipeline][equity-pipeline] |
| Tile | Class |
|:----------------------------------------------------|:-----------------------------------------|
| all-actor <sub>*(a)*</sub> | [AllActorTile][AllActorTile] |
| <sub>*(a)*</sub> received <sub>*(m)*</sub> | [ReceivedSigmaPTile][ReceivedSigmaPTile] |
| <sub>*(m)*</sub> all-equal <sub>*b*</sub> | [AllEqualTile][AllEqualTile] |
| <sub>*(a)*</sub> needed <sub>*(m)*</sub> | [NeededPTile][NeededPTile] |
| <sub>*(m0), (m1)*</sub> all-at-least <sub>*b*</sub> | [AllAtLeastTile][AllAtLeastTile] |
| equality <sub>*b*</sub> | [EqualityPipeline][EqualityPipeline] |
| equity <sub>*b*</sub> | [EquityPipeline][EquityPipeline] |

A specific scenario is given as an example
in [ResourceAllocationScenarioExample][resource-allocation-scenario-example].
in [ResourceAllocationScenarioExample][ResourceAllocationScenarioExample].
This scenario is used to test the equality tile
with [EqualityPipelineSpec][equality-pipeline-spec]
with [EqualityPipelineSpec][EqualityPipelineSpec]
and the equity tile
with [EquityPipelineSpec][equity-pipeline-spec].
with [EquityPipelineSpec][EquityPipelineSpec].


#### Equality
### Example of Equality

```mermaid
graph LR;
all-actor --> received;
received --> all-equal;
graph LR
all-actor(all-actor) --> received
received(received) --> all-equal(all-equal)
```


#### Equity
### Example of Equity

```mermaid
graph LR;
all-actor --> received;
all-actor --> needed;
received --> all-at-least;
needed --> all-at-least;
```


### Scoring Scenarios

These are some of the implemented fairness tiles for scoring scenarios:

| Tile | Class |
|:---------------------------------------------------|:-----------------------------------------------|
| all-actor <sub>*(a0), (a1), (a2)*</sub> | [AllActorTripleTile][all-actor-triple-tile] |
| <sub>*(a)*</sub> prediction <sub>*(m)*</sub> | [PredictionPTile][prediction-p-tile] |
| <sub>*(a)*</sub> result <sub>*(m)*</sub> | [ResultPTile][result-p-tile] |
| <sub>*(m0), (m1)*</sub> false-pos <sub>*(m)*</sub> | [FalsePosTile][false-pos-tile] |
| <sub>*(a)*</sub> with <sub>*(m)*</sub> | [WithPTile][with-p-tile] |
| <sub>*(m0), (m1)*</sub> correlation <sub>*m*</sub> | [CorrelationTile][correlation-tile] |
| <sub>*m*</sub> decision <sub>*b*</sub> | [DecisionTile][decision-tile] |
| unbiasedness <sub>*b*</sub> | [UnbiasednessPipeline][unbiassedness-pipeline] |

A specific scenario is given as an example in
[ScoringScenarioExample][scoring-scenario-example]. This scenario is used to test the
scoring scenario tile (unbiasedness with respect to falsepositives) with
[UnbiasednessPipelineSpec][unbiassedness-pipeline-spec].


#### Unbiasedness

```mermaid
graph LR;
all-actor --> prediction;
all-actor --> result;
all-actor --> with;
prediction --> false-pos;
result --> false-pos;
with --> correlation;
false-pos --> correlation;
correlation --> decision;
graph LR
all-actor(all-actor) --> received
all-actor --> needed
received(received) --> all-at-least(all-at-least)
needed(needed) --> all-at-least
```


Expand All @@ -100,13 +64,19 @@ correlation --> decision;
The auxiliary tiles are used in the construction of other tiles. Some of the auxiliary tiles
are:

| Tile | Class |
|:-------------------------------------------------------------------------|:----------------------------------------|
| <sub>*(a)*</sub> attribute <sub>*(m)*</sub> | [AttributePTile][attribute-p-tile] |
| <sub>*(m0), (m1)*</sub> &sigma; <sub>*(m)*</sub> | [SigmaTile][sigma-tile] |
| <sub>*(&alpha;0),(&alpha;1)*</sub> zip <sub>*(&alpha;0, &alpha;1)*</sub> | [ZipTile][zip-tile] |
| <sub>*(&alpha;0, &alpha;1)*</sub> unzip-0 <sub>*(&alpha;0)*</sub> | [UnzipPairFstTile][unzip-pair-fst-tile] |
| <sub>*(&alpha;0, &alpha;1)*</sub> unzip-1 <sub>*(&alpha;1)*</sub> | [UnzipPairSndTile][unzip-pair-snd-tile] |
| Tile | Class |
|:-------------------------------------------------------------------------|:-------------------------------------|
| <sub>*(a)*</sub> attribute <sub>*(m)*</sub> | [AttributePTile][AttributePTile] |
| <sub>*(m0), (m1)*</sub> &sigma; <sub>*(m)*</sub> | [SigmaTile][SigmaTile] |
| <sub>*(&alpha;0),(&alpha;1)*</sub> zip <sub>*(&alpha;0, &alpha;1)*</sub> | [ZipTile][ZipTile] |
| <sub>*(&alpha;0, &alpha;1)*</sub> unzip-0 <sub>*(&alpha;0)*</sub> | [UnzipPairFstTile][UnzipPairFstTile] |
| <sub>*(&alpha;0, &alpha;1)*</sub> unzip-1 <sub>*(&alpha;1)*</sub> | [UnzipPairSndTile][UnzipPairSndTile] |


### More examples

* [Child Care Subsidy][ccs-example]
* [Scoring Example][scoring-example]


## Author
Expand All @@ -123,31 +93,23 @@ are:
[package-tile-scala]: https://github.com/julianmendez/tiles/blob/master/core/src/main/scala/soda/tiles/fairness/tile/Package.scala
[package-tool]: https://github.com/julianmendez/tiles/tree/master/core/src/main/scala/soda/tiles/fairness/tool
[package-tool-scala]: https://github.com/julianmendez/tiles/blob/master/core/src/main/scala/soda/tiles/fairness/tool/Package.scala
[all-actor-tile]: https://github.com/julianmendez/tiles/blob/master/core/src/main/scala/soda/tiles/fairness/tile/AllActorTile.soda
[received-sigma-p-tile]: https://github.com/julianmendez/tiles/blob/master/core/src/main/scala/soda/tiles/fairness/tile/ReceivedSigmaPTile.soda
[all-equal-tile]: https://github.com/julianmendez/tiles/blob/master/core/src/main/scala/soda/tiles/fairness/tile/AllEqualTile.soda
[needed-p-tile]: https://github.com/julianmendez/tiles/blob/master/core/src/main/scala/soda/tiles/fairness/tile/NeededPTile.soda
[all-at-least-tile]: https://github.com/julianmendez/tiles/blob/master/core/src/main/scala/soda/tiles/fairness/tile/AllAtLeastTile.soda
[equality-pipeline]: https://github.com/julianmendez/tiles/blob/master/core/src/main/scala/soda/tiles/fairness/pipeline/EqualityPipeline.soda
[equity-pipeline]: https://github.com/julianmendez/tiles/blob/master/core/src/main/scala/soda/tiles/fairness/pipeline/EquityPipeline.soda
[all-actor-triple-tile]: https://github.com/julianmendez/tiles/blob/master/core/src/main/scala/soda/tiles/fairness/tile/AllActorTripleTile.soda
[prediction-p-tile]: https://github.com/julianmendez/tiles/blob/master/core/src/main/scala/soda/tiles/fairness/tile/PredictionPTile.soda
[result-p-tile]: https://github.com/julianmendez/tiles/blob/master/core/src/main/scala/soda/tiles/fairness/tile/ResultPTile.soda
[false-pos-tile]: https://github.com/julianmendez/tiles/blob/master/core/src/main/scala/soda/tiles/fairness/tile/FalsePosTile.soda
[with-p-tile]: https://github.com/julianmendez/tiles/blob/master/core/src/main/scala/soda/tiles/fairness/tile/WithPTile.soda
[correlation-tile]: https://github.com/julianmendez/tiles/blob/master/core/src/main/scala/soda/tiles/fairness/tile/CorrelationTile.soda
[decision-tile]: https://github.com/julianmendez/tiles/blob/master/core/src/main/scala/soda/tiles/fairness/tile/DecisionTile.soda
[unbiassedness-pipeline]: https://github.com/julianmendez/tiles/blob/master/core/src/main/scala/soda/tiles/fairness/pipeline/UnbiasednessPipeline.soda
[attribute-p-tile]: https://github.com/julianmendez/tiles/blob/master/core/src/main/scala/soda/tiles/fairness/tile/AttributePTile.soda
[sigma-tile]: https://github.com/julianmendez/tiles/blob/master/core/src/main/scala/soda/tiles/fairness/tile/SigmaTile.soda
[zip-tile]: https://github.com/julianmendez/tiles/blob/master/core/src/main/scala/soda/tiles/fairness/tile/ZipTile.soda
[unzip-pair-fst-tile]: https://github.com/julianmendez/tiles/blob/master/core/src/main/scala/soda/tiles/fairness/tile/UnzipPairFstTile.soda
[unzip-pair-snd-tile]: https://github.com/julianmendez/tiles/blob/master/core/src/main/scala/soda/tiles/fairness/tile/UnzipPairSndTile.soda
[resource-allocation-scenario-example]: https://github.com/julianmendez/tiles/blob/master/core/src/test/scala/soda/tiles/fairness/pipeline/ResourceAllocationScenarioExample.soda
[equality-pipeline-spec]: https://github.com/julianmendez/tiles/blob/master/core/src/test/scala/soda/tiles/fairness/pipeline/EqualityPipelineSpec.soda
[equity-pipeline-spec]: https://github.com/julianmendez/tiles/blob/master/core/src/test/scala/soda/tiles/fairness/pipeline/EquityPipelineSpec.soda
[scoring-scenario-example]: https://github.com/julianmendez/tiles/blob/master/core/src/test/scala/soda/tiles/fairness/pipeline/ScoringScenarioExample.soda
[unbiassedness-pipeline-spec]: https://github.com/julianmendez/tiles/blob/master/core/src/test/scala/soda/tiles/fairness/pipeline/UnbiasednessPipelineSpec.soda
[AllActorTile]: https://github.com/julianmendez/tiles/blob/master/core/src/main/scala/soda/tiles/fairness/tile/AllActorTile.soda
[ReceivedSigmaPTile]: https://github.com/julianmendez/tiles/blob/master/core/src/main/scala/soda/tiles/fairness/tile/ReceivedSigmaPTile.soda
[AllEqualTile]: https://github.com/julianmendez/tiles/blob/master/core/src/main/scala/soda/tiles/fairness/tile/AllEqualTile.soda
[NeededPTile]: https://github.com/julianmendez/tiles/blob/master/core/src/main/scala/soda/tiles/fairness/tile/NeededPTile.soda
[AllAtLeastTile]: https://github.com/julianmendez/tiles/blob/master/core/src/main/scala/soda/tiles/fairness/tile/AllAtLeastTile.soda
[EqualityPipeline]: https://github.com/julianmendez/tiles/blob/master/core/src/main/scala/soda/tiles/fairness/pipeline/EqualityPipeline.soda
[EquityPipeline]: https://github.com/julianmendez/tiles/blob/master/core/src/main/scala/soda/tiles/fairness/pipeline/EquityPipeline.soda
[AttributePTile]: https://github.com/julianmendez/tiles/blob/master/core/src/main/scala/soda/tiles/fairness/tile/AttributePTile.soda
[SigmaTile]: https://github.com/julianmendez/tiles/blob/master/core/src/main/scala/soda/tiles/fairness/tile/SigmaTile.soda
[ZipTile]: https://github.com/julianmendez/tiles/blob/master/core/src/main/scala/soda/tiles/fairness/tile/ZipTile.soda
[UnzipPairFstTile]: https://github.com/julianmendez/tiles/blob/master/core/src/main/scala/soda/tiles/fairness/tile/UnzipPairFstTile.soda
[UnzipPairSndTile]: https://github.com/julianmendez/tiles/blob/master/core/src/main/scala/soda/tiles/fairness/tile/UnzipPairSndTile.soda
[ResourceAllocationScenarioExample]: https://github.com/julianmendez/tiles/blob/master/core/src/test/scala/soda/tiles/fairness/pipeline/ResourceAllocationScenarioExample.soda
[EqualityPipelineSpec]: https://github.com/julianmendez/tiles/blob/master/core/src/test/scala/soda/tiles/fairness/pipeline/EqualityPipelineSpec.soda
[EquityPipelineSpec]: https://github.com/julianmendez/tiles/blob/master/core/src/test/scala/soda/tiles/fairness/pipeline/EquityPipelineSpec.soda
[ccs-example]: ccs_example.html
[scoring-example]: scoring_example.html

<script>
window.mermaid.init(undefined, document.querySelectorAll('.language-mermaid'));
Expand Down
91 changes: 91 additions & 0 deletions docs/ccs_example.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,91 @@
<head>
<script src="https://cdnjs.cloudflare.com/ajax/libs/mermaid/9.4.3/mermaid.min.js"> </script>
</head>


## Child Care Subsidy Example

| Tile | Class |
|:----------------------------------------------------|:-----------------------------------------|
| all-actor <sub>*(a)*</sub> | [AllActorTile][AllActorTile] |
| <sub>*(a)*</sub> received <sub>*(m)*</sub> | [ReceivedSigmaPTile][ReceivedSigmaPTile] |
| <sub>*(m)*</sub> all-satisfy (p) <sub>*b*</sub> | [AllSatisfyPTile][AllSatisfyPTile] |
| <sub>*(m)*</sub> all-equal <sub>*b*</sub> | [AllEqualTile][AllEqualTile] |
| <sub>*(a)*</sub> p <sub>*(m)*</sub> | [AttributePTile][AttributePTile] |
| <sub>*(a)*</sub> p ? <sub>*(a)*</sub> | [FilterActorTile][FilterActorTile] |
| <sub>*(m0), (m1)*</sub> all-at-least <sub>*b*</sub> | [AllAtLeastTile][AllAtLeastTile] |
| <sub>*(m0), (m1)*</sub> f (m0,m1) <sub>*(m)*</sub> | [SigmaTile][SigmaTile] |
| <sub>*b0, b1*</sub> f (b0,b1) <sub>*b*</sub> | [CombineBooleanTile][CombineBooleanTile] |


### No Child Care Subsidy

This is the [No Subsidy Pipeline][CcsNoSubsidyPipeline].

```mermaid
graph LR
all-actor(all-actor) --> received
received(received) --> all-satisfy-0(all-satisfy m=0)
```


### Child Care Subsidy Per Child Pipeline

This is the [Per Child Pipeline][CcsPerChildPipeline].

```mermaid
graph LR
all-actor(all-actor) --> received
all-actor --> children
received(received) --> m0/m1
children(children) --> m0/m1
m0/m1(m0 / m1) --> all-equal(all-equal)
```


### Child Care Subsidy Per Family Pipeline

This is the [Per Family Pipeline][CcsPerFamilyPipeline].

```mermaid
graph LR
all-actor(all-actor) --> received
received(received) --> all-equal(all-equal)
```


### Child Card Subsidy to Single Guardian Pipeline

This is the [Single Guardian Pipeline][CcsSingleGuardianPipeline].

```mermaid
graph LR
all-actor(all-actor) --> adults-1
all-actor --> adults-2
adults-1(adults a0 = 1?) --> received-1
adults-2(adults a1 > 1?) --> received-0
received-1(received) --> all-equal
received-0(received) --> all-satisfy-0
all-equal(all-equal) --> and(and)
all-satisfy-0(all-satisfy m=0) --> and
```

[AllActorTile]: https://github.com/julianmendez/tiles/blob/master/core/src/main/scala/soda/tiles/fairness/tile/AllActorTile.soda
[ReceivedSigmaPTile]: https://github.com/julianmendez/tiles/blob/master/core/src/main/scala/soda/tiles/fairness/tile/ReceivedSigmaPTile.soda
[AllSatisfyPTile]: https://github.com/julianmendez/tiles/blob/master/core/src/main/scala/soda/tiles/fairness/tile/AllSatisfyPTile.soda
[AllEqualTile]: https://github.com/julianmendez/tiles/blob/master/core/src/main/scala/soda/tiles/fairness/tile/AllEqualTile.soda
[AttributePTile]: https://github.com/julianmendez/tiles/blob/master/core/src/main/scala/soda/tiles/fairness/tile/AttributePTile.soda
[FilterActorTile]: https://github.com/julianmendez/tiles/blob/master/core/src/main/scala/soda/tiles/fairness/tile/FilterActorTile.soda
[AllAtLeastTile]: https://github.com/julianmendez/tiles/blob/master/core/src/main/scala/soda/tiles/fairness/tile/AllAtLeastTile.soda
[SigmaTile]: https://github.com/julianmendez/tiles/blob/master/core/src/main/scala/soda/tiles/fairness/tile/SigmaTile.soda
[CombineBooleanTile]: https://github.com/julianmendez/tiles/blob/master/core/src/main/scala/soda/tiles/fairness/tile/CombineBooleanTile.soda
[CcsSingleGuardianPipeline]: https://github.com/julianmendez/tiles/blob/master/examples/src/main/scala/soda/tiles/fairness/example/childcaresubsidy/CcsSingleGuardianPipeline.soda
[CcsNoSubsidyPipeline]: https://github.com/julianmendez/tiles/blob/master/examples/src/main/scala/soda/tiles/fairness/example/childcaresubsidy/CcsNoSubsidyPipeline.soda
[CcsPerChildPipeline]: https://github.com/julianmendez/tiles/blob/master/examples/src/main/scala/soda/tiles/fairness/example/childcaresubsidy/CcsPerChildPipeline.soda
[CcsPerFamilyPipeline]: https://github.com/julianmendez/tiles/blob/master/examples/src/main/scala/soda/tiles/fairness/example/childcaresubsidy/CcsPerFamilyPipeline.soda

<script>
window.mermaid.init(undefined, document.querySelectorAll('.language-mermaid'));
</script>


Loading

0 comments on commit f312b37

Please sign in to comment.