*! Version 2.8 of this help file by Mead Over, 7Sep2020

help for mluVersion 2.28 7Sep2020

Title

mlu -- Matrix lookup. Extract a single matrix element [rowid,colid]

Syntax

mlu
matrix_name[rowid,colid]
[,
options]

where rowid and colid can be specified as either integers
or strings.

Options

matrix_name Name of an existing Stata or Mata matrix. Required option.

rowid Name or number of a row of matrix_name. Required option.
Must be preceded by an open bracket "[" and followed by a comma.
If the matrix is a Stata (not a Mata) matrix, the rowid
can be a simple name or a compound name consisting of an equation name, a colon
and then a rowname. See rownames.

colid Name or number of a column of matrix_name. Required option.
Must be followed by a closed bracket "]".
If the matrix is a Stata (not a Mata) matrix, the colid
can be a simple name or a compound name consisting of an equation name, a colon
and then a rowname. See colnames.

local(lname) Name of the r() macro in mlu's return space
containing the value of the extracted matrix element: r(lname).
Default is to return the value of the element in r(element).

scalar(sname) Name of a returned scalar containing value of the
extracted matrix element. Specify the option replace to overwrite
an existing scalar of the same name.

global(sname) Name of a returned global macro containing value of the
extracted matrix element. Specify the option replace to overwrite
an existing global macro of the same name.

replace By default, mlu refuses to overwrite an existing
scalar or global macro of the same name. To enable mlu to overwrite an existing
scalar or global macro of the same name, specify the option replace.

add Instead of erasing and replacing any results currently in Stata's return space,
mlu's returned macros are appended to the existing return results. Rarely used.

verbose Report details of the matrix extraction

mata Specify that matrix_name is a Mata matrix.

stata Specify that matrix_name is a Stata matrix.

Description

mlu (think "matrix lookup") is a utility for extracting a single element
from either a Stata or a Mata matrix. mlu also stores in Stata's return
space several characteristics of the target matrix. For some users,
especially those with a Stata version earlier than 16, mlu may be
a convenient alternative to using Stata and Mata commands for extracting an element.

Prior to Stata 16, extracting an element of a Stata matrix by its row and column
names and placing it in a scalar required the user to type:

scalar cellvalue = el(A,rownumb(A,"price"),colnumb(A,"quantity"))

Using mlu, the user can instead type:

mlu A[price,quantity], scalar(cellvalue) replace

With Stata 15 or prior, mlu is also useful as a shortcut for retrieving an element of a matrix
returned by a Stata command as either r(matname) or e(matname).
By using mlu, the user can avoid the intermediate step usually
required of transferring the r(matname) or e(matname) to an
ordinary Stata matrix before its elements can be accessed. See Example 2
below.

mlu can also be used to extract an element from a real or string mata matrix.
See Examples 3 and 4 below.

mlu places in Stata's return space the full row and column
names of the extracted element.

It is possible that the same name refers to both a Stata and a Mata matrix.
In that case, the user must specify from which of the two matrices, mlu
is to extract an element. Example 5 illustrates the use of the options
stata and mata to specify the intended matrix.

To extract a submatrix from a Stata matrix,
see help for matrix extraction if the rows and columns
are contiguous. To extract a submatix consisting of rows and columns
whose names match a user-defined wild-card template, see mluwild.

An undocumented feature of Mata allows the association of row and/or column names
to the rows and columns of a Mata matrix. For details, see
this
post on Statalist. The current version of mlu does not exploit this possibility.
Therefore, to look up an element of a Mata matrix, the user must
designate the row and column by numbers, not names.

Examples

Example 1

. matrix def abcd = (1,2,3,4\5,6,7,8)

. matrix list abcd

abcd[2,4]
c1 c2 c3 c4
r1 1 2 3 4
r2 5 6 7 8

. matrix rownames abcd = price quantity

. matrix colnames abcd = apr may jun jul

. matrix list abcd

abcd[2,4]
apr may jun jul
price 1 2 3 4
quantity 5 6 7 8

. mlu abcd[quantity,jun], verbose
Element (2,3) of Stata matrix abcd[2,4] = 7

