Working with data maps in the MapPoint object model

Article
11/16/2006

Most data sets are used to create data maps. Data maps are visualizations of the data on the map. In other words, this is the way that the data is seen on the map.

Creating data maps

Creating a data map is relatively easy, as long as you know what you want to create. If you start with a map in the MapPoint user interface, it is easy to recreate it using the MapPoint object model. Almost all of the work is done with the DisplayDataMap method on the DataSet object. (The main exception to this is the title of the data map, which you can set after you create the data map by using the LegendTitle property of the DataMap object.)

Note If you want to display the actual MapPoint user interface for creating data maps, you can use the ShowDataMappingWizard method on the DataSets collection.

The DisplayDataMap method has many parameters that work together in intricate ways, so the following sections give you examples of how to create different kinds of maps, especially ones that are more complicated. To see the individual parameters explained in more detail, see the DisplayDataMap method reference topic. For many maps that you create, you will probably set most of the parameters to the default values, but the following examples will help when you want to override the default settings. You will notice that even in these examples, many values are either set to their defaults or just ignored.

Shaded Area maps

Each of the following examples of calling the DisplayDataMap method shows a different way to set up custom ranges for Shaded Area maps.

Continuous custom ranges

In this example, a set of continuous custom ranges is defined and given custom names in the legend.

  	Sub CreateContinuousShadedAreaDataMap()
	    Dim objDataSet As MapPoint.DataSet
	    Dim objDataMap As MapPoint.DataMap
	    Dim objField As MapPoint.Field
	    Dim lRangeValues(1 To 3) As Variant
	    Dim zRangeNames(1 To 3) As String
	    Dim lColorRange As Long

	    lRangeValues(1) = 0
	    lRangeValues(3) = 40000000
	    zRangeNames(1) = "Low"
	    zRangeNames(2) = "Medium"
	    zRangeNames(3) = "High"
	    lColorRange = 15 'full spectrum
	    Set objDataSet = objApp.ActiveMap.DataSets.GetDemographics
	    Set objField = objDataSet.Fields("Population (2000)")
	    Set objDataMap = objDataSet.DisplayDataMap( _
    	            geoDataMapTypeShadedArea, _
	                objField, geoShowByRegion1, geoCombineByDefault, _
	                geoRangeTypeContinuous, geoRangeOrderDefault, _
	                lColorRange, , lRangeValues, zRangeNames)
	    objDataMap.LegendTitle = "States shaded by population"
	End Sub

Notice that the Legend Title is set after the data map has been created through the LegendTitle property of the DataMap object.

Continuous ranges assign a color based on where the data falls in the overall range. Because of this, continuous ranges require only that the minimum and maximum of the range be set rather than individual range minimums and maximums. However, the custom range values are required to have three values in the range. This mimics the user interface, as you can see in the following illustration that shows data ranges created in the Data Mapping Wizard:

Continuous data range

The middle range is simply informational, which is why you do not need to set its value in your code (the lRangeValues array). The continuous setting still uses three names, and you will notice that the zRangeNames array is filled with three names.

Continuous logarithmic ranges

Continuous logarithmic ranges are identical in setup to the regular continuous ranges. The difference is that instead of setting the color based on a linear distance between the minimum and maximum (as in a continuous range), the color is based on a logarithmic distance between minimum and maximum, thus providing more contrast in the higher and lower ranges (if your data tends to bunch at ends of the full range, continuous logarithmic ranges can show distinctions better). The sample code above would work with geoRangeTypeContinuousLog and with geoRangeTypeContinuous.

Discrete ranges

If you want to divide your data into "groups" (sets of data whose values fall into specific categories) and set each group to a different color, use discrete ranges. MapPoint provides three settings for discrete ranges that give you different default ranges:

Discrete Equal Ranges Your data is divided into even ranges between the maximum value and the highest value. For example, if you have data with values from 1 to 1,000 and you create three discrete equal ranges, you will have ranges from 1 to 333, 334 to 666, and 667 to 1,000.

