Syntax 1: Viewing a single palette

To display a single palette, type the palette command followed by the name of the palette. For example, to view the s1 color palette, type:

. colorpalette s1
getting-started/1.svg

The graph produced by colorpalette displays the colors as well as their names or RGB codes and, possibly, some additional information. Here is an example of a semantic palette with color codes and labels (see the lin palette):

. colorpalette lin fruits
getting-started/2.svg

Likewise, when displaying a symbol palette using symbolpalette or a line pattern palette using linepalette, the names of the symbols or line pattern definitions are shown:

. symbolpalette default
getting-started/3.svg
. linepalette default
getting-started/4.svg
[top]

Syntax 2: Viewing multiple palettes

To display multiple palettes in a single graph, type the palette command, a colon, and a list of palettes separated by forward slashes:

. symbolpalette: default / lean / tufte / pplain / pblind
getting-started/5.svg

Names/codes and labels will not be displayed in this case. Options can be specified as overall options, but also separately for each palette. The options specified separately take precedence over the global options. Example:

. colorpalette, lcolor(black) span n(6): ///
>     HCL intense / HSV intense / HCL dark, n(3) / HSV dark, n(3)
getting-started/6.svg

Graph option lcolor(black) draws black lines around the color fields, graph option span adjusts the size of the color fields such that each palette spans the full width, and palette option n() determines the size of the palettes (number of colors). Further HCL schemes are displayed in the next example, which also illustrates the effect of the vertical option:

. colorpalette, vertical n(10): ///
>     HCL blues / HCL greens / HCL oranges / HCL purples / HCL heat / HCL plasma
getting-started/7.svg
[top]

Analyzing color palettes

The colorcheck command analyzes the colors returned by colorpalette by applying grayscale conversion and color vision deficiency transformation, and by computing minimum color differences among the converted colors. The purpose of the command is to evaluate whether the colors will be distinguishable by people who suffer from color vision deficiency and also whether the colors will be distinguishable in (non-color) print. The smallest noticeable difference between two colors has a color difference value (Delta E) of 1.0. A value of, say, 10 seems a reasonable minimum difference for colors used to display different features of data. colorcheck operates on the results returned by colorpalette (Syntax 1 only) and can be applied repeatedly. Example:

. colorpalette s2, nograph

. colorcheck

                   Number of colors    =      15
                   N. of comparisons   =     105
                   CVD severity        =       1
                   Proportion of gray  =       1
                   Grayscale method    =     LCh
                   Difference metric   =     Jab

-------------------------------------------------
       Delta E |   minimum    maximum       mean 
---------------+---------------------------------
  normal sight |  13.62459   78.73655   38.02262 
  monochromacy |  .8087024   60.80997   21.24502 
 deuteranomaly |  .9332426   80.05394   32.06157 
   protanomaly |  2.739547   73.76132   32.43288 
   tritanomaly |  4.185233   64.54694   34.77509 
-------------------------------------------------
getting-started/8.svg

We see that the colors in Stata's s2 palette are sufficiently distinguishable under normal vision, but that they are problematic for black and white print or for people suffering from color vision deficiency (CVD). To better see which of the colors are difficult to distinguish, we can use the sort() option to order the colors by shading in monochromacy vision ...

. colorcheck, sort(mono)
getting-started/9.svg

... or by hue in one of the simulated CVDs:

. colorcheck, sort(deuter)
getting-started/10.svg

We can also set the degree of grayscale conversion or the severity of CVD and flip the orientation of the display:

. colorcheck, mono(0.9) cvd(0.75) vertical

                   Number of colors    =      15
                   N. of comparisons   =     105
                   CVD severity        =     .75
                   Proportion of gray  =      .9
                   Grayscale method    =     LCh
                   Difference metric   =     Jab

-------------------------------------------------
       Delta E |   minimum    maximum       mean 
