LoCoH (Local Convex Hull)
Homerange Generator
for ArcView 3.x

Installation

LoCoH for ArcView 3.x offers a number of tools to help create home range distributions using the k-NNCH method (Getz and Wilmers 2004). Requirements for using the extension include:

To install LoCoH, copy the locoh_v2.avx file and the entire 'locoh' folder (which contains this help file) to the ArcView 3.x extensions folder. This is usually located in c:\esri\avgis_30\arcview\ext32. All of LoCoH's tools and options are available in one dialog which can be opened by clicking a button on the View toolbar (Figure 1).

Figure 1. LoCoH dialog box

Source Options

Under source options, select the theme from the current view which has the point data. Point data may be saved as a shapefile or event theme, but event themes have some limitations (see below). If the point theme has a unique ID field in the attribute table, LoCoH will add that field to the local hulls so you can link or join the themes together in ArcView. If the attribute table does not have a field which contains a unique value for every record, you can add one by clicking the 'Add' button.

Next you can choose to have LoCoH use a saved table to help find nearest neighbors, as opposed to manually searching for nearest neighbors each time. This can improve processing speed, particularly for large datasets. To find nearest neighbors using saved associations, check the corresponding checkbox and enter the name of an appropriate dbf file (see next paragraph). LoCoH will identify nearest neighbors using information saved in the dbf file. However if there are duplicate points among the group of nearest neighbors, LoCoH will go back to identifying neighbors spatially.

TIP: If you are working with more than 1,000 points, save nearest neighbor information to disk and use it when testing different values of k.

If you have not yet saved associations to disk, you can do so by specifying a unique ID field (see previous paragraph) and then clicking the 'Create' button. LoCoH will first ask you how many nearest neighbors you want saved to disk. You should enter the maximum number of nearest neighbors that you are likely to test. LoCoH will also create a meta-data file which it checks when reading the associations. Finding nearest neighbors for large datasets can be a slow process, but will improve performance when you create local hulls and isopleths. Whenever changes are made to the shapefile (e.g., new points are added), you should re-create the nearest-neighbor table.

LoCoH provides two options for analyzing a subset of the data. If some points are already selected, you can create a home range for just those points by checking the 'Selected points only' box. You can also filter the data based on attributes in the attribute table, Thus for example if the attribute table for the point data has a field called 'season', you can create separate home ranges for observations made in winter and summer. For more information on creating a criteria file, see Making a Criteria File below.

LoCoH will report whether the view has a projection or units set. This information is provided for the user's benefit only. If LoCoH detects that the data is in degrees (latitude-longitude), and has not been projected, it will display a warning message because unprojected decimal degrees is not a meaningful unit of measurement for area. If you are working with data in decimal degrees, it is recommended that you first project it through the View properties window.

File Options

To create density isopleths, LoCoH must create a number of intermediate shape files (e.g., local hulls unsorted, local hulls sorted, merged hulls, etc.). The File Options section lets you pick where intermediate files will be stored. You can also enter a 'base' that will be used to construct intermediate file names.

LoCoH also gives you an option to automatically delete intermediate files that are not added to the view or project. However any files added to a view or project can't be deleted until ArcView is closed.

Number of Nearest Neighbors Options

LoCoH gives you two choices for entering the number of nearest neighbors to test. With the 'discrete' method, you can enter a single number or multiple numbers separated by commas (e.g., 6, 9, 14). With the continuous method, you can test a number of values by specifying the first number, the last number, and a step value.

TIP: Normally the first thing a analyst should normally do is run the extension with a range of k values (e.g., 5-20) to see which value satisfies the 'minimum covering of spurious holes' rule. Creating isopleths for each value of k is not necessary at this point, but showing the k-area chart can be very helpful (see below).

Duplicate points options

Duplicate points are defined as two points which have the same spatial coordinates (attribute values are not taken into consideration in this version). Duplicate points present special challenges because LoCoH can not create local convex polygons unless there are at least three unique points. Three options are available for handling duplicate points. You can choose to randomly displace duplicate points by a small amount when creating the local hulls. Note this operation only affects the vertices of the local hull, your original data does not get changed. To displace points, enter a distance (in map units) points should be displaced. The 'Suggest' button will suggest a displacement distance by calculating 1/20th of the smallest distance between any two points in the distribution. The direction of displacement will be random.

Alternatively, you can choose to include duplicate points when identifying nearest neighbors, but exclude them when constructing local hulls (this is the behavior used in LCH version 1.x). The last option is to ignore duplcate points both in identifying nearest neighbors and constructing hulls.

View Options

Under view options, you can select whether or not to add the local and merged hulls to the view. Isopleths, if created, will automatically be added to the view.

You can also choose to create a chart showing the total area of merged local hulls versus k. If you have selected to filter points by attributes using a criteria file, a separate chart will created for each batch of points.

The k-area chart is useful when first identifying which value of k satisfies the 'minimum covering of spurious holes' rule. Often the chart will reveal one or more 'jumps' in the total area of local hulls as k increases. These jumps correspond to local hulls crossing over areas of the habitat where the animal is unlikely to exist. Inspecting the merged hulls for these values of k can tell you whether the new areas are spurious or not.

