## MapChart: Minimum Specification

The minimum specification for a MapChart requires a valid data model. A MapChart data model consists of two major data sources: Map data (vertices to draw the map shapes) and response data (values used to dynamically color and draw the map). The map data is defined in the SpatialDataModel, which is contained in the MapChartDataModel.

The spatial (or map) data should assign an Identification variable role to a Variable that will be used to match the map data with the response data. If the role is not assigned, the MapChart automatically assigns it to the first column found in the SpatialDataModel that is named "ID" or "State". Other required variables are X, Y and Segment. If these are not explicitly set on the SpatialDataModel, then they are assigned to variables with the same names.

Generally the data model should assign the Identification variable role to a ClassificationVariable in the model, but if the role is not assigned, the MapChart automatically assigns it to the first column found in the data model that is named "ID" or "State". If the Color variable role is not assigned, the map regions represent the Identification variable's frequency count.

Example
Basic Requirements for Creating a MapChart: Swing-based code, Servlet-based code

## MapChart: Functional Overview

Each value of the Identification variable is displayed as an instance of a map region. A VariableList can be used to specify the Color variable. A separate map is created for each Variable in the VariableList. Basic statistics such as Sum, Mean, and Frequency are supported.

The component will display a 2D map view, which displays the map as a choropleth chart, (a chart that applies color to the regions to indicate value). By default, the color is applied on a continuous scale from minimum to maximum value. To change this behavior, a CategorizationModel should be defined on the ClassificationVariable in the MapChartDataModel. Maps will show spatial trends best when using an equal distribution categorization.

Multiple charts can be arranged in columns (using the ColumnVariable role), rows (using the RowVariable role), or a graph matrix (using both roles). A separate chart is generated for each unique column or row value, or for each value pair when both a column and row variable are specified. You can control the arrangement and text of the labels and values that identify the column and row axes.

## MapChart: Data Access

A map chart's data properties are defined in a data model that descends from MapChartDataModel, an abstract class whose subclasses provide a handle to the data and determine the number and arrangement of data elements (map regions). MapChartDataModel has the subclass MapChartTableDataModel, which models relational data from a Swing TableModel and maps the data columns to the graph.

## MapChart: Display Properties

A MapChart's individual display properties can be set by calling the MapChart's getGraphModel() method, which returns a MapChartModel that can be used to set the desired properties. The MapChartModel class contains

- MapChart-specific properties
- Common graph properties
- A collection of models that control the appearance of the graph's peripheral elements, such as its axes and legend.

Although modifying the MapChartModel provides considerable control, it can be tedious to modify properties individually. For example, the colors used to display the map are defined in the graph style, and the MapChartModel can independently control these different colors, but doing so requires you to apply the same properties to all applicable locations.

An easier way to set a MapChart's display properties is to apply a pre-defined GraphStyle to the chart. A graph style sets many of the graph's visual characteristics, such as its use of colors, fonts, background, transparency, drop shadows, and more. A graph style can be used as is or modified through the GraphStyle class.

