*! Version 1.0 of this help file by Mead Over, 4Aug2020

help for mluwildVersion 1.0 4Aug2020

Title

mluwild -- Matrix extraction of rows and columns with names matching wild-card templates.

Syntax

mluwild
matrix_name[rowid,colid]
[,
options]

where rowid and colid are string expressions containing the so-called
"wild-card" characters "*" or "?". mluwild
(think "matrix lookup using wild-card characters")
extracts a submatrix of Stata matrix matrix_name, whose row and column names
conform to the wild-card templates specified by the user.

Options

matrix_name Name of an existing Stata matrix. Required option.

rowid String containing wild-card characters "*" or "?" which serves
as a mask or template for selecting rows of matrix_name. Required option.
Must be preceded by an open bracket "[" and followed by a comma.

colid Name or number of a column of matrix_name.
Must be followed by a closed bracket "]". Required option.

matrix(string) Name of returned Stata submatrix. Default name is submat.

clean Row and column names of extracted matrix are "cleaned"
of factor variable annotations "b" and "o".

omit Rows and columns with names that include the factor variable annotations "o" or "b"
are omitted from the extracted matrix.

verbose Display the extracted matrix.

Description

Stata matrices have always had the convenient property of allowing
rows and columns to be designated by either numbers or names.
See help for rownames.

The user can extract a submatrix from a Stata matrix by referring to rows
and columns either by their numbers or their names. But the selected
rows and/or columns must be contiguous. See help for matrix extraction.
An example is:

. matrix A = B[4..7, "price".."mpg"]

However, the user would sometimes like to create a submatrix composed only of
rows and columns with names that contain certain variable names
or particular character strings. For example, suppose the right-hand-side
variables in an estimation includes variables p_1, p_2, p_3, q_2 and x.
The user might want to extract elements of the estimated coefficient vector
e(b) for the price variables p_1, p_2 and p_3,
regardless of their order in the coefficient vector.
Using the multiple character wild-card "*", the names of the relevant columns
of the estimated coefficients e(b) can be referenced by the character string
"p*". Or, using the single-character wild card "?",
the variables can be referenced by the character string "p??" or "p_?".

mluwild uses the "wild-card" features of Stata's string function strmatch
to extract rows or columns of a matrix whose names match the user's
specified template or mask. mluwild is especially useful
extract matrix elements associated with
factor variables, because all the categories of a
factor variable can be characterized by a template with approriately placed
wild-card characters. strmatch allows the wild-card character "?"
to signify a single unspecified character and the wild-card character "*"
to signify any number of unspecified contiguous characters.

The full row or column name of a Stata matrix consists of two parts, an equation
name followed by a row or column name. mulwild's rowid or
colid mask applies to the full column or row name.
Therefore, mluwild can select rows and/or columns
associated with a specific equation. See Example 4.

Examples

Example 1: Extracting from an arbitraty Stata matrix

mluwild can extract a submatrix from any Stata matrix by its row
and column names. Here is an example of extracting a submatrix
consisting only of the second row,
and of the columns with names beginning with the letter "p".

. matrix input A = (1,2,3,4,5\11,12,13,14,15)

. mat colnames A = x p_1 q_1 p_2 p_3

. mat list A

A[2,5]
x p_1 q_1 p_2 p_3
r1 1 2 3 4 5
r2 11 12 13 14 15

. mluwild A["r2","p*"], verbose

| p_1 p_2 p_3

+

r2 | 12 14 15

Example 2: Extracting from a matrix returned by a single-equation estimation command

mluwild Is particularly useful for extracting a submatrix from
a matrix of coefficient estimates returned by one of Stata's
estimation commands in the ereturn space.
Here is an example of extracting a submatrix from the
results returned by regress.

. sysuse auto, clear
(1978 Automobile Data)

. regress price mpg i.rep78

Source | SS df MS Number of obs = 69

