Charting > Special Topics > Defining a Color Scale (colorScale)

Defining a Color Scale (colorScale)

Topics:

How to:

The colorScale property defines the colors to use for drawing the color scale for heatmap, treemap, and tagcloud charts.

You can also visualize the color transitions in a heatmap or choropleth as discrete bands. For map charts, you can also visualize the legend for map charts using bin markers. For information, see Defining a Color Scale for Heatmaps and Choropleth (colorScale).

Syntax: How to Define the Color Scale in a Treemap, Heatmap, or Tagcloud Chart 

  "colorScale": {
    "colors": ["string", "string", ..., "string"]  
},

where:

"colors": ["string", "string", ..., "string"]

Is an array of colors defined by a color name or numeric specification string. The default value is: ["#253494", "#2C7FB8", "#41B6C4", "#A1DAB4"].

Example: Defining a Color Scale

The following request generates a heatmap chart with a color scale consisting of the colors lime green, cyan, teal, and green: 

GRAPH FILE WF_RETAIL_LITE
SUM  REVENUE_US AS 'Revenue'
        GROSS_PROFIT_US AS 'Profit'
BY PRODUCT_CATEGORY
ON GRAPH PCHOLD FORMAT JSCHART
ON GRAPH SET LOOKGRAPH SPECTRAL
ON GRAPH SET STYLE *
*GRAPH_JS
"colorScale": {"colors": ["limegreen", "cyan", "teal", "green"]}
*END
ENDSTYLE
END

The output is:

The following request generates a treemap chart with a color scale consisting of the colors tan and antique white: 

GRAPH FILE WF_RETAIL_LITE
SUM GROSS_PROFIT_US COGS_US 
BY PRODUCT_CATEGORY
BY BUSINESS_REGION
ON GRAPH PCHOLD FORMAT JSCHART
ON GRAPH SET LOOKGRAPH TREEMAP
ON GRAPH SET STYLE *
*GRAPH_JS
"legend": {"visible": true},
"colorScale": {"colors": ["tan", "antiquewhite"]}   
*END
ENDSTYLE
END

The output is:

Treemap with a color scale ranging from tan to antique white

Defining a Color Scale for Heatmap and Map Charts

How to:

Three color modes for heatmaps and choropleths define the way color transitions are visualized on the chart and in the legend.

  • Continuous mode is the default visualization. In continuous mode, the colors in the color scale form a blended gradient.
  • Discrete mode visualizes the colorScale in discrete color bands. You define an array of color bands that provide start and stop values for each color. The color bands must be defined within the colorScale object.
  • Bin mode creates discrete markers on the legend for each entry in the colorScale array. This is useful when the color bands generate an unappealing legend that is hard to read.

Syntax: How to Define Discrete a Color Scale for a Heatmap or Choropleth

For discrete mode, the syntax follows. 

"colorScale": {
   "colorMode":"discrete",
   "invert": boolean,
   "colorBands":[
                 {
                  "start": value,
                  "stop": value,
                  "color": "string" 
                  },
                  .
                  .
                  .
                ]
          }

where:

"invert": boolean

Defines the order of the color bands. Valid values are:

  • true, which lists the bands from high to low.
  • false, which lists the bands from low to high. This is the default value.
"colorBands":
Is an array of start values, stop values, and colors for each color band.
"start": value

Is a number or percent string that defines where to start the color band.

"stop": value

Is a number or percent string that defines where to stop the color band.

"color": "string"

Defines the color of the band.

For continuous mode, the syntax follows.

"colorScale": {
  "colorMode": "continuous",
  "colors": ["string","string", ..., "string"]
        }

where:

"colors": ["string","string", ..., "string"]

Specify the colors to be blended.

Note: If you set the color mode to "continuous" but define color bands, the chart will be visualized in discrete mode.

Example: Defining a Discrete Set of Color Bands for a Choropleth

The following request defines a choropleth with discrete color bands.

Note: Due to their length, certain lines of code in the example below may wrap onto the next line of text. Wrapping may create breaks within strings or url references, which may cause errors when run. If you copy and paste this example, be sure to remove these line breaks before running it. 

GRAPH FILE WF_RETAIL_LITE
SUM MDN.STATE_PROV_POPULATION
BY STATE_PROV_NAME
WHERE COUNTRY_NAME EQ 'United States'
WHERE STATE_PROV_NAME NE 'Puerto Rico'
ON GRAPH PCHOLD FORMAT JSCHART
ON GRAPH SET LOOKGRAPH CHOROPLETH
ON GRAPH SET STYLE *
INCLUDE=IBFS:/FILE/IBI_HTML_DIR/javaassist/intl/EN/ENIADefault_combine.sty,$
*GRAPH_JS
"mapProperties": {
  "engine": "leaflet",
              
"leaflet": {
"initPos": { 
                  "center": [37.8, -96], 
                  "level": 4 
            },

"overlayLayers": [{
"title": "United States of America",
"dataLookup": "properties.state_name",
"layerInfo": {
"maxZoom": -1,
"minZoom": -1,
"type": "regions"
},"type": "tdg",
"url": function(){ return tdgchart.getScriptPath() + 'map/US.json'}
}],
  "controls": [
    {"control": "L.Control.Layers"},
    {
     "control": "L.Control.Scale",
     "options": {
      "imperial": true,
      "metric": true }
    }
   ], 
"baselayers": [{
   "title": "ArcGIS_World_Street_Map",
   "layerInfo": {
     "maxZoom": 17,
     "minZoom": 0,
    "attribution": function(){ 
return "&|copy; <a target='_blank' href='http://www.InformationBuilders.com'>Information Builders</a> | " + "Map Tiles: &|copy; Esri";
}
},
"url": function(){return 'http://services.arcgisonline.com/ArcGIS/rest/services/World_Street_Map/MapServer/tile/{z}/{y}/{x}';
}
   
}]    
}
},
"legend":{"visible":true},
 "colorScale": {
  "colorMode":"discrete",
  "colorBands": [
  {"start": 0, "stop": 8000000,"color":"green"},
  {"start": 8000000, "stop": 16000000,"color":"yellow"},
  {"start": 16000000, "stop": 24000000,"color":"blue"},
  {"start": 24000000, "stop": 38000000,"color":"red"}
]
}     
*END
 
