Previous TopicNext Topic


Class Total

The Total class exists as a holder for the aggregate functions. The Total class contains a number of functions for aggregating. These functions are BIRT extensions to JavaScript that summarize a set of rows. The BIRT Report Engine implements a function in the following two phases:

BIRT rewrites any script that contains an aggregate, creating a revised script that performs the two phases. The only time it is important to be aware of this process is when debugging an expression that contains an aggregate.

BIRT computes a one-pass aggregate as the rows are read. For example, if a group footer displays a sum over the rows in the group, BIRT computes the total as the rows are read.

BIRT computes a two-pass, or look-ahead aggregate before creating the content for each row. Consider the example of showing a value in the footer of a group, where the value is a percent of the total for all the accounts. The following statement performs this action:

(balance / Total.sum( balance, Total.OVERALL ) ) * 100.0 

In the preceding example, Total.OVERALL causes BIRT to compute the sum aggregate over all rows, even though the expression appears in a group total. A look-ahead aggregate involves an aggregate at a higher grouping level than the group in which it appears.

To compute the expression in the preceding example, BIRT makes one pass to compute the total balance and a second pass to compute the value for each account.

The general rules for the Total class are:

The application cannot create an instance of this class.

Static properties

OVERALL

functions

Total.ave

This aggregate function computes the mathematical mean value. If the expression evaluates to a number, then this function returns the average of those numbers. If the expression evaluates to a date, then the function returns the average date.

Syntax

Total.ave( expr [, filter [, group ]] )

Arguments

Returns

This function returns the average value of the given expression. Returns null if no rows were available.

Example

The following statement returns the average age of students in a class:

Total.ave( row.Age ) 

To return the average birthday of students in a class, use the following statement:

Total.ave( row.BirthDate ) 

See also

Total.median aggregate

Total.mode aggregate

Total.movingAve aggregate

Total.stdDev aggregate

Total.variance aggregate

Total.weightedAve aggregate

Total.count

This function counts the number of rows within the group.

Syntax

Total.count( [ filter [, group ]] )

Arguments

Example

This example counts the number of male and female students in a class. It is necessary to create two data items. Set the first to:

Total.sum( row.sex == 'M' ); 

Set the second to:

Total.sum( row.sex == 'F' ); 

See also

Total.countDistinct aggregate

Total.sum aggregate

Total.countDistinct

This function computes the number of distinct values within the group or data set. The expr argument gives an expression used to group the values. The expression refers to a data row column. Null values are counted as one distinct value.

Syntax

Total.countDistinct ( expr [, filter [, group ]] )

Arguments

Returns

The number of distinct values within the group or data set. Returns zero if no rows were available.

Example

Suppose we want to know the number of different countries represented by a group of students. We can define a data item that uses the following expression:

Total.countDistinct( row.Country ) 

In this statement row.Country is a column that contains the name or code for the student's home country. Suppose that some rows contain null, meaning that we don't know the home country. Use the following statement to exclude such rows from the count:

Total.countDistinct( row.Country, row.Country != null ) 

See also

Total.count aggregate

Total.first

This aggregate function returns the first value that appears in a data set. This is the first value fetched from the data set when fetching rows using the sort order defined for the Table or List.

Syntax

Total.first( expr [, filter [, group ]] )

Arguments

Returns

This function returns the first value that appears in the sequence of rows, or null if the data set contains no rows.

Example

Suppose that a report lists transactions for a given stock over a period of time. The following statement displays the earliest purchase of the stock:

Total.first( row.TransDate, row.Action == 'Buy' ); 

See also

Total.last aggregate

Total.max aggregate

Total.min aggregate

Total.irr

Computes the internal rate of return for a series of periodic cash flows. For a description of arguments and return values, see Finance.irr.

Syntax

Total.irr( expr, startingGuess [, filter [, group ]])

See also

Finance.irr function

Total.last

This function returns the last value that appears in a data set. This is the last value fetched from the data set when fetching rows using the sort order defined for the Table or List.

Syntax

Total.last( expr [, filter [, group ]] )

Arguments

Returns

This function returns the last value that appears in the sequence of rows, or null if the data set contains no rows.

Example

Suppose that a report lists transactions for a given stock over a period of time. The following statement displays the most recent sale of the stock:

Total.last( row.TransDate, row.Action == 'Sell' ); 

See also

Total.first aggregate

Total.max aggregate

Total.min aggregate

Total.max

This function computes the maximum value of the given expression. The expression is evaluated for each row, and the maximum value is retained. This function can work with number, date, or string.

Syntax

Total.max( expr [, filter [, group ]] )

Arguments

Returns

This function returns the maximum value of the given expression. It returns null if no rows were available.

Example

The following statement finds the oldest student within a class:

Total.max( row.Age ) 

See also

Total.first aggregate

Total.last aggregate

Total.min aggregate

Total.median

This aggregate function computes the mathematical median value. Half the values fall above the median, and half below.

Syntax

Total.median( expr [, filter [, group ]] )

Arguments

Returns

This function returns a median value of the given expression. Returns null if no rows were available.

Example

The following statement return the median age of students in a class:

Total.median( row.Age ) 

And, to return the median birthday of students in a class, use the following statement:

Total.median( row.BirthDate ) 

See also

Total.ave aggregate

Total.mode aggregate

Total.movingAve aggregate

Total.stdDev aggregate

Total.variance aggregate

Total.weightedAve aggregate

Total.min

