# micromapST panel description data.frame structure

### Description

The `panelDesc` data.frame provides the `micromapST` function with
the information required to process the `stateFrame` data and panelData data.frames
and to generate the required linked micromap plot.

It specifies which columns in the `stateFrame` data.frame contain the data
for each glyph column, the column types, labels, reference values and text, and when
more complex data is needed by a glyph (boxplot and time series) what the name of the data
structure..

1 2 3 4 5 6 7 8 9 10 11 12 13 | ```
Example
panelDesc = data.frame(
type=c("mapcum","id","dotconf","dotconf"),
lab1=c("","","White Males","White Females"),
lab2=c("","","Rate and 95% CI","Rate and 95% CI"),
lab3=c("","","Deaths per 100,000","Deaths per 100,000"),
col1=c(NA,NA,"Rate",9),
col2=c(NA,NA,4,11),
col3=c(NA,NA,5,12),
refVals=c(NA,NA,NA,wflungUS[,1]),
refTexts=c(NA,NA,NA,"US Rate"),
panelData=c("","","","")
``` |

The `panelDesc` data.frame (which does not have to be named "panelDesc", any name will do)
provides the means of defining how many columns to create, the type of glyph per column,
where the data required by the glyph is located in the `stateFrame` (column number or name)
or the name of a supplimental data structure when the glyph is boxplots or time series
(via the `panelData` list entry), the column titles, and the column's reference value and label
for the link micromap generation.

**Glyph Types**

The `type` vector defines the type of glyph to be used for each column.
The available glyphs are:

- Map types:
"map", "mapcum","maptail","mapmedian"

- State ID and/or Name:
"id"

- Ranking:
"rank"

- Graphical Type:
"dot", "dotse","dotconf", "bar", "arrow", "ts", "tsconf","scatdot", "segbar", "normbar", "ctrbar", "boxplot"

The following provides a description of each panel type:

- map
- US map with active states colored

- mapcum
- US map with active states colored and previously active state highlighted generating an accumulation from top to bottom

- maptail
- US map with active states colored and previously active state highlighted until the median state, then the reverse to the end (states that have not been active are highlighted.)

- mapmedian
- US map with active states colored. Maps above the median state have states with values above the median highlighted. Maps below the median state have states with values below the median highlighted. This helps define the above and below median state groups.

- id
- generates a column with a colored identifier (a square) and the state name or abbreviation.

- rank
- number the states in rank order from 1 to 51, sequentially.

- arrow
- an arrow between two values with a head.

- bar
- a single bar chart.

- boxplot
- a boxplot per state with box, upper and lower whiskers and outliers.

- dot
- a dot for a single value.

- dotse
- a dot for a single value and its standard error.

- dotconf
- a dot for a single value and its confidence interval.

- ts
- a time series line for up to 30 sets "x" and "y" values for each state.

- tsconf
- a time series line for a up to 30 sets of "x", "y" and upper "y" and lower "y" values as a confidence interval band for each state.

- segbar
- a horizontal stacked (segmented) bar plot starting at 0 for 2 to 9 bars.

- normbar
- a stacked bar plot where the data is normalized for each state by dividing the bar segment values by the sum of the values for all of the bars. Up to 9 bars are supported.

- ctrbar
- a stacked bar plot where the bar segments are centered around the 0.Up to 9 bars are supported.

- scatdot
- a set of 51 points with an "x" and "y" value per state.

**Labels (Column Headers and Footers)**

`micromapST` supports up to 3 column labels or titles: `lab1`,
`lab2` and `lab3`, where `lab1` and `lab2` are header titles for the column.
`lab3` is the footer title for the column. All titles are optional.
`lab3` is used to indicate the unit of measure at the bottom of the columns,
but is not limited to this use. For example:

1 2 3 4 |

`lab4` is used only when time series or scatter dot glyphs are used to provide a Y axis
title for the column.
All label/title vectors are optional and only required when an title or label is needed.

**Data References**

