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 all commits
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
37 changes: 35 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,39 @@ 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 of the elements to layout, the scales, the values (the scaled channels as a key: array object), the dimensions, and the mark as this. It must return the 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