|
| 1 | +--- |
| 2 | +title: "Segment" |
| 3 | +--- |
| 4 | + |
| 5 | +> Layers are declared with the [`DRAW` clause](../clause/draw.qmd). Read the documentation for this clause for a thorough description of how to use it. |
| 6 | +
|
| 7 | +The segment layer is used to create line segments between two endpoints. If differs from [lines](line.qmd) and [paths](path.qmd) in that it connects just two points rather than many. Data is expected to be in a different shape, with 4 coordinates for the start (x, y) and end (xend, yend) points on a single row. |
| 8 | + |
| 9 | +## Aesthetics |
| 10 | +The following aesthetics are recognised by the segment layer. |
| 11 | + |
| 12 | +### Required |
| 13 | +* `x`: Position along the x-axis of the start point. |
| 14 | +* `y`: Position along the y-axis of the end point. |
| 15 | +* `xend`\*: Position along the x-axis of the end point. |
| 16 | +* `yend`\*: Position along the y-axis of the end point. |
| 17 | + |
| 18 | +\* Only one of `xend` and `yend` is required. |
| 19 | +If one is missing, it takes on the value of the start point. |
| 20 | + |
| 21 | +### Optional |
| 22 | +* `colour`/`stroke`: The colour of the line. |
| 23 | +* `opacity`: The opacity of the line. |
| 24 | +* `linewidth`: The width of the line. |
| 25 | +* `linetype`: The type of the line, i.e. the dashing pattern. |
| 26 | + |
| 27 | +## Settings |
| 28 | +The segment layer has no additional settings. |
| 29 | + |
| 30 | +## Data transformation |
| 31 | +The segment layer does not transform its data but passes it through unchanged. |
| 32 | + |
| 33 | +## Data transformation |
| 34 | + |
| 35 | +## Examples |
| 36 | + |
| 37 | +Segments are useful when you have known start and end points of the data. For example in a graph |
| 38 | + |
| 39 | +```{ggsql} |
| 40 | +WITH edges AS ( |
| 41 | + SELECT * FROM (VALUES |
| 42 | + (0, 0, 1, 1, 'A'), |
| 43 | + (1, 1, 2, 1, 'A'), |
| 44 | + (2, 1, 3, 0, 'A'), |
| 45 | + (0, 3, 1, 2, 'B'), |
| 46 | + (1, 2, 2, 2, 'B'), |
| 47 | + (2, 2, 3, 3, 'B'), |
| 48 | + (1, 1, 1, 2, 'C'), |
| 49 | + (2, 2, 2, 1, 'C') |
| 50 | + ) AS t(x, y, xend, yend, type) |
| 51 | +) |
| 52 | +VISUALISE x, y, xend, yend FROM edges |
| 53 | + DRAW segment MAPPING type AS stroke |
| 54 | +``` |
| 55 | + |
| 56 | +You can use segments as part of a lollipop chart by anchoring one of the ends to 0. |
| 57 | +Note that `xend` is missing and has taken up the value of `x`. |
| 58 | + |
| 59 | +```{ggsql} |
| 60 | +SELECT ROUND(bill_dep) AS bill_dep, COUNT(*) AS n |
| 61 | + FROM ggsql:penguins |
| 62 | + GROUP BY ROUND(bill_dep) |
| 63 | +
|
| 64 | +VISUALISE bill_dep AS x, n AS y |
| 65 | + DRAW segment MAPPING 0 AS yend |
| 66 | + DRAW point |
| 67 | +``` |
| 68 | + |
| 69 | +By overlaying a thick line on a thin line, you can create a candlestick chart. |
| 70 | + |
| 71 | +```{ggsql} |
| 72 | +SELECT |
| 73 | + FIRST(Date) AS date, |
| 74 | + FIRST(temp) AS open, |
| 75 | + LAST(temp) AS close, |
| 76 | + MAX(temp) AS high, |
| 77 | + MIN(temp) AS low, |
| 78 | + CASE |
| 79 | + WHEN FIRST(temp) > LAST(temp) THEN 'colder' |
| 80 | + ELSE 'warmer' |
| 81 | + END AS trend |
| 82 | +FROM ggsql:airquality |
| 83 | +GROUP BY WEEKOFYEAR(Date) |
| 84 | +
|
| 85 | +VISUALISE date AS x, trend AS colour |
| 86 | + DRAW segment |
| 87 | + MAPPING open AS y, close AS yend |
| 88 | + SETTING linewidth => 5 |
| 89 | + DRAW segment |
| 90 | + MAPPING low AS y, high AS yend |
| 91 | +``` |
0 commit comments