.-
help for ^addtex^ and ^hlTex^ 
.-

A very simple utility to display texts on a graph ------------------------------------------------- ^addtex^ [filename]

^hlTex^ workhorse called by addtex, analyzes magnifications and locates texts on plot.

Description -----------

It is tedious and sometimes difficult to add texts on a graph.

The little ^addtex^ program listed below will put stored texts in preassigned positions on an existing graph. The texts to be displayed must be stored in global macros (see below).

The program obeys desired magnification (also stored, default 100) and saves the resulting plot when a (new) filename is provided.

^addtex^ should not require modifications, ^hlTex^ may be enriched.

*-------------- prog def addtex *-------------- if "`1'"=="" { gph open } else { gph open , saving(`1') } gr /* reproduces last graph */ hlTex /* adds the stored texts */ gph close end *

Example -------

. use auto . graph mpg price . ^addtex^ mpg

Plot something and let ^addtex^ put some stored texts in fixed places on the graph. The modified graph is saved in file mpg.gph. That's all, no programming, all you need to do is prepare your texts.

Things might look a bit messy though, and it will usually be better to use Stata's ^bounding box^ in order to leave some free space where the texts can be displayed. Declaring, for instance,

. global bb bbox(3000,3000,20000,29000,923,444,0)

will permit 3000 all around (about 10% of the graphing area) and request a text size of 923 by 444 (the standard in @gph@), oriented horizontally.

So, the second attempt would look like:

. erase mpg.gph . graph mpg price, $bb [ other graph options ] . ^addtex^ mpg

If you dont like the size of your added texts, you may change their overall magnification which is stored in the global macro hlMag

Running addtex again after

. glob hlMag 90

redraws the original graph where the added texts are reduced (90%), while default texts remain unchanged because they are controlled by the bbox.

Remarks:

- it is not required to rerun graph, just addtex. - all Stata graph options and, in particular, the 8 standard textlines remain available. They won't overlap if bbox-margins are adequate. - the default of 100 for hlMag corresponds to the gph standard textsize

Stored texts ------------

^addtex^ calls ^hlTex^ to display the following texts in the indicated positions. They are in global macros whose names all start with hlTex.

^hlText1^ (t1) top line, left justified ^hlText2^ (t2) second line from top, also left justified

^hlTexb1^ (b1) bottom line, left justified ^hlTexb2^ (b2) second line from bottom, also left justified

^hlTexr^ (r) right: parsed, one word per line, ^hlTexl^ (l) left: also one word per line,

^hlTexc^ (c) lower right corner, typically for signature or date.

Enhancements ------------

Four conventions allow modification of the default presentation of added texts (see examples):

the first convention applies to all added texts, the second to top and bottom texts and the last two to right and left texts.

1. Overall text magnification is saved in global hlMag, but individual text magnification may be requested as part of each stored text and will be stripped away. The convention is to start the text with ^mag(^#^)^, where the number # is the desired magnification.

2. Top and bottom texts are left-aligned. You may want to shift these texts to the right. The convention is to put ^shr(^#^)^ immediately after the mag() request (if present) or at the start of the text otherwise. The # corresponds roughly to the percent (of the total width) shifted to the right.

3. Left and right texts are parsed and displayed from the top line down. However, an isolated period is interpreted as meaning "write nothing on this line", so you can start writing lower than the top line. The height of a line is always 150% of the character height, and small characters will therefore need more skipping to get to a specific level on the graph.

4. It is possible to use left or right texts as a legend. The convention is to put ^sym(^ ^)^ immediately after the mag() request (if present) or at the start of the text otherwise. The parens contain the symbols you want to associate with each word of the legend. A special character (the ~) is used to mean "no sym": eg ^sym(~AB)^ means no symbol associated with first word, A with the second, B with the third.

Examples --------

Suppose the following globals have been declared before the call to graph in the automobile example above (these declarations might have been grouped in a do file):

glo hlText1 ^mag(110)^A BEAUTIFUL TITLE, LEFT ALIGNED (mag 110%) glo hlText2 ^shr(8)^and a sub-title, shifted to the right glo hlTexb1 mag(60)^shr(15)^footnote: $bb glo hlTexr mag(70) . . $S_DATE . . . . . just to show the current date ! glo hlTexl mag(80) . . . . . . . . . . . . . guess what, we're using auto data glo hlTexc mag(70)GvM

Then ^addtex^ will apply the following rules:

top1 : magnify 110%; show title top2 : standard mag (as stored in hlMag) move about 8% to the right bot1 : mag 60; move about 15% to the right, display global bb right : mag 70; skip 2 lines, show parsed date, skip 5 lines, remainder left : mag 80; skip 13 lines, start showing corner: mag 70; hi there

Suppose you replace some declarations as follows:

glo repair REPAIR poor so-so ave ok good glo hlTexl mag(73)sym(~12345) . . . . . . . . . . . . . . . $repair glo bb bbox(4000,3000,21000,27000,900,450,0)

and you run . gr mpg pri , $bb border xla(5000,10000,15000) yla s([rep78])

then the legend for the 5 symbols is shown in the left margin with the word LEGEND on top, no symbol in front.

If you think this looks awfully overcrowded, just think you could display the standard t1,t2,b1,b2,l1,l2,r1,r2 texts as well!

Author ------ Guy D. van Melle, university of Lausanne, Switzerland email: guy.van-melle@@inst.hospvd.ch

Also see -------- gphdt (STB-34) H.J.Newton & J.W.Hardin manual: [R] gph on-line: @gph@