54.2 Python Access to Model Data
Python functions can directly access data from within the model. The Special Features/Python tutorial example model PythonExample – Discount.trex from the prior section used data passed to the Python function via function arguments. Instead, the example model Python Example – GetTreeAgeData.trex pulls data directly from the model into the Python function via the treeage object.
Note: If performance is critical in your model, try to use the Python interpreter efficiently. For example, a treeage.eval() call is slower than passing an argument to the function.
The expression sent via treeage.eval can be any valid expression that can be calculated in the model, including variables, trackers, distributions, etc. Note that variables are calculated based on the node context from where the Python function was called. For special Monte Carlo keywords (e.g., _monte_pre_trial_eval), the root node context is used.
The treeage object has many methods/functions, but this example model uses the two most common ones listed below.
-
treeage.eval(”expression”) executes the expression in the model and returns the calculated value to the Python function.
-
treeage.debug(“title”, "message”) sends debugging output to the TreeAge Pro Calculation Trace Console.
The treeage.debug function is useful when debugging functions by allowing you to send text related to code syntax and/or calculated values to the Calculation Trace Console. The following example shows how to comment the Python code and how to use the eval and debug syntax.
The comment lines (starting with "#") provide information about the code within the Python function. Additional information is provided here:
-
def PythonGetTreeAgeData():. This is the function declaration of PythonGetTreeAgeData() which is a function with no arguments passed to it. The function uses treeage.eval() to get the information it needs from the model.
-
treeage.debug("PythonFunctionGetTreeAgeData", "Start function"). This sends the text in quotes to the Calculation Trace Console. The comma separating the quotes marks the start of a new line. In the console, you would know that this function has been called.
-
var1 = treeage.eval("myVar1");. Python uses this syntax to calculate and return the value for myVar1 from the TreeAge model and places that value in the internal variable var1 within the Python model. The subsequent line does the same - assigning var2 the TreeAge Pro value for myVar2.
-
product = var1 * var2;. The expression assigns the internal variable product the value equal to the product of the two variables var1 and var2.
-
treeage.debug("PythonGetTreeAgeData","End of function, return value " + str( product)). This sends text to the console, specifically the value of product which is the value returned by the Python function to the model.
-
return product;. This final command returns the value for product back to the expression that calls the function.
The Calculation Trace Console will show the debug outputs based on the commands described (above) as in the figure below.
The treeage object provides several other functions listed in the table below: Python treeage object syntax.
| Treeage object function | Description |
|---|---|
| treeage.eval("expression") | Returns the value of expression from the tree. |
| treeage.debug("title","msg") | Output to trace console view for tree (if detailed debugging preference is on). |
| treeage.loadTable("TableName", python_array) | Load data from an array in Python to a table within a TreeAge model. |
| pt = treeage.getParallelTrials() | Creates an object within Python with access to parallel trials info. |
| pt.getTrialNTracker(trial_number, "tracker_name") | Gets the current tracker tracker_name value for trial number trial_number. |
|
pt.setTrialNTracker(trial_number, "tracker_name", value) |
Sets the tracker tracker_name equal to value for trial number trial_number. |
| treeage.getGlobalTracker("GlobalTrackerName") | Gets the current value of a global tracker GlobalTrackerName. |
| treeage.setGlobalTracker("GlobalTrackerName", value) | Sets global tracker GlobalTrackerName equal to value. |
|
matrix = treeage.getGlobalMatrixN(n) |
Sets a reference to one of the global matrices, whose data can then be accessed/changed. Within Python the matrix is represented as a Python array. See following set of rows. |
|
matrix.getRows() matrix.getCols() |
Get the current number of rows, columns in the matrix. |
| matrix.getElement(int row, int col) | Get the value from a cell in the matrix at row row, column col. |
|
matrix.setElement(int row, int col, double val) |
Set the value of a cell in the matrix to val at row row, column col. |
|
matrix.incrElement(int r, int c, double val) |
Increment the value of cell in the matrix by the amount val. |
|
matrix.fill(double val) matrix.fillCol(double val, int col) matrix.fillRow(double val, int col) matrix.fillCol(double val, int col, int rowsUpperLimit) matrix.fillRow(double val, int row, int columnsUpperLimit) |
Populate the entire matrix with the val provided. Populate all cells in column col with the val provided. Populate all cells in row row with the val provided. Populate the cells in column col with the val provided from row 1 to row rowsUpperLimit. Populate the cells in row row with the val provided from column 1 to column colsUpperLimit. |
| matrix.getIndex() | Returns the index of the matrix. |
| matrix.clear() | Empties the matrix of all data. |
