.. highlight:: xml

.. _report-definition-xml:

Aggregation definition
======================

The aggregation definition document defines reporting periods, variables and output types in aggregation output.

An example of the document contents is given below, for a comprehensive description of all the possible content options see the `schema document <http://svn.simo-project.org/simo/trunk/simulator/xml/schemas/report_definition.xsd>`_. Data continuation and abbreviated content expressed as …:

The root level tag contains a reference to the schema document which is used to validate the content of the XML document::
   
   <report_definition xmlns="http://latitude.mmvar.helsinki.fi/simo"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
            xsi:schemaLocation="http://www.simo-project.org/simo
            ../schemas/report_definition.xsd">

First, you must define the initial date of the simulation (as YYYY-MM-DD) to get meaningful results::

   …
      <initial_date>2009-01-01</initial_date>  

Next, discount rate is defined for outputs that needed discounting, such as net present values of income from harvests etc.::

   …
      <discount_rate>3.0</discount_rate>

Reporting periods can contain a number of periods of given length. Period units can be one of: *year, month, day*::

   …
      <reporting_periods>
          <period>
              <length>5</length>
              <unit>year</unit>
          </period>
          <period>
              <length>137</length>
              <unit>month</unit>
          </period>
      </reporting_periods>

Single report definition can include multiple reports. The syntax for defining the reported variables is similar to optimization task subobjective and constraint syntax (see: :ref:`expression-syntax`). Below is an example of a very simple report, where harvest volumes from years 1..3 are reported. Note that period counting begins from 1, and the last period has a special indicator -1. You can of course indicate the last period with its direct ordinal number; i.e., for a 30 year simulation the last period is 30::

   …
      <reports>
         <report>
            <expression>sum[1:3](operation:Volume)</expression>
            <proportion>false</proportion>
         </report>

Reported values can be also grouped by given variable values, such as in::

   …
         <report>
            <expression>sum[1:7](operation:Volume)</expression>
            <proportion>false</proportion>
            <group_by>
               <grouping>
                   <level>operation</level>
                   <variable>SP</variable>
               </grouping>
            </group_by>
         </report>

Here is another example of result grouping (the results will be reported as precentage instead of values, since proportion is set to true).::

   …
         <report>
            <expression>sum[1:-1](comp_unit:AREA)</expression>
            <proportion>true</proportion>
            <group_by>
               <grouping>
                   <level>comp_unit</level>
                   <variable>DEVEL_CLASS</variable>
               </grouping>
            </group_by>
         </report>

         
It's also easy to give conditions to certain values, though in that case, it should in most cases be given to all the values so that the expression doesn't fail::

   …
         <item>
            <expression>avg[1:-1](comp_unit:Age[iteration eq 0] * comp_unit:AREA[iteration eq 0])</expression>
            <proportion>true</proportion>
         </item>

NOTE! The conditions do not work at the moment as they should (and like in expression output and optimization task)!!!

Report definition has a small extension to optimization task syntax for calculating weighted averages::

   …
         <report>
            <expression>wavg[1:-1](comp_unit:Age, comp_unit:AREA)</expression>
            <proportion>false</proportion>
         </report>

The aggregation expressions can be more complex as in optimization tasks::

   …
         <report>
            <expression>
               sum[1:60](operation:cash_flow:discount) + 
               sum[60:60](comp_unit:PV:discount * comp_unit:AREA) + 
               sum[60:60](comp_unit:PV_land:discount * comp_unit:AREA)
            </expression>
         <proportion>false</proportion>
       </report>