circuitscape_4_0.html

<h1 id="circuitscape-user-guide">CIRCUITSCAPE User Guide</h1>
<p><strong>Brad McRae, Viral Shah, and Tanmay Mohapatra</strong></p>
<p><strong>Version 4.0 Beta - Updated January 6, 2014</strong></p>
<p><strong><em>How to cite this document:</em></strong> <br/>McRae, B.H., V.B. Shah, and T.K. Mohapatra. 2013. Circuitscape 4 User Guide. The Nature Conservancy. https://www.circuitscape.org.</p>
<p><strong>First-time users:</strong> Please see the section on memory management before running large grids (&gt; 1 million cells).</p>
<h1 id="introduction">1. Introduction</h1>
<p>Circuitscape is an open-source program that uses circuit theory to model connectivity in heterogeneous landscapes. Its most common applications include modeling movement and gene flow of plants and animals, as well as identifying areas important for connectivity conservation. Circuit theory complements commonly-used connectivity models because of its connections to random walk theory and its ability to simultaneously evaluate contributions of multiple dispersal pathways. Landscapes are represented as conductive surfaces, with low resistances assigned to landscape features types that are most permeable to movement or best promote gene flow, and high resistances assigned to movement barriers. Effective resistances, current flow, and voltages calculated across the landscapes can then be related to ecological processes, such as individual movement and gene flow. More detail about the underlying model, its parameterization, and potential applications in ecology, evolution, and conservation planning can be found in McRae (2006) and McRae et al. (2008).</p>
<p>Circuitscape was originally designed to analyze connectivity across raster grids. With version 4.0, it can now analyze arbitrary networks (graphs) with any set of connections between nodes the user specifies. Circuitscape can be run from a stand-alone interface or from an ArcGIS toolbox:</p>
<p align="center"> 
<img src="images/image16.png" alt="GUI" width="500px;"/>
</p> 

<p><strong>Fig. 1.</strong> Stand-alone interface (supports raster and network analyses).</p>
<p align="center"> 
<img src="images/ArcGISInterface.png" alt="ArcGIS Toolbox" 
width=" 300px;"/>
</p> 

<p><strong>Fig. 2.</strong> ArcGIS Toolbox (for raster-based analyses only). The toolbox also includes utilities to put raster and feature class inputs into a common coordinate system. More utilities for creating core habitat areas and resistance layers are in development.</p>
<h3 id="before-you-start">Before You Start</h3>
<p>Whatever software you use, connectivity modeling involves a great deal of research, data compilation, GIS analyses, and careful interpretation of results. Defining areas to connect, parameterizing resistance models, and other modeling decisions you will need to make are not trivial. Before diving in, we strongly recommend that users first acquaint themselves with the process and challenges of connectivity modeling by consulting published resources. Good places to start include overviews on the <a href="https://www.corridordesign.org/">Corridor Design</a> and <a href="http://connectinglandscapes.org/">Connecting Landscapes</a> websites. Spear et al. (2010), Beier et al. (2011) and Zeller et al. (2012) offer helpful advice on resistance mapping and connectivity analysis in general. Before using this software, users should acquaint themselves with the use of circuit theory for modeling connectivity (summarized in McRae et al. 2008).</p>
<p>Lastly, users interested in mapping important connectivity areas may wish to consider <a href="https://code.google.com/p/linkage-mapper/">Linkage Mapper</a>, which maps least-cost corridors. Linkage Mapper now also hybridizes least-cost corridor modeling with Circuitscape (see the Pinchpoint Mapper tool within the Linkage Mapper toolkit). Links to other connectivity tools can be found on the <a href="https://www.corridordesign.org/">Corridor Design</a> and <a href="http://connectinglandscapes.org/">Connecting Landscapes</a> websites.</p>
<h1 id="how-circuitscape-works">2. How Circuitscape Works</h1>
<p>Circuitscape may be called through its own graphical user interface, from the Circuitscape for ArcGIS Toolbox, or from the command line. Users supply Circuitscape with resistance data and the program calculates effective resistances and/or creates maps of current flow and voltages across landscapes and networks.</p>
<h3 id="two-data-types-network-and-raster">Two data types: network and raster</h3>
<p>Circuitscape reads either a network of nodes connected by links or a raster grid of resistances (Fig. 3). Links and raster cells are attributed with resistance values that reflect the degree to which the landscape facilitates or impedes movement. Networks and raster maps can be coded in resistances (with higher values denoting greater resistance to movement) or conductances (the reciprocal of resistance; higher values indicate greater ease of movement).</p>
<p align="center"> 
<img src="images/SimpleNetworkAndRaster.png" 
width="500px;"/>
</p> 

<p><strong>Fig. 3.</strong> Simple illustrations of network and raster data types used by Circuitscape. The program can operate on networks of nodes (left panel) or raster grids (right panel). Raster grid cells can have any resistance value. Here, cells with zero resistance (“short-circuit regions,” which can be used to represent contiguous habitat patches) are shown in white, cells with a resistance of 1 are shown in gray, and a cell with infinite resistance (coded as NODATA) is shown in black.</p>
<p>For rasters, every grid cell with finite resistance is represented as a node in a graph, connected to either its four first-order or eight first- and second-order neighboring cells. Cells with infinite resistance (zero conductance) are dropped. Habitat patches, or collections of cells, can be assigned zero resistance (infinite conductance) using a separate “short-circuit region” file. These collections of cells are collapsed into a single node.</p>
<p align="center"> 
<img src ="images/RasterWithResistors.png" width="400px;"/>
</p> 

<p><strong>Fig. 4.</strong> Raster grids are converted to electrical networks. Each cell becomes a node (represented by a dot), and adjacent cells are connected to their four or eight neighbors by resistors. Here, the two short-circuit regions have each been collapsed into a single node. The infinite resistance cell is dropped entirely from the network.</p>
<div style="page-break-after: always;">

