Computations

Operands

An operand is any element defined in the model, called with its unique identifier (ID).

Measures

Measure IDs may be prefixed with B. to distinguish between the base measure and the derived measure.
Adding and dividing measures values:
```
<Computation targetArtefactTypes="FUNCTION" result="(TOPD+TOPT)/(DOPD+DOPT)" />
```
Using both base and derived measures (B.SLOC and SLOC respectively) in the same calculation:
```
<Measure measureId="COMR" defaultValue="-1">
<Computation targetArtefactTypes="CODE" result="LC - B.SLOC + (-04 - SLOC)" />
</Measure>
```
Indicators

Indicators are prefixed with I.. Computations with indicators use the rank of the indicator, as defined in the indicator’s associated scale.
Sum the values of the ranks of several indicators:
```
<Computation targetArtefactTypes="FUNCTION" result="I.SDOC+I.DFCX+I.CFCX" />
```
Using the rank of the root indicator for the artefact with the RANK keyword:
```
<Measure measureId="COMR" defaultValue="-1">
<Computation targetArtefactTypes="CODE" result="RANK + LC" />
</Measure>
```
Using the rank of the root indicator for the artefact with the LEVEL keyword:
```
<Measure measureId="COMR" defaultValue="-1">
<Computation targetArtefactTypes="CODE" result="LEVEL + LC" />
</Measure>
```

Rules

Rules are prefixed with R. The following example shows a computation which retrieves the number of times the rule R_COMPOUNDIF was violated for the current artefact:

<Computation targetArtefactTypes="PACKAGE" result="R.R_COMPOUNDIF" />

Using R.RULE_ID is the same as writing the following query:

<Computation targetArtefactTypes="PACKAGE" result="COUNT RULE.OCCURRENCES FROM NODE WHERE MEASUREID=RULE_ID" />

Query syntax is introduced later in this chapter, in Queries.

Operators

Add operands

Take the value of LC and add 10:

<Measure measureId="COMR" defaultValue="-1">
	<Computation targetArtefactTypes="CODE" result="LC + 10" />
</Measure>

Subtract operands / use the opposite of an operand

Take the value of LC, subtract SLOC:

<Measure measureId="COMR" defaultValue="-1">
	<Computation targetArtefactTypes="CODE" result="LC - SLOC" />
</Measure>

Using the opposite value of an operand:

<Measure measureId="COMR" defaultValue="-1">
	<Computation targetArtefactTypes="CODE" result="0.1 * -LC + 2 * -SLOC * 3" />
</Measure>

Multiply operands

Multiplying metrics:

<Measure measureId="COMR" defaultValue="-1">
	<Computation targetArtefactTypes="CODE" result="LC * SLOC * 6.0" />
</Measure>

Divide operands

Divide metrics:

<Measure measureId="COMR" defaultValue="-1">
	<Computation targetArtefactTypes="CODE" result="LC + 2 / 2" />
</Measure>

OR or ||

Allows evaluating operands as boolean conditions. An operand evaluates to true if its value is > 0. OR returns true if at least one operand evaluates to true

AND or &&

Allows evaluating operands as boolean conditions. An operand evaluates to true if its value is > 0. AND returns true if both operands evaluate to true

The operator precedence in computation is as follows:

1	- (as opposite or operand)
2	/, *
3	+, - (as subtraction)
4	<=, >=, !=, =, >, <
5	OR, \|\|
6	AND, &&

You can use parentheses to override operator precedence, if needed.

When a computation gives an error, the measure will be assigned the default value (-1 in the example below) instead of the result of the computation:

<Measure measureId="COMR" defaultValue="-1">
	<Computation targetArtefactTypes="CODE" result="LC / 0" />
</Measure>

When a measure is assigned its default value because of an error, the Measures tab of the Explorer will display the measure status as Error. When this happens for an indicator, the indicator is displayed in red in the Indicator Tree.

Functions

The icon indicates functions that can be used inside charts that support computations. Computations that can be used in a chart have a limited scope: they only apply to the current node in its current version.

Mathematical functions

MIN(value[,value,value…])

This function can be used in charts that support computations

Determines the minimum in a set of values

Use the lowest of three indicators:

<Measure measureId="EXAMPLE" defaultValue="-1">
	<Computation targetArtefactTypes="CODE" result="MIN(I.TESTABILITY, I.CHANGEABILITY, I.ANALISABILITY)" />
</Measure>

Using nested MIN and MAX functions:

<Measure measureId="EXAMPLE" defaultValue="-1">
	<Computation targetArtefactTypes="CODE" result="MIN(MAX(SLOC+(BLANK/2),1000),MAX(LC,1000))+2" />
</Measure>

FMIN(<Computation> min, <Computation> max, <Computation> value [, <Computation> value, <Computation> value…])

This function can be used in charts that support computations

Calculate the filtered minimum of comma-separated values. When using the FMIN() function, only the values within min and max are used to calculate a MIN(). To specify infinity as a bound, leave the value of min or max empty. If no values match the filter, the default value is returned.
Example 1:
```
FMIN(,,-2,4,11)
is equivalent to: FMIN(-Infinity,+Infinity,-2,4,11)
is equivalent to: MIN(-2,4,11)
```
Example 2:
```
FMIN(0,10,-2,4,11)
is equivalent to: MIN(4,11)
```
Example 3:
```
FMIN(0,1,-2,4,11)
is equivalent to: MIN(), which evaluates to null
and leads to using the default value of the measure and marking
it in the indicator tree with the status ERROR.
```
Example 4:
```
FMIN(2,,1,I.LC)
is equivalent to: FMIN(2,+Infinity,1,I.lC)
is equivalent to: MIN(I.LC)
resolves to: I.LC if LC >= 2, else default value
```

