docs: Update docs, examples, and spec types.

uwdata · Nov 21, 2024 · d0bf691 · d0bf691
1 parent 79259ca
commit d0bf691
Show file tree

Hide file tree

Showing 17 changed files with 635 additions and 265 deletions.
diff --git a/docs/api/spec/format.md b/docs/api/spec/format.md
@@ -154,7 +154,7 @@ The remaining top-level keys in the plot object should be attribute names.
       "data": { "from": "tableName", "filterBy": "$selection" },
       "x": "foo", // x-encode values of column "foo"
       "y": "bar", // y-encode values of column "bar"
-      "r": { "expr": "SQRT($areaParam)" }, // size based on an expression
+      "r": { "sql": "SQRT($areaParam)" }, // size based on an expression
       "fill": "$colorParam" // set fill color to a param value
     },
     { "select": "intervalXY", "as": "$selection" },
@@ -169,8 +169,10 @@ The remaining top-level keys in the plot object should be attribute names.
 Mark entries include a `mark` key whose value should be the mark type, a `data` key indicating the input data, and the remaining keys should be mark options such as encoding channels.
 Interactors are defined similarly, but using the `select` key.
 
-SQL expressions can be defined as objects with a single `expr` key.
+SQL expressions can be defined as objects with a single `sql` key.
 Param references (as in `"1 + $param"`) will be parsed and resolved.
+By default, param references evaluate to SQL literal values.
+To instead use a param to refer to a column name, use `$$` syntax: `"1 + $$param"`.
 
 ### Legends
 

diff --git a/docs/examples/symbols.md b/docs/examples/symbols.md
@@ -5,7 +5,7 @@
 
 # Symbol Plots
 
-Two scatter plots with `dot` marks: one with stroked symbols, the other filled.
+Two scatter plots with `dot` marks: one with stroked symbols, the other filled. Drop-down menus control which data table columns are plotted.
 
 <Example spec="/specs/yaml/symbols.yaml" />
 

diff --git a/docs/public/specs/esm/linear-regression-10m.js b/docs/public/specs/esm/linear-regression-10m.js
@@ -1,27 +1,45 @@
 import * as vg from "@uwdata/vgplot";
 
 await vg.coordinator().exec([
-  `CREATE TABLE IF NOT EXISTS flights10m AS SELECT GREATEST(-60, LEAST(ARR_DELAY, 180))::DOUBLE AS delay, DISTANCE AS distance, DEP_TIME AS time FROM 'https://idl.uw.edu/mosaic-datasets/data/flights-10m.parquet'`
+  `CREATE TABLE IF NOT EXISTS flights10m AS SELECT GREATEST(-60, LEAST(ARR_DELAY, 180))::DOUBLE AS delay, DISTANCE AS distance, DEP_TIME AS time FROM 'https://idl.uw.edu/mosaic-datasets/data/flights-10m.parquet'`,
+  `CREATE TABLE IF NOT EXISTS flights10p AS SELECT * FROM flights10m USING SAMPLE 10%`,
+  `CREATE TABLE IF NOT EXISTS flights5p AS SELECT * FROM flights10m USING SAMPLE 5%`,
+  `CREATE TABLE IF NOT EXISTS flights1p AS SELECT * FROM flights10m USING SAMPLE 1%`
 ]);
 
+const $data = vg.Param.value("flights10m");
 const $query = vg.Selection.intersect();
 