+
F(5, 63) = 4.39
Model | 149020603 5 29804120.7 Prob > F = 0.0017
Residual | 427776355 63 6790100.88 R-squared = 0.2584

+
Adj R-squared = 0.1995
Total | 576796959 68 8482308.22 Root MSE = 2605.8

+

--------

price | Coef. Std. Err. t P>|t| [95% Con f. Interval]

+

--------

mpg | -280.2615 61.57666 -4.55 0.000 -403.3126 -157.2103
|
rep78 |
2 | 877.6347 2063.285 0.43 0.672 -3245.51 5000.78
3 | 1425.657 1905.438 0.75 0.457 -2382.057 5233.371
4 | 1693.841 1942.669 0.87 0.387 -2188.274 5575.956
5 | 3131.982 2041.049 1.53 0.130 -946.7282 7210.693
|
_cons | 10449.99 2251.041 4.64 0.000 5951.646 14948.34

+

--------

. matrix list e(b)

e(b)[1,7]
1b. 2. 3. 4. 5.
mpg rep78 rep78 rep78 rep78 rep78 _cons
y1 -280.26149 0 877.63472 1425.657 1693.841 3131.9822 10449.991

. mluwild e(b)["y1","*rep78"], verbose

| 1b. 2. 3. 4. 5.
| rep78 rep78 rep78 rep78 rep78

+

y1 | 0 877.6347 1425.657 1693.841 3131.982

. mluwild e(b)["*","*rep78"], verbose

| 1b. 2. 3. 4. 5.
| rep78 rep78 rep78 rep78 rep78

+

y1 | 0 877.6347 1425.657 1693.841 3131.982

. mluwild e(b)["y1","*b*"], verbose

| 1b.
| rep78

+

y1 | 0

Because -mluwild- does not accept numeric row or column ids,
the following command exits with an error, as expected.

. mluwild e(b)[1,"*rep78"]
Row and column id's must be specified as strings, not numbers
r(198);

Example 3: Extracting from a matrix returned by a multi-equation estimation command

mluwild extracts submatrices from the results of a multi-equation estimator.
For example, the three-stage-regression routine, reg3, generates
output like this:

. reg3 (price mpg i.foreign) (weight length i.foreign)

Three-stage least-squares regression

Equation Obs Parms RMSE "R-sq" chi2 P

price 74 2 2500.87 0.2712 20.21 0.0000
weight 74 2 247.1115 0.8975 654.75 0.0000

+

--------

| Coef. Std. Err. z P>|z| [95% Con f. Interval]

+

--------

price |
mpg | -231.8876 51.89553 -4.47 0.000 -333.601 -130.1743
|
foreign |
Foreign | 1459.13 680.7589 2.14 0.032 124.8667 2793.393
_cons | 10670.04 1084.844 9.84 0.000 8543.787 12796.3

+

--------

weight |
length | 29.72397 1.492087 19.92 0.000 26.79953 32.6484
|
foreign |
Foreign | -181.147 74.70834 -2.42 0.015 -327.5727 -34.72135
_cons | -2512.783 294.6176 -8.53 0.000 -3090.223 -1935.344

+

--------

Endogenous variables: price weight
Exogenous variables: mpg 0.foreign 1.foreign length

Stata arranges the e(b) vector of estimated coefficients as two concatenated row matrices,
one for each of the two estimated equations:

. matrix list e(b)

e(b)[1,8]
price: price: price: price: weight: weight: weight: weight:
0b. 1. 0b. 1.
mpg foreign foreign _cons length foreign foreign _cons
y1 -231.88764 0 1459.1296 10670.042 29.723966 0 -181.147 -2512.7833

mluwild can extract the columns of the matrix containing the coefficients of the factor variable i.foreign:

. mluwild e(b)["y1","*for*"], verbose

| price | weight
| 0b. 1. | 0b. 1.
| foreign foreign | foreign foreign

+

+

y1 | 0 1459.13 | 0 -181.147

