Product: MapBasic
Version: 6.x
Platform: Not Platform Related
Category: Documentation
Summary:
Shade Statement - Description.
Question:
How is the shade statement used to create themes?
Answer:
Shade Statement
Purpose
Creates a thematic map layer and adds it to an existing Map window.
Syntax 1 (shading by ranges of values)
Shade [ Window window_id ]
{ layer_id | layer_name }
With expr
[ Ignore value_to_ignore ]
Ranges
[ Apply { Color | Size | All } ]
[ Use { Color | Size | All } [ Pen... ] [ Line... ] [ Brush... ] [ Symbol... ] ]
{ [ From Variable float_array
Style Variable style_array ] |
minimum : maximum [ Pen... ] [ Line...] [ Brush... ] [ Symbol... ]
[ , minimum : maximum [ Pen... ] [ Line...] [ Brush... ] [ Symbol... ] ... ] }
[ Default [ Pen... ] [ Line... ] [ Brush... ] [ Symbol... ] ]
Syntax 2 (shading by individual values)
Shade [ Window window_id ]
{ layer_id | layer_name }
With expr
[ Ignore value_to_ignore ]
Values const [ Pen... ] [ Line...] [ Brush... ] [ Symbol... ]
[ , const [ Pen... ] [ Line...] [ Brush... ] [ Symbol... ] ... ]
[ Vary { Color | All } ]
[ Default [ Pen... ] [ Brush... ] [ Symbol... ] ]
Syntax 3 (dot density)
Shade [ Window window_id ]
{ layer_id | layer_name }
With expr
Density dot_value : dot_size
[ Color color ]
Syntax 4 (graduated symbols)
Shade [ Window window_id ]
{ layer_id | layer_name }
With expr
Graduated min_value : symbol_size max_value : symbol_size
Symbol . . .
[ Inflect Symbol . . . ]
[ Vary Size By { “LOG” | “SQRT” | “CONST” } ]
Syntax 5 (pie charts)
Shade [ Window window_id ]
{ layer_id | layer_name | Selection }
With expr [ , expr . . . ]
[ Half ] Pie [ Angle angle ] [ Counter ]
[ Fixed ] [ Max Size chart_size [ Units unitname ]
[ At Value max_value [ Vary Size By {“LOG” | “SQRT” | “CONST” } ] ] ]
[ Border Pen . . . ]
[ Position [ { Left | Right | Center } ] [ { Above | Below | Center } ] ]
[ Style Brush . . . [ , Brush . . . ] ]
Syntax 6 (bar charts)
Shade [ Window window_id ]
{ layer_id | layer_name | Selection }
With expr [ , expr . . . ]
{ Bar [ Normalized ] | Stacked Bar [ Fixed ] }
[ Max Size chart_size [ Units unitname ]
[ At Value max_value [ Vary Size By {“LOG” | “SQRT” | “CONST” } ] ] ]
[ Border Pen . . . ]
[ Frame Brush . . . ]
[ Width value [ Units unitname ] ]
[ Position [ { Left | Right | Center } ] [ { Above | Below | Center } ] ]
[ Style Brush . . . [ , Brush . . .] ]
symbol_size is the point size to use for symbols having the appropriate value
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
const is a constant numeric expression or a constant string expression
The Pen clause specifies a line style (e.g. Pen( width, pattern, color ) ) to use for the borders of filled objects (e.g. 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 (e.g. Brush( pattern, forecolor, backcolor ) )
The Symbol clause specifies a symbol style (e.g. Symbol( shape, color, size ) )
minimum is the minimum numeric value for a range
maximum is the maximum numeric value for a range
dot_value is the numeric value associated with each dot in a dot density map
dot_size is the size, in pixels, of each dot on a dot density map
color is the RGB value for the color of the dots in a dot density map.
angle is the starting angle, in degrees, of the first wedge in a pie chart
chart_size is a Float size, representing the maximum height of each pie or bar chart
unitname is a paper unit name (e.g. “in” for inches, “cm” for centimeters)
max_value is a number, used in the At Value clause to control the heights of Pie and Bar charts. For each record, if the sum of the column expressions equals the max_value, that record’s Pie or Bar chart will be drawn at the chart_size height; the charts are smaller for rows with smaller sums.
Description
The Shade statement creates a thematic map layer and adds the layer to an existing Map window. The Shade statement corresponds to MapInfo’s Map>Create Thematic Map menu item. For an introduction to thematic mapping and the Create Thematic Map menu item, see the MapInfo documentation.
Between sessions, MapInfo preserves thematic settings by storing a Shade statement in the workspace file. Thus, to see an example of the Shade statement, create a Map, choose the Map>Create Thematic Map command, save the workspace (e.g. THEME.WOR), and examine the workspace in a MapBasic text edit window. Then, copy the Shade statement to a MapBasic program. Similarly, examples of the Shade statement can be seen by opening MapInfo’s MapBasic Window before choosing Map>Create Thematic Map.
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 (e.g. “world”).
Each Shade statement must specify an expr expression clause. MapInfo evaluates this expression for each object in the table being shaded; following the Shade statement, MapInfo 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.
The keywords following the expr clause dictate which type of shading MapInfo will perform. The Ranges keyword results in a shaded map where each object falls into a range of values; the Values keyword creates a map where each unique value has its own display style; the Density keyword creates a dot density map; the Graduated keyword results in a graduated symbols map; and the Pie and Bar keywords specify thematically constructed charts.
Ranges of Values
In a Ranges map (Syntax 1, above), the From Variable and Style Variable clauses can be used to read pre–calculated sets of range information from array variables. The array variables must have been initialized using the Create Ranges and Create Styles statements. For an example of using arrays in Shade statements, see Create Ranges.
If either the Ranges or Values keyword are specified, the statement can include the optional Default clause. This clause specifies the graphic styles used by the “all others” range. If a row does not fall into any of the specified ranges, MapInfo 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 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 shading regions, specify Brush( ) clauses to control the region fill styles. If shading points, specify Symbol( ) clauses. If shading linear objects (lines, polylines, or arcs) specify Line( ) clauses, not Pen( ) clauses; the syntax is identical, except that the keyword Line would be substituted instead of the keyword Pen. (In a Shade statement, the Pen clause controls the style for the borders of filled objects, such as regions.)
Use the Apply clause to control which display attributes MapInfo applies to the shaded objects.
Apply clause Effect
Apply Color The shading only changes the colors of objects in the map. Point objects appear in their original shape and size, but the thematic shading controls the point colors. Line objects appear in their original pattern and thickness, but the thematic shading controls the line colors. Filled objects appear in their original fill pattern, but the thematic shading controls the foreground color.
Apply Size The shading only changes the sizes of point objects and the thickness of linear objects. Point objects appear in their original shape and color, but the thematic shading controls the symbol sizes. Line objects appear in their original pattern and color, but the shading controls the line thickness.
Apply All The shading controls all display attributes - symbol shape, symbol size, line pattern, line thickness, and color.
If the Apply clause is omitted, Apply All is the default.
The Use clause controls whether MapInfo 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)
Note that the Use Size clause provides its own Symbol style: Shape 34 (circle), in red. Because of the Use Size clause, MapInfo uses only the size values from the latter Symbol clauses (9, 18, 27 point); MapInfo ignores the other display attributes (i.e. 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 Use Color is specified instead of Use Size, MapInfo 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 Apply All is specified(or if the Apply clause is omitted entirely).
Individual Values
In a Values map (Syntax 2, above), the keyword Values is followed by from one to 255 value descriptions. Each value description consists of a unique value (string or numeric), followed by the graphic styles that MapInfo should use to display objects having that exact value. If a record’s expr value is exactly equal to one of the Shade statement’s value descriptions, then that record’s object will be displayed with the appropriate graphic style. The value descriptions are separated by commas.
If the Shade statement specifies either the Ranges or Values keyword, the statement can include the optional Default clause. This clause specifies the graphic styles used by the “all others” range. If a row does not fall into any of the specified ranges, MapInfo assigns the row to the all–others range. The Vary clause sets how the objects will vary in appearance. The default is Vary All. If Vary All is specified, all of the display tools for each range are applied in the theme. If Vary Color is specified, only the color for the specified for each range is applied.
The following example assumes that the UK_Sales table has a column called Sales_Rep; this column contains the name of the sales representative who handles the accounts for a sales territory in the United Kingdom. The Shade statement will display each region in a shade which depends upon that region’s salesperson. Thus, all regions assigned to Bob will appear in one color, while all regions assigned to Jan will appear in another color, etc.
Open Table ”uk_sales”
Map From uk_sales
Shade 1 With Proper$(Sales_Rep)
Ignore ””
Values
”Alan” ,
”Amanda” ,
”Bob” ,
”Jan”
Dot Density Maps
In a Density map (Syntax 3, above), the keyword Density is followed by a dot_value : dot_size clause. Note that a map layer must include regions in order to provide the basis for a meaningful dot density map; this is because the number of dots displayed in each region represent some sort of density value for that region. For example, each dot might represent one thousand households.
In a dot density map, a numeric expr value is calculated for each region; the dot_value represents a numeric value as well. MapInfo decides how many dots to draw in a given region by dividing that region’s expr value by the map’s dot_value setting. Thus, if a region has an expr value of 100, and the Shade statement specifies a dot_value of 5, then MapInfo draws 20 dots in that region, because each dot represents a quantity of 5.
The dot_size specifies how large the dots should be, in terms of pixels. The dot_size should be one (1) or four (4). The optional color clause is used to set the color of the dots.
The following example creates a dot density map using the States table’s Num_HH_90 column, which indicates the number of households per state, circa 1990. The resultant dot density map will show many 4–pixel dots; each dot representing 60,000 households.
Open Table ”states”
Map From states
Shade states With Num_HH_90
Density 60000:4
Graduated Symbols Maps
In a Graduated map (Syntax 4, above), the keyword Graduated is followed by a pair of value : symbol_size clauses. The first of the value : symbol_size clauses specifies what size symbol corresponds to the minimum value, and the second of the value : symbol_size clauses specifies what size symbol corresponds to the maximum value. MapInfo uses intermediate symbol sizes for rows having values between the extremes.
A Symbol clause dictates what type of symbol should appear (circle, star, etc.). If the optional Inflect clause is included, which specifies a second Symbol style, MapInfo uses the secondary symbol style to draw symbols for rows having negative values.
The following example creates a graduated symbols map showing profits and losses. Stores showing a profit are represented as green triangles, pointing up. The Shade statement also includes an Inflection clause, so that stores showing a net loss appear as red triangles, pointing down.
Shade stores With Net_Profit
Graduated
0.0:0 15000:24
Symbol(36, GREEN, 24)
Inflect Symbol(37, RED, 24)
Vary Size By ”SQRT”
The optional Vary Size By clause controls how differences in numerical values correspond to differences in symbol sizes. If the Vary Size By clause is omitted, MapInfo varies the symbol size using the “SQRT” (square root) method, which assigns increasingly larger point sizes as the square roots of the values increase. When varying by square root, each symbol’s area is proportionate to the row’s value; thus, if one row has a value twice as large as another row, the row with the larger value will have a symbol that occupies twice as much area on the map. Note: having twice the area is not the same as having twice the point size. When double an object’s point size is doubled, its area quadruples, because both height and width are being increased.
Pie Chart Maps
In a Pie map (Syntax 5, above), MapInfo creates a small pie chart for each map object to be shaded. The With clause specifies a comma–separated list of two or more expressions to comprise each thematic pie.
If the optional keyword Half is placed before the keyword Pie, MapInfo draws half–pies; otherwise, MapInfo draws whole pies.
The optional Angle clause specifies the starting angle of the first pie wedge, specified in degrees. The default start angle is 180.
The optional Counter keyword specifies that wedges are drawn in counter–clockwise order, starting at the start angle.
The Max Size clause controls the sizes of the pie charts, in terms of paper units (e.g. “in” for inches). If the Fixed keyword is included, all charts are the same size.
For example, the following statement produces pie charts, all of the same size:
Shade sales_95 With phone_sales, retail_sales
Pie Fixed
Max Size 0.25 Units ”in”
To vary the sizes of Pie charts, omit the Fixed keyword and include the At Value clause. For example, the following statement produces a theme where the size of the Pie charts varies. If a record has a sum of 85,000 its Pie chart will be 0.25 inches tall; records having smaller values are shown as smaller Pie charts.
Shade sales_95 With phone_sales, retail_sales
Pie
Max Size 0.25 Units ”in” At Value 85000
The optional Vary Size By clause controls how MapInfo varies the Pie chart size. This clause is discussed above (see Graduated Symbols).
Each chart is placed on the original map object’s centroid, unless a Position clause is used.
The Style clause specifies a comma–separated list of Brush styles; specify one Brush style for each expression specified in the With clause. Brush style settings are optional; if these settings are omitted, MapInfo uses any Brush preferences saved by the user.
The following example creates a thematic map layer which positions each pie chart directly above each map object’s centroid.
Shade sales_95 With phone_sales, retail_sales
Pie Angle 180
Max Size 0.5 Units ”in” At Value 85000
Vary Size By ”SQRT”
Border Pen (1, 2, 0)
Position Center Above
Style Brush(2, RED, 0), Brush(2, BLUE, 0)
Bar Chart Maps
In a Bar map (Syntax 6, above), MapInfo creates a small bar chart for each map object. The With clause specifies a comma–separated list of expressions to comprise each thematic chart.
If you place the optional keyword Stacked before the keyword Bar, MapInfo draws a stacked bar chart; otherwise, MapInfo draws bars side–by–side. If you omit the keyword Stacked, you can include the keyword Normalized to specify that the bars have independent scales.
When creating a Stacked bar chart map, the optional Fixed keyword can be included to specify that all bar charts in the thematic layer should appear in the same size (e.g. half an inch tall) regardless of the numeric values for that map object. If the Fixed keyword is omitted, MapInfo sizes each object’s bar chart according to the net sum of the values in the chart.
The Frame Brush... clause specifies a fill style used for the background behind the bars.
The Position clause controls both the orientation of the bar charts (horizontal or vertical bars) and the position of the charts relative to object centroids. If the Position clause specifies Left or Right, the bars are horizontal, otherwise the bars are vertical.
The Style clause specifies a comma–separated list of Brush styles. Specify one Brush style for each expression specified in the With clause.
The following example creates a thematic map layer which positions each bar chart directly above each map object’s centroid.
Shade sales_93
With phone_sales, retail_sales
Bar
Max Size 0.4 Units ”in” At Value 1245000
Vary Size By ”CONST”
Border Pen (1, 2, 0)
Position Center Above
Style Brush(2, RED, 0), Brush(2, BLUE, 0)
Last Modified: 02/27/2001 10:28:16 AM
|