------------------------------------------------------------------------------- help forregaxisandlogaxis(Roger Newson) -------------------------------------------------------------------------------

Regular linear and logarithmic axis scales, ranges and tick lists

regaxis[varlist] [ifexp] [inrange] [,include(numlist)maxticks(#)singleokcycle(#)phases(numlist)margins(marginlist)pcratios(numlist)mcratios(marginratiolist)cbase(#)cppower(#)lrange(macname)lticks(macname)lrmin(macname)lrmax(macname)ltmin(macname)ltmax(macname)lntick(macname)lvmin(macname)lvmax(macname)grange(macname)gticks(macname)grmin(macname)grmax(macname)gtmin(macname)gtmax(macname)gntick(macname)gvmin(macname)gvmax(macname)]

logaxis[varlist] [ifexp] [inrange] [,include(numlist)maxticks(#)singleokbase(#)scalefactors(numlist)marginfactors(marginfactorlist)lrange(macname)lticks(macname)lrmin(macname)lrmax(macname)ltmin(macname)ltmax(macname)lntick(macname)lvmin(macname)lvmax(macname)grange(macname)gticks(macname)grmin(macname)grmax(macname)gtmin(macname)gtmax(macname)gntick(macname)gvmin(macname)gvmax(macname)]where

marginlistis a list of up to 2 non-negative numbers,marginratiolistis a list of up to 2 non-negative numbers, andmarginfactorlistis a list of up to 2 positive numbers equal to or greater than 1.

Description

regaxisgenerates a regular linear axis range and tick list for a list of variables and/or numbers to be included in the axis range.logaxisgenerates a regular logarithmic axis range and tick list for a list of variables and/or numbers to be included in the axis range. Both programs can output the elements of the axis range and/or tick list to be stored in local and/or global macros, which can then be used in Stata graphics commands as axis options and suboptions, such as the range() suboption of the xscale() and yscale() options, or the xlabel(), ylabel(), xtick() and ytick() options.

Input options forregaxisandlogaxis

include(numlist)specifies a list of numeric values that must be included in the range of values between the minimum tick and the maximum tick, in addition to all values specified in thevarlist. For example, if the user specifiesinclude(0), then the axis tick range will include zero, even if all values in thevarlistare positive.

maxticks(#)specifies the maximum number of ticks allowed on the axis. This number may not be less than 2 or greater than 1600. Ifmaxticks()is not specified, then it is set to 25, the maximum number of axis ticks allowed by the graph7 command. The number of ticks allowed is limited because Stata cannot handle numlists longer than 1600, but this limitation is not often important for graph axes in practice.

singleokspecifies that the output tick list can be a single tick if the data range contains only a single value equal to a valid tick mark position. Ifsingleokis not specified, and the data range contains only a single valid tick mark position, then the output tick list will also include one tick mark above that position and one tick mark below that position.

Input options forregaxisonly

cycle(#)specifies the cycle length of the sequence of axis ticks. The cycle length has the property that, ifcycleis the cycle length andtis a valid tick mark in the sequence, thent+cycleis also a valid tick mark in the sequence. Ifcycle()is not specified, then it is set to a sensible default value. (Most users do not need to know the definition of a "sensible default value", but more technically minded users can modify this definition by setting thecbase()andcppower()options below.)

phases(numlist)specifies a list of cycle phases at which the axis ticks appear. Ifphases()is not specified, then it is set using thepcratios()option, if that is specified, and otherwise defaults to a single value of 0. Axis ticks will be produced at positions of the form

tick_ij=phase_i+cycle*jwhere

jis an integer,iis an integer between 1 and the number of phases specified in thephases()option,phase_iis theith phase,cycleis the cycle length specified in thecycle()option, andtick_ijis the tick mark position. The integersjare chosen so that the tick marks span the nonmissing values in thevarlistand/or in theinclude()option.

margins(marginlist)specifies the lower and upper range margins, separating the lower and upper range limits from the minimum and maximum ticks, respectively. No more than 2 margins may be specified. If only one margin is given in themarginlist, then both margins are equal to that margin, If themargins()option is not specified, then it is set using themcratios()option if that is specified. Otherwise, both margins are set to 0, so that the axis range extends from the minimum tick to the maximum tick.

pcratios(numlist)specifies a list of phase/cycle ratios, which are used to define a list of values for thephases()option as a proportion of thecycle()option. Thepcratios()option is ignored if thephases()option is specified,

mcratios(marginratiolist)specifies a list of up to 2 margin/cycle ratios, which are used to define a list of values for themargins()option as a proportion of thecycle()option. If only one margin/cycle ratio is specified, then it is used to define both margins. Themcratios()option is ignored if themargins()option is specified,

cbase(#)specifies a logarithmic base used to define the default cycle length if thecycle()option is not specified. This logarithmic base must be positive, and is set to 10 if not specified by the user. Thecbase()option is ignored if the user specifies thecycle()option, but otherwise thecycle()option is defined using thecbase()option and thecppower()option (see below).

cppower(#)must be positive, and is set in default to twice thecbase()option. Thecbase()andcppower()options are used to define the default cycle length if thecycle()option is not supplied. Thecbase()andcppower()options are both ignored if the user specifies thecycle()option. Otherwise, thecycle()option is calculated as follows. Definevminto be the minimum value, andvmaxto be the maximum value, in thevarlistand/or in theinclude()option. If all values are missing, then define bothvminandvmaxto be zero. Then thecycle()option is set to 1 ifvmaxis equal tovmin, and is otherwise set to

cycle=cbase^ceil( log(vmax-vmin)/log(cbase) ) /cppowerwhere

cycleis the cycle length, thelog()andceil()functions are defined as in the help for mathematical functions, andcbaseandcppowerare the values of thecbase()andcppower()options. Therefore,cppoweris the number of cycles in the minimum integer power ofcbasethat is at least as large as the data range. The default valuescbase(10)andcppower(20)cause the tick positions to be "semi-round numbers", or multiples of5*10^k, wherekis a positive or negative integer.

Input options forlogaxisonly

base(#)specifies the logarithmic base of the axis ticks. This base must be strictly greater than one. Ifbase()is not specified, then it is set to the valuee=exp(1), implying that natural logarithms will be used to define the axis ticks.

scalefactors(numlist)specifies a list of scale factors defining the positions at which the axis ticks appear. Ifscale()is not specified, then it is set to a single value of 1. Axis ticks will be produced at positions of the form

tick_ij=scalefactor_i*base^jwhere

jis an integer,iis an integer between 1 and the number of scale factors specified in thescalefactors()option,scalefactor_iis theith scale factor,baseis the logarithmic base specified in thebase()option, andtick_ijis the tick mark position. The tick marks are chosen to span the nonmissing values in thevarlistand/or in theinclude()option.

marginfactors(marginfactorlist)specifies the lower and upper range margin factors. The lower range margin factor is the ratio of the minimum tick to the range minimum, and the upper range margin factor is the ratio of the range maximum to the maximum tick. For instance,marginfactors(1.01, 1.01)specifies that the range maximum is 1 percent greater than the maximum tick, and that the minimum tick is 1 percent greater than the range minimum. No more than 2 margin factors may be specified. If only one margin factor is given in themarginfactorlist, then both margin factors are equal to that margin factor, Ifmarginfactors()is not specified, then both margin factors are set to 1, so that the axis range extends from the minimum tick to the maximum tick.

Output options forregaxisandlogaxis

lrange(macname)inserts the axis range (a list of 2 numbers specifying the axis minimum and maximum) in a local macromacnamewithin the calling program's space. This macro will be accessible afterregaxisorlogaxishas finished. This is helpful for subsequent use, especially in therange()suboption of the graph axis scale optionsyscale(),xscale()ortscale().

lticks(macname)inserts the axis tick list in a local macromacnamewithin the calling program's space. This macro will be accessible afterregaxisorlogaxishas finished. This is helpful for subsequent use, especially in the graph axis label optionsylabel(),xlabel()ortlabel().

lrmin(macname)inserts the axis range minimum in a local macromacnamewithin the calling program's space.

lrmax(macname)inserts the axis range maximum in a local macromacnamewithin the calling program's space.

ltmin(macname)inserts the minimum tick in a local macromacnamewithin the calling program's space.

ltmax(macname)inserts the maximum tick in a local macromacnamewithin the calling program's space.

lntick(macname)inserts the number of axis ticks in a local macromacnamewithin the calling program's space.

lvmin(macname)inserts the minimum nonmissing value appearing in thevarlistand/or theinclude()option in a local macromacnamewithin the calling program's space. If there are no nonmissing values, then the value returned is 0 in the case ofregaxisand 1 in the case oflogaxis.

lvmax(macname)inserts the maximum nonmissing value appearing in thevarlistand/or theinclude()option in a local macromacnamewithin the calling program's space. If there are no nonmissing values, then the value returned is 0 in the case ofregaxisand 1 in the case oflogaxis.

grange(macname)inserts the axis range in the global macromacname.

gticks(macname)inserts the axis tick list in the global macromacname.

grmin(macname)inserts the axis range minimum in the global macromacname.

grmax(macname)inserts the axis range maximum in the global macromacname.

gtmin(macname)inserts the minimum tick in the global macromacname.

gtmax(macname)inserts the maximum tick in the global macromacname.

gntick(macname)inserts the number of axis ticks in the global macromacname.

gvmin(macname)inserts the minimum nonmissing value appearing in thevarlistand/or theinclude()option in the global macromacname.

gvmax(macname)inserts the maximum nonmissing value appearing in thevarlistand/or theinclude()option in the global macromacname.

Technical note

regaxisandlogaxisdefine an axis range and tick mark list to span the range of values of the variables in thevarlist(qualified by the if and in qualifiers if these are supplied) and/or the number list supplied by theinclude()option. Either thevarlist, or theinclude()option, or both may be absent. If all values are missing, thenregaxistakes the minimum and maximum values to be 0, andlogaxistakes the minimum and maximum values to be 1.A tick mark list is selected from the infinite sequence of candidate tick marks specified by the

cycle()andphase()options ofregaxis, or by thebase()andscalefactors()options oflogaxis. Initially, the tick mark list is defined as the shortest finite list of consecutive candidate tick marks with a maximum tick mark at or above the maximum value and a minimum tick mark at or below the minimum value. If the minimum and maximum tick marks are the same, andsingleokis not specified, thenregaxisandlogaxisadd one additional tick mark above and one additional tick mark below.If the number of tick marks defined in this way is greater than a maximum set by the

maxticks()option, thenregaxisandlogaxisrepeat the following procedure until the number of ticks is no more than themaxticks()value. If themaxticks()value is 2, then the first and last ticks are retained, and all others are removed. Otherwise, if there is more than one phase specified by thephases()option ofregaxis, or more than one scale factor specified by thescalefactors()option oflogaxis. then the last phase or scale factor is removed, and the axis is then redefined as before. Otherwise, if there is only one phase or scale factor, thenregaxisincrements thecycle()option by its original value, andlogaxismultiplies thebase()option by its original value, and the axis is then redefined as before.When a final list of tick marks has been defined, the range is set, using the

margins()option ofregaxisor themarginfactors()option oflogaxisto define a range minimum at or below the minimum tick and a range maximum at or above the maximum tick.

Examples

. regaxis. return list

. regaxis weight, include(0) lticks(xlabs). regaxis price, include(0) lticks(ylabs). scatter price weight, ylabel(`ylabs') xlabel(`xlabs')

. regaxis rep78, cycle(1) singleok margin(0.5) lrange(yrange)lticks(ylabs). regaxis weight, include(0) lticks(xlabs). scatter rep78 weight, yscale(range(`yrange')) ylabel(`ylabs')xlabel(`xlabs')

. regaxis length, cycle(12) lticks(xlabs). regaxis displacement, cycle(100) phases(0 70) lticks(ylabs). scatter displacement length, ylabel(`ylabs', angle(0)) xlabel(`xlabs')

. logaxis. return list

. logaxis length, base(2) scale(1 3 5) margin(1.05) lrange(xrange)lticks(xlabs). logaxis displacement, base(2) scale(1 3 5) lrange(yrange) lticks(ylabs). scatter displacement length, yscale(log range(`yrange'))ylabel(`ylabs', angle(0)) xscale(log range(`xrange')) xlabel(`xlabs')

Saved results

regaxisandlogaxissave the following results inr():

Scalars:

r(rmin)Range minimumr(rmax)Range maximumr(tmin)Minimum axis tick mark positionr(tmax)Maximum axis tick mark positionr(ntick)Number of axis ticksr(vmin)Minimum value invarlistand/orinclude()listr(vmax)Maximum value invarlistand/orinclude()list

Macros:

r(range)list of 2 values (the range minimum and maximum)r(ticks)list of axis tick mark positions

AuthorRoger Newson, National Heart and Lung Institute, Imperial College London, UK. Email: r.newson@imperial.ac.uk

Also seeManual:

[G] graph,[G]axis_options,[G]axis_scale_options,[G]axis_label_optionsOnline: help for graph, axis_options, axis_scale_options, axis_label_options