Depending on the type of glyphic selected for the column, 1 to 3 data
values for each state may be required: The `col1`, `col2` and
`col3` vectors serve as indexes to columns in the `stateFrame`
data.frame passed in the arguments of the `micromapST` function call.
The values can be either the numeric number of the row in
`stateFrame` data.frame or the column name.
If no index is required, the entry should be set to `NA`.

If the glyph requires one value, then only the `col1` index is
used and the `col2` and `col3` indexes are set to `NA` if present .
If 2 values are required, then `col1` and `col2` indexes are used
and the `col3` index is set to `NA`, if present.
If 3 values are required, then `col1`, `col2`, and `col3` indexes are used.

The `stateFrame` column indexes can be provided as an integer
or the column name. If the integer value is less than 1 or greater than
the number of columns in `stateFrame` or a column name is used that does
not exist in stateFrame, the `micromapST` function will stop and
generate an error message.

Glyph | Meaning | col1 | col2 | col3 | panelData |

Name | |||||

arrow | Arrow | Beginning | Ending Values | NA | NA |

Values | (arrow head) | ||||

bar | Horizontal | Bar end | NA | NA | NA |

bar | values | ||||

(length) | |||||

segbar | Horizontal | Values for | Values for | NA | NA |

stacked | first (left | the last | |||

bar | -most) segment | (right-most) | |||

(length) | bar segment | ||||

(length) | |||||

normbar | Horizontal | Values for | Values for | NA | NA |

