Getting started

Let's assume you put the following text into a sentiment analysis model:

text = "I loved the concert but not the opening act"
words = split(text)

9-element Vector{SubString{String}}:
 "I"
 "loved"
 "the"
 "concert"
 "but"
 "not"
 "the"
 "opening"
 "act"

The model returns a vector of sentiment scores for each word, where positive values indicate positive sentiment and negative values indicate negative sentiment:

val = [0.1, 2.5, 0.0, 0.3, -0.6, -1.4, 0.0, 0.1, -0.1]

To visualize the sentiment scores, we can use the heatmap function:

using TextHeatmaps

heatmap(val, words)

Ilovedtheconcertbutnottheopeningact

Color schemes

We can use a custom color scheme from ColorSchemes.jl using the keyword argument cs:

using ColorSchemes
heatmap(val, words; colorscheme=ColorSchemes.jet)

Ilovedtheconcertbutnottheopeningact

heatmap(val, words; colorscheme=ColorSchemes.inferno)

Ilovedtheconcertbutnottheopeningact

Mapping values onto the color scheme

To map values onto a color scheme, we first need to normalize all values to the range $[0,1]$.

For this purpose, two presets are available through the rangescale keyword argument:

:extrema: normalize to the minimum and maximum value of the explanation
:centered: normalize to the maximum absolute value of the explanation. Values of zero will be mapped to the center of the color scheme.

Depending on the color scheme, one of these presets may be more suitable than the other. The default color scheme, seismic, is centered around zero, making :centered a good choice:

heatmap(val, words; rangescale=:centered)

Ilovedtheconcertbutnottheopeningact

With the seismic colorscheme, the :extrema rangescale should be avoided: Even though the word "concert" has a positive sentiment score of 0.3, it is colored in blue:

heatmap(val, words; rangescale=:extrema)

Ilovedtheconcertbutnottheopeningact

However, for the inferno color scheme, which is not centered around zero, :extrema leads to a heatmap with higher contrast.

heatmap(val, words; colorscheme=ColorSchemes.inferno, rangescale=:centered)

Ilovedtheconcertbutnottheopeningact

heatmap(val, words; colorscheme=ColorSchemes.inferno, rangescale=:extrema)

Ilovedtheconcertbutnottheopeningact

Terminal support

In the context of this documentation page and notebooks, heatmaps are rendered using HTML. TextHeatmaps.jl also supports rendering heatmaps in the terminal.

Here we use the print function to force Documenter.jl to render the heatmap as raw text:

heatmap(val, words) |> print

I loved the concert but not the opening act