Functions

Functions allow you add more complex behaviour to your data field, such as taking averages of data or performing conditional calculations. You can even have the device alert you with a beep or vibration when certain conditions are fulfilled.

Quick Start

Case is not important: "if" is the same as "IF". Functions are evaluated once per second.
Tap/click on a function name in the table to jump to its detailed information.

[LargeMemory] Available only on: All Edges (except 130 and 520), 645 Music, Fenix 5X and Fenix 5+ (all variants)
[CIQ2]: Not available on CIQ1 devices: FR230/235, FR630, FR920XT, Vivoactive, Fenix 3/HR, D2 Bravo/Titanium, Quatix 3, Tactix Bravo
[AppBuilder5+]: applies to AppBuilder 5+ only.
[AppBuilder5]: applies to AppBuilder 5 and 5+.
[AppBuilderClassic]: applies to AppBuilder Classic only.

Logical Functions

Rotate phone to see examples

Function	Description	Example
if	Select between two values, based on true or false expression. e.g. Ignore all cadence values below 50	if(cadence gt 50, cadence, null)
ifs	Select between multiple values, based on true or false expressions	ifs(hr < 130, 1, hr < 150, 2, hr < 170, 3)
not	Logical negation	not(5 > 1) = 0
alt [AppBuilder5]	Selects an alternate value if the first value is 0 or null. e.g. Display "No HR" if heart rate unavailable.	alt(hr, 'No HR')
nonzero [AppBuilder5]	Returns null if x is zero, x otherwise. e.g. Calculate average cadence, not including zeros.	avg(nonzero(cadence))
findlte findgte findeq	Finds a number in a list, where x is less than or equal to, greater than or equal to, or equal to that number. e.g. Distance to next milestone	findlte(distance, 5, 12.5, 15, 20, 25, 30) - distance
findlt findgt [AppBuilder5][CIQ2]	Finds a number in a list, where x is less than, or greater than that number. e.g. Distance to next milestone
findlteindex findgteindex findeqindex	Finds the index (starting at 0) of a number in a list, where x is less than or equal to, greater than or equal to, or equal to that number. e.g. Heart rate zone	findlte(hr, 100, 120, 150)
findltindex findgtindex [AppBuilder5][CIQ2]	Finds the index (starting at 0) of a number in a list, where x is less than, or greater than that number.

Analysis Functions

[AppBuilderClassic] Note: "avg" functions ignore zeros when calculating averages. "AVG0" functions consider zeros.
[AppBuilder5] Note: "avg" functions consider zeros when calculating averages. To ignore zeros, use avg(nonzero(x))

Rotate phone to see examples

Function	Description	Example
avg	Average over entire activity	avg(hr)
lapavg	Average over current lap	lapavg(hr)
timeavg	Rolling/moving average over time e.g. 15 second average speed	timeavg(speed, 15)
prev	Previous value of x from the last second	altitude - prev(altitude)
prevn	Value of x from n seconds ago	prevn(altitude, 5)
sum	Sum of x over the activity, once per second. e.g. Moving time	sum(speed_raw gt 0.89408)
min max lapmin lapmax	Minimum/maximum of x over the activity/lap	lapmax(altitude)
start lapstart [AppBuilder5] [CIQ2]	Initial value of x for the activity/lap e.g. Lap calories	calories - lapstart(calories)
lastlap [AppBuilder5] [CIQ2]	Returns the value of x from the end of the last lap e.g. Last lap time	lastlap(laptime)

Advanced Analysis Functions [CIQ2]

Rotate phone to see examples

Function	Description	Example
prevd prevt	Previous sample of x from a certain distance or time ago. Useful for calculating elevation grade
when	Returns 1 when x becomes true. e.g. Count sprints (faster than 5 metres/second)	sum(when(speed_raw gt 5))
alert	Returns 1 when x becomes true, and alerts with beep or vibe. e.g. Count sprints and alert at start of sprint	sum(alert(speed_raw gt 5))

Math Functions

Rotate phone to see examples

