Aggregation documentation
Aggregation means calculating values over several periods of time and several organization units in a sub-tree.
Class diagram
The aggregation process must allow for:
1. Aggregation periods not corresponding with data input periods
Consider the following example:
Fig1
The user requests an aggregated value for unit1 from 1/4 to 1/6. The DataElement uses a weekly data input frequency; hence start data and/or end date of the aggregation period will not match with start date/end date of any input periods.
The example period constitutes eight full weeks and five days. To adjust for this kind of inaccuracy the system calculates an approximated value based on the formula
Fig2
where b is the total number of days of the boundary period and a is the number of days of the boundary period inside the aggregation period. In this situation is a=5 and b=7, thus is 5/7 of the value registered with the boundary period added to the aggregated value.
Look at the Javadoc for AverageDataElementAggregation.getAggregateOfValues(..) and SumDataElementAggregation.getAggregateOfValues(..) for implementation details.
2. Changes in the organization unit hierarchy
To be able to calculate earlier aggregation periods it is necessary to keep track of changes in the organization unit hierarchy. Consider the following example:
- Unit1 is added at 1/3 as the root unit of the organization tree.
- Unit2 is added at 1/3 as a child of unit1, and moved to a subtree with another root at 1/5.
- Unit3 is added at 1/4 as a child of unit1, and deleted at 1/5.
As a result of this only the values registered for unit1, unit2 from 1/3 to 1/5 and unit3 from 1/4 to 1/5 should count when calculating the aggregated value for the period of 1/3 to 1/7 (marked with green in fig 3). To save the history of the organization tree the parent-child relationship is stored in the database with an OrganizationUnitHierarchy object every time an unit is added, moved or deleted, i.e. when the organiztion tree is changed (marked with an arrow in fig 3). The example assumes that the data values are registered with the same data element.
Fig3
The periods divided up by the organization unit hierarchies are calculated separately and then summed or averaged. The correct aggregated value in the example will be 15 + 35 + 25 = 75 (if the data element has the SUM aggregation operator).
Look at the Javadoc for HibernateOrganizationStore.addOrganizationUnitHierarchy(..), HibernateOrganizationStore.getOrganizationUnitHierarchies(..) and HibernateOrganizationStore.getChildren(..) for implementation details.
3. Different aggregation methods
Currently there are two aggregation methods; Sum and Average. The aggregation method is decided by the aggregation operator property in the data element object. DefaultAggregationStore.getAggregatedDataValue delegates to SumDataElementAggregation.getAggregatedValue(..) or AverageDataElementAggregation.getAggregatedValue(..) to perform the aggregation. The two last-mentioned classes implements AbstractDataElementAggregation, and uses the template method design pattern to define the steps of the algorithm.
Look at the Javadoc for implementation details.
4. Constraints
Currently there are one rule for the aggregation calculation: The duration of the aggregation period must be greater og equal to all periods that is registered with routine datavalues being used in the aggregation. This aggregation rule is defined in AggregationRules.applyAggregationRule1(..). If this rule is being violated, an AggregationRuleViolationException is thrown. This exception can be caught in report modules, and the message property used to explain the reason for rule violation.
5. Aggregation of indicators
An indicator contains a formula including data elements and numbers. The formula is stored on the format ( [5]+[2] / 2 * [3] ) where the numbers inside the brackets are the ids of data elements. When aggregated; this string is converted by DefaultAggregationStore.generateExpression(..) to the format ( 100 + 150 / 2 * 50 ), where the numbers are the aggregated value of the given data element, period and organization unit. This method uses the existing methods for aggregation of data elements. The product of this expression is then calculated by DefaultAggregationStore.calculateExpression(..).
