Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Add examples in documentation #9

Merged
merged 3 commits into from
Mar 7, 2024
Merged

Add examples in documentation #9

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
53e78d5
Merge branch 'master' into documentation
julianmendez Mar 7, 2024
7ff28ff
Add examples in documentation
julianmendez Mar 7, 2024
e6531c3
Add examples in documentation
julianmendez Mar 7, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
144 changes: 53 additions & 91 deletions docs/README.md
View file
Open in desktop
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
View file
Open in desktop
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
Loading