</div>
<h3 id="calculation-modes">Calculation modes</h3>
<p>Circuitscape operates in one of four modes: <strong>pairwise</strong>, <strong>advanced</strong>, <strong>one-to-all</strong>, and <strong>all-to-one</strong>. Pairwise and advanced modes are available for both raster and network data types. The one-to-all and all-to-one modes are available for raster data only.</p>
<p>In the <strong>pairwise</strong> mode, connectivity is calculated between all pairs of focal nodes (points or regions between which connectivity is to be modeled) supplied to the program in a single input file. For each pair of focal nodes, one node will arbitrarily be connected to a 1-amp current source, while the other will be connected to ground. Effective resistances will be calculated iteratively between all pairs of focal nodes, and, if selected, maps of current and voltage will be produced. If there are <em>n</em> focal nodes, there will be <em>n</em>(<em>n</em> - 1)/2 calculations <strong>unless</strong> you’re using focal points (only one cell per focal node) and not mapping currents or voltages. In the latter case, we can do it in <em>n</em> calculations <strong>(much faster)</strong>.</p>
<p>The <strong>advanced</strong> mode offers much greater flexibility in defining sources and targets for current flow. The user defines any number of current sources and any number of grounds in a network or raster landscape, and these are all activated simultaneously. Sources represent points or areas from which current flows, whereas grounds represent nodes where current exits the system.</p>
<p>Source nodes can have different strengths (i.e. inject more or less current into the network or grid), and ground nodes can be tied to ground with any resistance. Current sources and grounds are supplied in separate input files.</p>
<p>Two other modes are available for raster data types only. The <strong>one-to-all </strong>mode is similar to the pairwise mode, and takes the same input files. However, instead of iterating across all focal node <em>pairs</em>, this mode iterates across all focal nodes. In each iteration, one focal node is connected to a 1-amp current source, while all remaining focal nodes are connected to ground. If there are <em>n</em> focal nodes, there will be <em>n</em> calculations.</p>
<p>The <strong>all-to-one </strong>mode is similar to the one-to-all mode, and takes the same input files. However, in this mode Circuitscape connects one focal node to ground and all remaining focal nodes to 1-amp current sources. It then repeats the process for each focal node; if there are <em>n</em> focal nodes, there will be <em>n</em> calculations.</p>
<p>Circuitscape can generate maps showing the current density and voltage at each node or cell under each configuration (and current flow for each link/resistor in networks). Additionally, Circuitscape writes a file reporting effective resistances between all pairs of focal nodes in the pairwise mode, and between each node and ground in the one-to-all mode. Resistances in the all-to-one mode are undefined, so a file is written with zeros indicating successful solves.</p>
<h3 id="illustrations-of-analyses-with-network-data">Illustrations of analyses with network data</h3>
<p>For network data types, any node can be connected to any other node by a resistor:</p>
<p align="center"> 
<img src="images/SimpleNetworkWithNumbers2.png" width=" 
400px;"/>
</p> 

<p><strong>Fig. 5.</strong> Example network. This network would be input as a <strong>text list</strong> specifying resistances between each pair of connected nodes (0-1, 1-2, 1-3, 2-3, and 2-4; see the “Input file formats” section below).</p>
<p>For <strong>pairwise analysis</strong> we would also supply a list of focal nodes (containing at least two node numbers, but as many as five, the number of nodes in the circuit) between which we want to perform calculations.</p>
<p align="center"> 
<img src="images/SimpleNetworkCurrentFlow.png" width=" 
400px;"/>
</p> 

<p><strong>Fig 6.</strong> In pairwise mode, Circuitscape will iterate across pairs of nodes in a focal node list. If node 0 and node 4 are in the focal node list, then one of the iterations will look like the above, with a 1 amp current source connected to one node and the other grounded. Current will flow across the network from the source to the ground. Branch currents, node currents, node voltages, and effective resistances between node pairs can be written for each iteration.</p>
<p>More complexity can be added by running in <strong>advanced mode</strong>, which allows any number of sources and grounds to be activated simultaneously. For example, we could modify the circuit above by adding a single, fixed source at node zero and adding multiple grounds with different resistances. Current sources and grounds are entered in separate files.</p>
<p align="center"> 
<img src="images/AdvancedNetwork.png" width=" 430px;"/>
</p> 

<p align="center"> 
<img src="images/AdvancedNetworkFlows.png" width=" 
400px;"/>
</p> 

<p><strong>Fig. 7.</strong> In advanced mode, any node can be tied to a current source or to ground, either directly or via resistors with any value (top panel). Currents passing through all nodes and links can then be calculated (bottom panel), and voltages can be calculated at each node. Circuit above is from McRae et al. (2008).</p>
<h3 id="illustrations-of-analyses-with-raster-data">Illustrations of analyses with raster data</h3>
<p align="center"> 
<img src="images/Fig1_RasterInputs.png" width=" 600px;"/>
</p> 

<p><strong>Fig. 8.</strong> Example raster input files for <strong>pairwise, one-to-all, and all-to-one modes</strong>. Input files in this example include a <strong>resistance map</strong> specifying per-cell resistances or conductances, a <strong>focal node location file</strong> (with two focal regions and one focal point in this case), and an optional <strong>short-circuit region map</strong>. Focal regions and short-circuit regions represent areas with zero resistance. Cells with the same region ID are considered perfectly connected and are collapsed into a single node, even if they are not contiguous.</p>
<p align="center"> 
<img src="images/Fig2_RasterPairwise.png" width=" 600px;"/>
</p> 

<p><strong>Fig. 9.</strong> Schematic describing <strong>pairwise</strong> mode analyses that would result from the input files shown in Fig. 8. Three sets of pairwise calculations– involving focal nodes 1 and 2, nodes 1 and 3, and nodes 2 and 3–would be conducted. For each pair, one node would be connected to a 1-amp current source, and the other to ground. Note that focal region nodes become short-circuit regions when they are activated (e.g., node 1 in scenario 1), but these regions are not present when the nodes are not activated (e.g., node 1 in scenario 3).</p>
<p align="center"> 
<img src="images/Fig3_RasterOneToAll.png" width=" 600px;"/>
</p> 

