Arcade expressions in the GeoAnalytics Desktop toolbox

Some GeoAnalytics Desktop tools use Arcade expressions in analysis. The tools and function of the expressions are outlined below.

Using Arcade, field names are formatted as $feature["field name"] or $feature.fieldname. The first option, $feature["field name"], is required when a field name includes a space. All examples below use this option. All tools use the $feature["field name"] format except Join Features. For Join Features, use $target["field name"] and $join["field name"] to specify the dataset to use.

Learn more about Arcade expressions

Arcade expressions are used in GeoAnalytics Desktop toolbox by the following tools:

  • Reconstruct Tracks and Create Buffers—Use buffer expressions to perform a mathematical calculation to set the buffer size. You can perform simple and advanced calculations that can be applied to all records. This calculation is applied to each feature.
  • Reconstruct Tracks—Use split expressions to specify a condition to split tracks. When points meet the criteria, tracks are split and summarized into different tracks. You can apply simple conditions as well as track-based conditions. For example, you can split tracks when the speed of the current point is less than two meters per second (TrackCurrentSpeed() < 2).
  • Join Features—Use join expressions to specify a condition to select features that should be included in the join. You can perform simple join conditions (such as field a > field c) as well as advanced conditions. The conditions are tested on each feature to determine what is analyzed.
  • Calculate Field—Perform simple and advanced calculations that are applied to all records. This calculation is applied to each feature.
  • Detect Incidents—Determine start and end conditions for incidents. Use start and end expressions to detect incidents. A Detect Incidents condition must always result in true or false. Use a condition to determine whether a feature should be included in an incident. The conditions are tested on each feature to determine which features are incidents.

Mathematical operation and function examples

Expressions can mathematically process numbers. The following table shows a sample of available operations.

Learn more about mathematical operations and functions available in Arcade

OperatorExplanationExample

a + b

Returns the sum of a plus b.

fieldname contains a value of 1.5

$feature["fieldname"] + 2.5

4.0

a - b

Returns the difference of a minus b.

fieldname contains a value of 3.3

$feature["fieldname"]- 2.2

1.1

a * b

Returns the product of a times b.

fieldname contains a value of 2.0

$feature["fieldname"] * 2.2

4.4

a / b

Returns the quotient of a divided by b.

fieldname contains a value of 4.0

$feature["fieldname"] / 1.25

3.2

abs( a )

Returns the absolute (positive) value of a.

fieldname contains a value of -1.5

abs($feature["fieldname"])

1.5

log ( a )

Returns the natural logarithm (base E) of a.

fieldname contains a value of 1

log($feature["fieldname"])

0

sin ( a )

Returns the trigonometric sine of a.

The input is assumed to be an angle in radians.

fieldname contains a value of 1.5707

sin($feature["fieldname"])

1

cos( a )

Returns the trigonometric cosine of a.

The input is assumed to be an angle in radians.

fieldname contains a value of 0

cos($feature["fieldname"])

1

tan( a )

Returns the tangent of a.

The input is assumed to be an angle in radians.

fieldname contains a value of 0

tan($feature["fieldname"])

0

sqrt( a )

Returns the square root of a.

fieldname contains a value of 9

sqrt($feature["fieldname"])

3

min( a, b )

Returns the lowest valued number between a and b.

fieldname contains a value of 1.5, and a value of -3

min($feature["fieldname"], -3)

-3

max( a, b )

Returns the highest valued number between a and b.

fieldname1 contains a value of 1.5, and fieldname2 contains a value of -3

max($feature["fieldname1"], $feature["fieldname2"])

1.5

constrain(<value>,<low>,<high>)

Returns the input value if it's within the constraining bounds. If the value is less than the low value, it returns the low value. If the value is greater than the high value, it returns the high value.

Example 1: constrain( $feature["distance"], 0, 10)

Returns 0 if distance is less than 0, 10 if distance is greater than 10, and distance otherwise.

Example 2: constrain($feature['Store dist'], 6, distance)

Returns 6 if Store dist is less than 6, distance if Store dist is greater than distance, and Store dist otherwise.

