pvdata: PathView dataset 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.

SYNTAX

pvdata varlist, [id(varname) AUTOorder(integer) OTHERVars(varnames)
          NOSort DEScending) SORTVars(varlist) Method(uniform|stacked)
          SAMPLE(0 to 100) test oldsort]

OPTIONS

id(varname)         Name of id variable in source dataset.

AUTOorder(#)        Arrange items to be plotted from left to right in the
                        order that corresponds to percent in this category.

NOSort              Do not sort items from first item to last item.

DEScending)         Sort in descending order.

SORTVars(varlist)   Sort on these variables; if not specified, sort using
                        varlist.

Method(stacked|uniform)     If stacked (default), create offsets to stack
                        the paths on top of each other; if uniform, make
                        offsets such that paths from categories with the
                        same value for a given id will be horizontal.

OTHERVars(varnames) Other variables to keep in dataset.

SAMPLE(0-100)       Sample this percent of cases; used with testing or
                        large datasets.

TEST                Run in test mode for debugging.

DISCUSSION

The dataset read by -pvdata- includes categorical variables to be plotted
with -pvplot-. Variables to be plotted are called "items". Each item must
have categorical values, referrred to as categories. Categories must be
sequential with all categories having at least one observation. For example
if the minimum category is 1 and the maximum is 5, at least one item must
include cases for each category 1, 2, 3, 4, and 5.

You must specify the K item variables and can optionally specify an id
variable, variables used to sort the data, and other variables. The dataset
created by -pvdata- has K-1 rows for each observation in the source
dataset. For a given observation, each row has information on a line segment
from item k to k-1. For example, with four items, the first row for
an observation will define the line segment from item 1 to item 2; the
second from item 2 to item 3; the third from item 3 to item 4.

The output dataset will include item, id, sort, and other variables, with
each item duplicated in each row of the dataset. For example, suppose the
source data has an id and three items with three categories. For id=1:

1  1  3  2

the -pvdata- dataset will include this information K-1 times:

1  1  3  2
1  1  3  2
1  1  3  2

This data is not necessary for plotting, but could be used for supplementary
analyses.

The -pvplot- command plots line segments corresponding to the
coordinate (itemST,catST) to the coordinate (itemEN,catEN), These coordinates
are located in these variables:

itemSTx         The x-coordinate for the starting point.

catSTy          The base y-coordinate for the starting point.

itemENx         The x-coordinate for the ending point.

catENy          The base y-coordinate for the ending point.

The base y-coordinates are offset by the amounts contained in:

catSTyoff        Offset for starting y-coordinate.

catENyoff        Offset for ending y-coordinate.

The variables created by -pvdata- for plotting are:

_pvrownum:      This PV id number is 1 for the first observation from the
                sorted source data, 2 for the second, and so on.

_pvsortorder    This indicates the order of the data in the -pvdata- dataset,
                ranging from 1 to (K-1)*N. This variable can be used if you
                sort the dataset created by -pvdata- and want to restore the
                data to the original order. This is not likely to be used
                often.

In addition to variables, -pvdata- sets the value of a global:

pvmod           0 if new data; existing pv globals are reset
                1 if existing pv graph is being modified using other globals

.-
Author: Scott Long
.-