Equal Data Points (or quantiles) Your data is divided into ranges such that each range contains the same number of records. For example, if you have nine records of data with values from 0 to 1,000, the ranges could be 0 to 5, 6 to 970, and 971 to 1,000, if that divided the data into three records per range.

Discrete Logarithmic Ranges This divides your data into ranges where the values of each range advances logarithmically from the previous range. For example, if your data ranged from 1 to 1,000, the ranges would be 1 to 10, 11 to 100, and 101 to 1,000.

For all three of these types of discrete ranges, you can have between 1 and 8 ranges, or "groups," for your data (although with discrete logarithmic ranges, the decision is made for you). If you want to create your own custom ranges, as in the following example, you can use any of the preceding choices for data range type, but your results will be the same because these all customize in the same way.

  	Sub CreateDiscreteRangesShadedAreaDataMap()
	    Dim objDataSet As MapPoint.DataSet
	    Dim objDataMap As MapPoint.DataMap
	    Dim objField As MapPoint.Field
	    Dim lRangeValues(1 To 5) As Variant
	    Dim zRangeNames(1 To 4) As String
	    Dim lColorRange As Long

	    lRangeValues(1) = 0
	    lRangeValues(2) = 10000000
	    lRangeValues(3) = 20000000
	    lRangeValues(4) = 30000000
	    lRangeValues(5) = 40000000
		zRangeNames(1) = "Low (< 10 million)"
	    zRangeNames(2) = "Medium (10 to 20 million)"
	    zRangeNames(3) = "High (20 to 30 million)"
	    zRangeNames(4) = "Really High (over 30 million)"
	    lColorRange = 15 'full spectrum
	    Set objDataSet = objApp.ActiveMap.DataSets.GetDemographics
	    Set objField = objDataSet.Fields("Population (2000)")
	    Set objDataMap = objDataSet.DisplayDataMap( _
	                geoDataMapTypeShadedArea, objField, _
	                geoShowByRegion1, geoCombineByDefault, _
	                geoRangeTypeDiscreteEqualRanges, _
	                geoRangeOrderDefault, _
	                lColorRange, 4, lRangeValues, zRangeNames)
	    objDataMap.LegendTitle = "States shaded by population"
	End Sub

The differences from the continuous range example are bolded in the previous example. In this case, there are four ranges (although, again, you can specify any number from 1 to 8). The Range Names again reflect that exactly, and the zRangeNames array has four names in it. However, the ranges themselves are created with five values. This is always the number of ranges plus 1. This is because there is one low value for each range (which is used as the high value for the previous range) and one high value for the last range (which has no following low value to use). The following illustration shows how this works in the Data Mapping Wizard, using three ranges as an example:

Named ranges

Range values in the object model always go from lowest to highest, although you can make them display in the opposite order in the legend and map by changing the DisplayDataMap method DataRangeOrder parameter. If you change the order, the values will change but the colors will not, so this changes the colors that are used for the different ranges.

Unique values

The last data range type to look at for Shaded Area maps is unique values. Use this type of data range to create "groups" of data, where all the records have exactly the same value (in other words, they are not really ranges, but simply values). The following example assumes that you already have data created in the map that is the only data set and that it has a field that is called "Sales," which has values of "Bad," "Fair," and "Good."

  	Sub CreateUniqueValuesShadedAreaDataMap()
	    Dim objDataSet As MapPoint.DataSet
	    Dim objDataMap As MapPoint.DataMap
	    Dim objField As MapPoint.Field
	    Dim lRangeValues(1 To 3) As Variant
	    Dim zRangeNames(1 To 3) As String
	    Dim lColorRange As Long

	    lRangeValues(1) = "Bad"
	    lRangeValues(2) = "Fair"
	    lRangeValues(3) = "Good"
	    zRangeNames(1) = "No Sales"
	    zRangeNames(2) = "Some Sales"
	    zRangeNames(3) = "Great Sales"
	    lColorRange = 13 'red white blue
	    Set objDataSet = objApp.ActiveMap.DataSets(1)
	    Set objField = objDataSet.Fields("Sales")
	    Set objDataMap = objDataSet.DisplayDataMap(geoDataMapTypeShadedArea, _
	                objField, geoShowByDefault, geoCombineByDefault, _
	                geoRangeTypeUniqueValues, geoRangeOrderDefault, _
	                lColorRange, 3, lRangeValues, zRangeNames)
	    objDataMap.LegendTitle = "Sales"
	End Sub