A graph style can be specified as an argument on a MapChart's constructor. Or, it can be applied to an existing chart by calling the MapChart's applyGraphStyle() method as follows:

    MapChart mapChart = new MapChart();
    mapChart.applyGraphStyle(new GraphStyle(GraphStyle.STYLE_SCIENCE);

Applying a GraphStyle to a graph propagates the GraphStyle's properties onto all applicable graph properties, including those in the graph model.

Rather than use the style as is, you can modify it before applying it. Modifying the style definition is typically easier and more convenient than modifying the graph's individual display properties. For example, the GraphStyle class contains only a single set of value text propertes. After applying the modified style, you can still adjust individual properties through the graph model.

The following code fragment modifies a graph style before applying it to a map chart.

    // Create and modify a graph style
    GraphStyle graphStyle = new GraphStyle(GraphStyle.STYLE_SCIENCE);
       graphStyle.getValueTextStyle().setColor(Color.darkGray);
       graphStyle.getValueTextStyle().setFont(new java.awt.Font("Arial",Font.BOLD,14));

    // Apply the modified graph style to a chart
    MapChart mapChart = new MapChart();
       mapChart.applyGraphStyle(graphStyle);

Whether you set a graph style or individual display properties, the new display settings override any previous settings that were applied to the graph. For example, if a gray background and yellow region outlines have been set on a graph, and then a style is applied to that same graph, the style's background and outline settings replace the previously set gray background and yellow outlines.

## MapChart: Titles and Footnotes

The MapChart component supports four titles and two footnotes, each with its own display attributes. To display multiple lines of text with the same attributes, use the line-end character (\n) in the specified text string.

To assign a title or footnote,

- Create a NoteModel to encapsulate a text value with associated display attributes
- Assign the model to the chart by calling one of the MapChart's setTitle() or setFootnote() methods.

The easiest way to set the text for a title or footnote is to get the chart's title or footnote property and set its text as follows:

    mapChart.getTitle1().setText("Line One\nLine Two");

To change the text attributes for a title or footnote, set the attributes on a NoteModel and assign the NoteModel to the appropriate title or footnote. The following example sets the title "Product Revenue" and displays it in blue, using a 24-point TimesRoman font with a drop shadow.

    NoteModel myTitle = new NoteModel( "Product Revenue" );
    myTitle.getTextStyle().setColor(Color.blue);
    myTitle.getTextStyle().setFont(new java.awt.Font("TimesRoman",Font.PLAIN,24));
    myTitle.getTextStyle().getShadowStyle().setVisible(true);

    // Create the graph and assign the title
    MapChart mapChart = new MapChart();
    mapChart.setTitle1( myTitle );

## MapChart: Usage Examples

The following example fragment graphs product revenue. It uses relational data from a Swing TableModel that contains a string column of State IDs and a numeric column of product Revenues. To enhance the graph's appearance, the example assigns the Magnify GraphStyle to the chart.

    javax.swing.table.TableModel mySalesData = <...>;
    javax.swing.table.TableModel myMapData   = <...>;

    // Create the MapChart's spatial data model.
    // Note that using the constructor without the variable specification
    // results in the SpatialDataModel assigning Identification to "State"
    // X to "X", Y to "Y" and Segment to "segment"
    SpatialDataModel sdm = new SpatialDataModel( myMapData );

    // Create the MapChart's data model.
    MapChartTableDataModel mapChartDataModel = new MapChartTableDataModel( mySalesData, sdm );
    mapChartDataModel.setIdentificationVariable( new ClassificationVariable("State") );
    mapChartDataModel.setColorVariable( new AnalysisVariable("Revenue") );

    // Create the MapChart applying the data model and the
    // "Magnify" GraphStyle
    MapChart mapChart = new MapChart( mapChartDataModel, new GraphStyle(GraphStyle.STYLE_MAGNIFY) );
    mapChart.setTitle1( new NoteModel("Product Revenue") );
    mapChart.setFootnote1( new NoteModel("Company Confidential") );

Assuming the TableModel also contains a column named Year (numeric or string) that identifies the year, and a column named ProductType (numeric or string) that identifies the product type, the following example organizes the graph by year and product type:

    javax.swing.table.TableModel mySalesData = <...>;

    // Create the MapChart's data model.
    MapChartTableDataModel barChartDataModel = new MapChartTableDataModel( mySalesData );
    barChartDataModel.setColumnVariable( new ClassificationVariable("Year") );
    barChartDataModel.setRowVariable( new ClassificationVariable("ProductType") );
    barChartDataModel.setCategoryVariable( new ClassificationVariable("Product") );
    barChartDataModel.setResponseVariable( new AnalysisVariable("Revenue") );

    // Create the MapChart applying the data model and the "Magnify" GraphStyle
    MapChart barChart = new MapChart( barChartDataModel, new GraphStyle(GraphStyle.STYLE_MAGNIFY) );
    barChart.getTitle1().setText("Product Revenue");
    barChart.getTitle2().setText("By Year and Product Type");
    barChart.getFootnote1().setText("Company Confidential");

Assuming the TableModel also contains a column named Year (numeric or string) that identifies the year, and a column named ProductType (numeric or string) that identifies the product type, the following example organizes the graph by year and product type:

    javax.swing.table.TableModel mySalesData = <...>;
    javax.swing.table.TableModel myMapData   = <...>;

    // Create the MapChart's spatial data model.
    // Note that using the constructor without the variable specification
    // results in the SpatialDataModel assigning Identification to "State"
    // X to "X", Y to "Y" and Segment to "segment"
    SpatialDataModel sdm = new SpatialDataModel( myMapData );

    // Create the MapChart's data model.
    MapChartTableDataModel mapChartDataModel = new MapChartTableDataModel( mySalesData, sdm );
    mapChartDataModel.setIdentificationVariable( new ClassificationVariable("State") );
    mapChartDataModel.setColorVariable( new AnalysisVariable("Revenue") );
    mapChartDataModel.setColumnVariable( new ClassificationVariable("Year") );
    mapChartDataModel.setRowVariable( new ClassificationVariable("ProductType") );

    // Create the MapChart applying the data model and the
    // "Magnify" GraphStyle
    MapChart mapChart = new MapChart( mapChartDataModel, new GraphStyle(GraphStyle.STYLE_MAGNIFY) );
    mapChart.setTitle1( new NoteModel("Product Revenue") );
    mapChart.setTitle2( new NoteModel("By Year and Product Type") );
    mapChart.setFootnote1( new NoteModel("Company Confidential") );

Assuming the TableModel also contains a numeric data column named PredictedRevenue for predicted revenue, the following example compares predicted revenue to actual revenue by product organized by year and product type. It also uses an equal distribution algorithm to categorize the response values:

    javax.swing.table.TableModel mySalesData = <...>;
    javax.swing.table.TableModel myMapData   = <...>;

    // Create the MapChart's spatial data model.
    // Note that using the constructor without the variable specification
    // results in the SpatialDataModel assigning Identification to "State"
    // X to "X", Y to "Y" and Segment to "segment"
    SpatialDataModel sdm = new SpatialDataModel( myMapData );

    // Create the MapChart's data model.
    MapChartTableDataModel mapChartDataModel = new MapChartTableDataModel( mySalesData, sdm );
    mapChartDataModel.setIdentificationVariable( new ClassificationVariable("State") );

    // Create an equal distribution categorization for the variables
    CategorizationModel cm = CategorizationModel.newCategorizationModel(
      GraphConstants.CATEGORIZATION_EQUAL_DISTRIBUTION, 0 );

    Variable[] respArray = new Variable[] { new AnalysisVariable(
      "PredictedRevenue",  null, null, "Predicted Revenue",
       GraphConstants.STATISTIC_SUM, cm, null ),

       new AnalysisVariable( "Revenue", null, null, "Actual Revenue",
       GraphConstants.STATISTIC_SUM, cm, null ) };

    mapChartDataModel.setColorVariable( new VariableList( varArray ) );

    mapChartDataModel.setColumnVariable( new ClassificationVariable("Year") );
    mapChartDataModel.setRowVariable( new ClassificationVariable("ProductType") );

    // Create the MapChart applying the data model and the
    // "Magnify" GraphStyle
    MapChart mapChart = new MapChart( mapChartDataModel, new GraphStyle(GraphStyle.STYLE_MAGNIFY) );
    mapChart.setTitle1( new NoteModel("Predicted Revenue vs Actual Revenue") );
    mapChart.setTitle2( new NoteModel("By Year and Product Type") );
    mapChart.setFootnote1( new NoteModel("Company Confidential") );

## MapChart: Behavior

The MapChart asynchronously updates when a PropertyChangeEvent is received from any of its models (DataModel, GraphModel or NoteModels).