MapChartTableDataModel: Basic Charts

The main responsibility of a MapChartTableDataModel is to determine which data variables are used in the map chart and what role each variable plays. A MapChartTableDataModel's primary roles are

IdentificationVariable

Specifies a classification variable whose values are used to match with map shape (spatial) data provided. A unique map region is produced for each unique classification value or combination of values when other variable roles are specified. Because a map chart should organize the identification variable's data values into single region entities, the IdentificationVariable role uses a ClassificationVariable, which is designed to manage and sort categorical values.

ColorVariable

Specifies an analysis variable whose values determine the color of each map region. The role uses a Variable or VariableList, which may be AnalysisVariables, if you desire a statistical computation with a variable instance, or a simple type if your would like to color by a String value.

The following code fragment graphs energy production by assigning the Identification and Color variable roles to variables named State and EnergyProduced:

// Create a data source that contains the map shape data and 
// assign it to a SpatialDataModel.
   Javax.swing.table.TableModel dataTable = <...>;
   SpatialDataModel sdm = new SpatialDataModel( dataTable );

// Create a data source that must contain a column
// named State and a numeric column named EnergyProduced
   dataTable = <...>;
   

// Create a data model and attach the data source to it
   MapChartTableDataModel dataModel =
     new MapChartTableDataModel( dataTable, sdm );
     
// Assign the Identification and Color variable roles
// to appropriate variable(s)
   dataModel.setIdentificationVariable(
     new ClassificationVariable("State"));
   dataModel.setColorVariable(new AnalysisVariable("EnergyProduced"));

// Create a MapChart and attach the data model to it
   MapChart mapChart = new MapChart();
   mapChart.setDataModel(dataModel);

MapChartTableDataModel: Data Summarization and Statistic Calculation

When a data model is assigned to a MapChart, the chart summarizes the data before displaying it. During summarization

• Analysis values are grouped into bins that are arranged by the classification values. For example, if the classification values represent sales territories, each bin represents one of the territories, and there is a bin for each territory.
• The statistic (set by the analysis variable's constructor) is applied to the analysis values in each bin. For example, if the analysis values represent regional sales figures and the statistic is Sum, then the sales figures in each bin are totaled.
• The MapChart displays the results for each bin as a map region whose color represents the computed statistic value. Identification values that do not match any map features are still included in the Categorization calculation and legend output.

The following statistics are the default calculations:

• If a color variable is not specified, a FREQUENCY count is calculated for each identification value.
• If a color variable is specified but no statistic is specified, a SUM is calculated for the color values associated with each identification value.

The AnalysisVariable constructor can be used to specify a statistic to calcuate. The following code fragment specifies a mean:

 
AnalysisVariable response=new AnalysisVariable(
  "Var1"                            // column for Color role
  ,GraphConstants.STATISTIC_MEAN    // statistic to calculate
);
MapChartTableDataModel dataModel=new MapChartTableDataModel();
dataModel.setColorVariable(response);

By default, a MapChart summarizes the data, even if the TableModel's data values have already been summarized. When the values in the data source have already been summarized, you can improve performance by turning off data summarization. Do this by setting the StatisticEnabled boolean to false as follows:

 
MapChartTableDataModel dataModel=new MapChartTableDataModel();
dataModel.setStatisticEnabled(false);

MapChartTableDataModel: Numeric Categorizations

By default, a continuous range is used to visualize the response data for a ColorVariable when the value is numeric. A CategorizationModel may be defined and applied to the AnalysisVariable to handle the various categorization algorithms.

In this example, a CategorizationModel is created to do equal distribution across 5 levels (quintiling):

 
CategorizationModel cm = CategorizationModel.newCategorizationModel(
  GraphConstants.CATEGORIZATION_EQUAL_DISTRIBUTION, 5 );

AnalysisVariable = colorVar = AnalysisVariable(
 "Revenue", null, null, "2006 Revenue", GraphConstants.STATISTIC_SUM, cm, null)};

MapChartTableDataModel dataModel=new MapChartTableDataModel(
  myResponseData, mySpatialData );
dataModel.setColorVariable(colorVar);

Also a format parameter on the ColorVariable's constructor can be used to specify the type of categorization (or midpointing) operation to use.

By default, a discrete categorization is performed when a string data column is specified for the ColorVariable role.

For example, for a numeric data column named Sample, the following code fragment formats the numeric values into categories Initial and Final, and then specifies the numeric variable for the Category role:

 
try { com.sas.text.SASUserDefinedFormat.createFormat(
        "value myFormat 1 - 3 = 'Initial' 4 - 6 = 'Final'");
    } catch (java.text.ParseException e) {
        java.lang.System.out.println("error=" + e.getMessage());
      }
