Visualization Types & Modifiers

Reference for the iXMaps .type() string: the four base types, the decision tree by data shape, and the complete modifier vocabulary.

Reference for the .type() string of an iXMaps layer: the base types, how to choose one by data shape, and the complete modifier vocabulary. .type() is step ③ of the four defining steps of a layer — see Layers & Themes for how it relates to .data(), .binding() and .style().

For the map context and basemaps see Map Setup; for color schemes and classification see Colors & Classification; for symbol sizing see Sizing & Scaling.

Visualization types

Type and style — two orthogonal dimensions

Every iXMaps layer is described by two independent specifications:

.type() — determines the form and method of the visualization: what geometric shape is used, how values are mapped to that shape, and which algorithm classifies or aggregates the data. Examples: bubbles sized by value, choropleth filled by class, flow lines between origin and destination.
.style() — defines appearance and numeric parameters: colors, opacities, size references, power curves, label formatting, scale-dependent visibility. Style is purely about how the chosen form looks and how its quantities are tuned.

Because the two are largely independent, swapping the chart type while keeping the style is often all it takes to explore a completely different representation of the same data. The sizing (normalsizevalue, scale, sizepow) and color (colorscheme, fillopacity) settings carry over unchanged, so the visual density and palette stay consistent across type changes.

// Start with sized bubbles:
.type("CHART|BUBBLE|SIZE|VALUES")
.style({ colorscheme: ["#0066cc"], normalsizevalue: "500000", scale: 1, showdata: "true" })

// Switch to a dot map — style unchanged:
.type("CHART|DOT")
.style({ colorscheme: ["#0066cc"], normalsizevalue: "500000", scale: 1, showdata: "true" })

// Or to a density grid — style unchanged:
.type("CHART|BUBBLE|SIZE|AGGREGATE")
.style({ colorscheme: ["#0066cc"], normalsizevalue: "500000", scale: 1, showdata: "true",
         gridwidth: "8px" })

The type string is a pipe-separated list of tokens — a base type followed by optional modifiers:

CHART | BUBBLE | SIZE | CATEGORICAL | GLOW | VALUES | NOLEGEND
  ↑        ↑      ↑         ↑          ↑       ↑         ↑
base   shape  sizing  coloring  effect  labels  visibility

The four base types

Every iXMaps layer starts with one of four base types. Everything else — classification method, chart shape, visual modifiers — is appended to one of these roots.

Base type	What it does
`FEATURE`	Renders geometry as-is: polygon fills, boundary lines, point markers. No data value required — used for base layers that provide geographic context.
`CHOROPLETH`	Colours polygon fills by data value. Draws no geometry of its own — requires a `FEATURE` layer under the same layer name to supply the polygons/lines (see The layer name is a join key). A value field is mapped through a colour scheme via a classification method.
`CHART`	Creates new SVG objects (bubbles, bars, pies, flow lines, …). A value field drives size, colour, or both.
`WMS`	Renders an external map image as a raster overlay — fetched live from an ArcGIS-style export/image endpoint (`.data({ server: url })`). Sized and positioned from the current map view, not from a style option; no data value or classification involved.

FEATURE is a structural layer — it gives the map geography. CHOROPLETH and CHART are data layers — they need a value field and a classification or sizing method to translate numbers into visual marks. WMS is neither: it’s an imagery layer, closer in spirit to a basemap than to a data visualization.

FEATURE actually draws a specific set of geometry types: Point, LineString, MultiLineString, Polygon, MultiPolygon, and an iXMaps-only Sphere (used for full-globe rendering under an orthographic projection). MultiPoint and GeometryCollection geometries are parsed but not drawn.

Positioning a CHART layer. A chart needs a map position for every record, and there are two ways to give it one, both through .binding({ lookup: ... }):

// (a) coordinates straight from the data — two pipe-separated fields, or one field holding a GeoJSON Point
.binding({ lookup: "lat_field|lon_field", value: "population" })
.type("CHART|BUBBLE|SIZE")

// (b) joined to a FEATURE layer's own shape, by id — same pattern as a CHOROPLETH join
.binding({ lookup: "iso2", value: "population" })   // same layer name as the FEATURE providing "iso2" ids
.type("CHART|BUBBLE|SIZE")

With a single lookup field, the chart’s position is the centroid of the matching FEATURE shape — draws no geometry of its own, same join mechanics as CHOROPLETH. With two pipe-separated fields (or a GeoJSON Point/MultiPoint value in one field), the position comes directly from the data, no FEATURE layer needed.

Classification method tokens

CHOROPLETH and CHART need one classification token that says how values are grouped into colour classes:

Token	Classes are built by
`EQUIDISTANT`	Equal-width intervals
`QUANTILE`	Equal feature count per class
`HEADTAIL`	Iterative mean split (heavy-tailed data) — the odd one out: ignores a `classes` count entirely, the data decides how many classes there are
`NATURAL`	Jenks natural breaks — see performance note for large datasets
`LOG`	Logarithmic intervals
`POW2` / `POW3`	Equal-width intervals in square-/cube-root space
`CATEGORICAL`	Discrete categories — requires the `values` style array (strings!)

