Skip to content
API Reference
distributions
kde
kdeplot

kdeplot

Mojo function 🡭

kdeplot

fn def kdeplot(values: List[Float64], bandwidth: Float64 = 0, fill: Bool = False, rug: Bool = False, theme: Theme = Theme(WHITE, Color(UInt8(30), UInt8(100), UInt8(180), UInt8(255)), Color(UInt8(80), UInt8(80), UInt8(80), UInt8(255)), Color(UInt8(225), UInt8(225), UInt8(225), UInt8(255)), Color(UInt8(40), UInt8(40), UInt8(40), UInt8(255)), SIMD(12), SIMD(3.5), SIMD(2), Int(60), Int(20), Int(20), Int(50), True, False, False, Color(UInt8(240), UInt8(240), UInt8(240), UInt8(255)), Int(3), Color(UInt8(60), UInt8(110), UInt8(200), UInt8(255)), Color(UInt8(235), UInt8(235), UInt8(235), UInt8(255)), Color(UInt8(220), UInt8(90), UInt8(40), UInt8(255)), ColorRamp(), ColorPalette(), SIMD(3), SIMD(15), True, SIMD(1), Int(0), False, Color(UInt8(200), UInt8(60), UInt8(60), UInt8(255)), Color(UInt8(224), UInt8(224), UInt8(224), UInt8(255)), Color(UInt8(120), UInt8(120), UInt8(120), UInt8(255)), Color(UInt8(100), UInt8(100), UInt8(100), UInt8(255)), Color(UInt8(230), UInt8(230), UInt8(230), UInt8(255)), Color(UInt8(255), UInt8(255), UInt8(255), UInt8(255)), UInt8(90), UInt8(160), False, False, SIMD(0), SIMD(18), SIMD(14), Color(UInt8(110), UInt8(110), UInt8(110), UInt8(255)), SIMD(14), Color(UInt8(150), UInt8(150), UInt8(150), UInt8(255)), Color(UInt8(224), UInt8(236), UInt8(246), UInt8(200)), Color(UInt8(255), UInt8(255), UInt8(255), UInt8(255)), True, False, False, True, AxisPosition.EDGE, AxisPosition.EDGE, String("sans-serif"), True, UInt8(90), Int(5), Int(4), Int(130), Int(14), Int(8), Int(14), Int(100), Int(8), SIMD(4), OutputFormat.SVG, Tooltips.AUTO, Missing.DRAW, String("(missing)"), Int(1000), False, LineStyle.SOLID, SIMD(1.5), LineStyle.SOLID, LegendPosition.RIGHT, XAxisLabelRotation.AUTO, TickFormat.AUTO, TickFormat.AUTO), width: Int = Int(640), height: Int = Int(420), title: String = "", subtitle: String = "", x_title: String = "", y_title: String = "") -> Chart[Kde]

A kernel-density curve over raw observations: the smooth estimate of a distribution’s shape, without a histogram’s bin-width choice.

Mark.KDE: the same estimate Mark.VIOLIN computes, drawn on a continuous frame – value across, density up – which is the form for comparing two or three distributions on shared axes.

To compare them on one frame, render_layers(kdeplot(a), kdeplot(b)) is how to say that: the curves share one density axis, so their peak heights are comparable, which is the whole point. render_facets() puts them side by side instead, a weaker reading but useful when the distributions barely overlap.

A KDE is smooth everywhere, including where there are no observations at all, so it can imply detail the sample does not support. rug=True marks where the data actually are, and bandwidth is worth setting deliberately – the same sample can show one mode or three depending on it.

Example:

from dataviz import kdeplot
from dataviz import save

def main() raises:
    # Illustrative checkout API latency (ms): a dense main mode with a
    # long tail from a handful of slow requests.
    var latency_ms: List[Float64] = [
        84.0, 72.0, 91.0, 68.0, 75.0, 88.0, 79.0, 73.0,
        96.0, 82.0, 77.0, 69.0, 85.0, 74.0, 101.0, 80.0,
        71.0, 93.0, 76.0, 87.0, 83.0, 70.0, 78.0, 89.0,
        81.0, 95.0, 67.0, 86.0, 72.0, 90.0, 110.0, 124.0,
        138.0, 156.0, 205.0, 98.0, 105.0, 118.0, 74.0, 82.0,
    ]
    var c = kdeplot(
        latency_ms,
        fill=True,
        rug=True,
        title="Illustrative Checkout API Latency",
        x_title="Latency (ms)",
        y_title="Density",
    )
    save(c, "docs/src/examples/out_kdeplot.svg")

