Marks cells that fall outside a threshold, either beyond an interquartile fence, beyond a number of standard deviations, or outside bounds you supply.
Arguments
- gt_object
A
gttable object to modify.- columns
The column or columns to test. Non-numeric columns are skipped.
- method
Character. How to decide what counts as an outlier. One of
"iqr","sd", or"bounds". Defaults to"iqr".- threshold
Numeric. The cutoff used by
"iqr"and"sd". IfNULL, the convention for the method is used:1.5for"iqr"and3for"sd". Defaults toNULL.- bounds
A length-2 numeric vector giving
c(lower, upper), required whenmethodis"bounds". UseNAfor an open end, such asc(NA, 100). Defaults toNULL.- side
Character. Which tail to flag. One of
"both","high", or"low". Defaults to"both".- fill
Optional. A hex color for the cell fill behind flagged values. Defaults to
NULL, which applies no fill.- color
Optional. A hex color for flagged text. If
NULL, a warning red is used, swapped for a readable alternative when it would not have enough contrast againstfill. Defaults toNULL.- bold
Logical. Should flagged values be bolded? Defaults to
TRUE.- symbol
Optional. A marker appended to flagged values, such as a dagger (
"\u2020"). Defaults toNULL.- note
Optional. A source note describing the rule that was applied. Pass
TRUEfor wording generated frommethodandthreshold, a string for your own, orNULLfor no note. Defaults toNULL.
Details
gt::data_color() shades a continuous scale; this flags a value as unusual.
Thresholds are computed separately for each column, so every column is judged
against its own distribution.
The default rule is the interquartile fence, not standard deviations, because
an SD fence is built from a spread that the outlier itself inflates. On
c(10.2, 10.4, 10.1, 19.8, 10.3, 10.0) the mean is 11.8 and the standard
deviation 3.92, so a three-SD fence reaches 23.6 and misses the 19.8. The
quartiles barely move, so the IQR fence stops at 10.75 and catches it. The
masking is worst in small samples. Use method = "sd" if you want it anyway.
See also
gt_highlight_na() for missing values, and gt_spotlight() for
drawing attention to whole rows.
Examples
library(gt)
nba <- subset(
sdv_example_standings, league == "nba",
c(team_name, points_for, points_against)
)
# the default fence (1.5 times the IQR) catches the league's lowest scorer
gt(nba) |> gt_outliers(c(points_for, points_against), note = TRUE)
team_name
points_for
points_against
Marked values fall outside 1.5 × IQR of the column quartiles.
# an explicit acceptance range, flagging only the high side
gt(nba) |>
gt_outliers(c(points_for, points_against),
method = "bounds", bounds = c(NA, 9800),
side = "high", fill = "#FDECEA", symbol = "\u2020"
)
team_name
points_for
points_against
# works on wider data too
nfl <- subset(
sdv_example_standings, league == "nfl",
c(team_name, wins, points_for, points_against)
)
gt(nfl) |> gt_outliers(c(wins, points_for, points_against))
team_name
wins
points_for
points_against