Text function examples

Arcade expressions can process text. The following table shows a sample of available operations.

Learn more about text functions available in Arcade

OperatorExplanationExampleResult

concatenate( <values>, <separator>)

Concatenates values together and returns a string.

  • values—An array of string values to concatenate.
  • separator ( optional)—A separator to use for concatenation if the values parameter is an array, or a string to concatenate if a single value is provided for the first parameter. If not provided, it will be empty.

fieldname contains a value of GeoAnalytics

Concatenate ([$features["fieldname"], "is", "great!"], ' ')

GeoAnalytics is great!

find(<searchText>, <text>, <startPos>)

Finds a string within a string. Wildcards are not supported.

  • searchText—The substring to search for.
  • text—The text to search.
  • startPos (optional)—The zero-based index of the location in the string to search from.

fieldname1 contains a value of 14NorthStreet and fieldname2 contains a value of North

find($feature["fieldname2"], $feature["fieldname1"])

2

lower(<value>)

Makes a string lowercase.

  • value—The string to be made lowercase.

fieldname contains a value of GEOANALYTICS

lower($feature["fieldname"])

geoanalytics

Text example using find and lower.

find(("north"), lower("146NorthStreet"))

Date function examples

Arcade expressions can process dates. The following table shows a sample of available operations. In Arcade, month values range from 0 (January) to 11 (December), days from the 1st to the 31st, hours from 0 (12:00 a.m.) to 23 (11:00 p.m.), minutes and seconds from 0 to 59, and milliseconds from 0 to 999.

Learn more about date functions available in Arcade

OperatorExplanationExampleResult

date( <value>, <month>, <day>, <hour>, <minute>)

Parses a value or set of values into a date string.

  • value(optional)— Either the number of milliseconds since January 1, 1970, UTC or a number representing a year. If a year is specified, the month and day must also be provided in subsequent parameters. This value can also be a date string or an ISO 8601 string to be converted to a date.
  • month (optional)—The month (0-11), where 0 is January and 11 is December.
  • day (optional)—The day of the month (1-31).
  • hour (optional)—The hour of the day (0-23).
  • minute (optional)—The minute of the hour (0-59).
  • second (optional)—The second of the minute (0-59).
  • millisecond (optional)—The millisecond of the second (0-999).

fieldname contains a value of 1476987783555

Example 1: Date($features["fieldname"])

Example 2: Date(2017,0,14,0)

Example 3: Date()

Example 1: 20 Oct 2016 11:23:03 am

Example 2: 14 Jan 2017 12:00:00 am

Example 3: Returns the current time

DateDiff(<date1>, <date2>, <units>)

Subtracts two dates and returns the difference in the specified units.

  • date1—The date value from which to subtract a second date.
  • date2—The date value to subtract from the first given date.
  • startpos (optional)—The units used to return the difference of the two given dates. The supported unit types are milliseconds, seconds, minutes, hours, days, months, and years. The default value is milliseconds.

Example 1: DateDiff(Date(2017,1,14,0), Date())

Example 2: DateDiff(Date(2017,1,14,0), Date(), "Years")

Result will vary depending on when you run this command.

Example 1: -20532129137

Example 2: -0.6546783768647119

Year(<dateValue>)

Returns the year of the given date.

  • value—A date value identifying the year.

Example 1: fieldname is a field of type Date with a value of 09 Oct 2017 04:30:43 pm

Year($feature["fieldname"])

Example 2: fieldname is a string field formatted as an ISO 8601 string with a value of 2012-09-27

Example 1: 2017

Example 2: 2012

Logical function examples

In addition to simple mathematical expressions, you can use advanced functions to apply buffer expressions.

FunctionExplanationExampleResult

iif(<condition>,<true value>,<false value>)

Returns one value if a condition evaluates to true and returns another value if that condition evaluates to false.

<true value> and <false value> can be the following:

  • A numeric field. If there is a space in the field name, use square brackets.
  • A number.
  • A function.

iif($feature["field1"] > $feature["field2"], $feature["field1"], 0)

