Control the coordinate system with PROJECT

The PROJECT clause defines the projection of the plot, that is, how abstract positional aesthetics are translated (projected) onto the plane defined by the screen/paper where the plot is viewed on.

Clause syntax

The PROJECT syntax contains a number of subclauses

PROJECT <aesthetic>, ... TO <coordinate-system>
    SETTING <parameter> => <value>, ...

The comma-separated list of aesthetic names are optional but allows you to define the names of the positional aesthetics in the plot. If omitted, the default aesthetic names of the coordinate system is used. The order given matters as the first name is used for the primary aesthetic, the second name for the secondary aesthetic and so on. For instance, using PROJECT y, x TO cartesian will flip the plot as anything mapped to y will now relate to the horizontal axis, and anything mapped to x will relate to the vertical axis. Note that it is not allowed to use the name of already established aesthetics as positional aesthetics, e.g. PROJECT fill, stroke TO polar is not allowed.

TO

TO <coordinate-system>

The TO clause is required and is followed by the name of the coordinate system. The coordinate system provides default names for the positional aesthetics and is responsible for how to translate values mapped to these onto the plane defined by the screen or paper.

SETTING

SETTING <parameter> => <value>, ...

This clause behaves much like the SETTINGS clause in DRAW, in that it allows you to fine-tune specific behavior of the projection. The specific coordinate system defines it’s own valid settings. Consult the coord documentations to read more.

Coordinate system inference

If you do not provide a PROJECT clause then the coordinate system will be picked for you based on the mappings in your query. The logic is as follows

  • If x, y or any of their variants are mapped to, a Cartesian coordinate system is used
  • If theta, radius or any of their variants are mapped to, a polar coordinate system is used
  • If none of the above applies, the plot defaults to a Cartesian coordinate system
  • If multiple applies (e.g. mapping to both x and theta) an error is thrown