. display "Element extracted is: " `r(element)'
Element extracted is: 7

Example 2

. sysuse auto
(1978 Automobile Data)

. reg price mpg

<output omitted>

After many commands, Stata returns results to the user as
stored results. For example, after this regression, the matrix of
estimated coefficients is returned as e(b).

. matrix list e(b)

e(b)[1,2]
mpg _cons
y1 -238.89435 11253.061

But prior to version 16, Stata did not permit the user to access elements of
these stored matrices directly.

// In Stata version 15 or earlier, the following assignment gives error -r(198)-.
. scalar alpha = e(b)[1,2]
invalid syntax
r(198);

// Substituting -`e(b)'- for -e(b)- doesn't work in any version of Stata.
. scalar alpha = `e(b)'[1,2]
matrix not found
r(111);

. matrix define eb = e(b) // Before Stata 16, the 2-step work-around was:

. scalar alpha = eb[1,2]

. display alpha
11253.061

As an alternative to the 2-step work-around, use mlu to extract the element directly
from e(b) like this.

. mlu e(b)[1,2], verbose scalar(alpha2) replace
Element (1,2) of Stata matrix e(b)[1,2] = 11253.061

. display alpha2
11253.061

Or use mlu to access an element of Stata's e(b) by its
row and column names like this:

. mlu e(b)[y1,mpg], verbose scalar(beta) replace
Element (1,1) of Stata matrix e(b)[1,2] = -238.89435

. display beta
-238.89435

Example 3

mlu can also be used to extract an element of a mata matrix.
To demonstrate this capability, first define and list a mata matrix. Then use mlu
to extract the element (4,1).

. mata: mata clear
. mata: R = (9,10\11,12\13,14\15,16)
. mata: R

We can use Mata to extract element (4,1) and place it in a Stata scalar like this:

. mata: st_numscalar("el41",R[4,1])
. display el41
15

Using mlu, the same result can be achieved like this:

. mlu R[4,1], verbose scalar(elmt41) replace
Element (4,1) of Mata matrix R[4,2] = 15
. display elmt41
15

Example 4

Unlike Stata matrices, a mata matrix can contain string	elements
instead of numeric elements. The following code constructs a mata string matrix
consisting of phrases that describe the shape and color of an object.

. mata: S = ("","",""\"","",""\"","",""\"","","")
. local object "a \`color' \`shape'"
. local i = 1
. local j = 1

. foreach color in red blue green {
2. foreach shape in square triangle circle oblong {
3. mata: S[`i',`j'] = "`object'"
4. local i = `i' + 1
5. }
6. local i = 1
7. local j = `j' + 1
8. }

We can use Mata to extract element (2,3) of this string matrix:

. mata: st_local("el23",S[2,3])
. display "`el23'"
a green triangle

Now use mlu to extract an element of this string matrix:

. mlu S[2,3], verbose
Element (2,3) of Mata matrix S[4,3] = a green triangle
. display "`r(element)'"
a green triangle

Example 5

We have previously defined the Stata matrix -abcd- as:

. matrix list abcd

abcd[2,4]
apr may jun jul
price 1 2 3 4
quantity 5 6 7 8

As shown above, we can extract an element of this matrix
by specifying the row and column of the element
either as integer indices or as row and column names.

. mlu abcd[quantity,jun], verbose
Element (2,3) of Stata matrix abcd[2,4] = 7

. mlu abcd[2,3], verbose
Element (2,3) of Stata matrix abcd[2,4] = 7

Now suppose there is an identically named Mata matrix, which might have
the same or different elements. Here we construct a Mata matrix
which vertically stacks twice the Stata matrix abcd onto the Stata matrix abcd.

. mata: abcd = (2*st_matrix("abcd")) \ st_matrix("abcd")

Note that the Mata version of the matrix has lost its row and column names,
so its elements can only be specified by row and column numbers.

. mata: abcd
1 2 3 4
+
+
1 | 2 4 6 8 |
2 | 10 12 14 16 |
3 | 1 2 3 4 |
4 | 5 6 7 8 |
+
+

Now that there are two matrices with the same name, the program -mlu-
needs to know from which matrix the user wishes to extract an element.

. mlu abcd[2,3], verbose // doesn't work
Stata's memory contains both a Stata and a Mata matrix with the name -abcd-.
Use one of the two options -stata- or -mata- to specify from which matrix to extract an element.

r(198);

By specifying either the option -stata- or the option -mata-,
the user can extract an element from the desired matrix.

. mlu abcd[2,3], verbose stata
Element (2,3) of Stata matrix abcd[2,4] = 7

. mlu abcd[2,3], verbose mata
Element (2,3) of Mata matrix abcd[4,4] = 14

Stored results

After the commmands:

. sysuse auto, clear
. reg3 (price mpg) (weight length)

<output omitted>

. matrix list e(b)

e(b)[1,4]
price: price: weight: weight:
mpg _cons length _cons
y1 -205.26388 10536.823 32.498483 -3088.0596

. mlu e(b)[y1,weight:length], verbose
Element (1,3) of Stata matrix e(b)[1,4] = 32.498483

The return list commmand displays:

. return list

macros:
r(stata_matrix) : "stata_matrix"
r(matname) : "e(b)"
r(colfullname) : "weight:length"
r(coleq) : "weight"
r(colname) : "length"
r(rowfullname) : "y1"
r(roweq) : "_"
r(rowname) : "y1"
r(rn) : "1"
r(cn) : "3"
r(rowdim) : "1"
r(coldim) : "4"
r(element) : "32.49848336070113"

If user has specified the scalar(sname) option,
mlu also returns the specified
matrix element as a scalar with the user's specified name.

scalars:
r(sname) = 7

Author

Mead Over Contact him at
MOver@CGDev.Org if you observe any
problems.