.. _predictionarg-py:

#################
predictionarg.py
#################

****************************
class PredictionArg(object):
****************************

Container class for passing the prediction model arguments to prediction library

Attributes:

- variables
- parameters
- result_vars
- error_check_mode
- allowed_risk_level
- rect_factor
- model_name
- model_language
- warnings
- errors
- error_objects
- output_type
- num_of_res: integer
- mem: array
- result_level: integer
- target_index: numpy array from data Handler's get_tind
- num_of_targets: integer
- num_of_res_vars: integer
- num_of_res_objs: integer
- remove_targets: set
- warning_flag: boolean
- error_flag: boolean

def __init__(self, name, lang):
===============================

Initialize a prediction model argument container::

    >>> from simo.simulation.model.predictionarg import PredictionArg
    >>> import numpy
    >>> arg = PredictionArg('modelname', 'C')
    >>> arg.model_name
    'modelname'
    >>> arg.model_language
    'C'


def set_targets(self, tind, torem, nresobjs):
=============================================

Store target object indices in the argument container::

    >>> tind = numpy.array([[0,0,0,0,0],
    ...                     [0,0,1,0,0],
    ...                     [0,0,2,0,0],
    ...                     [0,0,3,0,0],
    ...                     [0,0,4,0,0],
    ...                     [0,0,5,0,0]], dtype=int)
    >>> arg.set_targets(tind, set([3]), 1)
    >>> arg.num_of_targets
    6
    >>> arg.target_index
    array([[0, 0, 0, 0, 0],
           [0, 0, 1, 0, 0],
           [0, 0, 2, 0, 0],
           [0, 0, 3, 0, 0],
           [0, 0, 4, 0, 0],
           [0, 0, 5, 0, 0]])
    >>> arg.remove_targets
    set([3])


def set_result_level(self, result_level, cur_level):
====================================================

Set model result level::

    >>> arg.set_result_level(0, 'self')
    >>> arg.result_level
    0


def set_input_variables(self, nvar, values, loc, rem_targets):
==============================================================

Create container for model input variable values if None and store input variable values into the container::

    >>> values = numpy.ones(tind.shape[0], dtype=float)
    >>> values[0] = numpy.NaN
    >>> loc = 2
    >>> arg.set_input_variables(3, values, loc, set([0]))
    >>> arg.variables  # doctest: +ELLIPSIS
    array([[  0.,   0.,   0.,   0.,   0.,   0.],
           [  0.,   0.,   0.,   0.,   0.,   0.],
           [ ...,   1.,   1.,   1.,   1.,   1.]])
    >>> arg.remove_targets
    set([0, 3])


def set_result_variables(self, result_variables):
=================================================

Store result variable indices::

    >>> arg.set_result_variables([0,1,2])
    >>> arg.result_vars
    [0, 1, 2]
    >>> arg.num_of_res_vars
    3


def add_parameter(self, param):
===============================

Add input parameter value to model arguments::

    >>> arg.add_parameter(1.0)
    >>> arg.add_parameter(2.0)
    >>> arg.parameters
    deque([1.0, 2.0])


def set_containers(self):
=========================

Construct containers for passing results back from the model::

    >>> arg.set_containers()
    >>> arg.num_of_res_objs
    array([0, 0, 0, 0, 0, 0])
    >>> arg.mem
    array([[ 0.,  0.,  0.,  0.,  0.,  0.],
           [ 0.,  0.,  0.,  0.,  0.,  0.],
           [ 0.,  0.,  0.,  0.,  0.,  0.]])
    >>> arg.errors
    ['', '', '', '', '', '']


def remove_missing(self):
=========================

Remove objects with missing input variable values::

    >>> arg.remove_missing()
    >>> arg.variables
    array([[ 0.,  0.,  0.,  0.],
           [ 0.,  0.,  0.,  0.],
           [ 1.,  1.,  1.,  1.]])
    >>> arg.num_of_res_objs
    array([0, 0, 0, 0])
    >>> arg.mem
    array([[ 0.,  0.,  0.,  0.],
           [ 0.,  0.,  0.,  0.],
           [ 0.,  0.,  0.,  0.]])
    >>> arg.errors
    ['', '', '', '']
    >>> arg.num_of_targets
    4
    >>> arg.target_index
    array([[0, 0, 1, 0, 0],
           [0, 0, 2, 0, 0],
           [0, 0, 4, 0, 0],
           [0, 0, 5, 0, 0]])

def python2ctypes(self):
========================

Change argument types from python data types to c data types::

    >>> arg.python2ctypes()
    >>> arg.mem  # doctest: +ELLIPSIS +NORMALIZE_WHITESPACE
    [<simo.simulation.model.predictionarg.c_double_Array_3 object at ...>,
     <simo.simulation.model.predictionarg.c_double_Array_3 object at ...>,
     <simo.simulation.model.predictionarg.c_double_Array_3 object at ...>,
     <simo.simulation.model.predictionarg.c_double_Array_3 object at ...>]
    >>> arg.mem[0][0] = 0.0
    >>> arg.mem[0][1] = 1.0
    >>> arg.mem[0][2] = 2.0
    >>> arg.mem[1][0] = 0.1
    >>> arg.mem[2][0] = 0.2
    >>> arg.mem[3][0] = 0.3


def ctypes2python(self):
========================

Change argument types from ctypes to python and remove objects with evaluation errors from target objects::

    >>> arg.ctypes2python()
    >>> arg.mem  # doctest: +ELLIPSIS +NORMALIZE_WHITESPACE
    array([[ 0. ,  0.1,  0.2,  0.3],
           [ 1. ,  0. ,  0. ,  0. ],
           [ 2. ,  0. ,  0. ,  0. ]])


def __construct_ctypes_array(self,valuearray):
==============================================

structure. These arrays are used for passing data to the DLL model libraries. Uses ctypes package for the variable types

def add_error(self, i):
=======================

Add error to target object i::

    >>> arg.add_error(2)
    >>> arg.errors
    array(['', '', '', ''], 
          dtype='|S1')


def drop_error_objects(self):
=============================

Trim the prediction model result structures to only contain valid results; i.e., no error in model call. Also remove empty error strings.::

    >>> arg.drop_error_objects()
    >>> arg.target_index
    array([[0, 0, 1, 0, 0],
           [0, 0, 2, 0, 0],
           [0, 0, 5, 0, 0]])
    >>> arg.num_of_res_objs
    array([0, 0, 0])
    >>> arg.mem
    array([[ 0. ,  0.1,  0.3],
           [ 1. ,  0. ,  0. ],
           [ 2. ,  0. ,  0. ]])