Catalog.plot.shift

Catalog.plot.shift ¶

shift(
    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: ShiftBarConfig | 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,
) -> alt.LayerChart | alt.VConcatChart | alt.HConcatChart

Makes a word shift plot (a stacked bar chart) of the top contributing tokens distinguishing two compared corpora.

Word shift plots can only be used with scores derived from weighted averages. For comparing corpora using measures that are not weighted averages, use Catalog.plot.bar instead.

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.shift("weighted_avg_comparison")

All bars are interpreted in terms of how the comparison corpus differs from the reference corpus. For details, see the scoring documentation. For each token, there are two stacked bars. One bar shows whether the token is relatively positive or negative and whether it was used more or less in the comparison versus the reference. The other bar shows whether the token's score is higher or lower in the comparison versus the reference. Tokens are ranked by the magnitude of both stacked bars together.

Mathematically, the bars are derived from the following formula. Let \(\tau\) be a token, and let \(p_\tau^{(\mathcal{C})}\) and \(\phi_\tau^{(\mathcal{C})}\) be the normalized frequency and score of \(\tau\) in corpus \(\mathcal{C}\) respectively. Then the contribution \(\delta_\tau\) of the token is:

\[ \delta_\tau = \overbrace{ \biggl( p_\tau^{(C)} - p_\tau^{(R)} \biggr) }^{ \uparrow / \downarrow } \overbrace{ \biggl[ \frac{1}{2} \left( \phi_\tau^{(C)} + \phi_\tau^{(R)} - \Phi^{(\text{ref})} \right) \biggr] }^{ + / - } + \underbrace{ \frac{1}{2} \biggl( p_\tau^{(C)} + p_\tau^{(R)} \biggr) \biggl( \phi_\tau^{(C)} - \phi_\tau^{(R)} \biggr) }_{ \bigtriangleup / \bigtriangledown } \]

where \(R\) and \(C\) are the reference and comparison corpora respectively, and \(\Phi^{(\text{ref})}\) is the user-provided reference score.

The stacked bars represent the two parts of the summand. The first bar is whether a word is relatively positive \((+ / -)\) and appears more or less in the comparison corpus \((\uparrow / \downarrow)\). The second bar is whether the score is more or less positive in the comparison corpus \((\bigtriangleup / \bigtriangledown)\). Note, the bars may counteract one another if the two summand terms are different signs: this is shown visually with faded bars in the word shift plot when that is the case.

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.bar`	Concise bar plot of comparisons scored with any measure

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 (`not vertical`), 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` ¶	`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` ¶	`ShiftBarConfig \| dict \| None`	Configuration for the bars. Accepts a `ShiftBarConfig` 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`
`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`

Returns:

Type	Description
`LayerChart \| VConcatChart \| HConcatChart`	An Altair chart of the word shift plot

Raises:

Type	Description
`KeyError`	If `comparison` is not the alias of a comparison in the catalog
`ValueError`	If the comparison's measure is not a weighted average

Source

Catalog.plot.shift