-export default vg.plot(
-  vg.raster(
-    vg.from("flights10m"),
-    {x: "time", y: "delay", pixelSize: 4, pad: 0, imageRendering: "pixelated"}
-  ),
-  vg.regressionY(
-    vg.from("flights10m"),
-    {x: "time", y: "delay", stroke: "gray"}
-  ),
-  vg.regressionY(
-    vg.from("flights10m", {filterBy: $query}),
-    {x: "time", y: "delay", stroke: "firebrick"}
-  ),
-  vg.intervalXY({as: $query, brush: {fillOpacity: 0, stroke: "currentColor"}}),
-  vg.xDomain([0, 24]),
-  vg.yDomain([-60, 180]),
-  vg.colorScale("symlog"),
-  vg.colorScheme("blues")
+export default vg.vconcat(
+  vg.menu({
+    label: "Sample",
+    as: $data,
+    options: [
+    {value: "flights10m", label: "Full Data"},
+    {value: "flights10p", label: "10% Sample"},
+    {value: "flights5p", label: "5% Sample"},
+    {value: "flights1p", label: "1% Sample"}
+  ]
+  }),
+  vg.vspace(10),
+  vg.plot(
+    vg.raster(
+      vg.from($data),
+      {x: "time", y: "delay", pixelSize: 4, pad: 0, imageRendering: "pixelated"}
+    ),
+    vg.regressionY(
+      vg.from($data),
+      {x: "time", y: "delay", stroke: "gray"}
+    ),
+    vg.regressionY(
+      vg.from($data, {filterBy: $query}),
+      {x: "time", y: "delay", stroke: "firebrick"}
+    ),
+    vg.intervalXY({as: $query, brush: {fillOpacity: 0, stroke: "currentColor"}}),
+    vg.xDomain([0, 24]),
+    vg.yDomain([-60, 180]),
+    vg.colorScale("symlog"),
+    vg.colorScheme("blues"),
+    vg.colorDomain(vg.Fixed)
+  )
 );
diff --git a/docs/public/specs/esm/symbols.js b/docs/public/specs/esm/symbols.js
@@ -4,14 +4,30 @@ await vg.coordinator().exec([
   vg.loadParquet("penguins", "data/penguins.parquet")
 ]);
 
+const $x = vg.Param.value("body_mass");
+const $y = vg.Param.value("flipper_length");
+
 export default vg.vconcat(
+  vg.hconcat(
+    vg.menu({
+      label: "Y",
+      options: ["body_mass", "flipper_length", "bill_depth", "bill_length"],
+      as: $y
+    }),
+    vg.menu({
+      label: "X",
+      options: ["body_mass", "flipper_length", "bill_depth", "bill_length"],
+      as: $x
+    })
+  ),
+  vg.vspace(10),
   vg.hconcat(
     vg.plot(
       vg.dot(
         vg.from("penguins"),
         {
-          x: "body_mass",
-          y: "flipper_length",
+          x: vg.column($x),
+          y: vg.column($y),
           stroke: "species",
           symbol: "species"
         }
@@ -28,12 +44,7 @@ export default vg.vconcat(
     vg.plot(
       vg.dot(
         vg.from("penguins"),
-        {
-          x: "body_mass",
-          y: "flipper_length",
-          fill: "species",
-          symbol: "species"
-        }
+        {x: vg.column($x), y: vg.column($y), fill: "species", symbol: "species"}
       ),
       vg.name("filled"),
       vg.grid(true),

diff --git a/docs/public/specs/json/linear-regression-10m.json b/docs/public/specs/json/linear-regression-10m.json
@@ -4,56 +4,93 @@
     "description": "A linear regression plot predicting flight arrival delay based on the time of departure, over 10 million flight records. Regression computation is performed in the database, with optimized selection updates using pre-aggregated materialized views. The area around a regression line shows a 95% confidence interval. Select a region to view regression results for a data subset.\n"
   },
   "data": {
-    "flights10m": "SELECT GREATEST(-60, LEAST(ARR_DELAY, 180))::DOUBLE AS delay, DISTANCE AS distance, DEP_TIME AS time FROM 'https://idl.uw.edu/mosaic-datasets/data/flights-10m.parquet'"
+    "flights10m": "SELECT GREATEST(-60, LEAST(ARR_DELAY, 180))::DOUBLE AS delay, DISTANCE AS distance, DEP_TIME AS time FROM 'https://idl.uw.edu/mosaic-datasets/data/flights-10m.parquet'",
+    "flights10p": "SELECT * FROM flights10m USING SAMPLE 10%",
+    "flights5p": "SELECT * FROM flights10m USING SAMPLE 5%",
+    "flights1p": "SELECT * FROM flights10m USING SAMPLE 1%"
   },
-  "plot": [
-    {
-      "mark": "raster",
-      "data": {
-        "from": "flights10m"
-      },
-      "x": "time",
-      "y": "delay",
-      "pixelSize": 4,
-      "pad": 0,
-      "imageRendering": "pixelated"
-    },
+  "params": {
+    "data": "flights10m"
+  },
+  "vconcat": [
     {
-      "mark": "regressionY",
-      "data": {
-        "from": "flights10m"
-      },
-      "x": "time",
-      "y": "delay",
-      "stroke": "gray"
+      "input": "menu",
+      "label": "Sample",
+      "as": "$data",
+      "options": [
+        {
+          "value": "flights10m",
+          "label": "Full Data"
+        },
+        {
+          "value": "flights10p",
+          "label": "10% Sample"
+        },
+        {
+          "value": "flights5p",
+          "label": "5% Sample"
+        },
+        {
+          "value": "flights1p",
+          "label": "1% Sample"
+        }
+      ]
     },
     {
-      "mark": "regressionY",
-      "data": {
-        "from": "flights10m",
-        "filterBy": "$query"
-      },
-      "x": "time",
-      "y": "delay",
-      "stroke": "firebrick"
+      "vspace": 10
     },
     {
-      "select": "intervalXY",
-      "as": "$query",
-      "brush": {
-        "fillOpacity": 0,
-        "stroke": "currentColor"
-      }
+      "plot": [
+        {
+          "mark": "raster",
+          "data": {
+            "from": "$data"
+          },
+          "x": "time",
+          "y": "delay",
+          "pixelSize": 4,
+          "pad": 0,
+          "imageRendering": "pixelated"
+        },
+        {
+          "mark": "regressionY",
+          "data": {
+            "from": "$data"
+          },
+          "x": "time",
+          "y": "delay",
+          "stroke": "gray"
+        },
+        {
+          "mark": "regressionY",
+          "data": {
+            "from": "$data",
+            "filterBy": "$query"
+          },
+          "x": "time",
+          "y": "delay",
+          "stroke": "firebrick"
+        },
+        {
+          "select": "intervalXY",
+          "as": "$query",
+          "brush": {
+            "fillOpacity": 0,
+            "stroke": "currentColor"
+          }
+        }
+      ],
+      "xDomain": [
+        0,
+        24
+      ],
+      "yDomain": [
+        -60,
+        180
+      ],
+      "colorScale": "symlog",
+      "colorScheme": "blues",
+      "colorDomain": "Fixed"
     }
-  ],
-  "xDomain": [
-    0,
-    24
-  ],
-  "yDomain": [
-    -60,
-    180
-  ],
-  "colorScale": "symlog",
-  "colorScheme": "blues"
+  ]
 }
diff --git a/docs/public/specs/json/symbols.json b/docs/public/specs/json/symbols.json
@@ -1,14 +1,47 @@
 {
   "meta": {
     "title": "Symbol Plots",
-    "description": "Two scatter plots with `dot` marks: one with stroked symbols, the other filled.\n"
+    "description": "Two scatter plots with `dot` marks: one with stroked symbols, the other filled. Drop-down menus control which data table columns are plotted.\n"
   },
   "data": {
     "penguins": {
       "file": "data/penguins.parquet"
     }
   },
+  "params": {
+    "x": "body_mass",
+    "y": "flipper_length"
+  },
   "vconcat": [
+    {
+      "hconcat": [
+        {
+          "input": "menu",
+          "label": "Y",
+          "options": [
+            "body_mass",
+            "flipper_length",
+            "bill_depth",
+            "bill_length"
+          ],
+          "as": "$y"
+        },
+        {
+          "input": "menu",
+          "label": "X",
+          "options": [
+            "body_mass",
+            "flipper_length",
+            "bill_depth",
+            "bill_length"
+          ],
+          "as": "$x"
+        }
+      ]
+    },
+    {
+      "vspace": 10
+    },
     {
       "hconcat": [
         {
@@ -19,8 +52,12 @@
               "data": {
                 "from": "penguins"
               },
-              "x": "body_mass",
-              "y": "flipper_length",
+              "x": {
+                "column": "$x"
+              },
+              "y": {
+                "column": "$y"
+              },
               "stroke": "species",
               "symbol": "species"
             }
@@ -49,8 +86,12 @@
               "data": {
                 "from": "penguins"
               },
-              "x": "body_mass",
-              "y": "flipper_length",
+              "x": {
+                "column": "$x"
+              },
+              "y": {
+                "column": "$y"
+              },
               "fill": "species",
               "symbol": "species"
             }