NAME: Grid Tools (Jenness Enterprises), v. 1.1

Aka:  grid_tools_jen.avx

Last modified:  January 27, 2004

TOPICS:  statistics, neighborhood, legend, clip, merge, mosaic, combine, ramp, rainbow, color, GTheme

AUTHOR:  Jeff Jenness
Wildlife Biologist, GIS Analyst
Jenness Enterprises
3020 N. Schevene Blvd.
Flagstaff, AZ 86004 USA

jeffj@jennessent.com

DESCRIPTION:  This extension offers several assorted tools for analyzing, displaying, clipping and combining grids:
Neighborhood Statistics: Advanced options for generating neighborhood statistics, including a tool to generate custom neighborhoods.
Grid Statistics: A report of grid statistics, including mean, min, max, SD, etc., plus details on the size and extent of the grid.
Standardize Grid: An option to convert a grid into a standardized grid, with Mean = 0 and Standard Deviation = 1.
Rainbow Legend: Apply a ramped rainbow color scheme to the legend, with as many levels as you like. You can ramp through the spectrum in either direction (i.e. from Red to Violet or from Violet to Red).
Custom Legend: Develop a customized multi-color legend with as many color levels as you like, and ramp between all colors.
Clip Grids: Advanced grid-clipping tools, with options to clip based on the view extent, a theme extent, polygon features, polygon graphics and selected grid cells. Also options to clip outside or inside the clipping objects.
Combine Grids:  Tools for various methods of combining grids, including Merge, Mosaic, and Combine. The Merge tool includes a way to sort your grids.
REQUIRES: Spatial Analyst
This extension requires that the file "avdlog.dll" be present in the ArcView/BIN32 directory (or $AVBIN/avdlog.dll) and that the Dialog Designer extension be located in your ArcView/ext32 directory, which they usually are if you're running AV 3.1 or better.  The Dialog Designer doesn't have to be loaded; it just has to be available. If you are running AV 3.0a, you can download the appropriate files for free from ESRI at:

http://www.esri.com/software/arcview/extensions/dialog/index.html

REVISIONS: Version 1.1 (January 27, 2004) repairs a bug in the Rectangle Neighborhood Statistics which produced a “Error in grid_tools_jen.TPIDialogOK at 6233” message.

Recommended Citation Format: For those who wish to cite this extension, the author recommends something similar to:

Jenness, J. 2004. Grid Tools (Jenness Enterprises) v. 1.1 (grid_tools_jen.avx) extension for ArcView 3.x. Jenness Enterprises. Available at: http://www.jennessent.com/arcview/grid_tools.htm.

Please let me know if you cite this extension in a publication (jeffj@jennessent.com). I will update the citation list to include any publications that I am told about.

General Instructions: 3
Neighborhood Statistics: 3
Statistic Options: 3
Neighborhood Options: 4
Grid Descriptive Statistics: 7
Standardize Grids: 7
Multi-Color Ramping Tools for Legends: 8
Rainbow Color Ramps: 8
Custom Color Ramps: 10
Adding, Deleting and Changing Color Anchors: 13
Loading Pre-Defined Color Schemes: 14
Loading and Saving Custom Color Schemes: 15
Making Graphic Color Bars: 15
Clipping Grids: 17
Combining Grids: 17



General Instructions:

1) Begin by placing the "grid_tools_jen.avx" file into the ArcView extensions directory (../../Av_gis30/Arcview/ext32/).

2) After starting ArcView, load the extension by clicking on File --> Extensions… , scrolling down through the list of available extensions, and then clicking on the checkbox next to the extension called "Grid Tools (Jenness Enterprises)"

3) All tools are found in the “Grid Tools” menu in the View Menu Bar.

Neighborhood Statistics:

This option generates a new grid representing neighborhood statistics from an existing grid. Each cell value in the new grid represents some statistic (i.e. mean, min, max, standard deviation, etc.) from some region of cells surrounding the original cell in the original grid, where the region is called a Neighborhood and can come in a variety of shapes and sizes. The standard Spatial Analyst Neighborhood Statistics function includes options for rectangles, circles, wedges and doughnuts (see ArcView Help files for more information; especially “FocalStats Discussion”). The Neighborhood Statistics function included with this extension is very similar to the original Spatial Analyst function except that this tool allows you to generate custom-shaped neighborhoods and also generate multiple sets of statistics with one operation.