Figure 2. Sample k-area chart

Isopleth Options

Creating isopleths is normally done after you have selected an optimal value of k. The isopleth interval is the increment of additional points in each isopleth, measured as a percentage of the total number of points. An isopleth interval of 10 will result in 10 isopleths being generated (10%, 20%, 30%, etc.), an isopleth interval of 5 will result in 20 isopleths, and so on.

Advanced Options

Click the 'Advanced Options' button on the main dialog to view the Advanced Options form.

Figure 3. Advanced Options form

Isopleth Options

LoCoH also provides two options for how isopleths are 'capped'. You can either define isopleths as the minimum number of local hulls that enclose >= the nth percent of all points, or <= the nth percent of all points. This is illustrated in Figure 4 below.

Figure 4a. Isopleths created by greater-than-or-equal-to method

Figure 4b. Isopleths created by less-than-or-equal-to method

The last isopleth by definition encloses 100% of all points. However this does not always require all of the hulls, which can result in gaps in the union of merged hulls. To prevent this, you can force the last isopleth to use all local hulls.

If isopleths are created, they are automatically added to the view. The color ramp option lets you choose how the isopleths should be displayed. Colors can also be changed manually after the extension is finished, as they can for any other ArcView theme.

Log Options

LoCoH maintains a log of all of its actions which can be used to 1) record the sequence of steps and parameters used, 2) manage files, and 3) trouble-shoot problems. By default, LoCoH will start a new log file each day, and append information about new runs to the end of the file. The Log Options section allows you to specify where the log file should be saved, and whether or not to show it at the end of a run and/or when errors occur. The log is saved as a plain text file, and can be opened with any text editor or word processor.

Making a Criteria File

If you want to subset your data based on values in the theme attribute table, you must enter expressions in a criteria file using the follow guidelines:

  1. The criteria file should be saved as plain text (e.g., using notepad).
  2. Blank lines will be ignored.
  3. Any line that starts with a pound (#) or apostrophe (') character will be ignored. Thus you can use these characters to insert comments or 'rem-out' individual lines without completely deleting them.
  4. Each query expression that defines a subset of the data should be saved on a separate line.
  5. Each line that defines a subset of the data should have two parts separated by a colon.
  6. A line that contains the word "end" in square brackets marks the end of the criteria file. Any lines after this will be ignored by the script. Inserting [end] in the criteria file is optional.

The following is an example of a criteria file.

'Criteria file for buffalo radio collar data
'(this example assumes that the attribute table
'has fields called 'season' and 'sex')

wet_seasn: [season] = 1
dry_seasn: [season] = 2
males: [sex] = "m"
females: [sex] = "f"
dry_males: ([sex] = "m") And ([season] = 2)

[end]
any lines after this will be ignored by the extension

Performance Issues

Event Themes

An event theme is a point theme where the data is not stored in a shapefile but as coordinates in an external table, such as a text file, dbf file, or ODBC source. Each time the project is opened, ArcView opens the table, reads the X and Y coordinates, and recreates the points.

Most features of LoCoH work equally well with event themes as they do with point themes based on shapefiles. However certain operations, such as adding an id field to an attribute table, can not be saved for certain types of event themes (e.g., those based on text files or ODBC sources), and hence have to be recreated whenever the project is reopened. Furthermore, processing may be slower on event themes. Thus in general it is advisable to work with point themes based on shapefiles. You can save your event theme as a shapefile by using the 'Convert to shapefile' command on the Theme menu.

Large Datasets

Working with large point datasets can be very slow. For example, creating hulls with 25 nearest neighbors for 10,000 points will take over two hours on a Pentium IV running at 3.3 GHz with 1Gb RAM. To optimize performance, you should store nearest neighbor associations in an external file (see above). Creating this file will still take a long time, but subsequent runs should go much faster. For example, creating local hulls with 10 nearest neighbors for 10,000 points took 43 minutes when neighboring points were identified on-the-fly, but only 17 minutes when using a saved nearest neighbor associations. If multiple values of K are tested, the time-savings are even greater.

Version History

Version 2.1. March 2005

Version 2.01. December 2004

Version 2.0. November 2004

Version 1.1. February 2004

Copyright and License

LoCoH is copyright of the University of California. However use and distribution of LoCoH is allowed under the provisions of the GNU General Public License.

Development of LoCoH was made possible by support from the National Science Foundation (NSF/NIH EID Grant DEB-0090323).

Feedback

LoCoH is a work in progress, and we depend on the user community to provide feedback and let us know how to improve it. All of LoCoH's Avenue scripts are unencrypted and can be opened in the ArcView script editor, or imported into a new project with a utility such as the Scripts Import-Export extension.

Please send all comments, suggestions, and reports of bugs to Wayne Getz at getz@nature.berkeley.edu. When reporting a bug or error message, please provide as much background information as possible, and if possible a copy of the data that created the error. If we can recreate the problem, there is a good chance we can fix it or identify a work-around. LoCoH was programmed by Andy Lyons alyons@nature.berkeley.edu.

References

Getz, W. and C. Wilmers. 2004. A local nearest-neighbor convex-hull construction of home ranges and utilization distributions. Ecography 27: 489-505. View PDF (1.13 Mb).