<p><strong>Fig. 10.</strong> Schematic describing <strong>one-to-all mode</strong> analyses that would result from the input files shown in Fig. 8. Three sets of calculations– involving focal nodes 1, 2, and 3–would be conducted. For each, one node would be connected to a 1-amp current source, and the other two would be connected to ground. The all-to-one mode is similar, with arrow directions reversed; that is, one node is connected to ground while the remaining nodes are connected to 1-amp current sources.</p>
<p align="center"> 
<img src="images/Fig4_RasterAdvancedInputs.png" width=" 
600px;"/>
</p> 

<p><strong>Fig. 11.</strong> Example raster input files for <strong>advanced mode</strong>, which requires independent <strong>current source and ground files</strong>. Note that current sources in this example have different “strengths,” and ground nodes are connected to ground with differing levels of resistance. This example also includes an optional grid with five short-circuit regions.</p>
<p align="center"> 
<img src="images/Fig5_RasterEffectiveConfiguration.png" 
width=" 600px;"/>
</p> 

<p><strong>Fig. 12.</strong> The first two panels show the “effective” configuration resulting from the input files in Fig. 11. Because current source C and grounds D and E overlap with short-circuit regions, these short-circuit regions effectively become sources or grounds themselves. The rightmost panel shows a schematic of the resulting analysis, with all sources (white points and polygons) and grounds (black points and polygons) activated simultaneously. Note that sources may be negative (drawing current out of the system), and ground nodes can actually contribute current to the system when negative sources are present.</p>
<h1 id="installing-circuitscape">3. Installing Circuitscape</h1>
<h2 id="windows-and-mac-os-x-executables-most-users">Windows and Mac OS X executables (most users)</h2>
<p>Download and run the appropriate setup package (either 32- or 64-bit, depending on your operating system). This will install Circuitscape and create an “examples” directory in the installation directory with example input files on Windows. Mac users should download this directory separately.</p>
<h2 id="arcgis-toolbox-windows-only">ArcGIS Toolbox (Windows only)</h2>
<p>If you have ArcGIS 10.0 or later, you can download and install the Circuitscape for ArcGIS Toolbox from the Circuitscape website. Follow the installation instructions included in the zip package. You will also need to install the Circuitscape executable package (described above) for the toolbox to work.</p>
<h2 id="installing-circuitscape-as-a-python-package">Installing Circuitscape as a Python Package</h2>
<p>For Python users, Circuitscape is available as a regular Python package from the Python packages repository. You will also need to install several packages upon which Circuitscape depends.</p>
<p>Python can be installed from https://www.python.org/ and the <code>pip</code> installer can be installed from http://www.pip-installer.org/.</p>
<p>Before running Circuitscape, you will also need to install the Numpy, Scipy, PyAMG, wxPython and PythonCard Python packages.</p>
<p>Once these are installed, run the following command to get Circuitscape:</p>
<p><code>sudo pip install -U circuitscape</code></p>
<p>When you are done, the following commands will be available for using Circuitscape:</p>
<ul>
<li><code>python csgui.py</code> : to use the graphical user interface</li>
<li><code>python csrun.py &lt;path to .ini configuration file&gt;</code> : to use Circuitscape from the console</li>
<li><code>python csverify.py</code> : to verify the installation.</li>
</ul>
<h2 id="linux">Linux</h2>
<p>Circuitscape can be installed as a Python package on Linux, following the instructions above.</p>
<p>Optionally, you may download the following two files from the Circuitscape source repository:</p>
<ul>
<li><code>setup-unix.sh</code></li>
<li><code>pip_requirements.txt</code></li>
</ul>
<p>And run the command <code>sh setup-unix.sh</code> to guide you through the installation process.</p>
<h1 id="using-circuitscape-with-the-graphical-user-interface">4. Using Circuitscape with the graphical user interface</h1>
<p>To start the user interface using Windows, run Circuitscape as you would any other installed program. In Mac OS X, double-click on Circuitscape.app. The user interface shown in the Introduction section above will appear. You can also call Circuitscape from the Circuitscape for ArcGIS Toolbox, available from the Circuitscape website, or from the command line.</p>
<h2 id="step-1-choose-your-input-data-type">Step 1: Choose your input data type</h2>
<p>The first step is to choose whether you will be analyzing network or raster data.</p>
<h2 id="step-2-choose-a-modeling-mode">Step 2: Choose a modeling mode</h2>
<p>As described above, Circuitscape is run in one of four modes. Pairwise and advanced modes are available for both raster and network data types. The one-to-all and all-to-one modes are available for raster data only.</p>
<h2 id="raster-resistance-map-or-networkgraph">Raster resistance map or network/graph</h2>
<p>The resistance file specifies the ability of each cell in a landscape or link in a network to carry current (See Figs. 5 and 8). File formats are described in the <em>Input file formats</em> section below.</p>
<h3 id="data-represent-conductances-instead-of-resistances">Data represent conductances instead of resistances</h3>
<p>Most users code their network or raster data in terms of resistances (with higher values denoting greater resistance to movement), which is common in connectivity modeling. Check this box if you want to specify conductances instead (conductance is the reciprocal of resistance; higher values indicate greater ease of movement).</p>
<p>Note that zero and infinite values for conductances and resistances represent special cases. Infinite resistances are coded as NODATA values (see file format description in the <em>Input file formats</em> section below) in input resistance grids, or as zero or NODATA in input conductance grids; these are treated as complete barriers, and are disconnected from all other cells. For raster analyses, cells with zero resistance (infinite conductance) can be specified using a separate short-circuit region file as described below.</p>
<div style="page-break-after: always;">

