help for rescaleVersion 3.3, 16Mar2020

Title

rescale - Rescale variables automatically by powers of ten

Syntax

rescale
varlist
[if exp]
[,
hundreds
thousands
millions
billions
trillions
automatic
format(string)
keeplabel
already(real)
truncmax(tmaxlist)
truncmin(tminlist)
positive
maxvalue(real)
minvalue(real)
]

--- or ---

rescale varlist , undo

Description

This command addresses the absence of a simple option in STATA graphics
for rescaling the axes to powers of 10 so that the axis labels are in
integers each of which signifies a number of (say) millions or billions
of the graphed variable.

This command also addresses a feature of STATA graphics that can limit
the flexibility of twoway graphs - STATA's refusal to limit an axis to a
range which is less than any of the variables plotted on that axis.
With the truncmax and truncmin options, one can allow STATA to ignore
the extreme values of a subset of the variables on an axis, scaling it to the
variables included in the arguments of these options.

Use a single rescale command for all the variables on a single axis.
If both axes need to be rescaled use a separate rescale command for
each axis.

Because rescale changes the data, the user is responsible for
returning the data to its original condition before saving the data set.
One way to do that is to execute rescale varlist, undo which
"unscales" the variables in varlist, returning them to their
original state. The user could of course also use STATA's preserve
command before executing rescale and STATA's restore command after
completing graphing work with the rescaled variables.

Basic syntax

Suppose variables y1 and y2 have maximum values in the millions and one
wants to graph then both against year. The twoway graph command would be:

twoway (y1 year) (y2 year)

The axis would be labeled with integers ending in six zeros, an eyesore.

Using the program rescale, this can be rectified as follows:

rescale y1, y2, auto

twoway (y1 year) (y2 year)

rescale y1, y2, undo

The axis tick marks will be labeled with aesthetically preferable
integers and the words "Millions of" will appear at the beginning of the
variable labels in the graph legend.

In another situation, suppose one is interested in the variation over
time in the variable z1, which has a range from thousands to millions.
Suppose one would like to superimpose on that graph a depiction of
variable z2, which has a range of thousands to billions. The twoway
graph command showing the time trends of these variables would be:

twoway (z1 year) (z2 year)

The axis would be labeled with integers ending in nine zeros to capture
the entire range of z2, which would not only be an eyesore but would
also squash z1 down along the horizontal axes.

Using the program rescale, the graph can be made to focus on z1,
including values of z2 only where they are within the range of z1. The
code is as follows:

rescale z1, z2, auto truncmax(z1)

twoway (z1 year) (z2 year)

rescale z1, z2, undo

How it works

This program creates temporary versions of variables to be used in a
graph command. The temporary variables have the same names as the
original variables, but are rescaled and/or truncated in order to fit on
a common axis.

The existing variables to be rescaled are retained in the data,
with the prefix "___". The data can be restored to their original state
by repeating the rescale command with the same variable list and the
option undo. Alternatively, the preserve command can be issued
before the rescale command so that the data can be subsequently restored.

Options

hundreds thousands millions billions trillions automatic or none.
Choosing one of these options determines in what units the re-scaled
variable will be displayed. Try the automatic option first since it's
easiest. If it doesn't produce a satisfactory graph, try one of the others.
The none option allows rescale to be used solely to truncate variables,
without rescaling them.

format. If the -format- option is selected, the specified format is
applied to all rescaled variables. Otherwise, all rescaled variables are
assigned either the format %9.0fc or, if the largest absolute value of
any of the rescaled variables is less than 4, the format %9.1fc.

truncmax, truncmin. STATA ordinarily, and quite properly, refuses to
drop observations merely in order to fit a variable inside the scale
chosen for a graph. The truncmax and truncmin options override this
behavior in a specific way. When these options are selected and used to
designate one or more of the variables in varlist, the range of ALL
the variables in varlist is set to the range of the designated
variables. Observations which exceed the maximum maximorum of the
variables in tmaxlist or are less than the minimimum minimorum of the
variables in tminlist are set to missing.

positive. The positive option is only relevant if truncmin is
specified. It forces the option truncmin to ignore non-positive values
of the variables in -tminlist- when computing the minimum. The effect is
to truncate at the smallest value which is greater than zero.

Two other options, maxvalue and minvalue, allow the user to
truncate all the variables in varlist so that all observations
greater than maxvalue or less than minvalue are set to missing in the
rescaled variables.

already(current_scale)}. - Specifies that the variable(s) to be rescaled
are already in units of current_scale. Legitimate values of
current_scale are any positive power of 10 no greater than 10^9. Without
this option, specifying rescale x, millions would create a variable
which is x/1,000,000. With the already(1000) option specified, the
same command would instead create the variable x/1,000. Suppose the
target unit is millions and x is already in thousands, while y is in units.
In this case, apply the command rescale as follows:
rescale x, millions already(1000)
rescale y, millions
and then use both x and y on the same axis like this:
twoway (line x year, sort) (line y year)

