CreateTheme()

Summary

Creates a color or pattern theme on the current layer.

Changes

Optimal option added to Version 5.0.

Syntax

theme_name = CreateTheme(string identifier, string field_spec, string method, integer num_classes, array options)

Argument	Contents
identifier	The name you want to use for the theme
field_spec	The field spec for the field on which the theme is based
method	The method used to generate the classes, from the table below
num_classes	The number of classes you want to create

Method	How it works
Categories	One value per class; the most frequent values are chosen first (the List of Values method in Maptitude)
Counts	The values option specifies the number of features in each class
Equal Steps	Each class has the same interval value (e.g., 0-50, 50-100, etc.)
Equal Weight	Each class has a weighted sum that is roughly equal (supports the equal area and equal length options in Maptitude)
Manual	The values option specifies the low and high values for each class
Nested Means	The classes are created by first splitting the interval between the high and low value at the mean, and then recursively applying that procedure to each half until the desired number of classes have been defined. The number of classes must be a power of two and will be rounded up to achieve this, with a limit of 64 classes
Optimal	Each class is a cluster of values that minimizes within-group variance using the Fisher-Jenks Algorithm version of the Optimal method of irregular class creation. This method is sometimes called Natural Breaks.
Percents	The values option specifies the percentage of features in each class
Progression	The classes are created using an arithmetic or a geometric progression, with settings controlled by the direction, rate, scale and type options
Standard Deviation	The range of values in each class is the standard deviation times the value indicated in the scale option. If the number of classes is even, the classes start on either side of the mean; if the number of classes is odd, the first class is centered on the mean
Quantiles	Each class contains roughly the same number of features (the Equal Number of Features method in Maptitude)

Option	Type	Contents
Data Source	String	Indicates which data are scanned to determine the minimum and maximum values. If "All" (the default), all features are scanned; if "Screen" only features appearing on the screen in the current map are scanned
Direction	String	Whether the class values in a progression theme are "Decreasing" (the default) or "Increasing"
Drop Empty Classes	Boolean	Whether classes containing zero features should be dropped from the theme (defaults to "False")
Force Other Display	Boolean	Forces the display of the Other class in the legend even if empty (defaults to "False")
Force Value	Real	Forces a break between classes at the specified value (Numeric Categories, Equal Steps, Equal Weight, Quantiles, Standard Deviation)
Include Maximum	Boolean	Whether the maximum value is included (default) or excluded from the range of data
Include Minimum	Boolean	Whether the minimum value is included (default) or excluded from the range of data
Maximum Value	Real	The maximum value to include in a class
Minimum Value	Real	The minimum value to include in a class
Other	Boolean	Whether to include a class (the "Other" class) for features whose values do not fall into any other class (defaults to "True")
Pretty Values	Boolean	Whether to round off the high and low values for each class to make them more presentable (defaults to "False")
Rate	String	The type of rate to use for a progression theme; one of : "Constant", "Decreasing" (the default), or "Increasing"
Retain Values	Boolean	Whether the data values used to create the theme are kept in memory (this option is normally used with TestTheme()); defaults to "False"
Scale	Real	Scaling factor for progression or standard deviation methods; defaults to 1.0
Sort Order	String	If "Descending" classes are created starting with the highest value and working downward; if "Ascending" (the default), classes are created starting with the lowest value and working upward (all numeric themes)
Statistics	Boolean	If "True" complete statistics are generated for the theme and all classes; if "False" only simple summary statistics are calculated (defaults to "False")
Style	Boolean	"True" for a pattern theme; "False" (the default) for a color theme
Title	String	Title of the theme, as it appears in the legend (defaults to theme_name)
Type	String	The type of progression for a progression theme: "Arithmetic" (the default) or "Geometric"
Values	Array	An array containing one element for each class in the theme. The contents of the elements varies by method, as shown below
Weight Field	String	For the equal weight method, the field spec of a numeric field used to weight the data values
Zero	Boolean	Whether zero is treated as a missing value (defaults to "False")

