Custom Graph Reference

A complete list of Geometries and Statistics available in Custom Graph. Click the help button (?) in the layer settings for details on each item.

Geometry

Geometry–aesthetic compatibility

Each geometry accepts a specific set of aesthetics — visual mappings such as position, color, and size. Mapping an unsupported aesthetic to a geometry has no effect.

R = required, ○ = optional (triggers additional behavior when present), • = supported.

• Required aesthetics must be mapped to a column or provided by a statistic.
• color vs fill: Bar and Tile use fill for their interior color, not color. Area accepts both — color for the outline and fill for the interior. Ribbon draws no outline; color sets its fill color, and Ribbon's fill is only used with a threshold color scale. Crossbar and Box Plot use fill for the rectangle interior and color for the lines (for Box Plot: box outline, whiskers, median line, and the points beyond the whiskers).
• stroke: Only Point supports stroke, which sets a separate outline color.
• shape on Box Plot splits the boxes by the mapped column's levels (like color and fill) and draws the points beyond the whiskers with distinct marker shapes. size applies only to the points beyond the whiskers.
• ymin / ymax: Line draws an interval band when both are present. Ribbon, Errorbar, Crossbar, and Box Plot require them.
• q1 / q3: Box Plot needs quartiles for the top and bottom edges of the box. They cannot be mapped to a column, so the table lists no column for them, and only the Boxplot statistic supplies them.
• label: Text requires a mapped column. Label needs either aes.label or geom.defaults.labelContent.
• weight: This aesthetic has no column in the table because it does not affect how any Geometry is drawn. It maps a numeric column of frequency weights (how many observations each row stands for), and only statistics that support weights (ROC Curve) read it. The $n tooltip variable counts the rows used in the calculation and does not sum the weights.

Geometry–position compatibility

Each Geometry accepts a different set of position adjustments. See Position for what each position type means. Specifying a position type not listed below in tabs.addGraphLayer / tabs.updateGraphLayer returns an INVALID_INPUT error. When position is omitted, bar geom defaults to stack and other geoms default to identity.

MIDAS validates the position against the statistics as well as the geometry. The statistics listed in the following table can be combined only with the listed positions. Statistics not in the table accept every position. The set you can actually specify is the intersection with the geometry's allowed positions, and a position outside the intersection returns the same INVALID_INPUT error. stack and fill stack or normalize only the y values while the box and whisker values produced by the Boxplot stat stay unchanged, so the axis labeling would contradict the graph content. This is why the Boxplot stat cannot be combined with these positions.

Geometry and continuous color scales

A channel assigned a continuous color scale (sequential or diverging) does not split a layer into series. Line, Area, Step, and Ribbon each draw one path per layer, and the color becomes a gradient that varies along the X axis. In a flipped coordinate system it varies along the Y axis. Each data point places a gradient stop at its own position with the color resolved from that point's value, and the color is interpolated between points. Splitting the path by value would leave single-point paths for a column whose values differ from row to row, and a path with no length is not drawn.

To split paths by value, set the channel's scaleType to categorical.

Area's stack and fill positions stack one series onto another, which a continuous color scale does not provide. MIDAS draws such a layer with position identity and shows a warning above the graph. Bar draws one rectangle per point, so it stacks even with a continuous color scale.

Statistics

Statistics parameters

Each Statistic accepts a params object in the stats array passed to tabs.addGraphLayer / tabs.updateGraphLayer. The tables below list the parameter name, TypeScript type, default value, and a short description for every Statistic.

await window.midas.tabs.addGraphLayer('tab_001', {
  geom: { type: 'point' },
  stats: [
    { type: 'smooth', params: { method: 'loess', span: 0.5, interval: 'confidence' } }
  ],
  aes: { x: 'weight', y: 'mpg' }
});

In the type column: A | B means either value is accepted, T[] means an array of T, and a trailing ? on a field name (e.g. p?) marks it as optional. For the full behavior of each Statistic — assumptions, limits, and worked examples — see Custom Graph.

Identity (No transformation)

No parameters.

Bin (Histogram)

Time Bin (Datetime Histogram)

Smooth (Regression)

Count (Aggregation)

No parameters.

Density (KDE)

Summary (Aggregation)

Boxplot (Quartiles + Whiskers)

Survival (Kaplan-Meier)

ROC Curve

X Mean

X Median

Y Mean

Cumulative Sum (Pareto)

Sort (Pareto)

ECDF (Empirical CDF)

No parameters.

QQ (Normal Q-Q Plot)

Transform (Linear)

Palettes

Available values for paletteId in the color / fill aesthetic of layers[].scales. See Agent API for how to set palettes via API.

Categorical

For coloring by categorical variables. Use with scaleType: 'categorical'.

Default: midas-default.

Sequential

For continuous or ordinal variables. Use with scaleType: 'sequential'.

Also usable with scaleType: 'categorical' and 'threshold'. In those modes, one color per category or threshold region is sampled at equal intervals across the full palette range.

Default: blues. Viridis, Plasma, Inferno, and Magma are perceptually uniform and accommodate color vision diversity.

Diverging

For variables that diverge in both directions from a center value. Use with scaleType: 'diverging'.

Also usable with scaleType: 'threshold'. In that mode, one color per threshold region is sampled at equal intervals across the full palette range.

Default: rdbu.

scaleType and paletteId compatibility

With threshold, you can also specify colors directly via thresholdColors. When thresholdColors is set, it takes precedence; when omitted, one color per threshold region is sampled at equal intervals across the paletteId palette.

In the Graph Builder UI, switching the scale type automatically resets an incompatible palette to that scale type's default, and the graph keeps rendering. When an incompatible paletteId is set directly via the API, the graph fails to render at draw time.