MAX(value[,value,value…])

This function can be used in charts that support computations

Determines the maximum in a set of values

Use a measure if it is above a threshold, else use the threshold itself:

<Measure measureId="EXAMPLE" defaultValue="-1">
	<Computation targetArtefactTypes="CODE" result="MAX(10,VG)" />
</Measure>

Use the value of the higher of two measures:

<Measure measureId="EXAMPLE" defaultValue="-1">
	<Computation targetArtefactTypes="CODE" result="MAX(LC,SLOC)" />
</Measure>

Prevent a division by 0:

<Measure measureId="EXAMPLE" defaultValue="-1">
	<Computation targetArtefactTypes="CODE" result="LC / MAX(STAT, 1)" />
</Measure>

FMAX(<Computation> min, <Computation> max, <Computation> value [, <Computation> value, <Computation> value…])

This function can be used in charts that support computations

Calculates the filtered maximum of comma-separated values. When using the FMAX() function, only the values within min and max are used to calculate a MAX(). To specify infinity as a bound, leave the value of min or max empty. If no values match the filter, the default value is returned.
ABS(operand)

This function can be used in charts that support computations

Determines the absolute value for an operand
Retrieve the variation of a measure:
```
<Measure measureId="EXAMPLE" defaultValue="-1">
	<Computation targetArtefactTypes="CODE" result="ABS(DELTA_VALUE(LC))" />
</Measure>
```
AVR(value[,value,value…])

This function can be used in charts that support computations

Computes the average for a set of values
Calculate the average of three indicators:
```
<Measure measureId="EXAMPLE" defaultValue="-1">
	<Computation targetArtefactTypes="CODE" result="AVR(I.TESTABILITY, I.CHANGEABILITY, I.ANALISABILITY)" />
</Measure>
```
EXP(<Computation>)

This function can be used in charts that support computations

Calculates the exponential of a value
LN(<Computation> value)

This function can be used in charts that support computations

Calculates the natural logarithm of a value
LOG(<Computation> value, <Computation> base)

This function can be used in charts that support computations

Calculates the logarithm of a value
POW(<Computation> value, <Computation> power)

This function can be used in charts that support computations

Calculates a power
SQRT(<Computation> value)

This function can be used in charts that support computations

Calculates a square root
ROUND(<Computation> value)

This function can be used in charts that support computations

Rounds a number up or down to the nearest integer
FLOOR(<Computation> value)

This function can be used in charts that support computations

Rounds a number down to the nearest integer
CEIL(<Computation> value)

This function can be used in charts that support computations

Rounds a number up to the nearest integer
CENTROID(<Computation> value [| <computation> weight], …)

This function can be used in charts that support computations

Calculates the centroid of comma-separated pairs of value|weight. If no weight is specified, it is set to 1.
Calculate the centroid of 3 with weight 3 and 2 with weight 100 (=2.03) (this translates to (3x3 + 2x100) / (100+3)):
```
<Measure measureId="MATH_CENTROID_3_3_2_100" defaultValue="-1">
	<Computation targetArtefactTypes="APPLICATION" result="CENTROID(3|3,2|100)"/>
</Measure>
```

FCENTROID(<Computation> min, <Computation> max, <Computation> value [| <computation> weight], …)

This function can be used in charts that support computations

Calculates the filtered centroid of comma-separated pairs of value|weight. When using the FCENTROID() function, only the values within min and max are used to calculate a CENTROID(). To specify infinity as a bound, leave the value of min or max empty. If no values match the filter, the default value is returned.

Calculate the filtered centroid of TESTABILITY/STABILITY/MAINTAINABILITY:

Given the scale:
level: UNKNOWN, rank: -1
level: LEVELA, rank: 0
level: LEVELB, rank: 1
level: LEVELC, rank: 2

and given that I.TESTABILITY is UNKNOWN, I.STABILITY is LEVELB, I.MAINTAINABILITY is LEVELC

<Measure measureId="MATH_FCENTROID" defaultValue="-1">
	<Computation targetArtefactTypes="APPLICATION" result="FCENTROID(0,,I.TESTABILITY|3,I.STABILITY|2,I.MAINTAINABILITY)"/>
</Measure>

I.TESTABILITY is filtered out as it is not between the specified minimum and maximum.
The value is then computed as CENTROID(I.STABILITY|2,I.MAINTAINABILITY), which is (1x2 + 2) / (2+1).

FSUM(<Computation> min, <Computation> max, <Computation> value [, <Computation> value, <Computation> value…])

This function can be used in charts that support computations
Calculate the filtered sum of comma-separated values. When using the FSUM() function, only the values within min and max are used to calculate a sum. To specify infinity as a bound, leave the value of min or max empty. If no values match the filter, the default value is returned.
```
FSUM(,,1,2.5,2>1,3)
is evaluated as: 1 + 2.5 + 1 + 3
```
```
FSUM(2,4,1,2.5,2>1,3)
is evaluated as: 2.5 + 3
```
```
FSUM(6,,-1,I.LC,LC)
resolves to: I.LC if >= 6 or LC if >= 6
```

Conditional and level-related functions

IF(cond,val_yes,val_no)

This function can be used in charts that support computations

