From f9a0b84254fb29bb71030f69cb688f70daf7e282 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jes=C3=BAs=20Enrique=20Rasc=C3=B3n?= <blograso@gmail.com>
Date: Wed, 28 May 2025 12:06:31 +0200
Subject: [PATCH 1/4] first attempt at map docs

---
 src/routes/transforms/map/+page.md | 98 ++++++++++++++++++++++++------
 src/routes/transforms/map/+page.ts |  8 +++
 2 files changed, 89 insertions(+), 17 deletions(-)
 create mode 100644 src/routes/transforms/map/+page.ts

diff --git a/src/routes/transforms/map/+page.md b/src/routes/transforms/map/+page.md
index 74bfb0eb..529387e6 100644
--- a/src/routes/transforms/map/+page.md
+++ b/src/routes/transforms/map/+page.md
@@ -2,26 +2,90 @@
 title: Map transform
 ---
 
+Mapping transformations apply a given function to every element in the input
+data.
+
+Currently, there are 3 mapping transforms available: cumsum, rank, and quantile.
+
+
+## Cumsum
+
+```svelte live
+<script>
+    import {
+        Plot,
+        Line,
+        RuleY,
+        mapY,
+        stackY
+    } from 'svelteplot';
+
+    import { page } from '$app/state';
+    let { aapl } = $derived(page.data.data);
+</script>
+
+<Plot>
+  <RuleY y={0} />
+  <Line {...mapY({ data: aapl, x: 'Date', y:'Volume' }, 'cumsum')}  />
+</Plot>
+```
+
+
+## Rank
+
 ```svelte live
 <script>
-    import { Plot, BarX, mapX } from 'svelteplot';
+    import {
+        Plot,
+        Line,
+        mapY,
+        mapX,
+        RectY,binX
+    } from 'svelteplot';
+
+    import { page } from '$app/state';
+    let { olympians } = $derived(page.data.data);
+
+    const sortedOlympians = [...olympians].sort((a, b) => b.gold - a.gold).slice(0, 30);
+</script>
+
+<Plot marginLeft={50} x={{ tickRotate: -45 }}>
+    <Line
+        {...mapY(
+            { data: sortedOlympians, x: 'name', y: 'gold' },
+            'rank'
+        )}
+    />
+</Plot>
+```
+
+## Quantile
+
+```svelte live
+<script>
+    import {
+        Plot,
+        Line,
+        mapY,
+        mapX,
+        RectY,binX
+    } from 'svelteplot';
+
+    import { page } from '$app/state';
+    let { olympians } = $derived(page.data.data);
+
+    const sortedOlympians = [...olympians].sort((a, b) => b.gold - a.gold).slice(0, 30);
 </script>
 
-<Plot y={{ type: 'band' }}>
-    <BarX
-        {...mapX(
-            {
-                data: [
-                    { x: 1, v: 1 },
-                    { x: 2, v: 2 },
-                    { x: 3, v: -1 },
-                    { x: 4, v: 4 },
-                    { x: 5, v: 5 }
-                ],
-                x: 'v',
-                y: 'x'
-            },
-            'cumsum'
-        )} />
+<Plot marginLeft={50} x={{ tickRotate: -45 }}>
+    <Line
+        {...mapY(
+            { data: sortedOlympians, x: 'name', y: 'gold' },
+            'quantile'
+        )}
+    />
 </Plot>
 ```
+
+
+## Map Reference
diff --git a/src/routes/transforms/map/+page.ts b/src/routes/transforms/map/+page.ts
new file mode 100644
index 00000000..b3941759
--- /dev/null
+++ b/src/routes/transforms/map/+page.ts
@@ -0,0 +1,8 @@
+import { loadDatasets } from '$lib/helpers/data.js';
+import type { PageLoad } from './$types.js';
+
+export const load: PageLoad = async ({ fetch }) => {
+	return {
+		data: await loadDatasets(['aapl', 'olympians'], fetch)
+	};
+};

From e67134a65e4f82036c85ad5c8f0bd697314a6a60 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jes=C3=BAs=20Enrique=20Rasc=C3=B3n?= <blograso@gmail.com>
Date: Wed, 28 May 2025 20:52:58 +0200
Subject: [PATCH 2/4] more explainers

---
 src/routes/transforms/map/+page.md | 95 ++++++++++++++++++++++++++----
 src/routes/transforms/map/+page.ts |  2 +-
 2 files changed, 85 insertions(+), 12 deletions(-)

diff --git a/src/routes/transforms/map/+page.md b/src/routes/transforms/map/+page.md
index 529387e6..67e229df 100644
--- a/src/routes/transforms/map/+page.md
+++ b/src/routes/transforms/map/+page.md
@@ -10,7 +10,11 @@ Currently, there are 3 mapping transforms available: cumsum, rank, and quantile.
 
 ## Cumsum
 