This aggregate function computes the minimum value of the given expression. The expression is evaluated for each row, and the minimum value is retained. This function can work with any simple type: number, date, or string.

Syntax

Total.min( expr [, filter [, group ]] )

Arguments

Returns

This function returns the minimum value of the given expression. Returns null if no rows were available.

Example

The following statement returns the age of the youngest student within a class:

Total.min( row.Age ) 

See also

Total.first aggregate

Total.last aggregate

Total.max aggregate

Total.mirr

This aggregate function computes the modified internal rate of return for a series of periodic cash flows. For a description of arguments and return values, see Finance.irr.

Syntax

Total.mirr( expr, financeRate, reinvestmentRate[, filter [, group ]] )

See also

Finance.mirr function

Total.mode

This aggregate function computes the mathematical mode value. The mode is the value that occurs most frequently in the data. For example, in the sequence {1, 2, 3, 2, 4, 7}, 2 is the mode because it appears twice, while all other numbers appear only once. If a data set has multiple modes, such as in the sequence {1,2,3,2,3}, the mode aggregate returns null.

Syntax

Total.mode( expr [, filter [, group ]] )

Arguments

Returns

This function returns a mode value of the given expression. Returns null if no rows were available, or if the data has more than one mode.

Example

The following statement returns the most frequently occurring age of students in a class:

Total.mode( row.Age ) 

See also

Total.ave aggregate

Total.median aggregate

Total.movingAve aggregate

Total.stdDev aggregate

Total.variance aggregate

Total.weightedAve aggregate

Total.movingAve

This aggregate function computes a moving average. The expr argument gives the value to average, and the window argument gives the number of rows to consider. The rows are averaged in the order determined by the context, usually the order specified by a sort for a List or Table element.

Syntax

Total.movingAve( expr, window [, filter [, group ]] )

Arguments

Returns

This function returns a moving average value of the given expression. Returns null if no rows were available.

Example

Suppose a report lists the daily price for a stock. To display the moving average of that stock over the last five days, use the following statement:

Total.movingAve( row.price, 5 ); 

See also

Total.ave aggregate

Total.median aggregate

Total.mode aggregate

Total.stdDev aggregate

Total.variance aggregate

Total.weightedAve aggregate

Total.npv

This aggregate function computes the net present value of a varying series of periodic cash. For a description of arguments and return values, see Finance.npv.

Syntax

Total.npv( expr, rate, [, filter [, group ]] )

See also

Finance.npv function

Total.runningNpv

This aggregate function computes the running net present value of a varying series of periodic cash. For a description of arguments and return values, see Finance.npv.

Syntax

Total. runningnpv( expr, rate, [, filter [, group ]] )

See also

Finance.npv function

Total.npv function

Total.runningSum

This aggregate function computes a running sum of values in the group. The value for each row is computed using the expression provided in the expr argument.

This aggregate differs from sum in that Sum returns the total for the current grouping level, whereas RunningSum contains a value at every row representing the sum up to that point.

Syntax

runningSum( expr [, filter [, group ]] )

Arguments

Returns

This aggregate returns the running total of the given expression.

Example

The following statement returns the running total for order amounts for a customer:

Total.runningSum( row.OrderAmt ) 

See also

Total.count aggregate

Total.runningSum aggregate

Total.stdDev

This aggregate function computes the statistical standard deviation of a sequence of numbers. The standard deviation is a measure of the spread of a set of values.

Syntax

Total.stdDev( expr [, filter [, group ]] )

Arguments

Returns

This function returns a standard deviation of the given expression. Returns null if no rows were available.

See also

Total.ave aggregate

Total.median aggregate

Total.mode aggregate

Total.movingAve aggregate

Total.variance aggregate

Total.weightedAve aggregate

Total.sum

This aggregate function computes the sum resulting from adding up a value for each row in the group. The value for each row is computed using the expression given in the expr argument. The sum is obtained by adding all these values together.

Syntax

Total.sum( expr [, filter [, group ]] )

Arguments

Returns

The sum of the given expression. Returns zero if no rows were available.

Example

The following statement totals order amounts for a customer:

Total.sum( row.OrderAmt ) 

See also

Total.count aggregate

Total.runningSum aggregate

Total.variance

This aggregate function computes the statistical variance of a sequence of numbers. The variance is a measure of the spread of a set of values.

Syntax

Total.variance( expr [, filter [, group ]] )

Arguments

Returns

This function returns the variance of the given expression. Returns null if no rows were available.

See also

Total.ave aggregate

Total.median aggregate

Total.mode aggregate

Total.movingAve aggregate

Total.stdDev aggregate

Total.weightedAve aggregate

Total.weightedAve

This aggregate function computes the mathematical weighted mean value. If either the expr or weight arguments evaluate to null, then the row is excluded from the average.

Syntax

Total.weightedAve( expr, weight [, filter [, group ]] )

Arguments

Returns

This function returns the weighted average value of the given expression. Returns null if no rows were available.

Example

Suppose that a finance application tracks batches of a given stock purchased at different times. Each batch has a different purchase price, and a number of shares purchased at that price. The following statement computes the weighted average purchase price:

Total.weightedAve( row.purchasePrice, row.shareCount ) 

See also

Total.ave aggregate

Total.median aggregate

Total.mode aggregate

Total.movingAve aggregate

Total.stdDev aggregate

Total.variance aggregate


(c) Copyright Actuate Corporation 2006

Previous TopicNext Topic