By adding the option -omit-, the extracted matrix excludes the base level of i.foreign in both equations:

. mluwild e(b)["y1","*for*"], verbose omit

| price | weight
| 1. | 1.
| foreign | foreign

+
+

y1 | 1459.13 | -181.147

The estimated variance-covariance matrix from the above estimstion is:

. matrix list e(V)

symmetric e(V)[8,8]
price: price: price: price: weight: weight: weight: weight:
0b. 1. 0b. 1.
mpg foreign foreign _cons length foreign foreign _cons
price:mpg 2693.1458
price:0b.foreign 0 0
price:1.foreign -13319.772 0 463432.66
price:_cons -53396.794 0 145897.86 1176886.4
weight:length -26.012863 0 128.65452 515.75502 2.2263242
weight:0b.foreign 0 0 0 0 0 0
weight:1.foreign -717.67305 0 21002.359 9040.5517 61.422417 0 5581.3357
weight:_cons 5102.0228 0 -30422.302 -95968.717 -436.65925 0 -13202.58 86799.511

mluwild can extract the coefficients for i.foreign from the e(V) matrix,
omitting the elements associated with the base level:

. mluwild e(V)["*for*","*for*"], verbose omit

| price | weight
| 1. | 1.
| foreign | foreign

+
+

price | |
1.foreign | 463432.7 |

+
+

weight | |
1.foreign | 21002.36 | 5581.336

Example 4: Select based on the equation part of the row or column name

Using the approriate wild-card mask, mluwild can extract
elements of a matrix associated with a particular equation.
Here is the submatrix of estimated covariances between all price: equation
coefficients and the coefficient in the weight: equation
for the variable length:

. mluwild e(V)["price:*","*length"], omit

| weight
| length

+

price |
mpg | -26.01286
1.foreign | 128.6545
_cons | 515.755

Example 5: Factor variable interaction terms

Here is the submatrix of coefficients extracted from a specification that includes
an interaction term between a continuous variable, mpg,
and a discrete variable, i.foreign:

. regress price i.foreign##c.mpg

Source | SS df MS Number of obs = 74

+
F(3, 70) = 9.48
Model | 183435281 3 61145093.6 Prob > F = 0.0000
Residual | 451630115 70 6451858.79 R-squared = 0.2888

+
Adj R-squared = 0.2584
Total | 635065396 73 8699525.97 Root MSE = 2540.1

+

--------

price | Coef. Std. Err. t P>|t| [95% Con f. Interval]

+

--------

foreign |
Foreign | -13.58741 2634.664 -0.01 0.996 -5268.258 5241.084
mpg | -329.2551 74.98545 -4.39 0.000 -478.8088 -179.7013
|
foreign#c.mpg |
Foreign | 78.88826 112.4812 0.70 0.485 -145.4485 303.225
|
_cons | 12600.54 1527.888 8.25 0.000 9553.261 15647.81

+

--------

. mluwild e(b)["y1","*for*"], omit

| 1. 1.foreign#
| foreign c.mpg

+

y1 | -13.58741 78.88826

Stored results

After the commmands:

. sysuse auto, clear
(1978 Automobile Data)

. reg3 (price mpg i.foreign) (weight length i.foreign)

<output omitted>

. mluwild e(V)["*for*","*for*"], omit

mluwild returns the extracted submatrix, by default named submat,
and the following macros:

macros:
r(nkeptrows) : "2"
r(keptrows) : "price:1.foreign weight:1.foreign"
r(nkeptcols) : "2"
r(keptcols) : "price:1.foreign weight:1.foreign"
r(cnms) : "price:mpg price:0b.foreign price:1.foreign price:_cons weight:length weight:0b.foreign wei.."
r(rnms) : "price:mpg price:0b.foreign price:1.foreign price:_cons weight:length weight:0b.foreign wei.."

matrices:
r(submat) : 2 x 2

Author

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