{"id":76991,"date":"2017-05-23T07:00:12","date_gmt":"2017-05-23T07:00:12","guid":{"rendered":"http:\/\/www.esri.com\/arcgis-blog\/products\/product\/uncategorized\/creating-a-predominance-visualization-with-arcade\/"},"modified":"2024-11-11T12:39:59","modified_gmt":"2024-11-11T20:39:59","slug":"creating-a-predominance-visualization-with-arcade","status":"publish","type":"blog","link":"https:\/\/www.esri.com\/arcgis-blog\/products\/arcade\/mapping\/creating-a-predominance-visualization-with-arcade","title":{"rendered":"Creating a predominance visualization with Arcade"},"author":6561,"featured_media":0,"parent":0,"menu_order":0,"comment_status":"closed","ping_status":"closed","template":"","format":"standard","meta":{"_acf_changed":false,"_searchwp_excluded":""},"categories":[777102,22941],"tags":[32551,32521,30111,24921,27491,33531,28531,26521],"industry":[],"product":[36831,36601],"class_list":["post-76991","blog","type-blog","status-publish","format-standard","hentry","category-arcade","category-mapping","tag-arcade","tag-arcade-expressions","tag-data-visualization","tag-javascript","tag-jsapi4","tag-predominance","tag-renderer","tag-visualization","product-js-api-arcgis","product-developers"],"acf":{"short_description":"At the March 2017 Esri Developer Summit, Dave Bayer and I gave a presentation on how to use Arcade expressions in web apps built on the A...","flexible_content":[{"acf_fc_layout":"content","content":"

At the March 2017 Esri Developer Summit, Dave Bayer and I gave a presentation on how to use Arcade expressions in web apps<\/a> built on the ArcGIS platform. In that presentation I demonstrated a succinct way to create a predominance visualization<\/a> using Arcade<\/a>. <\/p>\n

Visualizing predominance involves coloring a layer’s features based on which attribute among a set of competing numeric attributes wins or beats the others in total count. Common applications of this include visualizing election results<\/a>, survey results<\/a>, and demographic majorities<\/a>.<\/p>\n

Arcade is a good solution for predominance visualizations because it allows you to avoid creating new fields in a service for storing the predominant category and the margin of victory. With Arcade, you write the expression and it will return the values at runtime, allowing you to drive the color of the visualization based on the predominant category.<\/p>\n

In our Dev Summit presentation I shared this webmap<\/a>, which depicts the predominant educational attainment achieved by people in Mexico on the municipal level.<\/p>\n

\"\"<\/a><\/p>\n

The expression used to create the visualization looks like this:<\/p>\n

\r\n\/\/ Calculate values based on attribute fields<\/span>\r\nvar<\/span> primary = $feature.EDUC04_CY + $feature.EDUC07_CY;\r\nvar<\/span> secondary = $feature.EDUC06_CY + $feature.EDUC08_CY;\r\nvar<\/span> highSchool = $feature.EDUC09_CY + $feature.EDUC11_CY;\r\nvar<\/span> college = $feature.EDUC10_CY + $feature.EDUC12_CY\r\n              + $feature.EDUC13_CY+$feature.EDUC14_CY\r\n              + $feature.EDUC15_CY;\r\n\r\n\/\/ pass all values to an array<\/span>\r\nvar<\/span> fields = [ $feature.EDUC01_CY, $feature.EDUC02_CY,\r\n               $feature.EDUC03_CY, $feature.EDUC05_CY,\r\n                primary, secondary,highSchool,college ];\r\n\r\n\/\/ get the max or winner<\/span>\r\nvar<\/span> winner = Max(fields);\r\n\r\n\/\/ return the string describing the winning value<\/span>\r\nreturn<\/span> Decode(winner,\r\n  $feature.EDUC01_CY, \"Didn't attend any school\"<\/span>,\r\n  $feature.EDUC02_CY, \"Preschool\"<\/span>,\r\n  $feature.EDUC03_CY, \"Incomplete elementary school\"<\/span>,\r\n  primary, \"Elementary school\"<\/span>,\r\n  $feature.EDUC05_CY, \"Incomplete middle school\"<\/span>,\r\n  secondary, \"Middle school\"<\/span>,\r\n  highSchool, \"High school\"<\/span>,\r\n  college, \"College\"<\/span>, \"Other\"<\/span>);\r\n<\/pre>\n
Once you understand Arcade’s syntax<\/a> and what the Decode()<\/a> function is doing, the expression is pretty straightforward to read. Decode is an Arcade function that matches a value (usually feature attribute) to another value among a set of potential matches. Each of the potential matches is paired with other values (usually a string) that describes it. In essence, it matches a value with a meaningful description. In this case, the input value to match is the maximum value of those field values\/expressions in the provided array. All values in the array are passed to the Decode<\/code> function along with matching strings describing what the value represents. So the string matching the max will always be returned. It’s slick, compact, and simple to use with any dataset.<\/p>\n
An alternate approach<\/h2>\n
However, one user at our presentation asked a great question: \u201cWhat if there\u2019s a tie for the top category?\u201d The answer we gave is that Decode will return the first<\/strong> match in the case of duplicate winners. While ties are relatively common in the datasets I\u2019ve looked at, very few of them involved the max value. Nevertheless, the Decode approach is flawed and doesn\u2019t address the real question: \u201cHow do we visualize ties for the top category?\u201d <\/p>\n
The solution I eventually came up takes advantage of Arcade\u2019s ability to write custom functions<\/a>. After testing the revised expression with several datasets, I found it easier to work with and the solution for dealing with tied max values satisfactory:<\/p>\n
\r\nvar<\/span> primary = $feature.EDUC04_CY + $feature.EDUC07_CY;\r\nvar<\/span> secondary = $feature.EDUC06_CY + $feature.EDUC08_CY;\r\nvar<\/span> highSchool = $feature.EDUC09_CY + $feature.EDUC11_CY;\r\nvar<\/span> college = $feature.EDUC10_CY + $feature.EDUC12_CY\r\n              + $feature.EDUC13_CY+$feature.EDUC14_CY\r\n              + $feature.EDUC15_CY;\r\n\r\n\/\/ The fields from which to calculate predominance<\/span>\r\n\/\/ The expression will return the alias of the predominant field<\/span>\r\n\r\nvar<\/span> fields = [\r\n  { value: $feature.EDUC01_CY, alias: \"Didn't attend any school\"<\/span> },\r\n  { value: $feature.EDUC02_CY, alias: \"Preschool\"<\/span> },\r\n  { value: $feature.EDUC03_CY, alias: \"Incomplete elementary school\"<\/span> },\r\n  { value: primary, alias: \"Elementary school\"<\/span> },\r\n  { value: $feature.EDUC05_CY, alias: \"Incomplete middle school\"<\/span> },\r\n  { value: secondary, alias: \"Middle school\"<\/span> },\r\n  { value: highSchool, alias: \"High school\"<\/span> },\r\n  { value: college, alias: \"College\"<\/span> }\r\n];\r\n\r\n\/\/ Returns the predominant category as the alias<\/span>\r\n\/\/ defined in the fields array. If there is a tie,<\/span>\r\n\/\/ then both names are concatenated and used to<\/span>\r\n\/\/ indicate the tie<\/span>\r\n\r\nfunction<\/span> getPredominantCategory<\/span>(fieldsArray<\/span>)<\/span>{\r\n  var<\/span> maxValue = -Infinity<\/span>;\r\n  var<\/span> maxCategory = \"\"<\/span>;\r\n  for<\/span>(var<\/span> k in<\/span> fieldsArray){\r\n    if<\/span>(fieldsArray[k].value > maxValue){\r\n      maxValue = fieldsArray[k].value;\r\n      maxCategory = fieldsArray[k].alias;\r\n    } else<\/span> if<\/span> (fieldsArray[k].value == maxValue){\r\n      maxCategory = maxCategory + \"\/\"<\/span> + fieldsArray[k].alias;\r\n    }\r\n  }\r\n  return<\/span> IIF(maxValue <= 0<\/span>, null<\/span>, maxCategory);\r\n}\r\n\r\ngetPredominantCategory(fields);\r\n<\/pre>\n
The getPredominantCategory()<\/code><\/strong> function returns the alias of the max category as defined in the fieldsArray<\/code><\/strong>. Notice that if a tie value is encountered for the max value, then the aliases of all fields involved with the tie are concatenated and returned. <\/p>\n
The results<\/h2>\n
Let’s take a look at how well this approach works using the Arcade playground<\/a>. I entered dummy field values representing the number of votes cast for three political parties in a fictitious feature and ran the expression. It correctly returned the maximum value.<\/p>\n
\"\"<\/a><\/p>\n
If the two lower values were tied, the same result was correctly returned since they don’t involve the maximum value.<\/p>\n
\"\"<\/a><\/p>\n
If two values were tied for first place, both aliases were returned as a concatenated string.<\/p>\n
\"\"<\/a><\/p>\n
In the unlikely event of a three-way tie, the expression even works in that scenario.<\/p>\n
\"\"<\/a><\/p>\n
And what if if all fields have the value of zero? It doesn’t seem right to visualize a tie since no votes were cast within the given feature. So the expression returns null<\/code>, which will indicate to the layer’s renderer to not bother with visualizing the feature.<\/p>\n
\"\"<\/a><\/p>\n
But how does this approach change the visualization of the educational attainment dataset in Mexico? As a whole, the visualization didn’t change much. If we open up the “change style” options in the ArcGIS Online map viewer, we can compare the categories and their total counts between each method used.<\/p>\n
\"\"<\/a><\/p>\n
Two unique tie situations were found among six municipalities where ties existed for the max value of the fields. Notice that the map viewer allows you to group values. So if you have a bunch of unique tie scenarios, you can group them into the “Other” category and rename it to “tie” so they are visualized with the same symbol. <\/p>\n
\"\"<\/a><\/p>\n
If building the visualization in a custom app with the ArcGIS API for JavaScript, you would use a UniqueValueRenderer<\/a> and just set the defaultSymbol<\/a> and defaultLabel<\/a> to this generic value. Then you won’t need to specify each tie scenario in the uniqueValueInfos<\/a> of the renderer.<\/p>\n
Interestingly, three of the six ties occurred in the same region. We’ll zoom to northwestern Oaxaca to get a better look at comparing the different visualizations for each method. The labels on each feature indicate the % gap or margin between the top two competing fields. I’ve circled the features in black where the gap is 0% (or where a tie exists).<\/p>\n
Decode methodology – no ties indicated<\/strong><\/p>\n
Notice that the features with ties incorrectly indicate a clear winner.<\/p>\n
\"\"<\/a><\/p>\n
Custom function methodology – unique ties indicated<\/strong><\/p>\n
Unique ties are visualized with different colors.<\/p>\n
\"\"<\/a><\/p>\n
Custom function methodology – all ties generically indicated<\/strong><\/p>\n
All ties are visualized with the same color after grouping them together.<\/p>\n
\"\"<\/a><\/p>\n
Methods for indicating strength of predominance<\/h2>\n
I’ve used two different methods for visualizing the strength of the predominant value, or the overall dominance of the winner. They’re explained in more depth in the session video<\/a> so I won’t go into too much depth describing the logic of the Arcade syntax used. <\/p>\n
The concept is that we’ll change the opacity value of each feature based on how convincing the win was between the competing values. This tells another side of the story, especially in the case of elections and survey results.<\/p>\n
Opacity can be driven by field values or Arcade expressions by clicking the “Attribute Values” link in the “Change style” options of ArcGIS Online.<\/p>\n
\"\"<\/a><\/p>\n
Strength<\/h3>\n
The first method I simply call “strength of predominance”. It compares the value of the winner to all other values and returns its strength as a percentage:<\/p>\n
\r\nvar<\/span> primary = $feature.EDUC04_CY + $feature.EDUC07_CY;\r\nvar<\/span> secondary = $feature.EDUC06_CY + $feature.EDUC08_CY;\r\nvar<\/span> highSchool = $feature.EDUC09_CY + $feature.EDUC11_CY;\r\nvar<\/span> college = $feature.EDUC10_CY + $feature.EDUC12_CY+$feature.EDUC13_CY\r\n              +$feature.EDUC14_CY+$feature.EDUC15_CY;\r\n\r\nvar<\/span> fields = [ $feature.EDUC01_CY, $feature.EDUC02_CY,\r\n               $feature.EDUC03_CY, $feature.EDUC05_CY,\r\n                primary, secondary, highSchool, college ];\r\nvar<\/span> winner = Max(fields);\r\nvar<\/span> total = Sum(fields);\r\nreturn<\/span> (winner\/total)*100<\/span>;\r\n<\/pre>\n
The percentage is then used to drive the opacity of each feature. The Smart mapping API<\/a> will provide good default breakpoints for the opacity values.<\/p>\n
\"\"<\/a><\/p>\n
Notice that features where ties exist can have varying levels of strength. In the image above, the northern-most circled feature has two attributes with high values that are tied. The competing field values might look something like this: [40, 40, 10, 4, 2, 1, 1, 0]<\/code>. The strength expression would return 40%. The max of this feature is likely higher than the max in most other features; thus the feature is more opaque even though a tie exists.<\/p>\n
The southern-most circled feature may have the following values for its competing categories: [20, 20, 19, 19, 10, 8, 3, 1]<\/code>. The strength expression would return 20%. The max is relatively low compared to the max value of other features, thus resulting in the vary transparent color.<\/p>\n
Gap<\/h3>\n
The “Gap” methodology only compares the max value with the second highest value. The resulting value indicates how much the winning feature won by, also know as the “margin of victory”.<\/p>\n
\r\nvar<\/span> primary = $feature.EDUC04_CY + $feature.EDUC07_CY;\r\nvar<\/span> secondary = $feature.EDUC06_CY + $feature.EDUC08_CY;\r\nvar<\/span> highSchool = $feature.EDUC09_CY + $feature.EDUC11_CY;\r\nvar<\/span> college = $feature.EDUC10_CY+$feature.EDUC12_CY\r\n             + $feature.EDUC13_CY + $feature.EDUC14_CY \r\n             + $feature.EDUC15_CY;\r\n\r\nvar<\/span> fields = [ $feature.EDUC01_CY, $feature.EDUC02_CY,\r\n              $feature.EDUC03_CY, $feature.EDUC05_CY,\r\n              primary, secondary,highSchool,college ];\r\n\r\nvar<\/span> order = Reverse(Sort(fields));\r\nvar<\/span> winner = order[0<\/span>];\r\nvar<\/span> secondPlace = order[1<\/span>];\r\nvar<\/span> total = Sum(fields);\r\nreturn<\/span> Round(((winner - secondPlace) \/ total) * 100<\/span>, 2<\/span>);\r\n<\/pre>\n
In this scenario, the tied features will always have a transparent fill.<\/p>\n
\"\"<\/a><\/p>\n
Summary<\/h2>\n
Arcade can be a powerful vehicle for exploring predominance visualizations among competing attributes. I mentioned a couple of expressions you can use when creating predominance visualizations. Just remember the limitations of each:<\/p>\n