Assigns different values based on the result of a condition. Note that nested IF constructions are allowed, and an IF block can contain OR or AND operators. A condition is simply a computation that returns 1 if true and 0 if false. For example, result="SLOC>50" returns 1 if the artefact’s SLOC is greater than 50, or 0 otherwise.
Set a measure to 6 if SLOC is above a threshold, else set it to 4:
```
<Measure measureId="EXAMPLE" defaultValue="-1">
	<Computation targetArtefactTypes="CODE" result="2+IF(SLOC>50,4,2)" />
</Measure>
```
Fall into the ELSE part of the IF statement to avoid using the default value:
```
<Measure measureId="EXAMPLE" defaultValue="-1">
	<Computation targetArtefactTypes="CODE" result="IF(2/0, 5, 10)" />
</Measure>
=> will return 10 instead of -1
```
Set a measure to 6 if SLOC is above a value and below another one, else set it to 4:
```
<Measure measureId="EXAMPLE" defaultValue="-1">
	<Computation targetArtefactTypes="CODE" result="2+IF(SLOC>50 AND SLOC<100,4,2)" />
</Measure>
```
A nested IF construction:
```
<Measure measureId="EXAMPLE" defaultValue="-1">
	<Computation targetArtefactTypes="CODE" result="2+IF(I.LC>IF(SLOC>300,SLOC,MAX(250,300)),98,8)" />
</Measure>
```
CASE(measureId,case1:value1,case2:value2[,…][,DEFAULT:value])

This function can be used in charts that support computations

Assigns different values to a measure based on the value of another measure. A fallback can be specified by using the DEFAULT case.
Assign a value for EASE_OF_USE based on the value of FEEDBACK:
```
<Measure measureId="EASE_OF_USE" defaultValue="-1">
	<Computation targetArtefactTypes="APPLICATION" result="CASE(FEEDBACK,C.BAD:0,C.GOOD:50,C.EXCELLENT:80,DEFAULT:-1)" />
</Measure>
```
NOT(computation)

This function can be used in charts that support computations

Returns 0 if the result of the computation is greater than or equal to 1, or 1 otherwise.
Set OLD_LARGE_FILE to 1 if the file is neither new nor under 500 lines
```
<Measure measureId="OLD_LARGE_FILE" defaultValue="-1">
	<Computation targetArtefactTypes="FILE" result="NOT(IS_NEW_ARTEFACT() AND LC<500)" />
</Measure>
```

RANK(scale_id,level_id)

This function can be used in charts that support computations

Provides a way to retrieve rank values from your model.

Retrieve rank values, given the following scale:

<Scale scaleId="SCALE_LINE">
	<ScaleLevel levelId="LEVELA" bounds="];10]"  rank="0" />
	<ScaleLevel levelId="LEVELB" bounds="]10;30]" rank="1" />
	<ScaleLevel levelId="LEVELC" bounds="]30;60]" rank="2" />
	<ScaleLevel levelId="LEVELD" bounds="]60;100]" rank="4" />
	<ScaleLevel levelId="LEVELE" bounds="]100;[" rank="8" />
</Scale>

You can use the RANK function as follows to find the rank of LEVELD. The example below returns 4:

<Measure measureId="EXAMPLE" defaultValue="-1">
	<Computation targetArtefactTypes="CODE" result="RANK(SCALE_LINE,LEVELD)" />
</Measure>

Using RANK is useful when combined with conditions. The examples below are equivalent:

<Measure measureId="EXAMPLE" defaultValue="-1">
	<Computation targetArtefactTypes="CODE" result="IF(I.LC>4,1,0)" />
</Measure>

<Measure measureId="EXAMPLE" defaultValue="-1">
	<Computation targetArtefactTypes="CODE" result="IF(I.LC>RANK(SCALE_LINE,LEVELD),1,0)" />
</Measure>

<Measure measureId="EXAMPLE" defaultValue="-1">
	<Computation targetArtefactTypes="CODE" result="IF(I.LC>LEVELD,1,0)" />
</Measure>

In the last example, we use the short syntax for the RANK function: >LEVELD is only valid when used after an indicator. The rank retrieved is the rank of level LEVELD for the scale of the current artefact type for the indicator LC.

FIND_RANK(scale_id,measure_id)

This function can be used in charts that support computations

Provides a way to retrieve a rank from your model by passing a measure and a scale. The FIND_RANK() function is mostly useful when using dynamic scales (see Dynamic scales).

The example below assigns to TEST_COVERAGE_RANK the value of the rank for the value of COVERAGE on the scale DYN_SCALE_OK_KO:

<Measure measureId="OBJECTIVE" targetArtefactTypes="APPLICATION;FOLDER;FILE;CLASS" defaultValue="-1" />
<Measure measureId="COVERAGE" targetArtefactTypes="APPLICATION;FOLDER;FILE;CLASS" defaultValue="-1" />

<Scale scaleId="DYN_SCALE_OK_KO">
	<ScaleLevel levelId="DYN_OK" bounds="[;APP(OBJECTIVE)]"  rank="0" />
	<ScaleLevel levelId="DYN_KO" bounds="[APP(OBJECTIVE);]" rank="1" />
</Scale>

<Scale scaleId="SCALE_OK_KO">
	<ScaleLevel levelId="OK" bounds="[1;1]"  rank="0" />
	<ScaleLevel levelId="KO" bounds="[0;0]" rank="1" />
</Scale>

<Measure measureId="TEST_COVERAGE_RANK">
	<Computation targetArtefactTypes="APPLICATION" result="FIND_RANK(DYN_SCALE_OK_KO,COVERAGE)" />
</Measure>

<Indicator indicatorId="TEST_COVERAGE" measureId="TEST_COVERAGE_RANK" scaleId="SCALE_OK_KO" />

)

APP(measure_id)

This function can be used in charts that support computations

Retrieves the value of a measure at application level
Compute the percentage of lines of code present in the current artefact using the entire application as the reference, with APP():
```
<Measure measureId="EXAMPLE" defaultValue="-1">
	<Computation targetArtefactTypes="CODE" result="(LC*100)/APP(LC)" />
</Measure>
```

) )

