Skip to content

Catalog.plot.bar

Catalog.plot.bar 

bar(
    comparison: str,
    max_rank: int = 50,
    vertical: bool = True,
    height: float | None = None,
    width: float | None = None,
    show_totals: bool = False,
    rank_axis_config: RankAxisConfig | dict | None = None,
    score_axis_config: ScoreAxisConfig | dict | None = None,
    color_config: BarColorConfig | dict | None = None,
    bar_config: BarConfig | dict | None = None,
    label_config: LabelConfig | dict | None = None,
    border_config: BorderConfig | dict | None = None,
    zero_line_config: ZeroLineConfig | dict | None = None,
    totals_config: TotalsConfig | dict | None = None,
    scale_factor: float = 1.0,
    show_legend: bool = False,
    split_nonnegative_by_corpus: bool = True,
) -> alt.LayerChart | alt.VConcatChart | alt.HConcatChart

Makes a bar chart of the top contributing tokens distinguishing two compared corpora.

Example 
import wordlevel as wl

cl = wl.Catalog.from_dict_of_freqs(
    {
        "before": {"good": 12, "bad": 8, "happy": 6, "sad": 4},
        "after": {"good": 5, "bad": 7, "happy": 3, "sad": 9},
    }
).with_comparisons(
    wl.comp("before", "after").score.proportion().alias("basic_comparison"),
    wl.comp("before", "after")
    .score.lexicon(wl.lex.labMT("english"))
    .alias("weighted_avg_comparison"),
)

chart = cl.plot.bar("basic_comparison")

Bars show the contribution of each token to the overall comparison score, ordered by magnitude. Which two groups the tokens are split into, and how each side reads, depends on the scoring measure.

Reference

For more details, see the following paper:

Gallagher, R. J., Frank, M. R., Mitchell, L., Schwartz, A. J., Reagan, A. J., Danforth, C. M., & Dodds, P. S. (2021). Generalized word shift graphs: a method for visualizing and explaining pairwise comparisons between texts. EPJ Data Science, 10(1), 4.

See Also
Plot Description
Catalog.plot.shift Detailed bar plot of comparisons scored with weighted averages

Parameters:

Name Type Description Default

comparison

str

The alias of a comparison in the catalog. See Catalog.with_comparisons and Comparison.alias

 required

max_rank

int

The maximum number of top-contributing tokens to display

 50

vertical

bool

Whether to orient the chart vertically, where tokens are listed top-to-bottom and bars extend horizontally. If False, tokens are listed left-to-right and bars extend vertically

 True

height

float | None

The height of the chart, in pixels. Ignored if vertical, see RankAxisConfig.bar_width to control the height

 None

width

float | None

The width of the chart, in pixels. Ignored if horizontal (vertical=False), see RankAxisConfig.bar_width to control the width

 None

show_totals

bool

Whether to show the overall total contributions of each score type and overall as an additional chart appended to the main chart

 False

rank_axis_config

RankAxisConfig | dict | None

Configuration for the rank axis. Accepts a RankAxisConfig or a dict with the same fields

 None

score_axis_config

ScoreAxisConfig | dict | None

Configuration for the score axis. Accepts a ScoreAxisConfig or a dict with the same fields

 None

color_config

BarColorConfig | dict | None

Configuration for the bar colors. Accepts a BarColorConfig or a dict with the same fields

 None

bar_config

BarConfig | dict | None

Configuration for the bars, other than their color. Accepts a BarConfig or a dict with the same fields

 None

label_config

LabelConfig | dict | None

Configuration for the bar labels. Accepts a LabelConfig or a dict with the same fields

 None

border_config

BorderConfig | dict | None

Configuration for the border of the entire chart. Accepts a BorderConfig or a dict with the same fields

 None

zero_line_config

ZeroLineConfig | dict | None

Configuration for the zero line at the score-axis origin. Accepts a ZeroLineConfig or a dict with the same fields

 None

totals_config

TotalsConfig | dict | None

Configuration for the totals panels, which labels each total bar. Accepts a TotalsConfig or a dict with the same fields. Ignored if show_totals is False

 None

scale_factor

float

Multiplier applied to the score axis when fitting it to the bar labels. Increasing it provides more space for the bar labels

 1.0

show_legend

bool

Whether to show the chart legend

 False

split_nonnegative_by_corpus

bool

When the scoring measure is inherently non-negative, whether to direct bar contributions in the positive and negative directions based on which corpus they are attributed to (the reference or comparison). The score axis is updated to reflect that all token-level scores are still positive. If False, attributions can still be distinguished per corpus by bar color. Ignored for measures that can be negative

 True

Returns:

Type Description
LayerChart | VConcatChart | HConcatChart

An Altair chart of the bar plot

Raises:

Type Description
KeyError

If comparison is not the alias of a comparison in the catalog
ValueError

If color_config specifies the wrong color fields

Source