Method	Contents of the values
Counts	Integers that indicate the number of features in each class
Percents	Real number that indicates the percentage of features in each class
Manual (string field)	Strings that indicates the value for each class
Manual (numeric field)	One of the following: real numbers that indicate the value for each class; or an array of {real low_value, boolean low_inclusive, real hi_value, boolean hi_inclusive} indicating the low and high values for each class

Returns

A string indicating the actual name of the theme.

Notes

CreateTheme() creates a theme on the current layer.
Only the Categories and Manual methods are valid for a string field.
If many features have identical values for the field used in the theme, the classes may not conform to the input specifications.
If the values, when using the Counts method, sum to more than the total number of features, or if the values, when using the Percents method, sum to more than 100%, the excess is ignored.
The num_classes parameter is the number of classes excluding the "Other" class; added if the Other option is "True" (the default).
For the Quantiles method, if the values of the num_classes parameter is larger than the number of features, the number of classes will be reduced, since each class must contain at least one feature.
CreateTheme() scans the data for the layer to find appropriate minimum, maximum, and class values for a numeric field, or to identify the values that appear in the data for a string field.
When the Pretty Values option is "True" the minimum and maximum values are rounded as far as possible, without affecting the assignment of features to classes.
For the Manual method, no statistics are generated when the Statistics option is "False".
The color and style of any theme class can be set regardless of whether the theme is a color theme or a pattern theme (as specified by the Style option). However, you cannot display two class themes of the same type at the same time.
The following options apply only to themes on numeric fields: Direction, Force Value, Maximum Value, Minimum Value, Include Maximum, Include Minimum, Pretty Values, Rate, Scale, Sort Order, Type, and Zero.
If the Retain Values option is set to "True" then the memory used should be freed either by a call to ClearThemeValues() or by a subsequent call to CreateTheme() or TestTheme().
The icons used for a color theme for a point layer are the font icons for the classes in the pattern theme. If there is no pattern theme, the font icon for the layer is used. However, with SetThemeIcons() you can set different font icons for some or all of your color theme classes, which will override the font icons for the pattern theme or the font icon for the layer. To have a bivariate map for a point layer, do not set font icons for the color theme.
After creating the theme, you may need to set theme styles; for more information, see Theme Styles.
To display the theme, call ShowTheme(); for more information, see Themes.

Examples

// An income theme with eight classes

thm1 = CreateTheme("Income Theme", "County.Income", "Quantiles", 8, )

//This theme has a break in class values at $30,000, and the low and high values are rounded

thm2 = CreateTheme("Income Theme", "County.Income", "Quantiles", 8, {

{"Force Value", 30000},

{"Pretty Values", "True"}})

//This theme has classes that are created manually

thm3 = CreateTheme("Sales Theme", "Regions.Sales", "Manual", 5, {

{"Values", {

{0, "True", 1000, "False"},

{1000, "True", 2500, "False"},

{2500, "True", 10000, "False"},

{10000, "True", 25000, "False"},

{25000, "True", 100000, "True"}}

}})

//This theme has classes containing the top ten; second ten; etc.

thm4 = CreateTheme("Sales Theme", "Customer|Sales", "Counts", 5, {

{"Values", {10, 10, 10, 10, 10},

{"Sort Order", "Descending"}

}})

Error Codes

Error	Meaning
Escape	The user interrupted data scanning
Error	An argument or option has the wrong type or the wrong number of values, or an error occurred while scanning the data
NotFound	There is no current layer, or the specified field(s) do(es) not exist on the current layer, or the specified field(s) do(es) not contain any valid data

Function	Summary
ShowTheme()	Displays a theme on the current layer
ClearThemeValues()	Remove the data used to generate a theme from memory
CreateChartTheme()	Creates a pie or bar chart theme on the current layer
CreateContinuousTheme()	Creates a continuous (scaled-symbol) theme on the current layer
CreateDotTheme()	Creates a dot-density theme on the current layer
DestroyTheme()	Removes the definition of a theme from the current layer
GetTheme()	Gets information about a theme
GetThemes()	Gets a list of themes defined on the current layer
SetThemeOptions()	Change some theme options
TestTheme()	Provides information on the classes created by a call to CreateTheme