PARENT(measure_id, [type]) and ANCESTOR(measure_id, [type])

Retrieves the value of a measure for an artefact’s parent or ancestor containing this measure. The concept is similar to that of the APP() function, but PARENT() only checks the artefact’s direct parent and ANCESTOR() goes up the tree until finding an artefact (of the optionally specified type) that has the requested measure ID.
Mark a method as risky if the parent class has changed, using PARENT():
```
<Measure measureId="RISKY" defaultValue="-1">
	<Computation targetArtefactTypes="FUNCTION" result="PARENT(CHANGED,CLASS)" />
</Measure>
```
Set an artefact as critical if one of its containing folder is critical:
```
<Measure measureId="IS_CRITICAL" defaultValue="-1">
	<Computation targetArtefactTypes="FOLDER;CLASS;FUNCTION" result="ANCESTOR(IS_CRITICAL,FOLDER)" />
</Measure>
```

) )

FPARENT(min,max,measure_id, [type]) and * FANCESTOR(min,max,measure_id, [type])

Provides the same function as PARENT and ANCESTOR but allows filtering for values to take into account. Note that if min or max are omitted, they are automatically replaced by -Infinity and +Infinity respectively.
Filtering with FPARENT():
```
IF(FPARENT(RANK(SCALE_LINE,LEVELG), RANK(SCALE_LINE,LEVELG), I.LC),1,2)
=> resolves as: IF(PARENT(I.LC)=RANK(SCALE_LINE,LEVELG),1,2)
=> return 1 if PARENT(I.LC) = LEVELG, otherwise 2
```
Filtering with FANCESTOR():
```
FANCESTOR(500,, LC, FOLDER)
=> returns LC for the first folder ancestor where LC >= 500
```

)

IS_DP_OK(data_provider_name)

Provides a way to find out if a Data Provider was executed successfully or not during the analysis. If the Data Provider was not executed or failed, the function returns 0. If the Data Provider was executed successfully, then the function returns 1.
Find out if the Checkstyle Data Provider was executed successfully with IS_DP_OK:
```
<Measure measureId="RAN_CHECKSTYLE" defaultValue="-1">
	<Computation targetArtefactTypes="APPLICATION" result="IS_DP_OK(Checkstyle)" />
</Measure>
```

)

DP_STATUS(data_provider_name)

Provides finer information about the execution status of a Data Provider than IS_DP_OK():
- returns -1 if the DP was not run
- returns 0 if the DP was successful
- returns 1 if the DP returned some warnings
- returns 2 if the DP reported errors
- returns 3 if the DP stopped with a fatal error
Find out the status of the execution of Checkstyle during the analysis:
```
<Measure measureId="CHECKSTYLE_STATUS" defaultValue="-1">
	<Computation targetArtefactTypes="APPLICATION" result="DP_STATUS(Checkstyle)" />
</Measure>
```

)

IS_META_PROJECT()

This function can be used in charts that support computations

Allows determining if the project is a meta-project, i.e. an aggregation of results from other Squore projects, and allows you to compute results differently if needed. The function returns 0 for regular projects and 1 for meta-projects. For more information about meta-projects, consult the Creating Meta-Projects section.

)

IS_APPROVED_TEMPLATE()

Returns 1 when the project uses an approved ruleset template, or 0 when it does not. Approved ruleset templates can be created by model managers using the Ruleset Editor. Refer to the Getting Started Guide for more information about ruleset edition.
IS_ARTEFACT_TYPE(artefact_type)

This function can be used in charts that support computations

Provides a way to check if an artefact is of a specific type. If the artefact is of the specified type, the function returns 1, else it returns 0.
Check if the artefact is a CHANGE_REQUEST:
```
<ArtefactType id="ISSUE" heirs="BUG;CHANGE_REQUEST;HOTLINE;REGRESSION" />
<Measure measureId="IS_CR" defaultValue="-1">
	<Computation targetArtefactTypes="ISSUE" result="IS_ARTEFACT_TYPE(CHANGE_REQUEST)" />
</Measure>
```

)

IS_NEW_ARTEFACT()

This function can be used in charts that support computations

Tests whether the artefact is new in the current version of the project. It returns 1 if true, 0 if false.
Define a measure whose value is set to 1 when the artefact is new, else 0:
```
<Measure measureId="EXAMPLE" defaultValue="-1">
	<Computation targetArtefactTypes="CODE" result="IS_NEW_ARTEFACT()" />
</Measure>
```
Use IS_NEW_ARTEFACT as a condition operator:
```
<Measure measureId="EXAMPLE" defaultValue="-1">
	<Computation targetArtefactTypes="CODE" result="IF(IS_NEW_ARTEFACT(),3,4)" />
</Measure>
```
IF(IS_NEW_ARTEFACT(),val_yes,val_no) is equivalent to IF(IS_NEW_ARTEFACT()>0,val_yes,val_no)

)

IS_MOVED_ARTEFACT()

Tests whether the artefact has been moved in the current version of the project. It returns 1 if true, 0 if false.
Define a measure whose value is set to 1 when the artefact has been moved, else 0:
```
<Measure measureId="EXAMPLE" defaultValue="-1">
	<Computation targetArtefactTypes="CODE" result="IS_MOVED_ARTEFACT()" />
</Measure>
```
Use IS_MOVED_ARTEFACT as a condition operator:
```
<Measure measureId="EXAMPLE" defaultValue="-1">
	<Computation targetArtefactTypes="CODE" result="IF(IS_MOVED_ARTEFACT(),3,4)" />
</Measure>
```
IF(IS_MOVED_ARTEFACT(),val_yes,val_no) is equivalent to IF(IS_MOVED_ARTEFACT()>0,val_yes,val_no)

)

