*! version 25Oct2010
help pvplot

Title

pvplot -- Create a PathView plot (2010-10-25)

Syntax

pvplot
[,
options]

Path colors and intensitiesd determine by color variable

colvar(colvar) Colors vary by categories values
of this variable.

colors(colors) Specify colors used by colvar.
Default colors are red blue green magenta aqua gold orange purple mint.
Shortcuts for specifying colors are: 2cat for red blue;
3cat for red blue green; 4cat for red blue green gold;
5cat for red blue green gold purple; bw for use of
gray scale values (i.e., black and white graph).

colintensity(values) Intensities used by each color. By
default these are all 1.0. To vary intensity, specify values from 0.0
to 1.0 with a value for each color specified with colors().
This allows you to use colors that are not full intensity.

colrange(min max) Minimuim and maximum values of colvar.
This is only needed if colvar has gaps. TO DO: clarify this option.

Intensity determined by intensity variable

intvar(intvar) Intensity varies by categories of
this variable which does not need to be the color variable. This allows
you to vary colors based on one variable and vary intensities based on
another variables. This can be same variable as colvar. If both
intvar() and colintensity() are specified, the intensity of a
path is the product of the intensity determined by the color variable and
the intensity variable.

intensity(values) Intensities from 0 to 1
corresponding to categories of the intensity variable.

intrange(min max) Minimuim and maximum values of intvar.
This is only needed if intvar has gaps.
TO DO: clarify this option.

Selecting paths to be hidden

hideif(if-condition) Select paths to be shown with the
color specified with hidecolor() and the intensity from
{bf:hideintensity(value)). Paths not selected as hidden are selected
to be shown using the normal coloring.

showif(if-condition) Select paths that are not hidden;
that is, these paths are shown with normal coloring.

hidecolor(color) Color used for hidden paths;
use white to not show paths. The default color is gray (gs13).

hideintensity(value) Intensity of hidden paths.
The default is 1.

Width and offest of paths

pathwidth(#) Line width of paths; the default is .01.

delta(#) Size of offset between lines. The default is computed
automatically by the program. To determine the optimal path, you may need
to experiment with a variety of values for delta.

Grids and borders

gridcolor(color) Color of grid lines. Default is black.

gridxwidth(#) Width of x-grid line; .3 is default.

gridywidth(#) Width of y-grid line; .2 is default.

gridspace(#) Space from grid to paths as integer; default 2.

border Add shading around graph. TO DO: verify this command.

Labeling the graph

angle Write labels on an angle.

caption(text) Add a caption using standard Stata options.
For example, caption(Source: mypgm.do 2010-02-10,size(tiny)).

title(text) Title using standard Stata options.

subtitle(text) Subtitle using standard Stata options.

note(text) Note using standard Stata options.

ylaboffset(#) Add offet to y-label; default is .25.

labelsize(string) Size of axes labels: tiny vsmall small medsmall
medium medlarge large or vlarge; default is vsmall.

Options related to interactive mode

reset By default the current graph uses the options from
the last graph in the current session.
The reset options returns all options to their defaults.
This is referred to as turning off interactive mode.
To remove a single option, you can drop it
(e.g., pvdata, hidecolor(drop)).

quietly Do not show graph, only change options to be used
for next graph that is createed.

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.

Other options

aspectratio(#) Aspect ratio of graph; default is 1.

options(string) These options are sent to Stata's
graph command.

export(string) Name of export file. For example,
export(mygraph.png, replace width(1400)).

sample(0-100) Randomly select this percent of cases.

Description

pvplot creates a parallel coordinates for categorical variables.
The usual parallel coordinates graph will use exactly the same line (i.e.,
path) for any cases that have the save values of the variables being
plotted. When the variables are interval this is not a problem. But, with
categorical variables you are likely to have many cases that are shown
by exactly the same path. To deal with this problem, pvplot adds a
small offset to paths so that each case is shown by a distinct path.
To use pvplot you begin by creating a dataset with pvdata.
This dataset creates one case for each line segment that is plotted by
pvplot. You can select which cases to plot using pvsel.

How colors are determined

Colors are controlled by: (1) the hue and (2) the intensity.
The hue is indicated by names such as red (see colorstyle). The
intensity is a number from 0.0 to 1.0 for lighter to darker colors.
You can control hue and intensity with the options:

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

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

colintensity() specifies the intensity for each color.

For example, for colors based on item sdneighb:

pvplot , ///
colvar(sdneighb) colors(red blue orange green)

Or, you can vary the intensity so that categories 1 and 2 of sdneighb
are shown as light colors (intensity .2) while values 3 and 4 are shown
with intensity 1.

pvplot , ///
colvar(sdneighb) colors(red blue orange green) ///
colintensity(.2 .2 1 1)

Intensity can also by determined by the value of a variable that is not the
same as teh color variable. For example, here
colors are controled by item sdneighb and intensity by the item dsmarry:

pvplot , ///
colvar(sdneighb) colors(red blue orange green) ///
intvar(sdmarry) intensity(.25 .5 .75 1)

You can also control the color by a variable that is not one of the items
being graphed:

pvplot , ///
colvar(nokids) colors(orange green)

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

pvplot , ///
colvar(sdneighb) colors(red blue orange green) ///
intvar(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.

Intensities are specified with decimal digits from 0.0 to 1.0 Or, you
can use the text string hi for 1, medhi for .8, med for .6,
medlo for .4, lo for .2. or vlo for .1.

Showing and hiding paths

You can select paths the will be represented as hidden lines; alternatively,
if you specify lines that are shown, all paths not specified as shown will
be hidden. A path that is "hidden" is simply drawn using a color and
an intensity that you specify with hidecolor() and
hideintensity(). You can make hidden paths invisible by selecting a
color that is the same as the background or an intensity that is 0.
Or you can "hide" paths by making them a color that highlights these paths.
For example, you could have all paths for men shown as pink).

Thus, colors and intensities can be control by the color variable, the
intensity variable, and whether a path is selected as hidden.

Interactive mode

Interactive mode makes it simple to modify an existing graph.
After you create a graph with pvplot,
the next graph created by pvplot will by default assume the values of
the options specified by the prior graph. This means that you can easily
change just one option without having to respecify other options. If you
want to change an option that was already set, you can either specify a new
value for that option or drop it (e.g., pvdata, hidecolor(drop)).

By default, pvstata works in interactive mode. If you want to
submit a command that resets all options to their defaults, you add the
default option to your command.

To see how interactive mode works, consider an example.
Suppose you create a graph with the command:

pvplot , ///
colvar(sdneighb) colors(red blue orange green) ///
gridspace(3) aspect(1) ///
export(graph1.png, replace)

Next I want a graph with different colors. Since the current options will be
used in the next graph, I only need to change the color options:

pvplot , ///
colors(pink blue orange green) ///
export(graph2.png, replace)

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

pvplot , default ///
colors(pink blue orange green) ///
export(graph3.png, replace)

The default option resets all options.

Interactive mode is useful both within a do-file so that you do not have
to repeatedly specify options, but is also useful if you want to submit
commands from the command line in Stata. To make this easier, the shorter
names pvs and pvp can be used instead of
pvsel and pvplot.