</div>
<h2 id="pairwise-one-to-all-and-all-to-one-mode-options">Pairwise, one-to-all, and all-to-one mode options</h2>
<h3 id="focal-node-location-and-data-type">Focal node location and data type</h3>
<p>This file specifies locations of nodes between which effective resistance and current flow are to be calculated (See Figs. 6 and 9). <strong>Each focal node should have a unique positive integer ID.</strong> Files may be text lists specifying coordinates or appropriate raster grid formats. When a grid is used, it must have the same cell size and extent as the resistance grid. The value stored in each grid cell location refers to the focal node ID. Cells that do not contain focal nodes should be coded with NODATA values. When a text list is used, the value field references the focal node ID. Examples are in the examples directory (located where Circuitscape is installed) and can also be found on the Circuitscape downloads page.</p>
<p>For raster analyses, focal nodes may occur at points (single cells on the resistance grid) or across regions (Fig. 8). For the latter, a single ID would occupymore than one cell in a grid or more than one pair of coordinates in a text list (and falling within more than one cell in the underlying resistance grid). Cells within a single region would then be collapsed into a single node, as they are when short-circuit region files are used (see below). The difference is that a focal region will be “burned in” to the resistance grid only for pairwise calculations that include that focal node. As with short-circuit regions, focal regions need not be made up of contiguous cells. For large grids or large numbers of focal nodes, focal regions may require more computation time. When calculating resistances on large raster grids and not creating voltage or current maps, focal points will run much more quickly.</p>
<h3 id="number-of-parallel-processors-to-use">Number of parallel processors to use</h3>
<p>On Mac OS X and Linux systems, Circuitscape can run iterations in parallel for pairwise mode when focal points, not focal regions, are used. Choose how many processors you would like to devote to Circuitscape runs.</p>
<h2 id="advanced-mode-options">Advanced mode options</h2>
<h3 id="current-source-file">Current source file</h3>
<p>This file specifies locations and strengths, in amps, of current sources (Figs. 7 and 11). Either a raster or a text list may be used. Rasters must have the same cell size, projection, and extent as the resistance grid, and cells that do not contain current sources should be coded with NODATA values. Note: current sources may be positive or negative (i.e., they may inject current into the grid or pull current out. Similarly, grounds may either serve as a sink for current or may contribute current if there are negative current sources in the grid). Examples are in the examples directory.</p>
<h3 id="ground-point-file">Ground point file</h3>
<p>This file specifies locations of ground nodes and resistances or conductances of resistors tying them to ground (Figs. 7 and 11). Either a raster or a text list may be used. Rasters must have the same cell size, projection, and extent as the resistance grid, and cells that do not contain grounds should be coded with NODATA values. Note that if a direct (R = 0) ground connection conflicts with a current source, the ground will be removed unless the ‘remove source’ option in the Options Window is chosen. Example ground input files are in the examples directory.</p>
<h3 id="data-represent-conductances-instead-of-resistances-to-ground">Data represent conductances instead of resistances to ground</h3>
<p>The default (unchecked) setting is to specify resistances to ground. Checking this box means that your ground point file specifies connections to ground in terms of conductance instead. To tie cells directly to ground, use resistances as the data type and set values in the corresponding ground point file to zero.</p>
<h2 id="output-options">Output options</h2>
<h3 id="base-output-filename">Base output filename</h3>
<p>Choose a directory path and base file name for output files. Resistances, current maps, voltage maps, and configuration files (which save user interface settings and have a .ini extension) will all use this base name, along with appropriate suffixes and extensions.</p>
<h3 id="create-current-maps">Create current maps</h3>
<p>When checked, current maps will be generated for every pair of focal nodes in the pairwise mode, or for the current source and ground configuration specified in the advanced mode. Current maps have the same dimension as the original input files, with values at each node (cell) representing the amount of current flowing through the node. In the pairwise mode, a current map file will be created for each focal node pair, and a cumulative (additive) file will be also written. (Note that for a given pair of focal nodes, current maps are identical regardless of which node is the source and which is the ground due to symmetry). For the advanced modeling mode, a single map will be written showing current densities at each cell resulting from the current source and ground configurations in the input files. These files can be displayed in a GIS as in Fig. 13. Such maps can be used to identify areas which contribute most to connectivity between focal points (McRae et al. 2008).</p>
<div class="figure">
<img src="images/image24.png" />
</div>
<p><strong>Fig. 13.</strong> Current map used to predict important connectivity areas between core habitat patches (green polygons, entered as focal regions) for mountain lions. Warmer colors indicate areas with higher current density. “Pinch points,” or areas where connectivity is most tenuous, are shown in yellow. Quantile classification schemes or “histogram equalize” stretches tend to work well for current maps when using ArcGIS. Research Collaborators: Brett Dickson and Rick Hopkins, Live Oak Associates.</p>
<h3 id="create-voltage-maps">Create voltage maps</h3>
<p>For the pairwise modeling mode, voltage maps give node voltages that would be observed for each focal node pair if one node were connected to a 1 amp current source and the other to ground. For the advanced modeling mode, voltage maps show voltages at each cell resulting from the current source and ground configurations in the input files.</p>
<h2 id="the-file-menu">The File menu</h2>
<h4 id="file-load-settings-from-last-run">File &gt;&gt; Load settings from last run</h4>
<p>Loads settings automatically saved the last time the “Run” button was clicked.</p>
<h4 id="file-load-settings-from-file">File &gt;&gt; Load settings from file</h4>
<p>Allows user to browse for a configuration file (.ini extension) with previously saved settings. These can include settings automatically saved in the user-specified output directory upon clicking the “Run” button, or those saved manually using the “Save settings” function.</p>
<h4 id="file-save-settings">File &gt;&gt; Save settings</h4>
<p>Allows the user to save settings they have entered in the user interface for future retrieval as a configuration file (.ini extension). This option is useful for creating run configurations for use in batch mode.</p>
<h4 id="file-verify-code">File &gt;&gt; Verify code</h4>
<p>Allows the user to verify that their installation is working properly. Datasets in the “verify” directory will be used, and effective resistances and current maps will be checked against known correct values. If verification fails, see the log Window for details.</p>
<h4 id="file-run-in-batch-mode">File &gt;&gt; Run in batch mode</h4>
<p>Using the batch mode, you can specify any number of configurations to run by loading configuration (.ini) files saved in a single directory. This can be useful for running large numbers of analyses. The configuration files can be created in the user interface and saved under “Save settings” as described above, and can be modified using standard text editors.</p>
<div style="page-break-after: always;">