if. The if modifier allows the rescaled variables to apply to a
subset of observations. The rescaled version of the variables are set to
missing for other observations. This option is an alternative to
truncmin and truncmax for excluding observations outside the
desired boundaries of a graph.

keeplabel. This option prevents rescale from prefixing the variable
label with a unit designation.

Examples

Suppose one wants to graph the two variables totalcost and
cost2ndline on the same vertical axis. The variables range in value
from 26,000 to 8.5 billion. Here are the describe command and summarize
caoomand for these variables before the application of rescale.

. des totalcost cost2ndline year

storage display value
variable name type format label variable label
-------------------------------------------------------------------------------
totalcost float %9.0g Dollars of current total fiscal
burden of ART
cost2ndline float %9.0g US dollars cost of 2nd Line ART

. sum totalcost cost2ndline year

Variable | Obs Mean Std. Dev. Min Max
-------------+--------------------------------------------------------
totalcost | 15 3.70e+09 2.61e+09 3.15e+08 8.46e+09
cost2ndline | 15 1.71e+09 1.77e+09 9.51e+07 5.30e+09
year | 15 2013 4.472136 2006 2020

. rescale totalcost cost2ndline, auto <========= SIMPLEST USE OF RESCALE COMMAND

. return list <========= INFO RETURNED BY rescale

scalars:
r(unit) = 1000000000

macros:
r(varlist) : "totalcost cost2ndline"
r(oldvars) : "_$_totalcost _$_cost2ndline"
r(unitlbl) : "Billions"

. global unitlbl "`r(unitlbl)'" <===== PRESERVE NEW UNIT FOR USE BELOW

. des totalcost cost2ndline year <===== DEFAULT IS TO CHANGE THE VARIABLE LABELS

storage display value
variable name type format label variable label
-------------------------------------------------------------------------------
totalcost double %9.0fc Billions of US$ total fiscal
burden of ART
cost2ndline double %9.0fc Billions of US$ cost of 2nd
Line ART
year int %9.0g

. sum totalcost cost2ndline year <======== NOTE DIVISION BY 1,000,000,000

Variable | Obs Mean Std. Dev. Min Max
-------------+--------------------------------------------------------
totalcost | 15 3.704333 2.61264 .314595 8.463969
cost2ndline | 15 1.706435 1.771091 .095131 5.303343
year | 15 2013 4.472136 2006 2020

The output of the following graph command is now more easily readable.

. twoway (line totalcost year, sort) (line cost2ndline year), /*
*/ ytitle($unitlbl of US Dollars) legend(order(1 2) nostack cols(1))

When there are no more graphs to perform and the data was not
preserved before the rescale command was executed, REMEMBER TO undo
THE rescale COMMAND.

. rescale totalcost cost2ndline, undo

--------------------------------------------------------------------------

Now here's a second example for use when the variables are already
scaled, but not sufficiently. The original data is:

. des costtot cost2nd

storage display value
variable name type format label variable label
-------------------------------------------------------------------------------
costtot long %15.0fc Current total fiscal burden of
ART ($1,000's)
cost2nd long %15.0fc Cost of 2nd Line ART ($1,000's)

. sum costtot cost2nd

Variable | Obs Mean Std. Dev. Min Max
-------------+--------------------------------------------------------
costtot | 15 3704333 2612640 314595 8463969
cost2nd | 15 1706435 1771091 95131 5303343

. rescale costtot cost2nd, auto already(1000) <===== USE -already- OPTION

. global unitlbl "`r(unitlbl)'" <===== PRESERVE NEW UNIT FOR USE BELOW

. sum costtot cost2nd

Variable | Obs Mean Std. Dev. Min Max
-------------+--------------------------------------------------------
costtot | 15 3.704333 2.61264 .314595 8.463969
cost2nd | 15 1.706435 1.771091 .095131 5.303343

Note the use of the global macro $unitlbl with new unit from rescale
in the following graph command.

. twoway (line costtot year, sort) (line cost2nd year), /*
*/ ytitle($unitlbl of US Dollars) /*
*/ ytitle(, orientation (vertical) margin(large)) /*
*/ legend(order(1 "Fiscal burden of ART ($unitlbl of US$)" /*
*/ 2 "Cost of 2nd Line ART ($unitlbl of US$)") nostack cols(1))

. rescale costtot cost2nd, undo

. sum costtot cost2nd

Variable | Obs Mean Std. Dev. Min Max
-------------+--------------------------------------------------------
costtot | 15 3704333 2612640 314595 8463969
cost2nd | 15 1706435 1771091 95131 5303343

Again be sure to use rescale varlist, undo in order to "unscale" the
data. The rescaled versions of the variables, created by rescale are
dropped and the original versions are given back their original names.

Author

Mead Over,
Center for Global Development, Washington, DC 20036 USA. Email:
MOver@CGDev.Org if you observe any problems.