Function	Description	Example
round [CIQ2]	Rounds x to the nearest integer	round(1.5) = 2 ; round(1.49) = 1
ln [AppBuilder5] [CIQ2]	Natural logarithm of x	ln(8)
log [AppBuilder5]	Logarithm of x to base b	log(8,2) = 3
abs [AppBuilder5][CIQ2]	Returns the absolute value of x	abs(-5) = 5

User Variables [AppBuilder5]

Rotate phone to see examples

Function	Description	Example
setv getv	Set/get user variables. e.g. Calculate the area of a circle	setv(1, pi) ; setv(2, distance) ; getv(1) * getv(2) ^ 2
setglobal getglobal [AppBuilder5+]	Set/get global user variables, which are shared between the six fields in AppBuilder 5+.

Recording Functions [AppBuilder5] [CIQ2]

Functions to control recording data to FIT file (so you can see it in Garmin Connect). When recording is enabled, the numerical result of your formula is automatically recorded to the FIT file (in the graph data), but if you want to display text, format numbers manually, record values to the lap data and summary, or override native data such as Power, these functions are for you.

Rotate phone to see examples

Function	Description	Example
record	Records a value to the graph data (once per second)	record(hr) + ' bpm'
recordlap	Records a value to the lap data	recordlap(lapavg(hr))
recordsummary	Records a value to the summary	recordsummary(max(hr))
norecord	Disables automatic recording to the graph e.g. Record max HR to the summary, but don't record anything to the graph. Display current HR.	recordsummary(max(hr)) ; norecord() ; hr

Number Formatting Functions [AppBuilder5] [CIQ2]

The numerical result of the formula is formatted according to the app settings, but if you want to set a custom format, or format multiple numbers, these functions are available.

Once a number is formatted, it becomes text, which can't be used in calculations or recorded. If you want to format a number and record it to the FIT activity file, use record() before formatting it. e.g. Record the max speed, then format it as a pace (minutes per mile):
formatpace(record(max(speed)))

Rotate phone to see examples

Function	Description	Example
formatnumber	Formats a number with no decimal places	formatnumber(12.499) 12.499: "12"
formatdecimal	Formats a number to the specified number of decimal places (2 by default)	formatdecimal(12.499) 12.499 (2 decimal places): "12.50" formatdecimal(200.9999,3) 200.9999 (3 decimal places): "201.000"
formatpace	Converts speed to pace. Speed: km/miles per hour Pace: minutes:seconds per km/mile	formatpace(speed) 12.0 mph: "5:00"
formattime	Displays seconds as [hours]:minutes:seconds	formattime(timer) 3612 seconds: "1:00:12"
formattime2	Displays minutes:seconds as minutes:seconds	formattime2(elapsedtime) 3612 seconds: "60:12"
format	Formats a number based on a format string. e.g. One decimal place	format(speed, '%.1f')

---

Details

Logical Functions

• if(condition, trueValue, falseValue)
  Returns trueValue if condition is true, falseValue otherwise
  (note: both trueValue and falseValue are always evaluated)
• ifs(cond1, trueValue1, cond2, trueValue2, ....)
  Returns trueValue1 if cond1 is true, trueValue2 if cond2 is true, etc.
  If no conditions are true, returns null (blank)
  (note: all of the trueValues and conds are always evaluated)
• not(x)
  Returns 1 if x is false (or null), 0 otherwise
• findlt(x, value0, value1, ...) [AppBuilder5]
  findlte(x, value0, value1, ...)
  - Finds the first value where x is less than (or equal to) value.
  Returns null if no value matches.
  Values should be sorted from lowest to highest
  
  findgt(x, value0, value1, ...) [AppBuilder5]
  findgte(x, value0, value1, ...)
  - Finds the first value where x is greater than (or equal to) value
  Returns null if no value matches.
  Values should be sorted from highest to lowest
  
  findeq(x, value0, value1, ...)
  - Finds the first value where x is equal to value
  Returns null if no value matches.
  Values can be in any order
  
  e.g. Distance to next milestone (5, 12.5, 15, 20, 25, 30 km or miles):
  findlte(distance, 5, 12.5, 15, 20, 25, 30) - distance