How classes map to colours, explicit ranges, diverging scales and data-driven palettes: see Colors & Classification.

Choosing by data shape

Is your data...
│
├─ Points (lat / lon)?
│  ├─ Just locations?                     → CHART|DOT
│  ├─ Coloured by category?               → CHART|BUBBLE|CATEGORICAL
│  ├─ Sized by value?                     → CHART|BUBBLE|SIZE|VALUES
│  ├─ Density grid (circles)?             → CHART|BUBBLE|SIZE|AGGREGATE  + gridwidth:"5px"
│  ├─ Density grid (squares)?             → CHART|SYMBOL|GRIDSIZE|AGGREGATE|RECT|SUM|DOPACITY|VALUES
│  ├─ Sparklines per grid cell?           → CHART|SYMBOL|PLOT|LINES
│  ├─ Flows origin→destination?           → CHART|VECTOR|BEZIER|POINTER
│  └─ Stacked / grouped bars?             → CHART|BAR|STACKED
│
├─ Polygons (GeoJSON / TopoJSON)?
│  ├─ Boundaries only?                    → FEATURE
│  ├─ Colour by data (inline)?            → FEATURE|CHOROPLETH|QUANTILE
│  └─ Join external data to geometry?     → CHOROPLETH|QUANTILE  (NEVER add FEATURE)
│
└─ An external map image (basemap, imagery, another WMS-like service)?
   └─ Just an overlay, no data value?     → WMS

Type modifiers

Visual effect modifiers:

Modifier	Effect
`GLOW`	Glow halo around symbols
`VALUES`	Render value labels inside / near symbols
`VALUESBACKGROUND`	Coloured background box behind value text
`TEXTONLY`	Labels only, no symbol
`TEXTLEGEND`	Legend entry keeps its text label but drops the color swatch
`GRADIENT`	Gradient colour along flow lines (use `linecolor: ["#from","#to"]`)
`DASH`	Animated flowing dashes on flow lines
`NOSCALE`	Disable dynamic zoom scaling
`CLIPTOGEOBOUNDS`	Clip chart rendering to polygon boundary
`3D`	3D rendering for `BAR`, `PIE`, `DONUT`
`BOX`	Background box behind each chart; customise with `boxopacity`, `boxmargin`, `bordercolor`
`MOVABLE`	Charts become draggable on the map

Scale-bounding CLIPTOGEOBOUNDS

When a layer uses CLIPTOGEOBOUNDS, the optional clipupper / cliplower style properties restrict the geo-bounds clipping to a map-scale range — same "1:scale" syntax as chartupper / chartlower. They are read only when CLIPTOGEOBOUNDS is present in the type string; on a layer without it they have no effect.

Filtering / visibility modifiers:

Modifier	Effect
`SILENT`	Excludes from legend AND suppresses tooltips
`NOLEGEND`	Excludes from legend only (tooltips still work)
`SIMPLELEGEND`	Collapses each legend entry to one compact inline line (swatch + label) instead of the default two-line layout
`COMPACTLEGEND`	Currently renders identically to `SIMPLELEGEND` — no distinguishing behavior yet
`ZEROISNOTVALUE`	Suppress rendering where value ≤ 0
`NEGATIVEISVALUE`	Allow and render negative values
`ZEROISVALUE`	Treat zero as a valid value (opposite of `ZEROISNOTVALUE`)
`NOOUTLIER`	Remove extreme outliers from classification
`NONEGATIVE`	Suppress rendering where computed value ≤ 0 (used with `DIFFERENCE`)

Value computation modifiers (derive a single value from two piped fields "a|b"):

Modifier	Formula	Use case
`DIFFERENCE`	`b − a`	Change, net gain/loss
`FRACTION`	`a / b`	Share, ratio
`PERCENT`	`a / b × 100`	Percentage
`PERMILLE`	`a / b × 1000`	Per-mille rate
`RELATIVE`	`a / b × 100 − 100`	Relative change vs. base
`INVERT`	`100 − a / b × 100`	Inverse share
`PRODUCT`	`a × b`	Combined value

Bind two fields with |: .binding({ value: "field_a|field_b" }). The modifier determines how the pair is collapsed to one value for colour/size mapping.

Multi-field coloring modifiers (for multiple piped fields — one winner lends its color, versus blending all of them at once):

Modifier	Effect
`DOMINANT`	Colour by whichever field clears a `filter` threshold (`min`/`max`/`mean`/`median`, ± `dfilter`%)
`PERCENTOFMEAN`	Same as `DOMINANT`, but the threshold is a percentage of the field’s mean rather than its raw value — comparable across fields with very different scales
`DEVIATION`	Same again, but the relevance metric is a z-score: `(value − mean) / stddev`
`OFFSETMEAN`	Show deviation of all fields as +/− pointers (use with `CHART\|BAR\|POINTER`)
`COMPOSECOLOR`	No single winner — blends every field’s value into one new color at once, additively by default (two fields → a bivariate choropleth; three or more → tri-/multivariate)
`SUBTRACTIVE`	`COMPOSECOLOR` modifier — blends subtractively instead of additively

