[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" <>
To   <>
Subject   RE: st: Accessing and changing -graph- options in a program
Date   Wed, 25 Feb 2009 11:21:43 -0000

I should have stressed the difference between declaring an option -str- and -str asis-. 
The help for -syntax- does explain. The difference is especially important for graphics options which may well include quoted text strings. 


Bert Jung

Thanks Gary and Nick!

Since I would like my program to end before hitting the actual -graph-
command (there are some time-consuming calculations prior to that
command) I will use Nick's method of a "bag" of options like
-regressopts()- but appropriately named for my purposes.  That should
make users aware of what's allowed and I will duly explain myself in
the -help- file as Gary suggested.

On Tue, Feb 24, 2009 at 8:52 AM, Nick Cox <> wrote:
> 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 2007w
> 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
> 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:

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