IS_RENAMED_ARTEFACT()

Tests whether the artefact has been renamed in the current version of the project. It returns 1 if true, 0 if false.
Define a measure whose value is set to 1 when the artefact has been renamed, else 0:
```
<Measure measureId="EXAMPLE" defaultValue="-1">
	<Computation targetArtefactTypes="CODE" result="IS_RENAMED_ARTEFACT()" />
</Measure>
```
Use IS_RENAMED_ARTEFACT as a condition operator:
```
<Measure measureId="EXAMPLE" defaultValue="-1">
	<Computation targetArtefactTypes="CODE" result="IF(IS_RENAMED_ARTEFACT(),3,4)" />
</Measure>
```
IF(IS_RENAMED_ARTEFACT(),val_yes,val_no) is equivalent to IF(IS_RENAMED_ARTEFACT()>0,val_yes,val_no)

)

IS_RELAXED_ARTEFACT()

This function can be used in charts that support computations

Provides a way to find out an artefact’s relaxation status. It returns 1 if the artefact is relaxed and 0 if it is not.

)

IS_FIRST_VERSION()

Tests whether the version is the first version of the project. It returns 1 if true, 0 if false.
Define a measure whose value is set to 1 when the version is the first version of the project, else 0:
```
<Measure measureId="IS_FIRST_VERSION" defaultValue="0">
	<Computation targetArtefactTypes="APPLICATION;FILES" result="IS_FIRST_VERSION()" />
</Measure>
```

)

LINKS(<linkTypeId> [, OUT|IN|IN_OUT] [, CONDITION])

Returns the number of links for an artefact. The function’s parameters are:
- linkTypeId (mandatory) is the desired type of link. The link type and its supported IN and OUT artefacts must be declared in the analysis model, see Artefact Links for more details. The link direction, which is one of:
  
  OUT considers only outbound links (links from this artefact to other artefacts)
  
  IN considers only inbound links (links from other artefacts to this artefact)
  
  IN_OUT considers all links for this artefact and is the default value if none is specified
- A condition to filter out unwanted links when counting. The condition is verified against the target artefacts according to the specified link direction. In order for the condition to be taken into account, the link type and its supported IN and OUT artefacts must be declared in the analysis model, see Artefact Links for more details.
Find the number of failing tests (link type: BLOCKS) for each requirement and requirement folder:
```
<Measure measureId="NUM_FAILING_TESTS" defaultValue="-1">
	<Computation targetArtefactTypes="REQUIREMENT" result="LINKS(BLOCKS,IN)" />
	<Computation targetArtefactTypes="REQUIREMENT_FOLDER" result="SUM REQUIREMENT.NUM_FAILING_TESTS FROM TREE" />
</Measure>
```
Find the number of failing tests for each requirement, excluding failing tests on relaxed code:
```
<Link id="BLOCKS" srcArtefactTypes="CODE" dstArtefactTypes="REQUIREMENT" />
	<Measure measureId="NUM_FAILING_TESTS_COND" defaultValue="-1">
	<Computation targetArtefactTypes="REQUIREMENT" result="LINKS(BLOCKS,IN, NOT(IS_RELAXED_ARTEFACT()))" />
</Measure>
```

)

LINKS_AGGREGATE(<aggregationType>, <computation>, <linkTypeId> [, OUT|IN|IN_OUT] [, CONDITION] [, default computation])

Allows aggregating metrics from linked artefacts. The function’s parameters are:
- aggregationType (mandatory) defines how the values for the metrics are aggregated. The supported values are:
  - MIN: minimal value
  - MAX: maximal value
  - OCC: number of data points
  - AVG: average value
  - DEV: standard deviation
  - SUM: sum of values
  - MED: median value
  - MOD: modal value
- computation (mandatory) is the computation to perform when encountering the desired type of link.
- linkTypeId (mandatory) is desired type of link to aggregate data from. The link type and its supported IN and OUT artefacts must be declared in the analysis model, see Artefact Links for more details. The link direction, which is one of:
  - OUT considers only outbound links (links from this artefact to other artefacts)
  - IN considers only inbound links (links from other artefacts to this artefact)
  - IN_OUT considers all links for this artefact and is the default value if none is specified
- A computation used as a condition to filter out unwanted artefacts
- A default computation that is used to return a value in case no link exists
Find out the average code coverage for code implementing requirements where tests are failing. Only consider code artefacts where there is test coverage. If there are no failing tests, set the metric to 0:
```
<Link id="BLOCKS" srcArtefactTypes="CODE" dstArtefactTypes="REQUIREMENT" />
<Measure measureId="TCOV_FAILING_TESTS" defaultValue="-1" type="PERCENT">
	<Computation targetArtefactTypes="REQUIREMENT" result="LINKS_AGGREGATE(AVG, TCOV, BLOCKS,IN, TCOV != -1, 0)" />
</Measure>
```

Temporal functions

)

PREVIOUS_VALUE(measureId [, <computation> defaultValue])

Retrieves the previous value of a measure or indicator (measureId). This function returns null when no previous value can be found. A default value can also be specified.
Use the value of LC from the previous analysis:
```
<Measure measureId="EXAMPLE" defaultValue="-1">
	<Computation targetArtefactTypes="CODE" result="PREVIOUS_VALUE(LC)" />
</Measure>
```

)

DELTA_VALUE(measureId [, <computation> defaultValue])