iif($feature["field1"] > $feature["field2"], iif($feature["field2"] = 0, $feature["field3"], $feature["field4"]), 0)

Returns field1 if field1 is greater than field2, and 0 otherwise.

Returns the result of the second iif function if field1 is greater than field2, and 0 otherwise.

when(<expression1> , <result1> , <expression2> , <result2> , ... , <expressionN> , <resultN>, <default>)

Evaluates a series of expressions in order until one evaluates to true.

  • expression—An expression.
  • result—The result of the expression. It can be a number or field.
  • default—An optional value if none of the expressions match.

when(($feature["field1"] + 10) > 1, 1,($feature["field2"] + 10) > 2 , 2, $feature["field3"])

If field1 + 10 is greater than 1, returns 1. If not, checks if field2 + 10 is greater than 2. If yes, it returns 2. If not, it returns field3.

decode(<conditional val> , <case1> , <result1>, <case2>, <result2>, ... <caseN>, <resultN>, <defaultValue> )

Evaluates an expression and compares its value with subsequent parameters. If the expression matches, it returns the next parameter value. If none match, there is the option for the last parameter to be a default return value.

  • conditional val—The conditional value. It can be a field or an expression.
  • case—A value to be compared to the conditional val.
  • result—The result if the corresponding case matches the conditional val.
  • defaultValue—An optional value if no other values are true.

decode($feature["field1"] + 3 , $feature["field1"], 1, $feature["field2"], 2, 0)

Compares equality between the conditional val field1 + 3 and case1 field1. If true, it returns 1. If false, it compares the equality between field1 + 3 and field2. If true, it returns 2; otherwise, it returns 0.

Conditional operators

Conditional statements can use the following operators:

OperatorExplanationExampleResults

a > b

a < b

a is greater than b

a is less than b

10 > 2

False

a >= b

a <= b

a is greater than or equal to b

a is less than or equal to b

abs(-10) >= 10

True

a != b

a is not equal to b

abs(-3) != -3

True

a == b

a is equal to b

abs(-5) == 5

True

<condition1> || <condition2>

Condition 1 or condition 2 is met.

(abs(-5) == 5) || (10 < 2)

True

<condition1> && <condition2>

Condition 1 and condition 2 are met.

(abs(-5) == 5) && (10 < 2)

False

Track-aware examples

Detect Incidents, Calculate Field, and Reconstruct Tracks can use track-aware equations in Arcade. In Calculate Field, track equations can be used when the input layer is time enabled, The expression is track aware is checked, and one or more fields are specified to identify tracks.

FunctionExplanationExampleResult

TrackStartTime()

Calculate the start time of a track in milliseconds from epoch.

Using a track that starts on January 2, 2017

TrackStartTime()

1483315200000

TrackDuration()

Calculate the duration of a track in milliseconds from the start until the current time step.

Using a track that starts on January 2, 2017, and the current time is January 4, 2017.

TrackDuration()

172800000

TrackCurrentTime()

Calculate the current time in a track.

Using a feature that occurs on January 3, 2017, at 9:00 a.m.

TrackCurrentTime()

1483434000000

TrackIndex

Return the time index of the feature being calculated.

Calculating this value on the first feature in a track.

TrackIndex

0

TrackFieldWindow(<fieldName>, <startIndex>, <endIndex>)

Return an array of values in the given field for the specified time index. The window function allows you to go forward and backward in time. The expression is evaluated at each feature in the track.

  • The current feature is at index 0.
  • Positive values represent features that occur in the future, after the current value. For example, position 1 is the next value in the array.
  • Negative numbers represent features that occurred in the past, before the previous feature. For example, -1 is the previous value in the array.

MyField has sequentially ordered values of [10, 20, 30, 40, 50]. The expression is evaluated at each feature in the track. Results are returned inclusive of the start feature and exclusive of the end feature.

