Mata (sfi.Mata)¶

class sfi.Mata¶

This class provides access to global Mata matrices. All row and column numbering of the matrix begins at 0. The allowed values for the row index row and the column index col are

-nrows <= row < nrows

and

-ncols <= col < ncols

Here nrows is the number of rows of the specified matrix, which is returned by getRowTotal(). ncols is the number of columns of the specified matrix, which is returned by getColTotal(). Negative values for row and col are allowed and are interpreted in the usual way for Python indexing.

Method Summary

`create`(name, nrows, ncols, initialValue)	Create a Mata matrix.
`get`(name[, rows, cols])	Access elements from a Mata matrix.
`getAt`(name, row, col)	Access an element from a Mata matrix.
`getColTotal`(name)	Get the number of columns in a Mata matrix.
`getEltype`(name)	Get the type of a Mata object.
`getRowTotal`(name)	Get the number of rows in a Mata matrix.
`isTypeComplex`(name)	Determine if the Mata object type is complex.
`isTypeReal`(name)	Determine if the Mata object type is real.
`isTypeString`(name)	Determine if the Mata object type is string.
`list`(name[, rows, cols])	Display a Mata matrix.
`store`(name, val)	Store elements in an existing Mata matrix.
`storeAt`(name, row, col, val)	Store an element in an existing Mata matrix.

Method Detail

static create(name, nrows, ncols, initialValue)¶

Create a Mata matrix.

Parameters:

name (str) – Name of the matrix.
nrows (int) – Number of rows.
ncols (int) – Number of columns.
initialValue (float, str, or complex) –
An initialization value for each element. The type of matrix created depends on the type of initialValue:
- float: a real matrix is created and all the element values equal initialValue.
- str: a string matrix is created and all the element values equal initialValue.
- complex: a complex matrix is created and all the element values equal initialValue.

Raises:

ValueError – This error can be raised if

nrows is not a positive integer.
ncols is not a positive integer.

static get(name, rows=None, cols=None)¶

Access elements from a Mata matrix.

Parameters:	name (str) – Name of the Mata matrix. rows (int or list-like, optional) – Rows to access. It can be specified as a single row index or an iterable of row indices. If rows is not specified, all the rows are specified. cols (int or list-like, optional) – Columns to access. It can be specified as a single column index or an iterable of column indices. If cols is not specified, all the columns are specified.
Returns:	A list of lists containing elements of the matrix. Each sublist contains values from each row of the matrix. Abort with an error if the matrix does not exist.
Return type:	list
Raises:	`ValueError` – This error can be raised if matrix name does not exist. any of the row indices specified in rows is out of range. any of the column indices specified in cols is out of range.

static getAt(name, row, col)¶

Access an element from a Mata matrix.

Parameters:	name (str) – Name of the Mata matrix. row (int) – Row to access. col (int) – Column to access.
Returns:	The value. The return type depends on the type of the matrix.
Return type:	float, str, or complex
Raises:	`ValueError` – This error can be raised if matrix name does not exist. row is out of range. col is out of range.

static getColTotal(name)¶

Get the number of columns in a Mata matrix.

Parameters:	name (str) – Name of the Mata matrix.
Returns:	The number of columns.
Return type:	int
Raises:	`ValueError` – If matrix name does not exist.

static getEltype(name)¶

Get the type of a Mata object.

Parameters:	name (str) – Name of the Mata object.
Returns:	The eltype in string form of the Mata object.
Return type:	str
Raises:	`ValueError` – If object name does not exist.

static getRowTotal(name)¶

Get the number of rows in a Mata matrix.

Parameters:	name (str) – Name of the Mata matrix.
Returns:	The number of rows.
Return type:	int
Raises:	`ValueError` – If matrix name does not exist.

static isTypeComplex(name)¶

Determine if the Mata object type is complex.

Parameters:	name (str) – Name of the Mata object.
Returns:	True if the Mata object type is complex.
Return type:	bool
Raises:	`ValueError` – If object name does not exist.

