Shading by Ranges of Values - MapBasic - 2023

Syntax

Shade [ Window window_id ] 
	{ layer_id | layer_name } 
	With Metadata 
	With expr 
		[ Ignore value_to_ignore ] 
	Ranges 
		[ Apply { Color | Size | All } ] 
		[ Use { Color | Size | All } [ Line... ] [ Brush... ] 
			[ Symbol... ]
		] 
		{ [ From Variable float_array Style Variable style_array ] | 
			 minimum : maximum [ Pen... ] [ Line...] [ Brush... ] 
			[ Symbol... ] [ Hide | Show ]
			[ , minimum : maximum [ Pen... ] [ Line...] [ Brush... ]
			[ Symbol... ] [ Hide | Show ] ... ]
		} 
		[ Style Replace { On | Off } ]
		[ Default [ Pen... ] [ Line... ] [ Brush... ] [ Symbol... ] ] 

window_id is the integer window identifier of a Map window.

layer_id is the layer identifier of a layer in the Map (one or larger).

layer_name is the name of a layer in the Map.

expr is the expression by which the table will be shaded, such as a column name.

value_to_ignore is a value to be ignored; this is usually zero (when using numerical expressions) or a blank string (when using string expressions); no thematic object will be created for a row if the row's value matches the value to be ignored.

float_array is an array of float values initialized by a Create Ranges statement.

style_array is an array of Pen, Brush or Symbol values initialized by a Create Styles statement.

minimum is the minimum numeric value for a range.

maximum is the maximum numeric value for a range.

Description

The optional window_id clause identifies which Map is to be shaded; if no window_id is provided, MapBasic shades the topmost Map window.

The Shade statement must specify which layer to shade thematically, even if the Map window has only one layer. The layer may be identified by number (layer_id), where the topmost map layer has a layer_id value of one, the next layer has a layer_id value of two, etc. Alternately, the Shade statement can identify the map layer by name (for example, "world").

Each Shade statement must specify an expr expression clause. MapInfo Pro evaluates this expression for each object in the table being shaded; following the Shade statement, MapInfo Pro chooses each object's display style based on that record's expr value. The expression typically includes the names of one or more columns from the table being shaded.

If you specify With Metadata, any theme metadata contained in the open table is used to create the Individual or Ranged Value theme.

The keywords following the expr clause dictate which type of shading MapInfo Pro will perform. The Ranges keyword results in a shaded map where each object falls into a range of values.

The Pen clause specifies a line style (for example, MakePen(width, pattern, color)) to use for the borders of filled objects (for example, regions).

The Line clause specifies a line style to use for lines, polylines, and arcs. The syntax of the Line clause is identical to the Pen clause, except for the keyword Line appearing in place of Pen.

The Brush clause specifies a fill style (for example, MakeBrush(pattern, forecolor, backcolor)).

The Symbol clause specifies a symbol style (for example, MakeSymbol(shape, color, size)).

For the specific syntax of a Ranges map, see Syntax Shading by Ranges of Values.

In a Ranges map, you can use the From Variable and Style Variable clauses to read pre-calculated sets of range information from array variables. The array variables must have been initialized using the Create Ranges statement and the Create Styles statement. For an example of using arrays in Shade statements, see Create Ranges statement.

If you specify either the Ranges or Values keyword, the statement can include the optional Default clause. This clause lets you specify the graphic styles used by the "all others" range. If a row does not fall into any of the specified ranges, MapInfo Pro assigns the row to the all-others range. If the Shade statement does not read range settings from array variables, then the Ranges keyword is followed by from one to sixteen explicit range descriptions. Each range description consists of a pair of numeric values (separated by a colon), followed by the graphic styles that MapInfo Pro should use to display objects belonging to that range. If a record's expr value is greater than or equal to the minimum value, and less than the maximum value, then that record belongs to that range. The range descriptions are separated by commas.

Open Table "states"
Map From states
Shade states With Pop_1990 Ranges
	4827000:29280000 Brush (2,0,201326591) ,
	1783000: 4827000 Brush (8,0,16777215) ,
	449000: 1783000 Brush (5,0,16777215)

If you are shading regions, specify Brush clauses to control the region fill styles. If you are shading points, specify Symbol clauses. If you are shading linear objects (lines, polylines, or arcs) specify Line clauses, not Pen clauses; the syntax is identical, except that you substitute the keyword Line instead of the keyword Pen. (In a Shade statement, the Pen clause controls the style for the borders of filled objects, such as regions.)

Specifying the Hide keyword hides the ranged thematic from the Map window. Alternatively, if the Show keyword is specified, the range would be visible in the Map window. It is optional to specify these keywords, and MapInfo Pro defaults to shows the ranged thematic, if the Hide keyword is not specified.

Style Replace On (default) specifies the layers under the theme are not drawn.

Style Replace Off specifies the layers under the theme are drawn (but without thematic shading), allowing for multi-variate transparent themes.

Style Replace On is the default and provides backwards compatibility with the existing behavior so that the underlying layers are not drawn.

You can use the Apply clause to control which display attributes MapInfo Pro applies to the shaded objects.

If you omit the Apply clause, Apply All is the default.

The Use clause lets you control whether MapInfo Pro applies all of the style elements from the range styles, or only some of the style elements. This is best illustrated by example. The following example shades the table WorldCap, which contains points. This example does not include a Use clause.

Shade WorldCap With Cap_Pop Ranges 
	Apply All 
	0 : 300000 Symbol(35,YELLOW,9) ,
	300000 : 900000 Symbol(35,GREEN,18) , 
	900000 : 20000000 Symbol(35,BLUE,27) 

In this thematic map, each range appears exactly as its Symbol clause dictates: Points in the low range appear as 9-point, yellow stars (code 35 is a star shape); points in the medium range appear as 18-point, green stars; points in the high range appear as 27-point, blue stars.

The following example shows the same statement with the addition of a Use Size clause.

Shade WorldCap With Cap_Pop Ranges 
	Apply All 

	Use Size Symbol(34, RED, 24) ' <<<<< Note! 

	0 : 300000 Symbol(35,YELLOW,9) ,
	300000 : 900000 Symbol(35,GREEN,18) , 
	900000 : 20000000 Symbol(35,BLUE,27) 

Because of the Use Size clause, MapInfo Pro uses only the size values from the latter Symbol clauses (9, 18, 27 point); MapInfo Pro ignores the other display attributes (for example, YELLOW, GREEN, BLUE). The thematic map shows red circles, because the Use Size Symbol clause specifies red circles. The end result: Points in the low range appear as 9-point, red circles; points in the medium range appear as 18-point, red circles; points in the high range appear as 27-point, red circles.

If you specify Use Color instead of Use Size, MapInfo Pro uses only the colors from the latter Symbol clauses. The map will show yellow, green, and blue circles, all at 24-point size.

Specifying Use All has the same effect as leaving out the Use clause.

The Use clause is only valid if you specify Apply All (or if you omit the Apply clause entirely).