Integrating external programs within ModelBuilder

Python or other language scripts can be integrated into models by making the script into a script tool and adding the script tool to a model. This can be used when Python or other scripting language logic is needed to enhance a model or to access an external package or program from within ArcGIS.

This section describes how to integrate R, an external statistical package, within the ModelBuilder environment. In the example described below, there are two scripts needed to execute R functionality: a Python script that calls the R source code and the actual R source code. The Python script is what is called from ModelBuilder and serves as a conduit, essentially organizing and piping the arguments from ModelBuilder to R.

The example describes how the two scripts work and interact through a model within the ArcGIS environment. You can follow the steps below like a tutorial or just read to understand and apply for your specific project.

Steps:

1. Downloading and extracting data
2. Installing R on your system
3. Creating a new model and adding the script tool to a model
4. Filling in the script tool parameters
5. Running the model

1-Downloading and extracting data

The example script, Using R in ArcGIS 10, is downloaded from the Geoprocessing Resource Center—Model and Script Tool Gallery. The unzipped folder contains four subfolders and a script tool: Point Clustering (R Version).

2-Installing R

The R package must be installed on the system before the script tool can be executed. If you are working through this section like a tutorial or want to try how this script works at some point in the future, read and follow the instructions carefully from Readme.pdf located in the Doc subfolder of the Resource Center script you downloaded. The R package is specifically used for this example; if you are using any other external program, you are responsible for understanding the details of installing the software.

3-Creating a new model and adding the script tool to a model

The downloaded folder has an R Tools toolbox with a script tool in it. A new model is added to the toolbox by right-clicking New > Model. This opens an empty model. The Point Clustering (R Version) script tool is added by dragging it onto the model from the Catalog window, like any other geoprocessing tool, and creates an output derived data variable connected to the script tool.

Details about writing a Python script and creating a script tool are not covered in this section. There is a complete description about writing a Python script that teaches you how to start and create a script. See Integrating scripts within a model to learn how to create a script tool.

Understanding the example Python script

The script tool that is added to the model can be edited by right-clicking the script tool and clicking Edit. The PointCluster.py script looks like the illustration below:

The code in the script calls for the input parameters to the tool in ArcGIS and passes these parameters to the R statistical package through the R script. When the parameters are passed to R from ArcGIS, the R program is executed and calculates the clusters for the inputs gathered though the Python script in ModelBuilder. The results are then rendered back for display in ArcMap.

Understanding the R script

You cannot see the R script in ModelBuilder or through the Catalog window. It is, however, located in the Scripts subfolder of the downloaded file. The PointCluster.r script is written and saved for this specific example and is called as an external R function in ModelBuilder. If you are using any other program, you have to be aware of the associated files that you need to create. You can then call these scripts, written for any program, from the Python script and run from ModelBuilder.

The PointCluster.r script is shown below. The R file gets the input arguments from the Python-based script tool that was used in ModelBuilder to collect the input parameters. Based on the inputs you provide, the R file executes the cluster analysis. These results are then passed back to the ModelBuilder or ArcGIS application though the Python script and displayed in ArcMap with the applied rendering.

4-Filling in the script tool parameters

The example script runs a cluster analysis on the input point feature class based on the cluster method and the attribute values of the points. In this example, a point feature class representing emergency 911 calls is used as the input. This data is located in the ToolData folder downloaded from the Resource Center. The original data is modified for this example. Each point has a count value indicating number of calls within a specific area around that point. The count field is used to calculate five clusters using the KMEANS_HARTIGAN cluster method.

These input parameters are defined through the Python script. The Python script tool has a dialog box where the input parameters can be designated within ArcGIS.

5-Running the model

When the model containing the R script tool is run, the command line execution window may pop up, indicating the R package program is preparing to execute.

Then the script launches the R statistical package with a default window of the clusTool library.

The R package then calculates the clusters based on the input provided through the Python script tool. The results are sent back, rendered in ArcMap and displayed.