stacked | first (left- | last (right- | |||

bar, nor- | most) bar | most,bar | |||

malized to | segment | segment | |||

total 100% | (length) | (length) | |||

ctrbar | Horizontal | Values for | Values for | NA | NA |

stacked | first (left- | last (right- | |||

bar, cen- | most) bar | most,bar | |||

tered on | segment | segment | |||

the middle | (length) | (length) | |||

bar | |||||

boxplot | Horizontal | NA | NA | NA | Name of |

box plot | output | ||||

list from | |||||

call to | |||||

boxplot(...plot=F) | |||||

dot | Dot | Values for | NA | NA | NA |

dots | |||||

dotconf | Dot with | Values | Values of | Values for | NA |

confidence | for dots | lower limits | upper limits tab | ||

interval | |||||

line | |||||

dotse | Dot with | Values for | Standard | NA | NA |

line length | dots | errors | |||

+/- standard | |||||

error | |||||

scatdot | Scater plot | Values on | Values on | NA | NA |

of dots | horizontal | vertical | |||

(x) axis | (y) axis | ||||

ts | Time Series | NA | NA | NA | Name of array |

(line) plot | with dimensions | ||||

of c(51,t,2), | |||||

where t = # | |||||

of time points | |||||

(max 15), x values | |||||

in [,,1], y values | |||||

in [,,2] | |||||

tsconf | Time Series | NA | NA | NA | Name of array |

(line) plot | with dimensions | ||||

with confidence | of c(51,t,4), as ts | ||||

limits | lower limit is | ||||

[,,3] amd the | |||||

upper limit is | |||||

[,,4] | |||||

The `panelData` vector is only used when a glyph requires more data per state than can be
provided by the `stateFrame` columns. Only glyphs using this vector are boxplots and time series.

In the case of the boxplot glyph, the boxplot function with plot=F is used to generate the boxplot statistical details for each state. The name of the resulting list of 51 sets of boxplot statistics (one for each state) is placed in the panelData vector element for the boxplot column.

For the time series and time series with confidence interval, the glyphs require a 3 dimensional
array of data. The first dimension ([`st`,,]) represents the 51 states. The second dimension ([,t,])
ranges from 2 to `n`. There is no upper limit, but 200-250 samples is a practical limit.
One for each data point. The third dimension ([,,`v`]) provides the values at
data point vart for state `st`. [,,var1] is the `x` axis value. For time series, is usually
just the value 1 to `n` to order the `y` values. [,,`2`] is the median `y` value. For time series
with confidence intervals: [,,`3`] is the lower value `y` and [,,`4`] is the upper value `y`.

**Reference Lines**

Reference lines can be created in arror, bar, dot, dotconf, dotse, and segbar glyphs by specifying the
reference values in the `RefVal=` vector. A label appearing at the bottom of the column can be
specified using the `RefTxt=` vector in the `panelDesc` data.frame.

### Usage

1 |

### Format

The parameters in the panelDesc data.frame structure are:

- type=
The types of graphics for each column of panels can be specified by the following keywords in the "type variable":

The following are the type of glyphics that can be specified in the type vector:

- Map types:
"map", "mapcum","maptail","mapmedian",

- State ID and/or Name:
"id",

- Glyph Type:
"dot", "dotse","dotconf", "bar", "arrow", "ts", "tsconf","scatdot", "segbar", "normbar", "ctrbar", "boxplot"

/cr The following provides a description of each panel type:

- map
- a non-highlighted map

- mapcum
- maps show the accumulated states top to bottom

- maptail
- maps show the accumulated states from the top and bottom toward median state.

- mapmedian
- the maps above the median highlight the states above the median state and maps below the median highlight states below the median state based on the sorting variable.

- id
- generates a column with a color identifier (a filled in square) and the state name. The plotNames parameter in the

`micromapST`call controls whether the state's full name or 2 character abbreviation is displayed.- rank
- sequentially number states from 1 (highest rank) to 51 (lowest rank)

- arrow
- an arrow from value 1 to value 2 with value 2 the head of the arrow.

- bar
- a bar for a single set of values, The values can be positive or negative.

- boxplot
- a boxplot for each state using a data.frame generated by the boxplot function with plot=F. The name of the boxplot data.frame is passed to

`micromapST`using the`panelData`vector.

- dot
- a dot for a single value using one set of values.

- dotse
- a dot for a single value and its standard error using two values.

- dotconf
- a dot for a single value and its confidence interval using three values.

- ts
- a time series line plot for each state. The glyph use the

`panelData`vector to get the name of a three (3) dimensional array the data for the plot. The array contains one entry per state, 1 to 30 data points and the`x`and`y`values. See section on`panelData`below for more details. A reasonable upper limit to the number of points is between 200-300.- tsconf
- a time series line and confidence interval band for each state. The glyph use the

`panelData`vector to get the name of a three (3) dimensional array the data for the plot. The array contains one entry per state, 1 to`n`data points and the`x`,`y`,`lower y`and`upper y`values. See section on`panelData`below for more details. A reasonable upper limit to the number of points is between 200-300.

- segbar
- a horizontal stacked (segmented) bar plot starting at 0 using data in the stateFrame data.frame. The

`col1`and`col2`columns are used to indicate the first and last columns in the stateFrame data.frame that contain the contiguous bar segment values (lengths). For example: The data for a 5 segment bar glyph is in columns 4 through 8 in the`stateFrame`(5 columns).`col1`is set to 4 to identify the first column and`col2`is set to 8 to identify the last column in the sequence. Column names may be used, but the column identified in`col1`must preceed the column identified in`col2`.- normbar
- a stacked bar plot where the data is normalized for each state by dividing the bar segment values by the sum of the values for all of the bars. The stacked bar plot for each state then ranges from 0 to 100% (edge to edge). The

`col1`and`col2`columns are used to identify the first and last columns for bar data in the`stateFrame`in the same way as for the "segbar" glyph (see above.)- ctrbar
- a stacked bar plot where the bar segments are centered around the middle of the data. If there is an even number of segments, the 0 point is between the lower half and the upper half of the segments. If there is an odd number of segments, the center is the midpoint of the middle segment. The other segments are plotted to the left and right of the center point. The

`col1`and`col2`columns are used to indicate the first and last columns in the`stateFrame`data.frame that contain the contiguous bar segment values. (See "segbar" type above for more information.)

- scatdot
- a set of 51 points with an

`x`and`y`value per state..All points are plotted in each panel with the key states in the panel highlighted.`col1`indicates`stateFrame`column containing the`x`values and`col2`indicates the column containing the`y`values.

Example:

`type=c("id","map","rank", "boxplot")`

To specify a`micromapST`with three columns, left to right, containing the state label, a map and a boxplot.

`col1=`,`col2=`,`col3=`Vectors of index numbers or names of columns in

`stateFrame`data.frame to be used as data for graphics. The uses of these three vectors are defined below:- any "map" type, id, boxplots, ts, and tsconf
glyphs do not use the

`col1`,`col2`, or`col3`vectors to locate data in the`stateFrame`data.frame. If these vectors are present, the corresponding entires should be`NA`

for the respective columns.

- dot
uses

`col1`to specify a single data column in`stateFrame`data.frame to be ploted.- bar
uses

`col1`to specify the data column in`stateFrame`data.frame for the length of the bar. The data value can be positive or negative.

- dotse
uses

`col1`and`col2`to specify the data columns in`stateFrame`data.frame to be used as the estimate and standard error values, respectively.- arrow
uses

`col1`and`col2`to specify the data columns in stateFrame data.frame for the beginning and end values of the arrow.

- segbar, normbar, ctrbar
uses

`col1`and`col2`to specify the first and last columns in the`stateFrame`data.frame. The`stateFrame`data.frame columns from`col1`to`col2`are used for the length values of each bar in the glyph.`col1`must preceed`col2`in the`stateFrame`data.frame. The minimum number of data columns is 2 columns with a maximum of 9 columns.- scatdot
uses

`col1`and`col2`to specify the`x`and`y`values respectivefully for a dot for each of the 51 states and DC in a scatter dot plot.

- dotconf
uses

`col1`,`col2`, and`col3`to specify the data columns in`stateFrame`data.frame for the estimate value, lower confidence interval, and upper confidence interval values.

See the table above

`lab1=`,`lab2=`-
Character vectors provide the two column labels (titles) lines at the top of each column. If no label is required, use

`""`

for a blank line. `lab3=`Character vector used as a label at the bottom of each column. This is typically used to show units of measure. If no label is required, use

`""`

for a blank line.

`lab4=`Character vector used as the vertical (y) axis label for 'ts', 'tsconf', and 'scatdot' glyphics. If no label is required, use

`""`

for a blank line.

`refVals=`Is a list of object names providing the reference values for each graphic column. The reference value is displayed as a dashed vertical line for each panel in the specified column.

\

`refTexts=`Is a list of 1 or 2 labels to be displayed at the bottom of each column to identify the reference value.

`panelData=`List of object names containing the boxplot data list and/or an array of time series data for each state. If boxplot and time series data are not used in a column, then associated object names should be

`NA`

.For boxplot data, each row name in the boxplot list must be the state abbreviation (2 character) for the state associated with the data. There must be 51 rows in the data.frame. Each row must be data produced by the boxplot function. The state abbreviation must be used as the boxplot$names to be able to associate the individual boxplots to each state. The

`names`attribute must contain the state name.For the time series glyph (ts), the data must be a three (3) dimensional array. The first dimension

`[`

represent one entry for each state (1 to 51). The second dimension`st`,,]`[,`

indexes up to 30 data points for the state. The third dimension`t`,]`[,,`

are the data point values.`v`]`[,,var{1}]`

is the`x`value and`[,,`

is the median`2`]`y`value for the data point. The rownames associated with the first dimension must be the 51 state/DC names to link the elements of this structure the presentation order of the states.For the time series with confidence intervals glyph (tsconf), the array is extended to include:

`[,,`

and`3`]`[,,`

for the`4`]`lower y`and`upper y`values.For time series data, the order of the first dimension of the array must match the state order in the

`stateFrame`. For example, the data in`dataArray[`

is the the state identified in`1`,,]`stateFrame[`

`1`,]

### Details

The `panelDesc` data.frame is used to describe the content of the
micromapST plot to the function. It contains the index of the data
in the `stateFrame`

data.frame, the types of graphics to be used in
each column, titles, column headers, reference values and labels, etc.

### Note

A descriptor may be omitted if none of the panel plots need it.

### Author(s)

Daniel B. Carr, George Mason University, Fairfax VA, with contributions from Jim Pearson and Linda Pickle of StatNet Consulting, LLC, Gaithersburg, MD

### See Also

`micromapST`