Notice that in this case the number of ranges, range names, and range values are all identical (3). This makes sense when you look at the Data Mapping Wizard in the MapPoint user interface:

Unique values

There is one data value and one name for each range.

Shaded Circle maps

The way that you call the DisplayDataMap method for Shaded Circle maps is identical to Shaded Area maps, with the exception of the map type.

Here is an example of creating a Shaded Circle Map:

  	Sub CreateShadedCircleDataMap()
	    Dim objDataSet As MapPoint.DataSet
	    Dim objDataMap As MapPoint.DataMap
	    Dim objField As MapPoint.Field
	    Dim lColorRange As Long
	
	    lColorRange = 1 'White to Purple
	    Set objDataSet = objApp.ActiveMap.DataSets.GetDemographics
	    Set objField = objDataSet.Fields("Population (2000)")
	    Set objDataMap = objDataSet.DisplayDataMap( _
	                geoDataMapTypeShadedCircle, objField, _
	                geoShowByCensus2, geoCombineByDefault, _
	                geoRangeTypeContinuous, _
	                geoRangeOrderDefault, lColorRange)
	    objDataMap.LegendTitle = "Metropolitan Areas by population"
	End Sub

Sized Circle maps

Sized Circle maps are almost identical to Shaded Area maps. In this case, the exceptions are the map type and the color scheme.

  	Sub CreateShadedCircleDataMap()
	    Dim objDataSet As MapPoint.DataSet
	    Dim objDataMap As MapPoint.DataMap
	    Dim objField As MapPoint.Field
	    Dim lColor As Long

	    lColor = 1 'Purple
	    Set objDataSet = objApp.ActiveMap.DataSets.GetDemographics
	    Set objField = objDataSet.Fields("Population (2000)")
	    Set objDataMap = objDataSet.DisplayDataMap( _
	                geoDataMapTypeSizedCircle, objField, _
	                geoShowByCensus2, geoCombineByDefault, _
	                geoRangeTypeContinuous, _
	                geoRangeOrderDefault, lColor)
	    objDataMap.LegendTitle = "Metropolitan Areas by population"
	End Sub

The color now represents a single color rather than a range (see the ColorScheme property reference topic for more information).

Multiple Symbol maps

Multiple Symbol maps do not have continuous ranges because the symbols that represent them are not continuous. However, all of the other range types are still available and work the same way as they do for Shaded Area maps.

  	Sub CreateDiscreteRangesMultipleSymbolsDataMap()
	    Dim objDataSet As MapPoint.DataSet
	    Dim objDataMap As MapPoint.DataMap
	    Dim objField As MapPoint.Field
	    Dim lRangeValues(1 To 5) As Variant
	    Dim zRangeNames(1 To 4) As String
	    Dim lSymbols(1 To 8) As Variant

	    lRangeValues(1) = 0
	    lRangeValues(2) = 10000000
	    lRangeValues(3) = 20000000
	    lRangeValues(4) = 30000000
	    lRangeValues(5) = 40000000
	    zRangeNames(1) = "Low (< 10 million)"
	    zRangeNames(2) = "Medium (10 to 20 million)"
	    zRangeNames(3) = "High (20 to 30 million)"
	    zRangeNames(4) = "Really High (over 30 million)"
	    lSymbols(1) = 121 'down arrow
	    lSymbols(2) = 123 'right arrow
	    lSymbols(3) = 128 'up to right arrow
	    lSymbols(4) = 254 'exclamation
	    Set objDataSet = objApp.ActiveMap.DataSets.GetDemographics
	    Set objField = objDataSet.Fields("Population (2000)")
	    Set objDataMap = objDataSet.DisplayDataMap( _
	                geoDataMapTypeMultipleSymbol, objField, _
	                geoShowByRegion1, geoCombineByDefault, _
	                geoRangeTypeDiscreteEqualRanges, _
	                geoRangeOrderDefault, , _
	                4, lRangeValues, _
	                zRangeNames, , , lSymbols)
	    objDataMap.LegendTitle = "States multiple symbol map"
	End Sub

