.. highlight:: xml

.. _cash-flow-table-xml:

Cash flow
=========

The cash flow document defines the costs and incomes of harvest and sivicultural operations used.

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/cash_flow_table.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::

   <cash_flow_tables xmlns="http://www.simo-project.org/simo"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:schemaLocation="http://www.simo-project.org/simo ../schemas/cash_flow_table.xsd">

In the cash flow tables a positive value refers income and negative cost. A Cash flow table named "timber_prices" is an example of table with classifiers:: 

   …
      <cash_flow_table name="timber_prices" 
                       logged="true"
                       desc="Timber prices in final cutting by trees species, 
                             assortment, length class and diameter class">
         <base>

The *logged*-attribute controls whether the cash flow values from the table are stored in the database (in case price tracking is on). 

The classifiers for the cash flow table are used to give a different value for different variable combinations. A classifier can be a data variable like the `PRICE_REGION` attribute from ``comp_unit`` level and `SP` attribute from ``stratum`` level::

   …
            <classifiers>
               <classifier to_db="true">
                  <variable>PRICE_REGION</variable>
                  <level>comp_unit</level>
               </classifier>
               <classifier to_db="true">
                  <variable>SP</variable>
                  <level>stratum</level>
               </classifier>

If logging is set on, *to_db*-attribute for each classifier controls whether the classifier value is stored in the database together with the actual cash flow value. 

A variable within a operation model can also be used as a classifier. Here the `assortment`, the `diameter` and the `length` attributes are used. The `assortment` attribute can get two different values: `1` or `2`. `1` refers to `log` and `2` `pulp` wood::

   …
               <classifier to_db="true">
                  <variable>assortment</variable>
                  <level>within-operation</level>
                  <labels>
                     <label>
                        <value>1</value>
                        <name>log</name>
                     </label>
                     <label>
                        <value>2</value>
                        <name>pulp</name>
                     </label>
                  </labels>
               </classifier>
               <classifier>
                  <variable>diameter</variable>
                  <level>within-operation</level>
               </classifier>
               <classifier>
                  <variable>length</variable>
                  <level>within-operation</level>
               </classifier>
            </classifiers>

Here in the table the timber prices for the certain attribute combinations are given. First five digits are classifiers and the last is the timber price::

   …
            <table>
               <cash_flow>1 1 1 160 370 55</cash_flow>
               <cash_flow>1 1 1 160 400 55</cash_flow>
               <cash_flow>1 1 2 70 270 15</cash_flow>
               …
            </table>
         </base>
      </cash_flow_table>

A very basic cash flow table named "scarification" is used as a example of table without classifiers. In the table there is only one digit given. It is the cost of certain soil preparation, scarification::

   …
      <cash_flow_table name="scarification" desc="Cost of scarification">
         <cash_flow_variable>
            <name/>
            <level/>
         </cash_flow_variable>
         <base>
            <table>
               <cash_flow>-250</cash_flow>
            </table>
         </base>
      </cash_flow_table>
      …
   </cash_flow_tables>

Dated tables
************

It's possible for the base to consist of several tables. In this case the valid time period for each table can be given as attributes for the <table> element::

   <base>
      <tables>
         <table start="2007-01-01" end="2011-12-31">
            <cash_flow>…</cash_flow>
         </table>
         <table start="2012-01-01" end="2016-12-31">
            <cash_flow>…</cash_flow>
         </table</cash_flow>
         </table>
      </tables>
   </base>

Trends
******

Trend element is used for defining a trend over time for cash flow, eg. increase in the average price level over time::

   <trends>
      <trend>

Time period for a trend is given in <start> and <end> elements as xs:date values::

   …
         <time_period>
            <start>2007-01-01</start>
            <end>2011-12-31</end>
         </time_period>

Trends can be classified like the cash flow table values, so that different attribute combinations get different trends::

   …
         <classifiers>
            <classifier>
               <variable>SP</variable>
               <level>stratum</level>
            </classifier>
            <classifier>
               <variable>assortment</variable>
               <level>within-operation</level>
               <labels>
                  <label>
                     <value>1</value>
                     <name>log</name>
                  </label>
                  <label>
                     <value>2</value>
                     <name>pulp</name>
                  </label>
               </labels>
            </classifier>
         </classifiers>

Cumulative factors for the trends are given in similar way as the cash flow table values. The value for variable y_t at year t is calculated by interpolating between years t_start and t_end, using values y_start and y_start + y_start * trend::

   …
         <cumulative_factors>
            <factor>1 1 0.05</factor>
            <factor>1 2 -0.02</factor>
            <factor>2 1 0.12</factor>
            <factor>2 2 0.03</factor>
         </cumulative_factors>
      </trend>
   </trends>