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_config: RankAxisConfig | dict | None = None,
    score_axis_config: ScoreAxisConfig | dict | None = None,
    color_config: ShiftColorConfig | 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,
) -> alt.LayerChart | alt.VConcatChart | alt.HConcatChart

Makes a word shift plot (a stacked 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.shift("weighted_avg_comparison")

There are two stacked bars per token: one indicating the difference in relative frequency, one indicating the difference in score. Tokens are ranked by the magnitude of both bars stacked together. For what each bar means and how to read the plot, see more on word shift graphs.

Word shift graphs 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.

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_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` ¶	`ShiftColorConfig \| dict \| None`	Configuration for the bar colors. Accepts a `ShiftColorConfig` 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`

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