arcuser

Learn ArcGIS Arcade in Four Easy Steps

Using ArcGIS Arcade, a basic scripting language from Esri, you can map the values you need or create completely new data values in minutes. Within ArcGIS Online, ArcGIS Pro, ArcGIS Runtime, and ArcGIS API for JavaScript, you can create expressions for visualization, labeling, pop-ups, calculations, and aliases.

In this exercise, you’ll write an Arcade expression to get comfortable with the interface. To follow along, open Basic Arcade Conversion: Celsius to Fahrenheit, a map I’ve shared on ArcGIS Online.

Click Modify Map at the top right of the window.

This example uses an ArcGIS Living Atlas of the World layer that shows virtual coral reef stations to help identify reefs at risk of coral bleaching. The data is in real time, meaning the data values are constantly being updated by the National Oceanic and Atmospheric Administration (NOAA). Warmer water temperatures can cause coral bleaching, so monitoring the temperature of the ocean using this data can help pinpoint reefs that are in danger. These “virtual stations” are not actual buoys or in situ stations transmitting data but rather derived reef locations from 5-kilometer- resolution raster data.

To follow along with this tip, open “Basic Arcade Conversion: Celsius to Fahrenheit,” a map I’ve shared on ArcGIS Online, and click Modify Map.

The map’s legend and the pop-up show the sea surface temperature of the virtual stations in Celsius. Celsius is a measurement that’s widely used around the world and within the scientific community, but if the people in the map audience are based in the United States, they might understand temperature better in Fahrenheit.

Because the data comes from a live feed that is updated regularly and the layer is owned by someone else, Arcade is the perfect tool for adjusting this map to degrees of Fahrenheit. The conversion from Celsius to Fahrenheit is a simple equation:

F = C x 1.8 + 32

You can convert this data value quickly using Arcade, and because the data is updated in the layer, your map will always reflect the newest values. Let’s get started!

Step 1:

Create a New Expression

In many of the places where you use data attributes in your maps, such as symbology, you’ll find an option to use an expression.

To use an expression for the map’s symbology, first go into the Change Style options for the Coral Reef Stations – Original layer under Contents.

Select the drop-down arrow to see the layer’s attributes. At the bottom, click New Expression to open the expression window.

Under Expression, write the Arcade expression. By default, a sample expression appears that is shown in comments denoted by //.

The expression window will appear, and at the top of the window you will see the default name of the expression: Custom. This will appear in the map’s legend, so it is a best practice to first name your expression something meaningful so that your map reader will understand what they are seeing.

Click Edit next to Custom and rename it “Sea Surface Temperature (F)”, then click Save.

Under Expression, write the Arcade expression. By default, a sample expression appears that is shown in comments denoted by //. You can delete this sample when writing your own expressions.

Step 2:

Use an Attribute from the Layer to Calculate a New Value

Take a closer look at the expression window to better understand how to use it. On the right side of the window, you’ll see the list of fields from your data under the Globals tab. They have $feature in front of the field name, which means that Arcade will process the expression for each feature in the map. When working with Arcade within pop-ups, you’ll see additional Globals such as $map, which is used for accessing data from other layers in a map using a function called FeatureSet().

On the Globals tab, find the attribute field for Sea Surface Temperature (C). Click $feature.sst to add it to the expression. The attribute’s alias appears above it as Field: Surface Temp (C).

Under the Functions tab, you’ll find a list of built-in functions. The documentation for each function is accessible through this window, making it easy to learn and use new functions.

When you want to reuse an expression you have already created on a layer, it will appear under the Existing tab. This tab will only appear once you have created an expression elsewhere.

The Constants tab contains formatting tools and other universal constants such as the value of pi.

To write your expression, go to the left portion of the window. On the Globals tab, find the attribute field for Sea Surface Temperature (C). Click $feature.sst to add it to the expression. The attribute’s alias appears above it as Field: Surface Temp (C).

Now, write out the equation for the Celsius to Fahrenheit conversion covered earlier. The asterisk (*) symbol can be used for multiplication, just as in Microsoft Excel. The expression should look like this:

$feature.sst * 1.8 + 32

Write out the equation for the Celsius to Fahrenheit conversion.

Step 3:

Test and Use

Test your expression to make sure it works. The expression will return the last line of code, meaning that if your expression is only one line, it will return the result of that line. If your expression is more advanced, you can use a return statement to control what the expression returns. Read my ArcGIS Blog post “Use Arcade Expressions to Map Your Ideas” to see how return statements are used.

Click the Test button, and a console will appear with the result of your expression. In this example, the result is the number 81.4189998626709. The expression was tested using the value 27.454999923706055, which, when converted to Fahrenheit, is 81.4189998626709. This means the expression worked as expected.

This result is using a value from a feature in the dataset to test, but because this is real-time data that is constantly updating, the result you obtain may be different.

To see or change the value being tested, find the attribute in the list on the right, select the pencil to the right of that attribute, and click it to see the value being used by the expression in the test. Confirm that the result is correct.

  1. Now you can use your expression as if it’s a normal data attribute. Change the symbology to the Counts and Amounts (Color) option.
  2. Click Options > Symbols > Fill and change the color ramp back to a bright red to replicate the map you started with.
  3. Move the Transparency slider to 0%, click OK, click Done, and your map is now in Fahrenheit. You did it! You wrote your first Arcade expression!
  4. Now, let’s reuse this expression in the pop-up.

Use the expression just created in the pop-up by highlighting {sst}, clicking the plus sign, and choosing the expression. Change deg C to deg F, and make the expression and reference text size small and bold.

Step 4:

Use an Existing Expression

Once you have used an expression on a layer in your map, you can easily reuse it without needing to rewrite it.

Go into the layer options and choose Configure Pop-up. Under Attribute Expressions, click Add. The expression window you saw earlier will appear, and now there is a new tab in the window called Existing. This contains any expressions being used on the layer. You can see the previous expression you wrote called Sea Surface Temperature (F), and it tells you where it is being used within the map (Color Style).

Click the existing expression and it will automatically appear within the expression window. As you did before, give the expression a useful name so that you can easily reference it later. Click OK to save the expression.

Within the Configure Pop-up panel, click the green Configure button to edit the existing custom attribute display. It currently uses an attribute called {sst}, which is the sea surface temperature in Celsius. Highlight {sst}, click the plus sign, and choose the expression you just added. Change deg C to deg F, and make the expression and reference text size small and bold. Save all your changes, and now your pop-up shows the value in Fahrenheit to match the map.

What You’ve Learned

Arcade is a powerful way to save time and do on-the-fly calculations. You no longer need to own a data layer or perform field calculations to see immediate adjustments to your data values.

About the author

Lisa Berry is a cartographic product engineer on the ArcGIS Living Atlas of the World team at Esri. She works to create clear and concise stories about demographic data using cartography. She also builds data layers and tutorials to help others create their own map masterpieces.