Follow us on Twitter

Using DisplayDataMap

Share:

Some of the most complex and difficult to use methods in MapPoint’s programming interface (API) are those that import data and plot it. The Using ImportData page described how to import data into MapPoint using C#. This page extends the examples on that page to include data plotting. See the Using ImportData page for the data and the base C# code. All of the C# examples below are code snippets which are inserted into the Using ImportData samples.

Data is plotted using the DisplayDataMap method, which is probably the most complex method in MapPoint’s entire API.  Just to make it harder to use, any incorrect parameters result in the same un-informative “The parameter is incorrect” error. This error does not tell you anything useful, such as which parameter is incorrect or what is actually wrong with it. It is therefore recommended that you start with a working example (e.g. from this article), and adjust it step-by-step until it does what you require. Diagnostics such as the field loop in the ImportData code sample, can also help.

The following code samples can all be inserted in the ImportData code sample where the comment “(data plotting code goes here)” appears.

Before describing all the parameters, let’s start with an example. The following code plots the sales data as Sized Pie Charts:

This is what the resulting map looks like:

Sized Pie Chart map produced from the above sample code

Sized Pie Chart map produced from the above sample code

There are potentially a lot of parameters but in this example we leave most of them as their defaults. Most of the other parameters are enumerations which define how the geographic data is displayed and grouped.

The most complex parameter in this example is the second one, datafields. This lists the data field or fields which will be plotted. Specify a MapPoint Field object (for one data field — e.g. in a shaded area map), or as in this example, an array of MapPoint Field objects to specify multiple data fields. The Field objects are queried using Fields.get_Item. Note that this uses 1-referenced indices.

All of the parameters are technically optional, although it is generally a good idea to explicitly specify many of them.  .NET’s interface to COM requires all ‘missing’ optional parameters to be passed as System.Reflection.Missing.Value. All of the code in these examples use a variable called missing which is set to System.Reflection.Missing.Value.

Many of the parameters are enumerations and the full set of values for these enumerations can be found in the MapPoint documentation.

DisplayDataMap has a lot of parameters, and here they are in order:

 

DataMapType

The first parameter specifies the map type using the GeoDataMapType enumeration. Here is an example using a value of geoDataMapTypeCategoricalColumn:

Categorical Column (multi-bar) Graph Example

Categorical Column (multi-bar) Graph Example

This parameter is optional and defaults to geoDataMapTypeDefault, which tells MapPoint to select the map type (typically a pushpin map).

Values of geoDataMapTypeCategoricalColumn, geoDataMapTypeSeriesColumn, geoDataMapTypeSizedPie, and geoDataMapTypeUnsizedPie are all multi-field plots which require multiple data fields (see the DataField parameter). All of the other map types require only one data field.

The values of geoDataMapTypeNone and geoDataMapTypeTerritory are not valid for use with DisplayDataMap.

 

DataField

DataField is the second parameter, and specifies the data field(s) to plot. This is either a single MapPoint Field object (for the single field map types) or an array of MapPoint Field objects (for multi-field map types).

Data fields are typically numeric. Some map types can also accept string (text) fields to indicate categories. String fields are not valid for the pie chart and column chart map types, i.e. all of the multi-field map types.

The default is for MapPoint to use the first valid data field in the dataset.

 

ShowDataBy

This is a geoShowByDefault enumeration value that specifies the geography level (entity) used to map the data. For example, in the above example, the data has been imported at the “Region 1” (US State) level, so it is plotted at the geoShowByRegion1 level.

Data can be plotted at the same or larger level than it is stored at. For example, data imported and stored by US Zipcode, can be plotted at the US State level. Use the CombineDataBy parameter to specify how this data will be combined (aggregated).

The default is geoShowByDefault which tells MapPoint to choose a default geography level for the dataset.

 

CombineDataBy

This parameter is only used if the ShowDataBy (see above) parameter forces data aggregation. It tells MapPoint how to aggregate (i.e. combine) geographic data. For example, how to combine values for individual US Zipcodes into one value for a US State. Data can be added (geoCombineByAdd), averaged (geoCombineByAverage), or by counting the number of values present (geoCombineByCount).

geoCombineByNone forces no aggregation; and the default (geoCombineByDefault) tells MapPoint to choose its own method of aggregation.

 

DataRangeType