---------------+---------------------------------
  normal sight |  13.62459   78.73655   38.02262 
  monochromacy |  3.477297   60.87618   22.25807 
 deuteranomaly |  3.656989   79.62343   32.19816 
   protanomaly |  6.125197    74.8825   32.57244 
   tritanomaly |   7.26585    66.5454   35.65413 
-------------------------------------------------
getting-started/11.svg
[top]

Retrieving palette elements

Retrieving colors from r()

If used in single palette mode (syntax 1), the palette commands return the definitions of the palette elements in r(). r(p) will contain a space separated list of all elements, r(p1), r(p2), etc. will contain the single elements one by one. Here is an example of a line plot using the Set1 palette from ColorBrewer:

. sysuse uslifeexp, clear
(U.S. life expectancy, 1900-1999)

. foreach v in le_wfemale le_wmale le_bfemale le_bmale {
  2.     label variable `v' `"`=substr("`:var lab `v''",18,.)'"'
  3. }

. colorpalette Set1, select(1/3 5) nograph

. return list

scalars:
                  r(n) =  4

macros:
              r(ptype) : "color"
              r(pname) : "Set1"
              r(pnote) : "categorical colors from colorbrewer2.org (Brewer et al. 2.."
            r(psource) : "http://www.personal.psu.edu/cab38/ColorBrewer/ColorBrewer.."
             r(pclass) : "qualitative"
                  r(p) : ""228 26 28" "55 126 184" "77 175 74" "255 127 0""
                 r(p4) : "255 127 0"
                 r(p3) : "77 175 74"
                 r(p2) : "55 126 184"
                 r(p1) : "228 26 28"

. line le_wfemale le_wmale le_bfemale le_bmale year, lcolor(`r(p)') ///
>     lw(*2 ..) ytitle(Life expectancy)
Code
getting-started/12.svg

Option select() is used to select specific colors from the palette. Here is another example that displays the language regions of Switzerland (using the spmap command by Maurizio Pisati; shape files and language data are from the Swiss Federal Statistical Office; the sfso palette implements some colors scheme used by the Swiss Federal Statistical Office):

. use towndata, clear

. colorpalette sfso languages, nograph

. spmap language using towns, id(_ID) fcolor(`r(p)') ocolor(`r(p)') ///
>     clmethod(unique) osize(vthin ..) ///
>     polygon(data(lakes) fcolor(ltblue*.8) ocolor(ebblue*.7) osize(vthin)) ///
>     line(data(cantons)) legend(pos(11))
Code
getting-started/13.png

In the above examples, qualitative color palettes were used because the data to be illustrated was categorical. For quantitative data, sequential or diverging color schemes are typically used. Here is an example illustrating the proportion of inhabitants who are on social welfare by Swiss municipalities, using the heat scale from the HSV palette. The scale goes from light yellow for low proportions to intense red for high proportions

. colorpalette HSV heat, n(6) reverse nograph

