Statalist


[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

RE: st: Accessing and changing -graph- options in a program


From   "Nick Cox" <n.j.cox@durham.ac.uk>
To   <statalist@hsphsun2.harvard.edu>
Subject   RE: st: Accessing and changing -graph- options in a program
Date   Tue, 24 Feb 2009 13:52:11 -0000

In addition to Gary's excellent comments, here and in his previous: 

The generic issue I take to be that different (groups of) options may
need to be assigned within a program to different commands. If all
options (legitimately) may be assigned to e.g. -graph-, then as said
they can all be passed via a wildcard, subject to setting up defaults
within the program. If a user specifies something inappropriate, that's
mostly their problem, although the help should explain too!

Otherwise there is a trade-off between doing all the segregation
yourself and making the user do it. 

Studying actual examples shows some techniques. Here is a digest of
-rcspline.ado- from SSC, omitting parts irrelevant to this point. 

*! 1.0.0 NJC 23 Oct 2007 
program rcspline
	version 10 
	syntax varlist(numeric min=2 max=2) [if] [in] [fweight], ///
	[Stub(str) NKnots(passthru) Knots(passthru)              ///
	REGressopts(str) addplot(str asis) Generate(str)         ///
	SCatter(str asis) SHowknots CI CI2(str asis) Level(int
`c(level)') * ] 

/// 

		if "`stub'" == "" tempname stub 
		mkspline `stub' = `x' if `touse' [`weight' `exp'] ///
		, cubic `nknots' `knots'                

///

		regress `y' `stub'* if `touse' [`weight' `exp'] ,
`regressopts'

		if `"`ci'`ci2'"' != "" { 
///
			local ciplot rarea `ll' `ul' `x', sort `ci2' 
		}

	}

	twoway `ciplot'                         ///   
	|| scatter `y' `x' if `touse',          ///
	`scatter'                               ///
	|| mspline `pred' `x' if `touse',       /// 
	bands(200)                              ///
	note(`stat', place(w))                  ///
	`showk'                                 ///
	legend(nodraw)                          ///
	yti(`ytitle')                           ///
	xti(`xtitle')                           /// 
	`options'                               ///
	|| `addplot'                         

end 	

This uses four separate techniques. 

1. The program calls -mkspline-. Because of what -rcspline- does, the
-cubic- option is wired into the call of -mkspline-. The user may also
specify -mkspline-'s -nknots()- and -knots()- which are indicated in the
syntax as -passthru- (I am not responsible for the spelling here.) 

2. The program calls -regress-. Here I oblige the user who wants options
other than the default to put any and all such options in a bag called
-regressopts()-. -regress- will look inside that bag, if it is not
empty. A bag technique is easy to implement and of course suggested by
StataCorp's own practices. Similar comments apply to -scatter()-, which
is another bag. 

3. A mixed technique applies to -ci-. Here the user is told that the
-ci- option may be specified with and without arguments. How is that
implemented? There are actually two utterly separate options -ci- and
-ci2()-, but the user need not (and arguably should not) be told that.
As -ci2()- is flagged as an option that can be abbreviated as -ci()-,
the effect is exactly the same as an option that may or may not be given
arguments. 

4. Finally, all other options picked up via the wildcard end up
qualifying the call to -twoway mspline-. 

That certainly does not exhaust the possibilities. Specifically, look at
-help undocumented- to learn about StataCorp's own parsing options for
graphics programs. I've usually found it sufficient to use one or more
of the simple techniques above, but if I am starting from a StataCorp
graphics program that includes e.g. a call to -_get_gropts- I usually
leave it and the associated code untouched to do their magic. 

Nick 
n.j.cox@durham.ac.uk 

Gary Longton

Bert Jung wrote:

> Many thanks Gary.  Is there any way to restrict the `options' macro to
> contain only elements allowed by -graph-?  My worry is that the
> wildcard [ * ] would collect any user input and could generate an
> error message at the end of the program.

Not that I am aware of, at least not at the level of the syntax command.

But the only user input that will be collected in `options' is that not
allowed 
by your syntax statement otherwise.  If user input isn't explicitly
allowed by 
the -syntax- command or doesn't consist of valid twoway options allowed
by the 
internal graph command, then it seems to follow that your program
*should* 
return an error.

So the question isn't whether the disallowed user input will return an
error. 
It will and should return an error whether [*] is included or not.
Including 
[*], in addition to allowing the inclusion of -twoway options-, only
delays the 
disallowed syntax error until the -twoway- command is called.  The error

returned by the internal graph command resulting from disallowed
arguments 
passed via `options' will be a meaningful one - it should identify the
first 
disallowed argument in the list - and should be similar to that which
would 
otherwise be returned by the initial syntax command in -mygraph- if [*]
were not 
included.

If writing the program for other users, you are likely to include a help
file 
which will specify the allowed options for -mygraph-, including an entry

indicating that generic twoway_options are allowed.  Eg. The help file
line from 
-histogram-, an official Stata ado also which uses [*] to capture and
pass along 
graph command options reads:

. . .
options
   . . .
   twoway_options       any options documented in [G] twoway_options
. . .

So users will know that not just "any input" is allowed, but that any of
the 
standard -twoway options- are permitted.

*
*   For searches and help try:
*   http://www.stata.com/help.cgi?search
*   http://www.stata.com/support/statalist/faq
*   http://www.ats.ucla.edu/stat/stata/



© Copyright 1996–2014 StataCorp LP   |   Terms of use   |   Privacy   |   Contact us   |   What's new   |   Site index