Computes the difference between the current value of a measure or indicator (measureId) and its previous value. This function returns null if no delta can be calculated. A default value can also be specified.
Obtaining the difference in ranking between two analyses for an artefact:
```
<Measure measureId="EXAMPLE" defaultValue="-1">
	<Computation targetArtefactTypes="CODE" result="DELTA_VALUE(RANK)" />
</Measure>
```
Compute a delta of opened/closed bugs since the previous analysis:
```
<Measure measureId="SPRINT_PROGRESS" defaultValue="-1">
<Computation targetArtefactTypes="SPRINT" result="DELTA_VALUE(NB_OPEN_CR)" />
</Measure>
```

)

PREVIOUS_INFO(infoId)

Retrieves the value of some artefact information (infoId) in the previous version, so it can be compared with the current artefact information (This is useful when combined with the EQUALS() or MATCHES() functions, as described in String matching functions).

)

FIRST_VALUE(measureId [, <computation> min[, <computation> max]])

Returns the first value ever assigned to a metric (measureId) in the current project, optionally within specific bounds (min, max).
Compute a delta of opened/closed bugs since the beginning of a sprint:
```
<Measure measureId="SPRINT_PROGRESS" defaultValue="-1">
	<Computation targetArtefactTypes="SPRINT" result="FIRST_VALUE(NB_OPEN_CR)-NB_OPEN_CR" />
</Measure>
```

)

AGGREGATE(aggregationType, measureId, [, <computation> minNb] [, <computation> maxNb] [, <computation> min] [, <computation> max])

Returns the aggregated value of the previous values of a metric (measureId). You can optionally configure the minimum and maximum (minNb, maxNb) number of valid data points to be aggregated, and specify bounds (min, max) for the values to consider for aggregation. The aggregation type (aggregationType) is a mandatory parameter, and must be one of MIN, MAX, OCC, AVG, DEV, SUM, MED or MOD.
Count the number of new issues reported based on the number of new issues opened daily:
```
<Measure measureId="NEW_ISSUES_TALLY" defaultValue="-1">
	<Computation targetArtefactTypes="SPRINT" result="AGGREGATE(SUM, NEW_CR)" />
</Measure>
```
Compute the average number of issues opened daily:
```
<Measure measureId="ISSUE_DISCOVERY_RATE" defaultValue="-1">
	<Computation targetArtefactTypes="SPRINT" result="AGGREGATE(AVG, NEW_CR)" />
</Measure>
```

)

LEAST_SQUARE_FIT(<computation> degree, measureId, <computation> date, [, <computation> minNb] [, <computation> maxNb] [, <computation> min] [, <computation> max])

Returns the interpolated or extrapolated value from the previous values of a metric (measureId) at a specific date (date). You can optionally configure the minimum and maximum (minNb, maxNb) number of valid data points to be taken into account, and specify bounds (min, max) for the values to consider for extrapolation. The date (date) and degree (degree) of the polynomial extrapolation are mandatory parameters.
Compute the value of WP_PCT at the next milestone using exactly 3 data points
```
<Measure measureId="WP_PCT_NEXT_1" defaultValue="-1"  >
	<Computation targetArtefactTypes="WORK_PRODUCT" result="LEAST_SQUARE_FIT(1, WP_PCT, DATE_MILESTONE(NEXT), 3, 3)" />
</Measure>
```

Date functions

Squore computes and stores dates internally as the number of milliseconds since January 1st 1970 in UTC. For version dates and project attributes, users can set a date using the following levels of precision:

Date "1979-07-28" is saved as July 28th 1979 at midnight UTC
Date/Time "1979-07-28T13:58:25" is saved as July 28th 1979 at 13:58:25 UTC
Date/Time in a specific timezone "1979-07-28T13:58:25+0800" is saved as July 28th 1979 at 13:58:25 UTC+8 There are various ways to display dates in the web interface. See the description of the format attribute in Measures for more information.

DATE(<year_param>, <month_param>, <day_param>)

This function can be used in charts that support computations

Converts year/month/day numbers to a date in milliseconds.

Convert to the date 28th July 1979:

<Measure measureId="EXAMPLE" defaultValue="-1">
	<Computation targetArtefactTypes="CODE" result="DATE(1979,07,28)" />
</Measure>

Convert to a date using measure IDs:

<Measure measureId="EXAMPLE" defaultValue="-1">
	<Computation targetArtefactTypes="CODE" result="DATE(YEAR_START+2,MONTH_START+MONTHS_SPENT,TARGET_DAY)" />
</Measure>

DAYS(<param>)

This function can be used in charts that support computations

Allows passing a number as a number of days in milliseconds
Add 4 days to May 19th 2012 to obtain May 23rd 2012:
```
<Measure measureId="EXAMPLE" defaultValue="-1">
	<Computation targetArtefactTypes="CODE" result="DATE(2012,05,19)+DAYS(4)" />
</Measure>
```

TO_DAYS(<duration>)

This function can be used in charts that support computations

Returns the number of days between two dates, given a duration in milliseconds

Calculate the age of a change request:

<Measure measureId="AGE" defaultValue="-1">
	<Computation targetArtefactTypes="CR" result="TO_DAYS(APP(PRESENT_DAY)-CREATE_TIME)" />
</Measure>

Find the number of days since the start of the project (attribute PROJECT_START_DATE) until today:

<Measure measureId="EXAMPLE" defaultValue="-1">
	<Computation targetArtefactTypes="CODE" result="TO_DAYS(TODAY()-PROJECT_START_DATE)" />
</Measure>

Find the number of working days since the start of the project (attribute PROJECT_START_DATE) until today:

