.-
help for ^rescale^	   version 2.3                       04Mar2009
.-

Rescale variables automatically by powers of ten
-------------------------------------------------

	^rescale^ varlist [^if^ exp] [, ^h^undreds ^th^ousands ^m^illions 
		^b^illions ^tr^illions ^auto^matic ^f^ormat(string) 
		^keep^label ^al^ready(real) truncmax(tmaxlist) 
		truncmin(tminlist) positive]

	   ---  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 ^rescale^d 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, which
can be restored to its 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 and then
the data can be ^restore^d after its use. 

Options
-------
^h^undreds ^th^ousands ^m^illions ^b^illions ^tr^illions or ^auto^matic.
Choosing one of these options determines in what units the re-scaled 
variable will be displayed. Try the ^auto^matic option first since it's 
easiest.  If it doesn't produce a satisfactory graph, try one of the others. 

^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. 

^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 of actual use
======================

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
^preserve^d 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
MOver@CGDev.org
