DrawPolygonsByGroups

Prototype

void DrawPolygonsByGroups( Plot plot, DataObject dobj, String sXVarName, String sYVarName, Matrix mIDVarNames, String sColorScheme, Matrix mColorParam, boolean bFill )

Parameters

Plot plot
The plot on which the polygons will appear.

DataObject dobj
The DataObject containing the variables that define the polygons.

String sXVarName
The name of the variable in dobj that specifies the X coordinates of the polygon vertices.

String sYVarName
The name of the variable in dobj that specifies the Y coordinates of the polygon vertices.

Matrix mIDVarNames
The names of the variables in dobj that associate X, Y coordinate pairs with a polygon. The groups defined by these variables determine the number of polygons.

String sColorScheme
This string determines how colors are assigned to each polygon. Valid choices are "UNIFORM", "RANDOM", and "CUSTOM".

Matrix mColorParam
The value of the sColorScheme parameter determines how this matrix is interpreted. See Remarks for details on how this parameter is used.

boolean bFill
If bFill is true, the polygons are filled using the current brush characteristics. If bFill is false, the polygons are not filled.

Remarks

This module uses the Plot.DrawPolygons method to draw polygons on a plot. The polygons are drawn in the current coordinate system (see Plot.DrawUseDataCoordinates and Plot.DrawUseNormalizedCoordinates) and are drawn in the current drawing region (see Plot.DrawSetRegion). This module is typically used to display a map underneath spatial data.

The polygons are drawn in colors determined by the sColorScheme and mColorParam parameters.

If sColorScheme is "UNIFORM", the polygons will all have the same color. The matrix mColorParam specifies the polygon color. If mColorParam has one row, the parameter represents a single color (either as a (1 x 3) matrix of RGB values or as a scalar integer color value) and all polygons are drawn in the specified color. If mColorParam has two rows, the polygon interiors are filled with the color specified by the first row and the polygon outlines are drawn in the color specified by the second row. When mColorParam has two rows, the bFill parameter is ignored.

If sColorScheme is "RANDOM", the polygons will be drawn in random colors chosen from a fixed color map. The matrix mColorParam should be a scalar integer that is used as a seed for random number generation.

If sColorScheme is "CUSTOM", the polygons will be drawn in colors according to the ordering of the groups defined by the variables specified in the mIDVarNames parameter. The matrix mColorParam should be an (n x 3) matrix of RGB colors or an (n x 1) vector of integer color values. An internal color map is created by calling the BlendColors module, which blends the mColorParam matrix into k colors where k is the number of groups. Each polygon is then drawn in the color assigned to its group.

See the documentation for ColorCodeObsByGroups for details on how to specify colors.

Example
declare DataObject dobj;
dobj = DataObject.CreateFromFile( "climate" );
colors = { 225 113 0, 0 128 0, 128 64 255 };
run ColorCodeObs( dobj, "TotalAvePrecipIn", colors, 40 );

declare ScatterPlot plot;
plot = ScatterPlot.Create( dobj, "longitude", "latitude" );
plot.SetMarkerSize( 7 );

declare DataObject dobjMap;
dobjMap = DataObject.CreateFromFile( "states48" );
plot.DrawUseDataCoordinates();
plot.DrawSetRegion( PLOTBACKGROUND );
run DrawPolygonsByGroups( plot, dobjMap,
    "Lon", "Lat", {"State" "Segment"},
    "Uniform", 0, false );
See Also

BlendColors
GetSortedMatrixByGroups
Plot.DrawPolygons
Plot.DrawSetRegion
Plot.DrawUseDataCoordinates
Plot.DrawUseNormalizedCoordinates