Skip to content

Commit 1206eed

Browse files
thomasp85thomasp85
authored
add proper example gallery (#194)
1 parent 671c583 commit 1206eed

15 files changed

Lines changed: 387 additions & 1 deletion

‎doc/_quarto.yml‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -47,7 +47,8 @@ website:
4747
href: syntax/clause/project.qmd
4848
- text: "`LABEL`"
4949
href: syntax/clause/label.qmd
50-
- examples.qmd
50+
- text: Gallery
51+
href: gallery/index.qmd
5152
- href: faq.qmd
5253
text: FAQ
5354
tools:

‎doc/gallery/examples/bar-chart.qmd‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
---
2+
title: "Bar Chart"
3+
description: "Categorical comparisons using bars"
4+
image: thumbnails/bar-chart.svg
5+
categories: [basic, bar]
6+
order: 3
7+
---
8+
9+
Bar charts display categorical data with rectangular bars. The height of each bar represents the value for that category.
10+
11+
## Code
12+
13+
```{ggsql}
14+
SELECT species, COUNT(*) as count FROM ggsql:penguins
15+
GROUP BY species
16+
VISUALISE species AS x, count AS y, species AS fill
17+
DRAW bar
18+
LABEL
19+
title => 'Penguin Count by Species',
20+
x => 'Species',
21+
y => 'Count'
22+
```
23+
24+
## Explanation
25+
26+
- The SQL query aggregates penguin counts by species
27+
- `species AS x` places species names on the x-axis
28+
- `count AS y` sets the bar height based on the count
29+
- `species AS fill` colors each bar by species
30+
- `DRAW bar` creates vertical bars
31+
32+
## Variations
33+
34+
### Horizontal Bars
35+
36+
Use `PROJECT y, x TO cartesian` to flip the axes for horizontal bars:
37+
38+
```{ggsql}
39+
SELECT species, COUNT(*) as count FROM ggsql:penguins
40+
GROUP BY species
41+
VISUALISE species AS x, count AS y, species AS fill
42+
DRAW bar
43+
PROJECT y, x TO cartesian
44+
LABEL
45+
title => 'Penguin Count by Species',
46+
x => 'Species',
47+
y => 'Count'
48+
```
49+
50+
### Auto-Count Bar Chart
51+
52+
When you don't specify a y aesthetic, ggsql automatically counts occurrences:
53+
54+
```{ggsql}
55+
SELECT species FROM ggsql:penguins
56+
VISUALISE species AS x
57+
DRAW bar
58+
LABEL
59+
title => 'Penguin Distribution',
60+
x => 'Species',
61+
y => 'Count'
62+
```

‎doc/gallery/examples/faceted.qmd‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
---
2+
title: "Faceted Plot"
3+
description: "Small multiples showing data split by category"
4+
image: thumbnails/faceted.svg
5+
categories: [faceted, advanced]
6+
order: 6
7+
---
8+
9+
Faceted plots (small multiples) split data into separate panels by one or more categorical variables. This makes it easy to compare patterns across groups.
10+
11+
## Code
12+
13+
```{ggsql}
14+
SELECT bill_len, bill_dep, species FROM ggsql:penguins
15+
VISUALISE bill_len AS x, bill_dep AS y
16+
DRAW point
17+
FACET species
18+
LABEL
19+
title => 'Bill Dimensions by Species',
20+
x => 'Bill Length (mm)',
21+
y => 'Bill Depth (mm)'
22+
```
23+
24+
## Explanation
25+
26+
- `FACET species` creates a separate panel for each penguin species
27+
- Each panel shows the same scatter plot, filtered to that species
28+
- This reveals species-specific patterns that might be hidden in a combined view
29+
30+
## Variations
31+
32+
### Grid Layout with Two Variables
33+
34+
Use `FACET rows BY cols` to create a grid layout:
35+
36+
```{ggsql}
37+
SELECT bill_len, bill_dep, species, island FROM ggsql:penguins
38+
VISUALISE bill_len AS x, bill_dep AS y
39+
DRAW point
40+
FACET species BY island
41+
LABEL
42+
title => 'Bill Dimensions by Species and Island',
43+
x => 'Bill Length (mm)',
44+
y => 'Bill Depth (mm)'
45+
```
46+
47+
### Free Scales
48+
49+
Allow each facet to have independent axis scales with `SETTING free`:
50+
51+
```{ggsql}
52+
SELECT bill_len, bill_dep, species FROM ggsql:penguins
53+
VISUALISE bill_len AS x, bill_dep AS y
54+
DRAW point
55+
FACET species SETTING free => 'y'
56+
LABEL
57+
title => 'Bill Dimensions (Free Y Scale)',
58+
x => 'Bill Length (mm)',
59+
y => 'Bill Depth (mm)'
60+
```

‎doc/gallery/examples/histogram.qmd‎

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
---
2+
title: "Histogram"
3+
description: "Distribution of a single numeric variable"
4+
image: thumbnails/histogram.svg
5+
categories: [statistical, distribution]
6+
order: 4
7+
---
8+
9+
Histograms show the distribution of a numeric variable by grouping values into bins and counting occurrences in each bin.
10+
11+
## Code
12+
13+
```{ggsql}
14+
SELECT Temp FROM ggsql:airquality
15+
VISUALISE Temp AS x
16+
DRAW histogram
17+
LABEL
18+
title => 'Temperature Distribution',
19+
x => 'Temperature (F)',
20+
y => 'Count'
21+
```
22+
23+
## Explanation
24+
25+
- `VISUALISE Temp AS x` specifies the variable to bin
26+
- `DRAW histogram` automatically computes bins and counts
27+
- No y mapping is needed - ggsql computes the count automatically
28+
29+
## Variations
30+
31+
### Custom Bin Count
32+
33+
Control the number of bins with `SETTING bins`:
34+
35+
```{ggsql}
36+
SELECT Temp FROM ggsql:airquality
37+
VISUALISE Temp AS x
38+
DRAW histogram
39+
SETTING bins => 15
40+
LABEL
41+
title => 'Temperature Distribution (15 bins)',
42+
x => 'Temperature (F)',
43+
y => 'Count'
44+
```
45+
46+
### Custom Bin Width
47+
48+
Set explicit bin width instead of count:
49+
50+
```{ggsql}
51+
SELECT Temp FROM ggsql:airquality
52+
VISUALISE Temp AS x
53+
DRAW histogram
54+
SETTING binwidth => 5
55+
LABEL
56+
title => 'Temperature Distribution (5 degree bins)',
57+
x => 'Temperature (F)',
58+
y => 'Count'
59+
```
60+
61+
### Density Instead of Count
62+
63+
Use `REMAPPING` to show density (proportion) instead of count:
64+
65+
```{ggsql}
66+
SELECT Temp FROM ggsql:airquality
67+
VISUALISE Temp AS x
68+
DRAW histogram
69+
REMAPPING density AS y
70+
LABEL
71+
title => 'Temperature Density',
72+
x => 'Temperature (F)',
73+
y => 'Density'
74+
```

‎doc/gallery/examples/line-chart.qmd‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
---
2+
title: "Line Chart"
3+
description: "Time series visualization with proper date scaling"
4+
image: thumbnails/line-chart.svg
5+
categories: [basic, line, time-series]
6+
order: 2
7+
---
8+
9+
Line charts are ideal for showing trends over time. The `SCALE x VIA date` clause ensures proper date formatting on the axis.
10+
11+
## Code
12+
13+
```{ggsql}
14+
SELECT Date, Temp FROM ggsql:airquality
15+
VISUALISE Date AS x, Temp AS y
16+
DRAW line
17+
SCALE x VIA date
18+
LABEL
19+
title => 'Daily Temperature',
20+
x => 'Date',
21+
y => 'Temperature (F)'
22+
```
23+
24+
## Explanation
25+
26+
- `SELECT ... FROM ggsql:airquality` queries the built-in air quality dataset
27+
- `VISUALISE Date AS x, Temp AS y` maps the date column to x and temperature to y
28+
- `DRAW line` connects data points with lines
29+
- `SCALE x VIA date` ensures the x-axis is formatted as dates with appropriate tick marks
30+
- `LABEL` provides descriptive titles for the chart and axes
31+
32+
## Variations
33+
34+
### Multiple Lines by Category
35+
36+
```{ggsql}
37+
SELECT Date, Temp, Month FROM ggsql:airquality
38+
VISUALISE Date AS x, Temp AS y, Month AS color
39+
DRAW line
40+
SCALE x VIA date
41+
LABEL
42+
title => 'Daily Temperature by Month',
43+
x => 'Date',
44+
y => 'Temperature (F)'
45+
```

‎doc/gallery/examples/multi-layer.qmd‎

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
---
2+
title: "Multi-Layer Plot"
3+
description: "Combining multiple geometric layers in one visualization"
4+
image: thumbnails/multi-layer.svg
5+
categories: [layers, advanced]
6+
order: 5
7+
---
8+
9+
Multi-layer plots combine different geometric elements (geoms) to create richer visualizations. Each `DRAW` clause adds a new layer.
10+
11+
## Code
12+
13+
```{ggsql}
14+
SELECT Date, Temp FROM ggsql:airquality
15+
VISUALISE Date AS x, Temp AS y
16+
DRAW line
17+
SETTING color => 'steelblue'
18+
DRAW point
19+
SETTING size => 4, color => 'darkblue'
20+
SCALE x VIA date
21+
LABEL
22+
title => 'Temperature with Line and Points',
23+
x => 'Date',
24+
y => 'Temperature (F)'
25+
```
26+
27+
## Explanation
28+
29+
- The first `DRAW line` creates a line connecting all points
30+
- The second `DRAW point` adds point markers at each data point
31+
- `SETTING` on each layer controls that layer's visual properties
32+
- Both layers share the same x and y mappings from `VISUALISE`
33+
34+
## Variations
35+
36+
### Different Aesthetics Per Layer
37+
38+
Each layer can have its own aesthetic mappings using `MAPPING`:
39+
40+
```{ggsql}
41+
SELECT Date, Temp, Ozone FROM ggsql:airquality
42+
VISUALISE Date AS x
43+
DRAW line
44+
MAPPING Temp AS y, 'Temperature' AS color
45+
DRAW line
46+
MAPPING Ozone AS y, 'Ozone' AS color
47+
SCALE x VIA date
48+
LABEL
49+
title => 'Temperature and Ozone Over Time',
50+
x => 'Date',
51+
y => 'Value'
52+
```
53+
54+
### Layers from Different Data Sources
55+
56+
Use `MAPPING ... FROM` to pull each layer from different CTEs:
57+
58+
```{ggsql}
59+
WITH temps AS (
60+
SELECT Date, Temp as value FROM ggsql:airquality
61+
),
62+
ozone AS (
63+
SELECT Date, Ozone as value FROM ggsql:airquality WHERE Ozone IS NOT NULL
64+
)
65+
VISUALISE
66+
DRAW line
67+
MAPPING Date AS x, value AS y, 'Temperature' AS color FROM temps
68+
DRAW point
69+
MAPPING Date AS x, value AS y, 'Ozone' AS color FROM ozone
70+
SETTING size => 3
71+
SCALE x VIA date
72+
LABEL
73+
title => 'Temperature vs Ozone',
74+
x => 'Date',
75+
y => 'Value'
76+
```

‎doc/gallery/examples/scatterplot.qmd‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
---
2+
title: "Scatter Plot"
3+
description: "Basic scatter plot mapping two numeric variables to position"
4+
image: thumbnails/scatterplot.svg
5+
categories: [basic, point]
6+
order: 1
7+
---
8+
9+
A scatter plot displays the relationship between two numeric variables by mapping them to x and y positions. This is one of the most fundamental visualization types for exploring correlations and patterns.
10+
11+
## Code
12+
13+
```{ggsql}
14+
VISUALISE bill_len AS x, bill_dep AS y FROM ggsql:penguins
15+
DRAW point
16+
LABEL
17+
title => 'Penguin Bill Dimensions',
18+
x => 'Bill Length (mm)',
19+
y => 'Bill Depth (mm)'
20+
```
21+
22+
## Explanation
23+
24+
- `VISUALISE ... FROM ggsql:penguins` loads the built-in penguins dataset
25+
- `bill_len AS x, bill_dep AS y` maps bill length to the x-axis and bill depth to the y-axis
26+
- `DRAW point` creates a scatter plot using points
27+
- `LABEL` adds descriptive axis labels and a title
28+
29+
## Variations
30+
31+
### With Color by Species
32+
33+
```{ggsql}
34+
VISUALISE bill_len AS x, bill_dep AS y, species AS color FROM ggsql:penguins
35+
DRAW point
36+
LABEL
37+
title => 'Penguin Bill Dimensions by Species',
38+
x => 'Bill Length (mm)',
39+
y => 'Bill Depth (mm)'
40+
```

‎doc/gallery/examples/thumbnails/bar-chart.svg‎

Lines changed: 1 addition & 0 deletions
Loading

‎doc/gallery/examples/thumbnails/faceted.svg‎

Lines changed: 1 addition & 0 deletions
Loading

0 commit comments

Comments
 (0)