This is a GeoDataRangeType enumeration used to specify how numeric values are plotted – are they grouped together into discrete ranges, or plotted using a continuous range of shades? Should a linear or a logarithmic scale be used? Should they be grouped so that each discrete interval contains the same number of data points?

The full set of values is discussed in the documentation, but some of the more complex examples that require further parameters, are demonstrated below.

The default is a value of geoRangeTypeDefault which tells MapPoint to choose what it thinks is the most appropriate range type. A range type can be set for all map types except for the unsized pie chart (which is always geoRangeTypeNone). Not all range types are appropriate for all map types. e.g. multiple symbol maps cannot use one of the continuous range options.

 

DataRangeOrder

This parameter is a GeoDataRangeOrder enumeration value that specifies the order for the data ranges. Data ranges can be ascending (geoRangeOrderLowToHigh), descending (geoRangeOrderHighToLow), or default (geoRangeOrderDefault).

It is ignored for the column charts and unsized pie charts.

 

ColorScheme

This is an optional long integer value that references a specific color scheme (palette) to use. The default is geoColorSchemeDefault (-1). Valid color schemes range from 0 to 15 and are illustrated in the MapPoint documentation page for the ColorScheme property.

All MapPoint data maps are limited to these preset color schemes.

 

DataRangeCount

This is an optional long integer value that species the number of ranges for the discrete data range types. It must be a value from 1 to 8. It is ignored for continuous data ranges, un-sized pie charts, and column chart maps.

 

ArrayOfCustomValues

This is an optional array of values for each data range. Because these values include the minimum and maximum values to be plotted, the number of array values should be one plus the number of ranges.

The continuous data range types require an array of size 3, but only the first and last values (start and end) are actually used.

Here is an example with four custom ranges with the shaded circle map type:

Shaded Circle Map demonstrating Custom Range Values

Shaded Circle Map demonstrating Custom Range Values

 

ArrayOfCustomNames

This is an array of custom names (labels) to be used for the map legend. These replace the labels or ranges (e.g. “3,000 to 5,000”, “2,000 to 2,999” in the above screenshot). Each label is specified with a string, and there should be one label per range (i.e. 4 in the above example).

 

DivideByField

This is optional parameter specifies the field to divide the values by. MapPoint has the ability to divide the data field(s) specified in the DataField parameter by another data field (i.e. a denominator). The data fields can only be divided by one denominator. Set this parameter to the MapPoint Field object that represents the denominator data field. The default is to use the existing DivideByField. Pass an empty variant to clear this field.

Here is an example, using the above data to plot a map of red sized circles showing “Our Sales” divided by “Competitor A Sales”:

Example map that uses the "divide by" parameter

Example map that uses the “divide by” parameter

 

ArrayOfDataFieldLabels

This parameter is used to pass an array of custom labels for each color / data field on the legend. The array size must be equal to the number of data fields. It is typically used with the categorical column and pie chart map types. The array must be of size 1 for the series column map type.

Here is an example that uses the above sales data with custom data field labels:

Sample map with custom data field labels

Sample map with custom data field labels

 

ArrayOfPushpinSymbols

This is an array that lists the pushpin symbols to be used for multiple symbol maps — it is ignored for the other map types. The array size must be equal to the DataRangeCount parameter. Symbols are referenced using integer indexes — the same indexes that are used to specify the symbols used by Pushpin objects. The valid range of values will vary according to the version of MapPoint and the number of custom symbols that have been loaded.

Here is an example that plots the above sales data using custom symbols to represent ranges of sales data. The symbols are consecutive (pins 218-215: the first eight numeric symbols in MapPoint 2010), so they are allocated using a FOR loop. They are assigned to equal-sized ranges of sales values:

Setting the individual pushpin symbols

Setting the individual pushpin symbols

 

 

Conclusions

As you can see, these methods and all of their parameters do indeed work. The secret (especially with DisplayDataMap) is to build up the method call one step at a time. Take a working example, check it works, and then change each parameter as required, testing after each stage. Although this makes for a slow development process, a step-by-step approach lets you quickly identify which parameter is set incorrectly when you get the non-descript “The parameter is incorrect” error.

Leave a Reply

 

 

 

You can use these HTML tags

<a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code class="" title="" data-url=""> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong> <pre class="" title="" data-url=""> <span class="" title="" data-url="">