.. _expression-py:

#############
expression.py
#############


    >>> import datetime


*************************
class OutputExpr(Output):
*************************

Class for expression output, i.e. output variables defined with a syntax similar to optimisation task definitions

def __init__(self, datadb, data_type, id_list, main_level, result_type, output_formats, output_filenames, output_constraint=None, default_decimal_places=1, archiving=False, result_padding=True, aggregation_def=None, expression_def=None, opres_vars=None):
==============================================================================================================================================================================================================================================================

Creates the output class. fully inherited, executes self.run() ::

    >>> from simo.output.test.init_objects import *
    >>> from collections import defaultdict
    >>> import datetime
    >>> import numpy
    >>> idata = InitData()
    >>> idata.init()
    >>> testdb = idata.testdb
    >>> const_obj = idata.const_obj
    >>> aggr_obj = idata.aggr_obj
    >>> expr_obj = idata.expr_obj
    >>> from simo.output.expression import OutputExpr
    >>> out = OutputExpr(testdb, 'result', ['stand1'], 'stratum', 
    ...                  'optimized',
    ...                  'output/test/expression.txt', TestLogger(),
    ...                  const_obj, 1, False, True, aggr_obj, expr_obj,
    ...                  ['cash_flow', 'Income', 'Scrapwood', 'Volume', 
    ...                  'BIOMASS_branches', 'BIOMASS_stumps'])
    >>> try: # doctest: +ELLIPSIS
    ...     f = open('output/test/expression.txt', 'r')
    ...     for line in f:
    ...         print line.rstrip('\n')
    ... finally:
    ...     f.close()
    level;unit;iteration;branch;1st expression;2nd expression
    comp_unit;stand1;0;0;0.0;0.0
    comp_unit;stand1;1;0;0.0;0.0
    comp_unit;stand2;0;0;0.0;0.0
    comp_unit;stand2;0;1;0.0;0.0
    comp_unit;stand2;1;0;0.0;0.0
    comp_unit;stand2;1;1;0.0;0.0
    stratum;stratum1-1;0;0;0.0;0.0
    stratum;stratum1-1;1;0;0.0;0.0
    stratum;stratum1-2;0;0;0.0;0.0
    stratum;stratum1-2;1;0;0.0;0.0
    stratum;stratum2-1;0;0;31.0;0.0
    stratum;stratum2-1;1;0;31.0;0.0
    stratum;stratum2-2;0;0;0.0;0.0
    stratum;stratum2-2;1;0;0.0;0.0
    stratum;stratum2-3;0;1;0.0;0.0
    stratum;stratum2-3;1;1;0.0;0.0
    
def run(self):
==============

Uses data from init to run the class-specific output (self.expression)

def _run_expr(self, expr_dict):
===============================

Executes the given expression dictionary for all reporting periods and return the results in a list of lists of strings.

def _execute_var(self, discount_rate, time_unit, time_length, var):
===================================================================

Executes the given aggregation set with the given values and returns results as a list of strings.

def _analyse_data(self):
========================

Go through expressions and input database and analyse some data properties.

def _process_exprs(self, exprs):
================================

Go through the expressions and try to deduce data levels and earliest and latest dates.

def _create_tables(self):
=========================

Create expression data tables, using Numpy arrays.

def _fill_tables(self):
=======================

Fill expression data tables with values from input databases.

def _collect_values(self, expr, array, forced_level=None):
==========================================================

Get values for a single expression operand from either data or operation result database.

Parameters::

    epxr -- subobjective or constraint expression in postfix form
    array -- target Numpy array

def _get_values_from_db(self, operand, dates, norm, condition=None,
                        forced_level=None):
===================================================================

Get value(s) for a single operand from data or operation result database.

Parameters::
    
    operand -- expression operand, i.e. variable, value or operator
    dates -- date range
    norm -- boolean indicating whether a normal or condition operand
    condition -- operand condition
    forced_level -- forced level name, i.e. use this level for getting the data

def _eval_constraint(self, dates, array, operand, norm):
===================================================================

Evaluate operand constraint and store only those objects for which the condition evaluated True.

Parameters::
    
    dates -- date range
    arr -- temporary data array
    operand -- current operand
    norm -- boolean indicating whether a normal or condition operand

def _set_value(self, array, it, uid, br, date, value):
======================================================

Store a single value into a correct location in a matrix and update branch number container.

Parameters::
    
    array -- Numpy array
    it -- iteration, int
    uid -- object id, str
    br -- branch, int
    i_e -- expression operand index, int
    date -- datetime object
    value -- value to store, float

def _filter_data_by_last_date(self, data):
==========================================

Filter data so that only the values from the last recorded date of each iteration-branch-object combination are selected. This is needed when operand dates are defined as [-1:-1]

Parameters ::

    data -- data generator object from datadb

::

    >>> data = [
    ...     ('1', 0, datetime.date(2000,12,31), 1000.),
    ...     ('1', 0, datetime.date(2005,12,31), 1005.),
    ...     ('1', 0, datetime.date(2010,12,31), 1010.),
    ...     ('1', 1, datetime.date(2000,12,31), 1100.),
    ...     ('1', 1, datetime.date(2005,12,31), 1105.),
    ...     ('1', 1, datetime.date(2010,12,31), 1110.),
    ...     ('2', 0, datetime.date(2000,12,31), 2000.),
    ...     ('2', 0, datetime.date(2005,12,31), 2005.),
    ...     ('2', 0, datetime.date(2010,12,31), 2010.),
    ...     ('2', 1, datetime.date(2000,12,31), 2100.),
    ...     ('2', 1, datetime.date(2005,12,31), 2105.),
    ...     ('2', 1, datetime.date(2010,12,31), 2110.)]
    >>> data = out._filter_data_by_last_date(data)
    >>> for item in data: print item
    ('1', 1, datetime.date(2010, 12, 31), 1110.0)
    ('2', 0, datetime.date(2010, 12, 31), 2010.0)
    ('1', 0, datetime.date(2010, 12, 31), 1010.0)
    ('2', 1, datetime.date(2010, 12, 31), 2110.0)

def _construct_strings(self):
=============================

Construct strings from expression value table contents for output.