Click the “Neighborhood Statistics” menu item to start the process. You will be asked to identify the grid theme you wish to analyze and the statistics you wish to generate. You may select multiple statistics. This window is resizable by dragging on a corner.

Statistic Options:

If your Grid Theme is a Floating Point theme (i.e. with decimal numbers, and therefore without an attribute table), then your statistics options will include:

  1. Minimum: Each cell value in the new grid will reflect the lowest value in the neighborhood around the original cell.
  2. Mean: Each cell value in the new grid will reflect the average value in the neighborhood.
  3. Maximum: Each cell value in the new grid will reflect the maximum value in the neighborhood.
  4. Range: Each cell value in the new grid will reflect the range of values (i.e. the maximum – the minimum) in the neighborhood.
  5. Standard Deviation: Each cell value in the new grid will reflect the standard deviation of values in the neighborhood.
  6. Variance: Each cell value in the new grid will reflect the variance of values in the neighborhood.
  7. Sum: Each cell value in the new grid will reflect the sum of values in the neighborhood.

If your Grid Theme is an Integer theme, you have a few more options:

  1. Majority: Each cell value in the new grid will reflect the value that occurs most often in the neighborhood.
  2. Minority: Each cell value in the new grid will reflect the value that occurs least often in the neighborhood.
  3. Median: Each cell value in the new grid will reflect the median value in the neighborhood.
  4. Variety: Each cell value in the new grid will reflect the number of unique values in the neighborhood.

Neighborhood Options:

You will next be asked to define your neighborhood. You can choose between a circle, annulus (doughnut-shape), rectangle, wedge, or custom shape. You can also enter your neighborhood parameters in units of either grid cells or map units (i.e. meters, feet, etc.).

  1. Circle: A circular neighborhood defined by a radius length extending outward from the cell center. In theory, this neighborhood should be composed of all grid cells whose cell centers lie within that distance of the focal cell center, but Spatial Analyst appears to have some kind of number rounding issue that sometimes includes or excludes cells that do not exactly fit this definition. If possible, test the neighborhood function to make sure it is including the all the cells you need it to. If not, you may be able to use the Custom Neighborhood function to create a correct neighborhood.





  2. Annulus: An annular neighborhood looks like a ring or doughnut defined by an inner and outer radius length extending outward from the cell center. This neighborhood should be composed of all cells whose cell centers lie within this ring, but this can also be affected by the rounding issues that affect the Circular neighborhood. If testing reveals that the annular neighborhood is not working exactly as desired, you may be able to generate a custom neighborhood that will work correctly.






  3. Wedge: A wedge-shaped neighborhood looks like a slice of pie cut out of a circular neighborhood and is defined by a starting angle, and ending angle, and a radius. As always, it is advisable to test and confirm that your neighborhood is correct, and possibly generate a custom neighborhood if necessary.


  4. Rectangle: A square or rectangular neighborhood defined by width and height, which will be centered around your focal cell center. Cells will be included in the neighborhood if the cell centers lie within this rectangle.








  1. Custom: Custom neighborhoods can be of any shape or arrangement and are defined by explicitly stating which cells, relative to the focal cell, will be included in the neighborhood. To generate a custom neighborhood, first select the “Custom” option from the drop-down list of Neighborhood Types:

Next click the “Create Custom Neighborhood” button to open the custom neighborhood definition window. Select your general neighborhood size by moving the slider to the correct value, and then click in the boxes to specify which cells you wish to be included in the analysis:

Click OK to go back to the “Define Neighborhood” window and notice that it now says “Custom 7 x 7 Neighborhood Loaded…”.

You can now click ‘OK’ and generate your neighborhood statistics grid(s).



Grid Descriptive Statistics:

This function produces a report detailing some general statistics for grid themes, including the minimum, maximum, mean, standard deviation, variance and range for all grid cell values in the grid. The report also describes the geographic extent, the number of rows, columns and cells, and the hard drive location of the grid.

Select the “Grid Descriptive Statistics” menu item and then select the grids you would like to describe:

Click ‘OK’ and you will see a report window with the grid description:

Standardize Grids:

