Skip to content

document layouts #713

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 4 commits into from
Closed

document layouts #713

Changes from 1 commit
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
d12bfe0
document layouts
Fil Jan 27, 2022
f7fdc77
no mutation
Fil Jan 27, 2022
bb97d16
Update README.md
Fil Jan 27, 2022
47d3bf1
remove custom layout example
Fil Jan 27, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
52 changes: 50 additions & 2 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -72,9 +72,9 @@ When drawing a single mark, you can call *mark*.**plot**(*options*) as shorthand
```js
Plot.barY(alphabet, {x: "letter", y: "frequency"}).plot()
```
### Layout options
### Geometry options

These options determine the overall layout of the plot; all are specified as numbers in pixels:
These options determine the overall geometry of the plot; all are specified as numbers in pixels:

* **marginTop** - the top margin
* **marginRight** - the right margin
Expand Down Expand Up @@ -1824,6 +1824,54 @@ Plot.stackX2({y: "year", x: "revenue", z: "format", fill: "group"})

Equivalent to [Plot.stackX](#plotstackxstack-options), except that the **x2** channel is returned as the **x** channel. This can be used, for example, to draw a line at the right edge of each stacked area.

## Layouts

A layout processes the transformed and scaled values of a mark before rendering. A layout might, for example, modify the marks’ positions to avoid occlusion. A layout operates in the representation space (such as pixels and colors, *i.e.* after scales have been applied) rather than data space.

### Dodge

The dodge layout can be applied to any mark that consumes *x* or *y*, such as the Dot, Image, Text and Vector marks.

#### Plot.dodgeY([*layoutOptions*, ]*options*)

```js
Plot.dodgeY({x: "date"})
```

If the marks are arranged along the *x* axis, the dodgeY layout piles them vertically, keeping their *x* position unchanged, and creating a *y* position that avoids overlapping.

#### Plot.dodgeX([*layoutOptions*, ]*options*)

```js
Plot.dodgeX({y: "value"})
```

Equivalent to Plot.dodgeY, but the piling is horizontal, keeping the marks’ *y* position unchanged, and creating an *x* position that avoids overlapping.

The dodge layouts accept the following layout options:

* **padding** — a number of pixels added to the radius of the mark to estimate its size
* **anchor** - the layout’s anchor: one of *middle*, *right*, and *left* (default) for dodgeX, and one of *middle*, *top*, and *bottom* (default) for dodgeY.

#### Custom layouts

When it *options* have a *layout* property, the layout function is called after the data has been faceted and scaled; it receives as inputs the index, scales, values (scaled channels) and dimensions, and the mark as this. It must return the (possibly modified) values.

For example, the following custom layout makes every fill color darker:

```js
Plot.dot(data, {
layout: (index, scales, values, dimension) => {
if (values.fill) {
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This example does nothing out of the box, because values.fill will always be undefined. Perhaps a more realistic example would be better? For example, maybe you could have a helper function…

function darker(key = "fill", amount = 1) {
  return (index, scales, {fill, ...values}, dimension) => {
    fill = fill.slice();
    for (const i of index) fill[i] = d3.rgb(fill[i]).darker(amount);
    return {...values, fill};
  };
}

And then

Plot.dot(penguins, {fill: "body_mass_g", layout: darker()})

I guess even this feels very contrived, since it’d be better to do this on the scale definition. Maybe we should remove the custom layouts section until we can think of a better motivating example?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

layout: contrasting on Plot.text could be short (and fix #540). A good contrasting color not as simple as checking a color's lightness, though, so an official implementation would likely diverge from such an example.

Removing this part for now.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Choosing a contrasting color sounds interesting and useful. Perhaps the fill input channel specifies the background color (e.g., fill: "imdb_rating" in the Simpsons example), and then the layout outputs a new fill channel where each output color is either light or dark depending on the lightness of the input? Something like:

Plot.text(simpsons, Plot.contrast({
  x: "season",
  y: "number_in_season",
  text: d => d.imdb_rating?.toFixed(1),
  title: "title",
  fill: "imdb_rating"
}))

Though, some sort of magic like this might be better…

Plot.text(simpsons, {
  x: "season",
  y: "number_in_season",
  text: d => d.imdb_rating?.toFixed(1),
  title: "title",
  fill: Plot.contrast("imdb_rating")
})

Which, I guess, would be like a per-channel layout.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'll open a new issue and prototype :)

for (const i of index) {
values.fill[i] = d3.rgb(values.fill[i]).darker();
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We shouldn’t use/recommend mutation.

}
}
return values;
}
})
```

## Curves

A curve defines how to turn a discrete representation of a line as a sequence of points [[*x₀*, *y₀*], [*x₁*, *y₁*], [*x₂*, *y₂*], …] into a continuous path; *i.e.*, how to interpolate between points. Curves are used by the [line](#line), [area](#area), and [link](#link) mark, and are implemented by [d3-shape](https://github.com/d3/d3-shape/blob/master/README.md#curves).
Expand Down