{{ message }}

# jenbell27 / Predominance-Tool

## Files

Failed to load latest commit information.
Type
Name
Commit time

# Predominance Toolset

The Predominance Tool prompts you to input the fields you are interested in and reports the predominant value. To run the full tool, you will need to first utilize the “Calculate Gap” tool which calculates the first and second highest numbers in a list of fields and outputs the gap between these two numbers. Then, the “Calculate Predominance” tool incorporates the gap value calculated in the first tool. The gap represents the difference between the largest value and the second largest value. The collection of these gap numbers are compared throughout the dataset in order to measure if the predominance is significant or not. The user can specify 1 of 3 options to determine significance: (1) Should the gap be larger than the mean of all gaps to be considered significant?, (2) Should the gap be greater than a specified standard deviation over the mean to be significant?, or (3) Should the percentage of the gap be greater than a user-specified value to be considered significant?

The rest of this document will address the specifics of each tool, how to implement it in ArcMap, and how to create meaningful symbology for your map.

### 1. The Calculate Gap Tool

This tool finds the first and second highest numbers in a list of inputted fields and outputs the gap (or difference) between these two numbers.

The first step is to click on the manila folder to select a feature class. A list of fields should pop up in the box below. Select the fields you are interested in comparing. After, click “OK” to run the tool.

The tool adds 7 fields to your feature class. To view these fields, right click on the feature class in the Table of Contents and click “Open Attribute Table”. The following is an explanation of each of the added fields:

1. Dominant Component (DomFName): The name of the field with the highest value.
2. Dominant Component Alias (DomFAlias): The alias of the field with the highest value.
3. Dominant Value (DomValue): The value of the dominant field.
4. Margin of Dominance (DomMarg): The difference between the first and second highest values.
5. % Dominance (DomPerc): The percent of the total values the dominant value represents. Calculated by dividing the maximum value by the total value of all selected fields.
6. Transparency (DomPerXP): The transparency of the dominant field. Calculated by subtracting the dominant percent from 100 (e.g., if the dominant field is 80% of the total values, the transparency will be 20%. If the highest value is only 30% of the total value, it will have a higher transparency of 70%.)
7. # of Ties (DomFCnt): The number of fields with the same value.

### 2. The Calculate Predominance Tool

This tool uses the gap (or Margin of Dominance) output from the previous tool to calculate the predominant value. The tool allows the user to specify three options to determine whether a maximum value is considered significant.

First, input the feature class you are interested in analyzing. This should be the same feature class you used in the Calculate Gap tool. Next, choose a predominance option that tells the tool what criteria the maximum field must meet to be considered significant. The three options are as follows:

1. Over the mean (OVER_MEAN): Compares each predominance gap to the mean of all gap values within the dataset.
2. Over the mean + standard deviation (OVER_STD): Compares each predominance gap to the mean of all gap values plus an additional standard deviation. The choices for the standard deviation are 1, .5, or .33.
3. Over a user-specified value (USER_SPEC): Compares the gap to a user-inputted value.

If the user-specified value is selected as the Predominance Option, enter the value. If you are not using a specified value, leave this section blank. If using the standard deviation option, choose between 1, .5, or .33 from the dropdown menu. After, click “OK” to run the tool.

The tool adds fields to the attribute table depending on which Predominance Option you choose:

1. If using “Over the mean”:

• Mean Gap (MeanGap): Calculates the average gap value of all the dominant margins.
• Predominant Field Over Mean Gap (DomOverMean): Outputs the predominant field if it meets the requirement of being over the mean gap value. If not, it outputs “No Predominance Over Mean”.
• Predominant Field Alias Over Mean Gap (MeanDomAlias): Outputs the alias of the predominant field if it meets the requirement of being over the mean gap value. If not, it outputs “No Predominance Over Mean”.
• Mean Gap Transparency (MeanGapTrans): If the predominant field meets the significance requirement, the transparency is set to 0. If not, the transparency is calculated with the following equation: ((average gap – gap)/average gap)*100)
2. If using “Over the mean + 1 standard deviation”:

• 1 Std Gap (OneSDGap): Calculates the average gap value plus one standard deviation of all the dominant margins.
• Predominant Field within 1 Std Dev (Dom1SD): Outputs the predominant field if it meets the requirement of being over the mean gap value plus one standard deviation. If not, it outputs “No Predominance Within 1.0 Standard Deviation”.
• Predominance Field Alias Over 1 SD (SD1DomAlias): Outputs the alias of the predominant field if it meets the requirement of being over the mean gap value plus one standard deviation. If not, it outputs “No Predominance Within 1.0 Standard Deviation”.
• Dominance Transparency Using 1 SD (SD1DomTrans): If the predominant field meets the significance requirement, the transparency is set to 0. If not, the transparency is calculated with the following equation: ((average gap – gap)/average gap)*100)
3. If using “Over the mean + .5 standard deviation”:

