pvplot: PathView plot command - 2008-01-31
.-

OVERVIEW

The commands -pvdata- and -pvplot- are used to plot categorical data using
a modification of parallel coordinates. Since many observations can have the
same values, small offsets are added to the data to allow all observations
to be represented by a line (i.e., a path). -pvdata- prepares the data for
plotting and -pvplot- plots the data.

You can use -pvp- as an abbreviation for -pvplot3-.

SYNTAX

    pvplot varlist, [options]

OPTIONS

Recent additions
================

Quietly                 Do not show graph, only change options.
                        [EXPAdd] /// add number to export
EXPAdd                  Add a counter to the last name of the export
                        file which allows you to generate new graphs without
                        having to change the name of the export file when
                        working interactively.

Interactive mode
================
Reset                   Build the plot from scratch by resetting all
                        options rather than using prior options. When you 
                        do not turn off interactive mode, options from 
                        the last graph are used unless you specify them again.
                        To remove an option that was set before, you can drop
                        it such as: pvdata, hidecolor(drop).

Colors
======

COLVar(varname)         Colors vary by categories of this variable
                        By default, the colors are: red green blue 
                        cyan magenta yellow. If COLV(2cat), use red blue.
                        If COLV(3cat), use red blue green. If COLV(4cat),
                        use red blue green gold. If COLV(5cat) use
                        red blue green gold purple. If COLV(bw), use ???
COLors(color-names)     Colors used by colvar
COLIntensity(values)    Intensities from 0 to 1 corresponding to colors
COLRange(min max)]      Minimuim and maximum values of colvar. This is
                        only needed if colvar has gaps.

INTVar(varname)         Intensity varies by categories of this variable
INTensity(values)       Intensities from 0 to 1 corresponding to categories
                            of intevar
INTRange(min max)]      Minimuim and maximum values of intvar. This is
                        only needed if intvar has gaps.

Show and hide paths
===================
SHOWIF(if-condition)    Show lines if this condition holds; otherwise lines
                            are drawn with hidecolor
HIDEIF(if-condition)    Hide lines if this condition holds using hidecolor;
                             otherwise lines are shown.
HIDEColor(color)        Color for hidden lines; white for to now show.
HIDEINTensity(value)    Intensity of hidden lines

Grids, labels and borders
=========================

angle                   Put labels on an angle
CAPtion(passthru)       Caption using standard Stata options.
TItle(passthru)         Title using standard Stata options.
SUBtitle(passthru)      Subtitle using standard Stata options.
note(passthru)          Note using standard Stata options.

GRIDColor(color)        Color of grid lines
GRIDWidth(real .3)      Width of grid line
GRIDYWidth(real .2)     Width of vertical grid line
GRIDSpace(integer 10)   Space from grid to paths
BORDER                  Add shading around graph
YLABOFFset(real .25)    Add offet to y label
LABELSize(string)]      Size of axes labels: tiny vsmall small medsmall
                            medium medlarge large vlarge
ASPECTratio(real 1)]    Aspect ratio of graph

Control of paths
================

PATHWidth(real .01)]    Line width of paths
Delta(real)             Size of offset between lines

Other options
=============

OPTions(string)         These options are sent to Stata's graph command.
EXport(string)          Name of export file with suffix png for PNG, etc.
SAMPLE(0 to 100)        Sample this percent of cases


HOW COLORS ARE CONTROLLED
.-

Colors are controlled both by the hue which is specified by a names such as red
and by the intensity which is controlled by a number from 0 to 1 where smaller
numbers produce lighter colors. Hue and intensity can be controlled in two
ways.

First, you can control color and intensity with:

    cvar() to specify the name of the variable whose categories will determine
    the color of a path.

    colors() controls which colors are used for which categories.

    colintensity() specifies the intensity for each color.

For example:

pvplot3 , ///
    colv(sdneighb) colors(red blue orange green)

or:

  pvplot3 , ///
    colv(sdneighb) colors(red blue orange green) ///
    colintensity(.1 .1 1 1)

Intensity can also by controlled by a different variable. Here
colors are controled by the first item and intensity by the last item:

  pvplot3 , ///
    colv(sdneighb) colors(red blue orange green) ///
    int(.25 .5 .75 1) intvar(sdmarry)

You can also control the color by a variable that isn't an item:

  pvplot3 , ///
    colv(nokids) colors(orange green)

Or, let color be controlled by an item and intensity by another variable:

  pvplot3 , ///
    colv(sdneighb) colors(red blue orange green) ///
    intv(nokids) intensity(.25 1)

If you specify intensity both with colintensity and intensity, the
intensity of a path is a product of the intensity from colvar and
intvar.

Specifying intensities: You can use decimal digits from 0 to 1. Or, you
can use the text string hi to indicate 1, med for .6, low or lo for .2.

INTERACTIVE MODE
.-

Interactive mode makes it simpler to modify an existing graph. To understand
how this works, consider an example. Suppose you create a graph with the
command:

  pvplot3 , ///
    colv(sdneighb) colors(red blue orange green) ///
    gridspace(3) aspect(1) ///
    title("my interactive example", size(small)) ///
    caption(Source: mypgm.do - 2008-01-27,size(vsmall)) ///
    export("mypgmA.png, replace width(1000)")

I want another graph with different colors exported to a different file. I
do not need to specify the other options. Instead I can use:

  pvplot3 , ///
    colors(pink blue orange green) ///
    export("mypgmB.png, replace width(1000)")

The -pvplot- program uses all prior options that have not been explicitly
changes.

Interactive model can be canceled with the intoff option. For example,

  pvplot3 , intoff ///
    colors(pink blue orange green) ///
    export("mypgmC.png, replace width(1000)")

Since interactive mode is off, the title and captions defined earlier are
not used in this graph.

The global that controls interactive mode is called pvinteractive and equal
1 if interative mode is in effect, else 0.

.-
Author: Scott Long
.-
