From 853f728c788b96abd490d4a4490169b142731c7c Mon Sep 17 00:00:00 2001 From: Julian Mendez Date: Thu, 7 Mar 2024 00:35:16 +0100 Subject: [PATCH] Update README.md --- docs/README.md | 162 ++++++++++++++++++++++++++++++------------------- 1 file changed, 101 insertions(+), 61 deletions(-) diff --git a/docs/README.md b/docs/README.md index 835c850..e65a37f 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,52 +1,50 @@ - -## Tiles +# [Tiles](https://julianmendez.github.io/tiles/) + +[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)][license] +[![build](https://github.com/julianmendez/tiles/workflows/Scala%20CI/badge.svg)][build-status] **Tiles** is a framework to create formal configurations of constraints. Its classes are -written in [Soda](https://julianmendez.github.io/soda) and grouped in packages translated to -[Scala](https://scala-lang.org). - -The fairness tiles are defined in -[package tile]( -https://github.com/julianmendez/tiles/tree/master/core/src/main/scala/soda/tiles/fairness/tile -) [(Scala translation)]( -https://github.com/julianmendez/tiles/blob/master/core/src/main/scala/soda/tiles/fairness/tile/Package.scala -) and they use entities and other tools defined in -[package tool]( -https://github.com/julianmendez/tiles/tree/master/core/src/main/scala/soda/tiles/fairness/tool -) [(Scala translation)]( -https://github.com/julianmendez/tiles/blob/master/core/src/main/scala/soda/tiles/fairness/tool/Package.scala -). +written in [Soda][soda] and grouped in packages translated to +[Scala][scala]. + +The fairness tiles are defined in [package tile][package-tile] +[(Scala translation)][package-tile-scala] and they use entities and other tools defined in +[package tool][package-tool] [(Scala translation)][package-tool-scala]. ### Resource Allocation Scenarios These are some of the implemented fairness tiles for resource allocation scenarios: -| Tile | Class | -|:-----------------------------------------------------|:---------------------------------------------------------------------------------------------------------------------------------------------| -| all-actor *(a)* | [AllActorTile](https://github.com/julianmendez/tiles/blob/master/core/src/main/scala/soda/tiles/fairness/tile/AllActorTile.soda) | -| *(a)* received-σ-p *(m)* | [ReceivedSigmaPTile](https://github.com/julianmendez/tiles/blob/master/core/src/main/scala/soda/tiles/fairness/tile/ReceivedSigmaPTile.soda) | -| *(m)* all-equal *b* | [AllEqualTile](https://github.com/julianmendez/tiles/blob/master/core/src/main/scala/soda/tiles/fairness/tile/AllEqualTile.soda) | -| *(a)* needed-p *(m)* | [NeededPTile](https://github.com/julianmendez/tiles/blob/master/core/src/main/scala/soda/tiles/fairness/tile/NeededPTile.soda) | -| *(m0, m1)* all-at-least *b* | [AllAtLeastTile](https://github.com/julianmendez/tiles/blob/master/core/src/main/scala/soda/tiles/fairness/tile/AllAtLeastTile.soda) | -| equality *b* | [EqualityPipeline](https://github.com/julianmendez/tiles/blob/master/core/src/main/scala/soda/tiles/fairness/pipeline/EqualityPipeline.soda) | -| equity *b* | [EquityPipeline](https://github.com/julianmendez/tiles/blob/master/core/src/main/scala/soda/tiles/fairness/pipeline/EquityPipeline.soda) | +| 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] | -A specific scenario is given as an example in [ResourceAllocationScenarioExample](https://github.com/julianmendez/tiles/blob/master/core/src/test/scala/soda/tiles/fairness/pipeline/ResourceAllocationScenarioExample.soda). -This scenario is used to test the equality tile with [EqualityPipelineSpec](https://github.com/julianmendez/tiles/blob/master/core/src/test/scala/soda/tiles/fairness/pipeline/EqualityPipelineSpec.soda) and the equity tile with [EquityPipelineSpec](https://github.com/julianmendez/tiles/blob/master/core/src/test/scala/soda/tiles/fairness/pipeline/EquityPipelineSpec.soda). +A specific scenario is given as an example +in [ResourceAllocationScenarioExample][resource-allocation-scenario-example]. +This scenario is used to test the equality tile +with [EqualityPipelineSpec][equality-pipeline-spec] +and the equity tile +with [EquityPipelineSpec][equity-pipeline-spec]. #### Equality ```mermaid graph LR; -all-actor --- received-σ-p; -received-σ-p --- all-equal; +all-actor --> received; +received --> all-equal; ``` @@ -54,10 +52,10 @@ received-σ-p --- all-equal; ```mermaid graph LR; -all-actor --- received-σ-p; -all-actor --- needed-p; -received-σ-p --- all-at-least; -needed-p --- all-at-least; +all-actor --> received; +all-actor --> needed; +received --> all-at-least; +needed --> all-at-least; ``` @@ -65,34 +63,35 @@ needed-p --- all-at-least; These are some of the implemented fairness tiles for scoring scenarios: -| Tile | Class | -|:-------------------------------------------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------| -| all-actor *(a0, a1, a2)* | [AllActorTripleTile](https://github.com/julianmendez/tiles/blob/master/core/src/main/scala/soda/tiles/fairness/tile/AllActorTripleTile.soda) | -| *(a)* prediction-p *(m)* | [PredictionPTile](https://github.com/julianmendez/tiles/blob/master/core/src/main/scala/soda/tiles/fairness/tile/PredictionPTile.soda) | -| *(a)* result-p *(m)* | [ResultPTile](https://github.com/julianmendez/tiles/blob/master/core/src/main/scala/soda/tiles/fairness/tile/ResultPTile.soda) | -| *(m0, m1)* false-pos *(m)* | [FalsePosTile](https://github.com/julianmendez/tiles/blob/master/core/src/main/scala/soda/tiles/fairness/tile/FalsePosTile.soda) | -| *(a)* with-p *(m)* | [WithPTile](https://github.com/julianmendez/tiles/blob/master/core/src/main/scala/soda/tiles/fairness/tile/WithPTile.soda) | -| *(m0, m1)* correlation *m* | [CorrelationTile](https://github.com/julianmendez/tiles/blob/master/core/src/main/scala/soda/tiles/fairness/tile/CorrelationTile.soda) | -| *m* decision *b* | [DecisionTile](https://github.com/julianmendez/tiles/blob/master/core/src/main/scala/soda/tiles/fairness/tile/DecisionTile.soda) | -| unbiasedness *b* | [UnbiasednessPipeline](https://github.com/julianmendez/tiles/blob/master/core/src/main/scala/soda/tiles/fairness/pipeline/UnbiasednessPipeline.soda) | +| 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](https://github.com/julianmendez/tiles/blob/master/core/src/test/scala/soda/tiles/fairness/pipeline/ScoringScenarioExample.soda). -This scenario is used to test the scoring scenario tile (unbiasedness with respect to false positives) with -[UnbiasednessPipelineSpec](https://github.com/julianmendez/tiles/blob/master/core/src/test/scala/soda/tiles/fairness/pipeline/UnbiasednessPipelineSpec.soda). +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-p; -all-actor --- result-p; -all-actor --- with-p; -prediction-p --- false-pos; -result-p --- false-pos; -with-p --- correlation; -false-pos --- correlation; -correlation --- decision; +all-actor --> prediction; +all-actor --> result; +all-actor --> with; +prediction --> false-pos; +result --> false-pos; +with --> correlation; +false-pos --> correlation; +correlation --> decision; ``` @@ -101,13 +100,54 @@ correlation --- decision; The auxiliary tiles are used in the construction of other tiles. Some of the auxiliary tiles are: -| Tile | Class | -|:-------------------------------------------------------------------------|:--------------------------------------------------------------------------------------------------------------------------------------| -| *(a)* attribute-p *(m)* | [AttributePTile](https://github.com/julianmendez/tiles/blob/master/core/src/main/scala/soda/tiles/fairness/tile/AttributePTile.soda) | -| *(m0, m1)* σ-p *(m)* | [SigmaTile](https://github.com/julianmendez/tiles/blob/master/core/src/main/scala/soda/tiles/fairness/tile/FalsePosTile.soda) | -| *(α0) (α1)* zip *(α0, α1)* | [ZipTile](https://github.com/julianmendez/tiles/blob/master/core/src/main/scala/soda/tiles/fairness/tile/ZipTile.soda) | -| *(α0, α1)* unzip-0 *(α0)* | [UnzipPairFstTile](https://github.com/julianmendez/tiles/blob/master/core/src/main/scala/soda/tiles/fairness/tile/UnzipPairFstTile.soda) | -| *(α0, α1)* unzip-1 *(α1)* | [UnzipPairSndTile](https://github.com/julianmendez/tiles/blob/master/core/src/main/scala/soda/tiles/fairness/tile/UnzipPairSndTile.soda) | +| 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] | + + +## Author + +[Julian Alfredo Mendez][author] + +[author]: https://julianmendez.github.io +[license]: https://www.apache.org/licenses/LICENSE-2.0.txt +[build-status]: https://github.com/julianmendez/tiles/actions +[release-notes]: https://julianmendez.github.io/tiles/RELEASE-NOTES.html +[soda]: https://github.com/julianmendez/soda +[scala]: https://scala-lang.org +[package-tile]: https://github.com/julianmendez/tiles/tree/master/core/src/main/scala/soda/tiles/fairness/tile +[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