Matrix from DataTable

From Emergent

There are several ways to access Matrix information from DataTables.

A Matrix object can be used in a variety of Math operations supported by the taMath object, and it can be used in a variety of other functions as well.

Accessing an Entire Column of Data

The columns of a DataTable are Matrix objects, so if you want an entire column of data as a Matrix object, you just need to access the Matrix for a column. In css code, as used in an expression in a Program, do the following:

  MyDataTable.data.MyColName.ar

where MyDataTable is your data table variable or a full path to a data table object, and ar is the field within the DataCol data column object that is the matrix of data.

Clearly, you do not want to do anything destructive with this matrix (e.g., change its geometry) because that will mess up the datatable. However, you can read/write to the data in the Matrix in this way.

Accessing a Matrix Cell

Data table columns can contain cells that are themselves a Matrix instead of a scalar (this is done by making the column Matrix have 1 more dimension than the cell dimensionality, where this extra outer dimension is the row number). There are functions (methods) on the DataTable that allow you to get and set these matrix cells:

  GetValAsMatrix(col, row)
  GetValAsMatrixColName(col_name, row) 

  SetValAsMatrix(Matrix* val, col, row)
  SetValAsMatrix(Matirx* val, col_name, row)

In Programs, you must use a program variable of the appropriate matrix type (e.g., float_Matrix, String_Matrix, etc) to store the matrix object pointer that you get from a GetValAsMatrix function call. Furthermore, this program variable must live in a ProgVars (loc vars in the program toolbar) object, and not in the global args/vars groups in the overall Program. This is needed to manage the memory allocation associated with extracting a sub-matrix from the overall column matrix of data -- a local variable gets created and destroyed as the program runs, whereas the global args/vars variables persist as long as the project is open, meaning that they can hold onto a sub-Matrix* guy even after its overall column has been deleted or modified. This can lead to problems.

The best practice is to put the ProgVars (loc vars) containing the Matrix* object pointer inside the same set of code where you will be getting the matrix from the data table. For example, if this is happening within a loop, put the loc vars at the top of the loop_code. This way, the memory management will all be resolved once the loop or other relevant scoping is done, and you won't end up with any "dangling pointers."

Accessing individual values within a Matrix Cell

There are special DataTable functions that allow you to directly access matrix cell values without having to first get the entire Matrix cell object itself (as described above). These are simpler and preferred if you don't need to pass the matrix object to some other function. These are:

  GetMatrixVal
  GetMatrixFlatVal

  SetMatrixVal
  SetMatrixFlatVal

where the flat versions just take a single "flat" index into the values within the matrix cell, while the use specific values for each dimension of the matrix cell.