<Measure measureId="EXAMPLE" defaultValue="-1">
	<Computation targetArtefactTypes="CODE" result="TO_DAYS(DURATION_WITHOUT_WEEKEND(PROJECT_START_DATE, TODAY()))" />
</Measure>

)

TODAY()

This function can be used in charts that support computations

Retrieves today’s date at midnight UTC

)

NOW()

This function can be used in charts that support computations

Retrieve today’s exact date and time (at the time of the analysis)

Functions NOW() and TODAY() should be used with caution in the analysis model. Be sure to understand fully their behaviors and implications before using them. For example, in case of an apply model, using NOW() would result in the loss of the origin version date.

In most cases we recommend the use of VERSION_DATE() function instead.

)

VERSION_DATE([, keyword])

This function can be used in charts that support computations

Retrieves the version’s date and time.

When creating a project, version date is set by default to the time of the analysis (NOW()), but users are allowed to specify a different date different from the current one.
Calculate whether an issue expires within a week of the analysis:
```
<Measure measureId="EXPIRES_THIS_WEEK" defaultValue="-1">
	<Computation targetArtefactTypes="BUG;CR" result="IF(EXPIRY_DATE - DAYS(7) < VERSION_DATE(),1,0)" />
</Measure>
```
Accepted keywords are FIRST, PREVIOUS and CURRENT. Which allows the user to retrieve the date of the first or previous version, default is the current one.

TRUNCATE_DATE(<date>, <unit>)

This function can be used in charts that support computations

Returns a date truncated to the specified precision unit and is useful when calculating date differences. The supported units are:

YEAR
QUARTER
MONTH
SEMI_MONTH
WEEK_SUNDAY (use when the first day of the week is Sunday)
WEEK_MONDAY (use when the first day of the week is Monday)
DAY
AM_PM
HOUR
MINUTE
SECOND

MILLISECOND

Truncate a date down to year precision:

<!-- Sat, 28 Jul 1979 11:14:04 GMT -->
<Constant id="EXACT_DATE" value="302008444000" />

<!-- Returns 283996800000 (aka: Mon, 01 Jan 1979 00:00:00 GMT) -->
<Measure measureId="TRUNCATE_TO_YEAR" defaultValue="-1">
	<Computation targetArtefactTypes="ISSUE" result="TRUNCATE_DATE(EXACT_DATE, YEAR)" />
</Measure>

Find out how much time it took to solve an issue. This example highlights how using TRUNCATE_DATE() can bring more precision depending on how you want to handle periods under 24 hours as one day or two days.

<!-- Date opened: Sat, 28 Jul 1979 07:47:47 GMT -->
<Constant id="TIME_OPENED" value="301996067000" />

<!-- Date closed 1: Sat, 28 Jul 1979 12:02:25 GMT -->
<Constant id="TIME_CLOSED_1" value="302011345000" />

<!-- Date closed 2: Sun, 29 Jul 1979 04:56:04 GMT -->
<Constant id="TIME_CLOSED_2" value="302072164000" />


<Measure measureId="TRUNCATE_TO_RETURN_ZERO" defaultValue="-1">
	<Computation targetArtefactTypes="ISSUE" result="TRUNCATE_DATE(TIME_CLOSED_1, DAY) - TRUNCATE_DATE(TIME_OPENED, DAY)" />
</Measure>

<Measure measureId="TRUNCATE_TO_RETURN_ONE" defaultValue="-1">
	<Computation targetArtefactTypes="ISSUE" result="TRUNCATE_DATE(TIME_CLOSED_2, DAY) - TRUNCATE_DATE(TIME_OPENED, DAY)" />
</Measure>

<Measure measureId="TO_DAYS_RETURNS_ONE" defaultValue="-1">
	<Computation targetArtefactTypes="ISSUE" result="DAYS(TIME_CLOSED_1 - TIME_OPENED)" />
</Measure>

<Measure measureId="TO_DAYS_RETURNS_ONE_ALSO" defaultValue="-1">
	<Computation targetArtefactTypes="ISSUE" result="DAYS(TIME_CLOSED_2 - TIME_OPENED)" />
</Measure>

DURATION_WITHOUT_WEEKEND(<computation> startDateTime, <computation> endDateTime)

This function can be used in charts that support computations

Returns the difference between startDateTime and endDateTime with Saturdays and Sundays removed. The function uses the GMT timezone and returns a result in milliseconds.

Milestone functions

)

HAS_MILESTONE([milestoneId or keyword] [, date])

This function can be used in charts that support computations

Checks if a milestone with the specified milestoneId exists in the project. The function returns 0 if no milestone is found, 1 if a milestone is found.
Find if we are at the last milestone of the project:
```
IS_LAST_MILESTONE=IF(HAS_MILESTONE(),0,1)
```
)
DATE_MILESTONE([milestoneId or keyword] [, date])

This function can be used in charts that support computations

Returns the date associated to a milestone.
Find if the date for the milestone BETA_RELEASE has been modified between June 2015 and now:
```
DATE_HAS_SLIPPED=(DATE_MILESTONE(BETA_RELEASE)-DATE_MILESTONE(BETA_RELEASE, DATE(2015,06,01))) != 0
```
Compute the date difference between the previous and next milestones:
```
MILESTONE_DURATION=DATE_MILESTONE(NEXT) - DATE_MILESTONE(PREVIOUS)
```
Find the date slip for the next milestone between now and the previous analysis:
```
DATE_SLIP=DATE_MILESTONE(NEXT) - DATE_MILESTONE(NEXT, VERSION_DATE(PREVIOUS))
```
Find the amount of time left until the next milestone:
```
DEADLINE=DATE_MILESTONE(NEXT) - VERSION_DATE()
```
)
GOAL(measureId [, milestoneId or keyword] [, date])

