Help File in Stata

Help files are an integral aspect of using Stata. For a user-written program such as multicat.ado, they become even more important because no documentation exists in the manuals. We can write a help file for multicat.ado by using Stata’s Do-file Editor to create a text file named multicat.sthlp. This help file should be saved in the same ado-file directory (for example, C:\ado\personal) as multicat.ado.

Any text file, saved in one of Stata’s recognized ado-file directories with a name of the form filename.sthlp, will be displayed onscreen by Stata when we type help filename. For example, we might write the following in the Do-file Editor, and save it in directory C:\ado\personal as file multicat.sthlp. Typing help multicat at any time would then cause Stata to display the text.

multicat — Multiple bar charts of categorical variables}

multicat varlist [aw = weightvar] [if exp] [in range], [missing] [by(groupvar)]

 

Description

multicat draws horizontal bar charts showing percentages of categorical variables. It saves one chart for each of the variables in varlist. Graphs are saved in the current default directory, with file names based on variable names preceded by a hyphen, such as -vote.gph or -region-vote.gph. They are saved both in Stata’s .gph format and one other graphical file format (.emf, .eps or .pdf) depending on operating system.

Using analytical weights [aw = weightvar] with multicat will result in percentages equivalent to those obtained by svy: tab applied to data declared as survey type, by a command such as svyset [pw = weightvar]. The svy: prefix cannot be used with multicat itself. Chapter 14 in

Statistics with Stata

(2012) has examples and discussion of multicat.

multicat requires that catplot is installed. Type

findit catplot for instructions on installing this unofficial

program, written by Nicholas Cox.

 

Options

missing       includes missing values in the bar chart and

calculated percentages.

by(groupvar) draws an image containing separate small charts for each value of groupvar.

 

Examples

multicat party wrongtrack vote

multicat party-vote [aw = weightvar], miss

multicat party-vote [aw = weightvar], by(region)

 

References

Hamilton, Lawrence C. 2012.

Statistics with Stata. Belmont, CA: Cengage

Nicer help files containing links, text formatting, dialog boxes, and other features can be designed using Stata Markup and Control Language (SMCL). All official Stata help files, as well as log files and onscreen results, employ SMCL. A recommended standard outline for help files appears in the User’s Guide.

The following is an SMCL version of the help file for multicat, roughly following the User’s Guide outline. Once this file has been saved in ado\personal with the file name multicat.sthlp, typing help multicat will produce a readable and official-looking display.

{smcl}

{* *! version 2.0 21jul2012}{___ }

{cmd:help multicat}

{hline}

 

{title:Title}

{phang}

{bf:multicat — Multiple bar charts of categorical variables}

 

{title:Syntax}

{p 8 17 12}

{cmd:multicat} {it:varlist} [{it:weight}] [{cmd:if} {it:exp}]

[ { cmd : in }     {it:range}]{cmd:,}     [ {cmdab : mi s s : ing} ]

[{cmd:by(}{it:groupvar}{cmd:)}]

{title:Description}

 

{pstd}

{cmd:multicat} draws horizontal bar charts showing percentages of categorical variables. It saves one chart for each of the variables in {it:varlist}. Graphs are saved in the current default directory, with file names based on variable names preceded by a hyphen, such as {it:-vote.gph} or {it:-region-vote.gph}. They are saved both in Stata’s .gph format and one other graphical file format (.emf, .eps or .pdf) depending on operating system.

{pstd}

Using analytical weights {cmd:[aw = }{it:weightvar}{cmd:]} with

{cmd:multicat} will result in percentages equivalent to those

obtained by {cmd:svy: tab} applied to data declared as survey type,

by a command such as {cmd:svyset [pw = }{it:weightvar}{cmd:]}. The

{cmd:svy:} prefix cannot be used with {cmd:multicat} itself. Chapter

14                   in                   {browse

“http://www.stata.com/bookstore/statistics-with-stata/index.html”:

Statistics with Stata} (2012) has examples and discussion of {cmd:multicat}.

{pstd}{cmd:multicat} requires that {cmd:catplot} is installed. Type {cmd:findit catplot} for instructions on installing this unofficial program, written by Nicholas Cox.

 

{title:Options}

{phang}

{cmdab:miss:ing} includes missing values in the bar chart and calculated percentages.

{phang}

{cmd:by(}{it:groupvar}{cmd:)} draws an image containing separate small charts for each value of {it:groupvar}.

 

{title:Examples}

{phang}

{cmd:. multicat party wrongtrack vote}

{phang}

{cmd:. multicat party-vote [aw = weightvar], miss} {phang}

{cmd:. multicat party-vote [aw = weightvar], by(region)}

 

{title:References}

{pstd}

Hamilton, Lawrence C. 2012.

{browse “http://www.stata.com/bookstore/statistics-with-stata/index.html”: Statistics with Stata}. Belmont, CA: Cengage.{p_end}

The help file begins with {smcl}, which tells Stata to process the file as SMCL. Curly brackets { } enclose SMCL codes, many of which have the form {command:text} or {command arguments:text}. The following examples illustrate how these codes are interpreted.

{cmd:help multicat} Display the text “help multicat” as a command. That is, show “help multicat” with whatever colors and font attributes are presently defined as appropriate for a command.

{hline}                       Draw a horizontal line.

{title:Title}                Display the text “Title” as a title.

{phang}                    Hanging indentation for the following paragraph.

{bf:multicat – …} Display text in boldface.

{p 8 17 12}                Format the following text as a paragraph, with the first line indented 8 characters, subsequent lines indented 17, and the right margin brought in 12 characters.

{it:varlist}                 Display the text varlist in italics.

{cmdab:miss:ing} Display “missing” as a command, with the letters “miss” marked as the minimum abbreviation.

{browse “http://www.stata.com/bookstore/statistics-with-stata/index.html”:Statistics…}

Link the text “Statistics with Stata” to the web address (URL) http://www.stata.com/bookstore/statistics-with-stata/index.html. Clicking on “Statistics with Stata” should then launch your browser and connect it to this URL.

The Programming Manual supplies details about using these and many other SMCL commands.

Source: Hamilton Lawrence C. (2012), Statistics with STATA: Version 12, Cengage Learning; 8th edition.