Matrix (sfi.Matrix)¶

class sfi.Matrix¶

This class provides access to Stata 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.

Matrix names can be one of the following:

global matrix such as “mymatrix”
r() matrix such as “r(Z)”
e() macro such as “e(Z)”

Method Summary

`convertSymmetricToStd`(name)	Convert a symmetric matrix to a standard matrix.
`create`(name, nrows, ncols, initialValue[, …])	Create a Stata matrix.
`get`(name[, rows, cols])	Get the data in a Stata matrix.
`getAt`(name, row, col)	Access an element from a Stata matrix.
`getColNames`(name)	Get the column names of a Stata matrix.
`getColTotal`(name)	Get the number of columns in a Stata matrix.
`getRowNames`(name)	Get the row names of a Stata matrix.
`getRowTotal`(name)	Get the number of rows in a Stata matrix.
`list`(name[, rows, cols])	Display a Stata matrix.
`setColNames`(name, colNames)	Set the column names of a Stata matrix.
`setRowNames`(name, rowNames)	Set the row names of a Stata matrix.
`store`(name, val)	Store elements in an existing Stata matrix or create a new Stata matrix if the matrix does not exist.
`storeAt`(name, row, col, val)	Store an element in an existing Stata matrix.

Method Detail

static convertSymmetricToStd(name)¶

Convert a symmetric matrix to a standard matrix.

Parameters:	name (str) – Name of the matrix.
Raises:	`ValueError` – If matrix name does not exist.

static create(name, nrows, ncols, initialValue, isSymmetric=False)¶

Create a Stata matrix.

Parameters:

name (str) – Name of the matrix.
nrows (int) – Number of rows.
ncols (int) – Number of columns.
initialValue (float) – An initialization value for each element.
isSymmetric (bool, optional) – Mark the matrix as symmetric. If the number of rows and columns are not equal, this parameter will be ignored. This parameter affects the behavior of storeAt(). When the matrix is marked as symmetric, storeAt() will always maintain symmetry. Default is False.

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)¶

Get the data in a Stata matrix.

Parameters:	name (str) – Name of the 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 the matrix values. 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 Stata matrix.

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

static getColNames(name)¶

Get the column names of a Stata matrix.

Parameters:	name (str) – Name of the matrix.
Returns:	A string list containing the column names of the matrix.
Return type:	list
Raises:	`ValueError` – If matrix name does not exist.

static getColTotal(name)¶

Get the number of columns in a Stata matrix.

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

static getRowNames(name)¶

Get the row names of a Stata matrix.

Parameters:	name (str) – Name of the matrix.
Returns:	A string list containing the row names of the matrix.
Return type:	list
Raises:	`ValueError` – If matrix name does not exist.

static getRowTotal(name)¶

Get the number of rows in a Stata matrix.

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

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

Display a Stata matrix.

Parameters:

name (str) – Name of the 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 setColNames(name, colNames)¶

Set the column names of a Stata matrix.

Parameters:

name (str) – Name of the matrix.
colNames (list or tuple) – A string list or tuple containing the column names for the matrix. The list or tuple length must match the number of columns in the matrix.

Raises:

ValueError – This error can be raised if

matrix name does not exist.
number of column names specified in colNames does not match the number of columns of the matrix.

static setRowNames(name, rowNames)¶

Set the row names of a Stata matrix.

Parameters:

name (str) – Name of the matrix.
rowNames (list or tuple) – A string list or tuple containing the row names for the matrix. The list or tuple length must match the number of rows in the matrix.

Raises:

ValueError – This error can be raised if

matrix name does not exist.
number of row names specified in rowNames does not match the number of rows of the matrix.

static store(name, val)¶

Store elements in an existing Stata matrix or create a new Stata matrix if the matrix does not exist.

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 must be a real number.

Raises:

ValueError – This error can be raised if

matrix name does not exist.
dimensions of val do not match the dimensions of the matrix.

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

Store an element in an existing Stata matrix.

Parameters:

name (str) – Name of the matrix.
row (int) – Row in which to store.
col (int) – Column in which to store.
val (float) – Value to store.

Raises:

ValueError – This error can be raised if

matrix name does not exist.
row is out of range.
col is out of range.

Examples¶

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

>>> from sfi import Matrix
>>> stata: sysuse auto, clear
(1978 Automobile Data)
>>> stata: regress mpg weight foreign

      Source |       SS           df       MS      Number of obs   =        74