As you can see, with Multiple Symbol maps, you can specify the symbol for each range of data, and you do not specify a color. Otherwise, this works in the same way as Shaded Area maps do.

Pie Chart maps

Pie Chart maps have no ranges, no colors, and no range labels. You must specify multiple fields to display, and you can create custom names for those fields. The following code creates a Pie Chart Map from state population:

  	Sub CreatePieChartsDataMap()
	    Dim objDataSet As MapPoint.DataSet
	    Dim objDataMap As MapPoint.DataMap
	    Dim objFields(1 To 3) As MapPoint.Field
	    Dim zFieldNames(1 To 3) As String

	    Set objDataSet = objApp.ActiveMap.DataSets.GetDemographics
	    Set objFields(1) = objDataSet.Fields( _
	                "Population, Ages 0-14 (2000)")
	    Set objFields(2) = objDataSet.Fields(_
	                "Population, Ages 15-24 (2000)")
	    Set objFields(3) = objDataSet.Fields(_
	                "Population, Ages 25-44 (2000)")
	
	    zFieldNames(1) = "Ages 0-14"
	    zFieldNames(2) = "Ages 15-24"
	    zFieldNames(3) = "Ages 25-44"

	    Set objDataMap = objDataSet.DisplayDataMap( _
	                geoDataMapTypeUnsizedPie, objFields, _
	                geoShowByRegion1, geoCombineByDefault, , _
	                geoRangeOrderDefault, , , , , , zFieldNames)

	    objDataMap.LegendTitle = "State populations by age (2000)"
	End Sub

Sized Pie Chart maps

Sized Pie Chart maps use ranges like Shaded Area maps to set the size of the charts. Unlike Shaded Area maps, you can't specify a color ramp (because the ranges denote sizes, not colors). Like regular Pie Chart maps, you can also specify the field names.

Column Chart maps

Column Chart maps are much like Pie Chart maps in that you can specify a set of field names, but you can also use one of the continuous range types (continuous or continuous logarithmic) to specify the way that the data values for each record match to the height of the column. Here is an example of creating a custom continuous range for Column Chart maps:

  	Sub CreateColumnChartsDataMap()
	    Dim objDataSet As MapPoint.DataSet
	    Dim objDataMap As MapPoint.DataMap
	    Dim objFields(1 To 3) As MapPoint.Field
	    Dim zFieldNames(1 To 3) As String
	    Dim lRangeValues(1 To 5) As Variant
	    Dim zRangeNames(1 To 5) As String

	    lRangeValues(1) = 0
	    lRangeValues(5) = 12000000
	    zRangeNames(1) = "Low"
	    zRangeNames(2) = "MediumLow"
	    zRangeNames(3) = "Medium"
	    zRangeNames(4) = "MediumHigh"
	    zRangeNames(5) = "High"

	    Set objDataSet = objApp.ActiveMap.DataSets.GetDemographics
	    Set objFields(1) = objDataSet.Fields( _
	                "Population, Ages 0-14 (2000)")
	    Set objFields(2) = objDataSet.Fields( _
	                "Population, Ages 15-24 (2000)")
	    Set objFields(3) = objDataSet.Fields( _
	                "Population, Ages 25-44 (2000)")
	
	    zFieldNames(1) = "Ages 0-14"
	    zFieldNames(2) = "Ages 15-24"
	    zFieldNames(3) = "Ages 25-44"

	    Set objDataMap = objDataSet.DisplayDataMap( _
	                geoDataMapTypeCategoricalColumn, objFields, _
	                geoShowByRegion1, geoCombineByDefault, _
	                geoRangeTypeContinuous, _
	                geoRangeOrderDefault, , , , _
	                zRangeNames, , zFieldNames)
	
	    objDataMap.LegendTitle = "State populations by age (2000)"
	End Sub