• Half Std Gap (HalfSDGap): Calculates the average gap value plus a half standard deviation of all the dominant margins.
• Predominant Field within Half Std Dev (DomHalfSD): Outputs the predominant field if it meets the requirement of being over the mean gap value plus a half standard deviation. If not, it outputs “No Predominance Within 0.5 Standard Deviation”.
• Predominance Field Alias Over Half SD (HalfSDDomAlias): Outputs the alias of the predominant field if it meets the requirement of being over the mean gap value plus a half standard deviation. If not, it outputs “No Predominance Within 0.5 Standard Deviation”.
• Dominance Transparency Using Half SD (HalfSDDomTrans): If the predominant field meets the significance requirement, the transparency is set to 0. If not, the transparency is calculated with the following equation: ((average gap – gap)/average gap)*100)
4. If using “Over the mean + .33 standard deviation”:

• Third Std Gap (ThirdSDGap): Calculates the average gap value plus a third standard deviation of all the dominant margins.
• Predominant Field wihin Third Std Dev (DomThirdSD): Outputs the predominant field if it meets the requirement of being over the mean gap value plus a third standard deviation. If not, it outputs “No Predominance Within 0.33 Standard Deviation”.
• Predominance Field Alias Over Third SD (ThirdSDDomAlias): Outputs the alias of the predominant field if it meets the requirement of being over the mean gap value plus a third standard deviation. If not, it outputs “No Predominance Within 0.33 Standard Deviation”.
• Dominance Transparency Using Third SD (ThirdSDDomTrans): If the predominant field meets the significance requirement, the transparency is set to 0. If not, the transparency is calculated with the following equation: ((average gap – gap)/average gap)*100)
5. If using “Over a user-specified value”:

• User Specified Gap (SpecGap): Fills each row with the gap value that the user specified.
• Predominant Field Over Specified Gap (DomOverSpec): Outputs the predominant field if it meets the requirement of being over the user-inputted value. If not, it outputs “No Predominance Over Specified Gap”.
• Predominant Field Alias Over Specified Gap (UserDomAlias): Outputs the alias of the predominant field if it meets the requirement of being over the user-inputted value. If not, it outputs “No Predominance Over Specified Gap”.
• Specified Gap Transparency Value (SpecGapTrans): If the predominant field meets the significance requirement, the transparency is set to 0. If not, the transparency is calculated with the following equation: ((average gap – gap)/average gap)*100)

### 3. Implement the Tool in ArcMap

The first step to using this Python script is to copy and paste the script into a Notepad. Save the document. In ArcMap, right-click on your project folder, hover over “New”, and click “Toolbox”. This creates a toolbox in your project folder. Right-click on the toolbox, hover over “Add”, and click “Script”. Follow the instructions below to create each tool (go to ArcGIS Help for more information on how to add scripts in ArcMap):

1. Calculate Gap Tool: Give the script a name, label, and description and click “Next”.
Click on the manila folder to open the script you saved in Notepad. Click “Next”. Add two parameters “Input feature class:” (Data Type: Feature Class) and “Fields to compare:” (Data Type: Field). Click “Finish”. To use the tool, just double click on the script and follow the tool instructions.

1. Calculate Predominance Tool: Give the script a name, label, and description and click “Next”. Click on the manila folder to open the script you saved in Notepad. Click “Next”. Add four parameters “Input Feature Class:” (Data Type: Feature Class), “Predominance Option:” (String), “If user-specified gap, enter value:” (Data Type: Long), and “If Standard Deviation Interval, choose value. Default is 1:” (Double). Click “Finish”. To use the tool, just double click on the script and follow the tool instructions.

### 4. Mapping Predominance

After running the Calculate Gap Tool and the Calculate Predominance tool, try mapping the predominant fields. To do this, right-click on the feature class in the Table of Contents and click on “Properties”. Go to the “Symbology” tab and click on the “Categories” section. In the Value Field, choose the field that was outputted from the Calculate Predominance tool (e.g., Predominant Field Over Mean Gap). Click “Add All Values”. Then click on the “Advanced” button to enable a transparency rule. Choose the field related to transparency (e.g., Mean Gap Transparency Value). Click “OK” to see the results on the map.

This type of predominance mapping is beneficial in showing how much more dominant one area is when compared to another. The solid areas (with less transparency) have a greater predominance gap than areas that are more transparent. One example of this type of mapping can be found in this predominant race map.