• findltindex(x, value0, value1, ...) [AppBuilder5]
  findlteindex(x, value0, value1, ...)
  - Find the index (starting at 0) of the first value less than (or equal to) x. If no value is found, returns null.
  (values should be sorted from lowest to highest)
  
  findgtindex(x, value0, value1, ...) [AppBuilder5]
  findgteindex(x, value0, value1, ...)
  - Find the index (starting at 0) of the first value greater than (or equal to) to x. If no value is found, returns null.
  (values should be sorted from highest to lowest)
  
  findeqindex(x, value0, value1, ...)
  - Find the index (starting at 0) of the first value equal to x. If no value is found, returns null.
  
  e.g. Calculate power zone, where:
  Zone 0: 0 to 100
  Zone 1: 101 to 150
  Zone 2: 151 to 200
  Zone 3: 201 to 250
  Zone 4: 251 to 300
  findlteindex(power, 100, 150, 200, 250, 300)

note: Unlike if statements in programming languages, all values inside logical functions are always evaluated, regardless of whether any of the conditions are true or false. For example the following will not work as expected:
if (speed_raw gt 5, alert(1), 0)
Instead, you would write:
alert(speed_raw gt 5)

Analysis Functions

Note: all data analysis functions ignore any data gathered while the timer is not running, unless otherwise noted.
Note: Blanks (nulls) are never counted in averages.
[AppBuilderClassic] Note: "avg" functions ignore zeros when calculating averages. "avg0" functions consider zeros.
[AppBuilder5] Note: "avg" functions consider zeros when calculating averages. To ignore zeros, use avg(nonzero(x))

For example:
min(hr) captures the minimum heart rate while the timer is running.
sum(condition) counts the number of seconds condition is true while the timer is running.

[N]: Returns null while timer is not running

• avg(value), lapavg(value)
  Calculates the average of value over the entire activity or lap. For AppBuilder Classic only, does not count zeros
• [AppBuilderClassic] avg0(value), lapavg0(value)
  Calculates the average of value over the entire activity or lap. Counts zeroes
• timeavg(value, t) [N]
  (rolling average, moving average)
  Calculates the simple moving average of value over the last t seconds, sampled once per second. For AppBuilder Classic only, does not count zeroes
  Returns null while the timer is not running.
  
  Note that the a value is still returned if the number of samples since the activity was started or unpaused is less than t (the "window size").
  
  [AppBuilderClassic] timeavg0(value, t) [N]
  (rolling average, moving average)
  Calculates the simple moving average of value over the last t seconds. Counts zeroes
  Returns null while the timer is not running.
  
  
  timeavg(value,t, strictWindow, pauseMode) [Appbuilder5] [CIQ2]
  Same as above, but with advanced options.
  
  
  strictWindow: (optional)
  0 (default): Does not wait until the sample window is full
  Returns an average even when the number of samples is less than the window size
  1: Waits until the sample window is full
  Returns null when the number of samples is less than the window size
  
  
  pauseMode: (optional)
  0: (default): Reset data on pause
  When timer is paused, discards all samples (previous and current). Returns null
  1: Keep old data during pause
  When timer is paused, keeps existing samples but does not collect new ones. Returns last known average
  2: Collect new data during pause
  When timer is paused, samples are collected. Returns the current average. Samples are also collected before the start of an activity, which may not be what you want. But this can be overridden with an explicit check — e.g. if (timer_raw eq 0, null, timeavg(...))
  
  
  Note: timeavg(value, t) is the same as timeavg(value, t, 0, 0)
• prev(value) [N]
  Returns the previous sample of value (from 1 second ago). Returns null while timer is not running
  
  prev(value, pauseMode) [AppBuilder5]
  Returns the previous sample of value (from 1 second ago), with the option to change the behaviour while the timer is paused.
  pauseMode: (optional)
  0: (default) (discard data during pause) When timer is paused, returns null
  1: (keep old data during pause) When timer is paused, returns last value from when the timer was running
  2: (collect new data during pause) When timer is paused, returns previous value from 1 second ago
  
