diff --git a/docs/README.md b/docs/README.md index e65a37f..e632c03 100644 --- a/docs/README.md +++ b/docs/README.md @@ -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 *(a)* | [AllActorTile][all-actor-tile] | -| *(a)* received *(m)* | [ReceivedSigmaPTile][received-sigma-p-tile] | -| *(m)* all-equal *b* | [AllEqualTile][all-equal-tile] | -| *(a)* needed *(m)* | [NeededPTile][needed-p-tile] | -| *(m0), (m1)* all-at-least *b* | [AllAtLeastTile][all-at-least-tile] | -| equality *b* | [EqualityPipeline][equality-pipeline] | -| equity *b* | [EquityPipeline][equity-pipeline] | +| Tile | Class | +|:----------------------------------------------------|:-----------------------------------------| +| all-actor *(a)* | [AllActorTile][AllActorTile] | +| *(a)* received *(m)* | [ReceivedSigmaPTile][ReceivedSigmaPTile] | +| *(m)* all-equal *b* | [AllEqualTile][AllEqualTile] | +| *(a)* needed *(m)* | [NeededPTile][NeededPTile] | +| *(m0), (m1)* all-at-least *b* | [AllAtLeastTile][AllAtLeastTile] | +| equality *b* | [EqualityPipeline][EqualityPipeline] | +| equity *b* | [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 *(a0), (a1), (a2)* | [AllActorTripleTile][all-actor-triple-tile] | -| *(a)* prediction *(m)* | [PredictionPTile][prediction-p-tile] | -| *(a)* result *(m)* | [ResultPTile][result-p-tile] | -| *(m0), (m1)* false-pos *(m)* | [FalsePosTile][false-pos-tile] | -| *(a)* with *(m)* | [WithPTile][with-p-tile] | -| *(m0), (m1)* correlation *m* | [CorrelationTile][correlation-tile] | -| *m* decision *b* | [DecisionTile][decision-tile] | -| unbiasedness *b* | [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 ``` @@ -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 | -|:-------------------------------------------------------------------------|:----------------------------------------| -| *(a)* attribute *(m)* | [AttributePTile][attribute-p-tile] | -| *(m0), (m1)* σ *(m)* | [SigmaTile][sigma-tile] | -| *(α0),(α1)* zip *(α0, α1)* | [ZipTile][zip-tile] | -| *(α0, α1)* unzip-0 *(α0)* | [UnzipPairFstTile][unzip-pair-fst-tile] | -| *(α0, α1)* unzip-1 *(α1)* | [UnzipPairSndTile][unzip-pair-snd-tile] | +| Tile | Class | +|:-------------------------------------------------------------------------|:-------------------------------------| +| *(a)* attribute *(m)* | [AttributePTile][AttributePTile] | +| *(m0), (m1)* σ *(m)* | [SigmaTile][SigmaTile] | +| *(α0),(α1)* zip *(α0, α1)* | [ZipTile][ZipTile] | +| *(α0, α1)* unzip-0 *(α0)* | [UnzipPairFstTile][UnzipPairFstTile] | +| *(α0, α1)* unzip-1 *(α1)* | [UnzipPairSndTile][UnzipPairSndTile] | + + +### More examples + +* [Child Care Subsidy][ccs-example] +* [Scoring Example][scoring-example] ## Author @@ -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 + + + +## Child Care Subsidy Example + +| Tile | Class | +|:----------------------------------------------------|:-----------------------------------------| +| all-actor *(a)* | [AllActorTile][AllActorTile] | +| *(a)* received *(m)* | [ReceivedSigmaPTile][ReceivedSigmaPTile] | +| *(m)* all-satisfy (p) *b* | [AllSatisfyPTile][AllSatisfyPTile] | +| *(m)* all-equal *b* | [AllEqualTile][AllEqualTile] | +| *(a)* p *(m)* | [AttributePTile][AttributePTile] | +| *(a)* p ? *(a)* | [FilterActorTile][FilterActorTile] | +| *(m0), (m1)* all-at-least *b* | [AllAtLeastTile][AllAtLeastTile] | +| *(m0), (m1)* f (m0,m1) *(m)* | [SigmaTile][SigmaTile] | +| *b0, b1* f (b0,b1) *b* | [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 + + + + diff --git a/docs/scoring_example.md b/docs/scoring_example.md new file mode 100644 index 0000000..e6e2fef --- /dev/null +++ b/docs/scoring_example.md @@ -0,0 +1,56 @@ + + + + + +### Scoring Scenario + +These are some of the implemented fairness tiles for scoring scenarios: + +| Tile | Class | +|:---------------------------------------------------|:---------------------------------------------| +| all-actor *(a0), (a1), (a2)* | [AllActorTripleTile][AllActorTripleTile] | +| *(a)* prediction *(m)* | [PredictionPTile][PredictionPTile] | +| *(a)* result *(m)* | [ResultPTile][ResultPTile] | +| *(m0), (m1)* false-pos *(m)* | [FalsePosTile][FalsePosTile] | +| *(a)* with *(m)* | [WithPTile][WithPTile] | +| *(m0), (m1)* correlation *m* | [CorrelationTile][CorrelationTile] | +| *m* decision *b* | [DecisionTile][DecisionTile] | +| unbiasedness *b* | [UnbiasednessPipeline][UnbiasednessPipeline] | + +A specific scenario is given as an example in +[ScoringScenarioExample][ScoringScenarioExample]. This scenario is used to test the +scoring scenario tile (unbiasedness with respect to falsepositives) with +[UnbiasednessPipelineSpec][UnbiasednessPipelineSpec]. + + +#### Unbiasedness + +```mermaid +graph LR + all-actor(all-actor) --> prediction + all-actor --> result + all-actor --> with-p + prediction(prediction) --> false-pos + result(result) --> false-pos + with-p(with) --> correlation + false-pos(false-pos) --> correlation + correlation(correlation) --> decision(decision) +``` + +[AllActorTripleTile]: https://github.com/julianmendez/tiles/blob/master/core/src/main/scala/soda/tiles/fairness/tile/AllActorTripleTile.soda +[PredictionPTile]: https://github.com/julianmendez/tiles/blob/master/core/src/main/scala/soda/tiles/fairness/tile/PredictionPTile.soda +[ResultPTile]: https://github.com/julianmendez/tiles/blob/master/core/src/main/scala/soda/tiles/fairness/tile/ResultPTile.soda +[FalsePosTile]: https://github.com/julianmendez/tiles/blob/master/core/src/main/scala/soda/tiles/fairness/tile/FalsePosTile.soda +[WithPTile]: https://github.com/julianmendez/tiles/blob/master/core/src/main/scala/soda/tiles/fairness/tile/WithPTile.soda +[CorrelationTile]: https://github.com/julianmendez/tiles/blob/master/core/src/main/scala/soda/tiles/fairness/tile/CorrelationTile.soda +[DecisionTile]: https://github.com/julianmendez/tiles/blob/master/core/src/main/scala/soda/tiles/fairness/tile/DecisionTile.soda +[UnbiasednessPipeline]: https://github.com/julianmendez/tiles/blob/master/core/src/main/scala/soda/tiles/fairness/pipeline/UnbiasednessPipeline.soda +[ScoringScenarioExample]: https://github.com/julianmendez/tiles/blob/master/core/src/test/scala/soda/tiles/fairness/pipeline/ScoringScenarioExample.soda +[UnbiasednessPipelineSpec]: https://github.com/julianmendez/tiles/blob/master/core/src/test/scala/soda/tiles/fairness/pipeline/UnbiasednessPipelineSpec.soda + + + +