migrate recoding benchmark to PLNK

this MR

• moves the last "recoding" benchmark to examples/benches/
• moves the README, which is now all alone, to examples/benches/
• adds a mention to examples/benches/README.md in README.md
• some minor improvements to the bench README

TODO

• find a way to plot the "recoding" results (thanks to !90 (merged))

scripts/plot/plot.py

@@ -4,36 +4,56 @@ import sys
 import matplotlib.pyplot as plt
 import argparse
 
+HELP = """## Example
+```nuon
+[
+    {
+        group: "Alice",
+        items: [
+            [ x, measurement, error ];
+            [ 1, 1143, 120 ],
+            [ 2, 1310, 248 ],
+            [ 4, 1609, 258 ],
+            [ 8, 1953, 343 ],
+            [ 16, 2145, 270 ],
+            [ 32, 3427, 301 ]
+        ],
+        style = {},  # optional, see section below
+    },
+    {
+        group: "Bob",
+        items: [
+            [ x, measurement, error ];
+            [ 1, 2388, 374 ],
+            [ 2, 2738, 355 ],
+            [ 4, 3191, 470 ],
+            [ 8, 3932, 671 ],
+            [ 16, 4571, 334 ],
+            [ 32, 4929, 1094 ]
+        ]
+        style = {},  # optional, see section below
+    },
+]
+```
+
+## Custom style
+any record inside the data can have an optional "style" specification.
+
+below is the full shape of that specification, where all of the keys are completely optional,
+default values have been chosen:
+```nuon
+{
+    color: null,  # see https://matplotlib.org/stable/users/explain/colors/colors.html
+    line: {
+        marker: "o",  # see https://matplotlib.org/stable/api/markers_api.html
+        type: null,  # see https://matplotlib.org/stable/gallery/lines_bars_and_markers/linestyles.html
+        width: null,  # just an integer
+    }
+    alpha: 0.3,  # a real number between 0 and 1
+}
+```"""
 
-# # Example
-# ```nuon
-# [
-#     {
-#         group: "Alice",
-#         items: [
-#             [ x, measurement, error ];
-#             [ 1, 1143, 120 ],
-#             [ 2, 1310, 248 ],
-#             [ 4, 1609, 258 ],
-#             [ 8, 1953, 343 ],
-#             [ 16, 2145, 270 ],
-#             [ 32, 3427, 301 ]
-#         ]
-#     },
-#     {
-#         group: "Bob",
-#         items: [
-#             [ x, measurement, error ];
-#             [ 1, 2388, 374 ],
-#             [ 2, 2738, 355 ],
-#             [ 4, 3191, 470 ],
-#             [ 8, 3932, 671 ],
-#             [ 16, 4571, 334 ],
-#             [ 32, 4929, 1094 ]
-#         ]
-#     },
-# ]
-# ```
+# see [`HELP`]
 def plot(
     data,
     title: str,
@@ -54,9 +74,26 @@ def plot(
         down = [y - z for (y, z) in  zip(ys, zs)]
         up = [y + z for (y, z) in zip(ys, zs)]
 
-        style = "dashed" if group["group"].endswith("-ark") else "solid"
-        ax.plot(xs, ys, label=group["group"], marker='o', linestyle=style)
-        ax.fill_between(xs, down, up, alpha=0.3)
+        style = {
+            "marker": 'o',
+            "linestyle": None,
+            "color": None,
+            "linewidth": None,
+        }
+        alpha = 0.3
+        if "style" in group:
+            custom_style = group["style"]
+            style["color"] = custom_style.get("color", None)
+            style["marker"] = custom_style.get("line", {}).get("marker", style["marker"])
+            style["linestyle"] = custom_style.get("line", {}).get("type", style["linestyle"])
+            style["linewidth"] = custom_style.get("line", {}).get("width", style["linewidth"])
+            alpha = custom_style.get("alpha", alpha)
+
+        ax.plot(xs, ys, label=group["group"], **style)
+        if style["color"] is None:
+            ax.fill_between(xs, down, up, alpha=alpha)
+        else:
+            ax.fill_between(xs, down, up, alpha=alpha, color=style["color"])
 
     ax.set_xlabel(x_label)
     ax.set_ylabel(y_label)
@@ -79,36 +116,11 @@ def plot(
 
 
 if __name__ == "__main__":
-    parser = argparse.ArgumentParser()
-    parser.add_argument("data", type=str, help="""
-        the actual data to show in a multibar plot, here is an example:
-        [
-            {
-                group: "Alice",
-                items: [
-                    [ x, measurement, error ];
-                    [ 1, 1143, 120 ],
-                    [ 2, 1310, 248 ],
-                    [ 4, 1609, 258 ],
-                    [ 8, 1953, 343 ],
-                    [ 16, 2145, 270 ],
-                    [ 32, 3427, 301 ]
-                ]
-            },
-            {
-                group: "Bob",
-                items: [
-                    [ x, measurement, error ];
-                    [ 1, 2388, 374 ],
-                    [ 2, 2738, 355 ],
-                    [ 4, 3191, 470 ],
-                    [ 8, 3932, 671 ],
-                    [ 16, 4571, 334 ],
-                    [ 32, 4929, 1094 ]
-                ]
-            },
-        ]
-                        """)
+    parser = argparse.ArgumentParser(
+        formatter_class=argparse.RawTextHelpFormatter
+    )
+    parser.add_argument("data", type=str, help=f"the actual data to show in a multibar plot\n\n{HELP}"
+)
     parser.add_argument("--title", "-t", type=str, help="the title of the plot")
     parser.add_argument("--x-label", "-x", type=str, help="the x label of the plot")
     parser.add_argument("--y-label", "-y", type=str, help="the y label of the plot")