• prevn(value, n) [N] [AppBuilder5] [CIQ2]
  Returns value from n seconds ago. Returns null and does not collect data while timer is not running. Returns the earliest data if less than n seconds have passed.
  
  prevn(value, n, strictWindow, pauseMode) [AppBuilder5] [CIQ2]
  Returns value from n seconds ago, with advanced options.
  
  strictWindow: (optional)
  
  0 (default): Does not wait until the sample window is full
  Returns a previous value even when the time is less than the window size
  1: Waits until the sample window is full
  Returns null when the time is less than the window size
  
  pauseMode: (optional)
  0: (default) (discard data during pause) When timer is paused, returns null
  1: (keep old data during pause) When timer is paused, returns last value from when the timer was running
  2: (collect new data during pause) When timer is paused, returns previous value from n seconds ago
  
• sum(value)
  Calculates the sum of value over the entire activity, sampled once per second. This is mostly useful when you combine it with true/false conditions (see sprinting example below).
• min(value), max(value)
  Calculates the min/max of value over the entire activity
• lapmin(value), lapmax(value)
  Calculates the min/max of value over the current lap.
• start(value), lapstart(value) [Appbuilder5] [CIQ2]
  Returns the first non-null value for the activity or current lap
• start(value, considerNulls), lapstart(value, considerNulls) [Appbuilder5] [CIQ2]
  considerNulls: (optional)
  0 (default): Ignores nulls — return the first non-null value, even if it's 30 minutes into the activity/lap
  1: Considers nulls — returns the first value, null or otherwise, for the activity/lap
  
• lastlap(value) [Appbuilder5] [CIQ2]
  Returns value from the end of the last lap. During the first lap, returns null
  
  e.g. Last Lap Time: lastlap(laptime)
  Last Lap Total Time: lastlap(timer)
  Last Lap Average HR: lastlap(lapavg(hr))
  

Advanced Analysis Functions [CIQ2]

Note: all data analysis functions ignore any data gathered while the timer is not running, unless otherwise noted.
[N]: Returns null while timer is not running
Note: Blanks (nulls) are never counted in averages.

• prevd(value, d, [numSamples], [ignorePause]) [N]
  Retrieves the last sample of value from at least d metres ago, as measured by the activity distance. Returns null while the timer is not running.
  (data is not sampled once per second; the total number of samples will always be around 10)

prevt(value, t, [numSamples], [ignorePause]) [N]
Retrieves the last sample of value from at least t seconds ago, as measured by the activity timer. Returns null while the timer is not running.
(data is not sampled once per second; the total number of samples will always be around 10)

numSamples [LargeMemory] [Optional]: Controls the number of samples. Fenix 5X/5+ have enough memory for about 5000 samples. 645 Music has enough memory for 2000. e.g. prevd(timer, 5000, 5000) retrieves the value of timer from 5000 metres ago, with a resolution of 1 meter (5000/5000)
ignorePause [LargeMemory] [Optional]:
  0: reset data when timer is paused (default).
  1: don't reset data when timer is paused
e.g. prevd(timer, 5000, 5000, 1) retrieves value of timer from 5000 metres ago, with a resolution of 1 meter (5000/5000), and works even if the timer is paused
• when(condition, [inThreshold], [outThreshold], [inNotify], [outNotify])
  when(condition) is equal 1 at the instant a continuous state (defined by condition) is entered, 0 otherwise. If the state is exited, then entered again, when() returns 1 again. You can optionally be notified each time the state is entered.
  
  - condition: The condition which defines the state. e.g. Sprinting: speed_raw gt 5
  - inThreshold/outThreshold: [optional] The number of seconds cond has to be true/false to enter/exit the state. Default: 5. Minimum: 1. (pass in 0 to get the default value)
  - inNotify/outNotify: [optional] action to take when you enter/exit the state described by condition
  Actions:
  0: None [default]
  1: Beep/vibrate (use device settings)
  2: Beep
  3: Vibrate
  [^ subject to device settings and support. i.e. Beep only works if your device has a speaker and "alert tones" is enabled for activities.]
  
  e.g.
  • Count # of times you sprinted (ran faster than 5 m/s):
    sum(when(speed_raw gt 5))
  • Count sprints that lasted longer than 30 seconds.
    sum(when(speed gt 16, 30))
  • Count sprints. Beep and vibrate when starting/stopping (use default thresholds)
    sum(when(speed_raw gt 5, 0, 0, 1, 1))
  • Count sprints. Vibrate when starting (use default thresholds)
    sum(when(speed gt 16, 0, 0, 3))
