.docname {XY chart}
.include {docs}

The **`.xychart`** .docslink {quarkdown-stdlib/com.quarkdown.stdlib.module.Mermaid/xychart.html} function allows you to plot 2D line and bar charts in a pure, flexible Quarkdown fashion, through the power of [Mermaid diagrams](mermaid-diagrams.qd).

All parameters, except for `values`, are optional.

| Parameter | Description                                                                   | Accepts                                                                                                      |
|-----------|-------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------|
| `lines`   | Whether to draw lines (defaults to true).                                     | [Boolean](boolean.qd)                                                                                        |
| `bars`    | Whether to draw bars (defaults to false).                                     | [Boolean](boolean.qd)                                                                                        |
| `x`       | Label for the X axis.                                                         | String                                                                                                       |
| `xrange`  | Numerical range for the X axis. Can be open-ended. Incompatible with `xtags`. | [Range](range.qd)                                                                                            |
| `xtags`   | Categorical tags for the X axis. Incompatible with `xrange`.                  | [Iterable](iterable.qd)                                                                                      |
| `y`       | Label for the Y axis.                                                         | String                                                                                                       |
| `yrange`  | Range for the Y axis. Can be open-ended.                                      | [Range](range.qd)                                                                                            |
| `caption` | Caption. If present, the chart is [numbered](numbering.qd) as a figure.       | String                                                                                                       |
| `values`  | Y values to plot.                                                             | [Iterable](iterable.qd) of points (single line), or iterable of iterables of points (multiple lines)         |

## Axis ranges

`xrange` and `yrange` define the boundaries of the visible area of the chart through the usual `x..y` [Range](range.qd) syntax.

The range may also be open on either end, or both:
- If open on the left end, the range starts from the minimum value among the plotted points.
- If open on the right end, the range ends at the maximum value among the plotted points.

For instance, `..` (infinite) is the default range, which shows the area between the minimum and maximum values.

## Possible input sources

### From static list (single line)

You can represent `values` as a Markdown list, just like all iterables.

.examplemirror
    .xychart bars:{yes} x:{Months} y:{Revenue} yrange:{100..}
        - 250
        - 500
        - 350
        - 450
        - 400
        - 500
        - 600

### From static list (multiple lines)

In case of nested lists (iterable of iterables), multiple lines will be plotted:

.examplemirror
    .xychart x:{Months} y:{Revenue}
        - - 250
          - 500
          - 350
          - 450
          - 400

        - - 400
          - 150
          - 200
          - 400
          - 450

### From iterations

Quarkdown [loops](loops.qd) return an iterable containing the result of each iteration, making them a suitable input for `values`, especially in combination with [math](math.qd) functions.

.examplemirror
    .xychart
        .repeat {100}
            .1::pow {2}::divide {100}

        .repeat {100}
            .1::logn::multiply {10}

### From CSV/table

[Table manipulation](table-manipulation.qd) functions such as [`.tablecolumn`](table-manipulation.qd#retrieve-columns) can extract values from the columns of a table as iterables.

.examplemirror
    .xychart
        .tablecolumn {2}
            .csv {assets/sales.csv}

If you need to access multiple columns from the same table, consider calling `.tablecolumns` for efficiency, which returns a collection of columns. You can then perform any [`Iterable`](iterable.qd) operation on it.

.examplemirror {In the following example, the chart displays two lines: one for the second and one for the third column of the CSV. Additionally, the first column of the table is used as a set of categorical tags for the X axis.}
    .var {columns}
        .tablecolumns
            .csv {assets/sales.csv}

    .xychart xtags:{.columns::first} x:{Years} y:{Sales}
        .columns::second
        .columns::third