-------------+----------------------------------   F(2, 71)        =     69.75
       Model |   1619.2877         2  809.643849   Prob > F        =    0.0000
    Residual |  824.171761        71   11.608053   R-squared       =    0.6627
-------------+----------------------------------   Adj R-squared   =    0.6532
       Total |  2443.45946        73  33.4720474   Root MSE        =    3.4071

------------------------------------------------------------------------------
         mpg |      Coef.   Std. Err.      t    P>|t|     [95% Conf. Interval]
-------------+----------------------------------------------------------------
      weight |  -.0065879   .0006371   -10.34   0.000    -.0078583   -.0053175
     foreign |  -1.650029   1.075994    -1.53   0.130      -3.7955    .4954422
       _cons |    41.6797   2.165547    19.25   0.000     37.36172    45.99768
------------------------------------------------------------------------------

>>> stata: mat list r(table)

rtable[9,3]
            weight     foreign       _cons
     b  -.00658789  -1.6500291   41.679702
    se   .00063711   1.0759941   2.1655472
     t  -10.340218  -1.5334927    19.24673
pvalue   8.283e-16    .1295987   6.896e-30
    ll  -.00785825  -3.7955004   37.361724
    ul  -.00531752   .49544223   45.997681
    df          71          71          71
  crit   1.9939434   1.9939434   1.9939434
 eform           0           0           0


>>> Matrix.getColTotal('r(table)')
3
>>> Matrix.getRowTotal('r(table)')
9
>>> Matrix.getColNames('r(table)')
['weight', 'foreign', '_cons']
>>> Matrix.getRowNames('r(table)')
['b', 'se', 't', 'pvalue', 'll', 'ul', 'df', 'crit', 'eform']
>>> Matrix.get('r(table)')
[[-0.0065878863757739495, -1.6500291058426284, 41.67970232610094], [0.0006371129348538762, 1.07
 59941181930703, 2.165547189658219], [-10.340217589970766, -1.5334926817383927, 19.24673012213
 56], [8.282870591352832e-16, 0.12959870084297345, 6.895575369076975e-30], [-0.007858253486794
 498, -3.795500441654602, 37.3617238695252], [-0.005317519264753402, 0.49544222996934506, 45.9
 97680782676674], [71.0, 71.0, 71.0], [1.9939433678456242, 1.9939433678456242, 1.9939433678456
 242], [0.0, 0.0, 0.0]]
>>>
>>> Matrix.get('r(table)', rows=(0,1))
[[-0.0065878863757739495, -1.6500291058426284, 41.67970232610094], [0.0006371129348538762, 1.07
 59941181930703, 2.165547189658219]]
>>>
>>> Matrix.get('r(table)', cols=(1,2))
[[-1.6500291058426284, 41.67970232610094], [1.0759941181930703, 2.165547189658219], [-1.5334926
 817383927, 19.2467301221356], [0.12959870084297345, 6.895575369076975e-30], [-3.7955004416546
 02, 37.3617238695252], [0.49544222996934506, 45.997680782676674], [71.0, 71.0], [1.9939433678
 456242, 1.9939433678456242], [0.0, 0.0]]
>>>
>>> Matrix.get('r(table)', rows=(0,1), cols=(1,2))
[[-1.6500291058426284, 41.67970232610094], [1.0759941181930703, 2.165547189658219]]
>>>
>>> Matrix.storeAt('r(table)', 0, 1, -5)
>>> Matrix.getAt('r(table)', 0, 1)
-5.0
>>> import numpy as np
>>> np.random.seed(16)
>>> npa = np.random.random((3,4))
>>> npa
array([[0.22329108, 0.52316334, 0.55070146, 0.04560195],
       [0.36072884, 0.22308094, 0.68872616, 0.16373143],
       [0.07032487, 0.94101086, 0.56368138, 0.07799234]])

>>> Matrix.create('ma', 3, 4, 0)
>>> Matrix.store('ma', npa)
>>> Matrix.list('ma')

            c1          c2          c3          c4
r1   .22329108   .52316334   .55070146   .04560195
r2   .36072884   .22308094   .68872616   .16373143
r3   .07032487   .94101086   .56368138   .07799234

>>> Matrix.store('mb', npa)
>>> Matrix.list('mb')

            c1          c2          c3          c4
r1   .22329108   .52316334   .55070146   .04560195
r2   .36072884   .22308094   .68872616   .16373143
r3   .07032487   .94101086   .56368138   .07799234

Table of Contents

Previous topic

Next topic

Matrix (sfi.Matrix)¶

Examples¶