Regular linear and logarithmic axis scales, ranges and tick lists
regaxis [ varlist ] [if exp] [in range] [, include(numlist) maxticks(#) singleok cycle(#) 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 ] [if exp] [in range] [, include(numlist) maxticks(#) singleok base(#) 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 marginlist is a list of up to 2 non-negative numbers, marginratiolist is a list of up to 2 non-negative numbers, and marginfactorlist is a list of up to 2 positive numbers equal to or greater than 1.
Description
regaxis generates a regular linear axis range and tick list for a list of variables and/or numbers to be included in the axis range. logaxis generates 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 for regaxis and logaxis
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 the varlist. For example, if the user specifies include(0), then the axis tick range will include zero, even if all values in the varlist are positive.
maxticks(#) specifies the maximum number of ticks allowed on the axis. This number may not be less than 2 or greater than 1600. If maxticks() 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.
singleok specifies 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. If singleok is 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 for regaxis only
cycle(#) specifies the cycle length of the sequence of axis ticks. The cycle length has the property that, if cycle is the cycle length and t is a valid tick mark in the sequence, then t+cycle is also a valid tick mark in the sequence. If cycle() 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 the cbase() and cppower() options below.)
phases(numlist) specifies a list of cycle phases at which the axis ticks appear. If phases() is not specified, then it is set using the pcratios() 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 * j
where j is an integer, i is an integer between 1 and the number of phases specified in the phases() option, phase_i is the ith phase, cycle is the cycle length specified in the cycle() option, and tick_ij is the tick mark position. The integers j are chosen so that the tick marks span the nonmissing values in the varlist and/or in the include() 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 the marginlist, then both margins are equal to that margin, If the margins() option is not specified, then it is set using the mcratios() 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 the phases() option as a proportion of the cycle() option. The pcratios() option is ignored if the phases() 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 the margins() option as a proportion of the cycle() option. If only one margin/cycle ratio is specified, then it is used to define both margins. The mcratios() option is ignored if the margins() option is specified,
cbase(#) specifies a logarithmic base used to define the default cycle length if the cycle() option is not specified. This logarithmic base must be positive, and is set to 10 if not specified by the user. The cbase() option is ignored if the user specifies the cycle() option, but otherwise the cycle() option is defined using the cbase() option and the cppower() option (see below).
cppower(#) must be positive, and is set in default to twice the cbase() option. The cbase() and cppower() options are used to define the default cycle length if the cycle() option is not supplied. The cbase() and cppower() options are both ignored if the user specifies the cycle() option. Otherwise, the cycle() option is calculated as follows. Define vmin to be the minimum value, and vmax to be the maximum value, in the varlist and/or in the include() option. If all values are missing, then define both vmin and vmax to be zero. Then the cycle() option is set to 1 if vmax is equal to vmin, and is otherwise set to
cycle = cbase^ceil( log(vmax-vmin)/log(cbase) ) / cppower
where cycle is the cycle length, the log() and ceil() functions are defined as in the help for mathematical functions, and cbase and cppower are the values of the cbase() and cppower() options. Therefore, cppower is the number of cycles in the minimum integer power of cbase that is at least as large as the data range. The default values cbase(10) and cppower(20) cause the tick positions to be "semi-round numbers", or multiples of 5*10^k, where k is a positive or negative integer.
Input options for logaxis only
base(#) specifies the logarithmic base of the axis ticks. This base must be strictly greater than one. If base() is not specified, then it is set to the value e=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. If scale() 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^j
where j is an integer, i is an integer between 1 and the number of scale factors specified in the scalefactors() option, scalefactor_i is the ith scale factor, base is the logarithmic base specified in the base() option, and tick_ij is the tick mark position. The tick marks are chosen to span the nonmissing values in the varlist and/or in the include() 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 the marginfactorlist, then both margin factors are equal to that margin factor, If marginfactors() 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 for regaxis and logaxis
lrange(macname) inserts the axis range (a list of 2 numbers specifying the axis minimum and maximum) in a local macro macname within the calling program's space. This macro will be accessible after regaxis or logaxis has finished. This is helpful for subsequent use, especially in the range() suboption of the graph axis scale options yscale(), xscale() or tscale().
lticks(macname) inserts the axis tick list in a local macro macname within the calling program's space. This macro will be accessible after regaxis or logaxis has finished. This is helpful for subsequent use, especially in the graph axis label options ylabel(), xlabel() or tlabel().
lrmin(macname) inserts the axis range minimum in a local macro macname within the calling program's space.
lrmax(macname) inserts the axis range maximum in a local macro macname within the calling program's space.
ltmin(macname) inserts the minimum tick in a local macro macname within the calling program's space.
ltmax(macname) inserts the maximum tick in a local macro macname within the calling program's space.
lntick(macname) inserts the number of axis ticks in a local macro macname within the calling program's space.
lvmin(macname) inserts the minimum nonmissing value appearing in the varlist and/or the include() option in a local macro macname within the calling program's space. If there are no nonmissing values, then the value returned is 0 in the case of regaxis and 1 in the case of logaxis.
lvmax(macname) inserts the maximum nonmissing value appearing in the varlist and/or the include() option in a local macro macname within the calling program's space. If there are no nonmissing values, then the value returned is 0 in the case of regaxis and 1 in the case of logaxis.
grange(macname) inserts the axis range in the global macro macname.
gticks(macname) inserts the axis tick list in the global macro macname.
grmin(macname) inserts the axis range minimum in the global macro macname.
grmax(macname) inserts the axis range maximum in the global macro macname.
gtmin(macname) inserts the minimum tick in the global macro macname.
gtmax(macname) inserts the maximum tick in the global macro macname.
gntick(macname) inserts the number of axis ticks in the global macro macname.
gvmin(macname) inserts the minimum nonmissing value appearing in the varlist and/or the include() option in the global macro macname.
gvmax(macname) inserts the maximum nonmissing value appearing in the varlist and/or the include() option in the global macro macname.
Technical note
regaxis and logaxis define an axis range and tick mark list to span the range of values of the variables in the varlist (qualified by the if and in qualifiers if these are supplied) and/or the number list supplied by the include() option. Either the varlist, or the include() option, or both may be absent. If all values are missing, then regaxis takes the minimum and maximum values to be 0, and logaxis takes 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() and phase() options of regaxis, or by the base() and scalefactors() options of logaxis. 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, and singleok is not specified, then regaxis and logaxis add 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, then regaxis and logaxis repeat the following procedure until the number of ticks is no more than the maxticks() value. If the maxticks() 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 the phases() option of regaxis, or more than one scale factor specified by the scalefactors() option of logaxis. 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, then regaxis increments the cycle() option by its original value, and logaxis multiplies the base() 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 of regaxis or the marginfactors() option of logaxis to 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
regaxis and logaxis save the following results in r():
Scalars:
r(rmin) Range minimum r(rmax) Range maximum r(tmin) Minimum axis tick mark position r(tmax) Maximum axis tick mark position r(ntick) Number of axis ticks r(vmin) Minimum value in varlist and/or include() list r(vmax) Maximum value in varlist and/or include() list
Macros:
r(range) list of 2 values (the range minimum and maximum) r(ticks) list of axis tick mark positions
Author
Roger Newson, National Heart and Lung Institute, Imperial College London, UK. Email: r.newson@imperial.ac.uk
Also see
Manual: [G] graph, [G] axis_options, [G] axis_scale_options, [G] axis_label_options Online: help for graph, axis_options, axis_scale_options, axis_label_options