{smcl}
{* *! version 1.2.2 15may2018}{...}
{findalias asfradohelp}{...}
{vieweralsosee "" "--"}{...}
{vieweralsosee "[R] help" "help help"}{...}
{viewerjumpto "Syntax" "examplehelpfile##syntax"}{...}
{viewerjumpto "Description" "examplehelpfile##description"}{...}
{viewerjumpto "Options" "examplehelpfile##options"}{...}
{viewerjumpto "Remarks" "examplehelpfile##remarks"}{...}
{viewerjumpto "Examples" "examplehelpfile##examples"}{...}
{title:Title}
{phang}
{bf:submatrix} {hline 2} Advanced Stata matrix subsetting, sorting and deleting.
{marker syntax}{...}
{title:Syntax}
{p 8 17 2}
{cmd: submatrix}
{it: A}
[{cmd:,} {it:options}]
{it: A} is an existing Stata matrix
{synoptset 30 tabbed}{...}
{synopthdr}
{synoptline}
{syntab:Main}
{synopt:*{opt rownum(numlist)}} contains the numbers of the rows to be retained from {it: A} {p_end}
{synopt:*{opt droprownum(numlist)}} contains the numbers of the rows to be dropped from {it: A} {p_end}
{synopt:*{opt colnum(numlist)}} contains the numbers of the column to be retained from {it: A} {p_end}
{synopt:*{opt dropcolnum(numlist)}} contains the numbers of the column to be dropped from {it: A} {p_end}
{synopt:*{opt rownames(string)}} contains the names of the rows to be retained from {it: A} {p_end}
{synopt:*{opt droprownames(string)}} contains the names of the rows to be dropped from {it: A} {p_end}
{synopt:*{opt colnames(string)}} contains the names of the column to be retained from {it: A} {p_end}
{synopt:*{opt dropcolnames(string)}} contains the names of the column to be dropped {p_end}
{synopt:{opt rowv:arlist}} specifies that arguments in {opt droprownames} and {opt rownames} are variables {p_end}
{synopt:{opt colv:arlist}} specifies that arguments in {opt dropcolnames} and {opt colnames} are variables {p_end}
{synopt:{opt nam:esfirst}} return rows and columns based on their names first. {p_end}
{synopt:{opt ign:ore}} ignore non existing row and columns names and numbers from the subsetting options (*) . {p_end}
{synoptline}
{p2colreset}{...}
{p 4 6 2}
* subsetting options, duplicated arguments are allowed. {p_end}
{marker description}{...}
{title:Description}
{pstd}
{cmd:submatrix} returns subset of a Stata matrix based on row and columns names, numbers and equations.
Users can specify which row and/or column to keep or to drop.
{marker options}{...}
{title:Options}
{dlgtab:Main}
{phang}
{opt rownames(string)} controls the names of the rows to be retained from matrix {it: A}.
If {it: string} does not match any element of {it: A}
returns an error unless {opt ignore} is specified (see {it: {help matrix_subscripting}}).
Double quotes may be used to enclose strings that contain spaces.
{phang}
{opt droprownames(string)} controls the names of the rows to be dropped from matrix {it: A}.
If {it: string} does not match any element of {it: A}
returns an error unless {opt ignore} is specified (see {it: {help matrix_subscripting}}).
Double quotes may be used to enclose strings that contain spaces.
{phang}
{opt colnames(string)} controls the names of the columns to be retained from matrix {it: A}.
If {it: string} does not match any element of {it: A}
returns an error unless {opt ignore} is specified (see {it: {help matrix_subscripting}}).
Double quotes may be used to enclose strings that contain spaces.
{phang}
{opt dropcolnames(string)} controls the names of the columns to be dropped from matrix {it: A}.
If {it: string} does not match any element of {it: A}
returns an error unless {opt ignore} is specified (see {it: {help matrix_subscripting}}).
Double quotes may be used to enclose strings that contain spaces.
{phang}
{opt rownum(numlist)} controls the numbers of the rows to be retained from matrix {it: A}.
Exits with an error if any element of {it: numlist} is larger than the row number
of A unless {opt ignore} is specified (see {it: {help matrix_subscripting}}).
{phang}
{opt droprownum(numlist)} controls the numbers of the rows to be dropped from matrix {it: A}.
Exits with an error if any element of {it: numlist} is larger than the
row number of A unless {opt ignore} is specified (see {it: {help matrix_subscripting}}).
{phang}
{opt colnum(numlist)} controls the numbers of the columns to be retained from matrix {it: A}.
Exits with an error if any element of {it: numlist} is larger than the column
number of A unless {opt ignore} is specified (see {it: {help matrix_subscripting}}).
{phang}
{opt dropcolnum(numlist)} controls the numbers of the columns to be dopped from matrix {it: A}.
Exits with an error if any element of {it: numlist} is larger than the column
number of A unless {opt ignore} is specified (see {it: {help matrix_subscripting}}).
{phang}
{opt colvarlist} requests {cmd: submatrix} to treat the names in {opt rownames}
and {opt droprownames} as a {it:{help varlist}}. This option enables factor variable
expansion and the use of the * character for matching
one or more characters.
{phang}
{opt rowvarlist} requests {cmd: submatrix} to treat the names in {opt colnames}
and {opt dropcolnames} as a {it:{help varlist}}. This option enables factor variable
expansion and the use of the * character for matching
one or more characters.
{phang}
{opt namesfirst} prioritizes subsetting based on {cmd: rownames} and {cmd: colnames} rather than
using {cmd: rownames} and {cmd: colnames} first.
{phang}
{opt ignore} requests {cmd: submatrix} to ignore any out of range element from {it: A}.
It affects {opt rownames}, {opt droprownames}, {opt colnames}, {opt dropcolnames},{opt rownum},
{opt droprownum}, {opt colnum} and {opt dropcolnum}. Using this option forces
{cmd: submatrix} to return a result anyway.
{marker examples}{...}
{title:Example 1}
{pstd} Initializing matrix A {p_end}
{phang} {cmd:. matrix A=(1,3,4,6,7,8,10 \ 1,3,4,6,7,8,10)} {p_end}
{pstd} Retaining columns 1, 5 and 7 (results in {cmd: r(mat)}) {p_end}
{phang} {cmd:. submatrix A, colnum(1 5 7)} {p_end}
{phang} {cmd:. matlist r(mat) } {p_end}
{pstd} Same as above, using column names instead of numbers {p_end}
{phang} {cmd:. submatrix A, colnames(c1 c5 c7)} {p_end}
{phang} {cmd:. matlist r(mat) } {p_end}
{pstd} Dropping columns 2,3,4 and 6, using {cmd: dropcolnum} {p_end}
{phang}{cmd:. submatrix A, dropcolnum(2(1)4 6 ) } {p_end}
{phang} {cmd:. matlist r(mat) } {p_end}
{title:Example 2}
{pstd} Loading data {p_end}
{phang}{cmd:. webuse nlswork, clear}{p_end}
{pstd}A regression with a large number of coefficients and interactions{p_end}
{phang}{cmd:. xtreg ln_wage grade age c.age#c.age ttl_exp c.ttl_exp#c.ttl_exp tenure c.tenure#c.tenure 2.race not_smsa south i.year##(i.msp i.ind_code), be}{p_end}
{pstd} Saving the result matrix {p_end}
{phang}{cmd:. matrix results=r(table)}{p_end}
{pstd} Subsetting results using row and column names (note the use of {cmd: colvarlist} of factor variable notation to select all the interactions of {cmd: .1.msp} with {cmd: .year}){p_end}
{phang}{cmd:. submatrix results, rownames(b pvalue) colnames(tenure c.tenure#c.tenure south i.year#1.msp) colvarlist }{p_end}
{phang}{cmd:. matlist r(mat)', twidth(20)}{p_end}
{title:Example 3}
{pstd}Loading data{p_end}
{phang}{cmd:. webuse sysdsn1, clear}{p_end}
{pstd}Multinomial logit regression{p_end}
{phang}{cmd:. mlogit insure age male nonwhite i.site, base(3)}{p_end}
{pstd} Saving the result matrix {p_end}
{phang}{cmd:. matrix b=e(b)}{p_end}
{pstd} Selecting coefficients of age and male. for all equations but Uninsure (note the column operator). {p_end}
{phang}{cmd:. submatrix b, dropcolnames("Uninsure:") colnames(age male)}{p_end}
{phang}{cmd:. matlist r(mat)}{p_end}
{pstd} Resorting the columns by equation {p_end}
{phang}{cmd:. matrix b1=r(mat)}{p_end}
{phang}{cmd:. submatrix b1, colnames( Indemnity: Prepaid:)}{p_end}
{phang}{cmd:. matlist r(mat)}{p_end}
{marker storedresults}{...}
{title:Stored results}
{pstd}
{cmd:submatrix} stores the following in {cmd:r()}:
{synoptset 15 tabbed}{...}
{p2col 5 11 15 2:Matrices}{p_end}
{synopt:{cmd:r(mat)}} the submatrix {p_end}