Count Plot

Generalized signature

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

statCountArgs :=
   x,
   weights = null

The possible types of x and weights depend on where a certain function is used. They can be simply Iterable (List, Set, etc.) or a reference to a column in a DataFrame (String, ColumnAccessor) or the DataColumn itself. x elements are type of X — generic type parameter.

statCount transform

statCount(statCountArgs) { /*new plotting context*/ } modifies a plotting context - instead of original data (no matter was it empty or not) new StatCount 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 statCount 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:

plot {
    statCount(df["class"]) {
        // New `StatCount` dataset here
        points {
            // Use `Stat.*` columns for mappings
            x(Stat.x)
            y(Stat.count)
            size(Stat.count)
            color(Stat.x)
        }
    }
}

CountPlot layer

CountPlot is a statistical plot used for visualizing the distribution of categorical variables. It's a bar plot where each bar is representing one of the categories: its x coordinate is corresponding to the category and y to its count. So basically, we can build a histogram with statCount as follows:

val statCountAndBarsPlt = df.plot {
    statCount("class") {
        bars {
            x(Stat.x)
            y(Stat.count)
        }
    }
    layout.title = "`statCount()` + `bars()` layer"
}
statCountAndBarsPlt

But we can do it even faster with countPlot(statCountArgs) method:

val countPlt = plot {
    countPlot(df["class"])
    layout.title = "`countPlot()` layer"
}
countPlt

Let's compare them:

plotGrid(listOf(statCountAndBarsPlt, countPlt))

These two plots are identical. Indeed, countPlot just uses statCount and bars and performs coordinate mappings under the hood. And we can customize count plot layer: countPlot() optionally opens a new context, where we can configure bars (as in the usual context opened by bars { ... }) — even change coordinate mappings from default ones. StatCount dataset of count plot is also can be accessed here.

df.plot {
    countPlot(`class`) {
        // filling color depends on `count` statistic
        fillColor(Stat.count) {
            scale = continuous(Color.GREEN..Color.RED)
        }
        borderLine.color = Color.BLACK
    }
}

If we specify weights, Stat.countWeighted is mapped to y by default:

df.plot {
    countPlot(`class`, hwy)
    // We can add other layers as well.
    // Let's add a horizontal mark line with constant y intercept:
    hLine {
        val criticalCount = 500
        yIntercept.constant(criticalCount)
        tooltips { line("Critical count: ${String.format("%d", criticalCount)}") }
        color = Color.RED; width = 3.0
    }
    x.axis.name = "Car class"
}

countPlot plot

countPlot(statCountArgs) and DataFrame.countPlot(statCountArgs) are a family of functions for fast plotting a count plot.

countPlot(listOf("A", "A", "A", "B", "B", "C", "B", "B"))

df.countPlot("class")

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 input and (optionally) weight throw invocation eponymous functions:

df.countPlot {
    x(`class`)
    weight(hwy)
}

CountPlot plot can be configured with .configure {} extension — it opens a context that combines bars, StatCount and plot context. That means you can configure bars settings, mappings using StatCount dataset and any plot adjustments:

df.countPlot {
    x(`class`)
}.configure {
    // Bars + StatCount + PlotBuilder
    // can't add new layer
    // can add bars mapping, including for `Stat.*` columns
    fillColor(Stat.x)
    alpha = 0.6
    // can configure general plot adjustments
    layout {
        title = "Configured `countPlot` plot"
        size = 600 to 350
    }
}

Inside groupBy{} plot context

We can apply groupBy modification to the initial dataset and count plot a histogram with grouped data the same way:

df.plot {
    groupBy(drv) {
        countPlot(`class`)
    }
}