version: 1.2.0
help flexmat July 19, 2021

Title

flexmat -- Creates a flexible matrix of real, string and complex elements

Syntax

flexmat
sub_command
,
[row(int)
col(int)
data(text or number)
filename(str)
reset
parse(str)
location(int)
newlocation
samelocation
swap
merge
matloc(int, int)
keep(int)
getlocinfo
emptyok
hidecw
]

Description

flexmat creates flexible matrices of text, numbers or both.
This program is specifically usesful 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.

Sub-commands

sub_commands

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

options

data(flexmat##data:text1, text2, ...) pass data contents, separated by a parse character

parse(flexmat##parse:comma, space, pipe) sepecify the parsing character used in the option data

row(flexmat##row:#) specify row number; default is 1

col(flexmat##col:#) specify column number; default is 1

location:(flexmat##location:#) specify location number; default is 1

filename(flexmat##filename:file_name) file name to store the flexmat output on disk

newlocation to build table on a new location

samelocation write contents to the last location used

swap replace contents of the last location used

matloc(flexmat##matloc:#,#) specify locations of matrices while merging(used with sub_command merge)

keep(flexmat##keep:#,#) used with the sub_command merge to keep existing matrices, eg keep(1) , keep(1,2)

locinfo report location number (used with the sub_command showmat)

hidecw hide control words (used with the sub_command showmat)

emptyok If need to add empty cells

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 seperated by a comma or any other delimters.
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 strated 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 seperated by a comma or any other delimters.
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 strated 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:

options

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 avaoid 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.
Therefoinsertrow 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 similr 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 fom addcol as insertrow 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 olumn, 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.

8. droploc : It deletes a location.
Option loc() must be used with this sub-command.

11. 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 thier first column. In other words, the two
matrices are merged on thier 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:

11.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).

11.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 newely merged matrix. Option keep(#,#)
can be used as as follows:

options

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 locaation 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 : displays 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

must specify the delimiter, with delimiter name in english.
See the following examples

options

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 enteties 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
locaton = 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 also displays the contents of the active flexmat file.

7. reploc Option reploc is used with flexmat show to
report the location numbers with data stored in different locations.

8. reset :
Option reset deletes any stored matrices. If the reset is used
withouth 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)

HOW TO EXPORT FLEXMAT TABLE

Once the flexmat file is ready, it can be then exported to any of the
asdocx's supported formats, that include MS Word, Excel, or LaTeX.
asdocx is a premium version of asdoc and is available for a nominal fee of $9.99.
Following is
the asdocx syntax for exporting flexmat files.

Syntax

asdocx exportflex
,
[asdocx_options]

Since the default output format is .docx, therefore, if just typed:

asdocx exportflex

the flexmat file will be exported to a Word file with .docx format. In case we wish to
send the output to an Excel file, then we would use the asdocx option
save(Myfile.xlsx). For example:

asdocx exportflex, save(Myfile.xlsx)

We can also use other asdocx options such as font(font_name) to change the font
family or fs(#) to set the font size of the document.

Author

::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: *
* *
* Dr. Attaullah Shah *
* Institute of Management Sciences, Peshawar, Pakistan *
* Email: attaullah.shah@imsciences.edu.pk *
* www.OpenDoors.Pk *
* www.FinTechProfessor.com *
*:::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::*

Also see

asdocx : Premium version - easy yet extremely powerful version of asdoc

asdoc : Easily send Stata tables to MW Word

asm: for momentum portfolios

astile : for creating fastest quantile groups

asgen : for weighted average mean

asrol : for rolling-window statistics

asreg : for rolling-window, by-group, and Fama and MacBeth regressions

ascol : for converting asset returns and prices from daily to a weekly, monthly, quarterly, and yearly frequency

searchfor : for searching text in data sets