project.qmd

---
title: "Control the coordinate system with `PROJECT`"
---

The `PROJECT` clause defines the projection of the plot, that is, how abstract position 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

```ggsql
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 position 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 position aesthetics, e.g. `PROJECT fill, stroke TO polar` is not allowed.

### `TO`
```ggsql
TO <coordinate-system>
```

The `TO` clause is required and is followed by the name of the [coordinate system](../index.qmd#coordinate-systems). 
The coordinate system provides default names for the position aesthetics and is responsible for how to translate values mapped to these onto the plane defined by the screen or paper.

### `SETTING`
```ggsql
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](../index.qmd#coordinate-systems) 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 `angle`, `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 angle) an error is thrown