In this case, to standardize a grid means to transform the grid cell values such that the grid has a mean = 0 and a standard deviation = 1. This may be useful in some analyses where the grids may have widely different numeric scales. For example, Andrew Weiss, in a discussion of Topographic Position Indices, describes how it may be desirable to standardize TPI grids before using them for landform identification. This process is described in a poster presented at the 2001 ESRI User Conference.

Technically, all that happens in this operation is that the original grid is subtracted from the grid mean, then divided by grid standard deviation:

Multi-Color Ramping Tools for Legends:

This extension offers two tools to generate customized color ramps for grid legends, enabling you to ramp between multiple colors and generate a large number of color levels. The tools also produce graphic color bars which can be used as attractive legends in layouts or other software.

Rainbow Color Ramps:

This tool generates an array of colors which replicate the visible color spectrum. Click the “Apply Rainbow Color Ramp…” menu item to open the Rainbow Color Ramp Options window:

Select your grid theme and the number of color gradations. This number will reflect the number of classification levels, or individual colors, in your new legend.

You have the option to ramp from Red to Violet or from Violet to Red. In either case the colors will ramp through the visible spectrum:

Click ‘OK’ to generate your new legend:

You also have the option to set your new legend visible or not. In cases where you generate large numbers of classification levels (150 in the example above), it may be useful to set your legend invisible so that it doesn’t take up the entire View table of contents area. You can also set the legend visibility in the “Theme” menu, but setting the visibility directly with this tool may be more convenient.

Finally, you can generate a graphic rainbow color ramp bar by clicking the “Make Graphic Color Bar” button. This option generates a new view, labeled something like “Color Bar” (possibly with a number after it) and will contain a single graphic object:

This graphic can be resized by selecting it with the button and stretching it by dragging on one of the handles:

This color bar can then be added to a layout using the standard Layout functions. Remember that this color bar is actually a View document, so you add it to your layout as you would any other view. Alternatively, you could copy and paste this graphic directly into your view. If so, you will almost certainly need to reposition and resize the graphic. The original graphic coordinates extend from (0, 0) to (500, 20).

You can also take a screenshot of the color bar to paste it into graphic-editing software (i.e. Photoshop, Photopaint, etc.). Click [Alt]-Print Screen to copy the image to the clipboard, then [Control]-V to paste the image into your graphics software.

Custom Color Ramps:

This tool is intended to generate grid legends that ramp (or blend) between multiple colors, and to give you the ability to set the colors and ramp anchor points. IMPORTANT: This tool is not designed to do any type of classification analysis. It only ramps colors smoothly between anchor points.

Click the “Build Custom Color Ramp…” menu item to start the process. You will first be asked to identify the grid theme to build a custom legend for:

Select your grid and click ‘OK’ to open the “Build Color Ramp” window:

The vertical slider on the right of the window shows how the colors will be ramped, and the number box at the top of the window shows how many total color levels to include in the ramp. The color boxes on the right side of the slider show the color anchors, and the numbers on the left side of the slider show the values associated with those colors. In this case, the tool will generate a legend with 24 shades of gray, ranging from White at Value=1617 to Black at 2348.

Adding, Deleting and Changing Color Anchors:

You can add a midpoint color anchor by dragging the slider to the appropriate point and choosing a color. For example, to ramp from White to Red to Black, you would drag the slider to the appropriate point and enter a Red color. As soon as you move the slider, the Color Palette window and a “Select Color” window will open:

Select the desired color and click ‘OK’ to add your new color anchor:

Apply, OK and Clear: You can test your new color ramp by clicking the ‘Apply’ button. This will apply the new color ramp to your theme while leaving the window open. Clicking the ‘OK’ button will apply the color ramp and close the window. The ‘Cancel’ button will close the dialog and reset the theme legend to the original condition.

Changing or Deleting Anchor Colors: You can change the colors of any of the anchor points, or delete any of the internal anchor points, by clicking on the color box. You will be prompted to either delete that color anchor or to change the color:

You cannot delete either of the end anchor points.

Clear: At any point you can clear and reset your custom ramp by clicking the ‘Clear’ button. This button clears all internal color anchors and resets the endpoints to White and Black. It does not change the current number of ramped colors.

Invert: The ‘Invert’ button reverses the order of the colors.

Refresh: The “Refresh” button redraws the slider and the color anchors. The window is resizable by dragging on a corner, but unfortunately the slider does not change size with the window. If you change the size of the window, you must click the ‘Refresh’ button to redraw everything.