</div>
<h2 id="the-options-window">The Options window</h2>
<p><img src="images/OptionsWindow.png" alt="ArcGIS Toolbox" width=" 300px;"/></p>
<p><strong>Fig. 14.</strong> The options window gives access to less-frequently-used options. To access this window via the menu bar, click on Options&gt;&gt; More settings &amp; inputs.</p>
<h3 id="calculation-options">Calculation Options</h3>
<h4 id="connect-raster-cells-to-four-neighbors-instead-of-eight">Connect raster cells to FOUR neighbors instead of EIGHT</h4>
<p>For raster operations, Circuitscape creates a graph (network) by connecting cells to their four (Fig. 4) or eight immediate neighbors. The default is eight (four cardinal and four diagonal neighbors), but check this box if you want to connect cells to their four cardinal neighbors only.</p>
<h4 id="use-average-conductance-instead-of-resistance-for-connections-between-cells">Use average conductance instead of resistance for connections between cells</h4>
<p>For raster operations, this choice determines whether cells are connected by their average resistance or by their average conductance. Most users will want the default (unchecked).</p>
<p>The distinction is particularly important when connecting cells with zero or infinite values. When average resistances are used, first-order neighbors connected by resistors with resistance given by: <em>Rab</em> = (<em>Ra</em> + <em>Rb</em>) / 2, and second-order (diagonal) neighbors are connected by resistors with resistance given by: <em>Rab</em> = √2 * (<em>Ra</em> + <em>Rb</em>) / 2, where <em>Ra</em> and <em>Rb</em> are the resistances of the neighboring cells. When average conductances are used, first-order neighbors connected by resistors with conductance (the reciprocal of resistance) given by: <em>Gab</em> = (<em>Ga</em> + <em>Gb</em>) / 2, and second-order (diagonal) neighbors are connected by resistors with resistance given by: <em>Gab</em> = (<em>Ga</em> + <em>Gb</em>) / (2*√2), where <em>Ga</em> and <em>Gb</em> are the conductances of the neighboring cells. (As noted above, resistance and conductance are reciprocals of each other, i.e., <em>Gab</em> = 1 / <em>Rab</em>.)</p>
<h4 id="preemptively-release-memory-when-possible">Preemptively release memory when possible</h4>
<p>If you are getting memory errors this option may help to free some memory. It will likely result in slower execution times.</p>
<h4 id="pairwise-mode-run-in-low-memory-mode">Pairwise mode: Run in low memory mode</h4>
<p>For raster operations, this option will use less memory in the pairwise mode when focal points (not regions) are used, but will also run somewhat slower.</p>
<h4 id="advanced-mode-use-unit-currents-i1-for-all-current-sources">Advanced mode: use unit currents (i=1) for all current sources</h4>
<p>All current sources will be set to 1 Amp, regardless of the value specified in the current source input file.</p>
<h4 id="advanced-mode-use-direct-connections-to-ground-r0-for-all-ground-points">Advanced mode: use direct connections to ground (R=0) for all ground points</h4>
<p>All ground cells will be tied directly to ground, regardless of the value specified in the input ground file.</p>
<h4 id="advanced-mode-when-a-source-and-ground-are-at-the-same-node">Advanced mode: when a source and ground are at the same node:</h4>
<p>Whenever a cell is connected both to a current source and to ground, this choice will determine whether the source is removed, the ground is removed, both are removed, or both are retained. For the latter, if a source is tied directly to ground (i.e., with zero resistance), the ground connection will be removed.</p>
<h3 id="mapping-options">Mapping Options</h3>
<h4 id="write-maximum-of-current-maps">Write maximum of current maps</h4>
<p>In pairwise, one-to-all, and all-to-one modes, current maps are created for every iteration. By default, Circuitscape will also write a cumulative map showing the sum of values at each node or grid cell across all iterations. If this option is checked, an an extra map that shows the maximum current value at each node or cell across iterations.</p>
<h4 id="write-cumulative-max-current-maps-only">Write cumulative &amp; max current maps only</h4>
<p>Maps of current flow between each pair of focal nodes (or for each focal node in one-to-all and all-to-one modes) will be calculated, but only one summed map of current from all calculations (and a map of maximum values if that option is checked) will be written to disk.</p>
<h4 id="compress-output-grids">Compress output grids</h4>
<p>Output ASCII grids are automatically compressed using the gzip file format. This can be useful when many large maps will be written.</p>
<h4 id="log-transform-current-maps">Log-transform current maps</h4>
<p>Values in output current maps will reflect a log10 transform of current densities, which can be useful for visualizing them in some GIS packages (e.g., ArcView 3.X). Cells with zero current will be re-coded with NODATA values.</p>
<h4 id="set-focal-node-currents-to-zero">Set focal node currents to zero</h4>
<p>When running raster data in pairwise, all-to-one, and one-to all modes, focal nodes will have zero current in output maps when they are activated. For pairwise mode, cumulative maps will still show currents flowing through focal regions that results from other pairs being activated. This helps to show current flowing through a focal region as it moves between other focal regions in cumulative current maps. This current passing through a focal region can give an idea of the importance of the focal region for connecting other focal region pairs (for an example, see Fig. 5 in Dickson et al. 2013).</p>
<h3 id="optional-input-files">Optional Input Files</h3>
<h4 id="read-raster-mask-file">Read raster mask file</h4>
<p>When checked, a dialog will open to select a raster mask file. Cells with negative, zero, or NODATA values in the mask will be dropped from the corresponding resistance map (i.e., treated as complete barriers). Positive integer cells will be retained. File should only contain integers and be in raster format. See example file “mask.asc” in the examples directory.</p>
<h4 id="load-a-raster-short-circuit-region-map">Load a raster short-circuit region map</h4>
<p>Short-circuit regions act as areas of zero resistance, essentially providing patches through which current is given a “free ride” as it flows across the landscape. Each short-circuit region should have a unique positive integer identifier; cells within each region are merged into a single node with all other cells in the region, including non-adjacent cells (i.e., regions need not be contiguous). Non-short-circuit-region areas should be stored as NODATA values. The file must have the same cell size and extent as the resistance grid.</p>
<h4 id="one-to-all-and-all-to-one-modes-read-source-strength-file">One-to-all and All-to-One modes: Read source strength file</h4>
<p>When checked, a dialog will open to select a text list of focal node IDs and corresponding source strengths. For any focal node in this list, the amount of current injected into that node when it is a source node will be set to the strength specified in the list. All nodes not in the list will default to 1 Amp. This should be in the same file format as the Text List File Format given below, but with two columns (ID followed by source strength). File should have a .txt extension. See example file “source_strength_list.txt” in the examples directory.</p>
<h4 id="read-file-with-focal-node-pairs-to-includeexclude">Read file with focal node pairs to include/exclude</h4>
<p>This option allows users to only perform calculations on a subset of focal node pairs. Users can either identify pairs to include in calculations, or pairs to exclude, as specified in the first line of the file.</p>
<p>This affects all modes except the Advanced Mode. Files should be in tab-delimited text with a .txt extension. See formatting information in the <em>Input file formats</em> section below.</p>
<h3 id="the-log-window">The Log Window</h3>
<h4 id="level">Level</h4>
<p>The default level (INFO) sends a moderate amount of information on the program’s progress to the terminal window. DEBUG gives more, and the other options give less.</p>
<h4 id="log-completion-times">Log completion times</h4>
<p>Writes names of operations and completion times for each to the terminal window.</p>
<h4 id="send-to-log-file">Send to log file</h4>
<p>Information printed to the screen will also be saved in a log file in the output directory.</p>
<h1 id="using-the-circuitscape-for-arcgis-toolbox-windows-only">5. Using the Circuitscape for ArcGIS Toolbox (Windows only)</h1>
<p>The ArcGIS toolbox can facilitate raster Circuitscape analyses. It allows you to run Circuitscape from ArcMap or ArcCatalog, using ESRI grids or raster file geodatabases as inputs (no need to export to ASCII). Toolbox options correspond to those in the stand-alone user interface described above. The toolbox also has utilities to convert shapefiles and feature classes to raster focal node files. You must have the Circuitscape executable installed to use the toolbox.</p>
<h1 id="running-circuitscape-from-the-command-line">6. Running Circuitscape from the command line</h1>
<p>On Linux machines, running Circuitscape from the command line can be useful, especially when running over a network. Whether Circuitscape is called from the command line or the graphical user interface, settings (such as input file names) are passed to the main Circuitscape module using a configuration file. The configuration file has a .ini extension, and can be edited and saved from the user interface. The file may also be edited directly in a standard text editor.</p>
<p>To call Circuitscape from the command line in Linux, use the command</p>
<pre><code>python csrun.py [config file]</code></pre>
<p>where <code>[config file]</code> is the name (and path, if the file is in a different directory) of the configuration (.ini) file.</p>
<p>On Windows machines, the command-line executable can be called using the command:</p>
<pre><code>cs_run.exe [config file] </code></pre>
<p>where <code>[config file]</code> is the name (and path, if the file is in a different directory) of the configuration file. You will need to call Circuitscape from the installation directory (e.g., <code>C:\Program Files\Circuitscape\</code>), or provide the full path to <code>cs_run.exe</code>.</p>
<h1 id="calling-circuitscape-from-other-programs">7. Calling Circuitscape from other programs</h1>
<p>Circuitscape can be invoked from external programs to do computations on rasters and networks and return results. It reads user settings from a configuration (.ini) file that can be either created manually or saved from the user interface (under File &gt;&gt; Save settings).</p>
<p>If the external program can interface with Python packages, then the Circuitscape methods can be called directly when Circuitscape is installed as a Python package. For example:</p>
<pre><code>from circuitscape import Compute