• alert(condition, [inNotify], [outNotify])
  Notifies you when a condition becomes true. (if the condition subsequently becomes false, then true again, you are notified a second time).
  
  Exactly like when, but with in/out thresholds of 1 second (alerts you immediately).
  iow, alert() notifies you when condition becomes true (and is equal to 1 at that instant, 0 at all other times).
  Also:
  inNotify: default is 1 (notifies per device settings, when condition becomes true)
  outNotify: default is 0 (does not notify, when condition becomes false, after previously being true)
  
  - Note on alert and when. To avoid continuous notifications, both of these functions only notify you (and return 1) at the instant the condition becomes true. If the condition becomes false, then true again (e.g sprinting: Speed gt 16), you get notified again.
  
  If it's a condition that never becomes false again (e.g.: Distance gt 10), then you will only get notified once. You can create separate alerts in this case, if you want to be notified multiple times. e.g.
  alert(distance gt 10); alert(distance gt 17.5); alert(distance gt 20)
  
  In when, the purpose of inThreshold/outThreshold is to control how sensitive the alert is to the condition rapidly becoming false and true again. For example, with an inThreshold of 10 seconds, you could only count sprints that lasted longer than 10 seconds. With an outTHReshold of 5 seconds, your sprint would only be considered over if you stopped sprinting for 5 seconds or more. (meaning you wouldn't be notified multiple times if you sprinted on and off for 10/5 seconds.)
  
  alert gets rid of the complexity of when by just using an inThreshold and outThreshold of 1 second. So you get notified immediately when condition becomes true, and the state is considered to be exited immediately when condition becomes false (so you can immediately receive another notification when it becomes true once again).

Math Functions

• round(x)
  Rounds x to the nearest whole number.
  Round(1.5) = 2
  Round(1.49) = 1
• log(x, b) [AppBuilder5]
  Returns the log base b of x. Returns null if the result is undefined
• ln(x) [AppBuilder5] [CIQ2]
  Returns the natural log of x. Returns null if the result is undefined

User Variables [AppBuilder5]

User variables are a powerful way to store values at a certain point in time (like the start of a lap) and use them later. Or you can eliminate repeated parts of your formula to simplify it greatly.

setv(index, value)
- Sets the variable index to value
- Returns the same value that was passed in

- Index is a number that identifies your variable. To do nothing, use null for Index -- this is useful in conditionals (see examples below)

getv(index)
- Retrieves the value of variable index
- Returns null if setv(index) was not previously called

Examples:
- Calculate the area of a circle with radius equal to the distance you've run:
setv(1, pi) ; setv(2, Distance) ; getv(1) * getv(2) ^ 2

- Approximate rolling average of x, for n samples (useful for very large samples, like 20 minutes or 1200 seconds):
setv(1, if (getv(1) eq null, 0, getv(1) - getv(1) / n + alt(x, 0) / n))

setglobal(index, value) [AppBuilder5+]
- Sets the global variable index to value.
- Returns the same value that was passed in

- Index is a number that identifies your variable. To do nothing, use null for Index
- Value is "global" - i.e. visible to the other formulas in AppBuilder 5+, so you can set a value in one formula and get it in another
getglobal(index) [AppBuilder5+]
- Retrieves the value of global variable index
- Returns null if setglobal(index) was not previously called

Note: the arguments to if are always evaluated, so the following will not work as expected (variable 1 will always be set to Timer):
if (timer gt 3000, setv(1, timer), null)

Instead, you want:
setv(if(timer gt 3000, 1, null), timer)
This works because specifying an index of null causes setv to do nothing.

Recording Functions [AppBuilder5] [CIQ2]

record(value[, nativeNumber, fitLabel])
recordlap(value[, nativeNumber, fitLabel])
recordsummary(value[, nativeNumber, fitLabel])

• Records value to the activity graph, lap data, and summary, respectively. Returns the same value that was passed in, to be used in further calculations, formatted, or recorded again.
• nativeNumber (optional): Default = null. When not null, this specifies the native FIT field number to use for recording, so you can override Power data on 3rd-party sites, for example.
• fitLabel (optional): Default = null. When not null, this specifies the internal FIT label (string) to use for recording, so you can override Power data on 3rd-party sites, for example.

norecord()

• Disables automatic recording of the formula result to the activity graph. You need this function if you want to record something to the summary or lap data, but not the graph.

Examples

Record cadence, but display cadence / 2:
record(cadence) / 2

Record Max cadence to activity summary, record nothing to the graph, display cadence: recordsummary(max(cadence)) ; norecord() ; cadence

Record number of sprints to graph, lap data and summary (and display it):
recordlap(recordsummary(sum(speed_raw gt 5)))
(the record() function is omitted in this example because the value of the entire formula is automatically recorded to the graph)

Record number of sprints to summary, record HR to graph (and display it):
recordsummary(sum(speed_raw gt 5)) ; hr

FIT Field Native Numbers

record, recordlap, and recordsummary take the FIT nativeNumber as an optional 2nd parameter, and the internal FIT label as an optional 3rd parameter. This allows you to override native fields such as Power on 3rd-party sites.
To find the correct "native field number" for your graph, lap or summary data:

• Download the FIT sdk: https://www.thisisant.com/resources/FIT
• Open the profile spreadsheet
• Switch to the Messages tab
• Scroll to the Activity File Messages section
• Look up field numbers in the appropriate section.
  Take note of the appropriate units - these should be the same as "raw units" in AppBuilder - e.g. "speed_raw" is in metres/s"
  • Summary fields - recordsummary()
    Subsection: session
    e.g.
    avg_power = 20 (watts)
    max_power = 21
    
  • Lap fields - recordlap()
    Subsection: lap
    e.g.
    avg_power = 19
    max_power = 20
    
  • Activity graph fields - record()
    Subsection: record
    e.g.
    speed = 6 (metres/second)
    power = 7
    

• e.g. Record Power to the graph:
  record(power, 7, "Power")
  (The "Power" label is necessary for power to be recognized by Stryd PowerCenter and Smashrun.)
• e.g. Record Lap Avg Power:
  recordlap(lapavg(power), 19)
• e.g. Record Lap Max Power:
  recordlap(lapmax(power), 20)
• e.g. Record Avg Power to the summary:
  recordsummary(avg(power), 20)
• e.g. Record Max Power to the summary:
  recordsummary(max(power), 21)
• e.g. Record Speed to the activity graph, while displaying Pace as normal:
  record(speed_raw, 6) ; formatpace(speed)

Examples

• Average speed for the last 10 seconds
  timeavg(speed, 10)
• Display speed if you have a good gps fix
  if (locationaccuracy eq 4, Speed, 0)
• Distance to next aid station (5, 10, 15, 20 km/mi):
  ifs(distance lt 5, 5, distance lt 10, 10 , distance lt 15, 15 , distance lt 20, 20) - distance
• # of seconds spent sprinting (running faster than 16 km/h) (assuming device speed unit is km)
  sum(speed gt 16)
• Best "max effort" speed (assuming your max HR is 195)
  max(0.9 * 195 / hr * speed)
• Alert me when 10 minutes have passed (beep/vibe)
  alert(timer gte 60 * 10)
• Normalized Power [AppBuilder5]
  avg(timeavg(power,30,1)^4)^0.25
  
  

  
  Lap NP (native): Carries rolling average over from previous lap
  lapavg(timeavg(power,30,1)^4)^0.25
  
  

  
  Lap NP: Resets at start of each lap
  

  lapavg(ifs(laptime gte 30,timeavg(power,30,1)^4))^0.25