AnalysisVariable myFormattedVar= AnalysisVariable(
 "Revenue", "myFormat", null, "Actual Revenue", GraphConstants.STATISTIC_SUM, null, null)};

MapChartTableDataModel dataModel=new MapChartTableDataModel(
  myResponseData, mySpatialData );
dataModel.setColorVariable(myFormattedVar);

MapChartTableDataModel: Multiple Response Variables

Multiple Color variables can be plotted against the same Identification variable by adding the variables to a VariableList, and then assigning that list rather than an individual variable to the Color role.

The following code fragment assigns the Color role to variables named Produced and Consumed:

 
AnalysisVariableList multiResponse=new AnalysisVariableList(
  new AnalysisVariable[] {
      new AnalysisVariable("Produced"),
      new AnalysisVariable("Consumed")
  } );
 
Variable[] varArray = new Variable[] { 
new AnalysisVariable( "produced",  null, null, "Energy Produced",
                       GraphConstants.STATISTIC_SUM, null, null ),
	new AnalysisVariable( "consumed", null, null, "Energy Consumed",
              GraphConstants.STATISTIC_SUM, null, null ) };
mapChartDataModel.setColorVariable( new VariableList( varArray ) );

The specification generates a map chart for each unique classification value. The placement of the maps (side-by-side or top/bottom) is determined by examining the dimensions of the area available versus the dimensions of the generated map extents.

MapChartTableDataModel: Multiple Charts in Columns and/or Rows

Separate MapCharts can be generated for each value of a ClassificationVariable by assigning either the ColumnVariable or RowVariable role to that variable.

For example, when charting energy production, a variable named Year might be assigned to the Column role so that a separate chart is generated for each region. The assignment would resemble the following:

 
dataModel.setColumnVariable(new ClassificationVariable("Region"));

If the Column role is assigned, charts are aligned horizontally by the variable's values. If the Row role is assigned, charts are aligned vertically.

The Column and Row variable roles can both be assigned to the same graph. In that case, a separate map chart is produced for each unique pair of (column, row) values and the plots are displayed in a grid. For example, when charting product sales, a variable named Year might be assigned to the Column role and a variable named Region might be assigned the Row role. In this case, a separate chart is generated for each region's sales in each year.

MapChartTableDataModel: Valid Variable Roles

The following table summarizes the MapChartTableDataModel variable roles and the type of data each role supports.

Variable Role	Class Type	Numeric	String	Multiple Variables
IdentificationVariable* Assigns the variable that identifies and links the responses with the map data	ClassificationVariable	Yes	Yes	No
ColorVariable Assigns the variable that determines the color of map regions. **	Variable (string) or Analysis Variable (numeric)	Yes	Yes	Yes
ColumnVariable Aligns multiple charts in columns	ClassificationVariable	Yes	Yes	Yes
RowVariable Aligns multiple charts in rows	ClassificationVariable	Yes	Yes	Yes
* required variable
** Use setColorVariableArray when using mixed types (Variable & AnalysisVariable)

MapChartTableDataModel: Behavior

To generate a graph, a MapChart needs a data column for the IdentificationVariable role. If the role is not assigned in the program code, a MapChart selects the first column found in the MapChartTableDataModel named "State" or "ID" and uses it as its Identification variable. If no such column exists in the data, no chart is displayed.

This default behavior occurs only when the Identification role is not assigned. If the role is assigned to a variable that does not exist in the data, the MapChart cannot display a graph

If the ColorVariable role is not assigned in the program code, then the color of map regions represent a frequency count of the Identification values. If the ColorVariable role is assigned, then the default statistic for the map region color is the sum of the color values for each identification value.

MapChartTableDataModel: Events

A MapChartTableDataModel fires property change events when

• any of its properties are changed
• any property in a contained model is modified.

For example, if the name property is changed in the ClassificationVariable that has been assigned to the IdentificationVariable role, the MapChartTableDataModel fires a PropertyChangeEvent to indicate that the IdentificationVariable has changed.

MapChartTableDataModel: Error Handling

When variable roles are assigned, the MapChartTableDataModel does not confirm that the variables exist in the TableModel. Thus, assigning a non-existent data column to a variable role may mean that the MapChart cannot display a graph. For example, if the IdentificationVariable role is assigned to a State column but the TableModel does not contain a State column, then the MapChart fails to produce a graph.

If the IdentificationVariable role is correctly assigned to an existing variable but another role is incorrectly assigned, the MapChart displays a graph without the incorrect role. For example, if the IdentificationVariable role is correctly assigned but the ColumnVariable role is not, a graph using the Identification role is generated, but the Column role is ignored.