. spmap welfare using towns, id(_ID) fcolor(`r(p)') ocolor(`r(p)') ///
>     clmethod(custom) clbreaks(0 1 2 3 4 5 12) osize(vthin ..) ///
>     polygon(data(lakes) fcolor(ltblue*.8) ocolor(ebblue*.7) osize(vthin)) ///
>     line(data(cantons) color(gs6)) legend(pos(11)) 
Code
getting-started/14.png

Furthermore, here is an example using a polar (diverging) scheme (the pinkgreen scheme from the HCL palette). Green colors are used for below average welfare proportions, pink colors are used for above average proportions.

. summarize welfare, meanonly

. generate rd = welfare/r(mean)

. colorpalette HCL pinkgreen, n(8) reverse nograph

. spmap rd using towns, id(_ID) fcolor(`r(p)') ocolor(`r(p)') ///
>     clmethod(custom) clbreaks(0 .25 .5 .667 1 1.5 2 4 6.25) osize(vthin ..) ///
>     polygon(data(lakes) fcolor(ltblue*.8) ocolor(ebblue*.7) osize(vthin)) ///
>     line(data(cantons) color(gs6)) legend(pos(11)) 
Code
getting-started/15.png
[top]

Storing colors as globals or locals

Instead of retrieving colors from r(), you can also store the single colors as global macros using the globals() option. You can then use these globals in subsequent graph commands to select the colors. For example, here is how to make some HTML colors available as global macros (you could make all 140 HTML colors available by typing colorpalette webcolors, globals):

. colorpalette Fuchsia Tomato SteelBlue SeaShell, globals

globals:
               Fuchsia : "255 0 255"
                Tomato : "255 99 71"
             SteelBlue : "70 130 180"
              SeaShell : "255 245 238"
Code

After that, type $name to select a color, where name is the name of the global:

. sysuse auto, clear
(1978 automobile data)

. scatter trunk turn mpg weight, mc($Fuchsia $Tomato $SteelBlue) ///
>     graphr(color($SeaShell))
Code
getting-started/17.svg

The defined globals will remain in memory until you restart Stata.

Depending on context (e.g., within a do-file or program), it may also be convenient to make colors available as local macros using the locals() option. Example:

. colorpalette Accent, locals

locals:
                     1 : "127 201 127"
                     2 : "190 174 212"
                     3 : "253 192 134"
                     4 : "255 255 153"
                     5 : "56 108 176"
                     6 : "240 2 127"
                     7 : "191 91 23"
                     8 : "102 102 102"

. scatter trunk turn mpg weight, mc(`1' `2' `3')
Code
getting-started/18.svg

The locals will remain in memory until the do-file or program concludes.

How the globals or locals are named depends on whether a selected palette provides color names or not. Furthermore, you can assign custom names as well as a prefix and suffix; see the description in the help file.

[top]

Making colors permanently available

To make new colors available permanently, use the stylefiles() option. This will cause RGB color definitions to be stored in style files on disk (one file for each color), from where Stata will read the color definitions (if the graph system has already been loaded, that is, if you already produced a graph in the current session, you will need to clear the graph memory before the stored colors become available; use discardor clear all to flush the working memory). The color names can then be used just like Stata's official color names. Example:

. colorpalette Fuchsia Tomato SteelBlue SeaShell, stylefiles
directory style does not exist
press any key to create the directory, or Break to abort

color styles:
               Fuchsia : "255 0 255"
                Tomato : "255 99 71"
             SteelBlue : "70 130 180"
              SeaShell : "255 245 238"

(style files written to directory style)

. discard

. sysuse auto, clear
(1978 automobile data)

. scatter trunk turn mpg weight, mc(Fuchsia Tomato SteelBlue) ///
>     graphr(color(SeaShell))
Code
getting-started/19.svg

colorpalette will store the style files in folder "style" in the current working directory:

. dir style

total 32
-rw-r--r--  1 jann  staff  19 Apr  3 13:22 color-Fuchsia.style
-rw-r--r--  1 jann  staff  21 Apr  3 13:22 color-SeaShell.style
-rw-r--r--  1 jann  staff  20 Apr  3 13:22 color-SteelBlue.style
-rw-r--r--  1 jann  staff  19 Apr  3 13:22 color-Tomato.style
Code

That is, the color definitions will be found by Stata as long as you do not change the working directory. I will now delete the style files because I don't want to keep them on my system:

. erase style/color-Fuchsia.style

. erase style/color-SeaShell.style

. erase style/color-SteelBlue.style

. erase style/color-Tomato.style

. rmdir style
Code

To make the colors permanently available irrespective of the working directory, type sylefiles(, personal). In this case the style files will be stored in folder "style" within the PERSONAL ado-file directory; see help sysdir.

[top]

Immediate palettes

Named colors

Instead of using a named palette you can provide a custom palette by specifying a list of colorstyles (named colors or, e.g., RBG colors specified as "# # #"). Here is an example displaying all named colors as listed in colorstyle (excluding black, white, and gray scales):

. colorpalette blue bluishgray brown cranberry cyan dimgray dkgreen dknavy  ///
>     dkorange eggshell emerald forest_green gold gray green khaki lavender ///
>     lime ltblue ltbluishgray ltkhaki magenta maroon midblue midgreen mint ///
>     navy olive olive_teal orange orange_red pink purple red sand sandb    ///
>     sienna stone teal yellow ebg ebblue edkblue eltblue eltgreen emidblue ///
>     erose, title(Named Stata colors)
Code
getting-started/22.svg

In addition to official Stata's named colors, colorpalette also supports 140 named HTML colors as listed at www.w3schools.com as well as various colors from W3.CSS. Example:

. colorpalette SlateBlue PaleVioletRed LightSeaGreen SandyBrown ///
>     w3-purple w3-lime w3-deep-orange, title(Some HTML and W3.CSS colors)
getting-started/23.svg
[top]

Color codes

Various input formats are available. Apart from RGB codes, for example, you can specify colors using hex triplets. Here's an example displaying (approximate) FS 595 Safety Colors:

. colorpalette #bd1e24 #e97600 #f6c700 #007256 #0067a7 #964f8e, rows(6) ///
>     title(Colors specified as hex triplets)
getting-started/24.svg

As another example, HCL colors can be provided as "HCL # # #", where the first number specifies the hue (dominant wavelength in degrees of the 360 degree color wheel), the second number specifies the chroma (colorfulness) and the third number specifies the luminance (brightness). colorpalette will translate the HCL colors to RGB. Example:

. colorpalette "HCL 0 100 70" "HCL 120 100 70" "HCL 240 100 70", ///
>     title(Colors specified using HCL codes)
getting-started/25.svg

For further details see colorlist in the help file for colorpalette.

[top]

Color intensity gradients

Various palette options are available that can be applied to the specified colors to transform the colors or to generate additional colors. The following example illustrates how a color gradient can be generated using the intensity() option (alternatively, you can also use option intensify(); the difference is that intensity() adds intensity-adjustment operators to the colors, whereas intensify() computes intensity-adjusted RGB codes):

. colorpalette #bd1e24, intensity(0.1(.05)1)
getting-started/26.svg

Likewise, you could also generate an opacity gradient using opacity() (Stata 15 or newer required), or gradients in terms of saturation (colorfulness) and luminance (brightness), see options saturate() and luminate():

. colorpalette, lcolor(black): ///
>       #bd1e24, saturate(20(10)100, level) name(Saturation 20-100) ///
>     / #bd1e24, luminate(20(10)100, level) name(Luminance 20-100)
getting-started/27.svg
[top]

Color interpolation

In general, a very useful option to generate color ramps is the ipolate() option (further examples):

. colorpalette: Purple Gold, ipolate(15, power(1.5)) ///
>             / DarkCyan FloralWhite DarkGoldenRod, ipolate(15) 
getting-started/28.svg
[top]

Custom palettes

If you want to create a personal named color palette, you can define a program called colorpalette_myname, where myname is the name of your palette. Your program should return the color definitions (e.g. RGB values or hex codes) as a comma-separated list in local macro P. In addition you may, for example, provide a comma-separated list of descriptions in local macro I. For example, the following program provides a palette called bootstrap3 containing the semantic colors used for buttons in Bootstrap v3.3:

. capture program drop colorpalette_bootstrap3

. program colorpalette_bootstrap3
  1.     c_local P #ffffff,#337ab7,#5cb85c,#5bc0de,#f0ad4e,#d9534f, ///
>               #e6e6e6,#286090,#449d44,#31b0d5,#ec971f,#c9302c
  2.     c_local I default,primary,success,info,warning,danger,default.focus, ///
>         primary.focus,success.focus,info.focus,warning.focus,danger.focus
  3. end

. colorpalette bootstrap3, rows(6)
Code
getting-started/29.svg

Likewise, a named symbol palette can be provided in program symbolpalette_myname, and a named line patter palette can be provided in program linepalette_myname. Here is a line pattern example:

. program linepalette_morse
  1.     c_local P .-###,-...###,-.-.###,-..###
  2.     c_local I A,B,C,D
  3. end

. linepalette morse
Code
getting-started/30.svg