Dynamic opacity modifiers:

Modifier	Effect
`DOPACITY`	Opacity proportional to value — lower values become transparent
`DOPACITYMIN`	Opacity emphasises minimum values — higher values become transparent
`DOPACITYMAX`	Opacity emphasises maximum values — tunable with `dopacitypow` / `dopacityscale`
`DOPACITYMINMAX`	Opacity emphasises both extremes — average values become transparent
`BIPOLAR`	Alias for `DOPACITYMINMAX`
`DOPACITYLOG`	Like `DOPACITYMAX` but uses the logarithm of the value
`DOPACITYMEAN`	Opacity from percent deviation from the field’s mean — for use with `DOMINANT` / `PERCENTOFMEAN`
`DOPACITYLOGMEAN`	Like `DOPACITYMEAN` but log-scaled
`DOPACITYPOWMEAN`	Like `DOPACITYMEAN`, power-curved via `dopacitypow` (same formula as `DOPACITYMEAN` in the current implementation)
`DOPACITYLOGMAX`	Value-over-max ratio, log-scaled — for `DOMINANT`-style multi-field themes
`DOPACITYPOWMAX`	Value-over-max ratio, power-curved (tunable with `dopacitypow`)

See Colors & Classification for how these combine with alphafield and the density-normalized special case.

Chart composition modifiers:

Modifier	Effect
`SEQUENCE`	Composite chart: one symbol per piped field, arranged in sequence
`STAR`	Like `SEQUENCE` but arranged in a star / sunburst around the centre
`STARBURST`	`PIE` / `DONUT` modifier — radius varies by value
`SIZE`	2D: surface area represents value; with `PIE`/`DONUT`: radius represents value
`HEIGHT`	With `PIE` / `DONUT`: height represents value
`WIDTH`	With `PIE` / `DONUT`: like `SIZE`; with `POINTER`: makes width dynamic
`VOLUME`	3D: volume represents value
`HORZ`	Arrange `BAR` / `SEQUENCE` charts horizontally instead of vertically
`MULTIPLE`	Offset repeated positions so overlapping points are all visible
`DIFFUSE`	Like `AGGREGATE` but distributes each value to the 4 nearest grid points

Sizing tokens (LINEAR, SIZEP1…SIZEP10, SIZELOG) set the sizepow dimension — see Sizing & Scaling.

Plot / sparkline modifiers (for CHART|SYMBOL|PLOT):

Modifier	Effect
`LINES`	Connects the points with line segments instead of discrete symbols — the gate most of the rest of this table depends on
`AREA`	Fill the area under the plot curve (needs `LINES`)
`FADE`	Fades that area fill toward the baseline instead of a solid color (needs `LINES\|AREA`)
`LOLLIPOP`	Adds a stem from the baseline up to each point — works with or without `LINES`
`LASTPOP`	Circle marker highlighting the last point of the series
`LASTARROW`	Arrowhead on the last plot segment — size via `markersize`
`LASTVALUE`	Text label showing the value at the end of the line
`NOCLIP`	Don’t clip the plot to its grid cell
`GRIDSIZE`	Derive chart size from the grid cell size (`gridwidth`)
`FIXSIZE`	Uniform chart size, independent of the data value
`FADEIN`	Fade the plot line in from transparent to opaque

Chart positioning modifiers:

Modifier	Effect
`CENTER`	Chart centred on its anchor point (default)
`LEFT` / `RIGHT`	Align chart to the left or right of the anchor
`TOP` / `BOTTOM`	Align chart above or below the anchor
`ABOVE` / `BELOW`	Aliases for `TOP` / `BOTTOM`
`RELOCATE`	With `AGGREGATE`: recomputes the merged position as the average of the original points that were combined, instead of leaving it at the first/last one
`SORT`	Sort chart parts by value descending
`UP`	Sort ascending (smallest on top)
`DOWN`	Sort descending (largest on top)
`RANDOM`	Random sort — useful with `STAR` to avoid pattern formation

Aggregation modifiers — records landing on the same position (or the same grid cell, see below) collapse into one item:

Modifier	Effect
`AGGREGATE`	Gates the whole mechanism — without it, none of the rest of this table does anything
`SUM`	Sum of all values in the cell (the default)
`COUNT`	Count of rows in the cell
`MEAN`	Arithmetic mean
`MIN`	Minimum
`MAX`	Maximum
`GROUP`	Same spatial binning as `AGGREGATE`, but without combining values — items stay separate, just clustered and ordered within their bin

By default AGGREGATE only merges records at the exact same position. Add a spatial grid to merge nearby-but-not-identical positions too — gridwidth: "Npx" in .style() sizes the grid cell in constant screen pixels (recalculated every zoom); the plain numeric form (gridwidth: 500) sizes it in real-world meters instead.

Special geometry modifiers:

Modifier	Effect
`BUFFER`	Draw buffer zones of `buffersize` metres around point, line, or polygon features