-------------------------------------------------------------------------------
help for figout
-------------------------------------------------------------------------------

Title

figout -- Ancillary program for tabout to create mini datatsets suitable for graphing

Table of contents

Syntax Description Options Examples

Syntax

figout using , infile(string) gvars(string) over(string) start(string) stop(string) [replace(string)]

Description

figout is an ancillary program for tabout to facilitate the creation of graphs based on table panels. figout reads the output file produced by tabout looking for a start word or phrase. It then extracts the numbers it finds until it reaches the stop word or phrase. It only extracts the number of columns for which you indicate gvars, which conveniently avoids extracting the totals column. Each line in the panel becomes the basis for the over option in the subsequent graph. figout then loads those numbers into a mini dataset and saves it under the name you specify with using. If figout fails to find either the start word or the stop word, no mini dataset is produced and you are issued a warning. Once the mini dataset is created, it is an easy matter to create a Stata graph. The data is in a form suitable for graph's over option, and figout automatically creates an order variable for you, to preserve the same order that was used in your original table.

tabout has a comprehensive tutorial which includes a full example of using figout. This is available from the SSC with this help file. The tutorial is also available here: http://www.ianwatson.com.au/stata/tabout_tutorial.pdf.

Options

using is required, and indicates the filename for the output of the mini Stata dataset. Note that you do not need to add the dta filename extension.

infile is required the name of the output file produced by {\tt tabout}, for example, {\tt table1.tex}. Note that you do need to add the filename extension because you may be using {\tt figout} with any number of file types ({\LaTeX}, csv, or tab-delimited).

gvars are names you wish to assign to your graph variables, and they need to match a contiguous block of cells in your table. They are basically the categories of the horizontal variable in your table.

over is the name of the graph variable to be used by the over option in the graph command. It is one the panels in your table, and basically matches one of your vertical variables.

start is a unique word or phrase on the line above the block of cells. It can usually refer to the panel title in a tabout table, unless the title is repeated in another panel.

stop is a unique word or phrase on the line beneath the block of cells. In the case of LaTeX, you can just use \midrule since this generally indicates the end of a panel if you are using the ptotal(single) option.

replace is optional and follows usual Stata convention and prevents you accidentally over-writing an existing Stata dataset with your new mini dataset. If you are confident that there are no other datasets with the same name, you can use the replace option and this makes it more convenient if you need to develop your figout code using several attempts.

Examples

The best example is the one given in the tabout tutorial ( http://www.ianwatson.com.au/stata/tabout_tutorial.pdf) where it's use in batch files is demonstrated.

sysuse nlsw88, clear gen wt = int(uniform()*10)

tabout coll race smsa south [iw=wt] using fig_tab.tex, c(row) f(1) /// style(tex) bt font(bold) topf(top.tex) botf(bot.tex) topstr(10cm) /// botstr(nlsw88.dta) cl1(2-4) ptot(single)

figout using fig_fig, infile(fig_tab.tex) rep /// gvars(not_south south) /// over(race) start(Race) stop(\midrule)

gr hbar not_south south, over(race, sort(order)) /// ytitle("Percentage", size(medium) ) /// ylab(0(10)80, angle(0) format(%9.0f) ) /// bar(1,bcolor(gs4)) bar(2,bcolor(gs8)) /// legend(label( 1 "Does not live in south") /// label(2 "Lives in south") /// pos(4) cols(1) symxsize(3) ring(0) size(medium) ) /// graphregion(lstyle(solid)) /// scheme(s2mono) scale(1.1) saving(fig_fig,replace) gr use fig_fig.gph grexportpdf using fig_fig

Author

Ian Watson Freelance researcher and Visiting Senior Research Fellow Macquarie University Sydney Australia mail@ianwatson.com.au www.ianwatson.com.au

Version 1.0.1 21mar2007