This function can be used in charts that support computations

Returns the goal for a metric at the specified milestone.
Find the goal for requirement stability set for the milestone PROTOTYPE as of June 2016:
```
REQ_STABILITY_GOAL=GOAL(REQ_STABILITY, PROTOTYPE, DATE(2016,06,01))
```
Find the delta between the goal for TEST between the previous and next milestones:
```
DELTA=GOAL(TEST) - GOAL(TEST, PREVIOUS)
```
Find the delta between the goal for TEST for the next milestone set for the previous analysis and now:
```
DELTA=GOAL(TEST) - GOAL(TEST, NEXT, VERSION_DATE(PREVIOUS))
```
Find the delta between the current value of TEST and the goal for TEST at the next milestone:
```
DELTA=GOAL(TEST) - TEST
```

You can use keywords instead of using a milestone ID. You can retrieve information about the next, previous, first or last milestones in the project by using:

NEXT
NEXT+STEP where STEP is a number indicating how many milestones to jump ahead
PREVIOUS
PREVIOUS-STEP where STEP is a number indicating how many milestones to jump backward
FIRST
LAST

In all milestone functions, if no milestone ID and no keyword is specified, then NEXT is used by default. All milestone functions accept a date parameter. The date is used to execute the function in that date context. If no date is specified, then the context used to execute the function is the analysis date.

String matching functions

The examples in this section are based on an artefact with the following data:

<I n="LANGUAGES" v="Java, C#, C++, C"/>
<I n="AUTHOR" v="gabriel"/>
<I n="URL" v="http://www.my_url.com"/> [^]
<I n="ONE_LANGUAGE" v="JaVa"/>

INFO(info_tag)

This function can be used in charts that support computations

Retrieves the textual information info_tag for an artefact.
ARTEFACT_NAME()

This function can be used in charts that support computations

Retrieves an artefact’s name
PROJECT_NAME()

This function can be used in charts that support computations

Retrieves a project’s name
VERSION_NAME()

This function can be used in charts that support computations

Retrieves a version’s name
MODEL()

This function can be used in charts that support computations

Retrieves the model’s folder name
PROP([prefix, ] id, propertyName)

This function can be used in charts that support computations

Retrieves the entity’s property, for the provided ID. Available properties and prefixes are defined in Descriptions syntax.

Prefixes will be useful to differentiate between entities having the same ID, measures, indicators and scales for examples.
NAME([prefix, ] id)

This function can be used in charts that support computations

Retrieves the name of the entity, for the provided ID.
MNEMO([prefix, ] id)

This function can be used in charts that support computations

Retrieves the mnemonic of the entity, for the provided ID.
DESCR([prefix, ] id)

This function can be used in charts that support computations

Retrieves the description of the entity, for the provided ID.
BUILD_URL([tabId])

This function can be used in charts that support computations

Retrieves the URL for the specified Explorer’s page tabId, or DASHBOARD by default. Available IDs are:
- DASHBOARD
- ACTION_ITEMS
- HIGHLIGHTS
- FINDINGS
- DOCUMENTS
- FORMS
- INDICATORS
- MEASURES
- COMMENTS
LEVEL(indicatorId)

This function can be used in charts that support computations

Retrieves the indicator’s level id.
EQUALS('haystack','needle'[, forceIgnoreCase])

This function can be used in charts that support computations

Checks if two strings are equal and returns 1 if they are.
Case-insensitive search:
```
EQUALS(INFO(AUTHOR), 'gabriel')
=> 1
```
Case-sensitive search:
```
EQUALS(INFO(LANGUAGES), 'Java, C#, C++, C', 0)
=> 1
```
CONTAINS('haystack','needle'[, forceIgnoreCase])

This function can be used in charts that support computations

Checks if a string contains another string and returns 1 if it does.
Case-insensitive search:
```
CONTAINS(INFO(LANGUAGES), 'C++')
=> 1
```
Case-sensitive search:
```
CONTAINS(INFO(LANGUAGES), 'Cobol', 0)
=> 0
```
Use two infos as search parameters:
```
CONTAINS(INFO(LANGUAGES), INFO(ONE_LANGUAGE), 1)
=> 1
```
STARTS_WITH('haystack','needle'[, forceIgnoreCase])

This function can be used in charts that support computations

Checks if a string starts with another string and returns 1 if it does.
Check if the URL starts with HTTP:
```
STARTS_WITH(INFO(URL), 'HTTP')
=> 1
```
Check if the URL starts with HTTPS:
```
STARTS_WITH(INFO(URL), 'HTTPS')
=> 0
```
ENDS_WITH('haystack','needle'[, forceIgnoreCase])

This function can be used in charts that support computations

Checks if a string ends with another string and returns 1 if it does.
Check if the URL ends with COM (case-sensitive):
```
ENDS_WITH(INFO(URL), '.COM', 0)
=> 0
```
MATCHES('string','regexp'[, forceIgnoreCase])

This function can be used in charts that support computations

Checks if a string matches a pattern and returns 1 if it does.
Check various regular expressions for the language field:
```
MATCHES(INFO(LANGUAGES), 'J.*', 0)
=> 1
```
```
MATCHES(INFO(LANGUAGES), '.*(, C\+\+).*', 0)
=> 1
```
```
MATCHES(INFO(LANGUAGES), '.*(, C\+\+\+).*', 0)
=> 0
```
forceIgnoreCase is an optional boolean set to 1 by default. If you want to perform a case-sensitive search, use 0, instead.

You can also retrieve the previous value of textual information for an artefact using the PREVIOUS_INFO() function, as described in Temporal functions.