static isTypeReal(name)¶

Determine if the Mata object type is real.

Parameters:	name (str) – Name of the Mata object.
Returns:	True if the Mata object type is real.
Return type:	bool
Raises:	`ValueError` – If object name does not exist.

static isTypeString(name)¶

Determine if the Mata object type is string.

Parameters:	name (str) – Name of the Mata object.
Returns:	True if the Mata object type is string.
Return type:	bool
Raises:	`ValueError` – If object name does not exist.

static list(name, rows=None, cols=None)¶

Display a Mata matrix.

Parameters:

name (str) – Name of the Mata matrix.
rows (int or list-like, optional) – Rows to display. It can be specified as a single row index or an iterable of row indices. If rows is not specified, all the rows are specified.
cols (int or list-like, optional) – Columns to display. It can be specified as a single column index or an iterable of column indices. If cols is not specified, all the columns are specified.

Raises:

ValueError – This error can be raised if

matrix name does not exist.
any of the row indices specified in rows is out of range.
any of the column indices specified in cols is out of range.

static store(name, val)¶

Store elements in an existing Mata matrix.

Parameters:

name (str) – Name of the matrix.
val (array-like) – Values to store. The dimensions of val should match the dimensions of the matrix. Each value of val can be a real number, a string, or a complex number. The matrix type determines the value type of each value.

Raises:

ValueError – This error can be raised if

matrix name does not exist.
dimensions of val do not match the dimensions of the matrix.
any of the value types specified in val do not match the matrix type.

static storeAt(name, row, col, val)¶

Store an element in an existing Mata matrix.

Parameters:

name (str) – Name of the matrix.
row (int) – Row in which to store.
col (int) – Column in which to store.
val (float, str, or complex) – Value to store. The matrix type determines the type of val.

Raises:

ValueError – This error can be raised if

matrix name does not exist.
row is out of range.
col is out of range.
value type of val does not match the matrix type.

Examples¶

The following provides a few quick examples illustrating how to use this class:

>>> from sfi import Mata
>>> Mata.create('mat', 2, 5, 0)
>>> Mata.get('mat')
[[0.0, 0.0, 0.0, 0.0, 0.0], [0.0, 0.0, 0.0, 0.0, 0.0]]
>>>
>>> import numpy as np
>>> np.random.seed(16)
>>> npa = np.random.random((2,5))
>>> npa
array([[0.22329108, 0.52316334, 0.55070146, 0.04560195, 0.36072884],
       [0.22308094, 0.68872616, 0.16373143, 0.07032487, 0.94101086]])
>>>
>>> Mata.store('mat', npa)
>>> Mata.get('mat')
[[0.22329107915353885, 0.5231633414006761, 0.5507014565811811, 0.045601950132806324, 0.36072883534777267],
 [0.22308094169128878, 0.6887261618213565, 0.1637314250008992, 0.07032486680550032, 0.941010860245836]]
>>> Mata.get('mat', rows=1)
[0.22308094169128878, 0.6887261618213565, 0.1637314250008992, 0.07032486680550032, 0.941010860245836]
>>> Mata.get('mat', cols=(1,2))
[[0.5231633414006761, 0.5507014565811811], [0.6887261618213565, 0.1637314250008992]]
>>> Mata.get('mat', rows=1, cols=(1,2))
[[0.6887261618213565, 0.1637314250008992]]
>>>
>>> Mata.getRowTotal('mat')
2
>>> Mata.getColTotal('mat')
5
>>> Mata.getEltype('mat')
'real'
>>> Mata.isTypeString('mat')
False
>>> Mata.storeAt('mat', 0, 0, -2)
>>> Mata.get('mat')
[[-2.0, 0.5231633414006761, 0.5507014565811811, 0.045601950132806324, 0.36072883534777267],
 [0.22308094169128878, 0.6887261618213565, 0.1637314250008992, 0.07032486680550032, 0.941010860245836]]

Table of Contents

Previous topic

Next topic

Mata (sfi.Mata)¶

Examples¶