Args:

  • values (List[Float64]): The observations.
  • bandwidth (Float64): Kernel bandwidth; not positive uses Silverman’s rule.
  • fill (Bool): Shade the curve down to zero as well as stroking it.
  • rug (Bool): Draw each observation as a tick along the baseline.
  • theme (Theme): Colors, sizes and spacing.
  • width (Int): Canvas width in pixels.
  • height (Int): Canvas height in pixels.
  • title (String): Chart title.
  • subtitle (String): Smaller line under the title.
  • x_title (String): X-axis label.
  • y_title (String): Y-axis label.

Returns:

Chart[Kde]: The finished Plot.

Raises:

Error: values is empty.

fn def kdeplot(df: DataFrame, values: String, bandwidth: Float64 = 0, fill: Bool = False, rug: Bool = False, theme: Theme = Theme(WHITE, Color(UInt8(30), UInt8(100), UInt8(180), UInt8(255)), Color(UInt8(80), UInt8(80), UInt8(80), UInt8(255)), Color(UInt8(225), UInt8(225), UInt8(225), UInt8(255)), Color(UInt8(40), UInt8(40), UInt8(40), UInt8(255)), SIMD(12), SIMD(3.5), SIMD(2), Int(60), Int(20), Int(20), Int(50), True, False, False, Color(UInt8(240), UInt8(240), UInt8(240), UInt8(255)), Int(3), Color(UInt8(60), UInt8(110), UInt8(200), UInt8(255)), Color(UInt8(235), UInt8(235), UInt8(235), UInt8(255)), Color(UInt8(220), UInt8(90), UInt8(40), UInt8(255)), ColorRamp(), ColorPalette(), SIMD(3), SIMD(15), True, SIMD(1), Int(0), False, Color(UInt8(200), UInt8(60), UInt8(60), UInt8(255)), Color(UInt8(224), UInt8(224), UInt8(224), UInt8(255)), Color(UInt8(120), UInt8(120), UInt8(120), UInt8(255)), Color(UInt8(100), UInt8(100), UInt8(100), UInt8(255)), Color(UInt8(230), UInt8(230), UInt8(230), UInt8(255)), Color(UInt8(255), UInt8(255), UInt8(255), UInt8(255)), UInt8(90), UInt8(160), False, False, SIMD(0), SIMD(18), SIMD(14), Color(UInt8(110), UInt8(110), UInt8(110), UInt8(255)), SIMD(14), Color(UInt8(150), UInt8(150), UInt8(150), UInt8(255)), Color(UInt8(224), UInt8(236), UInt8(246), UInt8(200)), Color(UInt8(255), UInt8(255), UInt8(255), UInt8(255)), True, False, False, True, AxisPosition.EDGE, AxisPosition.EDGE, String("sans-serif"), True, UInt8(90), Int(5), Int(4), Int(130), Int(14), Int(8), Int(14), Int(100), Int(8), SIMD(4), OutputFormat.SVG, Tooltips.AUTO, Missing.DRAW, String("(missing)"), Int(1000), False, LineStyle.SOLID, SIMD(1.5), LineStyle.SOLID, LegendPosition.RIGHT, XAxisLabelRotation.AUTO, TickFormat.AUTO, TickFormat.AUTO), width: Int = Int(640), height: Int = Int(420), title: String = "", subtitle: String = "", x_title: String = "", y_title: String = "") -> Chart[Kde]

kdeplot() over a named column of a dataframe_mojo DataFrame (#743); the x-axis title defaults to the column name.

See Plot.encode_frame() for how columns are read and what a column with missing values does.

Args:

  • df (DataFrame): The frame to read.
  • values (String): The numeric column holding the observations.
  • bandwidth (Float64): See the list overload.
  • fill (Bool): See the list overload.
  • rug (Bool): See the list overload.
  • theme (Theme): See the list overload.
  • width (Int): See the list overload.
  • height (Int): See the list overload.
  • title (String): See the list overload.
  • subtitle (String): See the list overload.
  • x_title (String): See the list overload.
  • y_title (String): See the list overload.

Returns:

Chart[Kde]: The finished chart – unrendered.

Raises:

Error: A named column is missing, has the wrong dtype for its channel, or has missing values.

rugplot