Introduction to flexmat
flexmat is part of the asdocx package. It is the real engine behind asdocx. flexmat creates flexible matrices of text, numbers or both. This program is specifically useful when numeric and string results need to be stored in a matrix form or in a table. flexmat hardly throws any comfortability error. So we can add cells, rows, columns, or even previously stored matrices to the current matrix without worrying about comfortability or about mixing reals with string. The syntax of the flexmat is given below.
flexmat sub_command , [data(text or number) row(int) col(int) matname(str)
reset(str) parse(str)]
Sub-commands
| sub-command | Description |
|---|---|
| addcell | add a single cell to a table |
| addrow | add a row of data to a table |
| addcol | add a column of data to a table |
| addmat | add an existing matrix to a table |
| insertrow | insert a row of data to a table |
| insertcol | insert a column of data to a table |
| droprow | drop a row |
| dropcol | drop a column |
| droploc | drop a location; must be used with option location() |
| showmat | display the stored tables / matrices |
| merge | merge two matrices; must be used with the option matloc() |
| reset | deletes existing matrices and clears memory |
Options
| option | Description |
|---|---|
| data(text1, text2, …) | pass data contents, separated by a parse character |
| parse(comma, space, pipe) | specify the parsing character used in the option data |
| row(#) | specify row number; default is 1 |
| col(#) | specify column number; default is 1 |
| location:(#) | specify locations of matrices while merging(used with sub-command merge) |
| filename(file_name) | file name to store the flexmat output on disk |
| droprow | drop a row |
| dropcol | drop a column |
| droploc | drop a location; must be used with option location() |
| showmat | display the stored tables / matrices |
| merge | merge two matrices; must be used with the option matloc() |
| reset | deletes existing matrices and clears memory |
Details and Examples : Sub-commands
1. addcell
The sub-command addcell adds cells to a matrix. This sub-command has three required options : data(str), row(int), and col(int). Whatever we pass on to the program through the option data() is considered as one cell and is written to the row and column combination of row() and col(). Consider the following example :
Example 1 - Constructing a table / matrix cell by cell flexmat reset flexmat addcell, data(Year) row(1) col(1) flexmat addcell, data(Mean) row(1) col(2) flexmat addcell, data(StDe) row(1) col(3) flexmat addcell, data(2001) row(2) col(1) flexmat addcell, data(5.1%) row(2) col(2) flexmat addcell, data(1.5%) row(2) col(3)
and the resuling table looks like this;
0 | 1 2 3
----+---------------------------
1 | Year Mean StDe
----+---------------------------
2 | 2001 5.1% 1.5%
--------------------------------
2. addrow
The sub-command addrow adds a row to a matrix. It has three required options : data(data1, data2, data3, …), row(int), and col(int). The data items in the option data should be separated by a comma or any other delimiters. The default parsing character (delimiter) is comma. If delimiter is not the comma, then option parse(comma, space, pipe) has to be used to specify the delimiter. Let us continue writing to the same matrix that we started in the above example. This time, instead of writing individual cells, we shall write a complete row. Our row will start from row number 3 and column number 1. We shall use the default delimiter, i.e. comma, hence option parse(comma) is omitted.
Example 2 - add row to a table flexmat addrow, data(2002, 6.74, 1.68) row(3) col(1) flexmat addrow, data(2003, 6.58, 1.61) row(4) col(1)
With the addition of the two more rows, our table now looks like:
0 | 1 2 3
----+----------------------------
1 | Year Mean StDe
----+----------------------------
2 | 2001 5.1% 1.5%
3 | 2002 6.74 1.68
4 | 2003 6.58 1.61
---------------------------------
3. addcol
The sub-command addcol adds a colum to a matrix. This sub-command has three required options : data(data1, data2, data3,…), row(int), and col(int). The data items in the option data should be separated by a comma or any other delimiters. The default parsing character (delimiter) is comma ",". If the delimiter is not comma, then option parse(space, pipe) has to be used to specify the delimiter. Let us continue writing to the same matrix that we started previously. This time, we shall add two new columns. Our row will start from row number 1 and column number 4. We shall use the default parsing, i.e. comma.
Example 3 - add columns to a table flexmat addcol, data(Min, 0, .012, 0.025) row(1) col(4) flexmat addcol, data(Max, 0, .012, 0.025) row(1) col(5)
With the addition of two more columns, our table now looks like:
0 | 1 2 3 4 5
----+----------------------------------------
1 | Year Mean SD Min Max
----+----------------------------------------
2 | 2001 5.1% 1.5% 0 10%
3 | 2002 6.74 1.68 .012 11
4 | 2003 6.58 1.61 0.025 9
---------------------------------------------
4. addmat
This sub-command appends existing matrix to the matrix on file. The matrix can be either a current matrix in the Stata memory or a saved matrix on a file. In the later case, the file name should be supplied in the option matname(matrix_name). This sub-command has three required options : matname(matrix_name), row(int), and col(int). Further, addmat has three optional options, that can be used to skip adding names of rows, columns, or both rows and columns of the matrix that is being added. These options are summarized below:
nonames skip column and row names
nocolname skip the matrix column names
norowname skip the matrix row name
Example 4 – add a matrix
In the following example, let us first create a Stata matrix, name it A, and then add it to our previously created table. To avoid the matrix row and column names, we shall use the option nonames. Also, we shall use option dec(3) to restrict decimal points to only three.
mat A = J(2,5,runiform())
flexmat addmat, matname(A) row(5) col(1) nonames dec(3)
0 |1 2 3 4 5
----+---------------------------------------------------------------------
1 |Year Mean SD Min Max
----+---------------------------------------------------------------------
2 |2001 5.1% 1.5% 0 10%
3 |2002 6.74 1.68 .012 11
4 |2003 6.58 1.61 0.025 9
5 |0.370 0.370 0.370 0.370 0.370
6 |0.370 0.370 0.370 0.370 0.370
--------------------------------------------------------------------------
5. insertrow
The sub-command insertrow inserts a row to a matrix. It differs from the addrow in a sense that it creates an additional row, while addrow adds or replaces contents at the given cell and column combination. Therefore, insertrow will always increase the row count of the matrix by one. On the other hand, addrow will increase count of the rows only when the specified row(#) number is greater than the existing rows of the matrix. In other aspects, it is similar to the addrow option.
Example 5 - insert row at row location of 5
flexmat insertrow, data(2004, 7.74, 3.68, .04, 11) row(3) col(1)
With the insert of one more rows, our table now looks like:
0 |1 2 3 4 5
----+---------------------------------------------------------------------
1 |Year Mean SD Min Max
----+---------------------------------------------------------------------
2 | 2001 5.1% 1.5% 0 10%
3 | 2002 6.74 1.68 .012 11
4 | 2003 6.58 1.61 0.025 9
5 | 2004 7.74 3.68 .04 11
6 | 0.370 0.370 0.370 0.370 0.370
7 | 0.370 0.370 0.370 0.370 0.370
--------------------------------------------------------------------------
6. insertcol
The sub-command insertcol inserts a column to a matrix. it differs from addcol in a similar way asinsertrow differs from addrow.
Example 6 - insert column at column location of 6
flexmat insertcol, data(Median, 4, 5, 7, 9,0.370,0.370) row(1) col(6) row(1) col(6)
With the insert of one more column, our table now looks like:
0 |1 2 3 4 5 6
----+-------------------------------------------------------------------------------
1 |Year Mean SD Min Max Median
----+-------------------------------------------------------------------------------
2 | 2001 5.1% 1.5% 0 10% 4
3 | 2002 6.74 1.68 .012 11 5
4 | 2003 6.58 1.61 0.025 9 7
5 | 2004 7.74 3.68 .04 11 9
6 | 0.370 0.370 0.370 0.370 0.370 0.370
7 | 0.370 0.370 0.370 0.370 0.370 0.370
-----------------------------------------------------------------------------------
7. droprow
It deletes a row. Option row() must be used with this sub-command.
8. dropcol
It deletes a column. Option col() must be used with this sub-command.
9. droploc
It deletes a location. Option loc() must be used with this sub-command.
10. merge
It merges two matrices; must use option matloc(), row() and col(). Think of merge as 1:1 merge of the official merge command. The two matrices are merged from two difference locations on the same filename. The merge happens on the similarity of contents of the two matrices in their first column. In other words, the two matrices are merged on their first columns. Values that are not merged, are added to the merged matrix at its end. The sub-command merge has one required option matloc(#,#) and one optional option opt keep(#,#). These are discussed below:
10.1 matloc(#,#): The location numbers are specified in the option matloc(#,#). For example, if the two matrices are located at location 1 and 2, the option matloc() will be typed as matloc(1,2).
10.2 keep(#,#): Further, we can use option keep(#,#) to keep either the first matrix one, the second matrix, or both in the flexmat system. If option keep(#,#) is not used, flexmat will delete these matrices and will keep just the newly merged matrix. Option keep(#,#) can be used as as follows:
options Description
—————————————————————————————————————————————–
keep(1) To keep the merged matrix and the first matrix in flexmat
keep(2) To keep the merged matrix and the second matrix in flexmat
keep(1,2) To keep the merged matrix and both the first and the second matrix in flexmat
—————————————————————————————————————————————–
Example 7 – merge two matrices of location 1 and 2
As shown in Example 6 above, we have a matrix that is currently stored in the default location of 1. Let us first create another matrix at location 2, and then merge it with the matrix at location. To expedite the process, let us use option addrow() to write full row in one line of code.
flexmat addrow, data(Year, P75) loc(2) flexmat addrow, data(2001, 4%) loc(2) row(2) flexmat addrow, data(2004, 9.3) loc(2) row(3)
The flexmat contents at this stage look like this: Note the loc = 1 and loc = 2, that show the location information of the two
matrices.
flexmat showmat, locinfo Loc = 1 0 |1 2 3 4 5 6 ----+------------------------------------------------------------------------------- 1 |Year Mean SD Min Max Median ----+------------------------------------------------------------------------------- 2 |2001 5.1% 1.5% 0 10% 4 3 |2002 6.74 1.68 .012 11 5 4 |2003 6.58 1.61 0.025 9 7 5 |2004 7.74 3.68 .04 11 9 6 |0.349 0.349 0.349 0.349 0.349 0.037 7 |0.349 0.349 0.349 0.349 0.349 0.370 ------------------------------------------------------------------------------------ Loc = 2 0 |1 2 ----+--------------------------- 1 |Year P75 ----+--------------------------- 2 |2001 4% 3 |2004 9.3 -------------------------------- The two matrices have three values in common in thier first rows: Year, 2001, 2004. Now let us merge the two matrices. flexmat merge, matloc(1,2) 0 |1 2 3 4 5 6 7 ----+------------------------------------------------------------------------------------- 1 |Year Mean SD Min Max Median P75 ----+------------------------------------------------------------------------------------- 2 |2001 5.1% 1.5% 0 10% 4 4% 3 |2002 6.74 1.68 .012 11 5 4 |2003 6.58 1.61 0.025 9 7 5 |2004 7.74 3.68 .04 11 9 9.3 6 |0.349 0.349 0.349 0.349 0.349 0.370 7 |0.349 0.349 0.349 0.349 0.349 0.370 ------------------------------------------------------------------------------------------
12. showmat
Option showmatdisplays the contents of the active flexmat file. The sub-command does not need any option. For example:
flexmat showmat
Options
1. data(text1, text2):
Option data() receives data contents (text, numeric, or alpha-numeric) and builds table cells with it. With the sub-commands addrow and addcol, flexmat parses the input data using the default delimiter of comma, i.e. “,”. Each of the parsed token then goes to the specified cells of the table. However, with the sub-command addcell, flexmat does not parse the input data and considers everything as part of a single cell.
2. parse(comma, semicolon, colon, space, pipe):
When using the sub-commands addrow or addcol, data contents must be delimited by a delimiter such as comma ,, semicolon ;, colon :, space , or pipe |. Option parse() must specify the delimiter, with delimiter name in English. See the following examples:
parse(comma) parsing on comma, that is “,”
parse(semicolon) parsing on semicolon, that is “;”
parse(colon) parsing on colon, that is “:”
parse(space) parsing on space, that is ” ”
parse(pipe) parsing on pipe, that is “|”
3. row(int) and col(int):
Both option row() and col() accept integers and marks the starting point at which the data contents are written in the matrix / table. The default of both the options is 1, hence if these options are not used, the data is written to the first row and first column combination of the table, that is cell 1. To increase readability of the flexmat table, the output is shown with the row and column number on the screen. If data is written to a cell, row, or a column, that has existing contents, it is over-written without any warning. However, if data is written to a new cell, row, or a column, flexmat will automatically add the new element to the matrix and populate it with the given data.
4. location(int):
The concept of locations in flexmat is to create separate entities or files. A simple example would be to create two matrices, keep them separate, and have an ability to access and modify their elements. We would then call matrix 1 as location = 1, and matrix 2 as location = 2. This way flexmat can hold multiple matrices and text blocks, and still provide its users an ability to access and modify these with convenience. By default, data is written to location = 1.
Example 5 – add table / matrix at location 2
mat B = J(2,5,runiform())
flexmat addmat, matname(B) nonames loc(2)
Example 6 – modify the matrix at location 2
flexmat addcell, data(Year) row(1) col(1) loc(2)
flexmat addcell, data(Mean) row(1) col(1) loc(2)
flexmat addcell, data(SD) row(1) col(1) loc(2)
flexmat addrow, data(2010, 1200, 1300) row(3) loc(2)
flexmat addcol, data(Min, .023, 1400) c(4) loc(2)
5. filename(file_name):
flexmat writes its matrices to a file on disk. The default file name used by flexmat is stored_results.flexmat. It is stored in the current directory. However, if you have used asdocx in the current Stata session, then asdocx borrows the file name from there and is saved in the “current_direcor\_asdocx” directory, where current_directory is not a literal name, it is the current directory where Stata is currently saving / reading files from. Both the .flexmat extension and the file name “stored_results” can be changed.
However, unless it is necessary to change these, it is not advised to change them. The reason is that once you change them, then you must use the option matname() to tell flexmat which file are you reading from when writing further contents to the file.
6. getlocinfo
It writes the highest location number to a global macro flexmat_current_loc. This command is rarely used. Actually, getlocinfo is used by asdocx to find next available location for writing contents. Besides writing this global macro, it displays the contents of the active flexmat file.
7. reploc
Option reploc is used with the sub-command flexmat showmat to report the location numbers.
8. reset
Option reset deletes any stored matrices. If option reset is used without any option, it will delete the default matrices, i.e stored_results.flexmat file in the current directory. reset(mydirectory/filename.ext) will delete file filename.ext in the mydirectory.
Example 7 – reset / delete locations
* Reset the active flexmat file
flexmat reset
* Reset a specific file in a given directory
flexmat reset(c:/flex/Mytable.flexmat)
Detailed Discussion on sub-commands
1. addcell
addcell adds cells to a matrix. This sub-command has three required options : data(str), row(int), and col(int). Whatever we pass on to the program through option data() is considered as one cell and is written to row and column combination of row() and col(). Therefore, row(1) means row number 1 and col(1) means column number 1. In the following examples, I am writing Year to the first row and first column of the table / matrix. But before that, on code line 1, I use the flexmat reset command to delete any previously stored information and clear the memory or stored matrix.
Code line 2: I add the text “Year” to the first row and first column using the addcell sub-command
Code line 3: Add the text “Mean” to row 1 and column 2. At this point, flexmat starts adding column and row number to the output table so that we can easily identify the column and row number of the table / matrix.
Code line 4: Add the text “SD” to the same row, that is row 1, and column 3.
Code line 5: Now, change to row 2 and add text “2001” at column 1.
Continue adding additional text till code line 7.
Examples : Add Cells
* Code line 1
flexmat reset
* Code line 2
flexmat addcell, data(Year) row(1) col(1)
Year
* Code line 3
flexmat addcell, data(Mean) row(1) col(2)
1 2
+---------------+
1 | Year Mean |
+---------------+
* Code line 4
.flexmat addcell, data(SD) row(1) col(3)
1 2 3
+----------------------+
1 | Year Mean SD |
+----------------------+
* Code line 5
flexmat addcell, data(2001) row(2) col(1)
0 |1 2 3
----+-----------------------------------
1 |Year Mean SD
----+-----------------------------------
2 |2001
----------------------------------------
* Code line 6
flexmat addcell, data(5.1%) row(2) col(2)
0 |1 2 3
----+-----------------------------------
1 |Year Mean SD
----+-----------------------------------
2 |2001 5.1%
----------------------------------------
* Code line 7
flexmat addcell, data(1.5%) row(2) col(3)
0 |1 2 3
----+-------------------------------------
1 |Year Mean SD
----+-------------------------------------
2 |2001 5.1% 1.5%
------------------------------------------