BACKGROUND:
This utility was produced for research into the Red-Cockaded Woodpecker (RCW) conservation
problem. The RCW is federally listed as an endangered species, and can only inhabit land
patches that are purchased and maintained as reserves (patches are grouped into parcels
for purchase). Like many species, RCW dispersion can be predicted using various simulation
models influenced by geographic landscape.

rcw-generator is a utility that, given a base set of coordinates for land patches (grouped
into parcels) with species suitability score, produces a random perturbation of that map
suitable for use in optimization problems. This generator was designed based on research
conducted in the papers:

[1] D. Sheldon, B. Dilkina, A. Elmachtoub, R. Finseth, A. Sabharwal, J. Conrad, 
C. P. Gomes, D. Shmoys, W. Allen, O. Amundsen, and B. Vaughan. Maximizing spread 
of cascades using network design. In UAI-2010: 26th Conference on Uncertainty in 
Artificial Intelligence, pp. 517–526, Catalina Island, Avalon, CA, July 2010.

[2] K. Ahmadizadeh, B. Dilkina, C. P. Gomes, and A. Sabharwal. An empirical study of 
optimization for maximizing diffusion in networks. In CP-2010: 16th Intl. Conf. on 
Principles and Practice of Constraint Programming, St Andrews, Scotland, Sept. 2010. 

The bibtex for these papers is at the end of this readme.  Please cite them when using 
this generator in your own work.  Although the generator was designed based on work 
into the conservation of the Red-Cockaded Woodpecker (RCW), it is applicable to any map 
of territories with an associated integer score in [0,9] representing the suitability of 
that territory as species habitat.  

MAKING THE UTILITY:
Typing "make" in this directory should build rcw-generator on any system with g++
installed.  Typing ./rcw-generator -h will give usage information.  

GIS INPUT:
The argument --gisfile=<file> to rcw-generator should specify a comma-separated file 
containing base map information derived from a GIS layer.  This file specifies a list 
of territories, grouped into real-estate parcels, with an associated integer suitability
score.  The directory sample_basemaps contains two sample GIS input files derived from a 
region of North Carolina, used to study the RCW conservation problem in [2].  

The GIS input files contain 1 line for each territory on the map with the following format:
<X-COORDINATE>,<Y-COORDINATE>,<SUITABILITY-SCORE>,<PARCEL_INDEX>

COST RANGES:
The argument --costfile=<file> to rcw-generator should specify a file containing one line 
per 10 suitability scores in [0,9].  Each line should be a comma-separated pair of integers,
<COST_MIN>,<COST_MAX> representing a range in which parcel costs should be uniformly chosen.
The entry on line N gives the range for choosing the cost of parcels with average suitability
N. The directory sample_costfile contains a simple example.  

INITIAL TERRITORIES:
The utility chooses a number of initial territories, specified by --ninit=<N>, to be 
initially occupied by the species.  The details of this selection process are described 
in [2].  

UTILITY OUTPUT:
After choosing costs for the parcels in the map, perturbing suitability scores, and 
choosing a set of initial territories (see [2] for details) the utility outputs a 
map to stdout. The first two lines give the number of territories and parcels in the 
map, respectively.  The next line gives a comma-separated list of costs for each 
parcel (so that the cost of parcel 0 is in position 0, etc.).  One line for each 
territory is then given, with the following format:
<X-COORDINATE>,<Y-COORDINATE>,<SUITABILITY-SCORE>,<INITIAL-FLAG>

SAMPLE DATA:
The directory sample_basemaps contains sample GIS data for instance generation.  
The directory sample_genmaps contains a number of maps generated for research 
in [2].  

REFERENCES:  
@inproceedings{sheldon-etal10:rcw,
  title={Maximizing Spread of Cascades Using Network Design},
  author={Sheldon, Daniel and Dilkina, Bistra and Elmachtoub, Adam and Finseth, Ryan and Sabharwal, 	
  Ashish and Conrad, Jon and Gomes, Carla P. and Shmoys, David and Allen, Will and Amundsen, Ole and 
  Vaughan, Buck},
  booktitle={UAI-2010: 26th Conference on Uncertainty in Artificial Intelligence},
  address={Catalina Island, Avalon, CA},
  month=jul,
  year=2010,
  pages={517-526}
}

@inproceedings{adgs10:rcw,
  author={Ahmadizadeh, Kiyan and Dilkina, Bistra and Gomes, Carla P. and Sabharwal, Ashish},
  title={An Empirical Study of Optimization for Maximizing Diffusion in Networks},
  booktitle={CP-2010: 16th Intl. Conf. on Principles and Practice of Constraint Programming},
  address={St Andrews, Scotland},
  month=sep,
  year=2010
}
