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: RankAxisConfig | dict | None = None,
    score_axis: ScoreAxisConfig | dict | None = None,
    bar_config: BarConfig
    | ScoreSignBarConfig
    | dict
    | None = None,
    label_config: LabelConfig | dict | None = None,
    border_config: BorderConfig | dict | None = None,
    zero_line_config: ZeroLineConfig | dict | None = None,
    total_shift_config: TotalShiftConfig
    | 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.

Bars show the contribution of each token to the overall comparison score, ordered by the magnitude. How the contributions are attributed and interpreted depends on the scoring measure. For frequency- and rank-based measures—such as proportions and rank-turbulence divergence—each token is attributed to the corpus for which it is most characteristic, i.e. which corpus it appears more in. For measures where attribution is based on the sign of the contribution—such as lexicon-weighted averages and Shannon entropy—a token's contribution is interpreted in terms of whether it reinforces or offsets the difference between the corpora. See the per-measure scoring documentation for details.

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")
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

 None

width

float | None

The width of the chart, in pixels

 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

RankAxisConfig | dict | None

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

 None

score_axis

ScoreAxisConfig | dict | None

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

 None

bar_config

BarConfig | ScoreSignBarConfig | dict | None

Configuration for the bars. Accepts a BarConfigfor corpus-attributed measures or an ScoreSignBarConfigfor sign-attributed measures. Also accepts a dict keyed by the same corresponding attribution labels

 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

total_shift_config

TotalShiftConfig | dict | None

Configuration for the grand total bar in the totals panels. Accepts a TotalShiftConfig 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

Source