ENDSTYLE
END

The chart and legend are visualized using the discrete color bands defined in the color scale, as shown on the following image:

Syntax: How to Define Color Mode Bins for a Choropleth or Bubblemap

For color mode bin, the syntax follows.

"colorScale":
  {
    "colorMode": "bin",
    "invert": boolean,
      "binMarkers":
         {
           "visible": boolean,
           "concatSymbol": "string",
           "size": number,
           "shape": "string",
           "rotation": number,
           "position": "string",
           "border":
                {
                  "width": number,
                  "color": "string",
                  "dash": "string"
                }
         }
   }

where:

"invert": boolean

Defines the order of the color bands. Valid values are:

  • true, which lists the bands from high to low.
  • false, which lists the bands from low to high. This is the default value.
"visible": boolean

Specifies whether to show the bin markers. Valid values are:

  • true, which shows the bin markers. This is the default value.
  • false, which does not show the bin markers.
"concatSymbol": "string"

Is a string that defines the symbol used in each legend label between the minimum value and maximum value for the bin. The default concatenation symbol is " ... ".

"size": number

Is the diameter of the bin marker in pixels. The default value is 8.

"shape": "string"

Is a string that specifies any standard marker shape. The default value is "square".

"rotation": number

Is a number that defines the rotation of the marker in degrees. The default value is 0 (zero).

"position": "string"

Specifies the position of the markers relative to the labels. Valid values are:

  • "left", which places the markers to the left of the labels. This is the default value.
  • "right", which places the markers to the right of the labels.
  • "bottom", which places the markers below the labels.
  • "top", which places the markers on top of the labels.
"border":

Defines the properties of the marker border.

"width": number

Is a number that defines the width of the border in pixels. The default value is 1.

"color": "string",

Is a string that defines the color of the marker border. The default value is "black".

"dash": "string"

Is a string that defines the dash style of the marker border. Specify the length of a dash in pixels followed by the length of the space between dashes in pixels. For example, dash: "1 1" generates a dotted line. The default value is " ", which generates a solid border.

Example: Using Bin Color Mode for a Choropleth

The following request uses color mode bin. The bin markers are square and 20 pixels in diameter. The concatenation symbol between the start and stop values is " -". The bin markers are beneath the bin labels and have a red border one pixel wide. The color bands are inverted so that the band representing the highest percents is on top. 

GRAPH FILE WF_RETAIL_LITE
SUM CITY_POPULATION
BY COUNTRY_NAME
WHERE COUNTRY_NAME NE 'Taiwan'
ON GRAPH PCHOLD FORMAT JSCHART
ON GRAPH SET LOOKGRAPH CHOROPLETH
ON GRAPH SET AUTOFIT ON
ON GRAPH SET STYLE *
TYPE=REPORT, CHART-LOOK=com.esri.map, $
TYPE=DATA, COLUMN=COUNTRY_NAME, BUCKET=location, $
TYPE=DATA, COLUMN=CITY_POPULATION, BUCKET=color, $
*GRAPH_JS
"legend": {"visible": true}, 
"colorScale":
      {
      "colorMode": "bin",
      "invert": true,
      "binMarkers": 
           {  
              "visible": true,
              "concatSymbol": " - ",
              "size": 20,
              "shape": "square",
              "rotation": 0,
              "position": "bottom",
                 "border": {
                     "width": 1,
                     "color": "red",
                           }
           },
      "colorBands":[
            {"start":"0%",  "stop":"10%",  "color":"#B57877"},
            {"start":"10%", "stop":"20%",  "color":"#2887A6"},
            {"start":"20%", "stop":"30%",  "color":"#7ABD66"},
            {"start":"30%", "stop":"40%",  "color":"#984EA3"},
            {"start":"40%", "stop":"100%", "color":"#4DAF4A"},
                   ]
      },
"extensions": {
"com.esri.map": {
"overlayLayers":
   [
    {
     "title": "WebFOCUS Countries Request",
     "layerType": "choropleth",
     "geometrySourceType": "esri",
     "geometryLocateField": ["Country"],
     "geometryDataField": "name",
     "url": "http://services.arcgis.com/P3ePLMYs2RVChkJx/arcgis/rest/services/World_Countries_(Generalized)/FeatureServer/0"
    }
   ],
               }
             }
*END
ENDSTYLE
END

The output is shown in the following image.

 WebFOCUS

Feedback