cs = Compute(&#39;configuration.ini&#39;, &#39;Screen&#39;)
result = cs.compute()</code></pre>
<p>If such direct interfacing with Python packages is not possible, Circuitscape can be invoked as an application with the following command:</p>
<pre><code>python csrun.py [configuration.ini]</code></pre>
<p>Alternatively, the cs_run.exe executable can be invoked from external programs on Windows.</p>
<p>In the cases above, results are written out to files which can be read back by the external program.</p>
<h1 id="input-file-formats">8. Input file formats</h1>
<p>When working with networks, text lists are used for all input files.</p>
<p>For raster analyses using the ArcGIS toolbox, resistance grids and other inputs can be in a number of raster formats. For raster analyses using the stand-alone Circuitscape interface (Fig. 1) or calling Circuitscape from the command line or from other programs, resistance grids should be in ASCII raster format, and focal node, current source, and ground files can be in either raster or text list format.</p>
<h2 id="esri-raster-formats-when-using-the-circuitscape-for-arcgis-toolbox">ESRI Raster formats (when using the Circuitscape for ArcGIS Toolbox)</h2>
<p>When using the Circuitscape for ArcGIS Toolbox, you can use ESRI grids, raster file geodatabases, ASCII rasters, and other raster formats supported by ArcGIS. It’s a good idea to have your input files in the same projection. The toolbox includes a utility to convert vector focal node files to raster, and to put all input files in one projection with the same raster extent.</p>
<h2 id="ascii-raster-format-when-using-standalone-user-interface-or-calling-directly.">ASCII raster format (when using standalone user interface or calling directly).</h2>
<p>When using the stand-alone Circuitscape interface, raster input maps should be stored in Arc/Info ASCII grid format, as exported by standard GIS packages (see examples in examples directory; these may be viewed with standard text editors). For focal nodes, the value stored in each grid location refers to the focal node ID, and a single ID can occupy more than one cell (IDs must be positive integers). For current sources, the grid value specifies the source strength in amps. For grounds, the grid value specifies either the resistance or conductance of the resistor tying each ground node to ground, as specified in the Options window.</p>
<p>The ASCII raster format is as follows:</p>
<p><strong>Header:</strong></p>
<pre><code>ncols        &lt;Number of columns&gt;
nrows        &lt;Number of rows&gt;
xllcorner    &lt;X coordinate of lower left corner&gt;
yllcorner    &lt;Y coordinate of lower left corner&gt;
cellsize     &lt;size of each cell&gt;
NODATA_value &lt;Code for cells with no habitat, focal nodes, sources or grounds&gt;</code></pre>
<p><strong>Body (grid data):</strong></p>
<p>Numeric data only. Columns are delimited with tabs and rows are delimited with new line characters.</p>
<p><strong>Examples (these can also be found in the examples directory)</strong></p>
<p>Below is a 10 x10 resistance map. Cells with infinite resistance are assigned NODATA values (-9999):</p>
<pre><code>ncols         10
nrows         10
xllcorner     1
yllcorner     1
cellsize      1
NODATA_value  -9999
130    168    153    -9999  14     12    13     107    140    171
104    3      2      -9999  13     158   12     14     13     114
124    2      2      12     -9999  -9999 13     161    4      5
184    5      4      14     13     14    -9999  13     4      4
105    143    103    169    -9999  115   10     -9999  166    14
187    1      163    188    121    142   14     175    -9999  10
198    11     110    115    149    2     2      164    3      -9999
100    11     193    14     12     4     2      1      11     13
-9999  11     12     11     10     12    167    157    181    157
-9999  -9999  122    134    12     157   192    184    190    172</code></pre>
<p>Below is a 10 x 10 focal region map. Here, groups of cells have been coded as focal regions- so these will be treated as “core area polygons” to be connected in circuit analyses. All cells within each focal region will be collapsed into a single node (even the non-contiguous cell in region #1) when that region is activated in pairwise, one-to-all, or all-to-one analyses. This format is identical to the short-circuit region file format.</p>
<pre><code>ncols                10
nrows                10
xllcorner            1
yllcorner            1
cellsize             1
NODATA_value -9999
-9999  -9999  -9999  -9999  -9999  -9999  -9999  -9999  -9999  -9999
-9999  1      1      -9999  -9999  -9999  -9999  -9999  -9999  -9999
-9999  1      1      -9999  -9999  -9999  -9999  -9999  3      3
-9999  1      1      -9999  -9999  -9999  -9999  -9999  3      3
-9999  -9999  -9999  -9999  -9999  -9999  -9999  -9999  -9999  -9999
-9999  1      -9999  -9999  -9999  -9999  -9999  -9999  -9999  -9999
-9999  -9999  -9999  -9999   2      2     -9999  -9999  -9999  -9999
-9999  -9999  -9999  -9999   2      2      2     -9999  -9999  -9999
-9999  -9999  -9999  -9999  -9999  -9999  -9999  -9999  -9999  -9999
-9999  -9999  -9999  -9999  -9999  -9999  -9999  -9999  -9999   -9999</code></pre>
<p>Note that regions 1 and 2 are well-connected by a low-resistance corridor in the resistance map above. Region 3 is connected to the other two regions only if cells are connected to their eight neighbors. In the four-neighbor case, region 3 would be completely isolated.</p>
<h2 id="text-list-file-format">Text list file format</h2>
<p>For network/graph operations, resistor networks, focal nodes, current sources, and grounds should be stored as text lists (saved with a “.txt” extension). To specify a network of resistors, three columns are used. The first and second columns give the node IDs being connected by a resistor, and the third column gives the resistance value. For example, the simple circuit:</p>
<p align="center">
<img src="images/SimpleNetworkWithNumbers2.png" width=" 400px;"/>
</p>  

<p>can be defined by the following text list:</p>
<pre><code>    0   1   1
    1   2   1
    1   3   1
    2   4   1
    3   4   1</code></pre>
<p>This file can be found in the examples directory (network_graph.txt).</p>
<p>For advanced mode, current sources and grounds are also stored as text lists. The above circuit can be expanded to include a current source and grounds with two extra input files. For example, we can add a 1 Amp current source at node 0 with a file that looks like this:</p>
<pre><code>    0   1</code></pre>
<p>To tie node 4 directly to ground (i.e. to connect it to ground with a wire that has a resistance of 0 Ohms) and connect the remaining nodes to ground with resistors, we can use a file that looks like this:</p>
<pre><code>    0   99
    1   33
    2   49.5
    3   49.5
    4   0</code></pre>
<p>These files are also included in the examples directory. The resulting circuit would look like this (from McRae et al. 2008):</p>
<p align="center">
<img src="images/AdvancedNetwork.png" width="500px;"/>
</p>  

<p>For <strong>raster</strong> operations, you can also store focal nodes, current sources, and grounds as text lists (saved with a “.txt” extension). For each node referenced in a text list, a value and X and Y coordinates are specified as shown below.</p>
<pre><code>    Value1 X1 Y1
    Value2 X2 Y2
    …</code></pre>
<p>Note: X and Y are geographical coordinates, not row and column numbers.</p>
<p>Example text list (a partial list of the cell locations in the focal region map above; coordinates are for cell centroids):</p>
<pre><code>    1    2.5    9.5
    1    3.5    9.5
    1    2.5    8.5
    1    3.5    8.5
    1    2.5    7.5  
    1    3.5    7.5
    1    2.5    5.5
    2    6.5    4.5
    …</code></pre>
<p>For focal nodes, the value field references the focal node ID; values must be positive integers, and a single ID can occupy more than one pair of coordinates (and more than one cell in the underlying resistance grid). For current sources, the value field references the source strength in amps. For grounds, the value field references either the resistance or conductance of the resistor tying each ground node to ground, as set in the Options window.</p>
<h2 id="includeexclude-file-format">Include/exclude file format</h2>
<p>This file will be loaded when the ‘Read file with focal node pairs to include/exclude’ option is checked, and affects all modes except the advanced mode. There are two file formats that can be used. The first is the simplest, and gives a list of pairs to include in calculations, or pairs to exclude, as specified in the first line of the file. For example, if there are five focal nodes, numbered 1-5, and the following list is entered, only pairs (1,2), (1,3), and (1,5) will be analyzed:</p>
<pre><code>mode    include
1       2
1       3
1       5</code></pre>
<p>Similarly, if the first line in the above file read:</p>
<pre><code>mode    exclude</code></pre>
<p>all pairs except (1,2), (1,3), and (1,5) would be analyzed. See example file “list_of_pairs_to_include.txt” in the examples directory.</p>
<p>The second method uses a matrix identifying which pairs of focal nodes to connect. The file specifies minimum and maximum values in the matrix to consider a pair connected. This method can be useful when used with a distance matrix to only run analyses between points separated by a minimum distance, or by a distance equal to or less than a maximum distance. Note: any focal node not in the matrix will be dropped from analyses. Entries on the diagonal are ignored. For example, in the following matrix, only pairs with entries between 2 and 50 are connected. Pairs (1,2), (2,4), and (3,4) will not be analyzed.<br />Focal node 5 will be dropped entirely:</p>
<pre><code>min 2
max 50
0     1     2     3     4     5 
1     0     100   6.67  7     1 
2     100   0     11    1     60
3     6.67  11    0     -1    100   
4     7     1     -1    0     0
5     1     60     100  0     0</code></pre>
<p>Make sure to include a zero in the upper-left corner of the matrix.</p>
<p>Files should be in tab-delimited text with a .txt extension. See example file “matrix_of_pairs_to_include_and_exclude.txt” in the examples directory.</p>
<h1 id="output-files">9. Output files</h1>
<h2 id="current-and-voltage-data">Current and voltage data</h2>
<p>Current and voltage data for networks will be written in text list formats.</p>
<p>When using the ArcGIS toolbox, current and voltage maps will be written in the raster format chosen by the user.</p>
<p>When not using the ArcGIS toolbox, raster voltage and current maps are written using the ASCII raster format described above.</p>
<h2 id="resistance-files">Resistance files</h2>
<p>Resistance data are written in both matrix and 3-column formats.</p>
<p>Here are pairwise resistances written to the output directory for the eight neighbor case (using per-cell resistances and average resistances for cell connection calculations; this can be replicated by loading eight_neighbor_example.ini from the examples directory). The first row and column contain the focal node IDs:</p>
<pre><code>  0          1            2            3  
  1          0            11.93688471  15.03634473
  2          11.93688471  0            11.57640568
  3          15.03634473  11.57640568  0  </code></pre>
<p>Here are pairwise resistances written to the output directory for the four neighbor case, in which focal node 3 was completely isolated (-1 indicates infinite resistance):</p>
<pre><code>  0          1            2            3  
  1          0            33.55792693  -1
  2          33.55792693  0            -1
  3          -1           -1           0      </code></pre>
<p>For convenience, resistances are also written to a separate file in a 3-column format, e.g.:</p>
<pre><code>  1      2       33.55792693           
  1      3       -1
  2      3       -1</code></pre>
<h1 id="computational-limitations-speed-and-landscape-size">10. Computational limitations, speed, and landscape size</h1>
<p>We have tested this code on landscapes with up to 100 million cells. Increasing numbers of connections using diagonal (eight neighbor) connections will decrease the size of landscapes that can be analyzed. Also, increasing landscape size or numbers of focal nodes will increase computation time. We anticipate future improvements will increase the program’s speed. Note that due to the matrix algebra involved with solving many pairs of focal nodes, Circuitscape will run much faster when focal points (each focal node falls within only one grid cell), rather than focal regions (at least one focal node occupies multiple grid cells), are used.</p>
<h2 id="important-note-memory-limitations">Important note: memory limitations</h2>
<p>Insufficient RAM is the most common cause of program errors. 32-bit systems will be particularly limited because no more than 2GB of memory can be addressed by any one process, limiting solvable landscapes to approximately 2-6 million cells, depending on the properties of the grid. Larger grids can be solved on 64-bit systems with large amounts of RAM.</p>
<p>There are several ways to increase the solvable grid size. These include closing all other programs (especially those that require lots of RAM such as ArcGIS), setting impermeable areas of your resistance map to NODATA, using focal points instead of regions in pairwise mode, connecting cells to their four neighbors only, and not creating current maps. Also, the one-to-all and all- to-one modes typically use less memory (and run more quickly) than the pairwise mode. In particular, the all-to-one mode can be an alternative to the pairwise mode when the goal is to produce a cumulative map of important connectivity areas among multiple source/target patches. Still, coarsening your grids (using larger cell sizes) may be necessary; doing so often produces results that are qualitatively similar to those obtained with smaller cell sizes. See McRae et al. 2008 for details of effects of using coarser grids.</p>
<h1 id="further-reading">11. Further Reading</h1>
<p>Beier, P., W. Spencer, R. Baldwin, and B.H. McRae. 2011. Best science practices for developing regional connectivity maps. Conservation Biology 25(5): 879-892</p>
<p>Dickson B.G., G.W. Roemer, B.H. McRae, and J.M. Rundall. 2013. Models of regional habitat quality and connectivity for pumas (<em>Puma concolor</em>) in the southwestern United States. PLoS ONE 8(12): e81898. doi:10.1371/journal.pone.0081898</p>
<p>McRae, B.H. 2006. Isolation by resistance. Evolution 60:1551-1561.</p>
<p>McRae, B.H. and P. Beier. 2007. Circuit theory predicts Gene flow in plant and animal populations. Proceedings of the National Academy of Sciences of the USA 104:19885-19890.</p>
<p>McRae, B.H., B.G. Dickson, T.H. Keitt, and V.B. Shah. 2008. Using circuit theory to model connectivity in ecology and conservation. Ecology 10: 2712-2724.</p>
<p>Shah, V.B. 2007. An Interactive System for Combinatorial Scientific Computing with an Emphasis on Programmer Productivity. PhD thesis, University of California, Santa Barbara.</p>
<p>Shah,V.B. and B.H. McRae. 2008. Circuitscape: a tool for landscape ecology. In: G. Varoquaux, T. Vaught, J. Millman (Eds.). Proceedings of the 7th Python in Science Conference (SciPy 2008), pp. 62-66.</p>
<p>Spear, S.F., N. Balkenhol, M.-J. Fortin, B.H. McRae and K. Scribner. 2010. Use of resistance surfaces for landscape genetic studies: Considerations of parameterization and analysis. Molecular Ecology 19(17): 3576-3591.</p>
<p>Zeller K.A., McGarigal K., and Whiteley A.R. 2012. Estimating landscape resistance to movement: a review. Landscape Ecology 27: 777-797.</p>