Loading Pre-Defined Color Schemes:

ArcView includes a number of pre-defined color schemes that are available in the Legend Editor (i.e. “Red Monochromatic”, “Elevation #1”, “Autumn Leaves”, etc.). This custom color ramp tool also gives you access to these color schemes, plus gives you the ability to ramp between all colors. Choose a scheme from the drop-down list and confirm that you wish to apply it:

Loading and Saving Custom Color Schemes:

This tool provides a way to save custom color ramps so they can be used with other themes. This tool does not save ArcView legends (*.avl) files like the Legend Editor does, but rather specialized files intended to be used specifically with this tool.

IMPORTANT: The saved color ramps do not reference the actual values of the data. If you build and save a custom ramp on a theme that ranges from a value of 1000 to 2000, then you will still be able to apply it to a theme that ranges from 100 to 200. The color anchor points are saved in terms of the percentage along the range of the data rather than in terms of specific data values.

Making Graphic Color Bars:

The “Make Graphic Color Bar” button will generate two graphic color bars that illustrate your color ramp, and which can be used to help make more attractive legends for your grid themes. For example, this tool was used to generate color bars for the author’s Mahalanobis Distances extension manual (see two illustrations at:

http://www.jennessent.com/arcview/mahalanobis_description.htm

In the case of the vertical color bars, the author took screen shots of the color bars, pasted them into image-editing software and rotated them (see discussion of Rainbow color bars above for instructions).

The button makes two color bars. The top one shows only the colors that are actually used in the legends (40 in the example below), while the bottom color bar smoothly blends between colors.

These color bars are actually in View documents, so they can be added to layouts using the “Add View Frame” function. The color bars can also be copied from the Color Bar window and pasted directly into your views, in which case they will likely need to be resized and repositioned in order to look aesthetically correct. They can be resized and repositioned the same way any other graphic shape is, by selecting it with the button and then moving the shape or dragging one of the handles.



Clipping Grids:

This extension allows you to clip grids according to the display extent, a theme extent, selected polygons in a polygon theme, selected polygon graphics, or selected grid cell in an integer grid. The extension also allows you to clip off the regions outside the specified area or to clip out the specified area.

Click the “Clip Grids…” menu item to open the “Clip Grids” window:

Select the grid or grids you wish to clip, the region you wish to base the clip on, and whether you want the new grid to represent only the region (Inside) or everything except the region (outside).

Combining Grids:

ArcView offers several methods for combining multiple grids into a single grid:

  1. Merge: The Merge request treats the set of multiple grids as a stack, where some grids may overlap others. In cases of overlapping grids, the grid which is highest in the stack will take precedence. For example, if a cell in Grid A has a value of 5, and a cell in the same location in Grid B has a value of 10, and if Grid A is higher in the stack than Grid B, then the Combined Grid cell value for that location will be 5. If Grid B was higher in the stack, then the new cell value would be 10.

To do a merge operation correctly, then, you must make sure your grids are in the right order. The Merge tool offered with this extension offers functions to sort your grids. Click the “Merge Grids…” menu item to open the “Select and Sort” window:

Select the grids you want to merge from the list on the right and click the “Add” button to add them to the list on the left. Then select any of the grids in the list on the left and use the arrow buttons to move them up or down. Once your list is sorted correctly, click the “OK” button to merge them.

  1. Mosaic: The Mosaic request attempts to blend overlapping grids so that the boundary is not so sharply defined. The author recommends that you review the ArcView Help Item “Mosaic Discussion” for an explanation of what happens here.

  2. Combine: The Combine request only works for Integer grids, and is a method of combining the attribute data. The combined grid will have a separate field in the attribute table for each of the input grids, and will have a separate record for every unique combination of attribute values.

Enjoy! Please contact the author if you have problems or find bugs.

Jeff Jenness jeffj@jennessent.com
Jenness Enterprises http://www.jennessent.com
3020 N. Schevene Blvd. (928) 607-4638
Flagstaff, AZ 86004

USA

Updates to this extension and an on-line version of this manual are available at

http://www.jennessent.com/arcview/grid_tools.htm

Please visit Jenness Enterprises ArcView Extensions site for more ArcView Extensions and other software by the author.  We also offer customized ArcView-based GIS consultation services to help you meet your specific data analysis and application development needs.