Compatibility is checked against the effective scale type. When sequential / diverging is specified for a non-numeric column, the effective type becomes categorical, so a palette that matches the specified type in the table above can still fail. The error message explains how the type was resolved.

Fixed geometry settings

Aesthetics map a column to a visual attribute. A constant color, size, or opacity that does not depend on data belongs in geom.defaults, not in aes. In the Graph Builder UI these settings are in the layer's Geometry section.

• Fixed color: Set the line, point, or text color with color in geom.defaults; set the fill color of bar, area, tile, ribbon, crossbar, and box plot with fill (any CSS color string). The border color of tile is stroke. Crossbar and box plot also use stroke for their fixed line color (box outline, center line, and whiskers) — they have no color key in geom.defaults.
• Fixed size: Set size (point radius), strokeWidth (line width of line-drawing geometries), or fontSize (text, label) in geom.defaults. The tables in geom.defaults keys by geometry show which geometry has which key.
• Fixed opacity: Set alpha in geom.defaults, where 0 is fully transparent and 1 is fully opaque.

await window.midas.tabs.addGraphLayer(tabId, {
  geom: { type: 'point', defaults: { color: '#3366CC', size: 8, alpha: 0.5 } },
  aes: { x: 'weight', y: 'height' }
});

Passing a fixed value through aes (for example aes.color: { fixedColor: ... } or aes.size: 8) returns an INVALID_INPUT error. aes.* accepts a column name only.

geom.defaults keys by geometry

The keys accepted in geom.defaults differ by geometry. The tables below list each geometry's key names, types, ranges, default values, and descriptions. They are the same set as the items in the Geometry section of the layer settings in the Graph Builder UI, and a key you omit is drawn with its default value. The Range column is the range selectable in the Graph Builder UI.

Two structured settings are not in the tables. Contour's points is an array of { x, y } that makes up the curve and can be set only through the Agent API. Label's labelContent displays Statistics output as the label and is described in Using labels with statistics.

Point (Scatter)

Line

Bar

Area

Tile (Heatmap)

Step (Kaplan-Meier)

Ribbon (Confidence Band)

Error Bar

Crossbar

Box Plot

Vertical Line (Reference)

Horizontal Line (Reference)

Contour

Density 2D

Text (Label)

Label (Annotation)

Multiple layers with different fixed colors

Add each series as a separate layer with its own geom.defaults.color:

// Layer 1: actual values in blue
await window.midas.tabs.addGraphLayer(tabId, {
  geom: { type: 'line', defaults: { color: '#3366CC' } },
  aes: { x: 'date', y: 'actual' }
});

// Layer 2: predicted values in red
await window.midas.tabs.addGraphLayer(tabId, {
  geom: { type: 'line', defaults: { color: '#CC3333' } },
  aes: { x: 'date', y: 'predicted' }
});

Alternative: categorical color mapping

When data is in long format (one row per observation with a grouping column), map the grouping column to color instead of setting a fixed color. The palette assigns a distinct color to each group automatically.

// Long format: each row has a "series" column ("actual" or "predicted")
await window.midas.tabs.addGraphLayer(tabId, {
  geom: { type: 'line' },
  aes: { x: 'date', y: 'value', color: 'series' }
});

This approach works well when the number of series is dynamic or when you want consistent palette colors across multiple graphs.

Using labels with statistics

When a layer uses a statistic (Count, Summary, Bin, etc.), the stat replaces original column values with aggregated results. An aes.label column mapping cannot reference the original data after transformation. To display stat-computed values as labels, set geom.defaults.labelContent instead of aes.label.

labelContent references stat output variables with the $ prefix:

// Show mean values as labels on a summary chart
await window.midas.tabs.addGraphLayer(tabId, {
  geom: {
    type: 'label',
    defaults: {
      labelContent: { field: '$y', format: '.1f' }
    }
  },
  stats: [{ type: 'summary', params: { outputs: [{ fun: 'mean', to: 'y' }] } }],
  aes: { x: 'category', y: 'value' }
});

The labelContent object accepts these properties:

When the variable or column given in field has no value on any point of the layer, MIDAS draws none of that layer's labels and shows a warning above the graph. The warning names the column or variable you set and lists the variables that do have values on that layer. Aggregation leaves no original column values on a point, so referencing an original column from a layer that uses Statistics produces this state.

Coordinates

The coordinate system is a graph-level setting, specified in the coordinates field of tabs.configureGraph or reports.addGraph. Available values:

• 'cartesian' (default) — Standard Cartesian coordinates
• 'flipped' — Swaps X and Y axes. Useful for horizontal bar charts with long category labels

In the GUI, this corresponds to the Coordinate System section in Graph Builder. See Custom Graph: Flipping Axes for a visual example.

scales.x / scales.y in flipped coordinates

In flipped coordinates, aes.y data appears on the physical X axis (horizontal) and aes.x data on the physical Y axis (vertical). Every scales.x / scales.y setting (type, domain, ticks, zoomEnabled, title, and the rest) follows the data axis: scales.x controls the axis showing aes.x data (the vertical axis when flipped), and scales.y controls the axis showing aes.y data (the horizontal axis when flipped).

// Horizontal bar chart: aes.x mapped to categories, aes.y to values
await window.midas.tabs.configureGraph(tabId, {
  coordinates: 'flipped',
  scales: {
    x: { title: 'Product' },      // axis for aes.x data — vertical when flipped
    y: { title: 'Sales (USD)' }   // axis for aes.y data — horizontal when flipped
  }
});

The secondary Y axis (scales.y2) is disabled in flipped coordinates.

See also

• Advanced Graph Creation - Custom Graph usage and tutorial
• The Graph Builder Tab - Graph Builder basics

Also available as a Markdown file.