This repository has been archived by the owner on Dec 15, 2018. It is now read-only.
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathcircuitscape_4_0_user_guide.html
1153 lines (1081 loc) · 62.6 KB
/
circuitscape_4_0_user_guide.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="https://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<title>circuitscape_4_0</title>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<style type="text/css">
/* GitHub stylesheet for MarkdownPad (https://markdownpad.com) */
/* Author: Nicolas Hery - https://nicolashery.com */
/* Version: b13fe65ca28d2e568c6ed5d7f06581183df8f2ff */
/* Source: https://github.com/nicolahery/markdownpad-github */
/* RESET
=============================================================================*/
html, body, div, span, applet, object, iframe, h1, h2, h3, h4, h5, h6, p, blockquote, pre, a, abbr, acronym, address, big, cite, code, del, dfn, em, img, ins, kbd, q, s, samp, small, strike, strong, sub, sup, tt, var, b, u, i, center, dl, dt, dd, ol, ul, li, fieldset, form, label, legend, table, caption, tbody, tfoot, thead, tr, th, td, article, aside, canvas, details, embed, figure, figcaption, footer, header, hgroup, menu, nav, output, ruby, section, summary, time, mark, audio, video {
margin: 0;
padding: 0;
border: 0;
}
/* BODY
=============================================================================*/
body {
font-family: Helvetica, arial, freesans, clean, sans-serif;
font-size: 14px;
line-height: 1.6;
color: #333;
background-color: #fff;
padding: 20px;
max-width: 960px;
margin: 0 auto;
}
body>*:first-child {
margin-top: 0 !important;
}
body>*:last-child {
margin-bottom: 0 !important;
}
/* BLOCKS
=============================================================================*/
p, blockquote, ul, ol, dl, table, pre {
margin: 15px 0;
}
/* HEADERS
=============================================================================*/
h1, h2, h3, h4, h5, h6 {
margin: 20px 0 10px;
padding: 0;
font-weight: bold;
-webkit-font-smoothing: antialiased;
}
h1 tt, h1 code, h2 tt, h2 code, h3 tt, h3 code, h4 tt, h4 code, h5 tt, h5 code, h6 tt, h6 code {
font-size: inherit;
}
h1 {
font-size: 28px;
color: #000;
}
h2 {
font-size: 24px;
border-bottom: 1px solid #ccc;
color: #000;
}
h3 {
font-size: 18px;
}
h4 {
font-size: 16px;
}
h5 {
font-size: 14px;
}
h6 {
color: #777;
font-size: 14px;
}
body>h2:first-child, body>h1:first-child, body>h1:first-child+h2, body>h3:first-child, body>h4:first-child, body>h5:first-child, body>h6:first-child {
margin-top: 0;
padding-top: 0;
}
a:first-child h1, a:first-child h2, a:first-child h3, a:first-child h4, a:first-child h5, a:first-child h6 {
margin-top: 0;
padding-top: 0;
}
h1+p, h2+p, h3+p, h4+p, h5+p, h6+p {
margin-top: 10px;
}
/* LINKS
=============================================================================*/
a {
color: #4183C4;
text-decoration: none;
}
a:hover {
text-decoration: underline;
}
/* LISTS
=============================================================================*/
ul, ol {
padding-left: 30px;
}
ul li > :first-child,
ol li > :first-child,
ul li ul:first-of-type,
ol li ol:first-of-type,
ul li ol:first-of-type,
ol li ul:first-of-type {
margin-top: 0px;
}
ul ul, ul ol, ol ol, ol ul {
margin-bottom: 0;
}
dl {
padding: 0;
}
dl dt {
font-size: 14px;
font-weight: bold;
font-style: italic;
padding: 0;
margin: 15px 0 5px;
}
dl dt:first-child {
padding: 0;
}
dl dt>:first-child {
margin-top: 0px;
}
dl dt>:last-child {
margin-bottom: 0px;
}
dl dd {
margin: 0 0 15px;
padding: 0 15px;
}
dl dd>:first-child {
margin-top: 0px;
}
dl dd>:last-child {
margin-bottom: 0px;
}
/* CODE
=============================================================================*/
pre, code, tt {
font-size: 12px;
font-family: Consolas, "Liberation Mono", Courier, monospace;
}
code, tt {
margin: 0 0px;
padding: 0px 0px;
white-space: nowrap;
border: 1px solid #eaeaea;
background-color: #f8f8f8;
border-radius: 3px;
}
pre>code {
margin: 0;
padding: 0;
white-space: pre;
border: none;
background: transparent;
}
pre {
background-color: #f8f8f8;
border: 1px solid #ccc;
font-size: 13px;
line-height: 19px;
overflow: auto;
padding: 6px 10px;
border-radius: 3px;
}
pre code, pre tt {
background-color: transparent;
border: none;
}
kbd {
-moz-border-bottom-colors: none;
-moz-border-left-colors: none;
-moz-border-right-colors: none;
-moz-border-top-colors: none;
background-color: #DDDDDD;
background-image: linear-gradient(#F1F1F1, #DDDDDD);
background-repeat: repeat-x;
border-color: #DDDDDD #CCCCCC #CCCCCC #DDDDDD;
border-image: none;
border-radius: 2px 2px 2px 2px;
border-style: solid;
border-width: 1px;
font-family: "Helvetica Neue",Helvetica,Arial,sans-serif;
line-height: 10px;
padding: 1px 4px;
}
/* QUOTES
=============================================================================*/
blockquote {
border-left: 4px solid #DDD;
padding: 0 15px;
color: #777;
}
blockquote>:first-child {
margin-top: 0px;
}
blockquote>:last-child {
margin-bottom: 0px;
}
/* HORIZONTAL RULES
=============================================================================*/
hr {
clear: both;
margin: 15px 0;
height: 0px;
overflow: hidden;
border: none;
background: transparent;
border-bottom: 4px solid #ddd;
padding: 0;
}
/* TABLES
=============================================================================*/
table th {
font-weight: bold;
}
table th, table td {
border: 1px solid #ccc;
padding: 6px 13px;
}
table tr {
border-top: 1px solid #ccc;
background-color: #fff;
}
table tr:nth-child(2n) {
background-color: #f8f8f8;
}
/* IMAGES
=============================================================================*/
img {
max-width: 100%
}
</style>
</head>
<body>
<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 - Updated March 28, 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. <a href="https://www.circuitscape.org">http://www.circuitscape.org</a>.</p>
<p><strong>First-time users:</strong> Please see the section on memory management before
running large grids (> 1 million cells).</p>
<h1 id="1-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="https://raw.github.com/Circuitscape/Circuitscape/master/docs/4.0/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="https://raw.github.com/Circuitscape/Circuitscape/master/docs/4.0/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="https://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>See the <a href="https://www.circuitscape.org/gnarly-landscape-utilities">Gnarly Landscape Utilities website</a> for tools that can help to automate resistance and core area modeling. </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="2-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="https://raw.github.com/Circuitscape/Circuitscape/master/docs/4.0/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 ="https://raw.github.com/Circuitscape/Circuitscape/master/docs/4.0/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>
<p><div style="page-break-after: always;"></div></p>
<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="https://raw.github.com/Circuitscape/Circuitscape/master/docs/4.0/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 <em>Input file formats</em> 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="https://raw.github.com/Circuitscape/Circuitscape/master/docs/4.0/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="https://raw.github.com/Circuitscape/Circuitscape/master/docs/4.0/images/AdvancedNetwork.png" width=" 430px;"/>
</p>
<p align="center"> <img src="https://raw.github.com/Circuitscape/Circuitscape/master/docs/4.0/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="https://raw.github.com/Circuitscape/Circuitscape/master/docs/4.0/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="https://raw.github.com/Circuitscape/Circuitscape/master/docs/4.0/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="https://raw.github.com/Circuitscape/Circuitscape/master/docs/4.0/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="https://raw.github.com/Circuitscape/Circuitscape/master/docs/4.0/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="https://raw.github.com/Circuitscape/Circuitscape/master/docs/4.0/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="3-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 <a href="https://www.python.org/">http://www.python.org/</a> and the <code>pip</code> installer
can be installed from <a href="https://www.pip-installer.org/">http://www.pip-installer.org/</a>. </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 <path to .ini configuration file></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="4-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-network-graph">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>
<p><div style="page-break-after: always;"></div></p>
<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>
<p><img src="https://raw.github.com/Circuitscape/Circuitscape/master/docs/4.0/images/image24.png" alt=""> </p>
<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 >> 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 >> 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 >> 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 >> 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 >> 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>
<p><div style="page-break-after: always;"></div></p>
<h2 id="the-options-window">The Options window</h2>
<p><img src="https://raw.github.com/Circuitscape/Circuitscape/master/docs/4.0/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>> More settings &
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> = sqrt(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 * sqrt(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-i-1-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-r-0-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 & 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-include-exclude">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="5-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="6-running-circuitscape-from-the-command-line">6. Running Circuitscape from the command line</h1>
<p>On Linux machines, Circuitscape is run from the command line. On other platforms,
running from the command line is useful when calling different Circuitscape from
scripts (e.g., written in Python or R) or external programs. </p>
<p>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 created and saved from
the user interface. The file may also be edited directly in a standard text
editor. We don't yet have documentation for each of the settings, but if you
save some different configurations from the user interface and edit the
resulting .ini files, you can quickly get the hang of which options correspond
to which settings in the interface. </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="7-calling-circuitscape-from-other-programs">7. Calling Circuitscape from other programs</h1>
<p>Circuitscape can be invoked from external programs and scripts (e.g., Python
and R) 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 >> 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('configuration.ini', 'Screen')
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
and scripts on Windows. Linkage Mapper calls Circuitscape this way from the
Pinchpoint and Centrality modules, as does the Circuitscape for ArcGIS toolbox. </p>
<p>In the cases above, results are written out to files which are then read back
by the external program. </p>
<h1 id="8-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 <Number of columns>
nrows <Number of rows>
xllcorner <X coordinate of lower left corner>
yllcorner <Y coordinate of lower left corner>
cellsize <size of each cell>
NODATA_value <Code for cells with no habitat, focal nodes, sources or grounds></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="https://raw.github.com/Circuitscape/Circuitscape/master/docs/4.0/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). <strong>Please note:</strong> typically, there should just be one entry for each pair of connected nodes. If there are two entries for a single pair in the form of (node1, node2, value1) and (node2, node1, value2), these will be considered parallel resistors and their conductances will be summed. For example, if the above text list had an extra entry for node pair (4, 3) like this:</p>
<pre><code> 0 1 1
1 2 1
1 3 1
2 4 1
3 4 1
4 3 1</code></pre>
<p>then the resistance between nodes 3 and 4 in the resulting graph would be 1/2 ohm. </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>