help colorpalette                            http://repec.sowi.unibe.ch/stata/palettes/
---------------------------------------------------------------------------------------

Title

    colorpalette -- Color palettes


Syntax

    Syntax 1: Retrieve/display colors from one or multiple palettes

        colorpalette [argument] [, palette_options graph_options ]

    where argument is

        palette [[, palette_options] / [ palette [, palette_options] / ... ]]

    Syntax 2: Display an overview of multiple palettes

        colorpalette [, palette_options graph_options ] : pspec [ / pspec / ... ]

    where pspec is

        palette [, palette_options]

    or . to insert a gap.


    palette               Description
    ---------------------------------------------------------------------------------
    Color list
      colorlist           custom list of colors (including 140 named web colors)

    Stata palettes (view)
      s2                  15 colors as in Stata's s2color scheme; the default
      s1                  15 colors as in Stata's s1color scheme
      s1r                 15 colors as in Stata's s1rcolor scheme
      economist           15 colors as in Stata's economist scheme
      mono                15 gray scales as in Stata's monochrome schemes

    Other palettes (view)
      cblind              9 colorblind-friendly by Okabe and Ito (2002)
      plottig             15 colors as in plottig by Bischof (2017b)
      538                 6 + 7 colors as in 538 by Bischof (2017a)
      mrc                 7 colors as in mrc by Morris (2013)
      tfl                 8 colors as in tfl by Morris (2015)
      burd                9 + 4 colors as in burd by Briatte (2013)
      lean                15 gray scales as in lean by Juul (2003)
      tableau             20 categorical colors by Lin et al. (2013)

    Color generators
      hue                 evenly spaced HCL hues
      hcl | lch | jmh     HCL, LCh, or J'M'h color generator
      hsv                 HSV color generator

    Collections
      colorbrewer         ColorBrewer palettes from colorbrewer2.org
      viridis             perceptually uniform colormaps from matplotlib.org
      matplotlib          other colormaps from matplotlib.org
      ptol                color schemes from Tol (2012)
      d3                  categorical color schemes from D3.js
      lin                 semantic colors schemes by Lin et al. (2013)
      spmap               color schemes from spmap by Pisati (2007)
      sfso                color schemes used by the Swiss Federal Statistical Office

    Custom
      myname              custom palette provided by program colorpalette_myname
      mata(name)          custom palette provided by ColrSpace object name
    ---------------------------------------------------------------------------------


    palette_options       Description
    ---------------------------------------------------------------------------------
    Main
      n(#)                size of the palette (number of colors)
      select(numlist)     select (and order) the colors
      order(numlist)      order the colors
      reverse             arrange palette in reverse order
      opacity(numlist)    set opacity, in percent
      intensity(numlist)  set color intensity multipliers
      ipolate(spec)       interpolate the colors
      intensify(numlist)  modify intensity
      saturate(spec)      modify saturation (colorfulness)
      luminate(spec)      modify luminance (brightness)
      gscale[(spec)]      convert to grayscale
      cblind[(spec)]      simulate color vision deficiency
      other               palette-specific options

    Technical
      forcergb            enforce translation to RGB
      noexpand            omit automatic interpolation/recycling
      class(class)        set palette class
    ---------------------------------------------------------------------------------


    graph_options         Description
    ---------------------------------------------------------------------------------
    Main
      title(string)       custom graph title
      nunumbers           omit color IDs
      gropts(options)     options passed through to graph command

    Syntax 1 only
      rows(#)             minimum number of rows; default is 5
      names               print names instead of codes (if available)
      nograph             do not generate a graph

    Syntax 2 only
      horizontal          horizontal plot; the default
      vertical            vertical plot
      span                use all available space for each palette
      labels(strlist)     custom palette labels
      lcolor(colorstyle)  custom outline color
      lwidth(lwstyle)     custom outline thickness
    ---------------------------------------------------------------------------------


Description

    colorpalette is a utility command to retrieve or display color palettes. Palette
    entries are returned in r().

    colorpalette is used by grstyle set.

    colorpalette requires version 14.2 of Stata or newer. Users of older Stata
    versions can use command colorpalette9, which has limited functionality but runs
    under Stata 9.2 or newer.

    colorpalette requires the colrspace package to be installed; type ssc install
    colrspace.


Options

        +-----------------+
    ----+ Palette options +----------------------------------------------------------

    n(#) specifies the size of the palette (the number of colors). Many palettes,
        such as, e.g., the color generators or the sequential and diverging
        ColorBrewer palettes, are adaptive to n() in the sense that they return
        different colors depending on n(). Other palettes, such as s2, contain a
        fixed set of colors. If n() is different from the (maximum or minimum) number
        of colors returned by a palette, the colors are either recycled or
        interpolated, depending on the class of palette; see option class() below. To
        prevent automatic recycling/interpolation, specify option noexpand (see
        below).

    select(numlist) selects (and reorders) the colors retrieved from the palette.
        Positive numbers refer to positions from the start; negative numbers refer to
        positions from the end. Only one of select() and order() is allowed.

    order(numlist) reorders the colors. Positive numbers refer to positions from the
        start; negative numbers refer to positions from the end. Colors not covered
        in numlist will be placed last, in their original order. Only one of select()
        and order() is allowed.

    reverse returns the colors in reverse order.

    opacity(numlist) sets the opacity level(s) (0: fully transparent, 100: fully
        opaque; Stata 15 required). Specify multiple values to use different opacity
        levels across the colors. If the number of specified opacity levels is
        smaller than the number of colors, the levels will be recycled; if the number
        of opacity levels is larger than the number of colors, the colors will be
        recycled. To skip assigning opacity to a particular color, you may set the
        corresponding element to . (missing). opacity() will be applied after n(),
        select(), order(), and reverse have been applied.

    intensity(numlist) sets the color intensity adjustment multipliers.  The values
        in numlist must be between 0 and 255. Values below 1 make the colors lighter;
        values larger than 1 make the colors darker (although the allowed scale goes
        up to 255, values as low as 5 or 10 may already make a color black). Specify
        multiple values to assign different multipliers across the colors. If the
        number of specified multipliers is smaller than the number of colors, the
        multipliers will be recycled; if the number of multipliers is larger than the
        number of colors, the colors will be recycled. To skip assigning an intensity
        multiplier to a particular color, you may set the corresponding element to .
        (missing).  intensity() will be applied after n(), select(), order(), and
        reverse have been applied.

        Example: colorpalette "189 30 36", intensity(0.1(.05)1)

    ipolate(n[, suboptions]) interpolates the colors to a total of n colors.
        ipolate() will be applied after n(), select(), order(), reverse, opacity(),
        and intensity() have been applied (intensity multipliers and opacity levels,
        if defined, will also be interpolated).

        Example: colorpalette cranberry dkorange, ipolate(5)

        Suboptions are as follows.

        space selects the color space in which the colors are interpolated. The
            default space is Jab (perceptually uniform CIECAM02-based J'a'b'). Other
            possibilities are, for example, RGB, lRGB, Lab, LCh, Luv, HCL, JMh, or
            HSV; see help colrspace for details.

            Example: colorpalette: #fafa6e #2a4858, ipolate(10) / #fafa6e #2a4858,
            ipolate(10, JMh)

        range(lb [ub]) sets the interpolation range, where lb and ub are the lower
            and upper bounds. The default is range(0 1). If lb is larger than ub, the
            colors are returned in reverse order. Extrapolation will be applied if
            the specified range exceeds [0,1].

            Example: colorpalette: #fafa6e #2a4858, ipolate(11, HCL) / #fafa6e
            #2a4858, ipolate(6, HCL range(0 .5))

        power(#), with # > 0, determines how the destination colors are distributed
            across the interpolation range. The default is to distribute them evenly;
            this is equivalent to power(1). A power value larger than 1 squishes the
            positions towards the lower bound. If interpolating between two colors,
            this means that the first color will dominate most of the interpolation
            range (slow to fast transition). A value between 0 and 1 squishes the
            positions towards the upper bound, thus making the second color the
            dominant color for most of the range (fast to slow transition). Another
            way to think of the effect of power() is that it moves the center of the
            color gradient up (if # > 1) or down (if 0 < # < 1).

            Example: colorpalette: #fafa6e #2a4858, ipolate(30, HCL power(1.5)) /
            #fafa6e #2a4858, ipolate(30, HCL power(0.7))

        positions(numlist) specifies the positions of the origin colors with respect
            to the interpolation range. The default is to arrange them on a regular
            grid from 0 and 1. If the number of specified positions is smaller than
            the number of origin colors, default positions are used for the remaining
            colors. If the same position is specified for multiple colors, these
            colors will be averaged before applying interpolation.

            Example: colorpalette: Black Crimson Gold, ipolate(30, position(0 .3 1))
            / Black Crimson Gold, ipolate(30, position(0 .7 1))

        padded requests padded interpolation. By default, the first color and the
            last color are taken as the end points of the interpolation range; these
            colors thus remain unchanged. Alternatively, if you specify option
            padded, the first and last colors will be interpreted as interval
            midpoints on an equally-spaced grid. This increases the interpolation
            range by half an interval on each side and causes the first color and the
            last color to be affected by the interpolation.

            Example (the difference is subtle, but the padded variant is a bit darker
            at the bottom and the top, which represents the original 11-color scale
            better than the unpadded variant):

                . colorpalette, span vertical: BrBG / BrBG, ipolate(30) / BrBG,
                  ipolate(30, padded)

    intensify(numlist) modifies the intensity of the colors. The values in numlist
        must be between 0 and 255. Values below 1 make the colors lighter; values
        larger than 1 make the colors darker (although the allowed scale goes up to
        255, values as low as 5 or 10 may already make a color black). Specify
        multiple values to apply different adjustments across the colors. If the
        number of specified values is smaller than the number of colors, the values
        will be recycled; if the number of values is larger than the number of
        colors, the colors will be recycled. To skip adjusting the intensity of a
        particular color, you may set the corresponding element to . (missing).
        intensify() will be applied after ipolate() has been applied.

        intensify() applies the same kind of intensity adjustment as implemented by
        the intensity adjustment multipliers set by intensity().  The difference
        between intensify() and intensity() is that intensity() only records the
        intensity multipliers (which are then returned as part of the color
        definitions), whereas intensify() directly applies intensity adjustment by
        transforming the RGB values. A second difference is that intensity() is
        applied before interpolation, whereas intensify() is applied after
        interpolation.

        Example: colorpalette "189 30 36", intensify(0.1(.05)1)

    saturate(numlist[, space level]) modifies the saturation (colorfulness) of the
        colors. Positive numbers will increase the chroma channel of the colors by
        the specified amount, negative numbers will reduce chroma. Specify multiple
        values to apply different adjustments across the colors. If the number of
        values is smaller than the number of colors, the values will be recycled; if
        the number of values is larger than the number of colors, the colors will be
        recycled. To skip adjusting the saturation of a particular color, you may set
        the corresponding element to . (missing). saturate() will be applied after
        ipolate() has been applied. Suboptions are as follows.

        space specifies the color space in which the colors are manipulated.
            Possible spaces are LCh (cylindrical representation of CIE L*a*b*), HCL
            (cylindrical representation of CIE L*u*v*), JCh (CIECAM02 JCh), and JMh
            (CIECAM02-based J'M'h). The default is LCh.

        level specifies that the provided numbers are levels, not differences. The
            default is to adjust the chroma values of the colors by
            adding/subtracting the specified amounts. Alternatively, if levels is
            specified, the chroma values of the colors will be set to the specified
            levels. Chroma values of typical colors lie between 0 and 100 or maybe
            150.

        Example: colorpalette: RdYlGn, saturate(25) / RdYlGn / RdYlGn, saturate(-25)

    luminate(numlist[, space level]) modifies the luminance (brightness) of the
        colors. Positive numbers will increase the luminance of the colors by the
        specified amount, negative numbers will reduce luminance. Specify multiple
        values to apply different adjustments across the colors. If the number of
        values is smaller than the number of colors, the values will be recycled; if
        the number of values is larger than the number of colors, the colors will be
        recycled. To skip adjusting the luminance of a particular color, you may set
        the corresponding element to . (missing). luminate() will be applied after
        ipolate() has been applied. Suboptions are as follows.

        space specifies the color space in which the colors are manipulated.
            Possible spaces are Lab (CIE L*a*b*), Luv (CIE L*u*v*), JCh (CIECAM02
            JCh), and JMh (CIECAM02-based J'M'h) (LCh, HCL, and Jab are also allowed,
            but result in the same colors as Lab, Luv, and JMh, respectively). The
            default is JMh.

        level specifies that the provided numbers are levels, not differences. The
            default is to adjust the luminance values of the colors by
            adding/subtracting the specified amounts. Alternatively, if levels is
            specified, the luminance values of the colors will be set to the
            specified levels. Luminance values of typical colors lie between 0 and
            100.

        Examples:

            . colorpalette: ptol, luminate(15) / ptol / ptol, luminate(-15)
            . colorpalette: blue red green, select(1 1 2 2 3 3) luminate(. 40)

    gscale[(p [, space ])] converts the colors to gray, where p in [0,1] specifies
        the proportion of gray. The default is 1 (full conversion). Suboption space
        specifies the color space in which the conversion is performed; it may be LCh
        (cylindrical representation of CIE L*a*b*), HCL (cylindrical representation
        of CIE L*u*v*), JCh (CIECAM02 JCh), and JMh (CIECAM02-based J'M'h). The
        default is LCh. Example:

            . colorpalette: s2 / s2, gscale(.5) / s2, gscale

    cblind[(severity [, type ])] simulates color vision deficiency, where severity in
        [0,1] specifies the severity of the deficiency and type specifies type of
        color vision deficiency, which may be deuteranomaly (the default),
        protanomaly, or tritanomaly. The default severity is 1 (i.e. deuteranopia,
        protanopia, or tritanopia, respectively). See Wikipedia for basic information
        on color blindness. Example:

            . colorpalette: Set1 / Set1, cblind(.5, deut) / Set1, cblind(.5, prot) /
                Set1, cblind(1, trit)

    other are additional palette-specific options. See the descriptions of the
        palettes below. Palette-specific options have to be unique, that is, they can
        only be specified once per palette. When collecting results from multiple
        palettes, palette options can be specified at the global level, to define
        default settings for all palettes, or at the local level of an individual
        palette. For general palette options, defaults set at the global level can be
        overridden by repeating an option at the local level. Such repetitions are
        not allowed for palette-specific options.

    forcergb enforces translation of all colors to RGB. By default, colorpalette does
        not translate colors specified as Stata color names or CMYK codes, because
        these specifications are understood by Stata graphics. Specify forcergb to
        return these colors as RGB values.

    noexpand omits recycling or interpolating colors if the number of requested
        colors is larger than the maximum number of colors defined in a palette.

    class(class) declares the class of the the palette, where class may be
        qualitative, sequential, diverging, or any other string. Palettes declared as
        qualitative will be recycled, all other palettes will be interpolated (if
        recycling or interpolation is necessary). Specifying class() only affects
        palettes that do not set the class as part of their definition.

        +---------------+
    ----+ Graph options +------------------------------------------------------------

    title(string) specifies a custom title for the graph.

    nonumbers suppresses the numbers identifying the colors in the graph.

    gropts(twoway_options) provides options to be passed through to the graph
        command.

    rows(#) specifies the minimum number of rows in the graph (syntax 1 only). The
        default is 5.

    names replaces the RGB values in the graph by the information found in r(p#info)
        (e.g. the color names), if such information is available (syntax 1 only).

    nograph suppresses the graph (syntax 1 only).

    horizontal displays the palettes horizontally (syntax 2 only). This is the
        default.

    vertical displays the palettes vertically (syntax 2 only).

    span adjusts the size of the color fields such that each palette spans the full
        plot region, irrespective of the number of colors (syntax 2 only).

    labels(strlist) provides custom labels for the palettes (syntax 2 only). Enclose
        labels with spaces in double quotes.

    lcolor(colorstyle) specifies a custom outline color (syntax 2 only).  The default
        is to use the same color for the outline as for the fill.

    lwidth(linewidthstyle) specifies a custom outline thickness (syntax 2 only). The
        default is lwidth(vthin).

Palettes

        +-----------+
    ----+ colorlist +----------------------------------------------------------------

    Instead of selecting a named color palette you can specify a space-separated list
    of colors using syntax

        ["]color[%#][*#]["] ...

    where %# sets the opacity (in percent; 0 = fully transparent, 100 = fully opaque;
    Stata 15 required), *# adjusts the intensity (values between 0 and 1 make the
    color lighter; values larger than one make the color darker), and color is one of
    the following:

        name               official Stata color name as listed in colorstyle
        webname            web color name as listed below
        #rrggbb            6-digit hex RGB value; white = #FFFFFF or #ffffff, navy =
                             #1A476F or #1a476f
        #rgb               3-digit abbreviated hex RGB value; white = #FFF or #fff
        # # #              RGB value in 0-255 scaling; navy = "26 71 111"
        # # # #            CMYK value in 0-255 or 0-1 scaling; navy = "85 40 0 144"
                             or ".333 .157 0 .565"
        space ...          color value in one of the color spaces supported by
                             colrspace; e.g., navy = "XYZ 5.55 5.87 15.9" or "Lab 29
                             -.4 -27.5" or "Jab 30.1 -8.9 -19" (see help colrspace
                             for more examples)

    Example: navy in 5 different ways

        . colorpalette navy "26 71 111" "85 40 0 144" "hsv 208 .766 .435" "hcl 246.6
            38.8 29"

    Example: hex colors (using colors from Bootstrap v3.3)

        . colorpalette #337ab7 #5cb85c #5bc0de #f0ad4e #d9534f

        For background information on hex colors see 
        en.wikipedia.org/wiki/Web_colors. Some websites providing collections of
        colors are www.w3schools.com/colors, htmlcolorcodes.com, or 
        www.color-hex.com).

    Example: specifying opacity and intensity adjustment

        . colorpalette "26 71 111%80" "26 71 111*.7" "26 71 111%80*.7"

    Example: web colors

        . colorpalette slate paleviolet lightsea sandy

    Supported are the standard web colors listed at www.w3schools.com. The 140 color
    names, sorted by color groups, are as follows.

    Pink colors (view):
        Pink, LightPink, HotPink, DeepPink, PaleVioletRed, MediumVioletRed

    Purple colors (view):
        Lavender, Thistle, Plum, Orchid, Violet, Fuchsia, Magenta, MediumOrchid,
        DarkOrchid, DarkViolet, BlueViolet, DarkMagenta, Purple, MediumPurple,
        MediumSlateBlue, SlateBlue, DarkSlateBlue, RebeccaPurple, Indigo

    Red and orange colors (view):
        LightSalmon, Salmon, DarkSalmon, LightCoral, IndianRed, Crimson, Red,
        FireBrick, DarkRed, Orange, DarkOrange, Coral, Tomato, OrangeRed

    Yellow colors (view):
        Gold, Yellow, LightYellow, LemonChiffon, LightGoldenRodYellow, PapayaWhip,
        Moccasin, PeachPuff, PaleGoldenRod, Khaki, DarkKhaki

    Green colors (view):
        GreenYellow, Chartreuse, LawnGreen, Lime, LimeGreen, PaleGreen, LightGreen,
        MediumSpringGreen, SpringGreen, MediumSeaGreen, SeaGreen, ForestGreen, Green,
        DarkGreen, YellowGreen, OliveDrab, DarkOliveGreen, MediumAquaMarine,
        DarkSeaGreen, LightSeaGreen, DarkCyan, Teal

    Cyan colors (view):
        Aqua, Cyan, LightCyan, PaleTurquoise, Aquamarine, Turquoise, MediumTurquoise,
        DarkTurquoise

    Blue colors (view):
        CadetBlue, SteelBlue, LightSteelBlue, LightBlue, PowderBlue, LightSkyBlue,
        SkyBlue, CornflowerBlue, DeepSkyBlue, DodgerBlue, RoyalBlue, Blue,
        MediumBlue, DarkBlue, Navy, MidnightBlue

    Brown colors (view):
        Cornsilk, BlanchedAlmond, Bisque, NavajoWhite, Wheat, BurlyWood, Tan,
        RosyBrown, SandyBrown, GoldenRod, DarkGoldenRod, Peru, Chocolate, Olive,
        SaddleBrown, Sienna, Brown, Maroon

    White colors (view):
        White, Snow, HoneyDew, MintCream, Azure, AliceBlue, GhostWhite, WhiteSmoke,
        SeaShell, Beige, OldLace, FloralWhite, Ivory, AntiqueWhite, Linen,
        LavenderBlush, MistyRose

    Grey colors (view):
        Gainsboro, LightGray, Silver, DarkGray, DimGray, Gray, LightSlateGray,
        SlateGray, DarkSlateGray, Black

    The color names can be abbreviated and typed in lowercase letters. If
    abbreviation is ambiguous, the first matching name in the alphabetically ordered
    list will be used. Furthermore, in case of name conflict, official Stata colors
    will take precedence over web colors; use the uppercase names as shown above to
    prevent such conflict (for example, pink will refer to official Stata pink, Pink
    will refer to web color pink).

        +----+
    ----+ s2 +-----------------------------------------------------------------------

    Palette s2 (view) contains the 15 colors used for p1 to p15 in Stata's s2color
    scheme. s2 is the default palette.

        +----+
    ----+ s1 +-----------------------------------------------------------------------

    Palette s1 (view) contains the colors used for p1 to p15 in Stata's s1color
    scheme.

        +-----+
    ----+ s1r +----------------------------------------------------------------------

    Palette s1r (view) contains the colors used for p1 to p15 in Stata's s1rcolor
    scheme.

        +-----------+
    ----+ economist +----------------------------------------------------------------

    Palette economist (view) contains the colors used for p1 to p15 in Stata's
    economist scheme.

        +------+
    ----+ mono +---------------------------------------------------------------------

    Palette mono (view) contains the gray scales used for p1 to p15 in Stata's
    monochrome schemes (s2mono, s1mono).

        +--------+
    ----+ cblind +-------------------------------------------------------------------

    The cblind palette (view) contains colorblind-friendly colors suggested by Okabe
    and Ito (2002), including gray as suggested at www.cookbook-r.com.  The same
    colors are also used (in different order and using gs10 for gray) in the
    plotplainblind and plottigblind schemes by Bischof (2017b). Type colorpalette
    cblind, select(1 2 4 5 9 8 7 3 6) for a palette equivalent to the one used in
    plotplainblind, and colorpalette cblind, select(1 4 5 9 8 7 3 6) for
    plottigblind.

        +---------+
    ----+ plottig +------------------------------------------------------------------

    Palette plottig (view) contains the colors used for p1 to p15 in the plottig
    scheme by Bischof (2017b). Most of these colors are the same as the colors
    produced by the hue color generator with default options (view), although in
    different order.

        +-----+
    ----+ 538 +----------------------------------------------------------------------

    Palette 538 (view) contains the colors used for p1 to p6, background, labels,
    axes etc., and CIs in the 538 scheme by Bischof (2017a). The palette replicates
    colors used at fivethirtyeight.com.

        +-----+
    ----+ mrc +----------------------------------------------------------------------

    Palette mrc (view) contains the colors used for p1 to p7 in the mrc scheme by
    Morris (2013). These are colors according to guidelines by the UK Medical
    Research Council.

        +-----+
    ----+ tfl +----------------------------------------------------------------------

    Palette tfl (view) contains the colors used for p1 to p8 in the tfl scheme by
    Morris (2015). The palette replicates Transport for London's corporate colors.

        +------+
    ----+ burd +---------------------------------------------------------------------

    Palette burd (view) contains the colors used for p1 to p9 and for CIs in the burd
    scheme by Briatte (2013). The p1 to p9 colors are a selection of colors from
    various ColorBrewer schemes.

        +------+
    ----+ lean +---------------------------------------------------------------------

    Palette lean (view) contains gray scales used for p1area to p15area in schemes
    lean1 and lean2 by Juul (2003).

        +---------+
    ----+ tableau +------------------------------------------------------------------

    The tableau (view) contains 20 categorical colors provided by Lin et al. (2013).
    The hex values of the colors have been taken from code provided by the authors at
    GitHub. The same colors are also used in d3.

        +-----+
    ----+ hue +----------------------------------------------------------------------

    The hue palette implements an algorithm that generates HCL colors with evenly
    spaced hues. The palette has been modeled after function hue_pal() from R's
    scales package by Hadley Wickham (see http://github.com/hadley/scales). This is
    the default color scheme used by R's ggplot2 for categorical data (see 
    http://ggplot2.tidyverse.org/reference/scale_hue.html). The hue palette with
    default options produces the same colors as the intense scheme of the hcl color
    generator.

    Syntax:

        hue [, hue(start end) chroma(#) luminance(#) direction(#) palette_options ]

    Options:

    hue(start end) sets the range of hues on the 360 degree color wheel. The default
        is hue(15 375). If the difference between start and end is a multiple of 360,
        end will be reduced by 360/n, where n is the number of requested colors (so
        that the space between the last and the first color is the same as between
        the other colors).

    chroma(#) sets the colorfulness (color intensity), with # >= 0. The default is
        chroma(100).

    luminance(#) sets the brightness (amount of gray), with # in [0, 100]. The
        default is luminance(65).

    direction(#) determines the direction to travel around the color wheel.
        direction(1), the default, travels clockwise; direction(-1) travels
        counter-clockwise.

    Examples:

        . colorpalette, span: hue, n(3) / hue, n(5) / hue, n(7) / hue, n(9)
        . colorpalette hue, n(5) hue(90 -30) chroma(50) luminance(70)

        +-------------+
    ----+ hcl/lch/jmh +--------------------------------------------------------------

    The hcl, lch, and jmh palettes are color generators in the HCL
    (Hue-Chroma-Luminance) space (cylindrical representation of CIE L*u*v*), the LCh
    space (cylindrical representation of CIE L*a*b*), and the CIECAM02-based J'M'h
    space, respectively. The hcl implementation is based on R's colorspace package by
    Ihaka et al. (2016); also see Zeileis et al. (2009) and hclwizard.org. The lch
    and jmh generators are implemented analogously.

    Let h1 and h2 be two hues on the 360 degree color wheel, c1 and c2 two chroma
    levels (M' in case of jmh), l1 and l2 two luminance levels (J' in case of jmh),
    p1 and p2 two power parameters, and i an index from 1 to n, where n is the number
    of requested colors. The colors are then generated according to the following
    formulas.

        Qualitative:
            H = h1 + (h2 - h1) * (i - 1) / (n - 1)
            C = c1
            L = l1

        Sequential:
            H = h2 - (h2 - h1) * j
            C = c2 - (c2 - c1) * j^p1
            L = l2 - (l2 - l1) * j^p2
            with j = (n - i) / (n - 1)

        Diverging:
            H = cond(j > 0, h1, h2)
            C = c1 * abs(j)^p1
            L = l2 - (l2 - l1) * abs(j)^p2
            with j = (n - 2*j + 1) / (n - 1)

    Syntax:

        {hcl|lhc|jmh} [, scheme hue(h1 [h2]) chroma(c1 [c2]) luminance(l1 [l2])
               power(p1 [p2]) palette_options ]

    Options:

    scheme picks the type of color formula (qualitative, sequential, or diverging)
        and sets the default parameter values. scheme can be one of following
        (qualitative is the default; abbreviations are allowed).

        Qualitative (view: hcl, lch, jmh)
                            h1              h2   c1   l1
        qualitative         15  h1+360*(n-1)/n   60   70
        intense             15  h1+360*(n-1)/n  100   65
        dark                15  h1+360*(n-1)/n   80   60
        light               15  h1+360*(n-1)/n   50   80
        pastel              15  h1+360*(n-1)/n   35   85

        Sequential (view: hcl, lch, jmh)
                            h1   h2   c1   c2   l1   l2   p1   p2
        sequential         260   h1   80   10   25   95    1   p1
        blues              260   h1   80   10   25   95    1   p1
        greens             145  125   80   10   25   95    1   p1
        grays                0   h1    0    0   15   95    1   p1
        oranges             40   h1  100   10   50   95    1   p1
        purples            280   h1   70   10   20   95    1   p1
        reds                10   20   80   10   25   95    1   p1
        heat                 0   90  100   30   50   90  0.2  1.0
        heat2                0   90   80   30   30   90  0.2  2.0
        terrain            130    0   80    0   60   95  0.1  1.0
        terrain2           130   30   65    0   45   90  0.5  1.5
        viridis            300   75   35   95   15   90  0.8  1.2
        plasma             100   h1   60  100   15   95  2.0  0.9
        redblue              0 -100   80   40   40   75  1.0  1.0

        Diverging (view: hcl, lch, jmh)
                            h1   h2   c1   l1   l2   p1   p2
        diverging          260    0   80   30   95    1   p1
        bluered            260    0   80   30   95    1   p1
        bluered2           260    0  100   50   95    1   p1
        bluered3           180  330   60   75   95    1   p1
        greenorange        130   45  100   70   95    1   p1
        browngreen          55  160   60   35   95    1   p1
        pinkgreen          340  128   90   35   95    1   p1
        purplegreen        300  128   60   30   95    1   p1

        The shown parameter values are for hcl; lch and jmh use adjusted values such
        that the end points of the generated colors are similar to the ones generated
        by hcl (see the source code of colorpalette.ado).

    hue(h1 [h2]) overwrites the default values for h1 and h2. h1 and h2 are hues on
        the 360 degree color wheel.

    chroma(c1 [c2]) overwrites the default values for c1 and c2, with c# >= 0. c1 and
        c2 determine the colorfulness (color intensity).

    luminance(l1 [l2]) overwrites the default values for l1 and l2, with l# in [0,
        100]. l1 and l2 determine the brightness.

    power(p1 [p2]) overwrites the default values for p1 and p2, with p# > 0. p1 and
        p2 determine the shape of the transition between chroma and luminance levels.
        For linear transitions, set p#=1; p#>1 makes the transition faster, p#<1
        makes the transition slower.

        +-----+
    ----+ hsv +----------------------------------------------------------------------

    The hsv palette is a HSV color generator (Hue-Saturation-Value). The
    implementation is partially based on R's grDevices package (which is part of the
    R core) and partially on colorspace by Ihaka et al. (2016).

    Let h1 and h2 be two hues on the 360 degree color wheel, s1 and s2 two saturation
    levels, v1 and v2 two value levels, p1 and p2 two power parameters, and i an
    index from 1 to n, where n is the number of requested colors. The HSV colors are
    then generated according to the following formulas.

        Qualitative:
            H = h1 + (h2 - h1) * (i - 1) / (n - 1)
            S = s1
            V = v1

        Sequential:
            H = h2 - (h2 - h1) * j
            S = s2 - (s2 - s1) * j^p1
            V = v2 - (v2 - v1) * j^p2
            with j = (n - i) / (n - 1)

        Diverging:
            H = cond(j > 0, h1, h2)
            S = s1 * abs(j)^p1
            V = v2 - (v2 - v1) * abs(j)^p2
            with j = (n - 2*j + 1) / (n - 1)

    Syntax:

        hsv [, scheme hue(h1 [h2]) saturation(s1 [s2]) value(v1 [v2]) power(p1 [p2])
               palette_options ]

    Options:

    scheme picks the type of color formula (qualitative, sequential, or diverging)
        and sets the default parameter values. scheme can be one of following
        (qualitative is the default; abbreviations are allowed).

        Qualitative (view)  h1              h2   s1   v1
        qualitative         15  h1+360*(n-1)/n   .4  .85
        intense             15  h1+360*(n-1)/n   .6  .9
        dark                15  h1+360*(n-1)/n   .6  .7
        light               15  h1+360*(n-1)/n   .3  .9
        pastel              15  h1+360*(n-1)/n   .2  .9
        rainbow             15  h1+360*(n-1)/n    1   1

        Sequential (view)   h1   h2   s1   s2   v1   v2   p1   p2
        sequential         240   h1   .8  .05   .6   1   1.2   p1
        blues              240   h1   .8  .05   .6   1   1.2   p1
        greens             140  120   1   .1    .3   1   1.2   p1
        grays                0   h1   0    0    .1  .95  1.0   p1
        oranges             30   h1   1   .1    .9   1   1.2   p1
        purples            270   h1   1   .1    .6   1   1.2   p1
        reds                 0   20   1   .1    .6   1   1.2   p1
        heat                 0   60   1   .2     1   1   0.3   p1
        terrain            120    0   1    0    .65 .95  0.7  1.5

        Diverging (view)    h1   h2   s1   v1   v2   p1   p2
        diverging          240    0   .8   .6  .95  1.2   p1
        bluered            240    0   .8   .6  .95  1.2   p1
        bluered2           240    0   .6   .8  .95  1.2   p1
        bluered3           175  320   .6   .8  .95  1.2   p1
        greenorange        130   40   1    .8  .95  1.2   p1
        browngreen          40  150   .8   .6  .95  1.2   p1
        pinkgreen          330  120   .9   .6  .95  1.2   p1
        purplegreen        290  120   .7   .5  .95  1.2   p1

    hue(h1 [h2]) overwrites the default values for h1 and h2. h1 and h2 are hues on
        the 360 degree color wheel.

    saturation(s1 [s2]) sets overwrites the default values for s1 and s2, with s# in
        [0, 1]. s1 and s2 determine the colorfulness (color intensity).

    value(v1 [v2]) overwrites the default values for v1 and v2, with v# in [0, 1]. l1
        and l2 determine the brightness.

    power(p1 [p2]) overwrites the default values for p1 and p2, with p# > 0. p1 and
        p2 determine the shape of the transition between saturation and value levels.
        For linear transitions, set p#=1; p#>1 makes the transition faster, p#<1
        makes the transition slower.

        +-------------+
    ----+ ColorBrewer +--------------------------------------------------------------

    ColorBrewer is a set of color schemes developed by Brewer et al. (2003; also see
    Brewer 2016). The colors are licensed under Apache License Version 2.0; see the
    copyright notes at ColorBrewer_updates.html. For more information on ColorBrewer
    also see http://colorbrewer2.org/. The RGB values for the implementation of the
    colors in colorpalette have been taken from the Excel spreadsheet provided at
    ColorBrewer_RGB.html.  The CMYK values have been taken from file cb.csv provided
    at GitHub. ColorBrewer palettes for Stata are also provided by Gomez (2015) and
    by Buchanan (2015).

    The syntax for the ColorBrewer palettes is

        scheme [, cmyk palette_options ]

    where scheme is one of the following

        Qualitative (view)
        Accent       8 accented colors for qualitative data
        Dark2        8 dark colors for qualitative data
        Paired       12 paired colors for qualitative data
        Pastel1      9 pastel colors for qualitative data
        Pastel2      8 pastel colors for qualitative data
        Set1         9 colors for qualitative data
        Set2         8 colors for qualitative data
        Set3         12 colors for qualitative data

        Sequential (single hue) (view)
        Blues        light blue to blue (3-9 colors)
        Greens       light green to green (3-9 colors)
        Greys        light gray to gray (3-9 colors)
        Oranges      light orange to orange (3-9 colors)
        Purples      light purple to purple (3-9 colors)
        Reds         light red to red (3-9 colors)

        Sequential (multi-hue) (view)
        BuGn         light blue to green (3-9 colors)
        BuPu         light blue to purple (3-9 colors)
        GnBu         light green to blue (3-9 colors)
        OrRd         light orange to red (3-9 colors)
        PuBu         light purple to blue (3-9 colors)
        PuBuGn       light purple over blue to green (3-9 colors)
        PuRd         light purple to red (3-9 colors)
        RdPu         light red to purple (3-9 colors)
        YlGn         light yellow to green (3-9 colors)
        YlGnBu       light yellow over green to blue (3-9 colors)
        YlOrBr       light yellow over orange to brown (3-9 colors)
        YlOrRd       light yellow over orange to red (3-9 colors)

        Diverging (view)
        BrBG         brown to green, light gray mid (3-11 colors)
        PiYG         pink to green, light gray mid (3-11 colors)
        PRGn         purple to green, light gray mid (3-11 colors)
        PuOr         purple to orange, light gray mid (3-11 colors)
        RdBu         red to blue, light gray mid (3-11 colors)
        RdGy         red to gray, white mid (3-11 colors)
        RdYlBu       red to blue, yellow mid (3-11 colors)
        RdYlGn       red to green, yellow mid (3-11 colors)
        Spectral     red - orange - yellow - green - blue (3-11 colors)

    and option cmyk requests the CMYK variant of the scheme. The default is to use
        the RGB variant.

        +---------+
    ----+ viridis +------------------------------------------------------------------

    The viridis collection provides perceptually uniform colormaps from matplotlib, a
    Python 2D plotting library (Hunter 2007). The color values have been taken from
    file _cm_listed.py at GitHub.

    The syntax for the viridis palettes is

        colormap [, range(lb [ub]) shifted palette_options ]

    where colormap is one of the following (view).

        viridis      blue - green - yellow (sequential)
        plasma       blue - red - yellow (sequential)
        inferno      black - blue - orange - yellow (sequential)
        magma        black - blue - red - yellow (sequential)
        cividis      blue - olive - yellow (sequential)
        twilight     blue - russet (diverging)

    Options:

    range(lb [ub]) selects the range of the colormap to be used, where lb and ub must
        be in [0,1]. The default is range(0 1). If lb is larger than ub, the colors
        are returned in reverse order.

    shifted only has an effect on twilight and shifts the color pattern from light
        extremes and dark in the middle to dark extremes and light in the middle.

        +------------+
    ----+ matplotlib +---------------------------------------------------------------

    The matplotlib palette provides several colormaps from matplotlib, a Python 2D
    plotting library (Hunter 2007). The definitions of the colormaps have been taken
    from file _cm.py at GitHub.

    The syntax for the matplotlib palette is

        matplotlib [, colormap range(lb [ub]) palette_options ]

    where colormap is one of the following (abbreviations allowed) (view)

        jet          blue - green - yellow - red; the default
        autumn       red - yellow
        spring       magenta - yellow
        summer       green - yellow
        winter       blue - lime
        bone         black - bluish gray - white
        cool         cyan - magenta
        copper       black - orange/brown
        coolwarm     blue - red (diverging)
        hot          heat colors

    and range(lb [ub]) selects the range of the colormap to be used, where lb and ub
    must be in [0,1]. The default is range(0 1). If lb is larger than ub, the colors
    are returned in reverse order.

        +------+
    ----+ ptol +---------------------------------------------------------------------

    The ptol collection provides color schemes suggested by Tol (2012). The syntax is

        ptol [, scheme palette_options ]

    where scheme is one of the following (abbreviations allowed) (view).

        qualitative    1-12 qualitative colors; the default
        diverging      3-11 diverging colors; very similar to reverse RdYlBu
        rainbow        4-12 rainbow colors

        +----+
    ----+ d3 +-----------------------------------------------------------------------

    The d3 collection provides color schemes from D3.js, using the color values found
    at github.com/d3. The syntax is

        d3 [, scheme palette_options ]

    where scheme is one of the following (view).

        10     10 categorical colors; the default; same as first 10 colors in tableau
        20     20 categorical colors in pairs; same colors as in tableau, but ordered
                 differently
        20b    20 categorical colors in groups of four
        20c    20 categorical colors in groups of four

        +-----+
    ----+ lin +----------------------------------------------------------------------

    The lin collection provides semantic color schemes suggested by Lin et al.
    (2013). The values of the colors have been taken from the source code of the
    brewscheme package by Buchanan (2015) (brewextra.ado, version 1.0.0, 21 March
    2016).

    The syntax is

        lin [, scheme palette_options ]

    where scheme is one of the following (abbreviations allowed):

        carcolor              6 car colors (selected by Turkers)
        carcolor algorithm    6 car colors (algorithm selected)
        food                  7 food colors (selected by Turkers)
        food algorithm        7 food colors (algorithm selected)
        features              5 feature colors (selected by Turkers)
        features algorithm    5 feature colors (algorithm selected)
        activities            5 activity colors (selected by Turkers)
        activities algorithm  5 activity colors (algorithm selected)
        fruits                7 fruit colors; the default (selected by expert)
        fruits algorithm      7 fruit colors; the default (algorithm selected)
        vegetables            7 vegetable colors (selected by expert)
        vegetables algorithm  7 vegetable colors (algorithm selected)
        drinks                7 drinks colors (selected by expert)
        drinks algorithm      7 drinks colors (algorithm selected)
        brands                7 brands colors (selected by expert)
        brands algorithm      7 brands colors (algorithm selected)

        +-------+
    ----+ spmap +--------------------------------------------------------------------

    The spmap collection provides color schemes from the spmap package by Pisati
    (2007). The implementation is based on code from spmap_color.ado (version 1.3.0,
    13 March 2017).

    The syntax is

        spmap [, scheme palette_options ]

    where scheme is one of the following (abbreviations allowed) (view):

        blues          light blue to blue (2-99 colors); the default
        greens         light green to green (2-99 colors)
        greys          light gray to black (2-99 colors)
        reds           light red to red (2-99 colors)
        rainbow        2-99 rainbow colors
        heat           2-16 heat colors
        terrain        2-16 terrain colors
        topological    2-16 topological colors

        +------+
    ----+ sfso +---------------------------------------------------------------------

    The sfso collection provides color schemes by the Swiss Federal Statistical
    Office (using hex and CMYK codes found in Bundesamt für Statistik 2017). The
    syntax is

        sfso [, scheme cmyk palette_options ]

    where scheme is one of the following

        Sequential (view)
        brown          dark brown to light brown (6 colors)
        orange         dark orange to light orange (6 colors)
        red            dark red to light red (6 colors)
        pink           dark pink to light pink (6 colors)
        purple         dark purple to light purple (6 colors)
        violet         dark violet to light violet (6 colors)
        blue           dark blue to light blue (7 colors); the default
        ltblue         lighter version of blue (6 colors)
        turquoise      dark turquoise to light turquoise (6 colors)
        green          dark green to light green (6 colors)
        olive          dark olive to light olive (6 colors)
        black          dark gray to light gray (6 colors)

        Semantic (view)
        parties        colors used by the SFSO for Swiss parties (11 colors)
        languages      colors used by the SFSO for languages (5 colors)
        votes          colors used by the SFSO for results from votes (10 colors)

    and option cmyk requests the CMYK variant of the scheme. The default is to use
        the RGB variant.

        +--------+
    ----+ myname +-------------------------------------------------------------------

    A personal named palette can be provided in form of a program called
    colorpalette_myname, where myname is the name of the palette. Palette myname will
    then be available to colorpalette like any other palette. Your program should
    return the color definitions as a comma-separated list in local macro P. In
    addition you may 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:

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

    After defining the program, you can, for example, type

        . colorpalette bootstrap3, rows(6)

    to view the palette. More complicated definitions of palettes that take account
    of options are also possible. See the palette definitions colorpalette.ado for
    examples.

        +-----------------------+
    ----+ Mata ColrSpace object +----------------------------------------------------

    colorpalette can retrieve colors from a Mata ColrSpace object. The syntax is

        mata(name) [, palette_options ]

    where name is the name the object. Example:

        . mata: C1 = C2 = ColrSpace()
        . mata: C1.palette("s2", 5)
        . mata: C1.pname("original colors")
        . mata: C2.set(C1.get("Lab") :* (1.2, 1, 1), "Lab")
        . mata: C2.pname("luminance * 1.2")
        . colorpalette: mata(C1) / mata(C2)
        . colorpalette mata(C2), cblind(0.5) title(50% deuteranomaly)


Example

    Apart from viewing color palettes, colorpalette is useful for retrieving colors
    that can then be passed through to a graph command. Here is an example of a
    contour plot using the terrain scheme from the hcl color generator:

        . sysuse sandstone, clear
        . colorpalette jmh, terrain n(10) nograph
        . twoway contour depth northing easting, levels(`r(n)') ccolors(`r(p)')


Saved results

    colorpalette stores the following in r() (Syntax 1 only):

    Scalars    
      r(n)            number of returned colors

    Macros     
      r(ptype)        color
      r(pname)        name of palette or custom
      r(pclass)       palette class (if provided)
      r(pnote)        additional information on palette (if provided)
      r(p)            space separated list of colors
      r(p#)           #th color
      r(p#info)       info of #th color (if provided)


References

    Bischof, D. 2017a. G538SCHEMES: module to provide graphics schemes for
        http://fivethirtyeight.com. Available from 
        http://ideas.repec.org/c/boc/bocode/s458404.html.
    Bischof, D. 2017b. New graphic schemes for Stata: plotplain and plottig.  The
        Stata Journal 17(3): 748–759.
    Briatte, F. 2013. SCHEME-BURD: Stata module to provide a ColorBrewer-inspired
        graphics scheme with qualitative and blue-to-red diverging colors. Available
        from http://ideas.repec.org/c/boc/bocode/s457623.html.
    Brewer, C. A., G. W. Hatchard, M. A. Harrower. 2003. ColorBrewer in Print: A
        Catalog of Color Schemes for Maps.  Cartography and Geographic Information
        Science 30(1): 5–32.
    Brewer, C. A. 2016. Designing Better Maps. A Guide for GIS Users. 2nd ed.
        Redlands, CA: Esri Press.
    Buchanan, B. 2015. BREWSCHEME: Stata module for generating customized graph
        scheme files. Available from 
        http://ideas.repec.org/c/boc/bocode/s458050.html.
    Bundesamt für Statistik 2017. Layoutrichtlinien. Gestaltungs und
        Redaktionsrichtlinien für Publikationen, Tabellen und grafische Assets.
        Version 1.1.1. Neuchâtel.
    Gomez, M. 2015. Stata command to generate color schemes. Available from 
        http://github.com/matthieugomez/stata-colorscheme.
    Hunter, J. D. 2007. Matplotlib: A 2D graphics environment. Computing in Science &
        Engineering 9(3): 90-95.
    Ihaka, R., P. Murrell, K. Hornik, J. C. Fisher, R. Stauffer, A. Zeileis.  2016.
        colorspace: Color Space Manipulation. R package version 1.3-2.  Available
        from http://CRAN.R-project.org/package=colorspace.
    Juul, S. 2003. Lean mainstream schemes for Stata 8 graphics. The Stata Journal
        3(3): 295-301.
    Lin, S., J. Fortuna, C. Kulkarni, M. Stone, J. Heer. 2013. Selecting
        Semantically-Resonant Colors for Data Visualization. Computer Graphics Forum
        32(3pt4): 401-410.
    Morris, T. 2013. SCHEME-MRC: Stata module to provide graphics scheme for UK
        Medical Research Council. Available from 
        http://ideas.repec.org/c/boc/bocode/s457703.html.
    Morris, T. 2015. SCHEME-TFL: Stata module to provide graph scheme, based on
        Transport for London's corporate colour pallette. Available from 
        http://ideas.repec.org/c/boc/bocode/s458103.html.
    Okabe, M., K. Ito. 2002. Color Universal Design (CUD). How to make figures and
        presentations that are friendly to Colorblind people. Available from 
        http://jfly.iam.u-tokyo.ac.jp/color/.
    Pisati, M. 2007. SPMAP: Stata module to visualize spatial data. Available from 
        http://ideas.repec.org/c/boc/bocode/s456812.html.
    Tol, P. 2012. Colour Schemes. SRON Technical Note, Doc. no. SRON/EPS/TN/09-002.
        Available from https://personal.sron.nl/~pault/colourschemes.pdf.
    Zeileis, A., K. Hornik, P. Murrell. 2009.  Escaping RGBland: Selecting Colors for
        Statistical Graphics.  Computational Statistics & Data Analysis 53:
        3259-3270.


Author

    Ben Jann, University of Bern, ben.jann@soz.unibe.ch

    Thanks for citing this software as

        Jann, B. (2018). Color palettes for Stata graphics. The Stata Journal 18(4):
        765-785.

    or

        Jann, B. (2017). palettes: Stata module providing color palettes, symbol
        palettes, and line pattern palettes. Available from 
        http://ideas.repec.org/c/boc/bocode/s458444.html.


Also see

    Online:  help for colrspace, colorpalette9, symbolpalette, linepalette, grstyle
             set, graph, colorstyle