-```svelte live
+The `cumsum` expression stands for Cumulative Sum. It represents how your data
+stacks up and changes. At any given point, you get the total sum of all previous
+data points.
+
+```svelte
 <script>
     import {
         Plot,
@@ -30,35 +34,104 @@ Currently, there are 3 mapping transforms available: cumsum, rank, and quantile.
 </Plot>
 ```
 
+Here we have the stocks data for Apple, plotted over time, with the cumulative
+sum mapping of the Volume. We can see how the volume increases overtime. Any
+sudden jumps in the Volume of Apple stocks would be very clear and visible in
+this kind of chart.
 
 ## Rank
 
+The `rank` function assigns a 0-based index to each datapoint had the data been
+sorted. Essentially it tells you where the datapoint lies within your whole
+dataset, for the provided property.
+
+
 ```svelte live
 <script>
     import {
         Plot,
         Line,
+        RuleY,
         mapY,
-        mapX,
-        RectY,binX
+        stackY
     } from 'svelteplot';
 
     import { page } from '$app/state';
-    let { olympians } = $derived(page.data.data);
+    let { cars } = $derived(page.data.data);
+
+    let sortedCars = [...cars].sort((a, b) => a["0-60 mph (s)"] - b["0-60 mph (s)"]).slice(0, 10);
 
-    const sortedOlympians = [...olympians].sort((a, b) => b.gold - a.gold).slice(0, 30);
 </script>
 
 <Plot marginLeft={50} x={{ tickRotate: -45 }}>
-    <Line
-        {...mapY(
-            { data: sortedOlympians, x: 'name', y: 'gold' },
-            'rank'
-        )}
-    />
+  <RuleY y={0} />
+  <Line {...mapY({ data:sortedCars, x: 'model', y:'0-60 mph (s)' }, 'rank')}  />
 </Plot>
 ```
 
+```svelte
+<script>
+    import {
+        Plot,
+        Line,
+        RuleY,
+        mapY,
+        stackY
+    } from 'svelteplot';
+
+    import { page } from '$app/state';
+    let { cars } = $derived(page.data.data);
+
+    let sortedCars = [...cars].sort((a, b) => a["0-60 mph (s)"] - b["0-60 mph (s)"]).slice(0, 10);
+
+</script>
+
+<Plot marginLeft={50} x={{ tickRotate: -45 }}>
+  <RuleY y={0} />
+  <Line {...mapY({ data:sortedCars, x: 'model', y:'0-60 mph (s)' }, 'rank')}  />
+</Plot>
+```
+
+
+Here, we are visualizing the top 10 fastest cars, and their ranking. As you can
+see, the Y axis does not output the actual seconds to reach 60mph, but rather answers the question "in what
+position does each car end up?".
+
+Sorting the cars before passing them to Plot is important. It's not necessary.
+The rank function just assigns a number to each datapoint based on the position
+it would occupy with the property provided (in this case, `"0-60 mph (s)"`). Had
+we not sorted the array, the visualization would look like this:
+
+
+```svelte live
+<script>
+    import {
+        Plot,
+        Line,
+        RuleY,
+        mapY,
+        mapX,
+        stackY
+    } from 'svelteplot';
+
+    import { page } from '$app/state';
+    let { cars } = $derived(page.data.data);
+</script>
+
+<Plot x={{ tickRotate: -45 }}>
+  <RuleY y={0} />
+  <Line {...mapY({ data:[...cars].slice(0,10), x: 'model', y:'0-60 mph (s)' }, 'rank')}  />
+</Plot>
+```
+
+As we can see, here we don't sort the array. We are still taking just 10 cars.
+In this case, we see the ordering that was implicit from the dataset, which
+appears to be in alphabetical order (though it may not be).
+
+Now the line is jagged, showing what each car's position is with respect to this
+subset of 10 cars.
+
+
 ## Quantile
 
 ```svelte live
diff --git a/src/routes/transforms/map/+page.ts b/src/routes/transforms/map/+page.ts
index b3941759..a75ea383 100644
--- a/src/routes/transforms/map/+page.ts
+++ b/src/routes/transforms/map/+page.ts
@@ -3,6 +3,6 @@ import type { PageLoad } from './$types.js';
 
 export const load: PageLoad = async ({ fetch }) => {
 	return {
-		data: await loadDatasets(['aapl', 'olympians'], fetch)
+		data: await loadDatasets(['aapl', 'cars', 'olympians'], fetch)
 	};
 };

From 568e7c92ef0f02f4cb0f256eae2573fec5618b5b Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jes=C3=BAs=20Enrique=20Rasc=C3=B3n?= <blograso@gmail.com>
Date: Thu, 29 May 2025 10:31:04 +0200
Subject: [PATCH 3/4] fix wording and add live example

---
 src/routes/transforms/map/+page.md | 22 +++++++++++++++++++++-
 1 file changed, 21 insertions(+), 1 deletion(-)

diff --git a/src/routes/transforms/map/+page.md b/src/routes/transforms/map/+page.md
index 67e229df..0d275e86 100644
--- a/src/routes/transforms/map/+page.md
+++ b/src/routes/transforms/map/+page.md
@@ -14,6 +14,26 @@ The `cumsum` expression stands for Cumulative Sum. It represents how your data
 stacks up and changes. At any given point, you get the total sum of all previous
 data points.
 
+```svelte live
+<script>
+    import {
+        Plot,
+        Line,
+        RuleY,
+        mapY,
+        stackY
+    } from 'svelteplot';
+
+    import { page } from '$app/state';
+    let { aapl } = $derived(page.data.data);
+</script>
+
+<Plot>
+  <RuleY y={0} />
+  <Line {...mapY({ data: aapl, x: 'Date', y:'Volume' }, 'cumsum')}  />
+</Plot>
+```
+
 ```svelte
 <script>
     import {
@@ -97,7 +117,7 @@ Here, we are visualizing the top 10 fastest cars, and their ranking. As you can
 see, the Y axis does not output the actual seconds to reach 60mph, but rather answers the question "in what
 position does each car end up?".
 
-Sorting the cars before passing them to Plot is important. It's not necessary.
+Sorting the cars before passing them to Plot is important, though not strictly necessary.
 The rank function just assigns a number to each datapoint based on the position
 it would occupy with the property provided (in this case, `"0-60 mph (s)"`). Had
 we not sorted the array, the visualization would look like this:

From fe40eb3ba38148bc5a176eab571bcf2abb3574da Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jes=C3=BAs=20Enrique=20Rasc=C3=B3n?= <blograso@gmail.com>
Date: Thu, 29 May 2025 21:57:44 +0200
Subject: [PATCH 4/4] add qunatile

---
 src/routes/transforms/map/+page.md | 48 +++++++++++++++++++++++-------
 1 file changed, 38 insertions(+), 10 deletions(-)

diff --git a/src/routes/transforms/map/+page.md b/src/routes/transforms/map/+page.md
index 0d275e86..a2eba5ac 100644
--- a/src/routes/transforms/map/+page.md
+++ b/src/routes/transforms/map/+page.md
@@ -128,6 +128,7 @@ we not sorted the array, the visualization would look like this:
     import {
         Plot,
         Line,
+        BarY,
         RuleY,
         mapY,
         mapX,
@@ -154,29 +155,56 @@ subset of 10 cars.
 
 ## Quantile
 
+The `quantile` function effectively works the same as the `rank` function, but
+instead of being 0-based index, it outputs a number between 0 and 1, basically
+giving the proportion in which each element lies within the whole dataset. 
+
+The calculation is whatever each element rank has, divided by the total number
+of elements.
+
 ```svelte live
 <script>
     import {
         Plot,
         Line,
+        RuleY,
         mapY,
-        mapX,
-        RectY,binX
+        stackY
     } from 'svelteplot';
 
     import { page } from '$app/state';
-    let { olympians } = $derived(page.data.data);
+    let { cars } = $derived(page.data.data);
+
+    let sortedCars = [...cars].sort((a, b) => a["0-60 mph (s)"] - b["0-60 mph (s)"]).slice(0, 10);
 
-    const sortedOlympians = [...olympians].sort((a, b) => b.gold - a.gold).slice(0, 30);
 </script>
 
 <Plot marginLeft={50} x={{ tickRotate: -45 }}>
-    <Line
-        {...mapY(
-            { data: sortedOlympians, x: 'name', y: 'gold' },
-            'quantile'
-        )}
-    />
+  <RuleY y={0} />
+  <Line {...mapY({ data:sortedCars, x: 'model', y:'0-60 mph (s)' }, 'quantile')}  />
+</Plot>
+```
+
+```svelte
+<script>
+    import {
+        Plot,
+        Line,
+        RuleY,
+        mapY,
+        stackY
+    } from 'svelteplot';
+
+    import { page } from '$app/state';
+    let { cars } = $derived(page.data.data);
+
+    let sortedCars = [...cars].sort((a, b) => a["0-60 mph (s)"] - b["0-60 mph (s)"]).slice(0, 10);
+
+</script>
+
+<Plot marginLeft={50} x={{ tickRotate: -45 }}>
+  <RuleY y={0} />
+  <Line {...mapY({ data:sortedCars, x: 'model', y:'0-60 mph (s)' }, 'quantile')}  />
 </Plot>
 ```