Boxplot

Generalized signature

The specific signature depends on the function, but all functions related to "boxplot" statistic (which will be discussed further below - different variations of statBoxplot(), statBoxplotOutliers() boxplot()) have approximately the same signature with the arguments above:

statBoxplotArgs :=
   x, // not necessarily
   y,
   whiskerIQRRatio: Double = 1.5

The possible types y depend on where a certain function is used. It can be simply Iterable (List, Set, etc.) or a reference to a column in a DataFrame (String, ColumnAccessor) or the DataColumn itself. It's used only with DataFrame - it's a reference to a column of the same type as an y. x elements are type of X - generic type parameter.

"boxplot"

"boxplotOutliers"

statBoxplot and statBoxplotOutliers transforms

statBoxplot(statBoxplotArgs) { /*new plotting context*/ } modifies a plotting context - instead of original data (no matter was it empty or not) new StatBoxplot dataset (calculated on given arguments; inputs and weights can be provided as Iterable or as dataset column reference - by name as a String, as a ColumnReference or as a DataColumn) is used inside a new context (original dataset and primary context are not affected - you can add layers using initial dataset outside the statBoxplot context). Since the old dataset is irrelevant, we cannot use references for its columns. But we can refer to the new ones. They are all contained in the Stat group and can be called inside the new context.

df.plot {
    statBoxplot(cond, rate) {
        // New "StatBoxplot" dataset here
        errorBars {
            // Use `Stat.*` columns for mappings
            x(Stat.x)
            yMin(Stat.min)
            yMax(Stat.max)
            borderLine.color(Stat.x)
        }
    }
    // Initial dataset here
    points {
        x("cond")
        y("rate")
        size = 0.5
        alpha = 0.2
        color("cond")
        position = Position.jitter()
    }
}

statBoxplotOutliers(statBoxplotArgs) { /*new plotting context*/ } works the same way with a new StatBoxplotOutliers` dataset.

df.plot {
    statBoxplotOutliers(cond, rate) {
        // New "StatBoxplotOutliers" dataset here
        points {
            x(Stat.x)
            y(Stat.y)
            color(Stat.x)
        }
    }
}

boxplot layer

To make a boxplot (statistical chart), we need boxplot statistics and boxes geom. Boxes attributes and boxplot statistics match. Also, we can add outliers using boxplotOutliers statistic and points layer.

val manualBoxplot = df.plot {
    statBoxplot(cond, rate) {
        boxes {
            // All positional aesthetics match boxplot statistics
            x(Stat.x)
            yMin(Stat.min)
            lower(Stat.lower)
            middle(Stat.middle)
            upper(Stat.upper)
            yMax(Stat.max)
        }
    }
    statBoxplotOutliers(cond, rate) {
        points {
            x(Stat.x)
            y(Stat.y)
        }
    }
    layout {
        title = "`statBoxplot` + `boxes` \n" +
                "and `statBoxplotOutliers` + `points`"
    }
}
manualBoxplot

But we can do it much faster with boxplot(statBoxplotArgs) method:

val boxplotPlot = df.plot {
    // Statistical boxplot layer - receives "statBoxplotArgs" and has default mappings
    boxplot(cond, rate)
    layout.title = "`boxplot()`"
}
boxplotPlot

Let's compare them:

plotGrid(listOf(manualBoxplot, boxplotPlot))

These two plots are identical. Indeed, statistical boxplot just uses the combination of statistics and layers above (statBoxplot + boxes and statBoxplotOutlier + points) and performs coordinates mappings under the hood. And we can customize statistical boxplot layer: boxplot() optionally opens a new context, where we can configure both boxes and outliers (as in usual contexts opened by boxes { ... }/points { ... }). Moreover, Stat. columns of StatBoxplot dataset are available in the context of boxes, exactly as Stat. columns of StatBoxplotOutliers are available in the context of outliers. Also, we can hide outliers.

df.plot {
    boxplot(cond, rate) {
        boxes {
            // Boxes context + StatBoxplot context
            // filling color depends on `x` category
            fillColor(Stat.x)
        }
        // hide outliers
        outliers.show = false
    }
}

df.plot {
    boxplot(cond, rate) {
        boxes {
            fatten = 0.5
            alpha = 0.6
            // Border line color depends on `x` category
            borderLine.color(Stat.x)
        }
        outliers {
            // points context + StatBoxplotOutliers context
            // color depends on `x` category
            color(Stat.x)
            symbol = Symbol.ASTERIX
        }
    }
}

Boxplot layer by a single sample (without x categories) - receives only one sample (Iterable or column reference)

plot {
    boxplot(rateC)
}

boxplot plot

boxplot(statBoxplotArgs) and DataFrame.boxplot(statBoxplotArgs) is a family of functions for fast plotting a boxplot.

// There's an additional argument "showOutliers"
df.boxplot("cond", "rate", showOutliers = false)

In case you want to provide inputs and weights using column selection DSL, it's a bit different from the usual one - you should assign x and y inputs throw invocation eponymous functions:

df.boxplot(whiskerIQRRatio = 2.0) {
    x(cond)
    y(rate)
}

Boxplot plot can be configured with .configure {} extension - it opens context similar to the one that creates a statistical boxplot layer, where you can configure boxes and outliers the same way, but also can configure any plot adjustments:

df.boxplot {
    x(cond)
    y(rate)
}.configure {
    // BoxplotLayer + PlotBuilder
    // can't add new layer but can configure `boxes` and `outliers`
    boxes {
        alpha = 0.7
        fillColor(Stat.middle) { scale = continuous(Color.GREEN..Color.RED) }
    }
    outliers {
        color(Stat.x)
        // jittered outliers
        position = Position.jitter(0.1, 0.0)
    }
    // can configure general plot adjustments
    layout {
        title = "Configured boxplot"
        size = 600 to 350
    }
}

Inside groupBy{} plot context

We can apply groupBy modification to the initial dataset and build a boxplot with grouped data the same way:

mpgShortDF.plot {
    groupBy(drv) {
        boxplot(`class`, hwy)
    }
}