One thing to notice about this is that even though you have created continuous ranges before by using three range values and three range names, in the case of Column Chart maps you use five, as in the user interface with the Data Mapping Wizard (see below). As in the previous examples, although the range values array has five values, you fill in only the first and last values.

Continous range data for Column Chart Map

Series Column Chart maps

Series Column Chart maps are identical to standard Column Chart maps with the exception that the data field labels (zFieldNames in the previous example) have only one value. This is because the label references a series of fields (as in "Population 1980 to 2000").

Clearing data maps without removing data

If you have imported data and show it as a data map, you may want to revert it back to the non-data mapped style without removing the entire data set. This is called a Pushpin Map. This is done with the DisplayPushpinMap method on a DataSet object.

Inspecting data maps

Now that you have seen how to create data maps, you can learn how to get information about existing data maps.

When you create a data map using the DisplayDataMap method you are returned a DataMap object that you can use to find out information about the data map. You can also access an existing DataMap object from the DataSet object (using the DataMap property of the DataSet object), but you should first make sure that it exists from the DataMapType property of the DataSet object. If that property returns geoDataMapTypeNone or geoDataMapTypePushpin, then there will not be a DataMap object associated with the DataSet.

The DataMap object

The DataMap object provides much of the information about the data map. It includes the field or fields that were used to create the data map, information about the ranges, and the other options in the data map. All of the information in the DataMap object (with the exception of the LegendTitle parameter that has been discussed previously) is read-only.

One way of looking at this is to see how the properties of the DataMap object relate to the DisplayDataMap method parameters that you have just learned about. Here is the syntax of the DisplayDataMap method:

DataSet.DisplayDataMap([DataMapType], [DataField], [ShowDataBy], [CombineDataBy], [DataRangeType], [DataRangeOrder], [ColorScheme], [DataRangeCount], [ArrayOfCustomValues], [ArrayOfCustomNames], [DivideByField], [ArrayOfDataFieldLabels], [ArrayOfPushpinSymbols])

The results of the DataMapType parameter can be found by the DataMapType property of the DataSet object. Because the DataSet object is the parent of the DataMap object, you can find it by using this code:

DataMap.Parent.DataMapType

The results of the DataField parameter can be found by the DataFields property of the DataMap object. This property returns an array of Field objects, just as the parameter takes an array.

If the legend was modified by the ArrayOfDataFieldLabels parameter, the Field objects returned by the DataFields property of the DataMap object will have the new names.

The result of the ShowDataBy, CombineDataBy, and DivideByField parameters are stored in the ShowDataBy, CombineDataBy, and DivideByField properties of the DataMap object.

The DataRangeType parameter becomes a part of the DataRanges collection. So the following code will return that:

DataMap.DataRanges.DataRangeType

Similarly, the DataRangeOrder, ColorScheme, and DataRangeCount parameters become the DataRanges collection properties DataRangeOrder, ColorScheme, and Count, respectively.

If the ranges were customized with the ArrayOfCustomValues and ArrayOfCustomNames parameters, then the IsCustomized property of the DataRanges collection will return True. In either case, the customized or noncustomized names and values are returned by the Name, HighValue, and LowValue properties of the individual DataRange objects. In some cases, the HighValue property will not be set (where there is only one value for a range, as in a unique value range).

The symbols established by the ArrayOfPushpinSymbols parameter are returned by the individual Symbol properties of the DataRange object.

There are also some useful properties that are not derived directly from the parameters. For example, the ValueCount property of the DataRange object returns the total number of values (records for single field maps, values in records for multiple field maps) that fall within the specified data range.

One interesting use for the information that you can get from a data map is to find out what the settings for which you used the defaults are. For example, if you create a Shaded Area Map by state, you can find the data ranges that were automatically generated, which will give you, at least, bounding information about the data that was matched. In fact, a common scenario creates a data map, inspects its properties, and then customizes it immediately by again calling the DisplayDataMap method.