Density

A density draws a kernel curve of one quantitative sample. The rows stay the observations. The spec does not contain a density transform. encoding.x is the sample. The curve is the estimate.

When to use it

Use a density when the question is the shape of a distribution: where the mass sits, and whether there is a second bump. Wait time has a pile near 15 minutes and a smaller pile near 40.

A histogram answers the same sample with counts in bins. The bars are the counts. A density smooths them into one curve. A box plot or a strip is the chart when the reader needs a median and quartiles, or every point. A density with a group field is one curve per group. It is not a violin.

Data

Each row is one observation. encoding.x is quantitative. A string field name is enough. An object can set the axis title. Wait time titles the sample Minutes.

encoding.color or encoding.series draws one curve per group. Wait by desk colors by desk. Front and back overlay. They share one extent. v1 does not stack the curves.

Fewer than two finite numbers in a group is not a curve. a11y.alt is required. One sentence, 10 to 500 characters, about the shape. State where the mass is. The bandwidth is an implementation detail.

A spec that renders

This is the smallest density. version, type, and a11y.alt are required. Five waits, and no mark. Bandwidth is Scott's rule. The curve is sampled at 64 points. The density axis starts at 0. One curve uses the accent color.

spec.json
{
  "version": "1",
  "type": "density",
  "data": [
    {
      "wait": 12
    },
    {
      "wait": 15
    },
    {
      "wait": 18
    },
    {
      "wait": 14
    },
    {
      "wait": 40
    }
  ],
  "encoding": {
    "x": "wait"
  },
  "a11y": {
    "alt": "Most waits sit near 15 minutes, with a tail out to 40."
  }
}

Install core and the adapter for your framework. The menu in the sidebar picks the snippet. spec is the JSON above.

Import@chartkitdev/core/charts/densityBundle@chartkitdev/core/extraFamilyLibrary
React
npm install @chartkitdev/core
npm install @chartkitdev/react

import { Chart } from "@chartkitdev/react";

export function Panel() {
  return <Chart spec={spec} />;
}
Vanilla
npm install @chartkitdev/core
npm install @chartkitdev/vanilla

import { mount } from "@chartkitdev/vanilla";

const chart = mount(document.querySelector("#chart"), spec);
chart.update(spec);
Vue
npm install @chartkitdev/core
npm install @chartkitdev/vue

<script setup>
import { Chart } from "@chartkitdev/vue";
</script>

<template>
  <Chart :spec="spec" />
</template>
Svelte
npm install @chartkitdev/core
npm install @chartkitdev/svelte

<script>
  import { Chart } from "@chartkitdev/svelte";
</script>

<Chart {spec} />
Astro
npm install @chartkitdev/core
npm install @chartkitdev/astro

---
import { Chart } from "@chartkitdev/astro";
---

<Chart spec={spec} />
Solid
npm install @chartkitdev/core
npm install @chartkitdev/solid

import { Chart } from "@chartkitdev/solid";

export function Panel() {
  return <Chart spec={spec} />;
}
Qwik
npm install @chartkitdev/core
npm install @chartkitdev/qwik

import { component$ } from "@builder.io/qwik";
import { Chart } from "@chartkitdev/qwik";

export const Panel = component$(() => {
  return <Chart spec={spec} />;
});
Angular
npm install @chartkitdev/core
npm install @chartkitdev/angular

import { Component } from "@angular/core";
import { Chart } from "@chartkitdev/angular";

@Component({
  standalone: true,
  imports: [Chart],
  template: `<ck-chart [spec]="spec" />`,
})
export class Panel {
  spec = spec;
}
Custom element
npm install @chartkitdev/core
npm install @chartkitdev/element

import "@chartkitdev/element";

const chart = document.querySelector("chart-kit");
chart.spec = spec;

Each option below is a key on the spec. The demo changes that key and updates the chart and the snippet together.

Examples

The rail switches among existing density specs. Wait time is one sample and Scott's rule. Wait by desk is two groups, a bandwidth of 3, and counts. Vertical waits runs the sample down the page and draws a rug of the raw points.

Bandwidth

mark.bandwidth is the Gaussian width in data units. Omit it, or set "auto", and the width is Scott's rule: 1.06 times the standard deviation times the sample size to the power −1/5. A number greater than 0 is used as given. Wait by desk sets 3.

mark.bandwidth
{
  "mark": { "bandwidth": 3 }
}
mark.bandwidth auto
{
  "mark": { "bandwidth": "auto" }
}

Auto removes the key, which is the same picture as "auto". 3 and 8 write that width. A narrower kernel keeps a second bump. A wider one can hide it. Any other number is set in the playground, and this control leaves it until you pick Auto, 3, or 8.

Normalize

mark.normalize is the height of the curve. Omit it, or set density, and the curve integrates to 1. count multiplies by the sample size, so the height reads as a count. Wait by desk uses count, and the axis title is Waits.

mark.normalize
{
  "mark": { "normalize": "count" }
}

The two settings share the same shape. The axis numbers change. Stacked densities are a later chart. These curves overlay.

Rug

mark.rug draws a tick for each raw observation on the baseline. Omit it and the curve is the only mark. Vertical waits sets true, so you can see the two clusters the kernel is smoothing.

mark.rug
{
  "mark": { "rug": true }
}

Off removes the key. On writes true. The rest of mark stays, including orientation and extent.

Orientation

mark.orientation chooses which axis holds the sample. Omit it and the chart is horizontal: the sample runs along x and the density along y. vertical swaps them. Vertical waits is that chart. The word is the same one a bar uses, and the default is the other way around.

mark.orientation
{
  "mark": { "orientation": "vertical" }
}

Legend

One curve hides the legend. A color field with more than one group shows it. Omit legend, or set true, and the legend sits on top. false hides it. legend.position is top, right, bottom, left, or inside.

legend.position
{
  "legend": { "position": "bottom" }
}

Wait time is one curve, so the legend stays hidden until you are on Wait by desk. Off still writes legend: false.

Tooltip

tooltip is on for a density when the key is omitted. Hovering the curve shows the sample value and the density, plus the group when there is one. tooltip: false turns the card off. tooltip: true turns it on.

tooltip false
{
  "tooltip": false
}
tooltip true
{
  "tooltip": true
}

tooltip.fields chooses the rows in the card. These examples omit the key. Turning the card off and on again puts that object back when the example had one, and deletes the key when the example omitted it.

The rest of the spec

mark.steps is how many samples the curve is drawn through. The default is 64. mark.extent is pad, data, or a pair of numbers. Pad extends the sample by three bandwidths. Vertical waits clips to the sample with data. mark.dims: 2 is a contour and is not drawn in this version. mark.bins belongs on a histogram. On a density, repair removes it. Theme presets live on the playground, with the full option list.