Example 1: TrackFieldWindow("MyField,-1,2)

Example 2: TrackFieldWindow("MyField,-2,0)[0]

Example 3: TrackFieldWindow("MyField,0,3)[2]

Example 1: When evaluated at each feature, the table shows the following results:

Evaluated featureResult

10

[10,20]

20

[10, 20, 30]

30

[20,30,40]

40

[30,40,50]

50

[40, 50]

Example 2: When evaluated at index 2 (value is 30), it returns 10.

Example 3: When evaluated at index 2 (value is 30), it returns 50.

TrackGeometryWindow(<startIndex>, <endIndex>)

Return an array of values representing geometry for the specified time index. The window function allows you to go forward and backward in time. The expression is evaluated at each feature in the track.

  • The current feature is at index 0.
  • Positive values represent features that occur in the future, after the current value. For example, position 1 is the next value in the array.
  • Negative numbers represent features that occurred in the past, before the previous feature. For example, -1 is the previous value in the array.

MyField has sequentially ordered values of [10, 20, 30, 40, 50]. The geometry of the features are [{x: 1, y: 1},{x: 2, y: 2} ,{x: null, y: null},{x: 4, y: 4}, {x: 5, y: 5}] The expression is evaluated at each feature in the track. Results are returned inclusive of the start feature, and exclusive of the end feature.

Example 1: TrackGeometryWindow(-1,2)

Example 2: TrackGeometryWindow(0,1)[0] on a polyline dataset

Example 3: TrackGeometryWindow(0,1)[0] on a polygon dataset

Example 4: Find the X value of the previous point TrackGeometryWindow(-1,0)[0]["x"]

Example 1: When evaluated at each feature, the table shows the following results.

Evaluated featureResult

10

[{x: 1, y: 1},{x: 2, y: 2}]

20

[{x: 1, y: 1},{x: 2, y: 2} ,{x: null, y: null}]

30

[{x: 2, y: 2} ,{x: null, y: null},{x: 4, y: 4}]

40

[{x: null, y: null},{x: 4, y: 4}, {x: 5, y: 5}]

50

[{x: 4, y: 4}, {x: 5, y: 5}]

Example 2: Polylines are returned in the following format: [{"paths":[[[-180,-22.88],[-177.6,-23.6]],[[180,-18.099999999999994],[179.7,-18.4],[179.4,-18.7],[178.9,-18.9],[178.5,-19.3],[178.2,-19.7],[178.4,-20],[178.8,-20.2],[178.9,-21.8],[179,-22.2],[179.4,-22.7],[180,-22.88]],[[-178,-17],[-178.8,-17.3],[-179.2,-17.5],[-179.6,-17.8],[-179.9,-18],[-180,-18.099999999999994]]]}]

Example 3: Polygons are returned in the following format: [{"rings":[[[-7882559.1197999995,6376090.883500002],[-7893142.474300001,6042715.216800004],[-8544018.775999999,6045361.0554000065],[-8544018.775999999,6376090.883500002],[-7882559.1197999995,6376090.883500002]]]}]

Example 4: Evaluated at index 2 (value is 30): 2

TrackWindow(<value1>, <value2>)

Return an array of values representing geometry and all attributes for the specified time index. The window function allows you to go forward and backward in time.

  • The current feature is at index 0.
  • Positive values represent features that occur in the future, after the current value. For example, position 1 is the next value in the array.
  • Negative numbers represent features that occurred in the past, before the previous feature. For example, -1 is the previous value in the array.

MyField has sequentially ordered values of [10, 20, 30, 40, 50], in addition to the objectID, globalID, and instant_datetime fields. The geometry of the features are [{x: 1, y: 1},{x: 2, y: 2} ,{x: null, y: null},{x: 4, y: 4}, {x: 5, y: 5}]. The expression is evaluated at each feature in the track. Results are returned inclusive of the start feature and exclusive of the end feature.

Example 1: TrackWindow(-1,0)[0]

Example 2: geometry(TrackWindow(-1,0)[0]["x"]

Example 1: When evaluated at each feature, the table shows the following results:

Evaluated featureResult

10

20

[{"geometry": {x: 1, y: 1}},{"attributes": {"MyField" : 10, "trackName":"ExampleTrack1"}}]

30

[{"geometry": {x: 2, y: 2}},{"attributes": {"MyField" : 20, "trackName":"ExampleTrack1"}}]

40

[{"geometry": {x: null, y: null}},{"attributes": {"MyField" : 30, "trackName":"ExampleTrack1"}}]

50

[{"geometry": {x: 4, y: 4}},{"attributes": {"MyField" : 40, "trackName":"ExampleTrack1"}}]

Example 2: Evaluated at index 2 (value is 30): 2

Use the following track expressions to calculate distance, speed, and acceleration on tracks. This is similar to calculations used in the Calculate Motion Statistics tool.

All distance calculations are calculated in meters, speed in meters per second, and acceleration in meters per second squared. Distances are measured using geodesic distances.

FunctionExplanation

TrackCurrentDistance()

The sum of the distances travelled between observations from the first to current observation.

TrackDistanceAt(value)

The sum of the distances travelled between observations from the first to the current observation plus the given value.

TrackDistanceWindow(value1, value2)

The distances between the first value (inclusive) to the last value (exclusive) in a window about the current observation (0).

TrackCurrentSpeed()

The speed between the previous observation and the current observation.

TrackSpeedAt(value1)

The speed at the observation relative to the current observation. For example, at value 2, it's the speed at the observation two observations after the current.

TrackSpeedWindow(value1, value2)

The speed values between the first value (inclusive) to the last value (exclusive) in a window around the current observation (0).

TrackCurrentAcceleration()

The acceleration between the previous observation and the current observation.

TrackAccelerationAt(value1)

The acceleration at the observation relative to the current observation.

TrackAccelerationWindow(value1, value2)

The acceleration values between the first value (inclusive) to the last value (exclusive) in a window around the current observation (0).

The example calculations for distance, speed, and acceleration use examples from the following image.

Track example image with six points

FunctionExample result

TrackCurrentDistance()

Point IDResult (meters)

P1

0

P2

60

P3

80 + 60 = 140

P4

30 + 80 + 60 = 170

P5

35 + 30 + 80 + 60 = 205

P6

25 + 35 + 30 + 80 + 60 = 230

TrackDistanceAt(2)

Point IDResult (meters)

P1

0 + 80 + 60 = 140

P2

30 + 80 + 60 = 170

P3

35 + 30 + 80 + 60 = 205

P4

25 + 35 + 30 + 80 + 60 = 230

P5

null

P6

null

TrackDistanceWindow(-1, 2)

Point IDResult (meters)

P1

[0,60]

P2

[0, 60, 140]

P3

[60, 140, 170]

P4

[140, 170, 205]

P5

[170, 205, 230]

P6

[205, 230]

TrackCurrentSpeed()

Point IDResult (meters/second)

P1

0

P2

60/60

1

P3

80/60

1.33

P4

30/60

.5

P5

35/60

0.5833

P6

25/60

0.4167

TrackSpeedAt(2)

Point IDResult (meters/second)

P1

80/60

1.33

P2

30/60

.5

P3

35/60

0.5833

P4

25/60

0.4167

P5

null

P6

null

TrackSpeedWindow(-1, 2)

Point IDResult (meters/second)

P1

[0, 1]

P2

[0, 1, 1.3]

P3

[1, 1.3, 0.5]

P4

[1.3, 0.5, 0.583]

P5

[0.5, 0.583, -0.4167]

P6

[0.583, -0.4167]

TrackCurrentAcceleration()

Point IDResult (meters/second²)

P1

0

P2

0.0167

P3

0.0056

P4

-0.0014

P5

0.0014

P6

-0.0028

TrackAccelerationAt(2)

Point IDResult (meters/second²)

P1

0.0056

P2

-0.0014

P3

0.0014

P4

-0.0028

P5

null

P6

null

TrackAccelerationWindow(-1, 2)

Point IDResult (meters/second²)

P1

[0, 0.0167]

P2

[0, 0.0167, 0.0056 ]

P3

[0.0167, 0.0056 , -0.0014]

P4

[ 0.0056 , -0.0014, 0.0014]

P5

[-0.0014, 0.0014, -0.0028]

P6

[0.0014, -0.0028]