Layers¶
Known issues
Some chart features have known issues in the current release. See Known issues.
A layer is one set of shapes drawn in a chart's plot, such as bars, a line, or pie slices, computed from the rows of one datamodel table.
Overview¶
A chart starts with one layer for each part its chart type draws: 1 for a bar chart, 2 for a candlestick (the wick and the body). Adding layers draws several things in one plot, such as a line over bars. Each layer has:
- Its own datamodel and table: shown on the layer's "Data Model:" button as
<datamodel>:<table>. - Its own axes: a horizontal axis ("Lower Axis" or "Upper Axis") and a vertical axis ("Left Axis" or "Right Axis").
- A chart type and fields: the expressions, over the table's columns, that place and style each shape.
Legends, crosshairs, and annotations are also layers. See Legends and annotations and Crosshair.
Opening the layer editor¶
The layer editor, "Edit Rendering Layer", edits every layer of a chart's plot in one window.
- In Editor mode, select the chart's edit button, then Plot -> Edit Layers.
- Check that a window titled "Edit Rendering Layer" opened, with a "LAYERS" list on the left.
The window has:
- "LAYERS": one entry per layer, with "+ Add Layer" above them. Selecting an entry shows that layer.
- The layer's settings: "Data Model:", "AXES" ("Horizontal Axis:", "Vertical Axis:"), "STYLE OPTIONS", and "GENERAL" ("Border Color:", "Gradient Fill:", "Category Ordinal Positions:").
- "CHART TYPE": tiles for the layer's type, with "View Underlying" and "View Prepared", and the type's fields below them.
- The buttons: "Apply", "Reset", "Clear", "Cancel", and "OK".
Changes show on the chart as they are made. "Cancel" undoes every change made since the window opened, including layers added or deleted; "OK" keeps them. Closing the window with its "x" after "Apply" keeps what was applied.
A chart created by an agent over MCP is transient until it is committed, and until then its Plot submenu offers only "Remove". See Building charts over MCP.
Adding a layer¶
"+ Add Layer" adds a layer to the chart's plot and lists it in "LAYERS".
- In "Edit Rendering Layer", select "+ Add Layer".
-
Select the kind of layer:
Item Adds "2D Chart" ▸ A bar, line, area, or scatter layer "Radial" A pie, radial bar, or speedometer layer "Legend" A legend for the other layers "Annotation" ▸ A reference line, band, box, segment, text, or image -
For "2D Chart", choose the chart type in its submenu: "V Bar Chart", "H Bar Chart", "Line Chart", "Area Chart", or "Scatter Plot". The type can be changed later under "CHART TYPE".
- Fill in the layer's fields. See Layer fields.
- Select "OK".
- Check that the new layer is drawn on the chart and listed in "LAYERS".
The first layer of a kind is named after it: "Radial", "Legend", "Annotation".
Drawing a line over bars¶
A line layer's "X:" takes a number, so on a bar chart's category axis a text column there is refused on "OK" with "Error in Axis --> X: return type must be a number, not String". The "Advanced" form places each point within a category instead:
- In "Edit Rendering Layer", select "+ Add Layer", then 2D Chart -> Line Chart.
- Under "CHART TYPE", select the "Advanced" tile.
-
Set the fields:
Field Value "Order By:" The bars' category column, such as Symbol, so the line joins the points in the axis's alphabetical order"X:" .5, the middle of each category"Y:" The value to draw, such as Qty"X Groupings:" The bars' category column, such as Symbol"Line Size (px):" The line's width, such as 3"Line Color:" "Series" colors each segment from the palette -
The new layer is at the top of "LAYERS", behind the bars. Select its "⋮", then "Move Layer To Front".
- Select "OK".
- Check that the line has a point over the middle of each bar.
Reordering, renaming, copying, and deleting layers¶
Each entry in "LAYERS" has a "⋮" menu with these items:
| Item | What it does |
|---|---|
| "Rename Layer Id" | Opens "Rename Layer", whose "Layer Id:" field sets the layer's id |
| "Copy Layer" | Adds a copy of the layer at the top of "LAYERS", behind the other layers, named with the next free number, such as "Layer3" |
| "Delete Layer" | Deletes the layer, after "Are you sure you want to delete this layer?". Unavailable when the plot has only one layer |
| "Move Layer To Back", "Move Layer To Front" | Moves the layer to the top of "LAYERS", behind the others, or to the bottom, in front |
| "Move Layer Backward", "Move Layer Forward" | Moves the layer one place up "LAYERS", toward the back, or one place down, toward the front |
| "Export/Import Layer" | Shows the layer as JSON. Edit it and select "Apply" to change the layer. See the note on importing below |
A deleted layer disappears from the chart at once, and "Cancel" brings it back.
"Export/Import Layer" merges the JSON into the layer rather than replacing it: a field the JSON leaves out keeps its current value, so removing a field from the JSON does not clear it. Clear the field in the layer editor instead. A value the layer cannot use, such as "xAxis": "right", is dropped with no message, and the layer stays on its axis; check the layer's settings after "Apply".
The layers are drawn in list order, from the top of "LAYERS" to the bottom, so the layer at the bottom is drawn in front of the others. "+ Add Layer" and "Copy Layer" put the new layer at the top, behind the existing ones. To bring a layer in front, use "Move Layer To Front", then check the chart. On the layer at the top, "Move Layer To Back" and "Move Layer Backward" are unavailable; on the layer at the bottom, "Move Layer To Front" and "Move Layer Forward" are.
Changing a layer's chart type¶
The "CHART TYPE" tiles change what the layer draws, keeping its fields where the types share them.
| Layer | Tiles |
|---|---|
| 2D | "Advanced", "V Bar", "H Bar", "Scatter", "Line", "Area" |
| Radial | "Advanced", "Pie", "Bar", "Speedometer" |
Each type except "Advanced" shows a short form with only the fields it uses. "Advanced" shows every field.
Layer fields¶
A layer's fields are expressions evaluated for each row of its table. Most hold a column name or a formula over columns, such as sum(Qty); some hold a quoted constant, such as "square".
The short forms group their fields under headings. A bar layer's headings are:
| Heading | Fields |
|---|---|
| "AXIS" | "X:", "Y:" |
| "MARKERS" | "Shape:" (default "square"), "Color:" (default "Series", __series_num) |
| "DATA" | "Where:", "Hover Over:" |
A scatter layer adds "Marker Size(px):", which defaults to 3, so the markers are small until it is raised. Its "DATA" heading also has "Group By:" and "Order By:".
The "Advanced" form groups every field under "Axis", "Labels", "Markers", "Marker Position Override", "Horizontal Stack Left & Right", "Vertical Stack Top & Bottom", "Lines", and "Area", with fields such as "X:", "Y:", "X Groupings:", "Label:", "Shape:", "Color:", "Width (px):", "Stack On:", and "Line Size (px):".
Filtering a layer's rows¶
"Where:" takes a condition, and the layer draws only the rows that meet it, such as Qty > 5. Compare values with ==, not =. A condition that leaves no rows draws nothing, and the chart's render stats then report "NO DATA" (see Troubleshooting).
Writing hover text¶
"Hover Over:" sets the text shown when the pointer is on a shape. It is an expression whose result is shown as HTML.
The bar, line, area, scatter, pie, radial bar, and speedometer types fill it in when the chart is created, such as "Symbol: "+Symbol+"<BR>sum ( Total Qty ): "+formatNumber(sum(TotalQty), "#.000", "") for a bar chart of sum(TotalQty) by Symbol. Templates leave it empty, except "Calendar", so a candlestick shows nothing on hover until it is written.
The "..." button next to the field lists the variables, functions, and operators that can be used in it. These rules apply:
- Join text with
+:"Open: " + Openshows the label followed by the value. - Break lines with
<br>:\nshows as a space. Other HTML works too, such as<b>...</b>for bold. - Format numbers with
formatNumber: a number joined as it is loses its trailing zeros (410.2);formatNumber(Open, "0.00", "")gives410.20. - Format dates with
formatDate:formatDate(Day, "EEE yyyy-MM-dd")shows the date in the user's time zone. Adding a time zone, as informatDate(Day, "yyyy-MM-dd", "UTC"), shows it in that zone instead. - Put the layer to read in front: where two layers draw at the same point, only the hover text of the layer in front is shown.
For example, for a candlestick's body layer:
The crosshair is an alternative that shows values without writing any hover text.
Pie and radial fields¶
Radial layers draw around a center: pie slices, radial bars, or a speedometer. The radial layer's own settings are "Flip X:", "Flip Y:", "Auto Min Value:", "Min Value:", "Auto Max Value:", and "Max Value:".
A pie layer's form shows:
| Heading | Fields |
|---|---|
| "DATA SERIES" | "Data:", "Data Label:", "Order By:", "Hover over:" |
| "COLOR" | "Color:" (default "Series", __row_num) |
| "ANGLE STACK" | "Maximum Angle:", "Minimum Angle:" |
| "RADIUS (OPTIONAL)" | "Outer Radius:" (default 1), "Inner Radius:" (default 0) |
| "SLICE LABELS" | "Label Position:" (default "leader"), "Label Size:" (default 12), and other label fields |
The "Advanced" form, which the "Donut" template uses, shows the same values under "Angle Stack" as "Stack On:", the pie form's "Data:", with "Stack Min (const):" and "Stack Max (const):".
The angle fields are swapped: "Maximum Angle:" holds the angle the pie starts at and "Minimum Angle:" the angle it ends at, so a new pie shows "Maximum Angle:" 0 and "Minimum Angle:" 360. Enter the start angle in "Maximum Angle:".
"Inner Radius:" shows only when "Auto Min Value:" is unticked. With it ticked, the default, a pie with "Inner Radius:" 0.55 still draws as a full pie; untick it, leaving "Min Value:" 0.0, and the pie draws as a ring.
Marker width is in pixels on 2D layers ("Width (px):") and in degrees on radial layers ("Width (°):").
The radial layer's style options include "Start Angle(degees):" and "End Angle(degees):", spelled as shown.
Color modes¶
Each color field, such as a marker's "Color:", has a mode chosen from a list beside it:
| Mode | Colors each shape |
|---|---|
| "No Color" | Not at all |
| "Color" | With one color, such as #888888 |
| "Formula" | With the color an expression returns, such as (Close>=Open?"#26A69A":"#EF5350") |
| "Series" | By series, from the chart's "Partition Colors" |
| "Gradient" | Along the chart's "Gradient Colors", by a number |
| "Custom Series" | By series, from a comma-separated list of colors, such as #ff0000,#00ff00, used in turn and repeated. Its "..." button adds a color from the theme |
| "Custom Gradient" | Along a gradient of your own, by a number. Select a stop on the gradient bar to change its color |
"Partition Colors" and "Gradient Colors" are part of the chart's style. See Colors and style.
With "Gradient", the value field holds the number to color by, such as a column Rk. The default "Gradient Colors" run from red through the plot's background color to green, so shapes near the middle of the range almost disappear. For a numeric value that needs every point visible, set "Gradient Colors" in the chart's style, or use "Custom Gradient".
Making a layer selectable¶
A layer's shapes can be selected only when its "User Selectable:" field, under "Labels" in the "Advanced" form, is true. A chart created in the gallery leaves it empty, so nothing on it can be selected and its onSelected callback never runs. Set it to true to let users select bars or points by clicking them, or by dragging a box and choosing "Select these N item(s)". See Using charts and the AmiScript reference.