GRASS-Wiki - User contributions [en]

Workshop on urban growth modeling with FUTURES

2016-03-22T22:09:43Z

⚠️Dbvanber: /* Development pressure */

{{ToModify}}
= Workshop introduction =
r.futures.* is an implementation of the '''FUT'''ure '''U'''rban-'''R'''egional '''E'''nvironment '''S'''imulation (FUTURES)[1] which is a model for multilevel simulations of emerging urban-rural landscape structure. FUTURES produces regional projections of landscape patterns using coupled submodels that integrate nonstationary drivers of land change: per capita demand (DEMAND submodel), site suitability (POTENTIAL submodel), and the spatial structure of conversion events (PGA submodel).

[1] Meentemeyer, R. K., Tang, W., Dorning, M. A., Vogler, J. B., Cunniffe, N. J., & Shoemaker, D. A. (2013). [http://www.tandfonline.com/doi/abs/10.1080/00045608.2012.707591 FUTURES: multilevel simulations of emerging urban-rural landscape structure using a stochastic patch-growing algorithm.] Annals of the Association of American Geographers, 103(4), 785-807

== Software ==
There are a number of software requirements to run FUTURES that will need to be download and installed. Required software includes:
* GRASS GIS 7
* addons
** {{AddonCmd|r.futures.pga}}
** {{AddonCmd|r.futures.potential}}
** {{AddonCmd|r.futures.potsurface}}
** {{AddonCmd|r.futures.demand}}
** {{AddonCmd|r.futures.devpressure}}
** {{AddonCmd|r.sample.category}}
* R (≥ 3.0.2) - needed for {{AddonCmd|r.futures.potential}} with packages:
**MuMIn, lme4, optparse, rgrass7
* SciPy - useful for {{AddonCmd|r.futures.demand}}

=== Installation ===
We use the R statistical software for our calculation of site suitability (i.e. development potential) in FUTURES. R is a free software environment for statistical computing and graphics. If you don't have R, or you have older an version, please download and install the software from [http://archive.linux.duke.edu/cran/ install R] and be sure to additionally add these required packages:
<pre>
install.packages(c("MuMIn", "lme4", "optparse", "rgrass7"))
</pre>

==== MS Windows ====
We will be using GRASS GIS 7.0.3 that can be found here in the [https://trac.osgeo.org/osgeo4w/ OSGeo4W] package manager.
Please install the latest stable GRASS GIS 7 version and the SciPy Python package using the ''Advanced install'' option.
A guide with step by step screen shot instructions is available [https://docs.google.com/presentation/d/1yEGpriBne7RvjB35HI6GecNwO1P1y2nRGqDThqoNnCE/edit?usp=sharing here].

In order for GRASS to be able to find R executables, GRASS must be on the PATH variable. Follow this [solution] to make R accessible from GRASS permanently.
A simple but temporary solution is to open GRASS GIS and paste this in the black terminal:
<pre>
set PATH=%PATH%;C:\Program Files\R\R-3.0.2\bin
</pre>
This has to be repeated after restarting GRASS session.

==== Ubuntu Linux ====
Install GRASS GIS from packages:
<pre>
sudo add-apt-repository ppa:ubuntugis/ubuntugis-unstable
sudo apt-get update
sudo apt-get install grass
</pre>

== Workshop data ==
The data that we will be using for the workshop can be download here: [http://fatra.cnr.ncsu.edu/futures/futures_ncspm_Asheville.zip sample dataset]. Please place these layers in your local GRASS directory:
* digital elevation model ([http://nationalmap.gov/elevation.html NED])
* [http://www.mrlc.gov/ NLCD] 2001, 2011
* NLCD 1992/2001 Retrofit Land Cover Change Product
* transportation network ([http://www.census.gov/geo/maps-data/data/tiger-line.html TIGER])
* county boundaries ([http://www.census.gov/geo/maps-data/data/tiger-line.html TIGER])
* protected areas ([http://www.conservationgateway.org/ConservationByGeography/NorthAmerica/UnitedStates/edc/reportsdata/terrestrial/secured/Pages/default.aspx Secured Lands])
* cities as points (USGS)

In addition, download [http://fatra.cnr.ncsu.edu/futures/futures_Asheville_files.zip population information as text files]:
* county population past estimates and future projections ([https://www.osbm.nc.gov/demog/county-projections NC OSBM]) per county (nonspatial)

= GRASS GIS introduction =
There are many advantages to using the open source GRASS GIS platform, but for many that are more familiar with ARCGis and QGis, the setup and implementation of spatial tools in GRASS can be confusing. Here we provide an overview of the GRASS GIS project: [https://grass.osgeo.org grass.osgeo.org] that might be helpful to review if you are a first time users. For this exercise it's not necessary to have a full understanding of how to use GRASS. However, you will need to know how to place your data in the correct GRASS database directory, as well as some basic GRASS functionality. Step by step instructions are provided below
== Setting up GRASS for the tutorial ==
GRASS uses unique database terminology and structure ([https://grass.osgeo.org/grass71/manuals/grass_database.html GRASS database]) that are important to understand for the set up of this tutorial, as you will need to place the required data (e.g. Mapset) in a specific GRASS database Location. In the following we review important terminology and give step by step direction on how to download and place you data in the correct location.

=== Important GRASS directory terminology ===
* A '''GRASS database''' consist of directory with specific Locations (projects) where data layer are stored
* '''Location''' hold all Mapsets in a specific directoy that have the same spatial projection (spatial reference system)
* '''Mapset''' are a collection of maps with the same spatial projection

=== Creating a GRASS database for the tutorial ===
You need to create a GRASS database with the Mapset that we will use for the tutorial before we can run the FUTURES model. Please Download the [http://fatra.cnr.ncsu.edu/futures/futures_ncspm_Asheville.zip workshop location], noting where the files are located on your local directory. Now, create (unless you already have it) a directory named <tt>grassdata</tt> (GRASS database) in your home folder (or Documents), unzip the downloaded data into this directory. You should now have a Location <tt>futures_ncspm</tt> in <tt>grassdata</tt>.

<center><gallery perrow=1 widths=500 heights=250>Image:GRASS FUTURES startup.png|GRASS GIS 7.0.3 startup dialog with downloaded Location and Mapsets for FUTURES workshop</gallery></center>

=== Launching and exploring data in GRASS ===
Now that we have the data in the correct GRASS database, we can launch the Graphical User Interface (GUI). The GUI interface allows you to display raster, vector data as well as navigate through zooming in and out. Advanced exploration and visualization, like many popular GIS software, is also possible in GRASS (e.g. queries, adding legend). The print screens below depicts how you can add different map layers (left) and display the metadata of your data layers.

<center><gallery perrow=2 widths=500 heights=250>Image:GRASS FUTURES wxGUI display.png|Layer Manager and Map Display overview. Annotations show how to add raster layer, query, add legend.
Image:wxGUI_metadata_rinfo.png|Show raster map metadata by right click on layer</gallery></center>

== GRASS functionality ==
One of the advantage of GRASS is the diversity and number of module addons that let you analyze all manner of spatial and temporal. Because it is open source modules are added daily increasing functionality and methods for analysis of your data. GRASS GIS has over [https://grass.osgeo.org/grass70/manuals/full_index.html 500 different modules] in the core distribution and over [https://grass.osgeo.org/grass70/manuals/addons/ 230 addon modules] that can be used to prepare and analyze data layers.
<center>
{| class="wikitable"
|-
! Prefix !! Function !! Example
|-
| r.* || raster processing || ''{{cmd|r.mapcalc}}'': map algebra
|-
| v.* || vector processing || ''{{cmd|v.clean}}'': topological cleaning
|-
| i.* || imagery processing || ''{{cmd|i.segment}}'': object recognition
|-
| db.* || database management || ''{{cmd|db.select}}'': select values from table
|-
| r3.* || 3D raster processing || ''{{cmd|r3.stats}}'': 3D raster statistics
|-
| t.* || temporal data processing || ''{{cmd|t.rast.aggregate}}'': temporal aggregation
|-
| g.* || general data management || ''{{cmd|g.rename}}'': renames map
|-
| d.* || display ||''{{cmd|d.rast}}'': display raster map
|}</center>

=== Command line vs. GUI interface===
GRASS modules can be executed either through a GUI or command line interface. The GUI offers a user-friendly approach to executing modules where the user can navigate to data layers that they would like to analyze and modify processing options with simple check boxes. The GUI also offer a easily accessible manual on how to execute a model. The command line interface allows users to execute a module using command prompts specific to that module. This is handy when you are running similar analyses with minor modification or are familiar with the module commands for quick efficient processing. In this workshop we provide module prompts that can be copy and pasted into the command line for our workflow, but you can use both GUI and command line depending on personal preference. Look how {{cmd|wxGUI.modules|version=71|desc=GUI and command line interface}} represent the same tool. ''Task:'' compute aspect (orientation) from provided digital elevation model using module {{cmd|r.slope.aspect}} using both module dialog and command line.
* How to find modules? Modules are organized by their functionality in wxGUI menu, or we can search for them in Search modules tab. If we already know which module to use, we can just type it in the wxGUI command console. <center><gallery perrow=3 widths=380 heights=190>Image:wxGUI_menu_rinfo.png|Modules can be found in wxGUI menu
Image:wxGUI_module_search.png|You can search modules by name, description or keywords in ''Search modules'' tab
Image:wxGUI_console_completion.png|By typing prefix r. we make a list of modules starting with that prefix to show up.</gallery></center>

=== Computational region===

{{cmd|g.region|desc=Computational region}} - is an important raster concept in GRASS that needs some explanation. In GRASS a computational region can be set, subsetting larger extent data for quicker testing of analysis or analysis of specific regions based on adminstrative units. We provide a few points to keep in mind when using the computational region function:
* defined by region extent and raster resolution
* applies to all raster operations
* persists between GRASS session, can be different for different mapsets
* advantages: keeps your results consistent, avoid clipping, for computationally demanding tasks set region to smaller extent, check your result is good and then set the computational region to the entire study area and rerun analysis
* run <code>g.region -p</code> or in menu ''Settings'' - ''Region'' - ''Display region'' to see current region settings
[[File:WxGUI set region.png|700px|thumb|center|Simple ways to set computational region from GUI. On the left, set region to match raster map. On the right, select the highlighted option and then set region by drawing rectangle.]]

* GRASS 3D view

= Modeling with FUTURES =
== Initial steps and data preparation ==
First we will set the computational region of our analyses to an extent covering our study area that aligns with our base landuse rasters. ''Like explained in the instructions above, you simply need copy and paste these commands into the command prompt of GRASS''.
<source lang="bash">g.region raster=landuse_2011 -p</source>

The FUTURES model uses the locations of development and new development to predict when and where new urban growth will occur. This requires longitudinal data on urban land use. We will derive urbanized areas from NLCD dataset for year 1992, 2001 and 2011
by extracting categories category 21 - 24 into a new binary map where developed is 1,
undeveloped 0 and NULL (no data). The NULL area is important in simulating urban growth as it preclude these are from becoming development. For this exercise we assume that water, wetlands and protected areas can not be developed, setting them to NULL.
First we will convert protected areas from vector to raster. We set
NULLs to zeros (for simpler raster algebra expression in the next step) using {{cmd|r.null}}:

<source lang="bash">
v.to.rast input=protected_areas output=protected_areas use=val
r.null map=protected_areas null=0
</source>

And then create rasters of developed/undeveloped areas using raster algebra:

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.mapcalc "urban_1992 = if(landuse_1992 >= 21 && landuse_1992 <= 24, 1, if(landuse_1992 == 11 || landuse_1992 >= 90 || protected_areas, null(), 0))"
r.mapcalc "urban_2001 = if(landuse_2001 >= 21 && landuse_2001 <= 24, 1, if(landuse_2001 == 11 || landuse_2001 >= 90 || protected_areas, null(), 0))"
r.mapcalc "urban_2011 = if(landuse_2011 >= 21 && landuse_2011 <= 24, 1, if(landuse_2011 == 11 || landuse_2011 >= 90 || protected_areas, null(), 0))"
</source>

FUTURES is a multi-level modelling framework meaning that we model population projections for subregions and assume that these subregions are influenced differently by the factors that influence where development happens. This requires defining subregions for model implementation. For this exercise we use the county level, which is the finest scale of population data that is available to us. We therefore need to convert vectors of counties to a raster with the values of the FIPS attribute which links to population file:

<source lang="bash">
v.to.rast input=counties type=area use=attr attribute_column=FIPS output=counties
</source>

Before further steps, we will set our working directory so that the input population files and text files
we are going to create are saved in one directory and easily accessible.
You can do that from menu ''Settings'' → ''GRASS working environment'' → ''Change working directory''.
Select (or create) a directory and move there the downloaded files <tt>population_projection.csv</tt> and <tt>population_trend.csv</tt>.

== Potential submodel ==
Module {{AddonCmd|r.futures.potential}} implements the POTENTIAL submodel as a part of FUTURES land change model. POTENTIAL is implemented using a set of coefficients that relate a selection of site suitability factors to the probability of a place becoming developed. This is implemented using the parameter table in combination with maps of those site suitability factors (mapped predictors). The coefficients are obtained by conducting multilevel logistic regression in R with package lme4 where the coefficients may vary by county. The best model is selected automatically using dredge function from package [https://cran.r-project.org/web/packages/MuMIn/index.html MuMIn].

First, we will derive possible predictors of urban growth using GRASS modules.
=== Predictors ===
==== Slope ====
Slope possibly influences urban growth as steep areas are difficult to build on. We will derive slope in degrees from digital elevation model using {{cmd|r.slope.aspect}} module:
<source lang="bash">r.slope.aspect elevation=elevation_30m slope=slope</source>

==== Distance from lakes/rivers ====
Distance to lakes or rivers may contribute to an amenity draw where people would like to build a house in a location where they can view water. First we will extract [http://www.mrlc.gov/nlcd11_leg.php category ''Open Water''] from 2011 NLCD dataset:
<source lang="bash">
r.mapcalc "water = if(landuse_2011 == 11, 1, null())"
</source>

Then we compute the distance to water with module {{cmd|r.grow.distance}} and set color table to shades of blue:
<source lang="bash">
r.grow.distance input=water distance=dist_to_water
r.colors -n map=dist_to_water color=blues
</source>

==== Distance from protected areas ====
Like water protected areas can attract urban growth as people enjoy living near scenic areas. We will use raster protected of protected areas we already created, but we will set NULL values to zero.
We compute the distance to protected areas with module {{cmd|r.grow.distance}} and set color table from green to red:
<source lang="bash">
r.null map=protected_areas setnull=0
r.grow.distance input=protected_areas distance=dist_to_protected
r.colors map=dist_to_protected color=gyr
</source>

==== Forests ====
Forest may influence urban growth in different ways. On the one hand it might be costly for developments as tree will need to be removed. On the other hand, people may want to live near forests. We calculate the percentage forest for a 1 km pixel to test forest influence, see NLCD [http://www.mrlc.gov/nlcd11_leg.php category ''Open Water'']:
<source lang="bash">
r.mapcalc "forest = if(landuse_2011 >= 41 && landuse_2011 <= 43, 1, 0)"
r.neighbors -c input=forest output=forest_smooth size=15 method=average
r.colors map=forest_smooth color=ndvi
</source>

==== Travel time to cities ====
Travel time to urban centers can often play a role in development with access to centers where employment is concentrated. Here we will compute travel time to cities (with population > 5000)
as cumulative cost distance where cost is defined as travel time on roads.
First we specify the speed on different types of roads.
We copy the roads raster into our mapset so that we can change it
by adding a new attribute field <tt>speed</tt>. Then we assign speed values (km/h) based on the type of road:

<source lang="bash">
g.copy vector=roads,myroads
v.db.addcolumn map=myroads columns="speed double precision"
v.db.update map=myroads column=speed value=50 where="MTFCC = 'S1400'"
v.db.update map=myroads column=speed value=100 where="MTFCC IN ('S1100', 'S1200')"
</source>

Now we rasterize the selected road types using the speed values from the attribute table as raster values.

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
v.to.rast input=myroads type=line where="MTFCC IN ('S1100', 'S1200', 'S1400')" output=roads_speed use=attr attribute_column=speed
</source>

We set the rest of the area to low speed and recompute the speed as time to travel through a 30m cell in minutes:

<source lang="bash">
r.null map=roads_speed null=5
r.mapcalc "roads_travel_time = 1.8 / roads_speed"
</source>

Finally we compute the travel time to larger cities using {{cmd|r.cost}}:

<source lang="bash">
r.cost input=roads_travel_time output=travel_time_cities start_points=cities
r.colors map=travel_time_cities color=byr
</source>

==== Road density ====
Dense road construction often occurs in suburban areas where much much development occurs in U.S. cities. To capture this influence we can calculate road density based on the road network. We rasterize roads and use a moving window analysis ({{cmd|r.neighbors}}) to compute road density for a 1 km area:

<source lang="bash">
v.to.rast input=roads output=roads use=val type=line
r.null map=roads null=0
r.neighbors -c input=roads output=road_dens size=25 method=average
</source>

==== Distance to interchanges ====

In the U.S. urban development often is clustered around interchanges as this provides easy access on transportation networks. To calculate this influence we will use the TIGER road database of type <tt>Ramp</tt> as interchanges, rasterize them and compute euclidean distance to them:

<source lang="bash">
v.to.rast input=roads type=line where="MTFCC = 'S1630'" output=interchanges use=val
r.grow.distance -m input=interchanges distance=dist_interchanges
</source>

=== Development pressure ===

Development pressure is an important variable in the FUTURES model that is always include as a dynamic variable reinforcing the pressure of past development. We assume that urban development in one location will increase the chance of development in near proximity. New simulated development is incorporated into calculating this development pressure every time step that FUTURES simulates urban growth. To estimate the influence that this local development pressure has, we include the development pressure {{AddonCmd|r.futures.devpressure}} in our initial model estimates. Development pressure is based on number of neighboring developed cells within a specified search distance, weighted by distance. Its special role in the model allows for path dependent feedback between predicted change and change in subsequent steps.

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.devpressure -n input=urban_2011 output=devpressure_2 method=gravity size=7 gamma=2 scaling_factor=10
r.futures.devpressure -n input=urban_2011 output=devpressure_1 method=gravity size=10 gamma=1 scaling_factor=1
r.futures.devpressure -n input=urban_2011 output=devpressure_0_5 method=gravity size=30 gamma=0.5 scaling_factor=0.1
</source>

When gamma increases, development influence decreases more rapidly with distance.
Size is half the size of the moving window. When gamma is low, local development influences more distant places.
We will derive 3 layers with different gamma and size parameters for the potential statistical model.

=== Rescaling variables ===

First we will look at the ranges of our predictor variables by running a short Python code snippet in Python shell:

<source lang="python" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
for name in ['slope', 'dist_to_water', 'dist_to_protected', 'forest_smooth', 'travel_time_cities', 'road_dens', 'dist_interchanges', 'devpressure_0_5', 'devpressure_1']:
minmax = grass.raster_info(name)
print name, minmax['min'], minmax['max']
</source>

We will rescale some of our input variables:

<source lang="bash">
r.mapcalc "dist_to_water_km = dist_to_water / 1000"
r.mapcalc "dist_to_protected_km = dist_to_protected / 1000"
r.mapcalc "dist_interchanges_km = dist_interchanges / 1000"
r.mapcalc "road_dens_perc = road_dens * 100"
r.mapcalc "forest_smooth_perc = forest_smooth * 100"
</source>

=== Sampling ===
To sample only in the analyzed counties, we will clip development layer:

<source lang="bash">
r.mapcalc "urban_change_01_11 = if(urban_2011 == 1, if(urban_2001 == 0, 1, null()), 0)"
r.mapcalc "urban_change_clip = if(counties, urban_change_01_11)"
</source>

To estimate the number of sampling points, we can use {{cmd|r.report}} to report number of developed/undeveloped cells and their ratio.

<source lang="bash">
r.report map=urban_change_clip units=h,c,p
</source>

We will sample the predictors and the response variable with 5000 random points in undeveloped areas and 1000 points in developed area:

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.sample.category input=urban_change_clip output=sampling sampled=counties,devpressure_0_5,devpressure_1,devpressure_2,slope,road_dens_perc,forest_smooth_perc,dist_to_water_km,dist_to_protected_km,dist_interchanges_km,travel_time_cities npoints=5000,1000
</source>

The attribute table can be exported as CSV file (not necessary step):

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
v.db.select map=sampling columns=urban_change_clip,counties,devpressure_0_5,devpressure_1,slope,road_dens_perc,forest_smooth_perc,dist_to_water_km,dist_to_protected_km,dist_interchanges_km,travel_time_cities separator=comma file=samples.csv
</source>

=== Development potential ===
Now we find best model for predicting urbanization using {{AddonCmd|r.futures.potential}} which wraps an R script.

We can run R [http://www.inside-r.org/packages/cran/MuMIn/docs/dredge dredge] function to find "best" model. We can specify minimum and maximum number of predictors the final model should use.
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.potential -d input=sampling output=potential.csv columns=devpressure_1,slope,road_dens_perc,forest_smooth_perc,dist_to_water_km,dist_to_protected_km,dist_interchanges_km,travel_time_cities developed_column=urban_change_clip subregions_column=counties min_variables=4
</source>

Also, we can play with different combinations of predictors, for example:

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.potential input=sampling output=potential.csv columns=devpressure_2,road_dens_perc,slope,dist_interchanges_km,dist_to_water_km developed_column=urban_change_clip subregions_column=counties --o
r.futures.potential input=sampling output=potential.csv columns=devpressure_1,road_dens_perc,slope,dist_interchanges_km,dist_to_water_km developed_column=urban_change_clip subregions_column=counties --o
...
</source>

You can then open the output file <tt>potential.csv</tt>, which is a CSV file with tabs as separators.

For this tutorial, the final potential is created with:
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.potential input=sampling output=potential.csv columns=devpressure_2,road_dens_perc,slope,dist_interchanges_km,dist_to_water_km developed_column=urban_change_clip subregions_column=counties --o
</source>

We can now visualize the suitability surface using module {{AddonCmd|r.futures.potsurface}}. It creates initial development potential (suitability) raster from predictors and model coefficients and serves only for evaluating development potential model. The values of the resulting raster range from 0 to 1.

<source lang="bash">
r.futures.potsurface input=potential.csv subregions=counties output=suitability
r.colors map=suitability color=byr
</source>

== Demand submodel ==
First we will mask out roads so that they don't influence into per capita land demand relation.
<source lang="bash">
v.to.rast input=roads type=line output=roads_mask use=val
r.mask roads_mask -i
</source>

We will use {{AddonCmd|r.futures.demand}} which derives the population vs. development relation. The relation can be linear/logarithmic/logarithmic2/exponential/exponential approach.
Look for examples of the different relations in the manual.

* linear: y = A + Bx
* logarithmic: y = A + Bln(x)
* logarithmic2: y = A + B * ln(x - C)        (requires SciPy)
* exponential: y = Ae^(BX)
* exp_approach: y = (1 - e^(-A(x - B))) + C        (requires SciPy)

The format of the input population CSV files is described in the manual. It is important to have synchronized categories of subregions and the column headers of the CSV files (in our case FIPS number). How to simply generate the list of years (for which demand is computed) is described in {{AddonCmd|r.futures.demand}} manual, for example run this in Python console:

<source lang="python">
','.join([str(i) for i in range(2011, 2036)])
</source>

Then we can create the DEMAND file:
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.demand development=urban_1992,urban_2001,urban_2011 subregions=counties observed_population=population_trend.csv projected_population=population_projection.csv simulation_times=2011,2012,2013,2014,2015,2016,2017,2018,2019,2020,2021,2022,2023,2024,2025,2026,2027,2028,2029,2030,2031,2032,2033,2034,2035 plot=plot_demand.pdf demand=demand.csv separator=comma
</source>

In your current working directory, you should find files <tt>plot_demand.png</tt> and <tt>demand.csv</tt>.

If you have SciPy installed, you can experiment with other methods for fitting the functions:
<source lang="bash">
r.futures.demand ... method=logarithmic2
r.futures.demand ... method=exp_approach
</source>
If necessary, you can create a set of demand files produced by fitting each method separately and
then pick for each county the method which seems best and manually create a new demand file.

When you are finished, remove the mask as it is not needed for the next steps.
<source lang="bash">
r.mask -r
</source>

== Patch calibration ==
Patch calibration can be a very time consuming computation.
Therefore we select only one county (Buncombe):

<source lang="bash">
v.to.rast input=counties type=area where="FIPS == 37021" use=attr attribute_column=FIPS output=calib_county
g.region raster=calib_county zoom=calib_county
</source>
to derive patches of new development by comparing historical and latest development.
We can keep only patches with minimum size 2 cells (1800 = 2 x 30 x 30 m).

<source lang="bash">
r.futures.calib development_start=urban_1992 development_end=urban_2011 subregions=counties patch_sizes=patches.txt patch_threshold=1800 -l
</source>
We obtained a file <tt>patches.txt</tt> (used later in the PGA) - a patch size distribution file - containing sizes of all found patches.

We can look at the distribution of the patch sizes:

<source lang="python">
from matplotlib import pyplot as plt
with open('patches.txt') as f:
patches = [int(patch) for patch in f.readlines()]
plt.hist(patches, 2000)
plt.xlim(0,50)
plt.show()
</source>

At this point, we start the calibration to get best parameters of patch shape
(for this tutorial, this step can be skipped and the suggested parameters are used).

<source lang="bash"
style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.calib development_start=urban_1992 development_end=urban_2011 subregions=calib_county patch_sizes=patches.txt calibration_results=calib.csv patch_threshold=1800 repeat=5 compactness_mean=0.1,0.3,0.5,0.7,0.9 compactness_range=0.05 discount_factor=0.1,0.3,0.5,0.7,0.9 predictors=road_dens_perc,forest_smooth_perc,dist_to_protected_km demand=demand.csv devpot_params=potential.csv num_neighbors=4 seed_search=2 development_pressure=devpressure_0_5 development_pressure_approach=gravity n_dev_neighbourhood=30 gamma=0.5 scaling_factor=0.1
</source>

== FUTURES simulation ==
We will switch back to our previous region:
<source lang="bash">
g.region raster=landuse_2011 -p
</source>

Now we have all the inputs necessary for running {{AddonCmd|r.futures.pga}}:

The entire command is here:
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.pga subregions=counties developed=urban_2011 predictors=slope,forest_smooth_perc,dist_interchanges_km,travel_time_cities devpot_params=potential.csv development_pressure=devpressure_1 n_dev_neighbourhood=10 development_pressure_approach=gravity gamma=1 scaling_factor=1 demand=demand.csv discount_factor=0.3 compactness_mean=0.2 compactness_range=0.1 patch_sizes=patches.txt num_neighbors=4 seed_search=2 random_seed=1 output=final output_series=final
</source>

=== Quick description ===
The command parameters and their values:
* raster map of counties with their categories
<code>
... subregions=counties ...
</code>

* raster of developed (1), undeveloped (0) and NULLs for undevelopable areas
<code>
... developed=urban_2011 ...
</code>

* predictors selected with {{AddonCmd|r.futures.potential}} and their coefficients in a <tt>potential.csv</tt> file. The order of predictors must match the order in the file and the categories of the counties must match raster <tt>counties</tt>.
<code>
... predictors=slope,forest_smooth_perc,dist_interchanges_km,travel_time_cities devpot_params=potential.csv ...
</code>

* initial development pressure computed by {{AddonCmd|r.futures.devpressure}}, it's important to set here the same parameters
<code>
... development_pressure=devpressure_1 n_dev_neighbourhood=10 development_pressure_approach=gravity gamma=1 scaling_factor=1 ...
</code>

* per capita land demand computed by {{AddonCmd|r.futures.demand}}, the categories of the counties must match raster <tt>counties</tt>.
<code>
... demand=demand.csv ...
</code>

* patch parameters from the calibration step
<code>
... discount_factor=0.3 compactness_mean=0.4 compactness_range=0.08 patch_sizes=patches.txt ...
</code>

* recommended parameters for patch growing algorithm
<code>
... num_neighbors=4 seed_search=2 ...
</code>

* set random seed for repeatable results or set flag <tt>-s</tt> to generate seed automatically
<code>
... random_seed=1 ...
</code>

* specify final output map and optionally basename for intermediate raster maps
<code>
output=final output_series=final
</code>

== Scenarios ==
Scenarios involving policies that encourage infill versus sprawl can be explored using the <tt>incentive_power</tt> parameter of {{AddonCmd|r.futures.pga}},
which uses a power function to transform the evenness of the probability gradient in POTENTIAL. You can change the power to a number between 0.25 and 4 to test urban sprawl/infill scenarios.
Higher power leads to infill behavior, lower power to urban sprawl.

== Postprocessing ==

Follow a [[Creating_animation_from_FUTURES_output_in_GRASS_GIS| tutorial how to make an animation from the results]].

= GRASS GIS Python API =

[[Category: Tutorial]]
[[Category: FUTURES]]
[[Category: Urban]]

Workshop on urban growth modeling with FUTURES

2016-03-22T22:01:48Z

⚠️Dbvanber: /* Distance to interchanges */

{{ToModify}}
= Workshop introduction =
r.futures.* is an implementation of the '''FUT'''ure '''U'''rban-'''R'''egional '''E'''nvironment '''S'''imulation (FUTURES)[1] which is a model for multilevel simulations of emerging urban-rural landscape structure. FUTURES produces regional projections of landscape patterns using coupled submodels that integrate nonstationary drivers of land change: per capita demand (DEMAND submodel), site suitability (POTENTIAL submodel), and the spatial structure of conversion events (PGA submodel).

[1] Meentemeyer, R. K., Tang, W., Dorning, M. A., Vogler, J. B., Cunniffe, N. J., & Shoemaker, D. A. (2013). [http://www.tandfonline.com/doi/abs/10.1080/00045608.2012.707591 FUTURES: multilevel simulations of emerging urban-rural landscape structure using a stochastic patch-growing algorithm.] Annals of the Association of American Geographers, 103(4), 785-807

== Software ==
There are a number of software requirements to run FUTURES that will need to be download and installed. Required software includes:
* GRASS GIS 7
* addons
** {{AddonCmd|r.futures.pga}}
** {{AddonCmd|r.futures.potential}}
** {{AddonCmd|r.futures.potsurface}}
** {{AddonCmd|r.futures.demand}}
** {{AddonCmd|r.futures.devpressure}}
** {{AddonCmd|r.sample.category}}
* R (≥ 3.0.2) - needed for {{AddonCmd|r.futures.potential}} with packages:
**MuMIn, lme4, optparse, rgrass7
* SciPy - useful for {{AddonCmd|r.futures.demand}}

=== Installation ===
We use the R statistical software for our calculation of site suitability (i.e. development potential) in FUTURES. R is a free software environment for statistical computing and graphics. If you don't have R, or you have older an version, please download and install the software from [http://archive.linux.duke.edu/cran/ install R] and be sure to additionally add these required packages:
<pre>
install.packages(c("MuMIn", "lme4", "optparse", "rgrass7"))
</pre>

==== MS Windows ====
We will be using GRASS GIS 7.0.3 that can be found here in the [https://trac.osgeo.org/osgeo4w/ OSGeo4W] package manager.
Please install the latest stable GRASS GIS 7 version and the SciPy Python package using the ''Advanced install'' option.
A guide with step by step screen shot instructions is available [https://docs.google.com/presentation/d/1yEGpriBne7RvjB35HI6GecNwO1P1y2nRGqDThqoNnCE/edit?usp=sharing here].

In order for GRASS to be able to find R executables, GRASS must be on the PATH variable. Follow this [solution] to make R accessible from GRASS permanently.
A simple but temporary solution is to open GRASS GIS and paste this in the black terminal:
<pre>
set PATH=%PATH%;C:\Program Files\R\R-3.0.2\bin
</pre>
This has to be repeated after restarting GRASS session.

==== Ubuntu Linux ====
Install GRASS GIS from packages:
<pre>
sudo add-apt-repository ppa:ubuntugis/ubuntugis-unstable
sudo apt-get update
sudo apt-get install grass
</pre>

== Workshop data ==
The data that we will be using for the workshop can be download here: [http://fatra.cnr.ncsu.edu/futures/futures_ncspm_Asheville.zip sample dataset]. Please place these layers in your local GRASS directory:
* digital elevation model ([http://nationalmap.gov/elevation.html NED])
* [http://www.mrlc.gov/ NLCD] 2001, 2011
* NLCD 1992/2001 Retrofit Land Cover Change Product
* transportation network ([http://www.census.gov/geo/maps-data/data/tiger-line.html TIGER])
* county boundaries ([http://www.census.gov/geo/maps-data/data/tiger-line.html TIGER])
* protected areas ([http://www.conservationgateway.org/ConservationByGeography/NorthAmerica/UnitedStates/edc/reportsdata/terrestrial/secured/Pages/default.aspx Secured Lands])
* cities as points (USGS)

In addition, download [http://fatra.cnr.ncsu.edu/futures/futures_Asheville_files.zip population information as text files]:
* county population past estimates and future projections ([https://www.osbm.nc.gov/demog/county-projections NC OSBM]) per county (nonspatial)

= GRASS GIS introduction =
There are many advantages to using the open source GRASS GIS platform, but for many that are more familiar with ARCGis and QGis, the setup and implementation of spatial tools in GRASS can be confusing. Here we provide an overview of the GRASS GIS project: [https://grass.osgeo.org grass.osgeo.org] that might be helpful to review if you are a first time users. For this exercise it's not necessary to have a full understanding of how to use GRASS. However, you will need to know how to place your data in the correct GRASS database directory, as well as some basic GRASS functionality. Step by step instructions are provided below
== Setting up GRASS for the tutorial ==
GRASS uses unique database terminology and structure ([https://grass.osgeo.org/grass71/manuals/grass_database.html GRASS database]) that are important to understand for the set up of this tutorial, as you will need to place the required data (e.g. Mapset) in a specific GRASS database Location. In the following we review important terminology and give step by step direction on how to download and place you data in the correct location.

=== Important GRASS directory terminology ===
* A '''GRASS database''' consist of directory with specific Locations (projects) where data layer are stored
* '''Location''' hold all Mapsets in a specific directoy that have the same spatial projection (spatial reference system)
* '''Mapset''' are a collection of maps with the same spatial projection

=== Creating a GRASS database for the tutorial ===
You need to create a GRASS database with the Mapset that we will use for the tutorial before we can run the FUTURES model. Please Download the [http://fatra.cnr.ncsu.edu/futures/futures_ncspm_Asheville.zip workshop location], noting where the files are located on your local directory. Now, create (unless you already have it) a directory named <tt>grassdata</tt> (GRASS database) in your home folder (or Documents), unzip the downloaded data into this directory. You should now have a Location <tt>futures_ncspm</tt> in <tt>grassdata</tt>.

<center><gallery perrow=1 widths=500 heights=250>Image:GRASS FUTURES startup.png|GRASS GIS 7.0.3 startup dialog with downloaded Location and Mapsets for FUTURES workshop</gallery></center>

=== Launching and exploring data in GRASS ===
Now that we have the data in the correct GRASS database, we can launch the Graphical User Interface (GUI). The GUI interface allows you to display raster, vector data as well as navigate through zooming in and out. Advanced exploration and visualization, like many popular GIS software, is also possible in GRASS (e.g. queries, adding legend). The print screens below depicts how you can add different map layers (left) and display the metadata of your data layers.

<center><gallery perrow=2 widths=500 heights=250>Image:GRASS FUTURES wxGUI display.png|Layer Manager and Map Display overview. Annotations show how to add raster layer, query, add legend.
Image:wxGUI_metadata_rinfo.png|Show raster map metadata by right click on layer</gallery></center>

== GRASS functionality ==
One of the advantage of GRASS is the diversity and number of module addons that let you analyze all manner of spatial and temporal. Because it is open source modules are added daily increasing functionality and methods for analysis of your data. GRASS GIS has over [https://grass.osgeo.org/grass70/manuals/full_index.html 500 different modules] in the core distribution and over [https://grass.osgeo.org/grass70/manuals/addons/ 230 addon modules] that can be used to prepare and analyze data layers.
<center>
{| class="wikitable"
|-
! Prefix !! Function !! Example
|-
| r.* || raster processing || ''{{cmd|r.mapcalc}}'': map algebra
|-
| v.* || vector processing || ''{{cmd|v.clean}}'': topological cleaning
|-
| i.* || imagery processing || ''{{cmd|i.segment}}'': object recognition
|-
| db.* || database management || ''{{cmd|db.select}}'': select values from table
|-
| r3.* || 3D raster processing || ''{{cmd|r3.stats}}'': 3D raster statistics
|-
| t.* || temporal data processing || ''{{cmd|t.rast.aggregate}}'': temporal aggregation
|-
| g.* || general data management || ''{{cmd|g.rename}}'': renames map
|-
| d.* || display ||''{{cmd|d.rast}}'': display raster map
|}</center>

=== Command line vs. GUI interface===
GRASS modules can be executed either through a GUI or command line interface. The GUI offers a user-friendly approach to executing modules where the user can navigate to data layers that they would like to analyze and modify processing options with simple check boxes. The GUI also offer a easily accessible manual on how to execute a model. The command line interface allows users to execute a module using command prompts specific to that module. This is handy when you are running similar analyses with minor modification or are familiar with the module commands for quick efficient processing. In this workshop we provide module prompts that can be copy and pasted into the command line for our workflow, but you can use both GUI and command line depending on personal preference. Look how {{cmd|wxGUI.modules|version=71|desc=GUI and command line interface}} represent the same tool. ''Task:'' compute aspect (orientation) from provided digital elevation model using module {{cmd|r.slope.aspect}} using both module dialog and command line.
* How to find modules? Modules are organized by their functionality in wxGUI menu, or we can search for them in Search modules tab. If we already know which module to use, we can just type it in the wxGUI command console. <center><gallery perrow=3 widths=380 heights=190>Image:wxGUI_menu_rinfo.png|Modules can be found in wxGUI menu
Image:wxGUI_module_search.png|You can search modules by name, description or keywords in ''Search modules'' tab
Image:wxGUI_console_completion.png|By typing prefix r. we make a list of modules starting with that prefix to show up.</gallery></center>

=== Computational region===

{{cmd|g.region|desc=Computational region}} - is an important raster concept in GRASS that needs some explanation. In GRASS a computational region can be set, subsetting larger extent data for quicker testing of analysis or analysis of specific regions based on adminstrative units. We provide a few points to keep in mind when using the computational region function:
* defined by region extent and raster resolution
* applies to all raster operations
* persists between GRASS session, can be different for different mapsets
* advantages: keeps your results consistent, avoid clipping, for computationally demanding tasks set region to smaller extent, check your result is good and then set the computational region to the entire study area and rerun analysis
* run <code>g.region -p</code> or in menu ''Settings'' - ''Region'' - ''Display region'' to see current region settings
[[File:WxGUI set region.png|700px|thumb|center|Simple ways to set computational region from GUI. On the left, set region to match raster map. On the right, select the highlighted option and then set region by drawing rectangle.]]

* GRASS 3D view

= Modeling with FUTURES =
== Initial steps and data preparation ==
First we will set the computational region of our analyses to an extent covering our study area that aligns with our base landuse rasters. ''Like explained in the instructions above, you simply need copy and paste these commands into the command prompt of GRASS''.
<source lang="bash">g.region raster=landuse_2011 -p</source>

The FUTURES model uses the locations of development and new development to predict when and where new urban growth will occur. This requires longitudinal data on urban land use. We will derive urbanized areas from NLCD dataset for year 1992, 2001 and 2011
by extracting categories category 21 - 24 into a new binary map where developed is 1,
undeveloped 0 and NULL (no data). The NULL area is important in simulating urban growth as it preclude these are from becoming development. For this exercise we assume that water, wetlands and protected areas can not be developed, setting them to NULL.
First we will convert protected areas from vector to raster. We set
NULLs to zeros (for simpler raster algebra expression in the next step) using {{cmd|r.null}}:

<source lang="bash">
v.to.rast input=protected_areas output=protected_areas use=val
r.null map=protected_areas null=0
</source>

And then create rasters of developed/undeveloped areas using raster algebra:

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.mapcalc "urban_1992 = if(landuse_1992 >= 21 && landuse_1992 <= 24, 1, if(landuse_1992 == 11 || landuse_1992 >= 90 || protected_areas, null(), 0))"
r.mapcalc "urban_2001 = if(landuse_2001 >= 21 && landuse_2001 <= 24, 1, if(landuse_2001 == 11 || landuse_2001 >= 90 || protected_areas, null(), 0))"
r.mapcalc "urban_2011 = if(landuse_2011 >= 21 && landuse_2011 <= 24, 1, if(landuse_2011 == 11 || landuse_2011 >= 90 || protected_areas, null(), 0))"
</source>

FUTURES is a multi-level modelling framework meaning that we model population projections for subregions and assume that these subregions are influenced differently by the factors that influence where development happens. This requires defining subregions for model implementation. For this exercise we use the county level, which is the finest scale of population data that is available to us. We therefore need to convert vectors of counties to a raster with the values of the FIPS attribute which links to population file:

<source lang="bash">
v.to.rast input=counties type=area use=attr attribute_column=FIPS output=counties
</source>

Before further steps, we will set our working directory so that the input population files and text files
we are going to create are saved in one directory and easily accessible.
You can do that from menu ''Settings'' → ''GRASS working environment'' → ''Change working directory''.
Select (or create) a directory and move there the downloaded files <tt>population_projection.csv</tt> and <tt>population_trend.csv</tt>.

== Potential submodel ==
Module {{AddonCmd|r.futures.potential}} implements the POTENTIAL submodel as a part of FUTURES land change model. POTENTIAL is implemented using a set of coefficients that relate a selection of site suitability factors to the probability of a place becoming developed. This is implemented using the parameter table in combination with maps of those site suitability factors (mapped predictors). The coefficients are obtained by conducting multilevel logistic regression in R with package lme4 where the coefficients may vary by county. The best model is selected automatically using dredge function from package [https://cran.r-project.org/web/packages/MuMIn/index.html MuMIn].

First, we will derive possible predictors of urban growth using GRASS modules.
=== Predictors ===
==== Slope ====
Slope possibly influences urban growth as steep areas are difficult to build on. We will derive slope in degrees from digital elevation model using {{cmd|r.slope.aspect}} module:
<source lang="bash">r.slope.aspect elevation=elevation_30m slope=slope</source>

==== Distance from lakes/rivers ====
Distance to lakes or rivers may contribute to an amenity draw where people would like to build a house in a location where they can view water. First we will extract [http://www.mrlc.gov/nlcd11_leg.php category ''Open Water''] from 2011 NLCD dataset:
<source lang="bash">
r.mapcalc "water = if(landuse_2011 == 11, 1, null())"
</source>

Then we compute the distance to water with module {{cmd|r.grow.distance}} and set color table to shades of blue:
<source lang="bash">
r.grow.distance input=water distance=dist_to_water
r.colors -n map=dist_to_water color=blues
</source>

==== Distance from protected areas ====
Like water protected areas can attract urban growth as people enjoy living near scenic areas. We will use raster protected of protected areas we already created, but we will set NULL values to zero.
We compute the distance to protected areas with module {{cmd|r.grow.distance}} and set color table from green to red:
<source lang="bash">
r.null map=protected_areas setnull=0
r.grow.distance input=protected_areas distance=dist_to_protected
r.colors map=dist_to_protected color=gyr
</source>

==== Forests ====
Forest may influence urban growth in different ways. On the one hand it might be costly for developments as tree will need to be removed. On the other hand, people may want to live near forests. We calculate the percentage forest for a 1 km pixel to test forest influence, see NLCD [http://www.mrlc.gov/nlcd11_leg.php category ''Open Water'']:
<source lang="bash">
r.mapcalc "forest = if(landuse_2011 >= 41 && landuse_2011 <= 43, 1, 0)"
r.neighbors -c input=forest output=forest_smooth size=15 method=average
r.colors map=forest_smooth color=ndvi
</source>

==== Travel time to cities ====
Travel time to urban centers can often play a role in development with access to centers where employment is concentrated. Here we will compute travel time to cities (with population > 5000)
as cumulative cost distance where cost is defined as travel time on roads.
First we specify the speed on different types of roads.
We copy the roads raster into our mapset so that we can change it
by adding a new attribute field <tt>speed</tt>. Then we assign speed values (km/h) based on the type of road:

<source lang="bash">
g.copy vector=roads,myroads
v.db.addcolumn map=myroads columns="speed double precision"
v.db.update map=myroads column=speed value=50 where="MTFCC = 'S1400'"
v.db.update map=myroads column=speed value=100 where="MTFCC IN ('S1100', 'S1200')"
</source>

Now we rasterize the selected road types using the speed values from the attribute table as raster values.

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
v.to.rast input=myroads type=line where="MTFCC IN ('S1100', 'S1200', 'S1400')" output=roads_speed use=attr attribute_column=speed
</source>

We set the rest of the area to low speed and recompute the speed as time to travel through a 30m cell in minutes:

<source lang="bash">
r.null map=roads_speed null=5
r.mapcalc "roads_travel_time = 1.8 / roads_speed"
</source>

Finally we compute the travel time to larger cities using {{cmd|r.cost}}:

<source lang="bash">
r.cost input=roads_travel_time output=travel_time_cities start_points=cities
r.colors map=travel_time_cities color=byr
</source>

==== Road density ====
Dense road construction often occurs in suburban areas where much much development occurs in U.S. cities. To capture this influence we can calculate road density based on the road network. We rasterize roads and use a moving window analysis ({{cmd|r.neighbors}}) to compute road density for a 1 km area:

<source lang="bash">
v.to.rast input=roads output=roads use=val type=line
r.null map=roads null=0
r.neighbors -c input=roads output=road_dens size=25 method=average
</source>

==== Distance to interchanges ====

In the U.S. urban development often is clustered around interchanges as this provides easy access on transportation networks. To calculate this influence we will use the TIGER road database of type <tt>Ramp</tt> as interchanges, rasterize them and compute euclidean distance to them:

<source lang="bash">
v.to.rast input=roads type=line where="MTFCC = 'S1630'" output=interchanges use=val
r.grow.distance -m input=interchanges distance=dist_interchanges
</source>

=== Development pressure ===

We compute development pressure with {{AddonCmd|r.futures.devpressure}}. Development pressure is a predictor based on number of neighboring developed cells within search distance, weighted by distance. The development pressure variable plays a special role in the model, allowing for a feedback between predicted change and change in subsequent steps.

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.devpressure -n input=urban_2011 output=devpressure_2 method=gravity size=7 gamma=2 scaling_factor=10
r.futures.devpressure -n input=urban_2011 output=devpressure_1 method=gravity size=10 gamma=1 scaling_factor=1
r.futures.devpressure -n input=urban_2011 output=devpressure_0_5 method=gravity size=30 gamma=0.5 scaling_factor=0.1
</source>

When gamma increases, development influence decreases more rapidly with distance.
Size is half the size of the moving window. When gamma is low, local development influences more distant places.
We will derive 3 layers with different gamma and size parameters for the potential statistical model.

=== Rescaling variables ===

First we will look at the ranges of our predictor variables by running a short Python code snippet in Python shell:

<source lang="python" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
for name in ['slope', 'dist_to_water', 'dist_to_protected', 'forest_smooth', 'travel_time_cities', 'road_dens', 'dist_interchanges', 'devpressure_0_5', 'devpressure_1']:
minmax = grass.raster_info(name)
print name, minmax['min'], minmax['max']
</source>

We will rescale some of our input variables:

<source lang="bash">
r.mapcalc "dist_to_water_km = dist_to_water / 1000"
r.mapcalc "dist_to_protected_km = dist_to_protected / 1000"
r.mapcalc "dist_interchanges_km = dist_interchanges / 1000"
r.mapcalc "road_dens_perc = road_dens * 100"
r.mapcalc "forest_smooth_perc = forest_smooth * 100"
</source>

=== Sampling ===
To sample only in the analyzed counties, we will clip development layer:

<source lang="bash">
r.mapcalc "urban_change_01_11 = if(urban_2011 == 1, if(urban_2001 == 0, 1, null()), 0)"
r.mapcalc "urban_change_clip = if(counties, urban_change_01_11)"
</source>

To estimate the number of sampling points, we can use {{cmd|r.report}} to report number of developed/undeveloped cells and their ratio.

<source lang="bash">
r.report map=urban_change_clip units=h,c,p
</source>

We will sample the predictors and the response variable with 5000 random points in undeveloped areas and 1000 points in developed area:

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.sample.category input=urban_change_clip output=sampling sampled=counties,devpressure_0_5,devpressure_1,devpressure_2,slope,road_dens_perc,forest_smooth_perc,dist_to_water_km,dist_to_protected_km,dist_interchanges_km,travel_time_cities npoints=5000,1000
</source>

The attribute table can be exported as CSV file (not necessary step):

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
v.db.select map=sampling columns=urban_change_clip,counties,devpressure_0_5,devpressure_1,slope,road_dens_perc,forest_smooth_perc,dist_to_water_km,dist_to_protected_km,dist_interchanges_km,travel_time_cities separator=comma file=samples.csv
</source>

=== Development potential ===
Now we find best model for predicting urbanization using {{AddonCmd|r.futures.potential}} which wraps an R script.

We can run R [http://www.inside-r.org/packages/cran/MuMIn/docs/dredge dredge] function to find "best" model. We can specify minimum and maximum number of predictors the final model should use.
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.potential -d input=sampling output=potential.csv columns=devpressure_1,slope,road_dens_perc,forest_smooth_perc,dist_to_water_km,dist_to_protected_km,dist_interchanges_km,travel_time_cities developed_column=urban_change_clip subregions_column=counties min_variables=4
</source>

Also, we can play with different combinations of predictors, for example:

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.potential input=sampling output=potential.csv columns=devpressure_2,road_dens_perc,slope,dist_interchanges_km,dist_to_water_km developed_column=urban_change_clip subregions_column=counties --o
r.futures.potential input=sampling output=potential.csv columns=devpressure_1,road_dens_perc,slope,dist_interchanges_km,dist_to_water_km developed_column=urban_change_clip subregions_column=counties --o
...
</source>

You can then open the output file <tt>potential.csv</tt>, which is a CSV file with tabs as separators.

For this tutorial, the final potential is created with:
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.potential input=sampling output=potential.csv columns=devpressure_2,road_dens_perc,slope,dist_interchanges_km,dist_to_water_km developed_column=urban_change_clip subregions_column=counties --o
</source>

We can now visualize the suitability surface using module {{AddonCmd|r.futures.potsurface}}. It creates initial development potential (suitability) raster from predictors and model coefficients and serves only for evaluating development potential model. The values of the resulting raster range from 0 to 1.

<source lang="bash">
r.futures.potsurface input=potential.csv subregions=counties output=suitability
r.colors map=suitability color=byr
</source>

== Demand submodel ==
First we will mask out roads so that they don't influence into per capita land demand relation.
<source lang="bash">
v.to.rast input=roads type=line output=roads_mask use=val
r.mask roads_mask -i
</source>

We will use {{AddonCmd|r.futures.demand}} which derives the population vs. development relation. The relation can be linear/logarithmic/logarithmic2/exponential/exponential approach.
Look for examples of the different relations in the manual.

* linear: y = A + Bx
* logarithmic: y = A + Bln(x)
* logarithmic2: y = A + B * ln(x - C)        (requires SciPy)
* exponential: y = Ae^(BX)
* exp_approach: y = (1 - e^(-A(x - B))) + C        (requires SciPy)

The format of the input population CSV files is described in the manual. It is important to have synchronized categories of subregions and the column headers of the CSV files (in our case FIPS number). How to simply generate the list of years (for which demand is computed) is described in {{AddonCmd|r.futures.demand}} manual, for example run this in Python console:

<source lang="python">
','.join([str(i) for i in range(2011, 2036)])
</source>

Then we can create the DEMAND file:
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.demand development=urban_1992,urban_2001,urban_2011 subregions=counties observed_population=population_trend.csv projected_population=population_projection.csv simulation_times=2011,2012,2013,2014,2015,2016,2017,2018,2019,2020,2021,2022,2023,2024,2025,2026,2027,2028,2029,2030,2031,2032,2033,2034,2035 plot=plot_demand.pdf demand=demand.csv separator=comma
</source>

In your current working directory, you should find files <tt>plot_demand.png</tt> and <tt>demand.csv</tt>.

If you have SciPy installed, you can experiment with other methods for fitting the functions:
<source lang="bash">
r.futures.demand ... method=logarithmic2
r.futures.demand ... method=exp_approach
</source>
If necessary, you can create a set of demand files produced by fitting each method separately and
then pick for each county the method which seems best and manually create a new demand file.

When you are finished, remove the mask as it is not needed for the next steps.
<source lang="bash">
r.mask -r
</source>

== Patch calibration ==
Patch calibration can be a very time consuming computation.
Therefore we select only one county (Buncombe):

<source lang="bash">
v.to.rast input=counties type=area where="FIPS == 37021" use=attr attribute_column=FIPS output=calib_county
g.region raster=calib_county zoom=calib_county
</source>
to derive patches of new development by comparing historical and latest development.
We can keep only patches with minimum size 2 cells (1800 = 2 x 30 x 30 m).

<source lang="bash">
r.futures.calib development_start=urban_1992 development_end=urban_2011 subregions=counties patch_sizes=patches.txt patch_threshold=1800 -l
</source>
We obtained a file <tt>patches.txt</tt> (used later in the PGA) - a patch size distribution file - containing sizes of all found patches.

We can look at the distribution of the patch sizes:

<source lang="python">
from matplotlib import pyplot as plt
with open('patches.txt') as f:
patches = [int(patch) for patch in f.readlines()]
plt.hist(patches, 2000)
plt.xlim(0,50)
plt.show()
</source>

At this point, we start the calibration to get best parameters of patch shape
(for this tutorial, this step can be skipped and the suggested parameters are used).

<source lang="bash"
style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.calib development_start=urban_1992 development_end=urban_2011 subregions=calib_county patch_sizes=patches.txt calibration_results=calib.csv patch_threshold=1800 repeat=5 compactness_mean=0.1,0.3,0.5,0.7,0.9 compactness_range=0.05 discount_factor=0.1,0.3,0.5,0.7,0.9 predictors=road_dens_perc,forest_smooth_perc,dist_to_protected_km demand=demand.csv devpot_params=potential.csv num_neighbors=4 seed_search=2 development_pressure=devpressure_0_5 development_pressure_approach=gravity n_dev_neighbourhood=30 gamma=0.5 scaling_factor=0.1
</source>

== FUTURES simulation ==
We will switch back to our previous region:
<source lang="bash">
g.region raster=landuse_2011 -p
</source>

Now we have all the inputs necessary for running {{AddonCmd|r.futures.pga}}:

The entire command is here:
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.pga subregions=counties developed=urban_2011 predictors=slope,forest_smooth_perc,dist_interchanges_km,travel_time_cities devpot_params=potential.csv development_pressure=devpressure_1 n_dev_neighbourhood=10 development_pressure_approach=gravity gamma=1 scaling_factor=1 demand=demand.csv discount_factor=0.3 compactness_mean=0.2 compactness_range=0.1 patch_sizes=patches.txt num_neighbors=4 seed_search=2 random_seed=1 output=final output_series=final
</source>

=== Quick description ===
The command parameters and their values:
* raster map of counties with their categories
<code>
... subregions=counties ...
</code>

* raster of developed (1), undeveloped (0) and NULLs for undevelopable areas
<code>
... developed=urban_2011 ...
</code>

* predictors selected with {{AddonCmd|r.futures.potential}} and their coefficients in a <tt>potential.csv</tt> file. The order of predictors must match the order in the file and the categories of the counties must match raster <tt>counties</tt>.
<code>
... predictors=slope,forest_smooth_perc,dist_interchanges_km,travel_time_cities devpot_params=potential.csv ...
</code>

* initial development pressure computed by {{AddonCmd|r.futures.devpressure}}, it's important to set here the same parameters
<code>
... development_pressure=devpressure_1 n_dev_neighbourhood=10 development_pressure_approach=gravity gamma=1 scaling_factor=1 ...
</code>

* per capita land demand computed by {{AddonCmd|r.futures.demand}}, the categories of the counties must match raster <tt>counties</tt>.
<code>
... demand=demand.csv ...
</code>

* patch parameters from the calibration step
<code>
... discount_factor=0.3 compactness_mean=0.4 compactness_range=0.08 patch_sizes=patches.txt ...
</code>

* recommended parameters for patch growing algorithm
<code>
... num_neighbors=4 seed_search=2 ...
</code>

* set random seed for repeatable results or set flag <tt>-s</tt> to generate seed automatically
<code>
... random_seed=1 ...
</code>

* specify final output map and optionally basename for intermediate raster maps
<code>
output=final output_series=final
</code>

== Scenarios ==
Scenarios involving policies that encourage infill versus sprawl can be explored using the <tt>incentive_power</tt> parameter of {{AddonCmd|r.futures.pga}},
which uses a power function to transform the evenness of the probability gradient in POTENTIAL. You can change the power to a number between 0.25 and 4 to test urban sprawl/infill scenarios.
Higher power leads to infill behavior, lower power to urban sprawl.

== Postprocessing ==

Follow a [[Creating_animation_from_FUTURES_output_in_GRASS_GIS| tutorial how to make an animation from the results]].

= GRASS GIS Python API =

[[Category: Tutorial]]
[[Category: FUTURES]]
[[Category: Urban]]

Workshop on urban growth modeling with FUTURES

2016-03-22T21:56:49Z

⚠️Dbvanber: /* Road density */

{{ToModify}}
= Workshop introduction =
r.futures.* is an implementation of the '''FUT'''ure '''U'''rban-'''R'''egional '''E'''nvironment '''S'''imulation (FUTURES)[1] which is a model for multilevel simulations of emerging urban-rural landscape structure. FUTURES produces regional projections of landscape patterns using coupled submodels that integrate nonstationary drivers of land change: per capita demand (DEMAND submodel), site suitability (POTENTIAL submodel), and the spatial structure of conversion events (PGA submodel).

[1] Meentemeyer, R. K., Tang, W., Dorning, M. A., Vogler, J. B., Cunniffe, N. J., & Shoemaker, D. A. (2013). [http://www.tandfonline.com/doi/abs/10.1080/00045608.2012.707591 FUTURES: multilevel simulations of emerging urban-rural landscape structure using a stochastic patch-growing algorithm.] Annals of the Association of American Geographers, 103(4), 785-807

== Software ==
There are a number of software requirements to run FUTURES that will need to be download and installed. Required software includes:
* GRASS GIS 7
* addons
** {{AddonCmd|r.futures.pga}}
** {{AddonCmd|r.futures.potential}}
** {{AddonCmd|r.futures.potsurface}}
** {{AddonCmd|r.futures.demand}}
** {{AddonCmd|r.futures.devpressure}}
** {{AddonCmd|r.sample.category}}
* R (≥ 3.0.2) - needed for {{AddonCmd|r.futures.potential}} with packages:
**MuMIn, lme4, optparse, rgrass7
* SciPy - useful for {{AddonCmd|r.futures.demand}}

=== Installation ===
We use the R statistical software for our calculation of site suitability (i.e. development potential) in FUTURES. R is a free software environment for statistical computing and graphics. If you don't have R, or you have older an version, please download and install the software from [http://archive.linux.duke.edu/cran/ install R] and be sure to additionally add these required packages:
<pre>
install.packages(c("MuMIn", "lme4", "optparse", "rgrass7"))
</pre>

==== MS Windows ====
We will be using GRASS GIS 7.0.3 that can be found here in the [https://trac.osgeo.org/osgeo4w/ OSGeo4W] package manager.
Please install the latest stable GRASS GIS 7 version and the SciPy Python package using the ''Advanced install'' option.
A guide with step by step screen shot instructions is available [https://docs.google.com/presentation/d/1yEGpriBne7RvjB35HI6GecNwO1P1y2nRGqDThqoNnCE/edit?usp=sharing here].

In order for GRASS to be able to find R executables, GRASS must be on the PATH variable. Follow this [solution] to make R accessible from GRASS permanently.
A simple but temporary solution is to open GRASS GIS and paste this in the black terminal:
<pre>
set PATH=%PATH%;C:\Program Files\R\R-3.0.2\bin
</pre>
This has to be repeated after restarting GRASS session.

==== Ubuntu Linux ====
Install GRASS GIS from packages:
<pre>
sudo add-apt-repository ppa:ubuntugis/ubuntugis-unstable
sudo apt-get update
sudo apt-get install grass
</pre>

== Workshop data ==
The data that we will be using for the workshop can be download here: [http://fatra.cnr.ncsu.edu/futures/futures_ncspm_Asheville.zip sample dataset]. Please place these layers in your local GRASS directory:
* digital elevation model ([http://nationalmap.gov/elevation.html NED])
* [http://www.mrlc.gov/ NLCD] 2001, 2011
* NLCD 1992/2001 Retrofit Land Cover Change Product
* transportation network ([http://www.census.gov/geo/maps-data/data/tiger-line.html TIGER])
* county boundaries ([http://www.census.gov/geo/maps-data/data/tiger-line.html TIGER])
* protected areas ([http://www.conservationgateway.org/ConservationByGeography/NorthAmerica/UnitedStates/edc/reportsdata/terrestrial/secured/Pages/default.aspx Secured Lands])
* cities as points (USGS)

In addition, download [http://fatra.cnr.ncsu.edu/futures/futures_Asheville_files.zip population information as text files]:
* county population past estimates and future projections ([https://www.osbm.nc.gov/demog/county-projections NC OSBM]) per county (nonspatial)

= GRASS GIS introduction =
There are many advantages to using the open source GRASS GIS platform, but for many that are more familiar with ARCGis and QGis, the setup and implementation of spatial tools in GRASS can be confusing. Here we provide an overview of the GRASS GIS project: [https://grass.osgeo.org grass.osgeo.org] that might be helpful to review if you are a first time users. For this exercise it's not necessary to have a full understanding of how to use GRASS. However, you will need to know how to place your data in the correct GRASS database directory, as well as some basic GRASS functionality. Step by step instructions are provided below
== Setting up GRASS for the tutorial ==
GRASS uses unique database terminology and structure ([https://grass.osgeo.org/grass71/manuals/grass_database.html GRASS database]) that are important to understand for the set up of this tutorial, as you will need to place the required data (e.g. Mapset) in a specific GRASS database Location. In the following we review important terminology and give step by step direction on how to download and place you data in the correct location.

=== Important GRASS directory terminology ===
* A '''GRASS database''' consist of directory with specific Locations (projects) where data layer are stored
* '''Location''' hold all Mapsets in a specific directoy that have the same spatial projection (spatial reference system)
* '''Mapset''' are a collection of maps with the same spatial projection

=== Creating a GRASS database for the tutorial ===
You need to create a GRASS database with the Mapset that we will use for the tutorial before we can run the FUTURES model. Please Download the [http://fatra.cnr.ncsu.edu/futures/futures_ncspm_Asheville.zip workshop location], noting where the files are located on your local directory. Now, create (unless you already have it) a directory named <tt>grassdata</tt> (GRASS database) in your home folder (or Documents), unzip the downloaded data into this directory. You should now have a Location <tt>futures_ncspm</tt> in <tt>grassdata</tt>.

<center><gallery perrow=1 widths=500 heights=250>Image:GRASS FUTURES startup.png|GRASS GIS 7.0.3 startup dialog with downloaded Location and Mapsets for FUTURES workshop</gallery></center>

=== Launching and exploring data in GRASS ===
Now that we have the data in the correct GRASS database, we can launch the Graphical User Interface (GUI). The GUI interface allows you to display raster, vector data as well as navigate through zooming in and out. Advanced exploration and visualization, like many popular GIS software, is also possible in GRASS (e.g. queries, adding legend). The print screens below depicts how you can add different map layers (left) and display the metadata of your data layers.

<center><gallery perrow=2 widths=500 heights=250>Image:GRASS FUTURES wxGUI display.png|Layer Manager and Map Display overview. Annotations show how to add raster layer, query, add legend.
Image:wxGUI_metadata_rinfo.png|Show raster map metadata by right click on layer</gallery></center>

== GRASS functionality ==
One of the advantage of GRASS is the diversity and number of module addons that let you analyze all manner of spatial and temporal. Because it is open source modules are added daily increasing functionality and methods for analysis of your data. GRASS GIS has over [https://grass.osgeo.org/grass70/manuals/full_index.html 500 different modules] in the core distribution and over [https://grass.osgeo.org/grass70/manuals/addons/ 230 addon modules] that can be used to prepare and analyze data layers.
<center>
{| class="wikitable"
|-
! Prefix !! Function !! Example
|-
| r.* || raster processing || ''{{cmd|r.mapcalc}}'': map algebra
|-
| v.* || vector processing || ''{{cmd|v.clean}}'': topological cleaning
|-
| i.* || imagery processing || ''{{cmd|i.segment}}'': object recognition
|-
| db.* || database management || ''{{cmd|db.select}}'': select values from table
|-
| r3.* || 3D raster processing || ''{{cmd|r3.stats}}'': 3D raster statistics
|-
| t.* || temporal data processing || ''{{cmd|t.rast.aggregate}}'': temporal aggregation
|-
| g.* || general data management || ''{{cmd|g.rename}}'': renames map
|-
| d.* || display ||''{{cmd|d.rast}}'': display raster map
|}</center>

=== Command line vs. GUI interface===
GRASS modules can be executed either through a GUI or command line interface. The GUI offers a user-friendly approach to executing modules where the user can navigate to data layers that they would like to analyze and modify processing options with simple check boxes. The GUI also offer a easily accessible manual on how to execute a model. The command line interface allows users to execute a module using command prompts specific to that module. This is handy when you are running similar analyses with minor modification or are familiar with the module commands for quick efficient processing. In this workshop we provide module prompts that can be copy and pasted into the command line for our workflow, but you can use both GUI and command line depending on personal preference. Look how {{cmd|wxGUI.modules|version=71|desc=GUI and command line interface}} represent the same tool. ''Task:'' compute aspect (orientation) from provided digital elevation model using module {{cmd|r.slope.aspect}} using both module dialog and command line.
* How to find modules? Modules are organized by their functionality in wxGUI menu, or we can search for them in Search modules tab. If we already know which module to use, we can just type it in the wxGUI command console. <center><gallery perrow=3 widths=380 heights=190>Image:wxGUI_menu_rinfo.png|Modules can be found in wxGUI menu
Image:wxGUI_module_search.png|You can search modules by name, description or keywords in ''Search modules'' tab
Image:wxGUI_console_completion.png|By typing prefix r. we make a list of modules starting with that prefix to show up.</gallery></center>

=== Computational region===

{{cmd|g.region|desc=Computational region}} - is an important raster concept in GRASS that needs some explanation. In GRASS a computational region can be set, subsetting larger extent data for quicker testing of analysis or analysis of specific regions based on adminstrative units. We provide a few points to keep in mind when using the computational region function:
* defined by region extent and raster resolution
* applies to all raster operations
* persists between GRASS session, can be different for different mapsets
* advantages: keeps your results consistent, avoid clipping, for computationally demanding tasks set region to smaller extent, check your result is good and then set the computational region to the entire study area and rerun analysis
* run <code>g.region -p</code> or in menu ''Settings'' - ''Region'' - ''Display region'' to see current region settings
[[File:WxGUI set region.png|700px|thumb|center|Simple ways to set computational region from GUI. On the left, set region to match raster map. On the right, select the highlighted option and then set region by drawing rectangle.]]

* GRASS 3D view

= Modeling with FUTURES =
== Initial steps and data preparation ==
First we will set the computational region of our analyses to an extent covering our study area that aligns with our base landuse rasters. ''Like explained in the instructions above, you simply need copy and paste these commands into the command prompt of GRASS''.
<source lang="bash">g.region raster=landuse_2011 -p</source>

The FUTURES model uses the locations of development and new development to predict when and where new urban growth will occur. This requires longitudinal data on urban land use. We will derive urbanized areas from NLCD dataset for year 1992, 2001 and 2011
by extracting categories category 21 - 24 into a new binary map where developed is 1,
undeveloped 0 and NULL (no data). The NULL area is important in simulating urban growth as it preclude these are from becoming development. For this exercise we assume that water, wetlands and protected areas can not be developed, setting them to NULL.
First we will convert protected areas from vector to raster. We set
NULLs to zeros (for simpler raster algebra expression in the next step) using {{cmd|r.null}}:

<source lang="bash">
v.to.rast input=protected_areas output=protected_areas use=val
r.null map=protected_areas null=0
</source>

And then create rasters of developed/undeveloped areas using raster algebra:

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.mapcalc "urban_1992 = if(landuse_1992 >= 21 && landuse_1992 <= 24, 1, if(landuse_1992 == 11 || landuse_1992 >= 90 || protected_areas, null(), 0))"
r.mapcalc "urban_2001 = if(landuse_2001 >= 21 && landuse_2001 <= 24, 1, if(landuse_2001 == 11 || landuse_2001 >= 90 || protected_areas, null(), 0))"
r.mapcalc "urban_2011 = if(landuse_2011 >= 21 && landuse_2011 <= 24, 1, if(landuse_2011 == 11 || landuse_2011 >= 90 || protected_areas, null(), 0))"
</source>

FUTURES is a multi-level modelling framework meaning that we model population projections for subregions and assume that these subregions are influenced differently by the factors that influence where development happens. This requires defining subregions for model implementation. For this exercise we use the county level, which is the finest scale of population data that is available to us. We therefore need to convert vectors of counties to a raster with the values of the FIPS attribute which links to population file:

<source lang="bash">
v.to.rast input=counties type=area use=attr attribute_column=FIPS output=counties
</source>

Before further steps, we will set our working directory so that the input population files and text files
we are going to create are saved in one directory and easily accessible.
You can do that from menu ''Settings'' → ''GRASS working environment'' → ''Change working directory''.
Select (or create) a directory and move there the downloaded files <tt>population_projection.csv</tt> and <tt>population_trend.csv</tt>.

== Potential submodel ==
Module {{AddonCmd|r.futures.potential}} implements the POTENTIAL submodel as a part of FUTURES land change model. POTENTIAL is implemented using a set of coefficients that relate a selection of site suitability factors to the probability of a place becoming developed. This is implemented using the parameter table in combination with maps of those site suitability factors (mapped predictors). The coefficients are obtained by conducting multilevel logistic regression in R with package lme4 where the coefficients may vary by county. The best model is selected automatically using dredge function from package [https://cran.r-project.org/web/packages/MuMIn/index.html MuMIn].

First, we will derive possible predictors of urban growth using GRASS modules.
=== Predictors ===
==== Slope ====
Slope possibly influences urban growth as steep areas are difficult to build on. We will derive slope in degrees from digital elevation model using {{cmd|r.slope.aspect}} module:
<source lang="bash">r.slope.aspect elevation=elevation_30m slope=slope</source>

==== Distance from lakes/rivers ====
Distance to lakes or rivers may contribute to an amenity draw where people would like to build a house in a location where they can view water. First we will extract [http://www.mrlc.gov/nlcd11_leg.php category ''Open Water''] from 2011 NLCD dataset:
<source lang="bash">
r.mapcalc "water = if(landuse_2011 == 11, 1, null())"
</source>

Then we compute the distance to water with module {{cmd|r.grow.distance}} and set color table to shades of blue:
<source lang="bash">
r.grow.distance input=water distance=dist_to_water
r.colors -n map=dist_to_water color=blues
</source>

==== Distance from protected areas ====
Like water protected areas can attract urban growth as people enjoy living near scenic areas. We will use raster protected of protected areas we already created, but we will set NULL values to zero.
We compute the distance to protected areas with module {{cmd|r.grow.distance}} and set color table from green to red:
<source lang="bash">
r.null map=protected_areas setnull=0
r.grow.distance input=protected_areas distance=dist_to_protected
r.colors map=dist_to_protected color=gyr
</source>

==== Forests ====
Forest may influence urban growth in different ways. On the one hand it might be costly for developments as tree will need to be removed. On the other hand, people may want to live near forests. We calculate the percentage forest for a 1 km pixel to test forest influence, see NLCD [http://www.mrlc.gov/nlcd11_leg.php category ''Open Water'']:
<source lang="bash">
r.mapcalc "forest = if(landuse_2011 >= 41 && landuse_2011 <= 43, 1, 0)"
r.neighbors -c input=forest output=forest_smooth size=15 method=average
r.colors map=forest_smooth color=ndvi
</source>

==== Travel time to cities ====
Travel time to urban centers can often play a role in development with access to centers where employment is concentrated. Here we will compute travel time to cities (with population > 5000)
as cumulative cost distance where cost is defined as travel time on roads.
First we specify the speed on different types of roads.
We copy the roads raster into our mapset so that we can change it
by adding a new attribute field <tt>speed</tt>. Then we assign speed values (km/h) based on the type of road:

<source lang="bash">
g.copy vector=roads,myroads
v.db.addcolumn map=myroads columns="speed double precision"
v.db.update map=myroads column=speed value=50 where="MTFCC = 'S1400'"
v.db.update map=myroads column=speed value=100 where="MTFCC IN ('S1100', 'S1200')"
</source>

Now we rasterize the selected road types using the speed values from the attribute table as raster values.

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
v.to.rast input=myroads type=line where="MTFCC IN ('S1100', 'S1200', 'S1400')" output=roads_speed use=attr attribute_column=speed
</source>

We set the rest of the area to low speed and recompute the speed as time to travel through a 30m cell in minutes:

<source lang="bash">
r.null map=roads_speed null=5
r.mapcalc "roads_travel_time = 1.8 / roads_speed"
</source>

Finally we compute the travel time to larger cities using {{cmd|r.cost}}:

<source lang="bash">
r.cost input=roads_travel_time output=travel_time_cities start_points=cities
r.colors map=travel_time_cities color=byr
</source>

==== Road density ====
Dense road construction often occurs in suburban areas where much much development occurs in U.S. cities. To capture this influence we can calculate road density based on the road network. We rasterize roads and use a moving window analysis ({{cmd|r.neighbors}}) to compute road density for a 1 km area:

<source lang="bash">
v.to.rast input=roads output=roads use=val type=line
r.null map=roads null=0
r.neighbors -c input=roads output=road_dens size=25 method=average
</source>

==== Distance to interchanges ====

We will consider TIGER roads of type <tt>Ramp</tt> as interchanges, rasterize them and compute euclidean distance to them:

<source lang="bash">
v.to.rast input=roads type=line where="MTFCC = 'S1630'" output=interchanges use=val
r.grow.distance -m input=interchanges distance=dist_interchanges
</source>

=== Development pressure ===

We compute development pressure with {{AddonCmd|r.futures.devpressure}}. Development pressure is a predictor based on number of neighboring developed cells within search distance, weighted by distance. The development pressure variable plays a special role in the model, allowing for a feedback between predicted change and change in subsequent steps.

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.devpressure -n input=urban_2011 output=devpressure_2 method=gravity size=7 gamma=2 scaling_factor=10
r.futures.devpressure -n input=urban_2011 output=devpressure_1 method=gravity size=10 gamma=1 scaling_factor=1
r.futures.devpressure -n input=urban_2011 output=devpressure_0_5 method=gravity size=30 gamma=0.5 scaling_factor=0.1
</source>

When gamma increases, development influence decreases more rapidly with distance.
Size is half the size of the moving window. When gamma is low, local development influences more distant places.
We will derive 3 layers with different gamma and size parameters for the potential statistical model.

=== Rescaling variables ===

First we will look at the ranges of our predictor variables by running a short Python code snippet in Python shell:

<source lang="python" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
for name in ['slope', 'dist_to_water', 'dist_to_protected', 'forest_smooth', 'travel_time_cities', 'road_dens', 'dist_interchanges', 'devpressure_0_5', 'devpressure_1']:
minmax = grass.raster_info(name)
print name, minmax['min'], minmax['max']
</source>

We will rescale some of our input variables:

<source lang="bash">
r.mapcalc "dist_to_water_km = dist_to_water / 1000"
r.mapcalc "dist_to_protected_km = dist_to_protected / 1000"
r.mapcalc "dist_interchanges_km = dist_interchanges / 1000"
r.mapcalc "road_dens_perc = road_dens * 100"
r.mapcalc "forest_smooth_perc = forest_smooth * 100"
</source>

=== Sampling ===
To sample only in the analyzed counties, we will clip development layer:

<source lang="bash">
r.mapcalc "urban_change_01_11 = if(urban_2011 == 1, if(urban_2001 == 0, 1, null()), 0)"
r.mapcalc "urban_change_clip = if(counties, urban_change_01_11)"
</source>

To estimate the number of sampling points, we can use {{cmd|r.report}} to report number of developed/undeveloped cells and their ratio.

<source lang="bash">
r.report map=urban_change_clip units=h,c,p
</source>

We will sample the predictors and the response variable with 5000 random points in undeveloped areas and 1000 points in developed area:

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.sample.category input=urban_change_clip output=sampling sampled=counties,devpressure_0_5,devpressure_1,devpressure_2,slope,road_dens_perc,forest_smooth_perc,dist_to_water_km,dist_to_protected_km,dist_interchanges_km,travel_time_cities npoints=5000,1000
</source>

The attribute table can be exported as CSV file (not necessary step):

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
v.db.select map=sampling columns=urban_change_clip,counties,devpressure_0_5,devpressure_1,slope,road_dens_perc,forest_smooth_perc,dist_to_water_km,dist_to_protected_km,dist_interchanges_km,travel_time_cities separator=comma file=samples.csv
</source>

=== Development potential ===
Now we find best model for predicting urbanization using {{AddonCmd|r.futures.potential}} which wraps an R script.

We can run R [http://www.inside-r.org/packages/cran/MuMIn/docs/dredge dredge] function to find "best" model. We can specify minimum and maximum number of predictors the final model should use.
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.potential -d input=sampling output=potential.csv columns=devpressure_1,slope,road_dens_perc,forest_smooth_perc,dist_to_water_km,dist_to_protected_km,dist_interchanges_km,travel_time_cities developed_column=urban_change_clip subregions_column=counties min_variables=4
</source>

Also, we can play with different combinations of predictors, for example:

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.potential input=sampling output=potential.csv columns=devpressure_2,road_dens_perc,slope,dist_interchanges_km,dist_to_water_km developed_column=urban_change_clip subregions_column=counties --o
r.futures.potential input=sampling output=potential.csv columns=devpressure_1,road_dens_perc,slope,dist_interchanges_km,dist_to_water_km developed_column=urban_change_clip subregions_column=counties --o
...
</source>

You can then open the output file <tt>potential.csv</tt>, which is a CSV file with tabs as separators.

For this tutorial, the final potential is created with:
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.potential input=sampling output=potential.csv columns=devpressure_2,road_dens_perc,slope,dist_interchanges_km,dist_to_water_km developed_column=urban_change_clip subregions_column=counties --o
</source>

We can now visualize the suitability surface using module {{AddonCmd|r.futures.potsurface}}. It creates initial development potential (suitability) raster from predictors and model coefficients and serves only for evaluating development potential model. The values of the resulting raster range from 0 to 1.

<source lang="bash">
r.futures.potsurface input=potential.csv subregions=counties output=suitability
r.colors map=suitability color=byr
</source>

== Demand submodel ==
First we will mask out roads so that they don't influence into per capita land demand relation.
<source lang="bash">
v.to.rast input=roads type=line output=roads_mask use=val
r.mask roads_mask -i
</source>

We will use {{AddonCmd|r.futures.demand}} which derives the population vs. development relation. The relation can be linear/logarithmic/logarithmic2/exponential/exponential approach.
Look for examples of the different relations in the manual.

* linear: y = A + Bx
* logarithmic: y = A + Bln(x)
* logarithmic2: y = A + B * ln(x - C)        (requires SciPy)
* exponential: y = Ae^(BX)
* exp_approach: y = (1 - e^(-A(x - B))) + C        (requires SciPy)

The format of the input population CSV files is described in the manual. It is important to have synchronized categories of subregions and the column headers of the CSV files (in our case FIPS number). How to simply generate the list of years (for which demand is computed) is described in {{AddonCmd|r.futures.demand}} manual, for example run this in Python console:

<source lang="python">
','.join([str(i) for i in range(2011, 2036)])
</source>

Then we can create the DEMAND file:
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.demand development=urban_1992,urban_2001,urban_2011 subregions=counties observed_population=population_trend.csv projected_population=population_projection.csv simulation_times=2011,2012,2013,2014,2015,2016,2017,2018,2019,2020,2021,2022,2023,2024,2025,2026,2027,2028,2029,2030,2031,2032,2033,2034,2035 plot=plot_demand.pdf demand=demand.csv separator=comma
</source>

In your current working directory, you should find files <tt>plot_demand.png</tt> and <tt>demand.csv</tt>.

If you have SciPy installed, you can experiment with other methods for fitting the functions:
<source lang="bash">
r.futures.demand ... method=logarithmic2
r.futures.demand ... method=exp_approach
</source>
If necessary, you can create a set of demand files produced by fitting each method separately and
then pick for each county the method which seems best and manually create a new demand file.

When you are finished, remove the mask as it is not needed for the next steps.
<source lang="bash">
r.mask -r
</source>

== Patch calibration ==
Patch calibration can be a very time consuming computation.
Therefore we select only one county (Buncombe):

<source lang="bash">
v.to.rast input=counties type=area where="FIPS == 37021" use=attr attribute_column=FIPS output=calib_county
g.region raster=calib_county zoom=calib_county
</source>
to derive patches of new development by comparing historical and latest development.
We can keep only patches with minimum size 2 cells (1800 = 2 x 30 x 30 m).

<source lang="bash">
r.futures.calib development_start=urban_1992 development_end=urban_2011 subregions=counties patch_sizes=patches.txt patch_threshold=1800 -l
</source>
We obtained a file <tt>patches.txt</tt> (used later in the PGA) - a patch size distribution file - containing sizes of all found patches.

We can look at the distribution of the patch sizes:

<source lang="python">
from matplotlib import pyplot as plt
with open('patches.txt') as f:
patches = [int(patch) for patch in f.readlines()]
plt.hist(patches, 2000)
plt.xlim(0,50)
plt.show()
</source>

At this point, we start the calibration to get best parameters of patch shape
(for this tutorial, this step can be skipped and the suggested parameters are used).

<source lang="bash"
style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.calib development_start=urban_1992 development_end=urban_2011 subregions=calib_county patch_sizes=patches.txt calibration_results=calib.csv patch_threshold=1800 repeat=5 compactness_mean=0.1,0.3,0.5,0.7,0.9 compactness_range=0.05 discount_factor=0.1,0.3,0.5,0.7,0.9 predictors=road_dens_perc,forest_smooth_perc,dist_to_protected_km demand=demand.csv devpot_params=potential.csv num_neighbors=4 seed_search=2 development_pressure=devpressure_0_5 development_pressure_approach=gravity n_dev_neighbourhood=30 gamma=0.5 scaling_factor=0.1
</source>

== FUTURES simulation ==
We will switch back to our previous region:
<source lang="bash">
g.region raster=landuse_2011 -p
</source>

Now we have all the inputs necessary for running {{AddonCmd|r.futures.pga}}:

The entire command is here:
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.pga subregions=counties developed=urban_2011 predictors=slope,forest_smooth_perc,dist_interchanges_km,travel_time_cities devpot_params=potential.csv development_pressure=devpressure_1 n_dev_neighbourhood=10 development_pressure_approach=gravity gamma=1 scaling_factor=1 demand=demand.csv discount_factor=0.3 compactness_mean=0.2 compactness_range=0.1 patch_sizes=patches.txt num_neighbors=4 seed_search=2 random_seed=1 output=final output_series=final
</source>

=== Quick description ===
The command parameters and their values:
* raster map of counties with their categories
<code>
... subregions=counties ...
</code>

* raster of developed (1), undeveloped (0) and NULLs for undevelopable areas
<code>
... developed=urban_2011 ...
</code>

* predictors selected with {{AddonCmd|r.futures.potential}} and their coefficients in a <tt>potential.csv</tt> file. The order of predictors must match the order in the file and the categories of the counties must match raster <tt>counties</tt>.
<code>
... predictors=slope,forest_smooth_perc,dist_interchanges_km,travel_time_cities devpot_params=potential.csv ...
</code>

* initial development pressure computed by {{AddonCmd|r.futures.devpressure}}, it's important to set here the same parameters
<code>
... development_pressure=devpressure_1 n_dev_neighbourhood=10 development_pressure_approach=gravity gamma=1 scaling_factor=1 ...
</code>

* per capita land demand computed by {{AddonCmd|r.futures.demand}}, the categories of the counties must match raster <tt>counties</tt>.
<code>
... demand=demand.csv ...
</code>

* patch parameters from the calibration step
<code>
... discount_factor=0.3 compactness_mean=0.4 compactness_range=0.08 patch_sizes=patches.txt ...
</code>

* recommended parameters for patch growing algorithm
<code>
... num_neighbors=4 seed_search=2 ...
</code>

* set random seed for repeatable results or set flag <tt>-s</tt> to generate seed automatically
<code>
... random_seed=1 ...
</code>

* specify final output map and optionally basename for intermediate raster maps
<code>
output=final output_series=final
</code>

== Scenarios ==
Scenarios involving policies that encourage infill versus sprawl can be explored using the <tt>incentive_power</tt> parameter of {{AddonCmd|r.futures.pga}},
which uses a power function to transform the evenness of the probability gradient in POTENTIAL. You can change the power to a number between 0.25 and 4 to test urban sprawl/infill scenarios.
Higher power leads to infill behavior, lower power to urban sprawl.

== Postprocessing ==

Follow a [[Creating_animation_from_FUTURES_output_in_GRASS_GIS| tutorial how to make an animation from the results]].

= GRASS GIS Python API =

[[Category: Tutorial]]
[[Category: FUTURES]]
[[Category: Urban]]

Workshop on urban growth modeling with FUTURES

2016-03-22T21:52:41Z

⚠️Dbvanber: /* Travel time to cities */

{{ToModify}}
= Workshop introduction =
r.futures.* is an implementation of the '''FUT'''ure '''U'''rban-'''R'''egional '''E'''nvironment '''S'''imulation (FUTURES)[1] which is a model for multilevel simulations of emerging urban-rural landscape structure. FUTURES produces regional projections of landscape patterns using coupled submodels that integrate nonstationary drivers of land change: per capita demand (DEMAND submodel), site suitability (POTENTIAL submodel), and the spatial structure of conversion events (PGA submodel).

[1] Meentemeyer, R. K., Tang, W., Dorning, M. A., Vogler, J. B., Cunniffe, N. J., & Shoemaker, D. A. (2013). [http://www.tandfonline.com/doi/abs/10.1080/00045608.2012.707591 FUTURES: multilevel simulations of emerging urban-rural landscape structure using a stochastic patch-growing algorithm.] Annals of the Association of American Geographers, 103(4), 785-807

== Software ==
There are a number of software requirements to run FUTURES that will need to be download and installed. Required software includes:
* GRASS GIS 7
* addons
** {{AddonCmd|r.futures.pga}}
** {{AddonCmd|r.futures.potential}}
** {{AddonCmd|r.futures.potsurface}}
** {{AddonCmd|r.futures.demand}}
** {{AddonCmd|r.futures.devpressure}}
** {{AddonCmd|r.sample.category}}
* R (≥ 3.0.2) - needed for {{AddonCmd|r.futures.potential}} with packages:
**MuMIn, lme4, optparse, rgrass7
* SciPy - useful for {{AddonCmd|r.futures.demand}}

=== Installation ===
We use the R statistical software for our calculation of site suitability (i.e. development potential) in FUTURES. R is a free software environment for statistical computing and graphics. If you don't have R, or you have older an version, please download and install the software from [http://archive.linux.duke.edu/cran/ install R] and be sure to additionally add these required packages:
<pre>
install.packages(c("MuMIn", "lme4", "optparse", "rgrass7"))
</pre>

==== MS Windows ====
We will be using GRASS GIS 7.0.3 that can be found here in the [https://trac.osgeo.org/osgeo4w/ OSGeo4W] package manager.
Please install the latest stable GRASS GIS 7 version and the SciPy Python package using the ''Advanced install'' option.
A guide with step by step screen shot instructions is available [https://docs.google.com/presentation/d/1yEGpriBne7RvjB35HI6GecNwO1P1y2nRGqDThqoNnCE/edit?usp=sharing here].

In order for GRASS to be able to find R executables, GRASS must be on the PATH variable. Follow this [solution] to make R accessible from GRASS permanently.
A simple but temporary solution is to open GRASS GIS and paste this in the black terminal:
<pre>
set PATH=%PATH%;C:\Program Files\R\R-3.0.2\bin
</pre>
This has to be repeated after restarting GRASS session.

==== Ubuntu Linux ====
Install GRASS GIS from packages:
<pre>
sudo add-apt-repository ppa:ubuntugis/ubuntugis-unstable
sudo apt-get update
sudo apt-get install grass
</pre>

== Workshop data ==
The data that we will be using for the workshop can be download here: [http://fatra.cnr.ncsu.edu/futures/futures_ncspm_Asheville.zip sample dataset]. Please place these layers in your local GRASS directory:
* digital elevation model ([http://nationalmap.gov/elevation.html NED])
* [http://www.mrlc.gov/ NLCD] 2001, 2011
* NLCD 1992/2001 Retrofit Land Cover Change Product
* transportation network ([http://www.census.gov/geo/maps-data/data/tiger-line.html TIGER])
* county boundaries ([http://www.census.gov/geo/maps-data/data/tiger-line.html TIGER])
* protected areas ([http://www.conservationgateway.org/ConservationByGeography/NorthAmerica/UnitedStates/edc/reportsdata/terrestrial/secured/Pages/default.aspx Secured Lands])
* cities as points (USGS)

In addition, download [http://fatra.cnr.ncsu.edu/futures/futures_Asheville_files.zip population information as text files]:
* county population past estimates and future projections ([https://www.osbm.nc.gov/demog/county-projections NC OSBM]) per county (nonspatial)

= GRASS GIS introduction =
There are many advantages to using the open source GRASS GIS platform, but for many that are more familiar with ARCGis and QGis, the setup and implementation of spatial tools in GRASS can be confusing. Here we provide an overview of the GRASS GIS project: [https://grass.osgeo.org grass.osgeo.org] that might be helpful to review if you are a first time users. For this exercise it's not necessary to have a full understanding of how to use GRASS. However, you will need to know how to place your data in the correct GRASS database directory, as well as some basic GRASS functionality. Step by step instructions are provided below
== Setting up GRASS for the tutorial ==
GRASS uses unique database terminology and structure ([https://grass.osgeo.org/grass71/manuals/grass_database.html GRASS database]) that are important to understand for the set up of this tutorial, as you will need to place the required data (e.g. Mapset) in a specific GRASS database Location. In the following we review important terminology and give step by step direction on how to download and place you data in the correct location.

=== Important GRASS directory terminology ===
* A '''GRASS database''' consist of directory with specific Locations (projects) where data layer are stored
* '''Location''' hold all Mapsets in a specific directoy that have the same spatial projection (spatial reference system)
* '''Mapset''' are a collection of maps with the same spatial projection

=== Creating a GRASS database for the tutorial ===
You need to create a GRASS database with the Mapset that we will use for the tutorial before we can run the FUTURES model. Please Download the [http://fatra.cnr.ncsu.edu/futures/futures_ncspm_Asheville.zip workshop location], noting where the files are located on your local directory. Now, create (unless you already have it) a directory named <tt>grassdata</tt> (GRASS database) in your home folder (or Documents), unzip the downloaded data into this directory. You should now have a Location <tt>futures_ncspm</tt> in <tt>grassdata</tt>.

<center><gallery perrow=1 widths=500 heights=250>Image:GRASS FUTURES startup.png|GRASS GIS 7.0.3 startup dialog with downloaded Location and Mapsets for FUTURES workshop</gallery></center>

=== Launching and exploring data in GRASS ===
Now that we have the data in the correct GRASS database, we can launch the Graphical User Interface (GUI). The GUI interface allows you to display raster, vector data as well as navigate through zooming in and out. Advanced exploration and visualization, like many popular GIS software, is also possible in GRASS (e.g. queries, adding legend). The print screens below depicts how you can add different map layers (left) and display the metadata of your data layers.

<center><gallery perrow=2 widths=500 heights=250>Image:GRASS FUTURES wxGUI display.png|Layer Manager and Map Display overview. Annotations show how to add raster layer, query, add legend.
Image:wxGUI_metadata_rinfo.png|Show raster map metadata by right click on layer</gallery></center>

== GRASS functionality ==
One of the advantage of GRASS is the diversity and number of module addons that let you analyze all manner of spatial and temporal. Because it is open source modules are added daily increasing functionality and methods for analysis of your data. GRASS GIS has over [https://grass.osgeo.org/grass70/manuals/full_index.html 500 different modules] in the core distribution and over [https://grass.osgeo.org/grass70/manuals/addons/ 230 addon modules] that can be used to prepare and analyze data layers.
<center>
{| class="wikitable"
|-
! Prefix !! Function !! Example
|-
| r.* || raster processing || ''{{cmd|r.mapcalc}}'': map algebra
|-
| v.* || vector processing || ''{{cmd|v.clean}}'': topological cleaning
|-
| i.* || imagery processing || ''{{cmd|i.segment}}'': object recognition
|-
| db.* || database management || ''{{cmd|db.select}}'': select values from table
|-
| r3.* || 3D raster processing || ''{{cmd|r3.stats}}'': 3D raster statistics
|-
| t.* || temporal data processing || ''{{cmd|t.rast.aggregate}}'': temporal aggregation
|-
| g.* || general data management || ''{{cmd|g.rename}}'': renames map
|-
| d.* || display ||''{{cmd|d.rast}}'': display raster map
|}</center>

=== Command line vs. GUI interface===
GRASS modules can be executed either through a GUI or command line interface. The GUI offers a user-friendly approach to executing modules where the user can navigate to data layers that they would like to analyze and modify processing options with simple check boxes. The GUI also offer a easily accessible manual on how to execute a model. The command line interface allows users to execute a module using command prompts specific to that module. This is handy when you are running similar analyses with minor modification or are familiar with the module commands for quick efficient processing. In this workshop we provide module prompts that can be copy and pasted into the command line for our workflow, but you can use both GUI and command line depending on personal preference. Look how {{cmd|wxGUI.modules|version=71|desc=GUI and command line interface}} represent the same tool. ''Task:'' compute aspect (orientation) from provided digital elevation model using module {{cmd|r.slope.aspect}} using both module dialog and command line.
* How to find modules? Modules are organized by their functionality in wxGUI menu, or we can search for them in Search modules tab. If we already know which module to use, we can just type it in the wxGUI command console. <center><gallery perrow=3 widths=380 heights=190>Image:wxGUI_menu_rinfo.png|Modules can be found in wxGUI menu
Image:wxGUI_module_search.png|You can search modules by name, description or keywords in ''Search modules'' tab
Image:wxGUI_console_completion.png|By typing prefix r. we make a list of modules starting with that prefix to show up.</gallery></center>

=== Computational region===

{{cmd|g.region|desc=Computational region}} - is an important raster concept in GRASS that needs some explanation. In GRASS a computational region can be set, subsetting larger extent data for quicker testing of analysis or analysis of specific regions based on adminstrative units. We provide a few points to keep in mind when using the computational region function:
* defined by region extent and raster resolution
* applies to all raster operations
* persists between GRASS session, can be different for different mapsets
* advantages: keeps your results consistent, avoid clipping, for computationally demanding tasks set region to smaller extent, check your result is good and then set the computational region to the entire study area and rerun analysis
* run <code>g.region -p</code> or in menu ''Settings'' - ''Region'' - ''Display region'' to see current region settings
[[File:WxGUI set region.png|700px|thumb|center|Simple ways to set computational region from GUI. On the left, set region to match raster map. On the right, select the highlighted option and then set region by drawing rectangle.]]

* GRASS 3D view

= Modeling with FUTURES =
== Initial steps and data preparation ==
First we will set the computational region of our analyses to an extent covering our study area that aligns with our base landuse rasters. ''Like explained in the instructions above, you simply need copy and paste these commands into the command prompt of GRASS''.
<source lang="bash">g.region raster=landuse_2011 -p</source>

The FUTURES model uses the locations of development and new development to predict when and where new urban growth will occur. This requires longitudinal data on urban land use. We will derive urbanized areas from NLCD dataset for year 1992, 2001 and 2011
by extracting categories category 21 - 24 into a new binary map where developed is 1,
undeveloped 0 and NULL (no data). The NULL area is important in simulating urban growth as it preclude these are from becoming development. For this exercise we assume that water, wetlands and protected areas can not be developed, setting them to NULL.
First we will convert protected areas from vector to raster. We set
NULLs to zeros (for simpler raster algebra expression in the next step) using {{cmd|r.null}}:

<source lang="bash">
v.to.rast input=protected_areas output=protected_areas use=val
r.null map=protected_areas null=0
</source>

And then create rasters of developed/undeveloped areas using raster algebra:

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.mapcalc "urban_1992 = if(landuse_1992 >= 21 && landuse_1992 <= 24, 1, if(landuse_1992 == 11 || landuse_1992 >= 90 || protected_areas, null(), 0))"
r.mapcalc "urban_2001 = if(landuse_2001 >= 21 && landuse_2001 <= 24, 1, if(landuse_2001 == 11 || landuse_2001 >= 90 || protected_areas, null(), 0))"
r.mapcalc "urban_2011 = if(landuse_2011 >= 21 && landuse_2011 <= 24, 1, if(landuse_2011 == 11 || landuse_2011 >= 90 || protected_areas, null(), 0))"
</source>

FUTURES is a multi-level modelling framework meaning that we model population projections for subregions and assume that these subregions are influenced differently by the factors that influence where development happens. This requires defining subregions for model implementation. For this exercise we use the county level, which is the finest scale of population data that is available to us. We therefore need to convert vectors of counties to a raster with the values of the FIPS attribute which links to population file:

<source lang="bash">
v.to.rast input=counties type=area use=attr attribute_column=FIPS output=counties
</source>

Before further steps, we will set our working directory so that the input population files and text files
we are going to create are saved in one directory and easily accessible.
You can do that from menu ''Settings'' → ''GRASS working environment'' → ''Change working directory''.
Select (or create) a directory and move there the downloaded files <tt>population_projection.csv</tt> and <tt>population_trend.csv</tt>.

== Potential submodel ==
Module {{AddonCmd|r.futures.potential}} implements the POTENTIAL submodel as a part of FUTURES land change model. POTENTIAL is implemented using a set of coefficients that relate a selection of site suitability factors to the probability of a place becoming developed. This is implemented using the parameter table in combination with maps of those site suitability factors (mapped predictors). The coefficients are obtained by conducting multilevel logistic regression in R with package lme4 where the coefficients may vary by county. The best model is selected automatically using dredge function from package [https://cran.r-project.org/web/packages/MuMIn/index.html MuMIn].

First, we will derive possible predictors of urban growth using GRASS modules.
=== Predictors ===
==== Slope ====
Slope possibly influences urban growth as steep areas are difficult to build on. We will derive slope in degrees from digital elevation model using {{cmd|r.slope.aspect}} module:
<source lang="bash">r.slope.aspect elevation=elevation_30m slope=slope</source>

==== Distance from lakes/rivers ====
Distance to lakes or rivers may contribute to an amenity draw where people would like to build a house in a location where they can view water. First we will extract [http://www.mrlc.gov/nlcd11_leg.php category ''Open Water''] from 2011 NLCD dataset:
<source lang="bash">
r.mapcalc "water = if(landuse_2011 == 11, 1, null())"
</source>

Then we compute the distance to water with module {{cmd|r.grow.distance}} and set color table to shades of blue:
<source lang="bash">
r.grow.distance input=water distance=dist_to_water
r.colors -n map=dist_to_water color=blues
</source>

==== Distance from protected areas ====
Like water protected areas can attract urban growth as people enjoy living near scenic areas. We will use raster protected of protected areas we already created, but we will set NULL values to zero.
We compute the distance to protected areas with module {{cmd|r.grow.distance}} and set color table from green to red:
<source lang="bash">
r.null map=protected_areas setnull=0
r.grow.distance input=protected_areas distance=dist_to_protected
r.colors map=dist_to_protected color=gyr
</source>

==== Forests ====
Forest may influence urban growth in different ways. On the one hand it might be costly for developments as tree will need to be removed. On the other hand, people may want to live near forests. We calculate the percentage forest for a 1 km pixel to test forest influence, see NLCD [http://www.mrlc.gov/nlcd11_leg.php category ''Open Water'']:
<source lang="bash">
r.mapcalc "forest = if(landuse_2011 >= 41 && landuse_2011 <= 43, 1, 0)"
r.neighbors -c input=forest output=forest_smooth size=15 method=average
r.colors map=forest_smooth color=ndvi
</source>

==== Travel time to cities ====
Travel time to urban centers can often play a role in development with access to centers where employment is concentrated. Here we will compute travel time to cities (with population > 5000)
as cumulative cost distance where cost is defined as travel time on roads.
First we specify the speed on different types of roads.
We copy the roads raster into our mapset so that we can change it
by adding a new attribute field <tt>speed</tt>. Then we assign speed values (km/h) based on the type of road:

<source lang="bash">
g.copy vector=roads,myroads
v.db.addcolumn map=myroads columns="speed double precision"
v.db.update map=myroads column=speed value=50 where="MTFCC = 'S1400'"
v.db.update map=myroads column=speed value=100 where="MTFCC IN ('S1100', 'S1200')"
</source>

Now we rasterize the selected road types using the speed values from the attribute table as raster values.

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
v.to.rast input=myroads type=line where="MTFCC IN ('S1100', 'S1200', 'S1400')" output=roads_speed use=attr attribute_column=speed
</source>

We set the rest of the area to low speed and recompute the speed as time to travel through a 30m cell in minutes:

<source lang="bash">
r.null map=roads_speed null=5
r.mapcalc "roads_travel_time = 1.8 / roads_speed"
</source>

Finally we compute the travel time to larger cities using {{cmd|r.cost}}:

<source lang="bash">
r.cost input=roads_travel_time output=travel_time_cities start_points=cities
r.colors map=travel_time_cities color=byr
</source>

==== Road density ====
We will rasterize roads and use moving window analysis ({{cmd|r.neighbors}}) to compute road density:

<source lang="bash">
v.to.rast input=roads output=roads use=val type=line
r.null map=roads null=0
r.neighbors -c input=roads output=road_dens size=25 method=average
</source>

==== Distance to interchanges ====

We will consider TIGER roads of type <tt>Ramp</tt> as interchanges, rasterize them and compute euclidean distance to them:

<source lang="bash">
v.to.rast input=roads type=line where="MTFCC = 'S1630'" output=interchanges use=val
r.grow.distance -m input=interchanges distance=dist_interchanges
</source>

=== Development pressure ===

We compute development pressure with {{AddonCmd|r.futures.devpressure}}. Development pressure is a predictor based on number of neighboring developed cells within search distance, weighted by distance. The development pressure variable plays a special role in the model, allowing for a feedback between predicted change and change in subsequent steps.

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.devpressure -n input=urban_2011 output=devpressure_2 method=gravity size=7 gamma=2 scaling_factor=10
r.futures.devpressure -n input=urban_2011 output=devpressure_1 method=gravity size=10 gamma=1 scaling_factor=1
r.futures.devpressure -n input=urban_2011 output=devpressure_0_5 method=gravity size=30 gamma=0.5 scaling_factor=0.1
</source>

When gamma increases, development influence decreases more rapidly with distance.
Size is half the size of the moving window. When gamma is low, local development influences more distant places.
We will derive 3 layers with different gamma and size parameters for the potential statistical model.

=== Rescaling variables ===

First we will look at the ranges of our predictor variables by running a short Python code snippet in Python shell:

<source lang="python" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
for name in ['slope', 'dist_to_water', 'dist_to_protected', 'forest_smooth', 'travel_time_cities', 'road_dens', 'dist_interchanges', 'devpressure_0_5', 'devpressure_1']:
minmax = grass.raster_info(name)
print name, minmax['min'], minmax['max']
</source>

We will rescale some of our input variables:

<source lang="bash">
r.mapcalc "dist_to_water_km = dist_to_water / 1000"
r.mapcalc "dist_to_protected_km = dist_to_protected / 1000"
r.mapcalc "dist_interchanges_km = dist_interchanges / 1000"
r.mapcalc "road_dens_perc = road_dens * 100"
r.mapcalc "forest_smooth_perc = forest_smooth * 100"
</source>

=== Sampling ===
To sample only in the analyzed counties, we will clip development layer:

<source lang="bash">
r.mapcalc "urban_change_01_11 = if(urban_2011 == 1, if(urban_2001 == 0, 1, null()), 0)"
r.mapcalc "urban_change_clip = if(counties, urban_change_01_11)"
</source>

To estimate the number of sampling points, we can use {{cmd|r.report}} to report number of developed/undeveloped cells and their ratio.

<source lang="bash">
r.report map=urban_change_clip units=h,c,p
</source>

We will sample the predictors and the response variable with 5000 random points in undeveloped areas and 1000 points in developed area:

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.sample.category input=urban_change_clip output=sampling sampled=counties,devpressure_0_5,devpressure_1,devpressure_2,slope,road_dens_perc,forest_smooth_perc,dist_to_water_km,dist_to_protected_km,dist_interchanges_km,travel_time_cities npoints=5000,1000
</source>

The attribute table can be exported as CSV file (not necessary step):

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
v.db.select map=sampling columns=urban_change_clip,counties,devpressure_0_5,devpressure_1,slope,road_dens_perc,forest_smooth_perc,dist_to_water_km,dist_to_protected_km,dist_interchanges_km,travel_time_cities separator=comma file=samples.csv
</source>

=== Development potential ===
Now we find best model for predicting urbanization using {{AddonCmd|r.futures.potential}} which wraps an R script.

We can run R [http://www.inside-r.org/packages/cran/MuMIn/docs/dredge dredge] function to find "best" model. We can specify minimum and maximum number of predictors the final model should use.
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.potential -d input=sampling output=potential.csv columns=devpressure_1,slope,road_dens_perc,forest_smooth_perc,dist_to_water_km,dist_to_protected_km,dist_interchanges_km,travel_time_cities developed_column=urban_change_clip subregions_column=counties min_variables=4
</source>

Also, we can play with different combinations of predictors, for example:

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.potential input=sampling output=potential.csv columns=devpressure_2,road_dens_perc,slope,dist_interchanges_km,dist_to_water_km developed_column=urban_change_clip subregions_column=counties --o
r.futures.potential input=sampling output=potential.csv columns=devpressure_1,road_dens_perc,slope,dist_interchanges_km,dist_to_water_km developed_column=urban_change_clip subregions_column=counties --o
...
</source>

You can then open the output file <tt>potential.csv</tt>, which is a CSV file with tabs as separators.

For this tutorial, the final potential is created with:
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.potential input=sampling output=potential.csv columns=devpressure_2,road_dens_perc,slope,dist_interchanges_km,dist_to_water_km developed_column=urban_change_clip subregions_column=counties --o
</source>

We can now visualize the suitability surface using module {{AddonCmd|r.futures.potsurface}}. It creates initial development potential (suitability) raster from predictors and model coefficients and serves only for evaluating development potential model. The values of the resulting raster range from 0 to 1.

<source lang="bash">
r.futures.potsurface input=potential.csv subregions=counties output=suitability
r.colors map=suitability color=byr
</source>

== Demand submodel ==
First we will mask out roads so that they don't influence into per capita land demand relation.
<source lang="bash">
v.to.rast input=roads type=line output=roads_mask use=val
r.mask roads_mask -i
</source>

We will use {{AddonCmd|r.futures.demand}} which derives the population vs. development relation. The relation can be linear/logarithmic/logarithmic2/exponential/exponential approach.
Look for examples of the different relations in the manual.

* linear: y = A + Bx
* logarithmic: y = A + Bln(x)
* logarithmic2: y = A + B * ln(x - C)        (requires SciPy)
* exponential: y = Ae^(BX)
* exp_approach: y = (1 - e^(-A(x - B))) + C        (requires SciPy)

The format of the input population CSV files is described in the manual. It is important to have synchronized categories of subregions and the column headers of the CSV files (in our case FIPS number). How to simply generate the list of years (for which demand is computed) is described in {{AddonCmd|r.futures.demand}} manual, for example run this in Python console:

<source lang="python">
','.join([str(i) for i in range(2011, 2036)])
</source>

Then we can create the DEMAND file:
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.demand development=urban_1992,urban_2001,urban_2011 subregions=counties observed_population=population_trend.csv projected_population=population_projection.csv simulation_times=2011,2012,2013,2014,2015,2016,2017,2018,2019,2020,2021,2022,2023,2024,2025,2026,2027,2028,2029,2030,2031,2032,2033,2034,2035 plot=plot_demand.pdf demand=demand.csv separator=comma
</source>

In your current working directory, you should find files <tt>plot_demand.png</tt> and <tt>demand.csv</tt>.

If you have SciPy installed, you can experiment with other methods for fitting the functions:
<source lang="bash">
r.futures.demand ... method=logarithmic2
r.futures.demand ... method=exp_approach
</source>
If necessary, you can create a set of demand files produced by fitting each method separately and
then pick for each county the method which seems best and manually create a new demand file.

When you are finished, remove the mask as it is not needed for the next steps.
<source lang="bash">
r.mask -r
</source>

== Patch calibration ==
Patch calibration can be a very time consuming computation.
Therefore we select only one county (Buncombe):

<source lang="bash">
v.to.rast input=counties type=area where="FIPS == 37021" use=attr attribute_column=FIPS output=calib_county
g.region raster=calib_county zoom=calib_county
</source>
to derive patches of new development by comparing historical and latest development.
We can keep only patches with minimum size 2 cells (1800 = 2 x 30 x 30 m).

<source lang="bash">
r.futures.calib development_start=urban_1992 development_end=urban_2011 subregions=counties patch_sizes=patches.txt patch_threshold=1800 -l
</source>
We obtained a file <tt>patches.txt</tt> (used later in the PGA) - a patch size distribution file - containing sizes of all found patches.

We can look at the distribution of the patch sizes:

<source lang="python">
from matplotlib import pyplot as plt
with open('patches.txt') as f:
patches = [int(patch) for patch in f.readlines()]
plt.hist(patches, 2000)
plt.xlim(0,50)
plt.show()
</source>

At this point, we start the calibration to get best parameters of patch shape
(for this tutorial, this step can be skipped and the suggested parameters are used).

<source lang="bash"
style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.calib development_start=urban_1992 development_end=urban_2011 subregions=calib_county patch_sizes=patches.txt calibration_results=calib.csv patch_threshold=1800 repeat=5 compactness_mean=0.1,0.3,0.5,0.7,0.9 compactness_range=0.05 discount_factor=0.1,0.3,0.5,0.7,0.9 predictors=road_dens_perc,forest_smooth_perc,dist_to_protected_km demand=demand.csv devpot_params=potential.csv num_neighbors=4 seed_search=2 development_pressure=devpressure_0_5 development_pressure_approach=gravity n_dev_neighbourhood=30 gamma=0.5 scaling_factor=0.1
</source>

== FUTURES simulation ==
We will switch back to our previous region:
<source lang="bash">
g.region raster=landuse_2011 -p
</source>

Now we have all the inputs necessary for running {{AddonCmd|r.futures.pga}}:

The entire command is here:
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.pga subregions=counties developed=urban_2011 predictors=slope,forest_smooth_perc,dist_interchanges_km,travel_time_cities devpot_params=potential.csv development_pressure=devpressure_1 n_dev_neighbourhood=10 development_pressure_approach=gravity gamma=1 scaling_factor=1 demand=demand.csv discount_factor=0.3 compactness_mean=0.2 compactness_range=0.1 patch_sizes=patches.txt num_neighbors=4 seed_search=2 random_seed=1 output=final output_series=final
</source>

=== Quick description ===
The command parameters and their values:
* raster map of counties with their categories
<code>
... subregions=counties ...
</code>

* raster of developed (1), undeveloped (0) and NULLs for undevelopable areas
<code>
... developed=urban_2011 ...
</code>

* predictors selected with {{AddonCmd|r.futures.potential}} and their coefficients in a <tt>potential.csv</tt> file. The order of predictors must match the order in the file and the categories of the counties must match raster <tt>counties</tt>.
<code>
... predictors=slope,forest_smooth_perc,dist_interchanges_km,travel_time_cities devpot_params=potential.csv ...
</code>

* initial development pressure computed by {{AddonCmd|r.futures.devpressure}}, it's important to set here the same parameters
<code>
... development_pressure=devpressure_1 n_dev_neighbourhood=10 development_pressure_approach=gravity gamma=1 scaling_factor=1 ...
</code>

* per capita land demand computed by {{AddonCmd|r.futures.demand}}, the categories of the counties must match raster <tt>counties</tt>.
<code>
... demand=demand.csv ...
</code>

* patch parameters from the calibration step
<code>
... discount_factor=0.3 compactness_mean=0.4 compactness_range=0.08 patch_sizes=patches.txt ...
</code>

* recommended parameters for patch growing algorithm
<code>
... num_neighbors=4 seed_search=2 ...
</code>

* set random seed for repeatable results or set flag <tt>-s</tt> to generate seed automatically
<code>
... random_seed=1 ...
</code>

* specify final output map and optionally basename for intermediate raster maps
<code>
output=final output_series=final
</code>

== Scenarios ==
Scenarios involving policies that encourage infill versus sprawl can be explored using the <tt>incentive_power</tt> parameter of {{AddonCmd|r.futures.pga}},
which uses a power function to transform the evenness of the probability gradient in POTENTIAL. You can change the power to a number between 0.25 and 4 to test urban sprawl/infill scenarios.
Higher power leads to infill behavior, lower power to urban sprawl.

== Postprocessing ==

Follow a [[Creating_animation_from_FUTURES_output_in_GRASS_GIS| tutorial how to make an animation from the results]].

= GRASS GIS Python API =

[[Category: Tutorial]]
[[Category: FUTURES]]
[[Category: Urban]]

Workshop on urban growth modeling with FUTURES

2016-03-22T21:12:18Z

⚠️Dbvanber: /* Forests */

{{ToModify}}
= Workshop introduction =
r.futures.* is an implementation of the '''FUT'''ure '''U'''rban-'''R'''egional '''E'''nvironment '''S'''imulation (FUTURES)[1] which is a model for multilevel simulations of emerging urban-rural landscape structure. FUTURES produces regional projections of landscape patterns using coupled submodels that integrate nonstationary drivers of land change: per capita demand (DEMAND submodel), site suitability (POTENTIAL submodel), and the spatial structure of conversion events (PGA submodel).

[1] Meentemeyer, R. K., Tang, W., Dorning, M. A., Vogler, J. B., Cunniffe, N. J., & Shoemaker, D. A. (2013). [http://www.tandfonline.com/doi/abs/10.1080/00045608.2012.707591 FUTURES: multilevel simulations of emerging urban-rural landscape structure using a stochastic patch-growing algorithm.] Annals of the Association of American Geographers, 103(4), 785-807

== Software ==
There are a number of software requirements to run FUTURES that will need to be download and installed. Required software includes:
* GRASS GIS 7
* addons
** {{AddonCmd|r.futures.pga}}
** {{AddonCmd|r.futures.potential}}
** {{AddonCmd|r.futures.potsurface}}
** {{AddonCmd|r.futures.demand}}
** {{AddonCmd|r.futures.devpressure}}
** {{AddonCmd|r.sample.category}}
* R (≥ 3.0.2) - needed for {{AddonCmd|r.futures.potential}} with packages:
**MuMIn, lme4, optparse, rgrass7
* SciPy - useful for {{AddonCmd|r.futures.demand}}

=== Installation ===
We use the R statistical software for our calculation of site suitability (i.e. development potential) in FUTURES. R is a free software environment for statistical computing and graphics. If you don't have R, or you have older an version, please download and install the software from [http://archive.linux.duke.edu/cran/ install R] and be sure to additionally add these required packages:
<pre>
install.packages(c("MuMIn", "lme4", "optparse", "rgrass7"))
</pre>

==== MS Windows ====
We will be using GRASS GIS 7.0.3 that can be found here in the [https://trac.osgeo.org/osgeo4w/ OSGeo4W] package manager.
Please install the latest stable GRASS GIS 7 version and the SciPy Python package using the ''Advanced install'' option.
A guide with step by step screen shot instructions is available [https://docs.google.com/presentation/d/1yEGpriBne7RvjB35HI6GecNwO1P1y2nRGqDThqoNnCE/edit?usp=sharing here].

In order for GRASS to be able to find R executables, GRASS must be on the PATH variable. Follow this [solution] to make R accessible from GRASS permanently.
A simple but temporary solution is to open GRASS GIS and paste this in the black terminal:
<pre>
set PATH=%PATH%;C:\Program Files\R\R-3.0.2\bin
</pre>
This has to be repeated after restarting GRASS session.

==== Ubuntu Linux ====
Install GRASS GIS from packages:
<pre>
sudo add-apt-repository ppa:ubuntugis/ubuntugis-unstable
sudo apt-get update
sudo apt-get install grass
</pre>

== Workshop data ==
The data that we will be using for the workshop can be download here: [http://fatra.cnr.ncsu.edu/futures/futures_ncspm_Asheville.zip sample dataset]. Please place these layers in your local GRASS directory:
* digital elevation model ([http://nationalmap.gov/elevation.html NED])
* [http://www.mrlc.gov/ NLCD] 2001, 2011
* NLCD 1992/2001 Retrofit Land Cover Change Product
* transportation network ([http://www.census.gov/geo/maps-data/data/tiger-line.html TIGER])
* county boundaries ([http://www.census.gov/geo/maps-data/data/tiger-line.html TIGER])
* protected areas ([http://www.conservationgateway.org/ConservationByGeography/NorthAmerica/UnitedStates/edc/reportsdata/terrestrial/secured/Pages/default.aspx Secured Lands])
* cities as points (USGS)

In addition, download [http://fatra.cnr.ncsu.edu/futures/futures_Asheville_files.zip population information as text files]:
* county population past estimates and future projections ([https://www.osbm.nc.gov/demog/county-projections NC OSBM]) per county (nonspatial)

= GRASS GIS introduction =
There are many advantages to using the open source GRASS GIS platform, but for many that are more familiar with ARCGis and QGis, the setup and implementation of spatial tools in GRASS can be confusing. Here we provide an overview of the GRASS GIS project: [https://grass.osgeo.org grass.osgeo.org] that might be helpful to review if you are a first time users. For this exercise it's not necessary to have a full understanding of how to use GRASS. However, you will need to know how to place your data in the correct GRASS database directory, as well as some basic GRASS functionality. Step by step instructions are provided below
== Setting up GRASS for the tutorial ==
GRASS uses unique database terminology and structure ([https://grass.osgeo.org/grass71/manuals/grass_database.html GRASS database]) that are important to understand for the set up of this tutorial, as you will need to place the required data (e.g. Mapset) in a specific GRASS database Location. In the following we review important terminology and give step by step direction on how to download and place you data in the correct location.

=== Important GRASS directory terminology ===
* A '''GRASS database''' consist of directory with specific Locations (projects) where data layer are stored
* '''Location''' hold all Mapsets in a specific directoy that have the same spatial projection (spatial reference system)
* '''Mapset''' are a collection of maps with the same spatial projection

=== Creating a GRASS database for the tutorial ===
You need to create a GRASS database with the Mapset that we will use for the tutorial before we can run the FUTURES model. Please Download the [http://fatra.cnr.ncsu.edu/futures/futures_ncspm_Asheville.zip workshop location], noting where the files are located on your local directory. Now, create (unless you already have it) a directory named <tt>grassdata</tt> (GRASS database) in your home folder (or Documents), unzip the downloaded data into this directory. You should now have a Location <tt>futures_ncspm</tt> in <tt>grassdata</tt>.

<center><gallery perrow=1 widths=500 heights=250>Image:GRASS FUTURES startup.png|GRASS GIS 7.0.3 startup dialog with downloaded Location and Mapsets for FUTURES workshop</gallery></center>

=== Launching and exploring data in GRASS ===
Now that we have the data in the correct GRASS database, we can launch the Graphical User Interface (GUI). The GUI interface allows you to display raster, vector data as well as navigate through zooming in and out. Advanced exploration and visualization, like many popular GIS software, is also possible in GRASS (e.g. queries, adding legend). The print screens below depicts how you can add different map layers (left) and display the metadata of your data layers.

<center><gallery perrow=2 widths=500 heights=250>Image:GRASS FUTURES wxGUI display.png|Layer Manager and Map Display overview. Annotations show how to add raster layer, query, add legend.
Image:wxGUI_metadata_rinfo.png|Show raster map metadata by right click on layer</gallery></center>

== GRASS functionality ==
One of the advantage of GRASS is the diversity and number of module addons that let you analyze all manner of spatial and temporal. Because it is open source modules are added daily increasing functionality and methods for analysis of your data. GRASS GIS has over [https://grass.osgeo.org/grass70/manuals/full_index.html 500 different modules] in the core distribution and over [https://grass.osgeo.org/grass70/manuals/addons/ 230 addon modules] that can be used to prepare and analyze data layers.
<center>
{| class="wikitable"
|-
! Prefix !! Function !! Example
|-
| r.* || raster processing || ''{{cmd|r.mapcalc}}'': map algebra
|-
| v.* || vector processing || ''{{cmd|v.clean}}'': topological cleaning
|-
| i.* || imagery processing || ''{{cmd|i.segment}}'': object recognition
|-
| db.* || database management || ''{{cmd|db.select}}'': select values from table
|-
| r3.* || 3D raster processing || ''{{cmd|r3.stats}}'': 3D raster statistics
|-
| t.* || temporal data processing || ''{{cmd|t.rast.aggregate}}'': temporal aggregation
|-
| g.* || general data management || ''{{cmd|g.rename}}'': renames map
|-
| d.* || display ||''{{cmd|d.rast}}'': display raster map
|}</center>

=== Command line vs. GUI interface===
GRASS modules can be executed either through a GUI or command line interface. The GUI offers a user-friendly approach to executing modules where the user can navigate to data layers that they would like to analyze and modify processing options with simple check boxes. The GUI also offer a easily accessible manual on how to execute a model. The command line interface allows users to execute a module using command prompts specific to that module. This is handy when you are running similar analyses with minor modification or are familiar with the module commands for quick efficient processing. In this workshop we provide module prompts that can be copy and pasted into the command line for our workflow, but you can use both GUI and command line depending on personal preference. Look how {{cmd|wxGUI.modules|version=71|desc=GUI and command line interface}} represent the same tool. ''Task:'' compute aspect (orientation) from provided digital elevation model using module {{cmd|r.slope.aspect}} using both module dialog and command line.
* How to find modules? Modules are organized by their functionality in wxGUI menu, or we can search for them in Search modules tab. If we already know which module to use, we can just type it in the wxGUI command console. <center><gallery perrow=3 widths=380 heights=190>Image:wxGUI_menu_rinfo.png|Modules can be found in wxGUI menu
Image:wxGUI_module_search.png|You can search modules by name, description or keywords in ''Search modules'' tab
Image:wxGUI_console_completion.png|By typing prefix r. we make a list of modules starting with that prefix to show up.</gallery></center>

=== Computational region===

{{cmd|g.region|desc=Computational region}} - is an important raster concept in GRASS that needs some explanation. In GRASS a computational region can be set, subsetting larger extent data for quicker testing of analysis or analysis of specific regions based on adminstrative units. We provide a few points to keep in mind when using the computational region function:
* defined by region extent and raster resolution
* applies to all raster operations
* persists between GRASS session, can be different for different mapsets
* advantages: keeps your results consistent, avoid clipping, for computationally demanding tasks set region to smaller extent, check your result is good and then set the computational region to the entire study area and rerun analysis
* run <code>g.region -p</code> or in menu ''Settings'' - ''Region'' - ''Display region'' to see current region settings
[[File:WxGUI set region.png|700px|thumb|center|Simple ways to set computational region from GUI. On the left, set region to match raster map. On the right, select the highlighted option and then set region by drawing rectangle.]]

* GRASS 3D view

= Modeling with FUTURES =
== Initial steps and data preparation ==
First we will set the computational region of our analyses to an extent covering our study area that aligns with our base landuse rasters. ''Like explained in the instructions above, you simply need copy and paste these commands into the command prompt of GRASS''.
<source lang="bash">g.region raster=landuse_2011 -p</source>

The FUTURES model uses the locations of development and new development to predict when and where new urban growth will occur. This requires longitudinal data on urban land use. We will derive urbanized areas from NLCD dataset for year 1992, 2001 and 2011
by extracting categories category 21 - 24 into a new binary map where developed is 1,
undeveloped 0 and NULL (no data). The NULL area is important in simulating urban growth as it preclude these are from becoming development. For this exercise we assume that water, wetlands and protected areas can not be developed, setting them to NULL.
First we will convert protected areas from vector to raster. We set
NULLs to zeros (for simpler raster algebra expression in the next step) using {{cmd|r.null}}:

<source lang="bash">
v.to.rast input=protected_areas output=protected_areas use=val
r.null map=protected_areas null=0
</source>

And then create rasters of developed/undeveloped areas using raster algebra:

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.mapcalc "urban_1992 = if(landuse_1992 >= 21 && landuse_1992 <= 24, 1, if(landuse_1992 == 11 || landuse_1992 >= 90 || protected_areas, null(), 0))"
r.mapcalc "urban_2001 = if(landuse_2001 >= 21 && landuse_2001 <= 24, 1, if(landuse_2001 == 11 || landuse_2001 >= 90 || protected_areas, null(), 0))"
r.mapcalc "urban_2011 = if(landuse_2011 >= 21 && landuse_2011 <= 24, 1, if(landuse_2011 == 11 || landuse_2011 >= 90 || protected_areas, null(), 0))"
</source>

FUTURES is a multi-level modelling framework meaning that we model population projections for subregions and assume that these subregions are influenced differently by the factors that influence where development happens. This requires defining subregions for model implementation. For this exercise we use the county level, which is the finest scale of population data that is available to us. We therefore need to convert vectors of counties to a raster with the values of the FIPS attribute which links to population file:

<source lang="bash">
v.to.rast input=counties type=area use=attr attribute_column=FIPS output=counties
</source>

Before further steps, we will set our working directory so that the input population files and text files
we are going to create are saved in one directory and easily accessible.
You can do that from menu ''Settings'' → ''GRASS working environment'' → ''Change working directory''.
Select (or create) a directory and move there the downloaded files <tt>population_projection.csv</tt> and <tt>population_trend.csv</tt>.

== Potential submodel ==
Module {{AddonCmd|r.futures.potential}} implements the POTENTIAL submodel as a part of FUTURES land change model. POTENTIAL is implemented using a set of coefficients that relate a selection of site suitability factors to the probability of a place becoming developed. This is implemented using the parameter table in combination with maps of those site suitability factors (mapped predictors). The coefficients are obtained by conducting multilevel logistic regression in R with package lme4 where the coefficients may vary by county. The best model is selected automatically using dredge function from package [https://cran.r-project.org/web/packages/MuMIn/index.html MuMIn].

First, we will derive possible predictors of urban growth using GRASS modules.
=== Predictors ===
==== Slope ====
Slope possibly influences urban growth as steep areas are difficult to build on. We will derive slope in degrees from digital elevation model using {{cmd|r.slope.aspect}} module:
<source lang="bash">r.slope.aspect elevation=elevation_30m slope=slope</source>

==== Distance from lakes/rivers ====
Distance to lakes or rivers may contribute to an amenity draw where people would like to build a house in a location where they can view water. First we will extract [http://www.mrlc.gov/nlcd11_leg.php category ''Open Water''] from 2011 NLCD dataset:
<source lang="bash">
r.mapcalc "water = if(landuse_2011 == 11, 1, null())"
</source>

Then we compute the distance to water with module {{cmd|r.grow.distance}} and set color table to shades of blue:
<source lang="bash">
r.grow.distance input=water distance=dist_to_water
r.colors -n map=dist_to_water color=blues
</source>

==== Distance from protected areas ====
Like water protected areas can attract urban growth as people enjoy living near scenic areas. We will use raster protected of protected areas we already created, but we will set NULL values to zero.
We compute the distance to protected areas with module {{cmd|r.grow.distance}} and set color table from green to red:
<source lang="bash">
r.null map=protected_areas setnull=0
r.grow.distance input=protected_areas distance=dist_to_protected
r.colors map=dist_to_protected color=gyr
</source>

==== Forests ====
Forest may influence urban growth in different ways. On the one hand it might be costly for developments as tree will need to be removed. On the other hand, people may want to live near forests. We calculate the percentage forest for a 1 km pixel to test forest influence, see NLCD [http://www.mrlc.gov/nlcd11_leg.php category ''Open Water'']:
<source lang="bash">
r.mapcalc "forest = if(landuse_2011 >= 41 && landuse_2011 <= 43, 1, 0)"
r.neighbors -c input=forest output=forest_smooth size=15 method=average
r.colors map=forest_smooth color=ndvi
</source>

==== Travel time to cities ====
Here we will compute travel time to cities (with population > 5000)
as cumulative cost distance where cost is defined as travel time on roads.
First we specify the speed on different types of roads.
We copy the roads raster into our mapset so that we can change it
by adding a new attribute field <tt>speed</tt>. Then we assign speed values (km/h) based on the type of road:

<source lang="bash">
g.copy vector=roads,myroads
v.db.addcolumn map=myroads columns="speed double precision"
v.db.update map=myroads column=speed value=50 where="MTFCC = 'S1400'"
v.db.update map=myroads column=speed value=100 where="MTFCC IN ('S1100', 'S1200')"
</source>

Now we rasterize the selected road types using the speed values from the attribute table as raster values.

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
v.to.rast input=myroads type=line where="MTFCC IN ('S1100', 'S1200', 'S1400')" output=roads_speed use=attr attribute_column=speed
</source>

We set the rest of the area to low speed and recompute the speed as time to travel through a 30m cell in minutes:

<source lang="bash">
r.null map=roads_speed null=5
r.mapcalc "roads_travel_time = 1.8 / roads_speed"
</source>

Finally we compute the travel time to larger cities using {{cmd|r.cost}}:

<source lang="bash">
r.cost input=roads_travel_time output=travel_time_cities start_points=cities
r.colors map=travel_time_cities color=byr
</source>

==== Road density ====
We will rasterize roads and use moving window analysis ({{cmd|r.neighbors}}) to compute road density:

<source lang="bash">
v.to.rast input=roads output=roads use=val type=line
r.null map=roads null=0
r.neighbors -c input=roads output=road_dens size=25 method=average
</source>

==== Distance to interchanges ====

We will consider TIGER roads of type <tt>Ramp</tt> as interchanges, rasterize them and compute euclidean distance to them:

<source lang="bash">
v.to.rast input=roads type=line where="MTFCC = 'S1630'" output=interchanges use=val
r.grow.distance -m input=interchanges distance=dist_interchanges
</source>

=== Development pressure ===

We compute development pressure with {{AddonCmd|r.futures.devpressure}}. Development pressure is a predictor based on number of neighboring developed cells within search distance, weighted by distance. The development pressure variable plays a special role in the model, allowing for a feedback between predicted change and change in subsequent steps.

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.devpressure -n input=urban_2011 output=devpressure_2 method=gravity size=7 gamma=2 scaling_factor=10
r.futures.devpressure -n input=urban_2011 output=devpressure_1 method=gravity size=10 gamma=1 scaling_factor=1
r.futures.devpressure -n input=urban_2011 output=devpressure_0_5 method=gravity size=30 gamma=0.5 scaling_factor=0.1
</source>

When gamma increases, development influence decreases more rapidly with distance.
Size is half the size of the moving window. When gamma is low, local development influences more distant places.
We will derive 3 layers with different gamma and size parameters for the potential statistical model.

=== Rescaling variables ===

First we will look at the ranges of our predictor variables by running a short Python code snippet in Python shell:

<source lang="python" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
for name in ['slope', 'dist_to_water', 'dist_to_protected', 'forest_smooth', 'travel_time_cities', 'road_dens', 'dist_interchanges', 'devpressure_0_5', 'devpressure_1']:
minmax = grass.raster_info(name)
print name, minmax['min'], minmax['max']
</source>

We will rescale some of our input variables:

<source lang="bash">
r.mapcalc "dist_to_water_km = dist_to_water / 1000"
r.mapcalc "dist_to_protected_km = dist_to_protected / 1000"
r.mapcalc "dist_interchanges_km = dist_interchanges / 1000"
r.mapcalc "road_dens_perc = road_dens * 100"
r.mapcalc "forest_smooth_perc = forest_smooth * 100"
</source>

=== Sampling ===
To sample only in the analyzed counties, we will clip development layer:

<source lang="bash">
r.mapcalc "urban_change_01_11 = if(urban_2011 == 1, if(urban_2001 == 0, 1, null()), 0)"
r.mapcalc "urban_change_clip = if(counties, urban_change_01_11)"
</source>

To estimate the number of sampling points, we can use {{cmd|r.report}} to report number of developed/undeveloped cells and their ratio.

<source lang="bash">
r.report map=urban_change_clip units=h,c,p
</source>

We will sample the predictors and the response variable with 5000 random points in undeveloped areas and 1000 points in developed area:

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.sample.category input=urban_change_clip output=sampling sampled=counties,devpressure_0_5,devpressure_1,devpressure_2,slope,road_dens_perc,forest_smooth_perc,dist_to_water_km,dist_to_protected_km,dist_interchanges_km,travel_time_cities npoints=5000,1000
</source>

The attribute table can be exported as CSV file (not necessary step):

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
v.db.select map=sampling columns=urban_change_clip,counties,devpressure_0_5,devpressure_1,slope,road_dens_perc,forest_smooth_perc,dist_to_water_km,dist_to_protected_km,dist_interchanges_km,travel_time_cities separator=comma file=samples.csv
</source>

=== Development potential ===
Now we find best model for predicting urbanization using {{AddonCmd|r.futures.potential}} which wraps an R script.

We can run R [http://www.inside-r.org/packages/cran/MuMIn/docs/dredge dredge] function to find "best" model. We can specify minimum and maximum number of predictors the final model should use.
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.potential -d input=sampling output=potential.csv columns=devpressure_1,slope,road_dens_perc,forest_smooth_perc,dist_to_water_km,dist_to_protected_km,dist_interchanges_km,travel_time_cities developed_column=urban_change_clip subregions_column=counties min_variables=4
</source>

Also, we can play with different combinations of predictors, for example:

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.potential input=sampling output=potential.csv columns=devpressure_2,road_dens_perc,slope,dist_interchanges_km,dist_to_water_km developed_column=urban_change_clip subregions_column=counties --o
r.futures.potential input=sampling output=potential.csv columns=devpressure_1,road_dens_perc,slope,dist_interchanges_km,dist_to_water_km developed_column=urban_change_clip subregions_column=counties --o
...
</source>

You can then open the output file <tt>potential.csv</tt>, which is a CSV file with tabs as separators.

For this tutorial, the final potential is created with:
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.potential input=sampling output=potential.csv columns=devpressure_2,road_dens_perc,slope,dist_interchanges_km,dist_to_water_km developed_column=urban_change_clip subregions_column=counties --o
</source>

We can now visualize the suitability surface using module {{AddonCmd|r.futures.potsurface}}. It creates initial development potential (suitability) raster from predictors and model coefficients and serves only for evaluating development potential model. The values of the resulting raster range from 0 to 1.

<source lang="bash">
r.futures.potsurface input=potential.csv subregions=counties output=suitability
r.colors map=suitability color=byr
</source>

== Demand submodel ==
First we will mask out roads so that they don't influence into per capita land demand relation.
<source lang="bash">
v.to.rast input=roads type=line output=roads_mask use=val
r.mask roads_mask -i
</source>

We will use {{AddonCmd|r.futures.demand}} which derives the population vs. development relation. The relation can be linear/logarithmic/logarithmic2/exponential/exponential approach.
Look for examples of the different relations in the manual.

* linear: y = A + Bx
* logarithmic: y = A + Bln(x)
* logarithmic2: y = A + B * ln(x - C)        (requires SciPy)
* exponential: y = Ae^(BX)
* exp_approach: y = (1 - e^(-A(x - B))) + C        (requires SciPy)

The format of the input population CSV files is described in the manual. It is important to have synchronized categories of subregions and the column headers of the CSV files (in our case FIPS number). How to simply generate the list of years (for which demand is computed) is described in {{AddonCmd|r.futures.demand}} manual, for example run this in Python console:

<source lang="python">
','.join([str(i) for i in range(2011, 2036)])
</source>

Then we can create the DEMAND file:
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.demand development=urban_1992,urban_2001,urban_2011 subregions=counties observed_population=population_trend.csv projected_population=population_projection.csv simulation_times=2011,2012,2013,2014,2015,2016,2017,2018,2019,2020,2021,2022,2023,2024,2025,2026,2027,2028,2029,2030,2031,2032,2033,2034,2035 plot=plot_demand.pdf demand=demand.csv separator=comma
</source>

In your current working directory, you should find files <tt>plot_demand.png</tt> and <tt>demand.csv</tt>.

If you have SciPy installed, you can experiment with other methods for fitting the functions:
<source lang="bash">
r.futures.demand ... method=logarithmic2
r.futures.demand ... method=exp_approach
</source>
If necessary, you can create a set of demand files produced by fitting each method separately and
then pick for each county the method which seems best and manually create a new demand file.

When you are finished, remove the mask as it is not needed for the next steps.
<source lang="bash">
r.mask -r
</source>

== Patch calibration ==
Patch calibration can be a very time consuming computation.
Therefore we select only one county (Buncombe):

<source lang="bash">
v.to.rast input=counties type=area where="FIPS == 37021" use=attr attribute_column=FIPS output=calib_county
g.region raster=calib_county zoom=calib_county
</source>
to derive patches of new development by comparing historical and latest development.
We can keep only patches with minimum size 2 cells (1800 = 2 x 30 x 30 m).

<source lang="bash">
r.futures.calib development_start=urban_1992 development_end=urban_2011 subregions=counties patch_sizes=patches.txt patch_threshold=1800 -l
</source>
We obtained a file <tt>patches.txt</tt> (used later in the PGA) - a patch size distribution file - containing sizes of all found patches.

We can look at the distribution of the patch sizes:

<source lang="python">
from matplotlib import pyplot as plt
with open('patches.txt') as f:
patches = [int(patch) for patch in f.readlines()]
plt.hist(patches, 2000)
plt.xlim(0,50)
plt.show()
</source>

At this point, we start the calibration to get best parameters of patch shape
(for this tutorial, this step can be skipped and the suggested parameters are used).

<source lang="bash"
style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.calib development_start=urban_1992 development_end=urban_2011 subregions=calib_county patch_sizes=patches.txt calibration_results=calib.csv patch_threshold=1800 repeat=5 compactness_mean=0.1,0.3,0.5,0.7,0.9 compactness_range=0.05 discount_factor=0.1,0.3,0.5,0.7,0.9 predictors=road_dens_perc,forest_smooth_perc,dist_to_protected_km demand=demand.csv devpot_params=potential.csv num_neighbors=4 seed_search=2 development_pressure=devpressure_0_5 development_pressure_approach=gravity n_dev_neighbourhood=30 gamma=0.5 scaling_factor=0.1
</source>

== FUTURES simulation ==
We will switch back to our previous region:
<source lang="bash">
g.region raster=landuse_2011 -p
</source>

Now we have all the inputs necessary for running {{AddonCmd|r.futures.pga}}:

The entire command is here:
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.pga subregions=counties developed=urban_2011 predictors=slope,forest_smooth_perc,dist_interchanges_km,travel_time_cities devpot_params=potential.csv development_pressure=devpressure_1 n_dev_neighbourhood=10 development_pressure_approach=gravity gamma=1 scaling_factor=1 demand=demand.csv discount_factor=0.3 compactness_mean=0.2 compactness_range=0.1 patch_sizes=patches.txt num_neighbors=4 seed_search=2 random_seed=1 output=final output_series=final
</source>

=== Quick description ===
The command parameters and their values:
* raster map of counties with their categories
<code>
... subregions=counties ...
</code>

* raster of developed (1), undeveloped (0) and NULLs for undevelopable areas
<code>
... developed=urban_2011 ...
</code>

* predictors selected with {{AddonCmd|r.futures.potential}} and their coefficients in a <tt>potential.csv</tt> file. The order of predictors must match the order in the file and the categories of the counties must match raster <tt>counties</tt>.
<code>
... predictors=slope,forest_smooth_perc,dist_interchanges_km,travel_time_cities devpot_params=potential.csv ...
</code>

* initial development pressure computed by {{AddonCmd|r.futures.devpressure}}, it's important to set here the same parameters
<code>
... development_pressure=devpressure_1 n_dev_neighbourhood=10 development_pressure_approach=gravity gamma=1 scaling_factor=1 ...
</code>

* per capita land demand computed by {{AddonCmd|r.futures.demand}}, the categories of the counties must match raster <tt>counties</tt>.
<code>
... demand=demand.csv ...
</code>

* patch parameters from the calibration step
<code>
... discount_factor=0.3 compactness_mean=0.4 compactness_range=0.08 patch_sizes=patches.txt ...
</code>

* recommended parameters for patch growing algorithm
<code>
... num_neighbors=4 seed_search=2 ...
</code>

* set random seed for repeatable results or set flag <tt>-s</tt> to generate seed automatically
<code>
... random_seed=1 ...
</code>

* specify final output map and optionally basename for intermediate raster maps
<code>
output=final output_series=final
</code>

== Scenarios ==
Scenarios involving policies that encourage infill versus sprawl can be explored using the <tt>incentive_power</tt> parameter of {{AddonCmd|r.futures.pga}},
which uses a power function to transform the evenness of the probability gradient in POTENTIAL. You can change the power to a number between 0.25 and 4 to test urban sprawl/infill scenarios.
Higher power leads to infill behavior, lower power to urban sprawl.

== Postprocessing ==

Follow a [[Creating_animation_from_FUTURES_output_in_GRASS_GIS| tutorial how to make an animation from the results]].

= GRASS GIS Python API =

[[Category: Tutorial]]
[[Category: FUTURES]]
[[Category: Urban]]

Workshop on urban growth modeling with FUTURES

2016-03-22T21:08:35Z

⚠️Dbvanber: /* Distance from protected areas */

{{ToModify}}
= Workshop introduction =
r.futures.* is an implementation of the '''FUT'''ure '''U'''rban-'''R'''egional '''E'''nvironment '''S'''imulation (FUTURES)[1] which is a model for multilevel simulations of emerging urban-rural landscape structure. FUTURES produces regional projections of landscape patterns using coupled submodels that integrate nonstationary drivers of land change: per capita demand (DEMAND submodel), site suitability (POTENTIAL submodel), and the spatial structure of conversion events (PGA submodel).

[1] Meentemeyer, R. K., Tang, W., Dorning, M. A., Vogler, J. B., Cunniffe, N. J., & Shoemaker, D. A. (2013). [http://www.tandfonline.com/doi/abs/10.1080/00045608.2012.707591 FUTURES: multilevel simulations of emerging urban-rural landscape structure using a stochastic patch-growing algorithm.] Annals of the Association of American Geographers, 103(4), 785-807

== Software ==
There are a number of software requirements to run FUTURES that will need to be download and installed. Required software includes:
* GRASS GIS 7
* addons
** {{AddonCmd|r.futures.pga}}
** {{AddonCmd|r.futures.potential}}
** {{AddonCmd|r.futures.potsurface}}
** {{AddonCmd|r.futures.demand}}
** {{AddonCmd|r.futures.devpressure}}
** {{AddonCmd|r.sample.category}}
* R (≥ 3.0.2) - needed for {{AddonCmd|r.futures.potential}} with packages:
**MuMIn, lme4, optparse, rgrass7
* SciPy - useful for {{AddonCmd|r.futures.demand}}

=== Installation ===
We use the R statistical software for our calculation of site suitability (i.e. development potential) in FUTURES. R is a free software environment for statistical computing and graphics. If you don't have R, or you have older an version, please download and install the software from [http://archive.linux.duke.edu/cran/ install R] and be sure to additionally add these required packages:
<pre>
install.packages(c("MuMIn", "lme4", "optparse", "rgrass7"))
</pre>

==== MS Windows ====
We will be using GRASS GIS 7.0.3 that can be found here in the [https://trac.osgeo.org/osgeo4w/ OSGeo4W] package manager.
Please install the latest stable GRASS GIS 7 version and the SciPy Python package using the ''Advanced install'' option.
A guide with step by step screen shot instructions is available [https://docs.google.com/presentation/d/1yEGpriBne7RvjB35HI6GecNwO1P1y2nRGqDThqoNnCE/edit?usp=sharing here].

In order for GRASS to be able to find R executables, GRASS must be on the PATH variable. Follow this [solution] to make R accessible from GRASS permanently.
A simple but temporary solution is to open GRASS GIS and paste this in the black terminal:
<pre>
set PATH=%PATH%;C:\Program Files\R\R-3.0.2\bin
</pre>
This has to be repeated after restarting GRASS session.

==== Ubuntu Linux ====
Install GRASS GIS from packages:
<pre>
sudo add-apt-repository ppa:ubuntugis/ubuntugis-unstable
sudo apt-get update
sudo apt-get install grass
</pre>

== Workshop data ==
The data that we will be using for the workshop can be download here: [http://fatra.cnr.ncsu.edu/futures/futures_ncspm_Asheville.zip sample dataset]. Please place these layers in your local GRASS directory:
* digital elevation model ([http://nationalmap.gov/elevation.html NED])
* [http://www.mrlc.gov/ NLCD] 2001, 2011
* NLCD 1992/2001 Retrofit Land Cover Change Product
* transportation network ([http://www.census.gov/geo/maps-data/data/tiger-line.html TIGER])
* county boundaries ([http://www.census.gov/geo/maps-data/data/tiger-line.html TIGER])
* protected areas ([http://www.conservationgateway.org/ConservationByGeography/NorthAmerica/UnitedStates/edc/reportsdata/terrestrial/secured/Pages/default.aspx Secured Lands])
* cities as points (USGS)

In addition, download [http://fatra.cnr.ncsu.edu/futures/futures_Asheville_files.zip population information as text files]:
* county population past estimates and future projections ([https://www.osbm.nc.gov/demog/county-projections NC OSBM]) per county (nonspatial)

= GRASS GIS introduction =
There are many advantages to using the open source GRASS GIS platform, but for many that are more familiar with ARCGis and QGis, the setup and implementation of spatial tools in GRASS can be confusing. Here we provide an overview of the GRASS GIS project: [https://grass.osgeo.org grass.osgeo.org] that might be helpful to review if you are a first time users. For this exercise it's not necessary to have a full understanding of how to use GRASS. However, you will need to know how to place your data in the correct GRASS database directory, as well as some basic GRASS functionality. Step by step instructions are provided below
== Setting up GRASS for the tutorial ==
GRASS uses unique database terminology and structure ([https://grass.osgeo.org/grass71/manuals/grass_database.html GRASS database]) that are important to understand for the set up of this tutorial, as you will need to place the required data (e.g. Mapset) in a specific GRASS database Location. In the following we review important terminology and give step by step direction on how to download and place you data in the correct location.

=== Important GRASS directory terminology ===
* A '''GRASS database''' consist of directory with specific Locations (projects) where data layer are stored
* '''Location''' hold all Mapsets in a specific directoy that have the same spatial projection (spatial reference system)
* '''Mapset''' are a collection of maps with the same spatial projection

=== Creating a GRASS database for the tutorial ===
You need to create a GRASS database with the Mapset that we will use for the tutorial before we can run the FUTURES model. Please Download the [http://fatra.cnr.ncsu.edu/futures/futures_ncspm_Asheville.zip workshop location], noting where the files are located on your local directory. Now, create (unless you already have it) a directory named <tt>grassdata</tt> (GRASS database) in your home folder (or Documents), unzip the downloaded data into this directory. You should now have a Location <tt>futures_ncspm</tt> in <tt>grassdata</tt>.

<center><gallery perrow=1 widths=500 heights=250>Image:GRASS FUTURES startup.png|GRASS GIS 7.0.3 startup dialog with downloaded Location and Mapsets for FUTURES workshop</gallery></center>

=== Launching and exploring data in GRASS ===
Now that we have the data in the correct GRASS database, we can launch the Graphical User Interface (GUI). The GUI interface allows you to display raster, vector data as well as navigate through zooming in and out. Advanced exploration and visualization, like many popular GIS software, is also possible in GRASS (e.g. queries, adding legend). The print screens below depicts how you can add different map layers (left) and display the metadata of your data layers.

<center><gallery perrow=2 widths=500 heights=250>Image:GRASS FUTURES wxGUI display.png|Layer Manager and Map Display overview. Annotations show how to add raster layer, query, add legend.
Image:wxGUI_metadata_rinfo.png|Show raster map metadata by right click on layer</gallery></center>

== GRASS functionality ==
One of the advantage of GRASS is the diversity and number of module addons that let you analyze all manner of spatial and temporal. Because it is open source modules are added daily increasing functionality and methods for analysis of your data. GRASS GIS has over [https://grass.osgeo.org/grass70/manuals/full_index.html 500 different modules] in the core distribution and over [https://grass.osgeo.org/grass70/manuals/addons/ 230 addon modules] that can be used to prepare and analyze data layers.
<center>
{| class="wikitable"
|-
! Prefix !! Function !! Example
|-
| r.* || raster processing || ''{{cmd|r.mapcalc}}'': map algebra
|-
| v.* || vector processing || ''{{cmd|v.clean}}'': topological cleaning
|-
| i.* || imagery processing || ''{{cmd|i.segment}}'': object recognition
|-
| db.* || database management || ''{{cmd|db.select}}'': select values from table
|-
| r3.* || 3D raster processing || ''{{cmd|r3.stats}}'': 3D raster statistics
|-
| t.* || temporal data processing || ''{{cmd|t.rast.aggregate}}'': temporal aggregation
|-
| g.* || general data management || ''{{cmd|g.rename}}'': renames map
|-
| d.* || display ||''{{cmd|d.rast}}'': display raster map
|}</center>

=== Command line vs. GUI interface===
GRASS modules can be executed either through a GUI or command line interface. The GUI offers a user-friendly approach to executing modules where the user can navigate to data layers that they would like to analyze and modify processing options with simple check boxes. The GUI also offer a easily accessible manual on how to execute a model. The command line interface allows users to execute a module using command prompts specific to that module. This is handy when you are running similar analyses with minor modification or are familiar with the module commands for quick efficient processing. In this workshop we provide module prompts that can be copy and pasted into the command line for our workflow, but you can use both GUI and command line depending on personal preference. Look how {{cmd|wxGUI.modules|version=71|desc=GUI and command line interface}} represent the same tool. ''Task:'' compute aspect (orientation) from provided digital elevation model using module {{cmd|r.slope.aspect}} using both module dialog and command line.
* How to find modules? Modules are organized by their functionality in wxGUI menu, or we can search for them in Search modules tab. If we already know which module to use, we can just type it in the wxGUI command console. <center><gallery perrow=3 widths=380 heights=190>Image:wxGUI_menu_rinfo.png|Modules can be found in wxGUI menu
Image:wxGUI_module_search.png|You can search modules by name, description or keywords in ''Search modules'' tab
Image:wxGUI_console_completion.png|By typing prefix r. we make a list of modules starting with that prefix to show up.</gallery></center>

=== Computational region===

{{cmd|g.region|desc=Computational region}} - is an important raster concept in GRASS that needs some explanation. In GRASS a computational region can be set, subsetting larger extent data for quicker testing of analysis or analysis of specific regions based on adminstrative units. We provide a few points to keep in mind when using the computational region function:
* defined by region extent and raster resolution
* applies to all raster operations
* persists between GRASS session, can be different for different mapsets
* advantages: keeps your results consistent, avoid clipping, for computationally demanding tasks set region to smaller extent, check your result is good and then set the computational region to the entire study area and rerun analysis
* run <code>g.region -p</code> or in menu ''Settings'' - ''Region'' - ''Display region'' to see current region settings
[[File:WxGUI set region.png|700px|thumb|center|Simple ways to set computational region from GUI. On the left, set region to match raster map. On the right, select the highlighted option and then set region by drawing rectangle.]]

* GRASS 3D view

= Modeling with FUTURES =
== Initial steps and data preparation ==
First we will set the computational region of our analyses to an extent covering our study area that aligns with our base landuse rasters. ''Like explained in the instructions above, you simply need copy and paste these commands into the command prompt of GRASS''.
<source lang="bash">g.region raster=landuse_2011 -p</source>

The FUTURES model uses the locations of development and new development to predict when and where new urban growth will occur. This requires longitudinal data on urban land use. We will derive urbanized areas from NLCD dataset for year 1992, 2001 and 2011
by extracting categories category 21 - 24 into a new binary map where developed is 1,
undeveloped 0 and NULL (no data). The NULL area is important in simulating urban growth as it preclude these are from becoming development. For this exercise we assume that water, wetlands and protected areas can not be developed, setting them to NULL.
First we will convert protected areas from vector to raster. We set
NULLs to zeros (for simpler raster algebra expression in the next step) using {{cmd|r.null}}:

<source lang="bash">
v.to.rast input=protected_areas output=protected_areas use=val
r.null map=protected_areas null=0
</source>

And then create rasters of developed/undeveloped areas using raster algebra:

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.mapcalc "urban_1992 = if(landuse_1992 >= 21 && landuse_1992 <= 24, 1, if(landuse_1992 == 11 || landuse_1992 >= 90 || protected_areas, null(), 0))"
r.mapcalc "urban_2001 = if(landuse_2001 >= 21 && landuse_2001 <= 24, 1, if(landuse_2001 == 11 || landuse_2001 >= 90 || protected_areas, null(), 0))"
r.mapcalc "urban_2011 = if(landuse_2011 >= 21 && landuse_2011 <= 24, 1, if(landuse_2011 == 11 || landuse_2011 >= 90 || protected_areas, null(), 0))"
</source>

FUTURES is a multi-level modelling framework meaning that we model population projections for subregions and assume that these subregions are influenced differently by the factors that influence where development happens. This requires defining subregions for model implementation. For this exercise we use the county level, which is the finest scale of population data that is available to us. We therefore need to convert vectors of counties to a raster with the values of the FIPS attribute which links to population file:

<source lang="bash">
v.to.rast input=counties type=area use=attr attribute_column=FIPS output=counties
</source>

Before further steps, we will set our working directory so that the input population files and text files
we are going to create are saved in one directory and easily accessible.
You can do that from menu ''Settings'' → ''GRASS working environment'' → ''Change working directory''.
Select (or create) a directory and move there the downloaded files <tt>population_projection.csv</tt> and <tt>population_trend.csv</tt>.

== Potential submodel ==
Module {{AddonCmd|r.futures.potential}} implements the POTENTIAL submodel as a part of FUTURES land change model. POTENTIAL is implemented using a set of coefficients that relate a selection of site suitability factors to the probability of a place becoming developed. This is implemented using the parameter table in combination with maps of those site suitability factors (mapped predictors). The coefficients are obtained by conducting multilevel logistic regression in R with package lme4 where the coefficients may vary by county. The best model is selected automatically using dredge function from package [https://cran.r-project.org/web/packages/MuMIn/index.html MuMIn].

First, we will derive possible predictors of urban growth using GRASS modules.
=== Predictors ===
==== Slope ====
Slope possibly influences urban growth as steep areas are difficult to build on. We will derive slope in degrees from digital elevation model using {{cmd|r.slope.aspect}} module:
<source lang="bash">r.slope.aspect elevation=elevation_30m slope=slope</source>

==== Distance from lakes/rivers ====
Distance to lakes or rivers may contribute to an amenity draw where people would like to build a house in a location where they can view water. First we will extract [http://www.mrlc.gov/nlcd11_leg.php category ''Open Water''] from 2011 NLCD dataset:
<source lang="bash">
r.mapcalc "water = if(landuse_2011 == 11, 1, null())"
</source>

Then we compute the distance to water with module {{cmd|r.grow.distance}} and set color table to shades of blue:
<source lang="bash">
r.grow.distance input=water distance=dist_to_water
r.colors -n map=dist_to_water color=blues
</source>

==== Distance from protected areas ====
Like water protected areas can attract urban growth as people enjoy living near scenic areas. We will use raster protected of protected areas we already created, but we will set NULL values to zero.
We compute the distance to protected areas with module {{cmd|r.grow.distance}} and set color table from green to red:
<source lang="bash">
r.null map=protected_areas setnull=0
r.grow.distance input=protected_areas distance=dist_to_protected
r.colors map=dist_to_protected color=gyr
</source>

==== Forests ====
We will smooth the transition between forest and other land use, see NLCD [http://www.mrlc.gov/nlcd11_leg.php category ''Open Water'']:
<source lang="bash">
r.mapcalc "forest = if(landuse_2011 >= 41 && landuse_2011 <= 43, 1, 0)"
r.neighbors -c input=forest output=forest_smooth size=15 method=average
r.colors map=forest_smooth color=ndvi
</source>

==== Travel time to cities ====
Here we will compute travel time to cities (with population > 5000)
as cumulative cost distance where cost is defined as travel time on roads.
First we specify the speed on different types of roads.
We copy the roads raster into our mapset so that we can change it
by adding a new attribute field <tt>speed</tt>. Then we assign speed values (km/h) based on the type of road:

<source lang="bash">
g.copy vector=roads,myroads
v.db.addcolumn map=myroads columns="speed double precision"
v.db.update map=myroads column=speed value=50 where="MTFCC = 'S1400'"
v.db.update map=myroads column=speed value=100 where="MTFCC IN ('S1100', 'S1200')"
</source>

Now we rasterize the selected road types using the speed values from the attribute table as raster values.

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
v.to.rast input=myroads type=line where="MTFCC IN ('S1100', 'S1200', 'S1400')" output=roads_speed use=attr attribute_column=speed
</source>

We set the rest of the area to low speed and recompute the speed as time to travel through a 30m cell in minutes:

<source lang="bash">
r.null map=roads_speed null=5
r.mapcalc "roads_travel_time = 1.8 / roads_speed"
</source>

Finally we compute the travel time to larger cities using {{cmd|r.cost}}:

<source lang="bash">
r.cost input=roads_travel_time output=travel_time_cities start_points=cities
r.colors map=travel_time_cities color=byr
</source>

==== Road density ====
We will rasterize roads and use moving window analysis ({{cmd|r.neighbors}}) to compute road density:

<source lang="bash">
v.to.rast input=roads output=roads use=val type=line
r.null map=roads null=0
r.neighbors -c input=roads output=road_dens size=25 method=average
</source>

==== Distance to interchanges ====

We will consider TIGER roads of type <tt>Ramp</tt> as interchanges, rasterize them and compute euclidean distance to them:

<source lang="bash">
v.to.rast input=roads type=line where="MTFCC = 'S1630'" output=interchanges use=val
r.grow.distance -m input=interchanges distance=dist_interchanges
</source>

=== Development pressure ===

We compute development pressure with {{AddonCmd|r.futures.devpressure}}. Development pressure is a predictor based on number of neighboring developed cells within search distance, weighted by distance. The development pressure variable plays a special role in the model, allowing for a feedback between predicted change and change in subsequent steps.

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.devpressure -n input=urban_2011 output=devpressure_2 method=gravity size=7 gamma=2 scaling_factor=10
r.futures.devpressure -n input=urban_2011 output=devpressure_1 method=gravity size=10 gamma=1 scaling_factor=1
r.futures.devpressure -n input=urban_2011 output=devpressure_0_5 method=gravity size=30 gamma=0.5 scaling_factor=0.1
</source>

When gamma increases, development influence decreases more rapidly with distance.
Size is half the size of the moving window. When gamma is low, local development influences more distant places.
We will derive 3 layers with different gamma and size parameters for the potential statistical model.

=== Rescaling variables ===

First we will look at the ranges of our predictor variables by running a short Python code snippet in Python shell:

<source lang="python" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
for name in ['slope', 'dist_to_water', 'dist_to_protected', 'forest_smooth', 'travel_time_cities', 'road_dens', 'dist_interchanges', 'devpressure_0_5', 'devpressure_1']:
minmax = grass.raster_info(name)
print name, minmax['min'], minmax['max']
</source>

We will rescale some of our input variables:

<source lang="bash">
r.mapcalc "dist_to_water_km = dist_to_water / 1000"
r.mapcalc "dist_to_protected_km = dist_to_protected / 1000"
r.mapcalc "dist_interchanges_km = dist_interchanges / 1000"
r.mapcalc "road_dens_perc = road_dens * 100"
r.mapcalc "forest_smooth_perc = forest_smooth * 100"
</source>

=== Sampling ===
To sample only in the analyzed counties, we will clip development layer:

<source lang="bash">
r.mapcalc "urban_change_01_11 = if(urban_2011 == 1, if(urban_2001 == 0, 1, null()), 0)"
r.mapcalc "urban_change_clip = if(counties, urban_change_01_11)"
</source>

To estimate the number of sampling points, we can use {{cmd|r.report}} to report number of developed/undeveloped cells and their ratio.

<source lang="bash">
r.report map=urban_change_clip units=h,c,p
</source>

We will sample the predictors and the response variable with 5000 random points in undeveloped areas and 1000 points in developed area:

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.sample.category input=urban_change_clip output=sampling sampled=counties,devpressure_0_5,devpressure_1,devpressure_2,slope,road_dens_perc,forest_smooth_perc,dist_to_water_km,dist_to_protected_km,dist_interchanges_km,travel_time_cities npoints=5000,1000
</source>

The attribute table can be exported as CSV file (not necessary step):

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
v.db.select map=sampling columns=urban_change_clip,counties,devpressure_0_5,devpressure_1,slope,road_dens_perc,forest_smooth_perc,dist_to_water_km,dist_to_protected_km,dist_interchanges_km,travel_time_cities separator=comma file=samples.csv
</source>

=== Development potential ===
Now we find best model for predicting urbanization using {{AddonCmd|r.futures.potential}} which wraps an R script.

We can run R [http://www.inside-r.org/packages/cran/MuMIn/docs/dredge dredge] function to find "best" model. We can specify minimum and maximum number of predictors the final model should use.
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.potential -d input=sampling output=potential.csv columns=devpressure_1,slope,road_dens_perc,forest_smooth_perc,dist_to_water_km,dist_to_protected_km,dist_interchanges_km,travel_time_cities developed_column=urban_change_clip subregions_column=counties min_variables=4
</source>

Also, we can play with different combinations of predictors, for example:

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.potential input=sampling output=potential.csv columns=devpressure_2,road_dens_perc,slope,dist_interchanges_km,dist_to_water_km developed_column=urban_change_clip subregions_column=counties --o
r.futures.potential input=sampling output=potential.csv columns=devpressure_1,road_dens_perc,slope,dist_interchanges_km,dist_to_water_km developed_column=urban_change_clip subregions_column=counties --o
...
</source>

You can then open the output file <tt>potential.csv</tt>, which is a CSV file with tabs as separators.

For this tutorial, the final potential is created with:
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.potential input=sampling output=potential.csv columns=devpressure_2,road_dens_perc,slope,dist_interchanges_km,dist_to_water_km developed_column=urban_change_clip subregions_column=counties --o
</source>

We can now visualize the suitability surface using module {{AddonCmd|r.futures.potsurface}}. It creates initial development potential (suitability) raster from predictors and model coefficients and serves only for evaluating development potential model. The values of the resulting raster range from 0 to 1.

<source lang="bash">
r.futures.potsurface input=potential.csv subregions=counties output=suitability
r.colors map=suitability color=byr
</source>

== Demand submodel ==
First we will mask out roads so that they don't influence into per capita land demand relation.
<source lang="bash">
v.to.rast input=roads type=line output=roads_mask use=val
r.mask roads_mask -i
</source>

We will use {{AddonCmd|r.futures.demand}} which derives the population vs. development relation. The relation can be linear/logarithmic/logarithmic2/exponential/exponential approach.
Look for examples of the different relations in the manual.

* linear: y = A + Bx
* logarithmic: y = A + Bln(x)
* logarithmic2: y = A + B * ln(x - C)        (requires SciPy)
* exponential: y = Ae^(BX)
* exp_approach: y = (1 - e^(-A(x - B))) + C        (requires SciPy)

The format of the input population CSV files is described in the manual. It is important to have synchronized categories of subregions and the column headers of the CSV files (in our case FIPS number). How to simply generate the list of years (for which demand is computed) is described in {{AddonCmd|r.futures.demand}} manual, for example run this in Python console:

<source lang="python">
','.join([str(i) for i in range(2011, 2036)])
</source>

Then we can create the DEMAND file:
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.demand development=urban_1992,urban_2001,urban_2011 subregions=counties observed_population=population_trend.csv projected_population=population_projection.csv simulation_times=2011,2012,2013,2014,2015,2016,2017,2018,2019,2020,2021,2022,2023,2024,2025,2026,2027,2028,2029,2030,2031,2032,2033,2034,2035 plot=plot_demand.pdf demand=demand.csv separator=comma
</source>

In your current working directory, you should find files <tt>plot_demand.png</tt> and <tt>demand.csv</tt>.

If you have SciPy installed, you can experiment with other methods for fitting the functions:
<source lang="bash">
r.futures.demand ... method=logarithmic2
r.futures.demand ... method=exp_approach
</source>
If necessary, you can create a set of demand files produced by fitting each method separately and
then pick for each county the method which seems best and manually create a new demand file.

When you are finished, remove the mask as it is not needed for the next steps.
<source lang="bash">
r.mask -r
</source>

== Patch calibration ==
Patch calibration can be a very time consuming computation.
Therefore we select only one county (Buncombe):

<source lang="bash">
v.to.rast input=counties type=area where="FIPS == 37021" use=attr attribute_column=FIPS output=calib_county
g.region raster=calib_county zoom=calib_county
</source>
to derive patches of new development by comparing historical and latest development.
We can keep only patches with minimum size 2 cells (1800 = 2 x 30 x 30 m).

<source lang="bash">
r.futures.calib development_start=urban_1992 development_end=urban_2011 subregions=counties patch_sizes=patches.txt patch_threshold=1800 -l
</source>
We obtained a file <tt>patches.txt</tt> (used later in the PGA) - a patch size distribution file - containing sizes of all found patches.

We can look at the distribution of the patch sizes:

<source lang="python">
from matplotlib import pyplot as plt
with open('patches.txt') as f:
patches = [int(patch) for patch in f.readlines()]
plt.hist(patches, 2000)
plt.xlim(0,50)
plt.show()
</source>

At this point, we start the calibration to get best parameters of patch shape
(for this tutorial, this step can be skipped and the suggested parameters are used).

<source lang="bash"
style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.calib development_start=urban_1992 development_end=urban_2011 subregions=calib_county patch_sizes=patches.txt calibration_results=calib.csv patch_threshold=1800 repeat=5 compactness_mean=0.1,0.3,0.5,0.7,0.9 compactness_range=0.05 discount_factor=0.1,0.3,0.5,0.7,0.9 predictors=road_dens_perc,forest_smooth_perc,dist_to_protected_km demand=demand.csv devpot_params=potential.csv num_neighbors=4 seed_search=2 development_pressure=devpressure_0_5 development_pressure_approach=gravity n_dev_neighbourhood=30 gamma=0.5 scaling_factor=0.1
</source>

== FUTURES simulation ==
We will switch back to our previous region:
<source lang="bash">
g.region raster=landuse_2011 -p
</source>

Now we have all the inputs necessary for running {{AddonCmd|r.futures.pga}}:

The entire command is here:
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.pga subregions=counties developed=urban_2011 predictors=slope,forest_smooth_perc,dist_interchanges_km,travel_time_cities devpot_params=potential.csv development_pressure=devpressure_1 n_dev_neighbourhood=10 development_pressure_approach=gravity gamma=1 scaling_factor=1 demand=demand.csv discount_factor=0.3 compactness_mean=0.2 compactness_range=0.1 patch_sizes=patches.txt num_neighbors=4 seed_search=2 random_seed=1 output=final output_series=final
</source>

=== Quick description ===
The command parameters and their values:
* raster map of counties with their categories
<code>
... subregions=counties ...
</code>

* raster of developed (1), undeveloped (0) and NULLs for undevelopable areas
<code>
... developed=urban_2011 ...
</code>

* predictors selected with {{AddonCmd|r.futures.potential}} and their coefficients in a <tt>potential.csv</tt> file. The order of predictors must match the order in the file and the categories of the counties must match raster <tt>counties</tt>.
<code>
... predictors=slope,forest_smooth_perc,dist_interchanges_km,travel_time_cities devpot_params=potential.csv ...
</code>

* initial development pressure computed by {{AddonCmd|r.futures.devpressure}}, it's important to set here the same parameters
<code>
... development_pressure=devpressure_1 n_dev_neighbourhood=10 development_pressure_approach=gravity gamma=1 scaling_factor=1 ...
</code>

* per capita land demand computed by {{AddonCmd|r.futures.demand}}, the categories of the counties must match raster <tt>counties</tt>.
<code>
... demand=demand.csv ...
</code>

* patch parameters from the calibration step
<code>
... discount_factor=0.3 compactness_mean=0.4 compactness_range=0.08 patch_sizes=patches.txt ...
</code>

* recommended parameters for patch growing algorithm
<code>
... num_neighbors=4 seed_search=2 ...
</code>

* set random seed for repeatable results or set flag <tt>-s</tt> to generate seed automatically
<code>
... random_seed=1 ...
</code>

* specify final output map and optionally basename for intermediate raster maps
<code>
output=final output_series=final
</code>

== Scenarios ==
Scenarios involving policies that encourage infill versus sprawl can be explored using the <tt>incentive_power</tt> parameter of {{AddonCmd|r.futures.pga}},
which uses a power function to transform the evenness of the probability gradient in POTENTIAL. You can change the power to a number between 0.25 and 4 to test urban sprawl/infill scenarios.
Higher power leads to infill behavior, lower power to urban sprawl.

== Postprocessing ==

Follow a [[Creating_animation_from_FUTURES_output_in_GRASS_GIS| tutorial how to make an animation from the results]].

= GRASS GIS Python API =

[[Category: Tutorial]]
[[Category: FUTURES]]
[[Category: Urban]]

Workshop on urban growth modeling with FUTURES

2016-03-22T20:13:49Z

⚠️Dbvanber: /* Potential submodel */

{{ToModify}}
= Workshop introduction =
r.futures.* is an implementation of the '''FUT'''ure '''U'''rban-'''R'''egional '''E'''nvironment '''S'''imulation (FUTURES)[1] which is a model for multilevel simulations of emerging urban-rural landscape structure. FUTURES produces regional projections of landscape patterns using coupled submodels that integrate nonstationary drivers of land change: per capita demand (DEMAND submodel), site suitability (POTENTIAL submodel), and the spatial structure of conversion events (PGA submodel).

[1] Meentemeyer, R. K., Tang, W., Dorning, M. A., Vogler, J. B., Cunniffe, N. J., & Shoemaker, D. A. (2013). [http://www.tandfonline.com/doi/abs/10.1080/00045608.2012.707591 FUTURES: multilevel simulations of emerging urban-rural landscape structure using a stochastic patch-growing algorithm.] Annals of the Association of American Geographers, 103(4), 785-807

== Software ==
There are a number of software requirements to run FUTURES that will need to be download and installed. Required software includes:
* GRASS GIS 7
* addons
** {{AddonCmd|r.futures.pga}}
** {{AddonCmd|r.futures.potential}}
** {{AddonCmd|r.futures.potsurface}}
** {{AddonCmd|r.futures.demand}}
** {{AddonCmd|r.futures.devpressure}}
** {{AddonCmd|r.sample.category}}
* R (≥ 3.0.2) - needed for {{AddonCmd|r.futures.potential}} with packages:
**MuMIn, lme4, optparse, rgrass7
* SciPy - useful for {{AddonCmd|r.futures.demand}}

=== Installation ===
We use the R statistical software for our calculation of site suitability (i.e. development potential) in FUTURES. R is a free software environment for statistical computing and graphics. If you don't have R, or you have older an version, please download and install the software from [http://archive.linux.duke.edu/cran/ install R] and be sure to additionally add these required packages:
<pre>
install.packages(c("MuMIn", "lme4", "optparse", "rgrass7"))
</pre>

==== MS Windows ====
We will be using GRASS GIS 7.0.3 that can be found here in the [https://trac.osgeo.org/osgeo4w/ OSGeo4W] package manager.
Please install the latest stable GRASS GIS 7 version and the SciPy Python package using the ''Advanced install'' option.
A guide with step by step screen shot instructions is available [https://docs.google.com/presentation/d/1yEGpriBne7RvjB35HI6GecNwO1P1y2nRGqDThqoNnCE/edit?usp=sharing here].

In order for GRASS to be able to find R executables, GRASS must be on the PATH variable. Follow this [solution] to make R accessible from GRASS permanently.
A simple but temporary solution is to open GRASS GIS and paste this in the black terminal:
<pre>
set PATH=%PATH%;C:\Program Files\R\R-3.0.2\bin
</pre>
This has to be repeated after restarting GRASS session.

==== Ubuntu Linux ====
Install GRASS GIS from packages:
<pre>
sudo add-apt-repository ppa:ubuntugis/ubuntugis-unstable
sudo apt-get update
sudo apt-get install grass
</pre>

== Workshop data ==
The data that we will be using for the workshop can be download here: [http://fatra.cnr.ncsu.edu/futures/futures_ncspm_Asheville.zip sample dataset]. Please place these layers in your local GRASS directory:
* digital elevation model ([http://nationalmap.gov/elevation.html NED])
* [http://www.mrlc.gov/ NLCD] 2001, 2011
* NLCD 1992/2001 Retrofit Land Cover Change Product
* transportation network ([http://www.census.gov/geo/maps-data/data/tiger-line.html TIGER])
* county boundaries ([http://www.census.gov/geo/maps-data/data/tiger-line.html TIGER])
* protected areas ([http://www.conservationgateway.org/ConservationByGeography/NorthAmerica/UnitedStates/edc/reportsdata/terrestrial/secured/Pages/default.aspx Secured Lands])
* cities as points (USGS)

In addition, download [http://fatra.cnr.ncsu.edu/futures/futures_Asheville_files.zip population information as text files]:
* county population past estimates and future projections ([https://www.osbm.nc.gov/demog/county-projections NC OSBM]) per county (nonspatial)

= GRASS GIS introduction =
There are many advantages to using the open source GRASS GIS platform, but for many that are more familiar with ARCGis and QGis, the setup and implementation of spatial tools in GRASS can be confusing. Here we provide an overview of the GRASS GIS project: [https://grass.osgeo.org grass.osgeo.org] that might be helpful to review if you are a first time users. For this exercise it's not necessary to have a full understanding of how to use GRASS. However, you will need to know how to place your data in the correct GRASS database directory, as well as some basic GRASS functionality. Step by step instructions are provided below
== Setting up GRASS for the tutorial ==
GRASS uses unique database terminology and structure ([https://grass.osgeo.org/grass71/manuals/grass_database.html GRASS database]) that are important to understand for the set up of this tutorial, as you will need to place the required data (e.g. Mapset) in a specific GRASS database Location. In the following we review important terminology and give step by step direction on how to download and place you data in the correct location.

=== Important GRASS directory terminology ===
* A '''GRASS database''' consist of directory with specific Locations (projects) where data layer are stored
* '''Location''' hold all Mapsets in a specific directoy that have the same spatial projection (spatial reference system)
* '''Mapset''' are a collection of maps with the same spatial projection

=== Creating a GRASS database for the tutorial ===
You need to create a GRASS database with the Mapset that we will use for the tutorial before we can run the FUTURES model. Please Download the [http://fatra.cnr.ncsu.edu/futures/futures_ncspm_Asheville.zip workshop location], noting where the files are located on your local directory. Now, create (unless you already have it) a directory named <tt>grassdata</tt> (GRASS database) in your home folder (or Documents), unzip the downloaded data into this directory. You should now have a Location <tt>futures_ncspm</tt> in <tt>grassdata</tt>.

<center><gallery perrow=1 widths=500 heights=250>Image:GRASS FUTURES startup.png|GRASS GIS 7.0.3 startup dialog with downloaded Location and Mapsets for FUTURES workshop</gallery></center>

=== Launching and exploring data in GRASS ===
Now that we have the data in the correct GRASS database, we can launch the Graphical User Interface (GUI). The GUI interface allows you to display raster, vector data as well as navigate through zooming in and out. Advanced exploration and visualization, like many popular GIS software, is also possible in GRASS (e.g. queries, adding legend). The print screens below depicts how you can add different map layers (left) and display the metadata of your data layers.

<center><gallery perrow=2 widths=500 heights=250>Image:GRASS FUTURES wxGUI display.png|Layer Manager and Map Display overview. Annotations show how to add raster layer, query, add legend.
Image:wxGUI_metadata_rinfo.png|Show raster map metadata by right click on layer</gallery></center>

== GRASS functionality ==
One of the advantage of GRASS is the diversity and number of module addons that let you analyze all manner of spatial and temporal. Because it is open source modules are added daily increasing functionality and methods for analysis of your data. GRASS GIS has over [https://grass.osgeo.org/grass70/manuals/full_index.html 500 different modules] in the core distribution and over [https://grass.osgeo.org/grass70/manuals/addons/ 230 addon modules] that can be used to prepare and analyze data layers.
<center>
{| class="wikitable"
|-
! Prefix !! Function !! Example
|-
| r.* || raster processing || ''{{cmd|r.mapcalc}}'': map algebra
|-
| v.* || vector processing || ''{{cmd|v.clean}}'': topological cleaning
|-
| i.* || imagery processing || ''{{cmd|i.segment}}'': object recognition
|-
| db.* || database management || ''{{cmd|db.select}}'': select values from table
|-
| r3.* || 3D raster processing || ''{{cmd|r3.stats}}'': 3D raster statistics
|-
| t.* || temporal data processing || ''{{cmd|t.rast.aggregate}}'': temporal aggregation
|-
| g.* || general data management || ''{{cmd|g.rename}}'': renames map
|-
| d.* || display ||''{{cmd|d.rast}}'': display raster map
|}</center>

=== Command line vs. GUI interface===
GRASS modules can be executed either through a GUI or command line interface. The GUI offers a user-friendly approach to executing modules where the user can navigate to data layers that they would like to analyze and modify processing options with simple check boxes. The GUI also offer a easily accessible manual on how to execute a model. The command line interface allows users to execute a module using command prompts specific to that module. This is handy when you are running similar analyses with minor modification or are familiar with the module commands for quick efficient processing. In this workshop we provide module prompts that can be copy and pasted into the command line for our workflow, but you can use both GUI and command line depending on personal preference. Look how {{cmd|wxGUI.modules|version=71|desc=GUI and command line interface}} represent the same tool. ''Task:'' compute aspect (orientation) from provided digital elevation model using module {{cmd|r.slope.aspect}} using both module dialog and command line.
* How to find modules? Modules are organized by their functionality in wxGUI menu, or we can search for them in Search modules tab. If we already know which module to use, we can just type it in the wxGUI command console. <center><gallery perrow=3 widths=380 heights=190>Image:wxGUI_menu_rinfo.png|Modules can be found in wxGUI menu
Image:wxGUI_module_search.png|You can search modules by name, description or keywords in ''Search modules'' tab
Image:wxGUI_console_completion.png|By typing prefix r. we make a list of modules starting with that prefix to show up.</gallery></center>

=== Computational region===

{{cmd|g.region|desc=Computational region}} - is an important raster concept in GRASS that needs some explanation. In GRASS a computational region can be set, subsetting larger extent data for quicker testing of analysis or analysis of specific regions based on adminstrative units. We provide a few points to keep in mind when using the computational region function:
* defined by region extent and raster resolution
* applies to all raster operations
* persists between GRASS session, can be different for different mapsets
* advantages: keeps your results consistent, avoid clipping, for computationally demanding tasks set region to smaller extent, check your result is good and then set the computational region to the entire study area and rerun analysis
* run <code>g.region -p</code> or in menu ''Settings'' - ''Region'' - ''Display region'' to see current region settings
[[File:WxGUI set region.png|700px|thumb|center|Simple ways to set computational region from GUI. On the left, set region to match raster map. On the right, select the highlighted option and then set region by drawing rectangle.]]

* GRASS 3D view

= Modeling with FUTURES =
== Initial steps and data preparation ==
First we will set the computational region of our analyses to an extent covering our study area that aligns with our base landuse rasters. ''Like explained in the instructions above, you simply need copy and paste these commands into the command prompt of GRASS''.
<source lang="bash">g.region raster=landuse_2011 -p</source>

The FUTURES model uses the locations of development and new development to predict when and where new urban growth will occur. This requires longitudinal data on urban land use. We will derive urbanized areas from NLCD dataset for year 1992, 2001 and 2011
by extracting categories category 21 - 24 into a new binary map where developed is 1,
undeveloped 0 and NULL (no data). The NULL area is important in simulating urban growth as it preclude these are from becoming development. For this exercise we assume that water, wetlands and protected areas can not be developed, setting them to NULL.
First we will convert protected areas from vector to raster. We set
NULLs to zeros (for simpler raster algebra expression in the next step) using {{cmd|r.null}}:

<source lang="bash">
v.to.rast input=protected_areas output=protected_areas use=val
r.null map=protected_areas null=0
</source>

And then create rasters of developed/undeveloped areas using raster algebra:

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.mapcalc "urban_1992 = if(landuse_1992 >= 21 && landuse_1992 <= 24, 1, if(landuse_1992 == 11 || landuse_1992 >= 90 || protected_areas, null(), 0))"
r.mapcalc "urban_2001 = if(landuse_2001 >= 21 && landuse_2001 <= 24, 1, if(landuse_2001 == 11 || landuse_2001 >= 90 || protected_areas, null(), 0))"
r.mapcalc "urban_2011 = if(landuse_2011 >= 21 && landuse_2011 <= 24, 1, if(landuse_2011 == 11 || landuse_2011 >= 90 || protected_areas, null(), 0))"
</source>

FUTURES is a multi-level modelling framework meaning that we model population projections for subregions and assume that these subregions are influenced differently by the factors that influence where development happens. This requires defining subregions for model implementation. For this exercise we use the county level, which is the finest scale of population data that is available to us. We therefore need to convert vectors of counties to a raster with the values of the FIPS attribute which links to population file:

<source lang="bash">
v.to.rast input=counties type=area use=attr attribute_column=FIPS output=counties
</source>

Before further steps, we will set our working directory so that the input population files and text files
we are going to create are saved in one directory and easily accessible.
You can do that from menu ''Settings'' → ''GRASS working environment'' → ''Change working directory''.
Select (or create) a directory and move there the downloaded files <tt>population_projection.csv</tt> and <tt>population_trend.csv</tt>.

== Potential submodel ==
Module {{AddonCmd|r.futures.potential}} implements the POTENTIAL submodel as a part of FUTURES land change model. POTENTIAL is implemented using a set of coefficients that relate a selection of site suitability factors to the probability of a place becoming developed. This is implemented using the parameter table in combination with maps of those site suitability factors (mapped predictors). The coefficients are obtained by conducting multilevel logistic regression in R with package lme4 where the coefficients may vary by county. The best model is selected automatically using dredge function from package [https://cran.r-project.org/web/packages/MuMIn/index.html MuMIn].

First, we will derive possible predictors of urban growth using GRASS modules.
=== Predictors ===
==== Slope ====
Slope possibly influences urban growth as steep areas are difficult to build on. We will derive slope in degrees from digital elevation model using {{cmd|r.slope.aspect}} module:
<source lang="bash">r.slope.aspect elevation=elevation_30m slope=slope</source>

==== Distance from lakes/rivers ====
Distance to lakes or rivers may contribute to an amenity draw where people would like to build a house in a location where they can view water. First we will extract [http://www.mrlc.gov/nlcd11_leg.php category ''Open Water''] from 2011 NLCD dataset:
<source lang="bash">
r.mapcalc "water = if(landuse_2011 == 11, 1, null())"
</source>

Then we compute the distance to water with module {{cmd|r.grow.distance}} and set color table to shades of blue:
<source lang="bash">
r.grow.distance input=water distance=dist_to_water
r.colors -n map=dist_to_water color=blues
</source>

==== Distance from protected areas ====
We will use raster protected of protected areas we already created, but we will set NULL values to zero.
We compute the distance to protected areas with module {{cmd|r.grow.distance}} and set color table from green to red:
<source lang="bash">
r.null map=protected_areas setnull=0
r.grow.distance input=protected_areas distance=dist_to_protected
r.colors map=dist_to_protected color=gyr
</source>

==== Forests ====
We will smooth the transition between forest and other land use, see NLCD [http://www.mrlc.gov/nlcd11_leg.php category ''Open Water'']:
<source lang="bash">
r.mapcalc "forest = if(landuse_2011 >= 41 && landuse_2011 <= 43, 1, 0)"
r.neighbors -c input=forest output=forest_smooth size=15 method=average
r.colors map=forest_smooth color=ndvi
</source>

==== Travel time to cities ====
Here we will compute travel time to cities (with population > 5000)
as cumulative cost distance where cost is defined as travel time on roads.
First we specify the speed on different types of roads.
We copy the roads raster into our mapset so that we can change it
by adding a new attribute field <tt>speed</tt>. Then we assign speed values (km/h) based on the type of road:

<source lang="bash">
g.copy vector=roads,myroads
v.db.addcolumn map=myroads columns="speed double precision"
v.db.update map=myroads column=speed value=50 where="MTFCC = 'S1400'"
v.db.update map=myroads column=speed value=100 where="MTFCC IN ('S1100', 'S1200')"
</source>

Now we rasterize the selected road types using the speed values from the attribute table as raster values.

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
v.to.rast input=myroads type=line where="MTFCC IN ('S1100', 'S1200', 'S1400')" output=roads_speed use=attr attribute_column=speed
</source>

We set the rest of the area to low speed and recompute the speed as time to travel through a 30m cell in minutes:

<source lang="bash">
r.null map=roads_speed null=5
r.mapcalc "roads_travel_time = 1.8 / roads_speed"
</source>

Finally we compute the travel time to larger cities using {{cmd|r.cost}}:

<source lang="bash">
r.cost input=roads_travel_time output=travel_time_cities start_points=cities
r.colors map=travel_time_cities color=byr
</source>

==== Road density ====
We will rasterize roads and use moving window analysis ({{cmd|r.neighbors}}) to compute road density:

<source lang="bash">
v.to.rast input=roads output=roads use=val type=line
r.null map=roads null=0
r.neighbors -c input=roads output=road_dens size=25 method=average
</source>

==== Distance to interchanges ====

We will consider TIGER roads of type <tt>Ramp</tt> as interchanges, rasterize them and compute euclidean distance to them:

<source lang="bash">
v.to.rast input=roads type=line where="MTFCC = 'S1630'" output=interchanges use=val
r.grow.distance -m input=interchanges distance=dist_interchanges
</source>

=== Development pressure ===

We compute development pressure with {{AddonCmd|r.futures.devpressure}}. Development pressure is a predictor based on number of neighboring developed cells within search distance, weighted by distance. The development pressure variable plays a special role in the model, allowing for a feedback between predicted change and change in subsequent steps.

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.devpressure -n input=urban_2011 output=devpressure_2 method=gravity size=7 gamma=2 scaling_factor=10
r.futures.devpressure -n input=urban_2011 output=devpressure_1 method=gravity size=10 gamma=1 scaling_factor=1
r.futures.devpressure -n input=urban_2011 output=devpressure_0_5 method=gravity size=30 gamma=0.5 scaling_factor=0.1
</source>

When gamma increases, development influence decreases more rapidly with distance.
Size is half the size of the moving window. When gamma is low, local development influences more distant places.
We will derive 3 layers with different gamma and size parameters for the potential statistical model.

=== Rescaling variables ===

First we will look at the ranges of our predictor variables by running a short Python code snippet in Python shell:

<source lang="python" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
for name in ['slope', 'dist_to_water', 'dist_to_protected', 'forest_smooth', 'travel_time_cities', 'road_dens', 'dist_interchanges', 'devpressure_0_5', 'devpressure_1']:
minmax = grass.raster_info(name)
print name, minmax['min'], minmax['max']
</source>

We will rescale some of our input variables:

<source lang="bash">
r.mapcalc "dist_to_water_km = dist_to_water / 1000"
r.mapcalc "dist_to_protected_km = dist_to_protected / 1000"
r.mapcalc "dist_interchanges_km = dist_interchanges / 1000"
r.mapcalc "road_dens_perc = road_dens * 100"
r.mapcalc "forest_smooth_perc = forest_smooth * 100"
</source>

=== Sampling ===
To sample only in the analyzed counties, we will clip development layer:

<source lang="bash">
r.mapcalc "urban_change_01_11 = if(urban_2011 == 1, if(urban_2001 == 0, 1, null()), 0)"
r.mapcalc "urban_change_clip = if(counties, urban_change_01_11)"
</source>

To estimate the number of sampling points, we can use {{cmd|r.report}} to report number of developed/undeveloped cells and their ratio.

<source lang="bash">
r.report map=urban_change_clip units=h,c,p
</source>

We will sample the predictors and the response variable with 5000 random points in undeveloped areas and 1000 points in developed area:

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.sample.category input=urban_change_clip output=sampling sampled=counties,devpressure_0_5,devpressure_1,devpressure_2,slope,road_dens_perc,forest_smooth_perc,dist_to_water_km,dist_to_protected_km,dist_interchanges_km,travel_time_cities npoints=5000,1000
</source>

The attribute table can be exported as CSV file (not necessary step):

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
v.db.select map=sampling columns=urban_change_clip,counties,devpressure_0_5,devpressure_1,slope,road_dens_perc,forest_smooth_perc,dist_to_water_km,dist_to_protected_km,dist_interchanges_km,travel_time_cities separator=comma file=samples.csv
</source>

=== Development potential ===
Now we find best model for predicting urbanization using {{AddonCmd|r.futures.potential}} which wraps an R script.

We can run R [http://www.inside-r.org/packages/cran/MuMIn/docs/dredge dredge] function to find "best" model. We can specify minimum and maximum number of predictors the final model should use.
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.potential -d input=sampling output=potential.csv columns=devpressure_1,slope,road_dens_perc,forest_smooth_perc,dist_to_water_km,dist_to_protected_km,dist_interchanges_km,travel_time_cities developed_column=urban_change_clip subregions_column=counties min_variables=4
</source>

Also, we can play with different combinations of predictors, for example:

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.potential input=sampling output=potential.csv columns=devpressure_2,road_dens_perc,slope,dist_interchanges_km,dist_to_water_km developed_column=urban_change_clip subregions_column=counties --o
r.futures.potential input=sampling output=potential.csv columns=devpressure_1,road_dens_perc,slope,dist_interchanges_km,dist_to_water_km developed_column=urban_change_clip subregions_column=counties --o
...
</source>

You can then open the output file <tt>potential.csv</tt>, which is a CSV file with tabs as separators.

For this tutorial, the final potential is created with:
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.potential input=sampling output=potential.csv columns=devpressure_2,road_dens_perc,slope,dist_interchanges_km,dist_to_water_km developed_column=urban_change_clip subregions_column=counties --o
</source>

We can now visualize the suitability surface using module {{AddonCmd|r.futures.potsurface}}. It creates initial development potential (suitability) raster from predictors and model coefficients and serves only for evaluating development potential model. The values of the resulting raster range from 0 to 1.

<source lang="bash">
r.futures.potsurface input=potential.csv subregions=counties output=suitability
r.colors map=suitability color=byr
</source>

== Demand submodel ==
First we will mask out roads so that they don't influence into per capita land demand relation.
<source lang="bash">
v.to.rast input=roads type=line output=roads_mask use=val
r.mask roads_mask -i
</source>

We will use {{AddonCmd|r.futures.demand}} which derives the population vs. development relation. The relation can be linear/logarithmic/logarithmic2/exponential/exponential approach.
Look for examples of the different relations in the manual.

* linear: y = A + Bx
* logarithmic: y = A + Bln(x)
* logarithmic2: y = A + B * ln(x - C)        (requires SciPy)
* exponential: y = Ae^(BX)
* exp_approach: y = (1 - e^(-A(x - B))) + C        (requires SciPy)

The format of the input population CSV files is described in the manual. It is important to have synchronized categories of subregions and the column headers of the CSV files (in our case FIPS number). How to simply generate the list of years (for which demand is computed) is described in {{AddonCmd|r.futures.demand}} manual, for example run this in Python console:

<source lang="python">
','.join([str(i) for i in range(2011, 2036)])
</source>

Then we can create the DEMAND file:
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.demand development=urban_1992,urban_2001,urban_2011 subregions=counties observed_population=population_trend.csv projected_population=population_projection.csv simulation_times=2011,2012,2013,2014,2015,2016,2017,2018,2019,2020,2021,2022,2023,2024,2025,2026,2027,2028,2029,2030,2031,2032,2033,2034,2035 plot=plot_demand.pdf demand=demand.csv separator=comma
</source>

In your current working directory, you should find files <tt>plot_demand.png</tt> and <tt>demand.csv</tt>.

If you have SciPy installed, you can experiment with other methods for fitting the functions:
<source lang="bash">
r.futures.demand ... method=logarithmic2
r.futures.demand ... method=exp_approach
</source>
If necessary, you can create a set of demand files produced by fitting each method separately and
then pick for each county the method which seems best and manually create a new demand file.

When you are finished, remove the mask as it is not needed for the next steps.
<source lang="bash">
r.mask -r
</source>

== Patch calibration ==
Patch calibration can be a very time consuming computation.
Therefore we select only one county (Buncombe):

<source lang="bash">
v.to.rast input=counties type=area where="FIPS == 37021" use=attr attribute_column=FIPS output=calib_county
g.region raster=calib_county zoom=calib_county
</source>
to derive patches of new development by comparing historical and latest development.
We can keep only patches with minimum size 2 cells (1800 = 2 x 30 x 30 m).

<source lang="bash">
r.futures.calib development_start=urban_1992 development_end=urban_2011 subregions=counties patch_sizes=patches.txt patch_threshold=1800 -l
</source>
We obtained a file <tt>patches.txt</tt> (used later in the PGA) - a patch size distribution file - containing sizes of all found patches.

We can look at the distribution of the patch sizes:

<source lang="python">
from matplotlib import pyplot as plt
with open('patches.txt') as f:
patches = [int(patch) for patch in f.readlines()]
plt.hist(patches, 2000)
plt.xlim(0,50)
plt.show()
</source>

At this point, we start the calibration to get best parameters of patch shape
(for this tutorial, this step can be skipped and the suggested parameters are used).

<source lang="bash"
style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.calib development_start=urban_1992 development_end=urban_2011 subregions=calib_county patch_sizes=patches.txt calibration_results=calib.csv patch_threshold=1800 repeat=5 compactness_mean=0.1,0.3,0.5,0.7,0.9 compactness_range=0.05 discount_factor=0.1,0.3,0.5,0.7,0.9 predictors=road_dens_perc,forest_smooth_perc,dist_to_protected_km demand=demand.csv devpot_params=potential.csv num_neighbors=4 seed_search=2 development_pressure=devpressure_0_5 development_pressure_approach=gravity n_dev_neighbourhood=30 gamma=0.5 scaling_factor=0.1
</source>

== FUTURES simulation ==
We will switch back to our previous region:
<source lang="bash">
g.region raster=landuse_2011 -p
</source>

Now we have all the inputs necessary for running {{AddonCmd|r.futures.pga}}:

The entire command is here:
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.pga subregions=counties developed=urban_2011 predictors=slope,forest_smooth_perc,dist_interchanges_km,travel_time_cities devpot_params=potential.csv development_pressure=devpressure_1 n_dev_neighbourhood=10 development_pressure_approach=gravity gamma=1 scaling_factor=1 demand=demand.csv discount_factor=0.3 compactness_mean=0.2 compactness_range=0.1 patch_sizes=patches.txt num_neighbors=4 seed_search=2 random_seed=1 output=final output_series=final
</source>

=== Quick description ===
The command parameters and their values:
* raster map of counties with their categories
<code>
... subregions=counties ...
</code>

* raster of developed (1), undeveloped (0) and NULLs for undevelopable areas
<code>
... developed=urban_2011 ...
</code>

* predictors selected with {{AddonCmd|r.futures.potential}} and their coefficients in a <tt>potential.csv</tt> file. The order of predictors must match the order in the file and the categories of the counties must match raster <tt>counties</tt>.
<code>
... predictors=slope,forest_smooth_perc,dist_interchanges_km,travel_time_cities devpot_params=potential.csv ...
</code>

* initial development pressure computed by {{AddonCmd|r.futures.devpressure}}, it's important to set here the same parameters
<code>
... development_pressure=devpressure_1 n_dev_neighbourhood=10 development_pressure_approach=gravity gamma=1 scaling_factor=1 ...
</code>

* per capita land demand computed by {{AddonCmd|r.futures.demand}}, the categories of the counties must match raster <tt>counties</tt>.
<code>
... demand=demand.csv ...
</code>

* patch parameters from the calibration step
<code>
... discount_factor=0.3 compactness_mean=0.4 compactness_range=0.08 patch_sizes=patches.txt ...
</code>

* recommended parameters for patch growing algorithm
<code>
... num_neighbors=4 seed_search=2 ...
</code>

* set random seed for repeatable results or set flag <tt>-s</tt> to generate seed automatically
<code>
... random_seed=1 ...
</code>

* specify final output map and optionally basename for intermediate raster maps
<code>
output=final output_series=final
</code>

== Scenarios ==
Scenarios involving policies that encourage infill versus sprawl can be explored using the <tt>incentive_power</tt> parameter of {{AddonCmd|r.futures.pga}},
which uses a power function to transform the evenness of the probability gradient in POTENTIAL. You can change the power to a number between 0.25 and 4 to test urban sprawl/infill scenarios.
Higher power leads to infill behavior, lower power to urban sprawl.

== Postprocessing ==

Follow a [[Creating_animation_from_FUTURES_output_in_GRASS_GIS| tutorial how to make an animation from the results]].

= GRASS GIS Python API =

[[Category: Tutorial]]
[[Category: FUTURES]]
[[Category: Urban]]

Workshop on urban growth modeling with FUTURES

2016-03-22T20:07:31Z

⚠️Dbvanber: /* Initial steps and data preparation */

{{ToModify}}
= Workshop introduction =
r.futures.* is an implementation of the '''FUT'''ure '''U'''rban-'''R'''egional '''E'''nvironment '''S'''imulation (FUTURES)[1] which is a model for multilevel simulations of emerging urban-rural landscape structure. FUTURES produces regional projections of landscape patterns using coupled submodels that integrate nonstationary drivers of land change: per capita demand (DEMAND submodel), site suitability (POTENTIAL submodel), and the spatial structure of conversion events (PGA submodel).

[1] Meentemeyer, R. K., Tang, W., Dorning, M. A., Vogler, J. B., Cunniffe, N. J., & Shoemaker, D. A. (2013). [http://www.tandfonline.com/doi/abs/10.1080/00045608.2012.707591 FUTURES: multilevel simulations of emerging urban-rural landscape structure using a stochastic patch-growing algorithm.] Annals of the Association of American Geographers, 103(4), 785-807

== Software ==
There are a number of software requirements to run FUTURES that will need to be download and installed. Required software includes:
* GRASS GIS 7
* addons
** {{AddonCmd|r.futures.pga}}
** {{AddonCmd|r.futures.potential}}
** {{AddonCmd|r.futures.potsurface}}
** {{AddonCmd|r.futures.demand}}
** {{AddonCmd|r.futures.devpressure}}
** {{AddonCmd|r.sample.category}}
* R (≥ 3.0.2) - needed for {{AddonCmd|r.futures.potential}} with packages:
**MuMIn, lme4, optparse, rgrass7
* SciPy - useful for {{AddonCmd|r.futures.demand}}

=== Installation ===
We use the R statistical software for our calculation of site suitability (i.e. development potential) in FUTURES. R is a free software environment for statistical computing and graphics. If you don't have R, or you have older an version, please download and install the software from [http://archive.linux.duke.edu/cran/ install R] and be sure to additionally add these required packages:
<pre>
install.packages(c("MuMIn", "lme4", "optparse", "rgrass7"))
</pre>

==== MS Windows ====
We will be using GRASS GIS 7.0.3 that can be found here in the [https://trac.osgeo.org/osgeo4w/ OSGeo4W] package manager.
Please install the latest stable GRASS GIS 7 version and the SciPy Python package using the ''Advanced install'' option.
A guide with step by step screen shot instructions is available [https://docs.google.com/presentation/d/1yEGpriBne7RvjB35HI6GecNwO1P1y2nRGqDThqoNnCE/edit?usp=sharing here].

In order for GRASS to be able to find R executables, GRASS must be on the PATH variable. Follow this [solution] to make R accessible from GRASS permanently.
A simple but temporary solution is to open GRASS GIS and paste this in the black terminal:
<pre>
set PATH=%PATH%;C:\Program Files\R\R-3.0.2\bin
</pre>
This has to be repeated after restarting GRASS session.

==== Ubuntu Linux ====
Install GRASS GIS from packages:
<pre>
sudo add-apt-repository ppa:ubuntugis/ubuntugis-unstable
sudo apt-get update
sudo apt-get install grass
</pre>

== Workshop data ==
The data that we will be using for the workshop can be download here: [http://fatra.cnr.ncsu.edu/futures/futures_ncspm_Asheville.zip sample dataset]. Please place these layers in your local GRASS directory:
* digital elevation model ([http://nationalmap.gov/elevation.html NED])
* [http://www.mrlc.gov/ NLCD] 2001, 2011
* NLCD 1992/2001 Retrofit Land Cover Change Product
* transportation network ([http://www.census.gov/geo/maps-data/data/tiger-line.html TIGER])
* county boundaries ([http://www.census.gov/geo/maps-data/data/tiger-line.html TIGER])
* protected areas ([http://www.conservationgateway.org/ConservationByGeography/NorthAmerica/UnitedStates/edc/reportsdata/terrestrial/secured/Pages/default.aspx Secured Lands])
* cities as points (USGS)

In addition, download [http://fatra.cnr.ncsu.edu/futures/futures_Asheville_files.zip population information as text files]:
* county population past estimates and future projections ([https://www.osbm.nc.gov/demog/county-projections NC OSBM]) per county (nonspatial)

= GRASS GIS introduction =
There are many advantages to using the open source GRASS GIS platform, but for many that are more familiar with ARCGis and QGis, the setup and implementation of spatial tools in GRASS can be confusing. Here we provide an overview of the GRASS GIS project: [https://grass.osgeo.org grass.osgeo.org] that might be helpful to review if you are a first time users. For this exercise it's not necessary to have a full understanding of how to use GRASS. However, you will need to know how to place your data in the correct GRASS database directory, as well as some basic GRASS functionality. Step by step instructions are provided below
== Setting up GRASS for the tutorial ==
GRASS uses unique database terminology and structure ([https://grass.osgeo.org/grass71/manuals/grass_database.html GRASS database]) that are important to understand for the set up of this tutorial, as you will need to place the required data (e.g. Mapset) in a specific GRASS database Location. In the following we review important terminology and give step by step direction on how to download and place you data in the correct location.

=== Important GRASS directory terminology ===
* A '''GRASS database''' consist of directory with specific Locations (projects) where data layer are stored
* '''Location''' hold all Mapsets in a specific directoy that have the same spatial projection (spatial reference system)
* '''Mapset''' are a collection of maps with the same spatial projection

=== Creating a GRASS database for the tutorial ===
You need to create a GRASS database with the Mapset that we will use for the tutorial before we can run the FUTURES model. Please Download the [http://fatra.cnr.ncsu.edu/futures/futures_ncspm_Asheville.zip workshop location], noting where the files are located on your local directory. Now, create (unless you already have it) a directory named <tt>grassdata</tt> (GRASS database) in your home folder (or Documents), unzip the downloaded data into this directory. You should now have a Location <tt>futures_ncspm</tt> in <tt>grassdata</tt>.

<center><gallery perrow=1 widths=500 heights=250>Image:GRASS FUTURES startup.png|GRASS GIS 7.0.3 startup dialog with downloaded Location and Mapsets for FUTURES workshop</gallery></center>

=== Launching and exploring data in GRASS ===
Now that we have the data in the correct GRASS database, we can launch the Graphical User Interface (GUI). The GUI interface allows you to display raster, vector data as well as navigate through zooming in and out. Advanced exploration and visualization, like many popular GIS software, is also possible in GRASS (e.g. queries, adding legend). The print screens below depicts how you can add different map layers (left) and display the metadata of your data layers.

<center><gallery perrow=2 widths=500 heights=250>Image:GRASS FUTURES wxGUI display.png|Layer Manager and Map Display overview. Annotations show how to add raster layer, query, add legend.
Image:wxGUI_metadata_rinfo.png|Show raster map metadata by right click on layer</gallery></center>

== GRASS functionality ==
One of the advantage of GRASS is the diversity and number of module addons that let you analyze all manner of spatial and temporal. Because it is open source modules are added daily increasing functionality and methods for analysis of your data. GRASS GIS has over [https://grass.osgeo.org/grass70/manuals/full_index.html 500 different modules] in the core distribution and over [https://grass.osgeo.org/grass70/manuals/addons/ 230 addon modules] that can be used to prepare and analyze data layers.
<center>
{| class="wikitable"
|-
! Prefix !! Function !! Example
|-
| r.* || raster processing || ''{{cmd|r.mapcalc}}'': map algebra
|-
| v.* || vector processing || ''{{cmd|v.clean}}'': topological cleaning
|-
| i.* || imagery processing || ''{{cmd|i.segment}}'': object recognition
|-
| db.* || database management || ''{{cmd|db.select}}'': select values from table
|-
| r3.* || 3D raster processing || ''{{cmd|r3.stats}}'': 3D raster statistics
|-
| t.* || temporal data processing || ''{{cmd|t.rast.aggregate}}'': temporal aggregation
|-
| g.* || general data management || ''{{cmd|g.rename}}'': renames map
|-
| d.* || display ||''{{cmd|d.rast}}'': display raster map
|}</center>

=== Command line vs. GUI interface===
GRASS modules can be executed either through a GUI or command line interface. The GUI offers a user-friendly approach to executing modules where the user can navigate to data layers that they would like to analyze and modify processing options with simple check boxes. The GUI also offer a easily accessible manual on how to execute a model. The command line interface allows users to execute a module using command prompts specific to that module. This is handy when you are running similar analyses with minor modification or are familiar with the module commands for quick efficient processing. In this workshop we provide module prompts that can be copy and pasted into the command line for our workflow, but you can use both GUI and command line depending on personal preference. Look how {{cmd|wxGUI.modules|version=71|desc=GUI and command line interface}} represent the same tool. ''Task:'' compute aspect (orientation) from provided digital elevation model using module {{cmd|r.slope.aspect}} using both module dialog and command line.
* How to find modules? Modules are organized by their functionality in wxGUI menu, or we can search for them in Search modules tab. If we already know which module to use, we can just type it in the wxGUI command console. <center><gallery perrow=3 widths=380 heights=190>Image:wxGUI_menu_rinfo.png|Modules can be found in wxGUI menu
Image:wxGUI_module_search.png|You can search modules by name, description or keywords in ''Search modules'' tab
Image:wxGUI_console_completion.png|By typing prefix r. we make a list of modules starting with that prefix to show up.</gallery></center>

=== Computational region===

{{cmd|g.region|desc=Computational region}} - is an important raster concept in GRASS that needs some explanation. In GRASS a computational region can be set, subsetting larger extent data for quicker testing of analysis or analysis of specific regions based on adminstrative units. We provide a few points to keep in mind when using the computational region function:
* defined by region extent and raster resolution
* applies to all raster operations
* persists between GRASS session, can be different for different mapsets
* advantages: keeps your results consistent, avoid clipping, for computationally demanding tasks set region to smaller extent, check your result is good and then set the computational region to the entire study area and rerun analysis
* run <code>g.region -p</code> or in menu ''Settings'' - ''Region'' - ''Display region'' to see current region settings
[[File:WxGUI set region.png|700px|thumb|center|Simple ways to set computational region from GUI. On the left, set region to match raster map. On the right, select the highlighted option and then set region by drawing rectangle.]]

* GRASS 3D view

= Modeling with FUTURES =
== Initial steps and data preparation ==
First we will set the computational region of our analyses to an extent covering our study area that aligns with our base landuse rasters. ''Like explained in the instructions above, you simply need copy and paste these commands into the command prompt of GRASS''.
<source lang="bash">g.region raster=landuse_2011 -p</source>

The FUTURES model uses the locations of development and new development to predict when and where new urban growth will occur. This requires longitudinal data on urban land use. We will derive urbanized areas from NLCD dataset for year 1992, 2001 and 2011
by extracting categories category 21 - 24 into a new binary map where developed is 1,
undeveloped 0 and NULL (no data). The NULL area is important in simulating urban growth as it preclude these are from becoming development. For this exercise we assume that water, wetlands and protected areas can not be developed, setting them to NULL.
First we will convert protected areas from vector to raster. We set
NULLs to zeros (for simpler raster algebra expression in the next step) using {{cmd|r.null}}:

<source lang="bash">
v.to.rast input=protected_areas output=protected_areas use=val
r.null map=protected_areas null=0
</source>

And then create rasters of developed/undeveloped areas using raster algebra:

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.mapcalc "urban_1992 = if(landuse_1992 >= 21 && landuse_1992 <= 24, 1, if(landuse_1992 == 11 || landuse_1992 >= 90 || protected_areas, null(), 0))"
r.mapcalc "urban_2001 = if(landuse_2001 >= 21 && landuse_2001 <= 24, 1, if(landuse_2001 == 11 || landuse_2001 >= 90 || protected_areas, null(), 0))"
r.mapcalc "urban_2011 = if(landuse_2011 >= 21 && landuse_2011 <= 24, 1, if(landuse_2011 == 11 || landuse_2011 >= 90 || protected_areas, null(), 0))"
</source>

FUTURES is a multi-level modelling framework meaning that we model population projections for subregions and assume that these subregions are influenced differently by the factors that influence where development happens. This requires defining subregions for model implementation. For this exercise we use the county level, which is the finest scale of population data that is available to us. We therefore need to convert vectors of counties to a raster with the values of the FIPS attribute which links to population file:

<source lang="bash">
v.to.rast input=counties type=area use=attr attribute_column=FIPS output=counties
</source>

Before further steps, we will set our working directory so that the input population files and text files
we are going to create are saved in one directory and easily accessible.
You can do that from menu ''Settings'' → ''GRASS working environment'' → ''Change working directory''.
Select (or create) a directory and move there the downloaded files <tt>population_projection.csv</tt> and <tt>population_trend.csv</tt>.

== Potential submodel ==
Module {{AddonCmd|r.futures.potential}} implements POTENTIAL submodel as a part of FUTURES land change model. POTENTIAL is implemented using a set of coefficients that relate a selection of site suitability factors to the probability of a place becoming developed. This is implemented using the parameter table in combination with maps of those site suitability factors (mapped predictors). The coefficients are obtained by conducting multilevel logistic regression in R with package lme4 where the coefficients may vary by county. The best model is selected automatically using dredge function from package [https://cran.r-project.org/web/packages/MuMIn/index.html MuMIn].

First, we will derive couple of predictors.
=== Predictors ===
==== Slope ====
We will derive slope in degrees from digital elevation model using {{cmd|r.slope.aspect}} module:
<source lang="bash">r.slope.aspect elevation=elevation_30m slope=slope</source>

==== Distance from lakes/rivers ====
First we will extract [http://www.mrlc.gov/nlcd11_leg.php category ''Open Water''] from 2011 NLCD dataset:
<source lang="bash">
r.mapcalc "water = if(landuse_2011 == 11, 1, null())"
</source>

Then we compute the distance to water with module {{cmd|r.grow.distance}} and set color table to shades of blue:
<source lang="bash">
r.grow.distance input=water distance=dist_to_water
r.colors -n map=dist_to_water color=blues
</source>

==== Distance from protected areas ====
We will use raster protected of protected areas we already created, but we will set NULL values to zero.
We compute the distance to protected areas with module {{cmd|r.grow.distance}} and set color table from green to red:
<source lang="bash">
r.null map=protected_areas setnull=0
r.grow.distance input=protected_areas distance=dist_to_protected
r.colors map=dist_to_protected color=gyr
</source>

==== Forests ====
We will smooth the transition between forest and other land use, see NLCD [http://www.mrlc.gov/nlcd11_leg.php category ''Open Water'']:
<source lang="bash">
r.mapcalc "forest = if(landuse_2011 >= 41 && landuse_2011 <= 43, 1, 0)"
r.neighbors -c input=forest output=forest_smooth size=15 method=average
r.colors map=forest_smooth color=ndvi
</source>

==== Travel time to cities ====
Here we will compute travel time to cities (with population > 5000)
as cumulative cost distance where cost is defined as travel time on roads.
First we specify the speed on different types of roads.
We copy the roads raster into our mapset so that we can change it
by adding a new attribute field <tt>speed</tt>. Then we assign speed values (km/h) based on the type of road:

<source lang="bash">
g.copy vector=roads,myroads
v.db.addcolumn map=myroads columns="speed double precision"
v.db.update map=myroads column=speed value=50 where="MTFCC = 'S1400'"
v.db.update map=myroads column=speed value=100 where="MTFCC IN ('S1100', 'S1200')"
</source>

Now we rasterize the selected road types using the speed values from the attribute table as raster values.

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
v.to.rast input=myroads type=line where="MTFCC IN ('S1100', 'S1200', 'S1400')" output=roads_speed use=attr attribute_column=speed
</source>

We set the rest of the area to low speed and recompute the speed as time to travel through a 30m cell in minutes:

<source lang="bash">
r.null map=roads_speed null=5
r.mapcalc "roads_travel_time = 1.8 / roads_speed"
</source>

Finally we compute the travel time to larger cities using {{cmd|r.cost}}:

<source lang="bash">
r.cost input=roads_travel_time output=travel_time_cities start_points=cities
r.colors map=travel_time_cities color=byr
</source>

==== Road density ====
We will rasterize roads and use moving window analysis ({{cmd|r.neighbors}}) to compute road density:

<source lang="bash">
v.to.rast input=roads output=roads use=val type=line
r.null map=roads null=0
r.neighbors -c input=roads output=road_dens size=25 method=average
</source>

==== Distance to interchanges ====

We will consider TIGER roads of type <tt>Ramp</tt> as interchanges, rasterize them and compute euclidean distance to them:

<source lang="bash">
v.to.rast input=roads type=line where="MTFCC = 'S1630'" output=interchanges use=val
r.grow.distance -m input=interchanges distance=dist_interchanges
</source>

=== Development pressure ===

We compute development pressure with {{AddonCmd|r.futures.devpressure}}. Development pressure is a predictor based on number of neighboring developed cells within search distance, weighted by distance. The development pressure variable plays a special role in the model, allowing for a feedback between predicted change and change in subsequent steps.

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.devpressure -n input=urban_2011 output=devpressure_2 method=gravity size=7 gamma=2 scaling_factor=10
r.futures.devpressure -n input=urban_2011 output=devpressure_1 method=gravity size=10 gamma=1 scaling_factor=1
r.futures.devpressure -n input=urban_2011 output=devpressure_0_5 method=gravity size=30 gamma=0.5 scaling_factor=0.1
</source>

When gamma increases, development influence decreases more rapidly with distance.
Size is half the size of the moving window. When gamma is low, local development influences more distant places.
We will derive 3 layers with different gamma and size parameters for the potential statistical model.

=== Rescaling variables ===

First we will look at the ranges of our predictor variables by running a short Python code snippet in Python shell:

<source lang="python" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
for name in ['slope', 'dist_to_water', 'dist_to_protected', 'forest_smooth', 'travel_time_cities', 'road_dens', 'dist_interchanges', 'devpressure_0_5', 'devpressure_1']:
minmax = grass.raster_info(name)
print name, minmax['min'], minmax['max']
</source>

We will rescale some of our input variables:

<source lang="bash">
r.mapcalc "dist_to_water_km = dist_to_water / 1000"
r.mapcalc "dist_to_protected_km = dist_to_protected / 1000"
r.mapcalc "dist_interchanges_km = dist_interchanges / 1000"
r.mapcalc "road_dens_perc = road_dens * 100"
r.mapcalc "forest_smooth_perc = forest_smooth * 100"
</source>

=== Sampling ===
To sample only in the analyzed counties, we will clip development layer:

<source lang="bash">
r.mapcalc "urban_change_01_11 = if(urban_2011 == 1, if(urban_2001 == 0, 1, null()), 0)"
r.mapcalc "urban_change_clip = if(counties, urban_change_01_11)"
</source>

To estimate the number of sampling points, we can use {{cmd|r.report}} to report number of developed/undeveloped cells and their ratio.

<source lang="bash">
r.report map=urban_change_clip units=h,c,p
</source>

We will sample the predictors and the response variable with 5000 random points in undeveloped areas and 1000 points in developed area:

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.sample.category input=urban_change_clip output=sampling sampled=counties,devpressure_0_5,devpressure_1,devpressure_2,slope,road_dens_perc,forest_smooth_perc,dist_to_water_km,dist_to_protected_km,dist_interchanges_km,travel_time_cities npoints=5000,1000
</source>

The attribute table can be exported as CSV file (not necessary step):

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
v.db.select map=sampling columns=urban_change_clip,counties,devpressure_0_5,devpressure_1,slope,road_dens_perc,forest_smooth_perc,dist_to_water_km,dist_to_protected_km,dist_interchanges_km,travel_time_cities separator=comma file=samples.csv
</source>

=== Development potential ===
Now we find best model for predicting urbanization using {{AddonCmd|r.futures.potential}} which wraps an R script.

We can run R [http://www.inside-r.org/packages/cran/MuMIn/docs/dredge dredge] function to find "best" model. We can specify minimum and maximum number of predictors the final model should use.
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.potential -d input=sampling output=potential.csv columns=devpressure_1,slope,road_dens_perc,forest_smooth_perc,dist_to_water_km,dist_to_protected_km,dist_interchanges_km,travel_time_cities developed_column=urban_change_clip subregions_column=counties min_variables=4
</source>

Also, we can play with different combinations of predictors, for example:

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.potential input=sampling output=potential.csv columns=devpressure_2,road_dens_perc,slope,dist_interchanges_km,dist_to_water_km developed_column=urban_change_clip subregions_column=counties --o
r.futures.potential input=sampling output=potential.csv columns=devpressure_1,road_dens_perc,slope,dist_interchanges_km,dist_to_water_km developed_column=urban_change_clip subregions_column=counties --o
...
</source>

You can then open the output file <tt>potential.csv</tt>, which is a CSV file with tabs as separators.

For this tutorial, the final potential is created with:
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.potential input=sampling output=potential.csv columns=devpressure_2,road_dens_perc,slope,dist_interchanges_km,dist_to_water_km developed_column=urban_change_clip subregions_column=counties --o
</source>

We can now visualize the suitability surface using module {{AddonCmd|r.futures.potsurface}}. It creates initial development potential (suitability) raster from predictors and model coefficients and serves only for evaluating development potential model. The values of the resulting raster range from 0 to 1.

<source lang="bash">
r.futures.potsurface input=potential.csv subregions=counties output=suitability
r.colors map=suitability color=byr
</source>

== Demand submodel ==
First we will mask out roads so that they don't influence into per capita land demand relation.
<source lang="bash">
v.to.rast input=roads type=line output=roads_mask use=val
r.mask roads_mask -i
</source>

We will use {{AddonCmd|r.futures.demand}} which derives the population vs. development relation. The relation can be linear/logarithmic/logarithmic2/exponential/exponential approach.
Look for examples of the different relations in the manual.

* linear: y = A + Bx
* logarithmic: y = A + Bln(x)
* logarithmic2: y = A + B * ln(x - C)        (requires SciPy)
* exponential: y = Ae^(BX)
* exp_approach: y = (1 - e^(-A(x - B))) + C        (requires SciPy)

The format of the input population CSV files is described in the manual. It is important to have synchronized categories of subregions and the column headers of the CSV files (in our case FIPS number). How to simply generate the list of years (for which demand is computed) is described in {{AddonCmd|r.futures.demand}} manual, for example run this in Python console:

<source lang="python">
','.join([str(i) for i in range(2011, 2036)])
</source>

Then we can create the DEMAND file:
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.demand development=urban_1992,urban_2001,urban_2011 subregions=counties observed_population=population_trend.csv projected_population=population_projection.csv simulation_times=2011,2012,2013,2014,2015,2016,2017,2018,2019,2020,2021,2022,2023,2024,2025,2026,2027,2028,2029,2030,2031,2032,2033,2034,2035 plot=plot_demand.pdf demand=demand.csv separator=comma
</source>

In your current working directory, you should find files <tt>plot_demand.png</tt> and <tt>demand.csv</tt>.

If you have SciPy installed, you can experiment with other methods for fitting the functions:
<source lang="bash">
r.futures.demand ... method=logarithmic2
r.futures.demand ... method=exp_approach
</source>
If necessary, you can create a set of demand files produced by fitting each method separately and
then pick for each county the method which seems best and manually create a new demand file.

When you are finished, remove the mask as it is not needed for the next steps.
<source lang="bash">
r.mask -r
</source>

== Patch calibration ==
Patch calibration can be a very time consuming computation.
Therefore we select only one county (Buncombe):

<source lang="bash">
v.to.rast input=counties type=area where="FIPS == 37021" use=attr attribute_column=FIPS output=calib_county
g.region raster=calib_county zoom=calib_county
</source>
to derive patches of new development by comparing historical and latest development.
We can keep only patches with minimum size 2 cells (1800 = 2 x 30 x 30 m).

<source lang="bash">
r.futures.calib development_start=urban_1992 development_end=urban_2011 subregions=counties patch_sizes=patches.txt patch_threshold=1800 -l
</source>
We obtained a file <tt>patches.txt</tt> (used later in the PGA) - a patch size distribution file - containing sizes of all found patches.

We can look at the distribution of the patch sizes:

<source lang="python">
from matplotlib import pyplot as plt
with open('patches.txt') as f:
patches = [int(patch) for patch in f.readlines()]
plt.hist(patches, 2000)
plt.xlim(0,50)
plt.show()
</source>

At this point, we start the calibration to get best parameters of patch shape
(for this tutorial, this step can be skipped and the suggested parameters are used).

<source lang="bash"
style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.calib development_start=urban_1992 development_end=urban_2011 subregions=calib_county patch_sizes=patches.txt calibration_results=calib.csv patch_threshold=1800 repeat=5 compactness_mean=0.1,0.3,0.5,0.7,0.9 compactness_range=0.05 discount_factor=0.1,0.3,0.5,0.7,0.9 predictors=road_dens_perc,forest_smooth_perc,dist_to_protected_km demand=demand.csv devpot_params=potential.csv num_neighbors=4 seed_search=2 development_pressure=devpressure_0_5 development_pressure_approach=gravity n_dev_neighbourhood=30 gamma=0.5 scaling_factor=0.1
</source>

== FUTURES simulation ==
We will switch back to our previous region:
<source lang="bash">
g.region raster=landuse_2011 -p
</source>

Now we have all the inputs necessary for running {{AddonCmd|r.futures.pga}}:

The entire command is here:
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.pga subregions=counties developed=urban_2011 predictors=slope,forest_smooth_perc,dist_interchanges_km,travel_time_cities devpot_params=potential.csv development_pressure=devpressure_1 n_dev_neighbourhood=10 development_pressure_approach=gravity gamma=1 scaling_factor=1 demand=demand.csv discount_factor=0.3 compactness_mean=0.2 compactness_range=0.1 patch_sizes=patches.txt num_neighbors=4 seed_search=2 random_seed=1 output=final output_series=final
</source>

=== Quick description ===
The command parameters and their values:
* raster map of counties with their categories
<code>
... subregions=counties ...
</code>

* raster of developed (1), undeveloped (0) and NULLs for undevelopable areas
<code>
... developed=urban_2011 ...
</code>

* predictors selected with {{AddonCmd|r.futures.potential}} and their coefficients in a <tt>potential.csv</tt> file. The order of predictors must match the order in the file and the categories of the counties must match raster <tt>counties</tt>.
<code>
... predictors=slope,forest_smooth_perc,dist_interchanges_km,travel_time_cities devpot_params=potential.csv ...
</code>

* initial development pressure computed by {{AddonCmd|r.futures.devpressure}}, it's important to set here the same parameters
<code>
... development_pressure=devpressure_1 n_dev_neighbourhood=10 development_pressure_approach=gravity gamma=1 scaling_factor=1 ...
</code>

* per capita land demand computed by {{AddonCmd|r.futures.demand}}, the categories of the counties must match raster <tt>counties</tt>.
<code>
... demand=demand.csv ...
</code>

* patch parameters from the calibration step
<code>
... discount_factor=0.3 compactness_mean=0.4 compactness_range=0.08 patch_sizes=patches.txt ...
</code>

* recommended parameters for patch growing algorithm
<code>
... num_neighbors=4 seed_search=2 ...
</code>

* set random seed for repeatable results or set flag <tt>-s</tt> to generate seed automatically
<code>
... random_seed=1 ...
</code>

* specify final output map and optionally basename for intermediate raster maps
<code>
output=final output_series=final
</code>

== Scenarios ==
Scenarios involving policies that encourage infill versus sprawl can be explored using the <tt>incentive_power</tt> parameter of {{AddonCmd|r.futures.pga}},
which uses a power function to transform the evenness of the probability gradient in POTENTIAL. You can change the power to a number between 0.25 and 4 to test urban sprawl/infill scenarios.
Higher power leads to infill behavior, lower power to urban sprawl.

== Postprocessing ==

Follow a [[Creating_animation_from_FUTURES_output_in_GRASS_GIS| tutorial how to make an animation from the results]].

= GRASS GIS Python API =

[[Category: Tutorial]]
[[Category: FUTURES]]
[[Category: Urban]]

Workshop on urban growth modeling with FUTURES

2016-03-22T19:57:39Z

⚠️Dbvanber: /* Initial steps and data preparation */

{{ToModify}}
= Workshop introduction =
r.futures.* is an implementation of the '''FUT'''ure '''U'''rban-'''R'''egional '''E'''nvironment '''S'''imulation (FUTURES)[1] which is a model for multilevel simulations of emerging urban-rural landscape structure. FUTURES produces regional projections of landscape patterns using coupled submodels that integrate nonstationary drivers of land change: per capita demand (DEMAND submodel), site suitability (POTENTIAL submodel), and the spatial structure of conversion events (PGA submodel).

[1] Meentemeyer, R. K., Tang, W., Dorning, M. A., Vogler, J. B., Cunniffe, N. J., & Shoemaker, D. A. (2013). [http://www.tandfonline.com/doi/abs/10.1080/00045608.2012.707591 FUTURES: multilevel simulations of emerging urban-rural landscape structure using a stochastic patch-growing algorithm.] Annals of the Association of American Geographers, 103(4), 785-807

== Software ==
There are a number of software requirements to run FUTURES that will need to be download and installed. Required software includes:
* GRASS GIS 7
* addons
** {{AddonCmd|r.futures.pga}}
** {{AddonCmd|r.futures.potential}}
** {{AddonCmd|r.futures.potsurface}}
** {{AddonCmd|r.futures.demand}}
** {{AddonCmd|r.futures.devpressure}}
** {{AddonCmd|r.sample.category}}
* R (≥ 3.0.2) - needed for {{AddonCmd|r.futures.potential}} with packages:
**MuMIn, lme4, optparse, rgrass7
* SciPy - useful for {{AddonCmd|r.futures.demand}}

=== Installation ===
We use the R statistical software for our calculation of site suitability (i.e. development potential) in FUTURES. R is a free software environment for statistical computing and graphics. If you don't have R, or you have older an version, please download and install the software from [http://archive.linux.duke.edu/cran/ install R] and be sure to additionally add these required packages:
<pre>
install.packages(c("MuMIn", "lme4", "optparse", "rgrass7"))
</pre>

==== MS Windows ====
We will be using GRASS GIS 7.0.3 that can be found here in the [https://trac.osgeo.org/osgeo4w/ OSGeo4W] package manager.
Please install the latest stable GRASS GIS 7 version and the SciPy Python package using the ''Advanced install'' option.
A guide with step by step screen shot instructions is available [https://docs.google.com/presentation/d/1yEGpriBne7RvjB35HI6GecNwO1P1y2nRGqDThqoNnCE/edit?usp=sharing here].

In order for GRASS to be able to find R executables, GRASS must be on the PATH variable. Follow this [solution] to make R accessible from GRASS permanently.
A simple but temporary solution is to open GRASS GIS and paste this in the black terminal:
<pre>
set PATH=%PATH%;C:\Program Files\R\R-3.0.2\bin
</pre>
This has to be repeated after restarting GRASS session.

==== Ubuntu Linux ====
Install GRASS GIS from packages:
<pre>
sudo add-apt-repository ppa:ubuntugis/ubuntugis-unstable
sudo apt-get update
sudo apt-get install grass
</pre>

== Workshop data ==
The data that we will be using for the workshop can be download here: [http://fatra.cnr.ncsu.edu/futures/futures_ncspm_Asheville.zip sample dataset]. Please place these layers in your local GRASS directory:
* digital elevation model ([http://nationalmap.gov/elevation.html NED])
* [http://www.mrlc.gov/ NLCD] 2001, 2011
* NLCD 1992/2001 Retrofit Land Cover Change Product
* transportation network ([http://www.census.gov/geo/maps-data/data/tiger-line.html TIGER])
* county boundaries ([http://www.census.gov/geo/maps-data/data/tiger-line.html TIGER])
* protected areas ([http://www.conservationgateway.org/ConservationByGeography/NorthAmerica/UnitedStates/edc/reportsdata/terrestrial/secured/Pages/default.aspx Secured Lands])
* cities as points (USGS)

In addition, download [http://fatra.cnr.ncsu.edu/futures/futures_Asheville_files.zip population information as text files]:
* county population past estimates and future projections ([https://www.osbm.nc.gov/demog/county-projections NC OSBM]) per county (nonspatial)

= GRASS GIS introduction =
There are many advantages to using the open source GRASS GIS platform, but for many that are more familiar with ARCGis and QGis, the setup and implementation of spatial tools in GRASS can be confusing. Here we provide an overview of the GRASS GIS project: [https://grass.osgeo.org grass.osgeo.org] that might be helpful to review if you are a first time users. For this exercise it's not necessary to have a full understanding of how to use GRASS. However, you will need to know how to place your data in the correct GRASS database directory, as well as some basic GRASS functionality. Step by step instructions are provided below
== Setting up GRASS for the tutorial ==
GRASS uses unique database terminology and structure ([https://grass.osgeo.org/grass71/manuals/grass_database.html GRASS database]) that are important to understand for the set up of this tutorial, as you will need to place the required data (e.g. Mapset) in a specific GRASS database Location. In the following we review important terminology and give step by step direction on how to download and place you data in the correct location.

=== Important GRASS directory terminology ===
* A '''GRASS database''' consist of directory with specific Locations (projects) where data layer are stored
* '''Location''' hold all Mapsets in a specific directoy that have the same spatial projection (spatial reference system)
* '''Mapset''' are a collection of maps with the same spatial projection

=== Creating a GRASS database for the tutorial ===
You need to create a GRASS database with the Mapset that we will use for the tutorial before we can run the FUTURES model. Please Download the [http://fatra.cnr.ncsu.edu/futures/futures_ncspm_Asheville.zip workshop location], noting where the files are located on your local directory. Now, create (unless you already have it) a directory named <tt>grassdata</tt> (GRASS database) in your home folder (or Documents), unzip the downloaded data into this directory. You should now have a Location <tt>futures_ncspm</tt> in <tt>grassdata</tt>.

<center><gallery perrow=1 widths=500 heights=250>Image:GRASS FUTURES startup.png|GRASS GIS 7.0.3 startup dialog with downloaded Location and Mapsets for FUTURES workshop</gallery></center>

=== Launching and exploring data in GRASS ===
Now that we have the data in the correct GRASS database, we can launch the Graphical User Interface (GUI). The GUI interface allows you to display raster, vector data as well as navigate through zooming in and out. Advanced exploration and visualization, like many popular GIS software, is also possible in GRASS (e.g. queries, adding legend). The print screens below depicts how you can add different map layers (left) and display the metadata of your data layers.

<center><gallery perrow=2 widths=500 heights=250>Image:GRASS FUTURES wxGUI display.png|Layer Manager and Map Display overview. Annotations show how to add raster layer, query, add legend.
Image:wxGUI_metadata_rinfo.png|Show raster map metadata by right click on layer</gallery></center>

== GRASS functionality ==
One of the advantage of GRASS is the diversity and number of module addons that let you analyze all manner of spatial and temporal. Because it is open source modules are added daily increasing functionality and methods for analysis of your data. GRASS GIS has over [https://grass.osgeo.org/grass70/manuals/full_index.html 500 different modules] in the core distribution and over [https://grass.osgeo.org/grass70/manuals/addons/ 230 addon modules] that can be used to prepare and analyze data layers.
<center>
{| class="wikitable"
|-
! Prefix !! Function !! Example
|-
| r.* || raster processing || ''{{cmd|r.mapcalc}}'': map algebra
|-
| v.* || vector processing || ''{{cmd|v.clean}}'': topological cleaning
|-
| i.* || imagery processing || ''{{cmd|i.segment}}'': object recognition
|-
| db.* || database management || ''{{cmd|db.select}}'': select values from table
|-
| r3.* || 3D raster processing || ''{{cmd|r3.stats}}'': 3D raster statistics
|-
| t.* || temporal data processing || ''{{cmd|t.rast.aggregate}}'': temporal aggregation
|-
| g.* || general data management || ''{{cmd|g.rename}}'': renames map
|-
| d.* || display ||''{{cmd|d.rast}}'': display raster map
|}</center>

=== Command line vs. GUI interface===
GRASS modules can be executed either through a GUI or command line interface. The GUI offers a user-friendly approach to executing modules where the user can navigate to data layers that they would like to analyze and modify processing options with simple check boxes. The GUI also offer a easily accessible manual on how to execute a model. The command line interface allows users to execute a module using command prompts specific to that module. This is handy when you are running similar analyses with minor modification or are familiar with the module commands for quick efficient processing. In this workshop we provide module prompts that can be copy and pasted into the command line for our workflow, but you can use both GUI and command line depending on personal preference. Look how {{cmd|wxGUI.modules|version=71|desc=GUI and command line interface}} represent the same tool. ''Task:'' compute aspect (orientation) from provided digital elevation model using module {{cmd|r.slope.aspect}} using both module dialog and command line.
* How to find modules? Modules are organized by their functionality in wxGUI menu, or we can search for them in Search modules tab. If we already know which module to use, we can just type it in the wxGUI command console. <center><gallery perrow=3 widths=380 heights=190>Image:wxGUI_menu_rinfo.png|Modules can be found in wxGUI menu
Image:wxGUI_module_search.png|You can search modules by name, description or keywords in ''Search modules'' tab
Image:wxGUI_console_completion.png|By typing prefix r. we make a list of modules starting with that prefix to show up.</gallery></center>

=== Computational region===

{{cmd|g.region|desc=Computational region}} - is an important raster concept in GRASS that needs some explanation. In GRASS a computational region can be set, subsetting larger extent data for quicker testing of analysis or analysis of specific regions based on adminstrative units. We provide a few points to keep in mind when using the computational region function:
* defined by region extent and raster resolution
* applies to all raster operations
* persists between GRASS session, can be different for different mapsets
* advantages: keeps your results consistent, avoid clipping, for computationally demanding tasks set region to smaller extent, check your result is good and then set the computational region to the entire study area and rerun analysis
* run <code>g.region -p</code> or in menu ''Settings'' - ''Region'' - ''Display region'' to see current region settings
[[File:WxGUI set region.png|700px|thumb|center|Simple ways to set computational region from GUI. On the left, set region to match raster map. On the right, select the highlighted option and then set region by drawing rectangle.]]

* GRASS 3D view

= Modeling with FUTURES =
== Initial steps and data preparation ==
First we will set the computational region of our analyses to an extent covering our study area that aligns with our base landuse rasters. ''Like explained in the instructions above, you simply need copy and paste these commands into the command prompt of GRASS''.
<source lang="bash">g.region raster=landuse_2011 -p</source>

The FUTURES model uses the locations of development and new development to predict when and where new urban growth will occur. This requires longitudinal data on urban land use. We will derive urbanized areas from NLCD dataset for year 1992, 2001 and 2011
by extracting categories category 21 - 24 into a new binary map where developed is 1,
undeveloped 0 and NULL (no data). The NULL area is important in simulating urban growth as it preclude these are from becoming development. For this exercise we assume that water, wetlands and protected areas can not be developed, setting them to NULL.
First we will convert protected areas from vector to raster. We set
NULLs to zeros (for simpler raster algebra expression in the next step) using {{cmd|r.null}}:

<source lang="bash">
v.to.rast input=protected_areas output=protected_areas use=val
r.null map=protected_areas null=0
</source>

And then create rasters of developed/undeveloped areas using raster algebra:

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.mapcalc "urban_1992 = if(landuse_1992 >= 21 && landuse_1992 <= 24, 1, if(landuse_1992 == 11 || landuse_1992 >= 90 || protected_areas, null(), 0))"
r.mapcalc "urban_2001 = if(landuse_2001 >= 21 && landuse_2001 <= 24, 1, if(landuse_2001 == 11 || landuse_2001 >= 90 || protected_areas, null(), 0))"
r.mapcalc "urban_2011 = if(landuse_2011 >= 21 && landuse_2011 <= 24, 1, if(landuse_2011 == 11 || landuse_2011 >= 90 || protected_areas, null(), 0))"
</source>

We will convert vector counties to raster with the values of the FIPS attribute which links to population file:

<source lang="bash">
v.to.rast input=counties type=area use=attr attribute_column=FIPS output=counties
</source>

Before further steps, we will set our working directory so that the input population files and text files
we are going to create are saved in one directory and easily accessible.
You can do that from menu ''Settings'' → ''GRASS working environment'' → ''Change working directory''.
Select (or create) a directory and move there the downloaded files <tt>population_projection.csv</tt> and <tt>population_trend.csv</tt>.

== Potential submodel ==
Module {{AddonCmd|r.futures.potential}} implements POTENTIAL submodel as a part of FUTURES land change model. POTENTIAL is implemented using a set of coefficients that relate a selection of site suitability factors to the probability of a place becoming developed. This is implemented using the parameter table in combination with maps of those site suitability factors (mapped predictors). The coefficients are obtained by conducting multilevel logistic regression in R with package lme4 where the coefficients may vary by county. The best model is selected automatically using dredge function from package [https://cran.r-project.org/web/packages/MuMIn/index.html MuMIn].

First, we will derive couple of predictors.
=== Predictors ===
==== Slope ====
We will derive slope in degrees from digital elevation model using {{cmd|r.slope.aspect}} module:
<source lang="bash">r.slope.aspect elevation=elevation_30m slope=slope</source>

==== Distance from lakes/rivers ====
First we will extract [http://www.mrlc.gov/nlcd11_leg.php category ''Open Water''] from 2011 NLCD dataset:
<source lang="bash">
r.mapcalc "water = if(landuse_2011 == 11, 1, null())"
</source>

Then we compute the distance to water with module {{cmd|r.grow.distance}} and set color table to shades of blue:
<source lang="bash">
r.grow.distance input=water distance=dist_to_water
r.colors -n map=dist_to_water color=blues
</source>

==== Distance from protected areas ====
We will use raster protected of protected areas we already created, but we will set NULL values to zero.
We compute the distance to protected areas with module {{cmd|r.grow.distance}} and set color table from green to red:
<source lang="bash">
r.null map=protected_areas setnull=0
r.grow.distance input=protected_areas distance=dist_to_protected
r.colors map=dist_to_protected color=gyr
</source>

==== Forests ====
We will smooth the transition between forest and other land use, see NLCD [http://www.mrlc.gov/nlcd11_leg.php category ''Open Water'']:
<source lang="bash">
r.mapcalc "forest = if(landuse_2011 >= 41 && landuse_2011 <= 43, 1, 0)"
r.neighbors -c input=forest output=forest_smooth size=15 method=average
r.colors map=forest_smooth color=ndvi
</source>

==== Travel time to cities ====
Here we will compute travel time to cities (with population > 5000)
as cumulative cost distance where cost is defined as travel time on roads.
First we specify the speed on different types of roads.
We copy the roads raster into our mapset so that we can change it
by adding a new attribute field <tt>speed</tt>. Then we assign speed values (km/h) based on the type of road:

<source lang="bash">
g.copy vector=roads,myroads
v.db.addcolumn map=myroads columns="speed double precision"
v.db.update map=myroads column=speed value=50 where="MTFCC = 'S1400'"
v.db.update map=myroads column=speed value=100 where="MTFCC IN ('S1100', 'S1200')"
</source>

Now we rasterize the selected road types using the speed values from the attribute table as raster values.

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
v.to.rast input=myroads type=line where="MTFCC IN ('S1100', 'S1200', 'S1400')" output=roads_speed use=attr attribute_column=speed
</source>

We set the rest of the area to low speed and recompute the speed as time to travel through a 30m cell in minutes:

<source lang="bash">
r.null map=roads_speed null=5
r.mapcalc "roads_travel_time = 1.8 / roads_speed"
</source>

Finally we compute the travel time to larger cities using {{cmd|r.cost}}:

<source lang="bash">
r.cost input=roads_travel_time output=travel_time_cities start_points=cities
r.colors map=travel_time_cities color=byr
</source>

==== Road density ====
We will rasterize roads and use moving window analysis ({{cmd|r.neighbors}}) to compute road density:

<source lang="bash">
v.to.rast input=roads output=roads use=val type=line
r.null map=roads null=0
r.neighbors -c input=roads output=road_dens size=25 method=average
</source>

==== Distance to interchanges ====

We will consider TIGER roads of type <tt>Ramp</tt> as interchanges, rasterize them and compute euclidean distance to them:

<source lang="bash">
v.to.rast input=roads type=line where="MTFCC = 'S1630'" output=interchanges use=val
r.grow.distance -m input=interchanges distance=dist_interchanges
</source>

=== Development pressure ===

We compute development pressure with {{AddonCmd|r.futures.devpressure}}. Development pressure is a predictor based on number of neighboring developed cells within search distance, weighted by distance. The development pressure variable plays a special role in the model, allowing for a feedback between predicted change and change in subsequent steps.

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.devpressure -n input=urban_2011 output=devpressure_2 method=gravity size=7 gamma=2 scaling_factor=10
r.futures.devpressure -n input=urban_2011 output=devpressure_1 method=gravity size=10 gamma=1 scaling_factor=1
r.futures.devpressure -n input=urban_2011 output=devpressure_0_5 method=gravity size=30 gamma=0.5 scaling_factor=0.1
</source>

When gamma increases, development influence decreases more rapidly with distance.
Size is half the size of the moving window. When gamma is low, local development influences more distant places.
We will derive 3 layers with different gamma and size parameters for the potential statistical model.

=== Rescaling variables ===

First we will look at the ranges of our predictor variables by running a short Python code snippet in Python shell:

<source lang="python" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
for name in ['slope', 'dist_to_water', 'dist_to_protected', 'forest_smooth', 'travel_time_cities', 'road_dens', 'dist_interchanges', 'devpressure_0_5', 'devpressure_1']:
minmax = grass.raster_info(name)
print name, minmax['min'], minmax['max']
</source>

We will rescale some of our input variables:

<source lang="bash">
r.mapcalc "dist_to_water_km = dist_to_water / 1000"
r.mapcalc "dist_to_protected_km = dist_to_protected / 1000"
r.mapcalc "dist_interchanges_km = dist_interchanges / 1000"
r.mapcalc "road_dens_perc = road_dens * 100"
r.mapcalc "forest_smooth_perc = forest_smooth * 100"
</source>

=== Sampling ===
To sample only in the analyzed counties, we will clip development layer:

<source lang="bash">
r.mapcalc "urban_change_01_11 = if(urban_2011 == 1, if(urban_2001 == 0, 1, null()), 0)"
r.mapcalc "urban_change_clip = if(counties, urban_change_01_11)"
</source>

To estimate the number of sampling points, we can use {{cmd|r.report}} to report number of developed/undeveloped cells and their ratio.

<source lang="bash">
r.report map=urban_change_clip units=h,c,p
</source>

We will sample the predictors and the response variable with 5000 random points in undeveloped areas and 1000 points in developed area:

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.sample.category input=urban_change_clip output=sampling sampled=counties,devpressure_0_5,devpressure_1,devpressure_2,slope,road_dens_perc,forest_smooth_perc,dist_to_water_km,dist_to_protected_km,dist_interchanges_km,travel_time_cities npoints=5000,1000
</source>

The attribute table can be exported as CSV file (not necessary step):

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
v.db.select map=sampling columns=urban_change_clip,counties,devpressure_0_5,devpressure_1,slope,road_dens_perc,forest_smooth_perc,dist_to_water_km,dist_to_protected_km,dist_interchanges_km,travel_time_cities separator=comma file=samples.csv
</source>

=== Development potential ===
Now we find best model for predicting urbanization using {{AddonCmd|r.futures.potential}} which wraps an R script.

We can run R [http://www.inside-r.org/packages/cran/MuMIn/docs/dredge dredge] function to find "best" model. We can specify minimum and maximum number of predictors the final model should use.
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.potential -d input=sampling output=potential.csv columns=devpressure_1,slope,road_dens_perc,forest_smooth_perc,dist_to_water_km,dist_to_protected_km,dist_interchanges_km,travel_time_cities developed_column=urban_change_clip subregions_column=counties min_variables=4
</source>

Also, we can play with different combinations of predictors, for example:

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.potential input=sampling output=potential.csv columns=devpressure_2,road_dens_perc,slope,dist_interchanges_km,dist_to_water_km developed_column=urban_change_clip subregions_column=counties --o
r.futures.potential input=sampling output=potential.csv columns=devpressure_1,road_dens_perc,slope,dist_interchanges_km,dist_to_water_km developed_column=urban_change_clip subregions_column=counties --o
...
</source>

You can then open the output file <tt>potential.csv</tt>, which is a CSV file with tabs as separators.

For this tutorial, the final potential is created with:
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.potential input=sampling output=potential.csv columns=devpressure_2,road_dens_perc,slope,dist_interchanges_km,dist_to_water_km developed_column=urban_change_clip subregions_column=counties --o
</source>

We can now visualize the suitability surface using module {{AddonCmd|r.futures.potsurface}}. It creates initial development potential (suitability) raster from predictors and model coefficients and serves only for evaluating development potential model. The values of the resulting raster range from 0 to 1.

<source lang="bash">
r.futures.potsurface input=potential.csv subregions=counties output=suitability
r.colors map=suitability color=byr
</source>

== Demand submodel ==
First we will mask out roads so that they don't influence into per capita land demand relation.
<source lang="bash">
v.to.rast input=roads type=line output=roads_mask use=val
r.mask roads_mask -i
</source>

We will use {{AddonCmd|r.futures.demand}} which derives the population vs. development relation. The relation can be linear/logarithmic/logarithmic2/exponential/exponential approach.
Look for examples of the different relations in the manual.

* linear: y = A + Bx
* logarithmic: y = A + Bln(x)
* logarithmic2: y = A + B * ln(x - C)        (requires SciPy)
* exponential: y = Ae^(BX)
* exp_approach: y = (1 - e^(-A(x - B))) + C        (requires SciPy)

The format of the input population CSV files is described in the manual. It is important to have synchronized categories of subregions and the column headers of the CSV files (in our case FIPS number). How to simply generate the list of years (for which demand is computed) is described in {{AddonCmd|r.futures.demand}} manual, for example run this in Python console:

<source lang="python">
','.join([str(i) for i in range(2011, 2036)])
</source>

Then we can create the DEMAND file:
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.demand development=urban_1992,urban_2001,urban_2011 subregions=counties observed_population=population_trend.csv projected_population=population_projection.csv simulation_times=2011,2012,2013,2014,2015,2016,2017,2018,2019,2020,2021,2022,2023,2024,2025,2026,2027,2028,2029,2030,2031,2032,2033,2034,2035 plot=plot_demand.pdf demand=demand.csv separator=comma
</source>

In your current working directory, you should find files <tt>plot_demand.png</tt> and <tt>demand.csv</tt>.

If you have SciPy installed, you can experiment with other methods for fitting the functions:
<source lang="bash">
r.futures.demand ... method=logarithmic2
r.futures.demand ... method=exp_approach
</source>
If necessary, you can create a set of demand files produced by fitting each method separately and
then pick for each county the method which seems best and manually create a new demand file.

When you are finished, remove the mask as it is not needed for the next steps.
<source lang="bash">
r.mask -r
</source>

== Patch calibration ==
Patch calibration can be a very time consuming computation.
Therefore we select only one county (Buncombe):

<source lang="bash">
v.to.rast input=counties type=area where="FIPS == 37021" use=attr attribute_column=FIPS output=calib_county
g.region raster=calib_county zoom=calib_county
</source>
to derive patches of new development by comparing historical and latest development.
We can keep only patches with minimum size 2 cells (1800 = 2 x 30 x 30 m).

<source lang="bash">
r.futures.calib development_start=urban_1992 development_end=urban_2011 subregions=counties patch_sizes=patches.txt patch_threshold=1800 -l
</source>
We obtained a file <tt>patches.txt</tt> (used later in the PGA) - a patch size distribution file - containing sizes of all found patches.

We can look at the distribution of the patch sizes:

<source lang="python">
from matplotlib import pyplot as plt
with open('patches.txt') as f:
patches = [int(patch) for patch in f.readlines()]
plt.hist(patches, 2000)
plt.xlim(0,50)
plt.show()
</source>

At this point, we start the calibration to get best parameters of patch shape
(for this tutorial, this step can be skipped and the suggested parameters are used).

<source lang="bash"
style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.calib development_start=urban_1992 development_end=urban_2011 subregions=calib_county patch_sizes=patches.txt calibration_results=calib.csv patch_threshold=1800 repeat=5 compactness_mean=0.1,0.3,0.5,0.7,0.9 compactness_range=0.05 discount_factor=0.1,0.3,0.5,0.7,0.9 predictors=road_dens_perc,forest_smooth_perc,dist_to_protected_km demand=demand.csv devpot_params=potential.csv num_neighbors=4 seed_search=2 development_pressure=devpressure_0_5 development_pressure_approach=gravity n_dev_neighbourhood=30 gamma=0.5 scaling_factor=0.1
</source>

== FUTURES simulation ==
We will switch back to our previous region:
<source lang="bash">
g.region raster=landuse_2011 -p
</source>

Now we have all the inputs necessary for running {{AddonCmd|r.futures.pga}}:

The entire command is here:
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.pga subregions=counties developed=urban_2011 predictors=slope,forest_smooth_perc,dist_interchanges_km,travel_time_cities devpot_params=potential.csv development_pressure=devpressure_1 n_dev_neighbourhood=10 development_pressure_approach=gravity gamma=1 scaling_factor=1 demand=demand.csv discount_factor=0.3 compactness_mean=0.2 compactness_range=0.1 patch_sizes=patches.txt num_neighbors=4 seed_search=2 random_seed=1 output=final output_series=final
</source>

=== Quick description ===
The command parameters and their values:
* raster map of counties with their categories
<code>
... subregions=counties ...
</code>

* raster of developed (1), undeveloped (0) and NULLs for undevelopable areas
<code>
... developed=urban_2011 ...
</code>

* predictors selected with {{AddonCmd|r.futures.potential}} and their coefficients in a <tt>potential.csv</tt> file. The order of predictors must match the order in the file and the categories of the counties must match raster <tt>counties</tt>.
<code>
... predictors=slope,forest_smooth_perc,dist_interchanges_km,travel_time_cities devpot_params=potential.csv ...
</code>

* initial development pressure computed by {{AddonCmd|r.futures.devpressure}}, it's important to set here the same parameters
<code>
... development_pressure=devpressure_1 n_dev_neighbourhood=10 development_pressure_approach=gravity gamma=1 scaling_factor=1 ...
</code>

* per capita land demand computed by {{AddonCmd|r.futures.demand}}, the categories of the counties must match raster <tt>counties</tt>.
<code>
... demand=demand.csv ...
</code>

* patch parameters from the calibration step
<code>
... discount_factor=0.3 compactness_mean=0.4 compactness_range=0.08 patch_sizes=patches.txt ...
</code>

* recommended parameters for patch growing algorithm
<code>
... num_neighbors=4 seed_search=2 ...
</code>

* set random seed for repeatable results or set flag <tt>-s</tt> to generate seed automatically
<code>
... random_seed=1 ...
</code>

* specify final output map and optionally basename for intermediate raster maps
<code>
output=final output_series=final
</code>

== Scenarios ==
Scenarios involving policies that encourage infill versus sprawl can be explored using the <tt>incentive_power</tt> parameter of {{AddonCmd|r.futures.pga}},
which uses a power function to transform the evenness of the probability gradient in POTENTIAL. You can change the power to a number between 0.25 and 4 to test urban sprawl/infill scenarios.
Higher power leads to infill behavior, lower power to urban sprawl.

== Postprocessing ==

Follow a [[Creating_animation_from_FUTURES_output_in_GRASS_GIS| tutorial how to make an animation from the results]].

= GRASS GIS Python API =

[[Category: Tutorial]]
[[Category: FUTURES]]
[[Category: Urban]]

Workshop on urban growth modeling with FUTURES

2016-03-22T19:54:48Z

⚠️Dbvanber: /* Initial steps and data preparation */

{{ToModify}}
= Workshop introduction =
r.futures.* is an implementation of the '''FUT'''ure '''U'''rban-'''R'''egional '''E'''nvironment '''S'''imulation (FUTURES)[1] which is a model for multilevel simulations of emerging urban-rural landscape structure. FUTURES produces regional projections of landscape patterns using coupled submodels that integrate nonstationary drivers of land change: per capita demand (DEMAND submodel), site suitability (POTENTIAL submodel), and the spatial structure of conversion events (PGA submodel).

[1] Meentemeyer, R. K., Tang, W., Dorning, M. A., Vogler, J. B., Cunniffe, N. J., & Shoemaker, D. A. (2013). [http://www.tandfonline.com/doi/abs/10.1080/00045608.2012.707591 FUTURES: multilevel simulations of emerging urban-rural landscape structure using a stochastic patch-growing algorithm.] Annals of the Association of American Geographers, 103(4), 785-807

== Software ==
There are a number of software requirements to run FUTURES that will need to be download and installed. Required software includes:
* GRASS GIS 7
* addons
** {{AddonCmd|r.futures.pga}}
** {{AddonCmd|r.futures.potential}}
** {{AddonCmd|r.futures.potsurface}}
** {{AddonCmd|r.futures.demand}}
** {{AddonCmd|r.futures.devpressure}}
** {{AddonCmd|r.sample.category}}
* R (≥ 3.0.2) - needed for {{AddonCmd|r.futures.potential}} with packages:
**MuMIn, lme4, optparse, rgrass7
* SciPy - useful for {{AddonCmd|r.futures.demand}}

=== Installation ===
We use the R statistical software for our calculation of site suitability (i.e. development potential) in FUTURES. R is a free software environment for statistical computing and graphics. If you don't have R, or you have older an version, please download and install the software from [http://archive.linux.duke.edu/cran/ install R] and be sure to additionally add these required packages:
<pre>
install.packages(c("MuMIn", "lme4", "optparse", "rgrass7"))
</pre>

==== MS Windows ====
We will be using GRASS GIS 7.0.3 that can be found here in the [https://trac.osgeo.org/osgeo4w/ OSGeo4W] package manager.
Please install the latest stable GRASS GIS 7 version and the SciPy Python package using the ''Advanced install'' option.
A guide with step by step screen shot instructions is available [https://docs.google.com/presentation/d/1yEGpriBne7RvjB35HI6GecNwO1P1y2nRGqDThqoNnCE/edit?usp=sharing here].

In order for GRASS to be able to find R executables, GRASS must be on the PATH variable. Follow this [solution] to make R accessible from GRASS permanently.
A simple but temporary solution is to open GRASS GIS and paste this in the black terminal:
<pre>
set PATH=%PATH%;C:\Program Files\R\R-3.0.2\bin
</pre>
This has to be repeated after restarting GRASS session.

==== Ubuntu Linux ====
Install GRASS GIS from packages:
<pre>
sudo add-apt-repository ppa:ubuntugis/ubuntugis-unstable
sudo apt-get update
sudo apt-get install grass
</pre>

== Workshop data ==
The data that we will be using for the workshop can be download here: [http://fatra.cnr.ncsu.edu/futures/futures_ncspm_Asheville.zip sample dataset]. Please place these layers in your local GRASS directory:
* digital elevation model ([http://nationalmap.gov/elevation.html NED])
* [http://www.mrlc.gov/ NLCD] 2001, 2011
* NLCD 1992/2001 Retrofit Land Cover Change Product
* transportation network ([http://www.census.gov/geo/maps-data/data/tiger-line.html TIGER])
* county boundaries ([http://www.census.gov/geo/maps-data/data/tiger-line.html TIGER])
* protected areas ([http://www.conservationgateway.org/ConservationByGeography/NorthAmerica/UnitedStates/edc/reportsdata/terrestrial/secured/Pages/default.aspx Secured Lands])
* cities as points (USGS)

In addition, download [http://fatra.cnr.ncsu.edu/futures/futures_Asheville_files.zip population information as text files]:
* county population past estimates and future projections ([https://www.osbm.nc.gov/demog/county-projections NC OSBM]) per county (nonspatial)

= GRASS GIS introduction =
There are many advantages to using the open source GRASS GIS platform, but for many that are more familiar with ARCGis and QGis, the setup and implementation of spatial tools in GRASS can be confusing. Here we provide an overview of the GRASS GIS project: [https://grass.osgeo.org grass.osgeo.org] that might be helpful to review if you are a first time users. For this exercise it's not necessary to have a full understanding of how to use GRASS. However, you will need to know how to place your data in the correct GRASS database directory, as well as some basic GRASS functionality. Step by step instructions are provided below
== Setting up GRASS for the tutorial ==
GRASS uses unique database terminology and structure ([https://grass.osgeo.org/grass71/manuals/grass_database.html GRASS database]) that are important to understand for the set up of this tutorial, as you will need to place the required data (e.g. Mapset) in a specific GRASS database Location. In the following we review important terminology and give step by step direction on how to download and place you data in the correct location.

=== Important GRASS directory terminology ===
* A '''GRASS database''' consist of directory with specific Locations (projects) where data layer are stored
* '''Location''' hold all Mapsets in a specific directoy that have the same spatial projection (spatial reference system)
* '''Mapset''' are a collection of maps with the same spatial projection

=== Creating a GRASS database for the tutorial ===
You need to create a GRASS database with the Mapset that we will use for the tutorial before we can run the FUTURES model. Please Download the [http://fatra.cnr.ncsu.edu/futures/futures_ncspm_Asheville.zip workshop location], noting where the files are located on your local directory. Now, create (unless you already have it) a directory named <tt>grassdata</tt> (GRASS database) in your home folder (or Documents), unzip the downloaded data into this directory. You should now have a Location <tt>futures_ncspm</tt> in <tt>grassdata</tt>.

<center><gallery perrow=1 widths=500 heights=250>Image:GRASS FUTURES startup.png|GRASS GIS 7.0.3 startup dialog with downloaded Location and Mapsets for FUTURES workshop</gallery></center>

=== Launching and exploring data in GRASS ===
Now that we have the data in the correct GRASS database, we can launch the Graphical User Interface (GUI). The GUI interface allows you to display raster, vector data as well as navigate through zooming in and out. Advanced exploration and visualization, like many popular GIS software, is also possible in GRASS (e.g. queries, adding legend). The print screens below depicts how you can add different map layers (left) and display the metadata of your data layers.

<center><gallery perrow=2 widths=500 heights=250>Image:GRASS FUTURES wxGUI display.png|Layer Manager and Map Display overview. Annotations show how to add raster layer, query, add legend.
Image:wxGUI_metadata_rinfo.png|Show raster map metadata by right click on layer</gallery></center>

== GRASS functionality ==
One of the advantage of GRASS is the diversity and number of module addons that let you analyze all manner of spatial and temporal. Because it is open source modules are added daily increasing functionality and methods for analysis of your data. GRASS GIS has over [https://grass.osgeo.org/grass70/manuals/full_index.html 500 different modules] in the core distribution and over [https://grass.osgeo.org/grass70/manuals/addons/ 230 addon modules] that can be used to prepare and analyze data layers.
<center>
{| class="wikitable"
|-
! Prefix !! Function !! Example
|-
| r.* || raster processing || ''{{cmd|r.mapcalc}}'': map algebra
|-
| v.* || vector processing || ''{{cmd|v.clean}}'': topological cleaning
|-
| i.* || imagery processing || ''{{cmd|i.segment}}'': object recognition
|-
| db.* || database management || ''{{cmd|db.select}}'': select values from table
|-
| r3.* || 3D raster processing || ''{{cmd|r3.stats}}'': 3D raster statistics
|-
| t.* || temporal data processing || ''{{cmd|t.rast.aggregate}}'': temporal aggregation
|-
| g.* || general data management || ''{{cmd|g.rename}}'': renames map
|-
| d.* || display ||''{{cmd|d.rast}}'': display raster map
|}</center>

=== Command line vs. GUI interface===
GRASS modules can be executed either through a GUI or command line interface. The GUI offers a user-friendly approach to executing modules where the user can navigate to data layers that they would like to analyze and modify processing options with simple check boxes. The GUI also offer a easily accessible manual on how to execute a model. The command line interface allows users to execute a module using command prompts specific to that module. This is handy when you are running similar analyses with minor modification or are familiar with the module commands for quick efficient processing. In this workshop we provide module prompts that can be copy and pasted into the command line for our workflow, but you can use both GUI and command line depending on personal preference. Look how {{cmd|wxGUI.modules|version=71|desc=GUI and command line interface}} represent the same tool. ''Task:'' compute aspect (orientation) from provided digital elevation model using module {{cmd|r.slope.aspect}} using both module dialog and command line.
* How to find modules? Modules are organized by their functionality in wxGUI menu, or we can search for them in Search modules tab. If we already know which module to use, we can just type it in the wxGUI command console. <center><gallery perrow=3 widths=380 heights=190>Image:wxGUI_menu_rinfo.png|Modules can be found in wxGUI menu
Image:wxGUI_module_search.png|You can search modules by name, description or keywords in ''Search modules'' tab
Image:wxGUI_console_completion.png|By typing prefix r. we make a list of modules starting with that prefix to show up.</gallery></center>

=== Computational region===

{{cmd|g.region|desc=Computational region}} - is an important raster concept in GRASS that needs some explanation. In GRASS a computational region can be set, subsetting larger extent data for quicker testing of analysis or analysis of specific regions based on adminstrative units. We provide a few points to keep in mind when using the computational region function:
* defined by region extent and raster resolution
* applies to all raster operations
* persists between GRASS session, can be different for different mapsets
* advantages: keeps your results consistent, avoid clipping, for computationally demanding tasks set region to smaller extent, check your result is good and then set the computational region to the entire study area and rerun analysis
* run <code>g.region -p</code> or in menu ''Settings'' - ''Region'' - ''Display region'' to see current region settings
[[File:WxGUI set region.png|700px|thumb|center|Simple ways to set computational region from GUI. On the left, set region to match raster map. On the right, select the highlighted option and then set region by drawing rectangle.]]

* GRASS 3D view

= Modeling with FUTURES =
== Initial steps and data preparation ==
First we will set the computational region of our analyses to an extent covering our study area that aligns with our base landuse rasters. ''Like explained in the instructions above, you simply need copy and paste these commands into the command prompt of GRASS''.
<source lang="bash">g.region raster=landuse_2011 -p</source>

The FUTURES model uses the locations of development and new development to predict when and where new urban growth will occur. This requires longitudinal data on urban land use. We will derive urbanized areas from NLCD dataset for year 1992, 2001 and 2011
by extracting categories category 21 - 24 into a new binary map where developed is 1,
undeveloped 0 and NULL (no data) is area unsuitable for development (water, wetlands, protected areas).
First we will convert protected areas from vector to raster. We set
NULLs to zeros (for simpler raster algebra expression in the next step) using {{cmd|r.null}}:

<source lang="bash">
v.to.rast input=protected_areas output=protected_areas use=val
r.null map=protected_areas null=0
</source>

And then create rasters of developed/undeveloped areas using raster algebra:

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.mapcalc "urban_1992 = if(landuse_1992 >= 21 && landuse_1992 <= 24, 1, if(landuse_1992 == 11 || landuse_1992 >= 90 || protected_areas, null(), 0))"
r.mapcalc "urban_2001 = if(landuse_2001 >= 21 && landuse_2001 <= 24, 1, if(landuse_2001 == 11 || landuse_2001 >= 90 || protected_areas, null(), 0))"
r.mapcalc "urban_2011 = if(landuse_2011 >= 21 && landuse_2011 <= 24, 1, if(landuse_2011 == 11 || landuse_2011 >= 90 || protected_areas, null(), 0))"
</source>

We will convert vector counties to raster with the values of the FIPS attribute which links to population file:

<source lang="bash">
v.to.rast input=counties type=area use=attr attribute_column=FIPS output=counties
</source>

Before further steps, we will set our working directory so that the input population files and text files
we are going to create are saved in one directory and easily accessible.
You can do that from menu ''Settings'' → ''GRASS working environment'' → ''Change working directory''.
Select (or create) a directory and move there the downloaded files <tt>population_projection.csv</tt> and <tt>population_trend.csv</tt>.

== Potential submodel ==
Module {{AddonCmd|r.futures.potential}} implements POTENTIAL submodel as a part of FUTURES land change model. POTENTIAL is implemented using a set of coefficients that relate a selection of site suitability factors to the probability of a place becoming developed. This is implemented using the parameter table in combination with maps of those site suitability factors (mapped predictors). The coefficients are obtained by conducting multilevel logistic regression in R with package lme4 where the coefficients may vary by county. The best model is selected automatically using dredge function from package [https://cran.r-project.org/web/packages/MuMIn/index.html MuMIn].

First, we will derive couple of predictors.
=== Predictors ===
==== Slope ====
We will derive slope in degrees from digital elevation model using {{cmd|r.slope.aspect}} module:
<source lang="bash">r.slope.aspect elevation=elevation_30m slope=slope</source>

==== Distance from lakes/rivers ====
First we will extract [http://www.mrlc.gov/nlcd11_leg.php category ''Open Water''] from 2011 NLCD dataset:
<source lang="bash">
r.mapcalc "water = if(landuse_2011 == 11, 1, null())"
</source>

Then we compute the distance to water with module {{cmd|r.grow.distance}} and set color table to shades of blue:
<source lang="bash">
r.grow.distance input=water distance=dist_to_water
r.colors -n map=dist_to_water color=blues
</source>

==== Distance from protected areas ====
We will use raster protected of protected areas we already created, but we will set NULL values to zero.
We compute the distance to protected areas with module {{cmd|r.grow.distance}} and set color table from green to red:
<source lang="bash">
r.null map=protected_areas setnull=0
r.grow.distance input=protected_areas distance=dist_to_protected
r.colors map=dist_to_protected color=gyr
</source>

==== Forests ====
We will smooth the transition between forest and other land use, see NLCD [http://www.mrlc.gov/nlcd11_leg.php category ''Open Water'']:
<source lang="bash">
r.mapcalc "forest = if(landuse_2011 >= 41 && landuse_2011 <= 43, 1, 0)"
r.neighbors -c input=forest output=forest_smooth size=15 method=average
r.colors map=forest_smooth color=ndvi
</source>

==== Travel time to cities ====
Here we will compute travel time to cities (with population > 5000)
as cumulative cost distance where cost is defined as travel time on roads.
First we specify the speed on different types of roads.
We copy the roads raster into our mapset so that we can change it
by adding a new attribute field <tt>speed</tt>. Then we assign speed values (km/h) based on the type of road:

<source lang="bash">
g.copy vector=roads,myroads
v.db.addcolumn map=myroads columns="speed double precision"
v.db.update map=myroads column=speed value=50 where="MTFCC = 'S1400'"
v.db.update map=myroads column=speed value=100 where="MTFCC IN ('S1100', 'S1200')"
</source>

Now we rasterize the selected road types using the speed values from the attribute table as raster values.

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
v.to.rast input=myroads type=line where="MTFCC IN ('S1100', 'S1200', 'S1400')" output=roads_speed use=attr attribute_column=speed
</source>

We set the rest of the area to low speed and recompute the speed as time to travel through a 30m cell in minutes:

<source lang="bash">
r.null map=roads_speed null=5
r.mapcalc "roads_travel_time = 1.8 / roads_speed"
</source>

Finally we compute the travel time to larger cities using {{cmd|r.cost}}:

<source lang="bash">
r.cost input=roads_travel_time output=travel_time_cities start_points=cities
r.colors map=travel_time_cities color=byr
</source>

==== Road density ====
We will rasterize roads and use moving window analysis ({{cmd|r.neighbors}}) to compute road density:

<source lang="bash">
v.to.rast input=roads output=roads use=val type=line
r.null map=roads null=0
r.neighbors -c input=roads output=road_dens size=25 method=average
</source>

==== Distance to interchanges ====

We will consider TIGER roads of type <tt>Ramp</tt> as interchanges, rasterize them and compute euclidean distance to them:

<source lang="bash">
v.to.rast input=roads type=line where="MTFCC = 'S1630'" output=interchanges use=val
r.grow.distance -m input=interchanges distance=dist_interchanges
</source>

=== Development pressure ===

We compute development pressure with {{AddonCmd|r.futures.devpressure}}. Development pressure is a predictor based on number of neighboring developed cells within search distance, weighted by distance. The development pressure variable plays a special role in the model, allowing for a feedback between predicted change and change in subsequent steps.

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.devpressure -n input=urban_2011 output=devpressure_2 method=gravity size=7 gamma=2 scaling_factor=10
r.futures.devpressure -n input=urban_2011 output=devpressure_1 method=gravity size=10 gamma=1 scaling_factor=1
r.futures.devpressure -n input=urban_2011 output=devpressure_0_5 method=gravity size=30 gamma=0.5 scaling_factor=0.1
</source>

When gamma increases, development influence decreases more rapidly with distance.
Size is half the size of the moving window. When gamma is low, local development influences more distant places.
We will derive 3 layers with different gamma and size parameters for the potential statistical model.

=== Rescaling variables ===

First we will look at the ranges of our predictor variables by running a short Python code snippet in Python shell:

<source lang="python" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
for name in ['slope', 'dist_to_water', 'dist_to_protected', 'forest_smooth', 'travel_time_cities', 'road_dens', 'dist_interchanges', 'devpressure_0_5', 'devpressure_1']:
minmax = grass.raster_info(name)
print name, minmax['min'], minmax['max']
</source>

We will rescale some of our input variables:

<source lang="bash">
r.mapcalc "dist_to_water_km = dist_to_water / 1000"
r.mapcalc "dist_to_protected_km = dist_to_protected / 1000"
r.mapcalc "dist_interchanges_km = dist_interchanges / 1000"
r.mapcalc "road_dens_perc = road_dens * 100"
r.mapcalc "forest_smooth_perc = forest_smooth * 100"
</source>

=== Sampling ===
To sample only in the analyzed counties, we will clip development layer:

<source lang="bash">
r.mapcalc "urban_change_01_11 = if(urban_2011 == 1, if(urban_2001 == 0, 1, null()), 0)"
r.mapcalc "urban_change_clip = if(counties, urban_change_01_11)"
</source>

To estimate the number of sampling points, we can use {{cmd|r.report}} to report number of developed/undeveloped cells and their ratio.

<source lang="bash">
r.report map=urban_change_clip units=h,c,p
</source>

We will sample the predictors and the response variable with 5000 random points in undeveloped areas and 1000 points in developed area:

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.sample.category input=urban_change_clip output=sampling sampled=counties,devpressure_0_5,devpressure_1,devpressure_2,slope,road_dens_perc,forest_smooth_perc,dist_to_water_km,dist_to_protected_km,dist_interchanges_km,travel_time_cities npoints=5000,1000
</source>

The attribute table can be exported as CSV file (not necessary step):

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
v.db.select map=sampling columns=urban_change_clip,counties,devpressure_0_5,devpressure_1,slope,road_dens_perc,forest_smooth_perc,dist_to_water_km,dist_to_protected_km,dist_interchanges_km,travel_time_cities separator=comma file=samples.csv
</source>

=== Development potential ===
Now we find best model for predicting urbanization using {{AddonCmd|r.futures.potential}} which wraps an R script.

We can run R [http://www.inside-r.org/packages/cran/MuMIn/docs/dredge dredge] function to find "best" model. We can specify minimum and maximum number of predictors the final model should use.
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.potential -d input=sampling output=potential.csv columns=devpressure_1,slope,road_dens_perc,forest_smooth_perc,dist_to_water_km,dist_to_protected_km,dist_interchanges_km,travel_time_cities developed_column=urban_change_clip subregions_column=counties min_variables=4
</source>

Also, we can play with different combinations of predictors, for example:

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.potential input=sampling output=potential.csv columns=devpressure_2,road_dens_perc,slope,dist_interchanges_km,dist_to_water_km developed_column=urban_change_clip subregions_column=counties --o
r.futures.potential input=sampling output=potential.csv columns=devpressure_1,road_dens_perc,slope,dist_interchanges_km,dist_to_water_km developed_column=urban_change_clip subregions_column=counties --o
...
</source>

You can then open the output file <tt>potential.csv</tt>, which is a CSV file with tabs as separators.

For this tutorial, the final potential is created with:
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.potential input=sampling output=potential.csv columns=devpressure_2,road_dens_perc,slope,dist_interchanges_km,dist_to_water_km developed_column=urban_change_clip subregions_column=counties --o
</source>

We can now visualize the suitability surface using module {{AddonCmd|r.futures.potsurface}}. It creates initial development potential (suitability) raster from predictors and model coefficients and serves only for evaluating development potential model. The values of the resulting raster range from 0 to 1.

<source lang="bash">
r.futures.potsurface input=potential.csv subregions=counties output=suitability
r.colors map=suitability color=byr
</source>

== Demand submodel ==
First we will mask out roads so that they don't influence into per capita land demand relation.
<source lang="bash">
v.to.rast input=roads type=line output=roads_mask use=val
r.mask roads_mask -i
</source>

We will use {{AddonCmd|r.futures.demand}} which derives the population vs. development relation. The relation can be linear/logarithmic/logarithmic2/exponential/exponential approach.
Look for examples of the different relations in the manual.

* linear: y = A + Bx
* logarithmic: y = A + Bln(x)
* logarithmic2: y = A + B * ln(x - C)        (requires SciPy)
* exponential: y = Ae^(BX)
* exp_approach: y = (1 - e^(-A(x - B))) + C        (requires SciPy)

The format of the input population CSV files is described in the manual. It is important to have synchronized categories of subregions and the column headers of the CSV files (in our case FIPS number). How to simply generate the list of years (for which demand is computed) is described in {{AddonCmd|r.futures.demand}} manual, for example run this in Python console:

<source lang="python">
','.join([str(i) for i in range(2011, 2036)])
</source>

Then we can create the DEMAND file:
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.demand development=urban_1992,urban_2001,urban_2011 subregions=counties observed_population=population_trend.csv projected_population=population_projection.csv simulation_times=2011,2012,2013,2014,2015,2016,2017,2018,2019,2020,2021,2022,2023,2024,2025,2026,2027,2028,2029,2030,2031,2032,2033,2034,2035 plot=plot_demand.pdf demand=demand.csv separator=comma
</source>

In your current working directory, you should find files <tt>plot_demand.png</tt> and <tt>demand.csv</tt>.

If you have SciPy installed, you can experiment with other methods for fitting the functions:
<source lang="bash">
r.futures.demand ... method=logarithmic2
r.futures.demand ... method=exp_approach
</source>
If necessary, you can create a set of demand files produced by fitting each method separately and
then pick for each county the method which seems best and manually create a new demand file.

When you are finished, remove the mask as it is not needed for the next steps.
<source lang="bash">
r.mask -r
</source>

== Patch calibration ==
Patch calibration can be a very time consuming computation.
Therefore we select only one county (Buncombe):

<source lang="bash">
v.to.rast input=counties type=area where="FIPS == 37021" use=attr attribute_column=FIPS output=calib_county
g.region raster=calib_county zoom=calib_county
</source>
to derive patches of new development by comparing historical and latest development.
We can keep only patches with minimum size 2 cells (1800 = 2 x 30 x 30 m).

<source lang="bash">
r.futures.calib development_start=urban_1992 development_end=urban_2011 subregions=counties patch_sizes=patches.txt patch_threshold=1800 -l
</source>
We obtained a file <tt>patches.txt</tt> (used later in the PGA) - a patch size distribution file - containing sizes of all found patches.

We can look at the distribution of the patch sizes:

<source lang="python">
from matplotlib import pyplot as plt
with open('patches.txt') as f:
patches = [int(patch) for patch in f.readlines()]
plt.hist(patches, 2000)
plt.xlim(0,50)
plt.show()
</source>

At this point, we start the calibration to get best parameters of patch shape
(for this tutorial, this step can be skipped and the suggested parameters are used).

<source lang="bash"
style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.calib development_start=urban_1992 development_end=urban_2011 subregions=calib_county patch_sizes=patches.txt calibration_results=calib.csv patch_threshold=1800 repeat=5 compactness_mean=0.1,0.3,0.5,0.7,0.9 compactness_range=0.05 discount_factor=0.1,0.3,0.5,0.7,0.9 predictors=road_dens_perc,forest_smooth_perc,dist_to_protected_km demand=demand.csv devpot_params=potential.csv num_neighbors=4 seed_search=2 development_pressure=devpressure_0_5 development_pressure_approach=gravity n_dev_neighbourhood=30 gamma=0.5 scaling_factor=0.1
</source>

== FUTURES simulation ==
We will switch back to our previous region:
<source lang="bash">
g.region raster=landuse_2011 -p
</source>

Now we have all the inputs necessary for running {{AddonCmd|r.futures.pga}}:

The entire command is here:
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.pga subregions=counties developed=urban_2011 predictors=slope,forest_smooth_perc,dist_interchanges_km,travel_time_cities devpot_params=potential.csv development_pressure=devpressure_1 n_dev_neighbourhood=10 development_pressure_approach=gravity gamma=1 scaling_factor=1 demand=demand.csv discount_factor=0.3 compactness_mean=0.2 compactness_range=0.1 patch_sizes=patches.txt num_neighbors=4 seed_search=2 random_seed=1 output=final output_series=final
</source>

=== Quick description ===
The command parameters and their values:
* raster map of counties with their categories
<code>
... subregions=counties ...
</code>

* raster of developed (1), undeveloped (0) and NULLs for undevelopable areas
<code>
... developed=urban_2011 ...
</code>

* predictors selected with {{AddonCmd|r.futures.potential}} and their coefficients in a <tt>potential.csv</tt> file. The order of predictors must match the order in the file and the categories of the counties must match raster <tt>counties</tt>.
<code>
... predictors=slope,forest_smooth_perc,dist_interchanges_km,travel_time_cities devpot_params=potential.csv ...
</code>

* initial development pressure computed by {{AddonCmd|r.futures.devpressure}}, it's important to set here the same parameters
<code>
... development_pressure=devpressure_1 n_dev_neighbourhood=10 development_pressure_approach=gravity gamma=1 scaling_factor=1 ...
</code>

* per capita land demand computed by {{AddonCmd|r.futures.demand}}, the categories of the counties must match raster <tt>counties</tt>.
<code>
... demand=demand.csv ...
</code>

* patch parameters from the calibration step
<code>
... discount_factor=0.3 compactness_mean=0.4 compactness_range=0.08 patch_sizes=patches.txt ...
</code>

* recommended parameters for patch growing algorithm
<code>
... num_neighbors=4 seed_search=2 ...
</code>

* set random seed for repeatable results or set flag <tt>-s</tt> to generate seed automatically
<code>
... random_seed=1 ...
</code>

* specify final output map and optionally basename for intermediate raster maps
<code>
output=final output_series=final
</code>

== Scenarios ==
Scenarios involving policies that encourage infill versus sprawl can be explored using the <tt>incentive_power</tt> parameter of {{AddonCmd|r.futures.pga}},
which uses a power function to transform the evenness of the probability gradient in POTENTIAL. You can change the power to a number between 0.25 and 4 to test urban sprawl/infill scenarios.
Higher power leads to infill behavior, lower power to urban sprawl.

== Postprocessing ==

Follow a [[Creating_animation_from_FUTURES_output_in_GRASS_GIS| tutorial how to make an animation from the results]].

= GRASS GIS Python API =

[[Category: Tutorial]]
[[Category: FUTURES]]
[[Category: Urban]]

Workshop on urban growth modeling with FUTURES

2016-03-22T19:49:43Z

⚠️Dbvanber: /* Initial steps and data preparation */

{{ToModify}}
= Workshop introduction =
r.futures.* is an implementation of the '''FUT'''ure '''U'''rban-'''R'''egional '''E'''nvironment '''S'''imulation (FUTURES)[1] which is a model for multilevel simulations of emerging urban-rural landscape structure. FUTURES produces regional projections of landscape patterns using coupled submodels that integrate nonstationary drivers of land change: per capita demand (DEMAND submodel), site suitability (POTENTIAL submodel), and the spatial structure of conversion events (PGA submodel).

[1] Meentemeyer, R. K., Tang, W., Dorning, M. A., Vogler, J. B., Cunniffe, N. J., & Shoemaker, D. A. (2013). [http://www.tandfonline.com/doi/abs/10.1080/00045608.2012.707591 FUTURES: multilevel simulations of emerging urban-rural landscape structure using a stochastic patch-growing algorithm.] Annals of the Association of American Geographers, 103(4), 785-807

== Software ==
There are a number of software requirements to run FUTURES that will need to be download and installed. Required software includes:
* GRASS GIS 7
* addons
** {{AddonCmd|r.futures.pga}}
** {{AddonCmd|r.futures.potential}}
** {{AddonCmd|r.futures.potsurface}}
** {{AddonCmd|r.futures.demand}}
** {{AddonCmd|r.futures.devpressure}}
** {{AddonCmd|r.sample.category}}
* R (≥ 3.0.2) - needed for {{AddonCmd|r.futures.potential}} with packages:
**MuMIn, lme4, optparse, rgrass7
* SciPy - useful for {{AddonCmd|r.futures.demand}}

=== Installation ===
We use the R statistical software for our calculation of site suitability (i.e. development potential) in FUTURES. R is a free software environment for statistical computing and graphics. If you don't have R, or you have older an version, please download and install the software from [http://archive.linux.duke.edu/cran/ install R] and be sure to additionally add these required packages:
<pre>
install.packages(c("MuMIn", "lme4", "optparse", "rgrass7"))
</pre>

==== MS Windows ====
We will be using GRASS GIS 7.0.3 that can be found here in the [https://trac.osgeo.org/osgeo4w/ OSGeo4W] package manager.
Please install the latest stable GRASS GIS 7 version and the SciPy Python package using the ''Advanced install'' option.
A guide with step by step screen shot instructions is available [https://docs.google.com/presentation/d/1yEGpriBne7RvjB35HI6GecNwO1P1y2nRGqDThqoNnCE/edit?usp=sharing here].

In order for GRASS to be able to find R executables, GRASS must be on the PATH variable. Follow this [solution] to make R accessible from GRASS permanently.
A simple but temporary solution is to open GRASS GIS and paste this in the black terminal:
<pre>
set PATH=%PATH%;C:\Program Files\R\R-3.0.2\bin
</pre>
This has to be repeated after restarting GRASS session.

==== Ubuntu Linux ====
Install GRASS GIS from packages:
<pre>
sudo add-apt-repository ppa:ubuntugis/ubuntugis-unstable
sudo apt-get update
sudo apt-get install grass
</pre>

== Workshop data ==
The data that we will be using for the workshop can be download here: [http://fatra.cnr.ncsu.edu/futures/futures_ncspm_Asheville.zip sample dataset]. Please place these layers in your local GRASS directory:
* digital elevation model ([http://nationalmap.gov/elevation.html NED])
* [http://www.mrlc.gov/ NLCD] 2001, 2011
* NLCD 1992/2001 Retrofit Land Cover Change Product
* transportation network ([http://www.census.gov/geo/maps-data/data/tiger-line.html TIGER])
* county boundaries ([http://www.census.gov/geo/maps-data/data/tiger-line.html TIGER])
* protected areas ([http://www.conservationgateway.org/ConservationByGeography/NorthAmerica/UnitedStates/edc/reportsdata/terrestrial/secured/Pages/default.aspx Secured Lands])
* cities as points (USGS)

In addition, download [http://fatra.cnr.ncsu.edu/futures/futures_Asheville_files.zip population information as text files]:
* county population past estimates and future projections ([https://www.osbm.nc.gov/demog/county-projections NC OSBM]) per county (nonspatial)

= GRASS GIS introduction =
There are many advantages to using the open source GRASS GIS platform, but for many that are more familiar with ARCGis and QGis, the setup and implementation of spatial tools in GRASS can be confusing. Here we provide an overview of the GRASS GIS project: [https://grass.osgeo.org grass.osgeo.org] that might be helpful to review if you are a first time users. For this exercise it's not necessary to have a full understanding of how to use GRASS. However, you will need to know how to place your data in the correct GRASS database directory, as well as some basic GRASS functionality. Step by step instructions are provided below
== Setting up GRASS for the tutorial ==
GRASS uses unique database terminology and structure ([https://grass.osgeo.org/grass71/manuals/grass_database.html GRASS database]) that are important to understand for the set up of this tutorial, as you will need to place the required data (e.g. Mapset) in a specific GRASS database Location. In the following we review important terminology and give step by step direction on how to download and place you data in the correct location.

=== Important GRASS directory terminology ===
* A '''GRASS database''' consist of directory with specific Locations (projects) where data layer are stored
* '''Location''' hold all Mapsets in a specific directoy that have the same spatial projection (spatial reference system)
* '''Mapset''' are a collection of maps with the same spatial projection

=== Creating a GRASS database for the tutorial ===
You need to create a GRASS database with the Mapset that we will use for the tutorial before we can run the FUTURES model. Please Download the [http://fatra.cnr.ncsu.edu/futures/futures_ncspm_Asheville.zip workshop location], noting where the files are located on your local directory. Now, create (unless you already have it) a directory named <tt>grassdata</tt> (GRASS database) in your home folder (or Documents), unzip the downloaded data into this directory. You should now have a Location <tt>futures_ncspm</tt> in <tt>grassdata</tt>.

<center><gallery perrow=1 widths=500 heights=250>Image:GRASS FUTURES startup.png|GRASS GIS 7.0.3 startup dialog with downloaded Location and Mapsets for FUTURES workshop</gallery></center>

=== Launching and exploring data in GRASS ===
Now that we have the data in the correct GRASS database, we can launch the Graphical User Interface (GUI). The GUI interface allows you to display raster, vector data as well as navigate through zooming in and out. Advanced exploration and visualization, like many popular GIS software, is also possible in GRASS (e.g. queries, adding legend). The print screens below depicts how you can add different map layers (left) and display the metadata of your data layers.

<center><gallery perrow=2 widths=500 heights=250>Image:GRASS FUTURES wxGUI display.png|Layer Manager and Map Display overview. Annotations show how to add raster layer, query, add legend.
Image:wxGUI_metadata_rinfo.png|Show raster map metadata by right click on layer</gallery></center>

== GRASS functionality ==
One of the advantage of GRASS is the diversity and number of module addons that let you analyze all manner of spatial and temporal. Because it is open source modules are added daily increasing functionality and methods for analysis of your data. GRASS GIS has over [https://grass.osgeo.org/grass70/manuals/full_index.html 500 different modules] in the core distribution and over [https://grass.osgeo.org/grass70/manuals/addons/ 230 addon modules] that can be used to prepare and analyze data layers.
<center>
{| class="wikitable"
|-
! Prefix !! Function !! Example
|-
| r.* || raster processing || ''{{cmd|r.mapcalc}}'': map algebra
|-
| v.* || vector processing || ''{{cmd|v.clean}}'': topological cleaning
|-
| i.* || imagery processing || ''{{cmd|i.segment}}'': object recognition
|-
| db.* || database management || ''{{cmd|db.select}}'': select values from table
|-
| r3.* || 3D raster processing || ''{{cmd|r3.stats}}'': 3D raster statistics
|-
| t.* || temporal data processing || ''{{cmd|t.rast.aggregate}}'': temporal aggregation
|-
| g.* || general data management || ''{{cmd|g.rename}}'': renames map
|-
| d.* || display ||''{{cmd|d.rast}}'': display raster map
|}</center>

=== Command line vs. GUI interface===
GRASS modules can be executed either through a GUI or command line interface. The GUI offers a user-friendly approach to executing modules where the user can navigate to data layers that they would like to analyze and modify processing options with simple check boxes. The GUI also offer a easily accessible manual on how to execute a model. The command line interface allows users to execute a module using command prompts specific to that module. This is handy when you are running similar analyses with minor modification or are familiar with the module commands for quick efficient processing. In this workshop we provide module prompts that can be copy and pasted into the command line for our workflow, but you can use both GUI and command line depending on personal preference. Look how {{cmd|wxGUI.modules|version=71|desc=GUI and command line interface}} represent the same tool. ''Task:'' compute aspect (orientation) from provided digital elevation model using module {{cmd|r.slope.aspect}} using both module dialog and command line.
* How to find modules? Modules are organized by their functionality in wxGUI menu, or we can search for them in Search modules tab. If we already know which module to use, we can just type it in the wxGUI command console. <center><gallery perrow=3 widths=380 heights=190>Image:wxGUI_menu_rinfo.png|Modules can be found in wxGUI menu
Image:wxGUI_module_search.png|You can search modules by name, description or keywords in ''Search modules'' tab
Image:wxGUI_console_completion.png|By typing prefix r. we make a list of modules starting with that prefix to show up.</gallery></center>

=== Computational region===

{{cmd|g.region|desc=Computational region}} - is an important raster concept in GRASS that needs some explanation. In GRASS a computational region can be set, subsetting larger extent data for quicker testing of analysis or analysis of specific regions based on adminstrative units. We provide a few points to keep in mind when using the computational region function:
* defined by region extent and raster resolution
* applies to all raster operations
* persists between GRASS session, can be different for different mapsets
* advantages: keeps your results consistent, avoid clipping, for computationally demanding tasks set region to smaller extent, check your result is good and then set the computational region to the entire study area and rerun analysis
* run <code>g.region -p</code> or in menu ''Settings'' - ''Region'' - ''Display region'' to see current region settings
[[File:WxGUI set region.png|700px|thumb|center|Simple ways to set computational region from GUI. On the left, set region to match raster map. On the right, select the highlighted option and then set region by drawing rectangle.]]

* GRASS 3D view

= Modeling with FUTURES =
== Initial steps and data preparation ==
First we will set the computational region of our analyses to an extent covering our study area that aligns with our base landuse rasters. ''Like explained in the instructions above, you simply need copy and paste these commands into the command prompt of GRASS''.
<source lang="bash">g.region raster=landuse_2011 -p</source>

We will derive urbanized areas from NLCD dataset for year 1992, 2001 and 2011
by extracting categories category 21 - 24 into a new binary map where developed is 1,
undeveloped 0 and NULL (no data) is area unsuitable for development (water, wetlands, protected areas).
First we will convert protected areas from vector to raster. We set
NULLs to zeros (for simpler raster algebra expression in the next step) using {{cmd|r.null}}:

<source lang="bash">
v.to.rast input=protected_areas output=protected_areas use=val
r.null map=protected_areas null=0
</source>

And then create rasters of developed/undeveloped areas using raster algebra:

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.mapcalc "urban_1992 = if(landuse_1992 >= 21 && landuse_1992 <= 24, 1, if(landuse_1992 == 11 || landuse_1992 >= 90 || protected_areas, null(), 0))"
r.mapcalc "urban_2001 = if(landuse_2001 >= 21 && landuse_2001 <= 24, 1, if(landuse_2001 == 11 || landuse_2001 >= 90 || protected_areas, null(), 0))"
r.mapcalc "urban_2011 = if(landuse_2011 >= 21 && landuse_2011 <= 24, 1, if(landuse_2011 == 11 || landuse_2011 >= 90 || protected_areas, null(), 0))"
</source>

We will convert vector counties to raster with the values of the FIPS attribute which links to population file:

<source lang="bash">
v.to.rast input=counties type=area use=attr attribute_column=FIPS output=counties
</source>

Before further steps, we will set our working directory so that the input population files and text files
we are going to create are saved in one directory and easily accessible.
You can do that from menu ''Settings'' → ''GRASS working environment'' → ''Change working directory''.
Select (or create) a directory and move there the downloaded files <tt>population_projection.csv</tt> and <tt>population_trend.csv</tt>.

== Potential submodel ==
Module {{AddonCmd|r.futures.potential}} implements POTENTIAL submodel as a part of FUTURES land change model. POTENTIAL is implemented using a set of coefficients that relate a selection of site suitability factors to the probability of a place becoming developed. This is implemented using the parameter table in combination with maps of those site suitability factors (mapped predictors). The coefficients are obtained by conducting multilevel logistic regression in R with package lme4 where the coefficients may vary by county. The best model is selected automatically using dredge function from package [https://cran.r-project.org/web/packages/MuMIn/index.html MuMIn].

First, we will derive couple of predictors.
=== Predictors ===
==== Slope ====
We will derive slope in degrees from digital elevation model using {{cmd|r.slope.aspect}} module:
<source lang="bash">r.slope.aspect elevation=elevation_30m slope=slope</source>

==== Distance from lakes/rivers ====
First we will extract [http://www.mrlc.gov/nlcd11_leg.php category ''Open Water''] from 2011 NLCD dataset:
<source lang="bash">
r.mapcalc "water = if(landuse_2011 == 11, 1, null())"
</source>

Then we compute the distance to water with module {{cmd|r.grow.distance}} and set color table to shades of blue:
<source lang="bash">
r.grow.distance input=water distance=dist_to_water
r.colors -n map=dist_to_water color=blues
</source>

==== Distance from protected areas ====
We will use raster protected of protected areas we already created, but we will set NULL values to zero.
We compute the distance to protected areas with module {{cmd|r.grow.distance}} and set color table from green to red:
<source lang="bash">
r.null map=protected_areas setnull=0
r.grow.distance input=protected_areas distance=dist_to_protected
r.colors map=dist_to_protected color=gyr
</source>

==== Forests ====
We will smooth the transition between forest and other land use, see NLCD [http://www.mrlc.gov/nlcd11_leg.php category ''Open Water'']:
<source lang="bash">
r.mapcalc "forest = if(landuse_2011 >= 41 && landuse_2011 <= 43, 1, 0)"
r.neighbors -c input=forest output=forest_smooth size=15 method=average
r.colors map=forest_smooth color=ndvi
</source>

==== Travel time to cities ====
Here we will compute travel time to cities (with population > 5000)
as cumulative cost distance where cost is defined as travel time on roads.
First we specify the speed on different types of roads.
We copy the roads raster into our mapset so that we can change it
by adding a new attribute field <tt>speed</tt>. Then we assign speed values (km/h) based on the type of road:

<source lang="bash">
g.copy vector=roads,myroads
v.db.addcolumn map=myroads columns="speed double precision"
v.db.update map=myroads column=speed value=50 where="MTFCC = 'S1400'"
v.db.update map=myroads column=speed value=100 where="MTFCC IN ('S1100', 'S1200')"
</source>

Now we rasterize the selected road types using the speed values from the attribute table as raster values.

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
v.to.rast input=myroads type=line where="MTFCC IN ('S1100', 'S1200', 'S1400')" output=roads_speed use=attr attribute_column=speed
</source>

We set the rest of the area to low speed and recompute the speed as time to travel through a 30m cell in minutes:

<source lang="bash">
r.null map=roads_speed null=5
r.mapcalc "roads_travel_time = 1.8 / roads_speed"
</source>

Finally we compute the travel time to larger cities using {{cmd|r.cost}}:

<source lang="bash">
r.cost input=roads_travel_time output=travel_time_cities start_points=cities
r.colors map=travel_time_cities color=byr
</source>

==== Road density ====
We will rasterize roads and use moving window analysis ({{cmd|r.neighbors}}) to compute road density:

<source lang="bash">
v.to.rast input=roads output=roads use=val type=line
r.null map=roads null=0
r.neighbors -c input=roads output=road_dens size=25 method=average
</source>

==== Distance to interchanges ====

We will consider TIGER roads of type <tt>Ramp</tt> as interchanges, rasterize them and compute euclidean distance to them:

<source lang="bash">
v.to.rast input=roads type=line where="MTFCC = 'S1630'" output=interchanges use=val
r.grow.distance -m input=interchanges distance=dist_interchanges
</source>

=== Development pressure ===

We compute development pressure with {{AddonCmd|r.futures.devpressure}}. Development pressure is a predictor based on number of neighboring developed cells within search distance, weighted by distance. The development pressure variable plays a special role in the model, allowing for a feedback between predicted change and change in subsequent steps.

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.devpressure -n input=urban_2011 output=devpressure_2 method=gravity size=7 gamma=2 scaling_factor=10
r.futures.devpressure -n input=urban_2011 output=devpressure_1 method=gravity size=10 gamma=1 scaling_factor=1
r.futures.devpressure -n input=urban_2011 output=devpressure_0_5 method=gravity size=30 gamma=0.5 scaling_factor=0.1
</source>

When gamma increases, development influence decreases more rapidly with distance.
Size is half the size of the moving window. When gamma is low, local development influences more distant places.
We will derive 3 layers with different gamma and size parameters for the potential statistical model.

=== Rescaling variables ===

First we will look at the ranges of our predictor variables by running a short Python code snippet in Python shell:

<source lang="python" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
for name in ['slope', 'dist_to_water', 'dist_to_protected', 'forest_smooth', 'travel_time_cities', 'road_dens', 'dist_interchanges', 'devpressure_0_5', 'devpressure_1']:
minmax = grass.raster_info(name)
print name, minmax['min'], minmax['max']
</source>

We will rescale some of our input variables:

<source lang="bash">
r.mapcalc "dist_to_water_km = dist_to_water / 1000"
r.mapcalc "dist_to_protected_km = dist_to_protected / 1000"
r.mapcalc "dist_interchanges_km = dist_interchanges / 1000"
r.mapcalc "road_dens_perc = road_dens * 100"
r.mapcalc "forest_smooth_perc = forest_smooth * 100"
</source>

=== Sampling ===
To sample only in the analyzed counties, we will clip development layer:

<source lang="bash">
r.mapcalc "urban_change_01_11 = if(urban_2011 == 1, if(urban_2001 == 0, 1, null()), 0)"
r.mapcalc "urban_change_clip = if(counties, urban_change_01_11)"
</source>

To estimate the number of sampling points, we can use {{cmd|r.report}} to report number of developed/undeveloped cells and their ratio.

<source lang="bash">
r.report map=urban_change_clip units=h,c,p
</source>

We will sample the predictors and the response variable with 5000 random points in undeveloped areas and 1000 points in developed area:

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.sample.category input=urban_change_clip output=sampling sampled=counties,devpressure_0_5,devpressure_1,devpressure_2,slope,road_dens_perc,forest_smooth_perc,dist_to_water_km,dist_to_protected_km,dist_interchanges_km,travel_time_cities npoints=5000,1000
</source>

The attribute table can be exported as CSV file (not necessary step):

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
v.db.select map=sampling columns=urban_change_clip,counties,devpressure_0_5,devpressure_1,slope,road_dens_perc,forest_smooth_perc,dist_to_water_km,dist_to_protected_km,dist_interchanges_km,travel_time_cities separator=comma file=samples.csv
</source>

=== Development potential ===
Now we find best model for predicting urbanization using {{AddonCmd|r.futures.potential}} which wraps an R script.

We can run R [http://www.inside-r.org/packages/cran/MuMIn/docs/dredge dredge] function to find "best" model. We can specify minimum and maximum number of predictors the final model should use.
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.potential -d input=sampling output=potential.csv columns=devpressure_1,slope,road_dens_perc,forest_smooth_perc,dist_to_water_km,dist_to_protected_km,dist_interchanges_km,travel_time_cities developed_column=urban_change_clip subregions_column=counties min_variables=4
</source>

Also, we can play with different combinations of predictors, for example:

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.potential input=sampling output=potential.csv columns=devpressure_2,road_dens_perc,slope,dist_interchanges_km,dist_to_water_km developed_column=urban_change_clip subregions_column=counties --o
r.futures.potential input=sampling output=potential.csv columns=devpressure_1,road_dens_perc,slope,dist_interchanges_km,dist_to_water_km developed_column=urban_change_clip subregions_column=counties --o
...
</source>

You can then open the output file <tt>potential.csv</tt>, which is a CSV file with tabs as separators.

For this tutorial, the final potential is created with:
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.potential input=sampling output=potential.csv columns=devpressure_2,road_dens_perc,slope,dist_interchanges_km,dist_to_water_km developed_column=urban_change_clip subregions_column=counties --o
</source>

We can now visualize the suitability surface using module {{AddonCmd|r.futures.potsurface}}. It creates initial development potential (suitability) raster from predictors and model coefficients and serves only for evaluating development potential model. The values of the resulting raster range from 0 to 1.

<source lang="bash">
r.futures.potsurface input=potential.csv subregions=counties output=suitability
r.colors map=suitability color=byr
</source>

== Demand submodel ==
First we will mask out roads so that they don't influence into per capita land demand relation.
<source lang="bash">
v.to.rast input=roads type=line output=roads_mask use=val
r.mask roads_mask -i
</source>

We will use {{AddonCmd|r.futures.demand}} which derives the population vs. development relation. The relation can be linear/logarithmic/logarithmic2/exponential/exponential approach.
Look for examples of the different relations in the manual.

* linear: y = A + Bx
* logarithmic: y = A + Bln(x)
* logarithmic2: y = A + B * ln(x - C)        (requires SciPy)
* exponential: y = Ae^(BX)
* exp_approach: y = (1 - e^(-A(x - B))) + C        (requires SciPy)

The format of the input population CSV files is described in the manual. It is important to have synchronized categories of subregions and the column headers of the CSV files (in our case FIPS number). How to simply generate the list of years (for which demand is computed) is described in {{AddonCmd|r.futures.demand}} manual, for example run this in Python console:

<source lang="python">
','.join([str(i) for i in range(2011, 2036)])
</source>

Then we can create the DEMAND file:
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.demand development=urban_1992,urban_2001,urban_2011 subregions=counties observed_population=population_trend.csv projected_population=population_projection.csv simulation_times=2011,2012,2013,2014,2015,2016,2017,2018,2019,2020,2021,2022,2023,2024,2025,2026,2027,2028,2029,2030,2031,2032,2033,2034,2035 plot=plot_demand.pdf demand=demand.csv separator=comma
</source>

In your current working directory, you should find files <tt>plot_demand.png</tt> and <tt>demand.csv</tt>.

If you have SciPy installed, you can experiment with other methods for fitting the functions:
<source lang="bash">
r.futures.demand ... method=logarithmic2
r.futures.demand ... method=exp_approach
</source>
If necessary, you can create a set of demand files produced by fitting each method separately and
then pick for each county the method which seems best and manually create a new demand file.

When you are finished, remove the mask as it is not needed for the next steps.
<source lang="bash">
r.mask -r
</source>

== Patch calibration ==
Patch calibration can be a very time consuming computation.
Therefore we select only one county (Buncombe):

<source lang="bash">
v.to.rast input=counties type=area where="FIPS == 37021" use=attr attribute_column=FIPS output=calib_county
g.region raster=calib_county zoom=calib_county
</source>
to derive patches of new development by comparing historical and latest development.
We can keep only patches with minimum size 2 cells (1800 = 2 x 30 x 30 m).

<source lang="bash">
r.futures.calib development_start=urban_1992 development_end=urban_2011 subregions=counties patch_sizes=patches.txt patch_threshold=1800 -l
</source>
We obtained a file <tt>patches.txt</tt> (used later in the PGA) - a patch size distribution file - containing sizes of all found patches.

We can look at the distribution of the patch sizes:

<source lang="python">
from matplotlib import pyplot as plt
with open('patches.txt') as f:
patches = [int(patch) for patch in f.readlines()]
plt.hist(patches, 2000)
plt.xlim(0,50)
plt.show()
</source>

At this point, we start the calibration to get best parameters of patch shape
(for this tutorial, this step can be skipped and the suggested parameters are used).

<source lang="bash"
style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.calib development_start=urban_1992 development_end=urban_2011 subregions=calib_county patch_sizes=patches.txt calibration_results=calib.csv patch_threshold=1800 repeat=5 compactness_mean=0.1,0.3,0.5,0.7,0.9 compactness_range=0.05 discount_factor=0.1,0.3,0.5,0.7,0.9 predictors=road_dens_perc,forest_smooth_perc,dist_to_protected_km demand=demand.csv devpot_params=potential.csv num_neighbors=4 seed_search=2 development_pressure=devpressure_0_5 development_pressure_approach=gravity n_dev_neighbourhood=30 gamma=0.5 scaling_factor=0.1
</source>

== FUTURES simulation ==
We will switch back to our previous region:
<source lang="bash">
g.region raster=landuse_2011 -p
</source>

Now we have all the inputs necessary for running {{AddonCmd|r.futures.pga}}:

The entire command is here:
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.pga subregions=counties developed=urban_2011 predictors=slope,forest_smooth_perc,dist_interchanges_km,travel_time_cities devpot_params=potential.csv development_pressure=devpressure_1 n_dev_neighbourhood=10 development_pressure_approach=gravity gamma=1 scaling_factor=1 demand=demand.csv discount_factor=0.3 compactness_mean=0.2 compactness_range=0.1 patch_sizes=patches.txt num_neighbors=4 seed_search=2 random_seed=1 output=final output_series=final
</source>

=== Quick description ===
The command parameters and their values:
* raster map of counties with their categories
<code>
... subregions=counties ...
</code>

* raster of developed (1), undeveloped (0) and NULLs for undevelopable areas
<code>
... developed=urban_2011 ...
</code>

* predictors selected with {{AddonCmd|r.futures.potential}} and their coefficients in a <tt>potential.csv</tt> file. The order of predictors must match the order in the file and the categories of the counties must match raster <tt>counties</tt>.
<code>
... predictors=slope,forest_smooth_perc,dist_interchanges_km,travel_time_cities devpot_params=potential.csv ...
</code>

* initial development pressure computed by {{AddonCmd|r.futures.devpressure}}, it's important to set here the same parameters
<code>
... development_pressure=devpressure_1 n_dev_neighbourhood=10 development_pressure_approach=gravity gamma=1 scaling_factor=1 ...
</code>

* per capita land demand computed by {{AddonCmd|r.futures.demand}}, the categories of the counties must match raster <tt>counties</tt>.
<code>
... demand=demand.csv ...
</code>

* patch parameters from the calibration step
<code>
... discount_factor=0.3 compactness_mean=0.4 compactness_range=0.08 patch_sizes=patches.txt ...
</code>

* recommended parameters for patch growing algorithm
<code>
... num_neighbors=4 seed_search=2 ...
</code>

* set random seed for repeatable results or set flag <tt>-s</tt> to generate seed automatically
<code>
... random_seed=1 ...
</code>

* specify final output map and optionally basename for intermediate raster maps
<code>
output=final output_series=final
</code>

== Scenarios ==
Scenarios involving policies that encourage infill versus sprawl can be explored using the <tt>incentive_power</tt> parameter of {{AddonCmd|r.futures.pga}},
which uses a power function to transform the evenness of the probability gradient in POTENTIAL. You can change the power to a number between 0.25 and 4 to test urban sprawl/infill scenarios.
Higher power leads to infill behavior, lower power to urban sprawl.

== Postprocessing ==

Follow a [[Creating_animation_from_FUTURES_output_in_GRASS_GIS| tutorial how to make an animation from the results]].

= GRASS GIS Python API =

[[Category: Tutorial]]
[[Category: FUTURES]]
[[Category: Urban]]

Workshop on urban growth modeling with FUTURES

2016-03-22T19:37:36Z

⚠️Dbvanber: /* Command line vs. GUI interface */

{{ToModify}}
= Workshop introduction =
r.futures.* is an implementation of the '''FUT'''ure '''U'''rban-'''R'''egional '''E'''nvironment '''S'''imulation (FUTURES)[1] which is a model for multilevel simulations of emerging urban-rural landscape structure. FUTURES produces regional projections of landscape patterns using coupled submodels that integrate nonstationary drivers of land change: per capita demand (DEMAND submodel), site suitability (POTENTIAL submodel), and the spatial structure of conversion events (PGA submodel).

[1] Meentemeyer, R. K., Tang, W., Dorning, M. A., Vogler, J. B., Cunniffe, N. J., & Shoemaker, D. A. (2013). [http://www.tandfonline.com/doi/abs/10.1080/00045608.2012.707591 FUTURES: multilevel simulations of emerging urban-rural landscape structure using a stochastic patch-growing algorithm.] Annals of the Association of American Geographers, 103(4), 785-807

== Software ==
There are a number of software requirements to run FUTURES that will need to be download and installed. Required software includes:
* GRASS GIS 7
* addons
** {{AddonCmd|r.futures.pga}}
** {{AddonCmd|r.futures.potential}}
** {{AddonCmd|r.futures.potsurface}}
** {{AddonCmd|r.futures.demand}}
** {{AddonCmd|r.futures.devpressure}}
** {{AddonCmd|r.sample.category}}
* R (≥ 3.0.2) - needed for {{AddonCmd|r.futures.potential}} with packages:
**MuMIn, lme4, optparse, rgrass7
* SciPy - useful for {{AddonCmd|r.futures.demand}}

=== Installation ===
We use the R statistical software for our calculation of site suitability (i.e. development potential) in FUTURES. R is a free software environment for statistical computing and graphics. If you don't have R, or you have older an version, please download and install the software from [http://archive.linux.duke.edu/cran/ install R] and be sure to additionally add these required packages:
<pre>
install.packages(c("MuMIn", "lme4", "optparse", "rgrass7"))
</pre>

==== MS Windows ====
We will be using GRASS GIS 7.0.3 that can be found here in the [https://trac.osgeo.org/osgeo4w/ OSGeo4W] package manager.
Please install the latest stable GRASS GIS 7 version and the SciPy Python package using the ''Advanced install'' option.
A guide with step by step screen shot instructions is available [https://docs.google.com/presentation/d/1yEGpriBne7RvjB35HI6GecNwO1P1y2nRGqDThqoNnCE/edit?usp=sharing here].

In order for GRASS to be able to find R executables, GRASS must be on the PATH variable. Follow this [solution] to make R accessible from GRASS permanently.
A simple but temporary solution is to open GRASS GIS and paste this in the black terminal:
<pre>
set PATH=%PATH%;C:\Program Files\R\R-3.0.2\bin
</pre>
This has to be repeated after restarting GRASS session.

==== Ubuntu Linux ====
Install GRASS GIS from packages:
<pre>
sudo add-apt-repository ppa:ubuntugis/ubuntugis-unstable
sudo apt-get update
sudo apt-get install grass
</pre>

== Workshop data ==
The data that we will be using for the workshop can be download here: [http://fatra.cnr.ncsu.edu/futures/futures_ncspm_Asheville.zip sample dataset]. Please place these layers in your local GRASS directory:
* digital elevation model ([http://nationalmap.gov/elevation.html NED])
* [http://www.mrlc.gov/ NLCD] 2001, 2011
* NLCD 1992/2001 Retrofit Land Cover Change Product
* transportation network ([http://www.census.gov/geo/maps-data/data/tiger-line.html TIGER])
* county boundaries ([http://www.census.gov/geo/maps-data/data/tiger-line.html TIGER])
* protected areas ([http://www.conservationgateway.org/ConservationByGeography/NorthAmerica/UnitedStates/edc/reportsdata/terrestrial/secured/Pages/default.aspx Secured Lands])
* cities as points (USGS)

In addition, download [http://fatra.cnr.ncsu.edu/futures/futures_Asheville_files.zip population information as text files]:
* county population past estimates and future projections ([https://www.osbm.nc.gov/demog/county-projections NC OSBM]) per county (nonspatial)

= GRASS GIS introduction =
There are many advantages to using the open source GRASS GIS platform, but for many that are more familiar with ARCGis and QGis, the setup and implementation of spatial tools in GRASS can be confusing. Here we provide an overview of the GRASS GIS project: [https://grass.osgeo.org grass.osgeo.org] that might be helpful to review if you are a first time users. For this exercise it's not necessary to have a full understanding of how to use GRASS. However, you will need to know how to place your data in the correct GRASS database directory, as well as some basic GRASS functionality. Step by step instructions are provided below
== Setting up GRASS for the tutorial ==
GRASS uses unique database terminology and structure ([https://grass.osgeo.org/grass71/manuals/grass_database.html GRASS database]) that are important to understand for the set up of this tutorial, as you will need to place the required data (e.g. Mapset) in a specific GRASS database Location. In the following we review important terminology and give step by step direction on how to download and place you data in the correct location.

=== Important GRASS directory terminology ===
* A '''GRASS database''' consist of directory with specific Locations (projects) where data layer are stored
* '''Location''' hold all Mapsets in a specific directoy that have the same spatial projection (spatial reference system)
* '''Mapset''' are a collection of maps with the same spatial projection

=== Creating a GRASS database for the tutorial ===
You need to create a GRASS database with the Mapset that we will use for the tutorial before we can run the FUTURES model. Please Download the [http://fatra.cnr.ncsu.edu/futures/futures_ncspm_Asheville.zip workshop location], noting where the files are located on your local directory. Now, create (unless you already have it) a directory named <tt>grassdata</tt> (GRASS database) in your home folder (or Documents), unzip the downloaded data into this directory. You should now have a Location <tt>futures_ncspm</tt> in <tt>grassdata</tt>.

<center><gallery perrow=1 widths=500 heights=250>Image:GRASS FUTURES startup.png|GRASS GIS 7.0.3 startup dialog with downloaded Location and Mapsets for FUTURES workshop</gallery></center>

=== Launching and exploring data in GRASS ===
Now that we have the data in the correct GRASS database, we can launch the Graphical User Interface (GUI). The GUI interface allows you to display raster, vector data as well as navigate through zooming in and out. Advanced exploration and visualization, like many popular GIS software, is also possible in GRASS (e.g. queries, adding legend). The print screens below depicts how you can add different map layers (left) and display the metadata of your data layers.

<center><gallery perrow=2 widths=500 heights=250>Image:GRASS FUTURES wxGUI display.png|Layer Manager and Map Display overview. Annotations show how to add raster layer, query, add legend.
Image:wxGUI_metadata_rinfo.png|Show raster map metadata by right click on layer</gallery></center>

== GRASS functionality ==
One of the advantage of GRASS is the diversity and number of module addons that let you analyze all manner of spatial and temporal. Because it is open source modules are added daily increasing functionality and methods for analysis of your data. GRASS GIS has over [https://grass.osgeo.org/grass70/manuals/full_index.html 500 different modules] in the core distribution and over [https://grass.osgeo.org/grass70/manuals/addons/ 230 addon modules] that can be used to prepare and analyze data layers.
<center>
{| class="wikitable"
|-
! Prefix !! Function !! Example
|-
| r.* || raster processing || ''{{cmd|r.mapcalc}}'': map algebra
|-
| v.* || vector processing || ''{{cmd|v.clean}}'': topological cleaning
|-
| i.* || imagery processing || ''{{cmd|i.segment}}'': object recognition
|-
| db.* || database management || ''{{cmd|db.select}}'': select values from table
|-
| r3.* || 3D raster processing || ''{{cmd|r3.stats}}'': 3D raster statistics
|-
| t.* || temporal data processing || ''{{cmd|t.rast.aggregate}}'': temporal aggregation
|-
| g.* || general data management || ''{{cmd|g.rename}}'': renames map
|-
| d.* || display ||''{{cmd|d.rast}}'': display raster map
|}</center>

=== Command line vs. GUI interface===
GRASS modules can be executed either through a GUI or command line interface. The GUI offers a user-friendly approach to executing modules where the user can navigate to data layers that they would like to analyze and modify processing options with simple check boxes. The GUI also offer a easily accessible manual on how to execute a model. The command line interface allows users to execute a module using command prompts specific to that module. This is handy when you are running similar analyses with minor modification or are familiar with the module commands for quick efficient processing. In this workshop we provide module prompts that can be copy and pasted into the command line for our workflow, but you can use both GUI and command line depending on personal preference. Look how {{cmd|wxGUI.modules|version=71|desc=GUI and command line interface}} represent the same tool. ''Task:'' compute aspect (orientation) from provided digital elevation model using module {{cmd|r.slope.aspect}} using both module dialog and command line.
* How to find modules? Modules are organized by their functionality in wxGUI menu, or we can search for them in Search modules tab. If we already know which module to use, we can just type it in the wxGUI command console. <center><gallery perrow=3 widths=380 heights=190>Image:wxGUI_menu_rinfo.png|Modules can be found in wxGUI menu
Image:wxGUI_module_search.png|You can search modules by name, description or keywords in ''Search modules'' tab
Image:wxGUI_console_completion.png|By typing prefix r. we make a list of modules starting with that prefix to show up.</gallery></center>

=== Computational region===

{{cmd|g.region|desc=Computational region}} - is an important raster concept in GRASS that needs some explanation. In GRASS a computational region can be set, subsetting larger extent data for quicker testing of analysis or analysis of specific regions based on adminstrative units. We provide a few points to keep in mind when using the computational region function:
* defined by region extent and raster resolution
* applies to all raster operations
* persists between GRASS session, can be different for different mapsets
* advantages: keeps your results consistent, avoid clipping, for computationally demanding tasks set region to smaller extent, check your result is good and then set the computational region to the entire study area and rerun analysis
* run <code>g.region -p</code> or in menu ''Settings'' - ''Region'' - ''Display region'' to see current region settings
[[File:WxGUI set region.png|700px|thumb|center|Simple ways to set computational region from GUI. On the left, set region to match raster map. On the right, select the highlighted option and then set region by drawing rectangle.]]

* GRASS 3D view

= Modeling with FUTURES =
== Initial steps and data preparation ==
First we will set the computational region of our analyses to an extent covering our study area and aligned with our base landuse rasters:
<source lang="bash">g.region raster=landuse_2011 -p</source>

We will derive urbanized areas from NLCD dataset for year 1992, 2001 and 2011
by extracting categories category 21 - 24 into a new binary map where developed is 1,
undeveloped 0 and NULL (no data) is area unsuitable for development (water, wetlands, protected areas).
First we will convert protected areas from vector to raster. We set
NULLs to zeros (for simpler raster algebra expression in the next step) using {{cmd|r.null}}:

<source lang="bash">
v.to.rast input=protected_areas output=protected_areas use=val
r.null map=protected_areas null=0
</source>

And then create rasters of developed/undeveloped areas using raster algebra:

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.mapcalc "urban_1992 = if(landuse_1992 >= 21 && landuse_1992 <= 24, 1, if(landuse_1992 == 11 || landuse_1992 >= 90 || protected_areas, null(), 0))"
r.mapcalc "urban_2001 = if(landuse_2001 >= 21 && landuse_2001 <= 24, 1, if(landuse_2001 == 11 || landuse_2001 >= 90 || protected_areas, null(), 0))"
r.mapcalc "urban_2011 = if(landuse_2011 >= 21 && landuse_2011 <= 24, 1, if(landuse_2011 == 11 || landuse_2011 >= 90 || protected_areas, null(), 0))"
</source>

We will convert vector counties to raster with the values of the FIPS attribute which links to population file:

<source lang="bash">
v.to.rast input=counties type=area use=attr attribute_column=FIPS output=counties
</source>

Before further steps, we will set our working directory so that the input population files and text files
we are going to create are saved in one directory and easily accessible.
You can do that from menu ''Settings'' → ''GRASS working environment'' → ''Change working directory''.
Select (or create) a directory and move there the downloaded files <tt>population_projection.csv</tt> and <tt>population_trend.csv</tt>.

== Potential submodel ==
Module {{AddonCmd|r.futures.potential}} implements POTENTIAL submodel as a part of FUTURES land change model. POTENTIAL is implemented using a set of coefficients that relate a selection of site suitability factors to the probability of a place becoming developed. This is implemented using the parameter table in combination with maps of those site suitability factors (mapped predictors). The coefficients are obtained by conducting multilevel logistic regression in R with package lme4 where the coefficients may vary by county. The best model is selected automatically using dredge function from package [https://cran.r-project.org/web/packages/MuMIn/index.html MuMIn].

First, we will derive couple of predictors.
=== Predictors ===
==== Slope ====
We will derive slope in degrees from digital elevation model using {{cmd|r.slope.aspect}} module:
<source lang="bash">r.slope.aspect elevation=elevation_30m slope=slope</source>

==== Distance from lakes/rivers ====
First we will extract [http://www.mrlc.gov/nlcd11_leg.php category ''Open Water''] from 2011 NLCD dataset:
<source lang="bash">
r.mapcalc "water = if(landuse_2011 == 11, 1, null())"
</source>

Then we compute the distance to water with module {{cmd|r.grow.distance}} and set color table to shades of blue:
<source lang="bash">
r.grow.distance input=water distance=dist_to_water
r.colors -n map=dist_to_water color=blues
</source>

==== Distance from protected areas ====
We will use raster protected of protected areas we already created, but we will set NULL values to zero.
We compute the distance to protected areas with module {{cmd|r.grow.distance}} and set color table from green to red:
<source lang="bash">
r.null map=protected_areas setnull=0
r.grow.distance input=protected_areas distance=dist_to_protected
r.colors map=dist_to_protected color=gyr
</source>

==== Forests ====
We will smooth the transition between forest and other land use, see NLCD [http://www.mrlc.gov/nlcd11_leg.php category ''Open Water'']:
<source lang="bash">
r.mapcalc "forest = if(landuse_2011 >= 41 && landuse_2011 <= 43, 1, 0)"
r.neighbors -c input=forest output=forest_smooth size=15 method=average
r.colors map=forest_smooth color=ndvi
</source>

==== Travel time to cities ====
Here we will compute travel time to cities (with population > 5000)
as cumulative cost distance where cost is defined as travel time on roads.
First we specify the speed on different types of roads.
We copy the roads raster into our mapset so that we can change it
by adding a new attribute field <tt>speed</tt>. Then we assign speed values (km/h) based on the type of road:

<source lang="bash">
g.copy vector=roads,myroads
v.db.addcolumn map=myroads columns="speed double precision"
v.db.update map=myroads column=speed value=50 where="MTFCC = 'S1400'"
v.db.update map=myroads column=speed value=100 where="MTFCC IN ('S1100', 'S1200')"
</source>

Now we rasterize the selected road types using the speed values from the attribute table as raster values.

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
v.to.rast input=myroads type=line where="MTFCC IN ('S1100', 'S1200', 'S1400')" output=roads_speed use=attr attribute_column=speed
</source>

We set the rest of the area to low speed and recompute the speed as time to travel through a 30m cell in minutes:

<source lang="bash">
r.null map=roads_speed null=5
r.mapcalc "roads_travel_time = 1.8 / roads_speed"
</source>

Finally we compute the travel time to larger cities using {{cmd|r.cost}}:

<source lang="bash">
r.cost input=roads_travel_time output=travel_time_cities start_points=cities
r.colors map=travel_time_cities color=byr
</source>

==== Road density ====
We will rasterize roads and use moving window analysis ({{cmd|r.neighbors}}) to compute road density:

<source lang="bash">
v.to.rast input=roads output=roads use=val type=line
r.null map=roads null=0
r.neighbors -c input=roads output=road_dens size=25 method=average
</source>

==== Distance to interchanges ====

We will consider TIGER roads of type <tt>Ramp</tt> as interchanges, rasterize them and compute euclidean distance to them:

<source lang="bash">
v.to.rast input=roads type=line where="MTFCC = 'S1630'" output=interchanges use=val
r.grow.distance -m input=interchanges distance=dist_interchanges
</source>

=== Development pressure ===

We compute development pressure with {{AddonCmd|r.futures.devpressure}}. Development pressure is a predictor based on number of neighboring developed cells within search distance, weighted by distance. The development pressure variable plays a special role in the model, allowing for a feedback between predicted change and change in subsequent steps.

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.devpressure -n input=urban_2011 output=devpressure_2 method=gravity size=7 gamma=2 scaling_factor=10
r.futures.devpressure -n input=urban_2011 output=devpressure_1 method=gravity size=10 gamma=1 scaling_factor=1
r.futures.devpressure -n input=urban_2011 output=devpressure_0_5 method=gravity size=30 gamma=0.5 scaling_factor=0.1
</source>

When gamma increases, development influence decreases more rapidly with distance.
Size is half the size of the moving window. When gamma is low, local development influences more distant places.
We will derive 3 layers with different gamma and size parameters for the potential statistical model.

=== Rescaling variables ===

First we will look at the ranges of our predictor variables by running a short Python code snippet in Python shell:

<source lang="python" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
for name in ['slope', 'dist_to_water', 'dist_to_protected', 'forest_smooth', 'travel_time_cities', 'road_dens', 'dist_interchanges', 'devpressure_0_5', 'devpressure_1']:
minmax = grass.raster_info(name)
print name, minmax['min'], minmax['max']
</source>

We will rescale some of our input variables:

<source lang="bash">
r.mapcalc "dist_to_water_km = dist_to_water / 1000"
r.mapcalc "dist_to_protected_km = dist_to_protected / 1000"
r.mapcalc "dist_interchanges_km = dist_interchanges / 1000"
r.mapcalc "road_dens_perc = road_dens * 100"
r.mapcalc "forest_smooth_perc = forest_smooth * 100"
</source>

=== Sampling ===
To sample only in the analyzed counties, we will clip development layer:

<source lang="bash">
r.mapcalc "urban_change_01_11 = if(urban_2011 == 1, if(urban_2001 == 0, 1, null()), 0)"
r.mapcalc "urban_change_clip = if(counties, urban_change_01_11)"
</source>

To estimate the number of sampling points, we can use {{cmd|r.report}} to report number of developed/undeveloped cells and their ratio.

<source lang="bash">
r.report map=urban_change_clip units=h,c,p
</source>

We will sample the predictors and the response variable with 5000 random points in undeveloped areas and 1000 points in developed area:

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.sample.category input=urban_change_clip output=sampling sampled=counties,devpressure_0_5,devpressure_1,devpressure_2,slope,road_dens_perc,forest_smooth_perc,dist_to_water_km,dist_to_protected_km,dist_interchanges_km,travel_time_cities npoints=5000,1000
</source>

The attribute table can be exported as CSV file (not necessary step):

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
v.db.select map=sampling columns=urban_change_clip,counties,devpressure_0_5,devpressure_1,slope,road_dens_perc,forest_smooth_perc,dist_to_water_km,dist_to_protected_km,dist_interchanges_km,travel_time_cities separator=comma file=samples.csv
</source>

=== Development potential ===
Now we find best model for predicting urbanization using {{AddonCmd|r.futures.potential}} which wraps an R script.

We can run R [http://www.inside-r.org/packages/cran/MuMIn/docs/dredge dredge] function to find "best" model. We can specify minimum and maximum number of predictors the final model should use.
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.potential -d input=sampling output=potential.csv columns=devpressure_1,slope,road_dens_perc,forest_smooth_perc,dist_to_water_km,dist_to_protected_km,dist_interchanges_km,travel_time_cities developed_column=urban_change_clip subregions_column=counties min_variables=4
</source>

Also, we can play with different combinations of predictors, for example:

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.potential input=sampling output=potential.csv columns=devpressure_2,road_dens_perc,slope,dist_interchanges_km,dist_to_water_km developed_column=urban_change_clip subregions_column=counties --o
r.futures.potential input=sampling output=potential.csv columns=devpressure_1,road_dens_perc,slope,dist_interchanges_km,dist_to_water_km developed_column=urban_change_clip subregions_column=counties --o
...
</source>

You can then open the output file <tt>potential.csv</tt>, which is a CSV file with tabs as separators.

For this tutorial, the final potential is created with:
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.potential input=sampling output=potential.csv columns=devpressure_2,road_dens_perc,slope,dist_interchanges_km,dist_to_water_km developed_column=urban_change_clip subregions_column=counties --o
</source>

We can now visualize the suitability surface using module {{AddonCmd|r.futures.potsurface}}. It creates initial development potential (suitability) raster from predictors and model coefficients and serves only for evaluating development potential model. The values of the resulting raster range from 0 to 1.

<source lang="bash">
r.futures.potsurface input=potential.csv subregions=counties output=suitability
r.colors map=suitability color=byr
</source>

== Demand submodel ==
First we will mask out roads so that they don't influence into per capita land demand relation.
<source lang="bash">
v.to.rast input=roads type=line output=roads_mask use=val
r.mask roads_mask -i
</source>

We will use {{AddonCmd|r.futures.demand}} which derives the population vs. development relation. The relation can be linear/logarithmic/logarithmic2/exponential/exponential approach.
Look for examples of the different relations in the manual.

* linear: y = A + Bx
* logarithmic: y = A + Bln(x)
* logarithmic2: y = A + B * ln(x - C)        (requires SciPy)
* exponential: y = Ae^(BX)
* exp_approach: y = (1 - e^(-A(x - B))) + C        (requires SciPy)

The format of the input population CSV files is described in the manual. It is important to have synchronized categories of subregions and the column headers of the CSV files (in our case FIPS number). How to simply generate the list of years (for which demand is computed) is described in {{AddonCmd|r.futures.demand}} manual, for example run this in Python console:

<source lang="python">
','.join([str(i) for i in range(2011, 2036)])
</source>

Then we can create the DEMAND file:
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.demand development=urban_1992,urban_2001,urban_2011 subregions=counties observed_population=population_trend.csv projected_population=population_projection.csv simulation_times=2011,2012,2013,2014,2015,2016,2017,2018,2019,2020,2021,2022,2023,2024,2025,2026,2027,2028,2029,2030,2031,2032,2033,2034,2035 plot=plot_demand.pdf demand=demand.csv separator=comma
</source>

In your current working directory, you should find files <tt>plot_demand.png</tt> and <tt>demand.csv</tt>.

If you have SciPy installed, you can experiment with other methods for fitting the functions:
<source lang="bash">
r.futures.demand ... method=logarithmic2
r.futures.demand ... method=exp_approach
</source>
If necessary, you can create a set of demand files produced by fitting each method separately and
then pick for each county the method which seems best and manually create a new demand file.

When you are finished, remove the mask as it is not needed for the next steps.
<source lang="bash">
r.mask -r
</source>

== Patch calibration ==
Patch calibration can be a very time consuming computation.
Therefore we select only one county (Buncombe):

<source lang="bash">
v.to.rast input=counties type=area where="FIPS == 37021" use=attr attribute_column=FIPS output=calib_county
g.region raster=calib_county zoom=calib_county
</source>
to derive patches of new development by comparing historical and latest development.
We can keep only patches with minimum size 2 cells (1800 = 2 x 30 x 30 m).

<source lang="bash">
r.futures.calib development_start=urban_1992 development_end=urban_2011 subregions=counties patch_sizes=patches.txt patch_threshold=1800 -l
</source>
We obtained a file <tt>patches.txt</tt> (used later in the PGA) - a patch size distribution file - containing sizes of all found patches.

We can look at the distribution of the patch sizes:

<source lang="python">
from matplotlib import pyplot as plt
with open('patches.txt') as f:
patches = [int(patch) for patch in f.readlines()]
plt.hist(patches, 2000)
plt.xlim(0,50)
plt.show()
</source>

At this point, we start the calibration to get best parameters of patch shape
(for this tutorial, this step can be skipped and the suggested parameters are used).

<source lang="bash"
style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.calib development_start=urban_1992 development_end=urban_2011 subregions=calib_county patch_sizes=patches.txt calibration_results=calib.csv patch_threshold=1800 repeat=5 compactness_mean=0.1,0.3,0.5,0.7,0.9 compactness_range=0.05 discount_factor=0.1,0.3,0.5,0.7,0.9 predictors=road_dens_perc,forest_smooth_perc,dist_to_protected_km demand=demand.csv devpot_params=potential.csv num_neighbors=4 seed_search=2 development_pressure=devpressure_0_5 development_pressure_approach=gravity n_dev_neighbourhood=30 gamma=0.5 scaling_factor=0.1
</source>

== FUTURES simulation ==
We will switch back to our previous region:
<source lang="bash">
g.region raster=landuse_2011 -p
</source>

Now we have all the inputs necessary for running {{AddonCmd|r.futures.pga}}:

The entire command is here:
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.pga subregions=counties developed=urban_2011 predictors=slope,forest_smooth_perc,dist_interchanges_km,travel_time_cities devpot_params=potential.csv development_pressure=devpressure_1 n_dev_neighbourhood=10 development_pressure_approach=gravity gamma=1 scaling_factor=1 demand=demand.csv discount_factor=0.3 compactness_mean=0.2 compactness_range=0.1 patch_sizes=patches.txt num_neighbors=4 seed_search=2 random_seed=1 output=final output_series=final
</source>

=== Quick description ===
The command parameters and their values:
* raster map of counties with their categories
<code>
... subregions=counties ...
</code>

* raster of developed (1), undeveloped (0) and NULLs for undevelopable areas
<code>
... developed=urban_2011 ...
</code>

* predictors selected with {{AddonCmd|r.futures.potential}} and their coefficients in a <tt>potential.csv</tt> file. The order of predictors must match the order in the file and the categories of the counties must match raster <tt>counties</tt>.
<code>
... predictors=slope,forest_smooth_perc,dist_interchanges_km,travel_time_cities devpot_params=potential.csv ...
</code>

* initial development pressure computed by {{AddonCmd|r.futures.devpressure}}, it's important to set here the same parameters
<code>
... development_pressure=devpressure_1 n_dev_neighbourhood=10 development_pressure_approach=gravity gamma=1 scaling_factor=1 ...
</code>

* per capita land demand computed by {{AddonCmd|r.futures.demand}}, the categories of the counties must match raster <tt>counties</tt>.
<code>
... demand=demand.csv ...
</code>

* patch parameters from the calibration step
<code>
... discount_factor=0.3 compactness_mean=0.4 compactness_range=0.08 patch_sizes=patches.txt ...
</code>

* recommended parameters for patch growing algorithm
<code>
... num_neighbors=4 seed_search=2 ...
</code>

* set random seed for repeatable results or set flag <tt>-s</tt> to generate seed automatically
<code>
... random_seed=1 ...
</code>

* specify final output map and optionally basename for intermediate raster maps
<code>
output=final output_series=final
</code>

== Scenarios ==
Scenarios involving policies that encourage infill versus sprawl can be explored using the <tt>incentive_power</tt> parameter of {{AddonCmd|r.futures.pga}},
which uses a power function to transform the evenness of the probability gradient in POTENTIAL. You can change the power to a number between 0.25 and 4 to test urban sprawl/infill scenarios.
Higher power leads to infill behavior, lower power to urban sprawl.

== Postprocessing ==

Follow a [[Creating_animation_from_FUTURES_output_in_GRASS_GIS| tutorial how to make an animation from the results]].

= GRASS GIS Python API =

[[Category: Tutorial]]
[[Category: FUTURES]]
[[Category: Urban]]

Workshop on urban growth modeling with FUTURES

2016-03-22T19:32:50Z

⚠️Dbvanber: /* Command line vs. GUI interface */

{{ToModify}}
= Workshop introduction =
r.futures.* is an implementation of the '''FUT'''ure '''U'''rban-'''R'''egional '''E'''nvironment '''S'''imulation (FUTURES)[1] which is a model for multilevel simulations of emerging urban-rural landscape structure. FUTURES produces regional projections of landscape patterns using coupled submodels that integrate nonstationary drivers of land change: per capita demand (DEMAND submodel), site suitability (POTENTIAL submodel), and the spatial structure of conversion events (PGA submodel).

[1] Meentemeyer, R. K., Tang, W., Dorning, M. A., Vogler, J. B., Cunniffe, N. J., & Shoemaker, D. A. (2013). [http://www.tandfonline.com/doi/abs/10.1080/00045608.2012.707591 FUTURES: multilevel simulations of emerging urban-rural landscape structure using a stochastic patch-growing algorithm.] Annals of the Association of American Geographers, 103(4), 785-807

== Software ==
There are a number of software requirements to run FUTURES that will need to be download and installed. Required software includes:
* GRASS GIS 7
* addons
** {{AddonCmd|r.futures.pga}}
** {{AddonCmd|r.futures.potential}}
** {{AddonCmd|r.futures.potsurface}}
** {{AddonCmd|r.futures.demand}}
** {{AddonCmd|r.futures.devpressure}}
** {{AddonCmd|r.sample.category}}
* R (≥ 3.0.2) - needed for {{AddonCmd|r.futures.potential}} with packages:
**MuMIn, lme4, optparse, rgrass7
* SciPy - useful for {{AddonCmd|r.futures.demand}}

=== Installation ===
We use the R statistical software for our calculation of site suitability (i.e. development potential) in FUTURES. R is a free software environment for statistical computing and graphics. If you don't have R, or you have older an version, please download and install the software from [http://archive.linux.duke.edu/cran/ install R] and be sure to additionally add these required packages:
<pre>
install.packages(c("MuMIn", "lme4", "optparse", "rgrass7"))
</pre>

==== MS Windows ====
We will be using GRASS GIS 7.0.3 that can be found here in the [https://trac.osgeo.org/osgeo4w/ OSGeo4W] package manager.
Please install the latest stable GRASS GIS 7 version and the SciPy Python package using the ''Advanced install'' option.
A guide with step by step screen shot instructions is available [https://docs.google.com/presentation/d/1yEGpriBne7RvjB35HI6GecNwO1P1y2nRGqDThqoNnCE/edit?usp=sharing here].

In order for GRASS to be able to find R executables, GRASS must be on the PATH variable. Follow this [solution] to make R accessible from GRASS permanently.
A simple but temporary solution is to open GRASS GIS and paste this in the black terminal:
<pre>
set PATH=%PATH%;C:\Program Files\R\R-3.0.2\bin
</pre>
This has to be repeated after restarting GRASS session.

==== Ubuntu Linux ====
Install GRASS GIS from packages:
<pre>
sudo add-apt-repository ppa:ubuntugis/ubuntugis-unstable
sudo apt-get update
sudo apt-get install grass
</pre>

== Workshop data ==
The data that we will be using for the workshop can be download here: [http://fatra.cnr.ncsu.edu/futures/futures_ncspm_Asheville.zip sample dataset]. Please place these layers in your local GRASS directory:
* digital elevation model ([http://nationalmap.gov/elevation.html NED])
* [http://www.mrlc.gov/ NLCD] 2001, 2011
* NLCD 1992/2001 Retrofit Land Cover Change Product
* transportation network ([http://www.census.gov/geo/maps-data/data/tiger-line.html TIGER])
* county boundaries ([http://www.census.gov/geo/maps-data/data/tiger-line.html TIGER])
* protected areas ([http://www.conservationgateway.org/ConservationByGeography/NorthAmerica/UnitedStates/edc/reportsdata/terrestrial/secured/Pages/default.aspx Secured Lands])
* cities as points (USGS)

In addition, download [http://fatra.cnr.ncsu.edu/futures/futures_Asheville_files.zip population information as text files]:
* county population past estimates and future projections ([https://www.osbm.nc.gov/demog/county-projections NC OSBM]) per county (nonspatial)

= GRASS GIS introduction =
There are many advantages to using the open source GRASS GIS platform, but for many that are more familiar with ARCGis and QGis, the setup and implementation of spatial tools in GRASS can be confusing. Here we provide an overview of the GRASS GIS project: [https://grass.osgeo.org grass.osgeo.org] that might be helpful to review if you are a first time users. For this exercise it's not necessary to have a full understanding of how to use GRASS. However, you will need to know how to place your data in the correct GRASS database directory, as well as some basic GRASS functionality. Step by step instructions are provided below
== Setting up GRASS for the tutorial ==
GRASS uses unique database terminology and structure ([https://grass.osgeo.org/grass71/manuals/grass_database.html GRASS database]) that are important to understand for the set up of this tutorial, as you will need to place the required data (e.g. Mapset) in a specific GRASS database Location. In the following we review important terminology and give step by step direction on how to download and place you data in the correct location.

=== Important GRASS directory terminology ===
* A '''GRASS database''' consist of directory with specific Locations (projects) where data layer are stored
* '''Location''' hold all Mapsets in a specific directoy that have the same spatial projection (spatial reference system)
* '''Mapset''' are a collection of maps with the same spatial projection

=== Creating a GRASS database for the tutorial ===
You need to create a GRASS database with the Mapset that we will use for the tutorial before we can run the FUTURES model. Please Download the [http://fatra.cnr.ncsu.edu/futures/futures_ncspm_Asheville.zip workshop location], noting where the files are located on your local directory. Now, create (unless you already have it) a directory named <tt>grassdata</tt> (GRASS database) in your home folder (or Documents), unzip the downloaded data into this directory. You should now have a Location <tt>futures_ncspm</tt> in <tt>grassdata</tt>.

<center><gallery perrow=1 widths=500 heights=250>Image:GRASS FUTURES startup.png|GRASS GIS 7.0.3 startup dialog with downloaded Location and Mapsets for FUTURES workshop</gallery></center>

=== Launching and exploring data in GRASS ===
Now that we have the data in the correct GRASS database, we can launch the Graphical User Interface (GUI). The GUI interface allows you to display raster, vector data as well as navigate through zooming in and out. Advanced exploration and visualization, like many popular GIS software, is also possible in GRASS (e.g. queries, adding legend). The print screens below depicts how you can add different map layers (left) and display the metadata of your data layers.

<center><gallery perrow=2 widths=500 heights=250>Image:GRASS FUTURES wxGUI display.png|Layer Manager and Map Display overview. Annotations show how to add raster layer, query, add legend.
Image:wxGUI_metadata_rinfo.png|Show raster map metadata by right click on layer</gallery></center>

== GRASS functionality ==
One of the advantage of GRASS is the diversity and number of module addons that let you analyze all manner of spatial and temporal. Because it is open source modules are added daily increasing functionality and methods for analysis of your data. GRASS GIS has over [https://grass.osgeo.org/grass70/manuals/full_index.html 500 different modules] in the core distribution and over [https://grass.osgeo.org/grass70/manuals/addons/ 230 addon modules] that can be used to prepare and analyze data layers.
<center>
{| class="wikitable"
|-
! Prefix !! Function !! Example
|-
| r.* || raster processing || ''{{cmd|r.mapcalc}}'': map algebra
|-
| v.* || vector processing || ''{{cmd|v.clean}}'': topological cleaning
|-
| i.* || imagery processing || ''{{cmd|i.segment}}'': object recognition
|-
| db.* || database management || ''{{cmd|db.select}}'': select values from table
|-
| r3.* || 3D raster processing || ''{{cmd|r3.stats}}'': 3D raster statistics
|-
| t.* || temporal data processing || ''{{cmd|t.rast.aggregate}}'': temporal aggregation
|-
| g.* || general data management || ''{{cmd|g.rename}}'': renames map
|-
| d.* || display ||''{{cmd|d.rast}}'': display raster map
|}</center>

=== Command line vs. GUI interface===
GRASS modules can be executed either through a GUI or command line interface. The GUI offers a user-friendly approach to executing modules where the user can navigate to data layers that they would like to analyze and modify processing options with simple check boxes. The GUI also offer a easily accessible manual on how to execute a model. The command line interface allows users to execute a module using command prompts specific to that module. This is handy when you are running similar analyses with minor modification or are familiar with the module commands for quick efficient processing. In this workshop we provide module prompts that can be copy and pasted into the command line for our workflow, but you can use both GUI and command line depending on personal preference. Look how {{cmd|wxGUI.modules|version=71|desc=GUI and command line interface}} represent the same tool. ''Task:'' compute aspect (orientation) from provided digital elevation model using module {{cmd|r.slope.aspect}} using both module dialog and command line.
* How to find modules? Modules are organized by their functionality in wxGUI menu, or we can search for them in Search modules tab. If we already know which module to use, we can just type it in the wxGUI command console. <center><gallery perrow=3 widths=380 heights=190>Image:wxGUI_menu_rinfo.png|Modules can be found in wxGUI menu
Image:wxGUI_module_search.png|You can search modules by name, description or keywords in ''Search modules'' tab
Image:wxGUI_console_completion.png|By typing prefix r. we make a list of modules starting with that prefix to show up.</gallery></center>


* {{cmd|g.region|desc=Computational region}} - an important raster concept
** defined by region extent and raster resolution
** applies to all raster operations
** persists between GRASS session, can be different for different mapsets
** advantages: keeps your results consistent, avoid clipping, for computationally demanding tasks set region to smaller extent, check your result is good and then set the computational region to the entire study area and rerun analysis
** run <code>g.region -p</code> or in menu ''Settings'' - ''Region'' - ''Display region'' to see current region settings
[[File:WxGUI set region.png|700px|thumb|center|Simple ways to set computational region from GUI. On the left, set region to match raster map. On the right, select the highlighted option and then set region by drawing rectangle.]]

* GRASS 3D view

= Modeling with FUTURES =
== Initial steps and data preparation ==
First we will set the computational region of our analyses to an extent covering our study area and aligned with our base landuse rasters:
<source lang="bash">g.region raster=landuse_2011 -p</source>

We will derive urbanized areas from NLCD dataset for year 1992, 2001 and 2011
by extracting categories category 21 - 24 into a new binary map where developed is 1,
undeveloped 0 and NULL (no data) is area unsuitable for development (water, wetlands, protected areas).
First we will convert protected areas from vector to raster. We set
NULLs to zeros (for simpler raster algebra expression in the next step) using {{cmd|r.null}}:

<source lang="bash">
v.to.rast input=protected_areas output=protected_areas use=val
r.null map=protected_areas null=0
</source>

And then create rasters of developed/undeveloped areas using raster algebra:

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.mapcalc "urban_1992 = if(landuse_1992 >= 21 && landuse_1992 <= 24, 1, if(landuse_1992 == 11 || landuse_1992 >= 90 || protected_areas, null(), 0))"
r.mapcalc "urban_2001 = if(landuse_2001 >= 21 && landuse_2001 <= 24, 1, if(landuse_2001 == 11 || landuse_2001 >= 90 || protected_areas, null(), 0))"
r.mapcalc "urban_2011 = if(landuse_2011 >= 21 && landuse_2011 <= 24, 1, if(landuse_2011 == 11 || landuse_2011 >= 90 || protected_areas, null(), 0))"
</source>

We will convert vector counties to raster with the values of the FIPS attribute which links to population file:

<source lang="bash">
v.to.rast input=counties type=area use=attr attribute_column=FIPS output=counties
</source>

Before further steps, we will set our working directory so that the input population files and text files
we are going to create are saved in one directory and easily accessible.
You can do that from menu ''Settings'' → ''GRASS working environment'' → ''Change working directory''.
Select (or create) a directory and move there the downloaded files <tt>population_projection.csv</tt> and <tt>population_trend.csv</tt>.

== Potential submodel ==
Module {{AddonCmd|r.futures.potential}} implements POTENTIAL submodel as a part of FUTURES land change model. POTENTIAL is implemented using a set of coefficients that relate a selection of site suitability factors to the probability of a place becoming developed. This is implemented using the parameter table in combination with maps of those site suitability factors (mapped predictors). The coefficients are obtained by conducting multilevel logistic regression in R with package lme4 where the coefficients may vary by county. The best model is selected automatically using dredge function from package [https://cran.r-project.org/web/packages/MuMIn/index.html MuMIn].

First, we will derive couple of predictors.
=== Predictors ===
==== Slope ====
We will derive slope in degrees from digital elevation model using {{cmd|r.slope.aspect}} module:
<source lang="bash">r.slope.aspect elevation=elevation_30m slope=slope</source>

==== Distance from lakes/rivers ====
First we will extract [http://www.mrlc.gov/nlcd11_leg.php category ''Open Water''] from 2011 NLCD dataset:
<source lang="bash">
r.mapcalc "water = if(landuse_2011 == 11, 1, null())"
</source>

Then we compute the distance to water with module {{cmd|r.grow.distance}} and set color table to shades of blue:
<source lang="bash">
r.grow.distance input=water distance=dist_to_water
r.colors -n map=dist_to_water color=blues
</source>

==== Distance from protected areas ====
We will use raster protected of protected areas we already created, but we will set NULL values to zero.
We compute the distance to protected areas with module {{cmd|r.grow.distance}} and set color table from green to red:
<source lang="bash">
r.null map=protected_areas setnull=0
r.grow.distance input=protected_areas distance=dist_to_protected
r.colors map=dist_to_protected color=gyr
</source>

==== Forests ====
We will smooth the transition between forest and other land use, see NLCD [http://www.mrlc.gov/nlcd11_leg.php category ''Open Water'']:
<source lang="bash">
r.mapcalc "forest = if(landuse_2011 >= 41 && landuse_2011 <= 43, 1, 0)"
r.neighbors -c input=forest output=forest_smooth size=15 method=average
r.colors map=forest_smooth color=ndvi
</source>

==== Travel time to cities ====
Here we will compute travel time to cities (with population > 5000)
as cumulative cost distance where cost is defined as travel time on roads.
First we specify the speed on different types of roads.
We copy the roads raster into our mapset so that we can change it
by adding a new attribute field <tt>speed</tt>. Then we assign speed values (km/h) based on the type of road:

<source lang="bash">
g.copy vector=roads,myroads
v.db.addcolumn map=myroads columns="speed double precision"
v.db.update map=myroads column=speed value=50 where="MTFCC = 'S1400'"
v.db.update map=myroads column=speed value=100 where="MTFCC IN ('S1100', 'S1200')"
</source>

Now we rasterize the selected road types using the speed values from the attribute table as raster values.

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
v.to.rast input=myroads type=line where="MTFCC IN ('S1100', 'S1200', 'S1400')" output=roads_speed use=attr attribute_column=speed
</source>

We set the rest of the area to low speed and recompute the speed as time to travel through a 30m cell in minutes:

<source lang="bash">
r.null map=roads_speed null=5
r.mapcalc "roads_travel_time = 1.8 / roads_speed"
</source>

Finally we compute the travel time to larger cities using {{cmd|r.cost}}:

<source lang="bash">
r.cost input=roads_travel_time output=travel_time_cities start_points=cities
r.colors map=travel_time_cities color=byr
</source>

==== Road density ====
We will rasterize roads and use moving window analysis ({{cmd|r.neighbors}}) to compute road density:

<source lang="bash">
v.to.rast input=roads output=roads use=val type=line
r.null map=roads null=0
r.neighbors -c input=roads output=road_dens size=25 method=average
</source>

==== Distance to interchanges ====

We will consider TIGER roads of type <tt>Ramp</tt> as interchanges, rasterize them and compute euclidean distance to them:

<source lang="bash">
v.to.rast input=roads type=line where="MTFCC = 'S1630'" output=interchanges use=val
r.grow.distance -m input=interchanges distance=dist_interchanges
</source>

=== Development pressure ===

We compute development pressure with {{AddonCmd|r.futures.devpressure}}. Development pressure is a predictor based on number of neighboring developed cells within search distance, weighted by distance. The development pressure variable plays a special role in the model, allowing for a feedback between predicted change and change in subsequent steps.

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.devpressure -n input=urban_2011 output=devpressure_2 method=gravity size=7 gamma=2 scaling_factor=10
r.futures.devpressure -n input=urban_2011 output=devpressure_1 method=gravity size=10 gamma=1 scaling_factor=1
r.futures.devpressure -n input=urban_2011 output=devpressure_0_5 method=gravity size=30 gamma=0.5 scaling_factor=0.1
</source>

When gamma increases, development influence decreases more rapidly with distance.
Size is half the size of the moving window. When gamma is low, local development influences more distant places.
We will derive 3 layers with different gamma and size parameters for the potential statistical model.

=== Rescaling variables ===

First we will look at the ranges of our predictor variables by running a short Python code snippet in Python shell:

<source lang="python" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
for name in ['slope', 'dist_to_water', 'dist_to_protected', 'forest_smooth', 'travel_time_cities', 'road_dens', 'dist_interchanges', 'devpressure_0_5', 'devpressure_1']:
minmax = grass.raster_info(name)
print name, minmax['min'], minmax['max']
</source>

We will rescale some of our input variables:

<source lang="bash">
r.mapcalc "dist_to_water_km = dist_to_water / 1000"
r.mapcalc "dist_to_protected_km = dist_to_protected / 1000"
r.mapcalc "dist_interchanges_km = dist_interchanges / 1000"
r.mapcalc "road_dens_perc = road_dens * 100"
r.mapcalc "forest_smooth_perc = forest_smooth * 100"
</source>

=== Sampling ===
To sample only in the analyzed counties, we will clip development layer:

<source lang="bash">
r.mapcalc "urban_change_01_11 = if(urban_2011 == 1, if(urban_2001 == 0, 1, null()), 0)"
r.mapcalc "urban_change_clip = if(counties, urban_change_01_11)"
</source>

To estimate the number of sampling points, we can use {{cmd|r.report}} to report number of developed/undeveloped cells and their ratio.

<source lang="bash">
r.report map=urban_change_clip units=h,c,p
</source>

We will sample the predictors and the response variable with 5000 random points in undeveloped areas and 1000 points in developed area:

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.sample.category input=urban_change_clip output=sampling sampled=counties,devpressure_0_5,devpressure_1,devpressure_2,slope,road_dens_perc,forest_smooth_perc,dist_to_water_km,dist_to_protected_km,dist_interchanges_km,travel_time_cities npoints=5000,1000
</source>

The attribute table can be exported as CSV file (not necessary step):

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
v.db.select map=sampling columns=urban_change_clip,counties,devpressure_0_5,devpressure_1,slope,road_dens_perc,forest_smooth_perc,dist_to_water_km,dist_to_protected_km,dist_interchanges_km,travel_time_cities separator=comma file=samples.csv
</source>

=== Development potential ===
Now we find best model for predicting urbanization using {{AddonCmd|r.futures.potential}} which wraps an R script.

We can run R [http://www.inside-r.org/packages/cran/MuMIn/docs/dredge dredge] function to find "best" model. We can specify minimum and maximum number of predictors the final model should use.
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.potential -d input=sampling output=potential.csv columns=devpressure_1,slope,road_dens_perc,forest_smooth_perc,dist_to_water_km,dist_to_protected_km,dist_interchanges_km,travel_time_cities developed_column=urban_change_clip subregions_column=counties min_variables=4
</source>

Also, we can play with different combinations of predictors, for example:

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.potential input=sampling output=potential.csv columns=devpressure_2,road_dens_perc,slope,dist_interchanges_km,dist_to_water_km developed_column=urban_change_clip subregions_column=counties --o
r.futures.potential input=sampling output=potential.csv columns=devpressure_1,road_dens_perc,slope,dist_interchanges_km,dist_to_water_km developed_column=urban_change_clip subregions_column=counties --o
...
</source>

You can then open the output file <tt>potential.csv</tt>, which is a CSV file with tabs as separators.

For this tutorial, the final potential is created with:
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.potential input=sampling output=potential.csv columns=devpressure_2,road_dens_perc,slope,dist_interchanges_km,dist_to_water_km developed_column=urban_change_clip subregions_column=counties --o
</source>

We can now visualize the suitability surface using module {{AddonCmd|r.futures.potsurface}}. It creates initial development potential (suitability) raster from predictors and model coefficients and serves only for evaluating development potential model. The values of the resulting raster range from 0 to 1.

<source lang="bash">
r.futures.potsurface input=potential.csv subregions=counties output=suitability
r.colors map=suitability color=byr
</source>

== Demand submodel ==
First we will mask out roads so that they don't influence into per capita land demand relation.
<source lang="bash">
v.to.rast input=roads type=line output=roads_mask use=val
r.mask roads_mask -i
</source>

We will use {{AddonCmd|r.futures.demand}} which derives the population vs. development relation. The relation can be linear/logarithmic/logarithmic2/exponential/exponential approach.
Look for examples of the different relations in the manual.

* linear: y = A + Bx
* logarithmic: y = A + Bln(x)
* logarithmic2: y = A + B * ln(x - C)        (requires SciPy)
* exponential: y = Ae^(BX)
* exp_approach: y = (1 - e^(-A(x - B))) + C        (requires SciPy)

The format of the input population CSV files is described in the manual. It is important to have synchronized categories of subregions and the column headers of the CSV files (in our case FIPS number). How to simply generate the list of years (for which demand is computed) is described in {{AddonCmd|r.futures.demand}} manual, for example run this in Python console:

<source lang="python">
','.join([str(i) for i in range(2011, 2036)])
</source>

Then we can create the DEMAND file:
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.demand development=urban_1992,urban_2001,urban_2011 subregions=counties observed_population=population_trend.csv projected_population=population_projection.csv simulation_times=2011,2012,2013,2014,2015,2016,2017,2018,2019,2020,2021,2022,2023,2024,2025,2026,2027,2028,2029,2030,2031,2032,2033,2034,2035 plot=plot_demand.pdf demand=demand.csv separator=comma
</source>

In your current working directory, you should find files <tt>plot_demand.png</tt> and <tt>demand.csv</tt>.

If you have SciPy installed, you can experiment with other methods for fitting the functions:
<source lang="bash">
r.futures.demand ... method=logarithmic2
r.futures.demand ... method=exp_approach
</source>
If necessary, you can create a set of demand files produced by fitting each method separately and
then pick for each county the method which seems best and manually create a new demand file.

When you are finished, remove the mask as it is not needed for the next steps.
<source lang="bash">
r.mask -r
</source>

== Patch calibration ==
Patch calibration can be a very time consuming computation.
Therefore we select only one county (Buncombe):

<source lang="bash">
v.to.rast input=counties type=area where="FIPS == 37021" use=attr attribute_column=FIPS output=calib_county
g.region raster=calib_county zoom=calib_county
</source>
to derive patches of new development by comparing historical and latest development.
We can keep only patches with minimum size 2 cells (1800 = 2 x 30 x 30 m).

<source lang="bash">
r.futures.calib development_start=urban_1992 development_end=urban_2011 subregions=counties patch_sizes=patches.txt patch_threshold=1800 -l
</source>
We obtained a file <tt>patches.txt</tt> (used later in the PGA) - a patch size distribution file - containing sizes of all found patches.

We can look at the distribution of the patch sizes:

<source lang="python">
from matplotlib import pyplot as plt
with open('patches.txt') as f:
patches = [int(patch) for patch in f.readlines()]
plt.hist(patches, 2000)
plt.xlim(0,50)
plt.show()
</source>

At this point, we start the calibration to get best parameters of patch shape
(for this tutorial, this step can be skipped and the suggested parameters are used).

<source lang="bash"
style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.calib development_start=urban_1992 development_end=urban_2011 subregions=calib_county patch_sizes=patches.txt calibration_results=calib.csv patch_threshold=1800 repeat=5 compactness_mean=0.1,0.3,0.5,0.7,0.9 compactness_range=0.05 discount_factor=0.1,0.3,0.5,0.7,0.9 predictors=road_dens_perc,forest_smooth_perc,dist_to_protected_km demand=demand.csv devpot_params=potential.csv num_neighbors=4 seed_search=2 development_pressure=devpressure_0_5 development_pressure_approach=gravity n_dev_neighbourhood=30 gamma=0.5 scaling_factor=0.1
</source>

== FUTURES simulation ==
We will switch back to our previous region:
<source lang="bash">
g.region raster=landuse_2011 -p
</source>

Now we have all the inputs necessary for running {{AddonCmd|r.futures.pga}}:

The entire command is here:
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.pga subregions=counties developed=urban_2011 predictors=slope,forest_smooth_perc,dist_interchanges_km,travel_time_cities devpot_params=potential.csv development_pressure=devpressure_1 n_dev_neighbourhood=10 development_pressure_approach=gravity gamma=1 scaling_factor=1 demand=demand.csv discount_factor=0.3 compactness_mean=0.2 compactness_range=0.1 patch_sizes=patches.txt num_neighbors=4 seed_search=2 random_seed=1 output=final output_series=final
</source>

=== Quick description ===
The command parameters and their values:
* raster map of counties with their categories
<code>
... subregions=counties ...
</code>

* raster of developed (1), undeveloped (0) and NULLs for undevelopable areas
<code>
... developed=urban_2011 ...
</code>

* predictors selected with {{AddonCmd|r.futures.potential}} and their coefficients in a <tt>potential.csv</tt> file. The order of predictors must match the order in the file and the categories of the counties must match raster <tt>counties</tt>.
<code>
... predictors=slope,forest_smooth_perc,dist_interchanges_km,travel_time_cities devpot_params=potential.csv ...
</code>

* initial development pressure computed by {{AddonCmd|r.futures.devpressure}}, it's important to set here the same parameters
<code>
... development_pressure=devpressure_1 n_dev_neighbourhood=10 development_pressure_approach=gravity gamma=1 scaling_factor=1 ...
</code>

* per capita land demand computed by {{AddonCmd|r.futures.demand}}, the categories of the counties must match raster <tt>counties</tt>.
<code>
... demand=demand.csv ...
</code>

* patch parameters from the calibration step
<code>
... discount_factor=0.3 compactness_mean=0.4 compactness_range=0.08 patch_sizes=patches.txt ...
</code>

* recommended parameters for patch growing algorithm
<code>
... num_neighbors=4 seed_search=2 ...
</code>

* set random seed for repeatable results or set flag <tt>-s</tt> to generate seed automatically
<code>
... random_seed=1 ...
</code>

* specify final output map and optionally basename for intermediate raster maps
<code>
output=final output_series=final
</code>

== Scenarios ==
Scenarios involving policies that encourage infill versus sprawl can be explored using the <tt>incentive_power</tt> parameter of {{AddonCmd|r.futures.pga}},
which uses a power function to transform the evenness of the probability gradient in POTENTIAL. You can change the power to a number between 0.25 and 4 to test urban sprawl/infill scenarios.
Higher power leads to infill behavior, lower power to urban sprawl.

== Postprocessing ==

Follow a [[Creating_animation_from_FUTURES_output_in_GRASS_GIS| tutorial how to make an animation from the results]].

= GRASS GIS Python API =

[[Category: Tutorial]]
[[Category: FUTURES]]
[[Category: Urban]]

Workshop on urban growth modeling with FUTURES

2016-03-22T19:29:34Z

⚠️Dbvanber: /* GRASS functionality */

{{ToModify}}
= Workshop introduction =
r.futures.* is an implementation of the '''FUT'''ure '''U'''rban-'''R'''egional '''E'''nvironment '''S'''imulation (FUTURES)[1] which is a model for multilevel simulations of emerging urban-rural landscape structure. FUTURES produces regional projections of landscape patterns using coupled submodels that integrate nonstationary drivers of land change: per capita demand (DEMAND submodel), site suitability (POTENTIAL submodel), and the spatial structure of conversion events (PGA submodel).

[1] Meentemeyer, R. K., Tang, W., Dorning, M. A., Vogler, J. B., Cunniffe, N. J., & Shoemaker, D. A. (2013). [http://www.tandfonline.com/doi/abs/10.1080/00045608.2012.707591 FUTURES: multilevel simulations of emerging urban-rural landscape structure using a stochastic patch-growing algorithm.] Annals of the Association of American Geographers, 103(4), 785-807

== Software ==
There are a number of software requirements to run FUTURES that will need to be download and installed. Required software includes:
* GRASS GIS 7
* addons
** {{AddonCmd|r.futures.pga}}
** {{AddonCmd|r.futures.potential}}
** {{AddonCmd|r.futures.potsurface}}
** {{AddonCmd|r.futures.demand}}
** {{AddonCmd|r.futures.devpressure}}
** {{AddonCmd|r.sample.category}}
* R (≥ 3.0.2) - needed for {{AddonCmd|r.futures.potential}} with packages:
**MuMIn, lme4, optparse, rgrass7
* SciPy - useful for {{AddonCmd|r.futures.demand}}

=== Installation ===
We use the R statistical software for our calculation of site suitability (i.e. development potential) in FUTURES. R is a free software environment for statistical computing and graphics. If you don't have R, or you have older an version, please download and install the software from [http://archive.linux.duke.edu/cran/ install R] and be sure to additionally add these required packages:
<pre>
install.packages(c("MuMIn", "lme4", "optparse", "rgrass7"))
</pre>

==== MS Windows ====
We will be using GRASS GIS 7.0.3 that can be found here in the [https://trac.osgeo.org/osgeo4w/ OSGeo4W] package manager.
Please install the latest stable GRASS GIS 7 version and the SciPy Python package using the ''Advanced install'' option.
A guide with step by step screen shot instructions is available [https://docs.google.com/presentation/d/1yEGpriBne7RvjB35HI6GecNwO1P1y2nRGqDThqoNnCE/edit?usp=sharing here].

In order for GRASS to be able to find R executables, GRASS must be on the PATH variable. Follow this [solution] to make R accessible from GRASS permanently.
A simple but temporary solution is to open GRASS GIS and paste this in the black terminal:
<pre>
set PATH=%PATH%;C:\Program Files\R\R-3.0.2\bin
</pre>
This has to be repeated after restarting GRASS session.

==== Ubuntu Linux ====
Install GRASS GIS from packages:
<pre>
sudo add-apt-repository ppa:ubuntugis/ubuntugis-unstable
sudo apt-get update
sudo apt-get install grass
</pre>

== Workshop data ==
The data that we will be using for the workshop can be download here: [http://fatra.cnr.ncsu.edu/futures/futures_ncspm_Asheville.zip sample dataset]. Please place these layers in your local GRASS directory:
* digital elevation model ([http://nationalmap.gov/elevation.html NED])
* [http://www.mrlc.gov/ NLCD] 2001, 2011
* NLCD 1992/2001 Retrofit Land Cover Change Product
* transportation network ([http://www.census.gov/geo/maps-data/data/tiger-line.html TIGER])
* county boundaries ([http://www.census.gov/geo/maps-data/data/tiger-line.html TIGER])
* protected areas ([http://www.conservationgateway.org/ConservationByGeography/NorthAmerica/UnitedStates/edc/reportsdata/terrestrial/secured/Pages/default.aspx Secured Lands])
* cities as points (USGS)

In addition, download [http://fatra.cnr.ncsu.edu/futures/futures_Asheville_files.zip population information as text files]:
* county population past estimates and future projections ([https://www.osbm.nc.gov/demog/county-projections NC OSBM]) per county (nonspatial)

= GRASS GIS introduction =
There are many advantages to using the open source GRASS GIS platform, but for many that are more familiar with ARCGis and QGis, the setup and implementation of spatial tools in GRASS can be confusing. Here we provide an overview of the GRASS GIS project: [https://grass.osgeo.org grass.osgeo.org] that might be helpful to review if you are a first time users. For this exercise it's not necessary to have a full understanding of how to use GRASS. However, you will need to know how to place your data in the correct GRASS database directory, as well as some basic GRASS functionality. Step by step instructions are provided below
== Setting up GRASS for the tutorial ==
GRASS uses unique database terminology and structure ([https://grass.osgeo.org/grass71/manuals/grass_database.html GRASS database]) that are important to understand for the set up of this tutorial, as you will need to place the required data (e.g. Mapset) in a specific GRASS database Location. In the following we review important terminology and give step by step direction on how to download and place you data in the correct location.

=== Important GRASS directory terminology ===
* A '''GRASS database''' consist of directory with specific Locations (projects) where data layer are stored
* '''Location''' hold all Mapsets in a specific directoy that have the same spatial projection (spatial reference system)
* '''Mapset''' are a collection of maps with the same spatial projection

=== Creating a GRASS database for the tutorial ===
You need to create a GRASS database with the Mapset that we will use for the tutorial before we can run the FUTURES model. Please Download the [http://fatra.cnr.ncsu.edu/futures/futures_ncspm_Asheville.zip workshop location], noting where the files are located on your local directory. Now, create (unless you already have it) a directory named <tt>grassdata</tt> (GRASS database) in your home folder (or Documents), unzip the downloaded data into this directory. You should now have a Location <tt>futures_ncspm</tt> in <tt>grassdata</tt>.

<center><gallery perrow=1 widths=500 heights=250>Image:GRASS FUTURES startup.png|GRASS GIS 7.0.3 startup dialog with downloaded Location and Mapsets for FUTURES workshop</gallery></center>

=== Launching and exploring data in GRASS ===
Now that we have the data in the correct GRASS database, we can launch the Graphical User Interface (GUI). The GUI interface allows you to display raster, vector data as well as navigate through zooming in and out. Advanced exploration and visualization, like many popular GIS software, is also possible in GRASS (e.g. queries, adding legend). The print screens below depicts how you can add different map layers (left) and display the metadata of your data layers.

<center><gallery perrow=2 widths=500 heights=250>Image:GRASS FUTURES wxGUI display.png|Layer Manager and Map Display overview. Annotations show how to add raster layer, query, add legend.
Image:wxGUI_metadata_rinfo.png|Show raster map metadata by right click on layer</gallery></center>

== GRASS functionality ==
One of the advantage of GRASS is the diversity and number of module addons that let you analyze all manner of spatial and temporal. Because it is open source modules are added daily increasing functionality and methods for analysis of your data. GRASS GIS has over [https://grass.osgeo.org/grass70/manuals/full_index.html 500 different modules] in the core distribution and over [https://grass.osgeo.org/grass70/manuals/addons/ 230 addon modules] that can be used to prepare and analyze data layers.
<center>
{| class="wikitable"
|-
! Prefix !! Function !! Example
|-
| r.* || raster processing || ''{{cmd|r.mapcalc}}'': map algebra
|-
| v.* || vector processing || ''{{cmd|v.clean}}'': topological cleaning
|-
| i.* || imagery processing || ''{{cmd|i.segment}}'': object recognition
|-
| db.* || database management || ''{{cmd|db.select}}'': select values from table
|-
| r3.* || 3D raster processing || ''{{cmd|r3.stats}}'': 3D raster statistics
|-
| t.* || temporal data processing || ''{{cmd|t.rast.aggregate}}'': temporal aggregation
|-
| g.* || general data management || ''{{cmd|g.rename}}'': renames map
|-
| d.* || display ||''{{cmd|d.rast}}'': display raster map
|}</center>

=== Command line vs. GUI interface===
GRASS modules can be executed either through a GUI and command line interface. The GUI offers a user-friendly approach to executing modules where the user can navigate to data layers that they would like to analyze and check processing options. The GUI also offer a easily accessible manual on how to execute a model. The command line interface allows users to execute a module using command prompts specific to that module. This handy when you are running similar analyses with minor modification or are familiar with the module commands for quick efficient processing. In this workshop we provide module prompts that can be copy and pasted into the command line for out workflow, but you can use both GUI and command line depending on personal preference. Look how {{cmd|wxGUI.modules|version=71|desc=GUI and command line interface}} represent the same tool. ''Task:'' compute aspect (orientation) from provided digital elevation model using module {{cmd|r.slope.aspect}} using both module dialog and command line.
* How to find modules? Modules are organized by their functionality in wxGUI menu, or we can search for them in Search modules tab. If we already know which module to use, we can just type it in the wxGUI command console. <center><gallery perrow=3 widths=380 heights=190>Image:wxGUI_menu_rinfo.png|Modules can be found in wxGUI menu
Image:wxGUI_module_search.png|You can search modules by name, description or keywords in ''Search modules'' tab
Image:wxGUI_console_completion.png|By typing prefix r. we make a list of modules starting with that prefix to show up.</gallery></center>


* {{cmd|g.region|desc=Computational region}} - an important raster concept
** defined by region extent and raster resolution
** applies to all raster operations
** persists between GRASS session, can be different for different mapsets
** advantages: keeps your results consistent, avoid clipping, for computationally demanding tasks set region to smaller extent, check your result is good and then set the computational region to the entire study area and rerun analysis
** run <code>g.region -p</code> or in menu ''Settings'' - ''Region'' - ''Display region'' to see current region settings
[[File:WxGUI set region.png|700px|thumb|center|Simple ways to set computational region from GUI. On the left, set region to match raster map. On the right, select the highlighted option and then set region by drawing rectangle.]]

* GRASS 3D view

= Modeling with FUTURES =
== Initial steps and data preparation ==
First we will set the computational region of our analyses to an extent covering our study area and aligned with our base landuse rasters:
<source lang="bash">g.region raster=landuse_2011 -p</source>

We will derive urbanized areas from NLCD dataset for year 1992, 2001 and 2011
by extracting categories category 21 - 24 into a new binary map where developed is 1,
undeveloped 0 and NULL (no data) is area unsuitable for development (water, wetlands, protected areas).
First we will convert protected areas from vector to raster. We set
NULLs to zeros (for simpler raster algebra expression in the next step) using {{cmd|r.null}}:

<source lang="bash">
v.to.rast input=protected_areas output=protected_areas use=val
r.null map=protected_areas null=0
</source>

And then create rasters of developed/undeveloped areas using raster algebra:

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.mapcalc "urban_1992 = if(landuse_1992 >= 21 && landuse_1992 <= 24, 1, if(landuse_1992 == 11 || landuse_1992 >= 90 || protected_areas, null(), 0))"
r.mapcalc "urban_2001 = if(landuse_2001 >= 21 && landuse_2001 <= 24, 1, if(landuse_2001 == 11 || landuse_2001 >= 90 || protected_areas, null(), 0))"
r.mapcalc "urban_2011 = if(landuse_2011 >= 21 && landuse_2011 <= 24, 1, if(landuse_2011 == 11 || landuse_2011 >= 90 || protected_areas, null(), 0))"
</source>

We will convert vector counties to raster with the values of the FIPS attribute which links to population file:

<source lang="bash">
v.to.rast input=counties type=area use=attr attribute_column=FIPS output=counties
</source>

Before further steps, we will set our working directory so that the input population files and text files
we are going to create are saved in one directory and easily accessible.
You can do that from menu ''Settings'' → ''GRASS working environment'' → ''Change working directory''.
Select (or create) a directory and move there the downloaded files <tt>population_projection.csv</tt> and <tt>population_trend.csv</tt>.

== Potential submodel ==
Module {{AddonCmd|r.futures.potential}} implements POTENTIAL submodel as a part of FUTURES land change model. POTENTIAL is implemented using a set of coefficients that relate a selection of site suitability factors to the probability of a place becoming developed. This is implemented using the parameter table in combination with maps of those site suitability factors (mapped predictors). The coefficients are obtained by conducting multilevel logistic regression in R with package lme4 where the coefficients may vary by county. The best model is selected automatically using dredge function from package [https://cran.r-project.org/web/packages/MuMIn/index.html MuMIn].

First, we will derive couple of predictors.
=== Predictors ===
==== Slope ====
We will derive slope in degrees from digital elevation model using {{cmd|r.slope.aspect}} module:
<source lang="bash">r.slope.aspect elevation=elevation_30m slope=slope</source>

==== Distance from lakes/rivers ====
First we will extract [http://www.mrlc.gov/nlcd11_leg.php category ''Open Water''] from 2011 NLCD dataset:
<source lang="bash">
r.mapcalc "water = if(landuse_2011 == 11, 1, null())"
</source>

Then we compute the distance to water with module {{cmd|r.grow.distance}} and set color table to shades of blue:
<source lang="bash">
r.grow.distance input=water distance=dist_to_water
r.colors -n map=dist_to_water color=blues
</source>

==== Distance from protected areas ====
We will use raster protected of protected areas we already created, but we will set NULL values to zero.
We compute the distance to protected areas with module {{cmd|r.grow.distance}} and set color table from green to red:
<source lang="bash">
r.null map=protected_areas setnull=0
r.grow.distance input=protected_areas distance=dist_to_protected
r.colors map=dist_to_protected color=gyr
</source>

==== Forests ====
We will smooth the transition between forest and other land use, see NLCD [http://www.mrlc.gov/nlcd11_leg.php category ''Open Water'']:
<source lang="bash">
r.mapcalc "forest = if(landuse_2011 >= 41 && landuse_2011 <= 43, 1, 0)"
r.neighbors -c input=forest output=forest_smooth size=15 method=average
r.colors map=forest_smooth color=ndvi
</source>

==== Travel time to cities ====
Here we will compute travel time to cities (with population > 5000)
as cumulative cost distance where cost is defined as travel time on roads.
First we specify the speed on different types of roads.
We copy the roads raster into our mapset so that we can change it
by adding a new attribute field <tt>speed</tt>. Then we assign speed values (km/h) based on the type of road:

<source lang="bash">
g.copy vector=roads,myroads
v.db.addcolumn map=myroads columns="speed double precision"
v.db.update map=myroads column=speed value=50 where="MTFCC = 'S1400'"
v.db.update map=myroads column=speed value=100 where="MTFCC IN ('S1100', 'S1200')"
</source>

Now we rasterize the selected road types using the speed values from the attribute table as raster values.

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
v.to.rast input=myroads type=line where="MTFCC IN ('S1100', 'S1200', 'S1400')" output=roads_speed use=attr attribute_column=speed
</source>

We set the rest of the area to low speed and recompute the speed as time to travel through a 30m cell in minutes:

<source lang="bash">
r.null map=roads_speed null=5
r.mapcalc "roads_travel_time = 1.8 / roads_speed"
</source>

Finally we compute the travel time to larger cities using {{cmd|r.cost}}:

<source lang="bash">
r.cost input=roads_travel_time output=travel_time_cities start_points=cities
r.colors map=travel_time_cities color=byr
</source>

==== Road density ====
We will rasterize roads and use moving window analysis ({{cmd|r.neighbors}}) to compute road density:

<source lang="bash">
v.to.rast input=roads output=roads use=val type=line
r.null map=roads null=0
r.neighbors -c input=roads output=road_dens size=25 method=average
</source>

==== Distance to interchanges ====

We will consider TIGER roads of type <tt>Ramp</tt> as interchanges, rasterize them and compute euclidean distance to them:

<source lang="bash">
v.to.rast input=roads type=line where="MTFCC = 'S1630'" output=interchanges use=val
r.grow.distance -m input=interchanges distance=dist_interchanges
</source>

=== Development pressure ===

We compute development pressure with {{AddonCmd|r.futures.devpressure}}. Development pressure is a predictor based on number of neighboring developed cells within search distance, weighted by distance. The development pressure variable plays a special role in the model, allowing for a feedback between predicted change and change in subsequent steps.

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.devpressure -n input=urban_2011 output=devpressure_2 method=gravity size=7 gamma=2 scaling_factor=10
r.futures.devpressure -n input=urban_2011 output=devpressure_1 method=gravity size=10 gamma=1 scaling_factor=1
r.futures.devpressure -n input=urban_2011 output=devpressure_0_5 method=gravity size=30 gamma=0.5 scaling_factor=0.1
</source>

When gamma increases, development influence decreases more rapidly with distance.
Size is half the size of the moving window. When gamma is low, local development influences more distant places.
We will derive 3 layers with different gamma and size parameters for the potential statistical model.

=== Rescaling variables ===

First we will look at the ranges of our predictor variables by running a short Python code snippet in Python shell:

<source lang="python" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
for name in ['slope', 'dist_to_water', 'dist_to_protected', 'forest_smooth', 'travel_time_cities', 'road_dens', 'dist_interchanges', 'devpressure_0_5', 'devpressure_1']:
minmax = grass.raster_info(name)
print name, minmax['min'], minmax['max']
</source>

We will rescale some of our input variables:

<source lang="bash">
r.mapcalc "dist_to_water_km = dist_to_water / 1000"
r.mapcalc "dist_to_protected_km = dist_to_protected / 1000"
r.mapcalc "dist_interchanges_km = dist_interchanges / 1000"
r.mapcalc "road_dens_perc = road_dens * 100"
r.mapcalc "forest_smooth_perc = forest_smooth * 100"
</source>

=== Sampling ===
To sample only in the analyzed counties, we will clip development layer:

<source lang="bash">
r.mapcalc "urban_change_01_11 = if(urban_2011 == 1, if(urban_2001 == 0, 1, null()), 0)"
r.mapcalc "urban_change_clip = if(counties, urban_change_01_11)"
</source>

To estimate the number of sampling points, we can use {{cmd|r.report}} to report number of developed/undeveloped cells and their ratio.

<source lang="bash">
r.report map=urban_change_clip units=h,c,p
</source>

We will sample the predictors and the response variable with 5000 random points in undeveloped areas and 1000 points in developed area:

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.sample.category input=urban_change_clip output=sampling sampled=counties,devpressure_0_5,devpressure_1,devpressure_2,slope,road_dens_perc,forest_smooth_perc,dist_to_water_km,dist_to_protected_km,dist_interchanges_km,travel_time_cities npoints=5000,1000
</source>

The attribute table can be exported as CSV file (not necessary step):

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
v.db.select map=sampling columns=urban_change_clip,counties,devpressure_0_5,devpressure_1,slope,road_dens_perc,forest_smooth_perc,dist_to_water_km,dist_to_protected_km,dist_interchanges_km,travel_time_cities separator=comma file=samples.csv
</source>

=== Development potential ===
Now we find best model for predicting urbanization using {{AddonCmd|r.futures.potential}} which wraps an R script.

We can run R [http://www.inside-r.org/packages/cran/MuMIn/docs/dredge dredge] function to find "best" model. We can specify minimum and maximum number of predictors the final model should use.
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.potential -d input=sampling output=potential.csv columns=devpressure_1,slope,road_dens_perc,forest_smooth_perc,dist_to_water_km,dist_to_protected_km,dist_interchanges_km,travel_time_cities developed_column=urban_change_clip subregions_column=counties min_variables=4
</source>

Also, we can play with different combinations of predictors, for example:

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.potential input=sampling output=potential.csv columns=devpressure_2,road_dens_perc,slope,dist_interchanges_km,dist_to_water_km developed_column=urban_change_clip subregions_column=counties --o
r.futures.potential input=sampling output=potential.csv columns=devpressure_1,road_dens_perc,slope,dist_interchanges_km,dist_to_water_km developed_column=urban_change_clip subregions_column=counties --o
...
</source>

You can then open the output file <tt>potential.csv</tt>, which is a CSV file with tabs as separators.

For this tutorial, the final potential is created with:
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.potential input=sampling output=potential.csv columns=devpressure_2,road_dens_perc,slope,dist_interchanges_km,dist_to_water_km developed_column=urban_change_clip subregions_column=counties --o
</source>

We can now visualize the suitability surface using module {{AddonCmd|r.futures.potsurface}}. It creates initial development potential (suitability) raster from predictors and model coefficients and serves only for evaluating development potential model. The values of the resulting raster range from 0 to 1.

<source lang="bash">
r.futures.potsurface input=potential.csv subregions=counties output=suitability
r.colors map=suitability color=byr
</source>

== Demand submodel ==
First we will mask out roads so that they don't influence into per capita land demand relation.
<source lang="bash">
v.to.rast input=roads type=line output=roads_mask use=val
r.mask roads_mask -i
</source>

We will use {{AddonCmd|r.futures.demand}} which derives the population vs. development relation. The relation can be linear/logarithmic/logarithmic2/exponential/exponential approach.
Look for examples of the different relations in the manual.

* linear: y = A + Bx
* logarithmic: y = A + Bln(x)
* logarithmic2: y = A + B * ln(x - C)        (requires SciPy)
* exponential: y = Ae^(BX)
* exp_approach: y = (1 - e^(-A(x - B))) + C        (requires SciPy)

The format of the input population CSV files is described in the manual. It is important to have synchronized categories of subregions and the column headers of the CSV files (in our case FIPS number). How to simply generate the list of years (for which demand is computed) is described in {{AddonCmd|r.futures.demand}} manual, for example run this in Python console:

<source lang="python">
','.join([str(i) for i in range(2011, 2036)])
</source>

Then we can create the DEMAND file:
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.demand development=urban_1992,urban_2001,urban_2011 subregions=counties observed_population=population_trend.csv projected_population=population_projection.csv simulation_times=2011,2012,2013,2014,2015,2016,2017,2018,2019,2020,2021,2022,2023,2024,2025,2026,2027,2028,2029,2030,2031,2032,2033,2034,2035 plot=plot_demand.pdf demand=demand.csv separator=comma
</source>

In your current working directory, you should find files <tt>plot_demand.png</tt> and <tt>demand.csv</tt>.

If you have SciPy installed, you can experiment with other methods for fitting the functions:
<source lang="bash">
r.futures.demand ... method=logarithmic2
r.futures.demand ... method=exp_approach
</source>
If necessary, you can create a set of demand files produced by fitting each method separately and
then pick for each county the method which seems best and manually create a new demand file.

When you are finished, remove the mask as it is not needed for the next steps.
<source lang="bash">
r.mask -r
</source>

== Patch calibration ==
Patch calibration can be a very time consuming computation.
Therefore we select only one county (Buncombe):

<source lang="bash">
v.to.rast input=counties type=area where="FIPS == 37021" use=attr attribute_column=FIPS output=calib_county
g.region raster=calib_county zoom=calib_county
</source>
to derive patches of new development by comparing historical and latest development.
We can keep only patches with minimum size 2 cells (1800 = 2 x 30 x 30 m).

<source lang="bash">
r.futures.calib development_start=urban_1992 development_end=urban_2011 subregions=counties patch_sizes=patches.txt patch_threshold=1800 -l
</source>
We obtained a file <tt>patches.txt</tt> (used later in the PGA) - a patch size distribution file - containing sizes of all found patches.

We can look at the distribution of the patch sizes:

<source lang="python">
from matplotlib import pyplot as plt
with open('patches.txt') as f:
patches = [int(patch) for patch in f.readlines()]
plt.hist(patches, 2000)
plt.xlim(0,50)
plt.show()
</source>

At this point, we start the calibration to get best parameters of patch shape
(for this tutorial, this step can be skipped and the suggested parameters are used).

<source lang="bash"
style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.calib development_start=urban_1992 development_end=urban_2011 subregions=calib_county patch_sizes=patches.txt calibration_results=calib.csv patch_threshold=1800 repeat=5 compactness_mean=0.1,0.3,0.5,0.7,0.9 compactness_range=0.05 discount_factor=0.1,0.3,0.5,0.7,0.9 predictors=road_dens_perc,forest_smooth_perc,dist_to_protected_km demand=demand.csv devpot_params=potential.csv num_neighbors=4 seed_search=2 development_pressure=devpressure_0_5 development_pressure_approach=gravity n_dev_neighbourhood=30 gamma=0.5 scaling_factor=0.1
</source>

== FUTURES simulation ==
We will switch back to our previous region:
<source lang="bash">
g.region raster=landuse_2011 -p
</source>

Now we have all the inputs necessary for running {{AddonCmd|r.futures.pga}}:

The entire command is here:
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.pga subregions=counties developed=urban_2011 predictors=slope,forest_smooth_perc,dist_interchanges_km,travel_time_cities devpot_params=potential.csv development_pressure=devpressure_1 n_dev_neighbourhood=10 development_pressure_approach=gravity gamma=1 scaling_factor=1 demand=demand.csv discount_factor=0.3 compactness_mean=0.2 compactness_range=0.1 patch_sizes=patches.txt num_neighbors=4 seed_search=2 random_seed=1 output=final output_series=final
</source>

=== Quick description ===
The command parameters and their values:
* raster map of counties with their categories
<code>
... subregions=counties ...
</code>

* raster of developed (1), undeveloped (0) and NULLs for undevelopable areas
<code>
... developed=urban_2011 ...
</code>

* predictors selected with {{AddonCmd|r.futures.potential}} and their coefficients in a <tt>potential.csv</tt> file. The order of predictors must match the order in the file and the categories of the counties must match raster <tt>counties</tt>.
<code>
... predictors=slope,forest_smooth_perc,dist_interchanges_km,travel_time_cities devpot_params=potential.csv ...
</code>

* initial development pressure computed by {{AddonCmd|r.futures.devpressure}}, it's important to set here the same parameters
<code>
... development_pressure=devpressure_1 n_dev_neighbourhood=10 development_pressure_approach=gravity gamma=1 scaling_factor=1 ...
</code>

* per capita land demand computed by {{AddonCmd|r.futures.demand}}, the categories of the counties must match raster <tt>counties</tt>.
<code>
... demand=demand.csv ...
</code>

* patch parameters from the calibration step
<code>
... discount_factor=0.3 compactness_mean=0.4 compactness_range=0.08 patch_sizes=patches.txt ...
</code>

* recommended parameters for patch growing algorithm
<code>
... num_neighbors=4 seed_search=2 ...
</code>

* set random seed for repeatable results or set flag <tt>-s</tt> to generate seed automatically
<code>
... random_seed=1 ...
</code>

* specify final output map and optionally basename for intermediate raster maps
<code>
output=final output_series=final
</code>

== Scenarios ==
Scenarios involving policies that encourage infill versus sprawl can be explored using the <tt>incentive_power</tt> parameter of {{AddonCmd|r.futures.pga}},
which uses a power function to transform the evenness of the probability gradient in POTENTIAL. You can change the power to a number between 0.25 and 4 to test urban sprawl/infill scenarios.
Higher power leads to infill behavior, lower power to urban sprawl.

== Postprocessing ==

Follow a [[Creating_animation_from_FUTURES_output_in_GRASS_GIS| tutorial how to make an animation from the results]].

= GRASS GIS Python API =

[[Category: Tutorial]]
[[Category: FUTURES]]
[[Category: Urban]]

Workshop on urban growth modeling with FUTURES

2016-03-22T19:10:02Z

⚠️Dbvanber: /* GRASS functionality */

{{ToModify}}
= Workshop introduction =
r.futures.* is an implementation of the '''FUT'''ure '''U'''rban-'''R'''egional '''E'''nvironment '''S'''imulation (FUTURES)[1] which is a model for multilevel simulations of emerging urban-rural landscape structure. FUTURES produces regional projections of landscape patterns using coupled submodels that integrate nonstationary drivers of land change: per capita demand (DEMAND submodel), site suitability (POTENTIAL submodel), and the spatial structure of conversion events (PGA submodel).

[1] Meentemeyer, R. K., Tang, W., Dorning, M. A., Vogler, J. B., Cunniffe, N. J., & Shoemaker, D. A. (2013). [http://www.tandfonline.com/doi/abs/10.1080/00045608.2012.707591 FUTURES: multilevel simulations of emerging urban-rural landscape structure using a stochastic patch-growing algorithm.] Annals of the Association of American Geographers, 103(4), 785-807

== Software ==
There are a number of software requirements to run FUTURES that will need to be download and installed. Required software includes:
* GRASS GIS 7
* addons
** {{AddonCmd|r.futures.pga}}
** {{AddonCmd|r.futures.potential}}
** {{AddonCmd|r.futures.potsurface}}
** {{AddonCmd|r.futures.demand}}
** {{AddonCmd|r.futures.devpressure}}
** {{AddonCmd|r.sample.category}}
* R (≥ 3.0.2) - needed for {{AddonCmd|r.futures.potential}} with packages:
**MuMIn, lme4, optparse, rgrass7
* SciPy - useful for {{AddonCmd|r.futures.demand}}

=== Installation ===
We use the R statistical software for our calculation of site suitability (i.e. development potential) in FUTURES. R is a free software environment for statistical computing and graphics. If you don't have R, or you have older an version, please download and install the software from [http://archive.linux.duke.edu/cran/ install R] and be sure to additionally add these required packages:
<pre>
install.packages(c("MuMIn", "lme4", "optparse", "rgrass7"))
</pre>

==== MS Windows ====
We will be using GRASS GIS 7.0.3 that can be found here in the [https://trac.osgeo.org/osgeo4w/ OSGeo4W] package manager.
Please install the latest stable GRASS GIS 7 version and the SciPy Python package using the ''Advanced install'' option.
A guide with step by step screen shot instructions is available [https://docs.google.com/presentation/d/1yEGpriBne7RvjB35HI6GecNwO1P1y2nRGqDThqoNnCE/edit?usp=sharing here].

In order for GRASS to be able to find R executables, GRASS must be on the PATH variable. Follow this [solution] to make R accessible from GRASS permanently.
A simple but temporary solution is to open GRASS GIS and paste this in the black terminal:
<pre>
set PATH=%PATH%;C:\Program Files\R\R-3.0.2\bin
</pre>
This has to be repeated after restarting GRASS session.

==== Ubuntu Linux ====
Install GRASS GIS from packages:
<pre>
sudo add-apt-repository ppa:ubuntugis/ubuntugis-unstable
sudo apt-get update
sudo apt-get install grass
</pre>

== Workshop data ==
The data that we will be using for the workshop can be download here: [http://fatra.cnr.ncsu.edu/futures/futures_ncspm_Asheville.zip sample dataset]. Please place these layers in your local GRASS directory:
* digital elevation model ([http://nationalmap.gov/elevation.html NED])
* [http://www.mrlc.gov/ NLCD] 2001, 2011
* NLCD 1992/2001 Retrofit Land Cover Change Product
* transportation network ([http://www.census.gov/geo/maps-data/data/tiger-line.html TIGER])
* county boundaries ([http://www.census.gov/geo/maps-data/data/tiger-line.html TIGER])
* protected areas ([http://www.conservationgateway.org/ConservationByGeography/NorthAmerica/UnitedStates/edc/reportsdata/terrestrial/secured/Pages/default.aspx Secured Lands])
* cities as points (USGS)

In addition, download [http://fatra.cnr.ncsu.edu/futures/futures_Asheville_files.zip population information as text files]:
* county population past estimates and future projections ([https://www.osbm.nc.gov/demog/county-projections NC OSBM]) per county (nonspatial)

= GRASS GIS introduction =
There are many advantages to using the open source GRASS GIS platform, but for many that are more familiar with ARCGis and QGis, the setup and implementation of spatial tools in GRASS can be confusing. Here we provide an overview of the GRASS GIS project: [https://grass.osgeo.org grass.osgeo.org] that might be helpful to review if you are a first time users. For this exercise it's not necessary to have a full understanding of how to use GRASS. However, you will need to know how to place your data in the correct GRASS database directory, as well as some basic GRASS functionality. Step by step instructions are provided below
== Setting up GRASS for the tutorial ==
GRASS uses unique database terminology and structure ([https://grass.osgeo.org/grass71/manuals/grass_database.html GRASS database]) that are important to understand for the set up of this tutorial, as you will need to place the required data (e.g. Mapset) in a specific GRASS database Location. In the following we review important terminology and give step by step direction on how to download and place you data in the correct location.

=== Important GRASS directory terminology ===
* A '''GRASS database''' consist of directory with specific Locations (projects) where data layer are stored
* '''Location''' hold all Mapsets in a specific directoy that have the same spatial projection (spatial reference system)
* '''Mapset''' are a collection of maps with the same spatial projection

=== Creating a GRASS database for the tutorial ===
You need to create a GRASS database with the Mapset that we will use for the tutorial before we can run the FUTURES model. Please Download the [http://fatra.cnr.ncsu.edu/futures/futures_ncspm_Asheville.zip workshop location], noting where the files are located on your local directory. Now, create (unless you already have it) a directory named <tt>grassdata</tt> (GRASS database) in your home folder (or Documents), unzip the downloaded data into this directory. You should now have a Location <tt>futures_ncspm</tt> in <tt>grassdata</tt>.

<center><gallery perrow=1 widths=500 heights=250>Image:GRASS FUTURES startup.png|GRASS GIS 7.0.3 startup dialog with downloaded Location and Mapsets for FUTURES workshop</gallery></center>

=== Launching and exploring data in GRASS ===
Now that we have the data in the correct GRASS database, we can launch the Graphical User Interface (GUI). The GUI interface allows you to display raster, vector data as well as navigate through zooming in and out. Advanced exploration and visualization, like many popular GIS software, is also possible in GRASS (e.g. queries, adding legend). The print screens below depicts how you can add different map layers (left) and display the metadata of your data layers.

<center><gallery perrow=2 widths=500 heights=250>Image:GRASS FUTURES wxGUI display.png|Layer Manager and Map Display overview. Annotations show how to add raster layer, query, add legend.
Image:wxGUI_metadata_rinfo.png|Show raster map metadata by right click on layer</gallery></center>

== GRASS functionality ==
One of the advantage of GRASS is diverse number of module addons that let you analyze all manner of spatial and temporal. Because it is open source modules are added daily increasing functionality and methods for analysis of your data. GRASS GIS has over [https://grass.osgeo.org/grass70/manuals/full_index.html 500 different modules] in the core distribution and over [https://grass.osgeo.org/grass70/manuals/addons/ 230 addon modules]
<center>
{| class="wikitable"
|-
! Prefix !! Function !! Example
|-
| r.* || raster processing || ''{{cmd|r.mapcalc}}'': map algebra
|-
| v.* || vector processing || ''{{cmd|v.clean}}'': topological cleaning
|-
| i.* || imagery processing || ''{{cmd|i.segment}}'': object recognition
|-
| db.* || database management || ''{{cmd|db.select}}'': select values from table
|-
| r3.* || 3D raster processing || ''{{cmd|r3.stats}}'': 3D raster statistics
|-
| t.* || temporal data processing || ''{{cmd|t.rast.aggregate}}'': temporal aggregation
|-
| g.* || general data management || ''{{cmd|g.rename}}'': renames map
|-
| d.* || display ||''{{cmd|d.rast}}'': display raster map
|}</center>

=== Command line vs. GUI interface===
* GRASS modules have GUI and command line interface. In this workshop we use commands to describe the workflow, but we can use both GUI and command line depending on personal preference. Look how {{cmd|wxGUI.modules|version=71|desc=GUI and command line interface}} represent the same tool. ''Task:'' compute aspect (orientation) from provided digital elevation model using module {{cmd|r.slope.aspect}} using both module dialog and command line.
* How to find modules? Modules are organized by their functionality in wxGUI menu, or we can search for them in Search modules tab. If we already know which module to use, we can just type it in the wxGUI command console. <center><gallery perrow=3 widths=380 heights=190>Image:wxGUI_menu_rinfo.png|Modules can be found in wxGUI menu
Image:wxGUI_module_search.png|You can search modules by name, description or keywords in ''Search modules'' tab
Image:wxGUI_console_completion.png|By typing prefix r. we make a list of modules starting with that prefix to show up.</gallery></center>


* {{cmd|g.region|desc=Computational region}} - an important raster concept
** defined by region extent and raster resolution
** applies to all raster operations
** persists between GRASS session, can be different for different mapsets
** advantages: keeps your results consistent, avoid clipping, for computationally demanding tasks set region to smaller extent, check your result is good and then set the computational region to the entire study area and rerun analysis
** run <code>g.region -p</code> or in menu ''Settings'' - ''Region'' - ''Display region'' to see current region settings
[[File:WxGUI set region.png|700px|thumb|center|Simple ways to set computational region from GUI. On the left, set region to match raster map. On the right, select the highlighted option and then set region by drawing rectangle.]]

* GRASS 3D view

= Modeling with FUTURES =
== Initial steps and data preparation ==
First we will set the computational region of our analyses to an extent covering our study area and aligned with our base landuse rasters:
<source lang="bash">g.region raster=landuse_2011 -p</source>

We will derive urbanized areas from NLCD dataset for year 1992, 2001 and 2011
by extracting categories category 21 - 24 into a new binary map where developed is 1,
undeveloped 0 and NULL (no data) is area unsuitable for development (water, wetlands, protected areas).
First we will convert protected areas from vector to raster. We set
NULLs to zeros (for simpler raster algebra expression in the next step) using {{cmd|r.null}}:

<source lang="bash">
v.to.rast input=protected_areas output=protected_areas use=val
r.null map=protected_areas null=0
</source>

And then create rasters of developed/undeveloped areas using raster algebra:

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.mapcalc "urban_1992 = if(landuse_1992 >= 21 && landuse_1992 <= 24, 1, if(landuse_1992 == 11 || landuse_1992 >= 90 || protected_areas, null(), 0))"
r.mapcalc "urban_2001 = if(landuse_2001 >= 21 && landuse_2001 <= 24, 1, if(landuse_2001 == 11 || landuse_2001 >= 90 || protected_areas, null(), 0))"
r.mapcalc "urban_2011 = if(landuse_2011 >= 21 && landuse_2011 <= 24, 1, if(landuse_2011 == 11 || landuse_2011 >= 90 || protected_areas, null(), 0))"
</source>

We will convert vector counties to raster with the values of the FIPS attribute which links to population file:

<source lang="bash">
v.to.rast input=counties type=area use=attr attribute_column=FIPS output=counties
</source>

Before further steps, we will set our working directory so that the input population files and text files
we are going to create are saved in one directory and easily accessible.
You can do that from menu ''Settings'' → ''GRASS working environment'' → ''Change working directory''.
Select (or create) a directory and move there the downloaded files <tt>population_projection.csv</tt> and <tt>population_trend.csv</tt>.

== Potential submodel ==
Module {{AddonCmd|r.futures.potential}} implements POTENTIAL submodel as a part of FUTURES land change model. POTENTIAL is implemented using a set of coefficients that relate a selection of site suitability factors to the probability of a place becoming developed. This is implemented using the parameter table in combination with maps of those site suitability factors (mapped predictors). The coefficients are obtained by conducting multilevel logistic regression in R with package lme4 where the coefficients may vary by county. The best model is selected automatically using dredge function from package [https://cran.r-project.org/web/packages/MuMIn/index.html MuMIn].

First, we will derive couple of predictors.
=== Predictors ===
==== Slope ====
We will derive slope in degrees from digital elevation model using {{cmd|r.slope.aspect}} module:
<source lang="bash">r.slope.aspect elevation=elevation_30m slope=slope</source>

==== Distance from lakes/rivers ====
First we will extract [http://www.mrlc.gov/nlcd11_leg.php category ''Open Water''] from 2011 NLCD dataset:
<source lang="bash">
r.mapcalc "water = if(landuse_2011 == 11, 1, null())"
</source>

Then we compute the distance to water with module {{cmd|r.grow.distance}} and set color table to shades of blue:
<source lang="bash">
r.grow.distance input=water distance=dist_to_water
r.colors -n map=dist_to_water color=blues
</source>

==== Distance from protected areas ====
We will use raster protected of protected areas we already created, but we will set NULL values to zero.
We compute the distance to protected areas with module {{cmd|r.grow.distance}} and set color table from green to red:
<source lang="bash">
r.null map=protected_areas setnull=0
r.grow.distance input=protected_areas distance=dist_to_protected
r.colors map=dist_to_protected color=gyr
</source>

==== Forests ====
We will smooth the transition between forest and other land use, see NLCD [http://www.mrlc.gov/nlcd11_leg.php category ''Open Water'']:
<source lang="bash">
r.mapcalc "forest = if(landuse_2011 >= 41 && landuse_2011 <= 43, 1, 0)"
r.neighbors -c input=forest output=forest_smooth size=15 method=average
r.colors map=forest_smooth color=ndvi
</source>

==== Travel time to cities ====
Here we will compute travel time to cities (with population > 5000)
as cumulative cost distance where cost is defined as travel time on roads.
First we specify the speed on different types of roads.
We copy the roads raster into our mapset so that we can change it
by adding a new attribute field <tt>speed</tt>. Then we assign speed values (km/h) based on the type of road:

<source lang="bash">
g.copy vector=roads,myroads
v.db.addcolumn map=myroads columns="speed double precision"
v.db.update map=myroads column=speed value=50 where="MTFCC = 'S1400'"
v.db.update map=myroads column=speed value=100 where="MTFCC IN ('S1100', 'S1200')"
</source>

Now we rasterize the selected road types using the speed values from the attribute table as raster values.

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
v.to.rast input=myroads type=line where="MTFCC IN ('S1100', 'S1200', 'S1400')" output=roads_speed use=attr attribute_column=speed
</source>

We set the rest of the area to low speed and recompute the speed as time to travel through a 30m cell in minutes:

<source lang="bash">
r.null map=roads_speed null=5
r.mapcalc "roads_travel_time = 1.8 / roads_speed"
</source>

Finally we compute the travel time to larger cities using {{cmd|r.cost}}:

<source lang="bash">
r.cost input=roads_travel_time output=travel_time_cities start_points=cities
r.colors map=travel_time_cities color=byr
</source>

==== Road density ====
We will rasterize roads and use moving window analysis ({{cmd|r.neighbors}}) to compute road density:

<source lang="bash">
v.to.rast input=roads output=roads use=val type=line
r.null map=roads null=0
r.neighbors -c input=roads output=road_dens size=25 method=average
</source>

==== Distance to interchanges ====

We will consider TIGER roads of type <tt>Ramp</tt> as interchanges, rasterize them and compute euclidean distance to them:

<source lang="bash">
v.to.rast input=roads type=line where="MTFCC = 'S1630'" output=interchanges use=val
r.grow.distance -m input=interchanges distance=dist_interchanges
</source>

=== Development pressure ===

We compute development pressure with {{AddonCmd|r.futures.devpressure}}. Development pressure is a predictor based on number of neighboring developed cells within search distance, weighted by distance. The development pressure variable plays a special role in the model, allowing for a feedback between predicted change and change in subsequent steps.

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.devpressure -n input=urban_2011 output=devpressure_2 method=gravity size=7 gamma=2 scaling_factor=10
r.futures.devpressure -n input=urban_2011 output=devpressure_1 method=gravity size=10 gamma=1 scaling_factor=1
r.futures.devpressure -n input=urban_2011 output=devpressure_0_5 method=gravity size=30 gamma=0.5 scaling_factor=0.1
</source>

When gamma increases, development influence decreases more rapidly with distance.
Size is half the size of the moving window. When gamma is low, local development influences more distant places.
We will derive 3 layers with different gamma and size parameters for the potential statistical model.

=== Rescaling variables ===

First we will look at the ranges of our predictor variables by running a short Python code snippet in Python shell:

<source lang="python" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
for name in ['slope', 'dist_to_water', 'dist_to_protected', 'forest_smooth', 'travel_time_cities', 'road_dens', 'dist_interchanges', 'devpressure_0_5', 'devpressure_1']:
minmax = grass.raster_info(name)
print name, minmax['min'], minmax['max']
</source>

We will rescale some of our input variables:

<source lang="bash">
r.mapcalc "dist_to_water_km = dist_to_water / 1000"
r.mapcalc "dist_to_protected_km = dist_to_protected / 1000"
r.mapcalc "dist_interchanges_km = dist_interchanges / 1000"
r.mapcalc "road_dens_perc = road_dens * 100"
r.mapcalc "forest_smooth_perc = forest_smooth * 100"
</source>

=== Sampling ===
To sample only in the analyzed counties, we will clip development layer:

<source lang="bash">
r.mapcalc "urban_change_01_11 = if(urban_2011 == 1, if(urban_2001 == 0, 1, null()), 0)"
r.mapcalc "urban_change_clip = if(counties, urban_change_01_11)"
</source>

To estimate the number of sampling points, we can use {{cmd|r.report}} to report number of developed/undeveloped cells and their ratio.

<source lang="bash">
r.report map=urban_change_clip units=h,c,p
</source>

We will sample the predictors and the response variable with 5000 random points in undeveloped areas and 1000 points in developed area:

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.sample.category input=urban_change_clip output=sampling sampled=counties,devpressure_0_5,devpressure_1,devpressure_2,slope,road_dens_perc,forest_smooth_perc,dist_to_water_km,dist_to_protected_km,dist_interchanges_km,travel_time_cities npoints=5000,1000
</source>

The attribute table can be exported as CSV file (not necessary step):

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
v.db.select map=sampling columns=urban_change_clip,counties,devpressure_0_5,devpressure_1,slope,road_dens_perc,forest_smooth_perc,dist_to_water_km,dist_to_protected_km,dist_interchanges_km,travel_time_cities separator=comma file=samples.csv
</source>

=== Development potential ===
Now we find best model for predicting urbanization using {{AddonCmd|r.futures.potential}} which wraps an R script.

We can run R [http://www.inside-r.org/packages/cran/MuMIn/docs/dredge dredge] function to find "best" model. We can specify minimum and maximum number of predictors the final model should use.
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.potential -d input=sampling output=potential.csv columns=devpressure_1,slope,road_dens_perc,forest_smooth_perc,dist_to_water_km,dist_to_protected_km,dist_interchanges_km,travel_time_cities developed_column=urban_change_clip subregions_column=counties min_variables=4
</source>

Also, we can play with different combinations of predictors, for example:

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.potential input=sampling output=potential.csv columns=devpressure_2,road_dens_perc,slope,dist_interchanges_km,dist_to_water_km developed_column=urban_change_clip subregions_column=counties --o
r.futures.potential input=sampling output=potential.csv columns=devpressure_1,road_dens_perc,slope,dist_interchanges_km,dist_to_water_km developed_column=urban_change_clip subregions_column=counties --o
...
</source>

You can then open the output file <tt>potential.csv</tt>, which is a CSV file with tabs as separators.

For this tutorial, the final potential is created with:
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.potential input=sampling output=potential.csv columns=devpressure_2,road_dens_perc,slope,dist_interchanges_km,dist_to_water_km developed_column=urban_change_clip subregions_column=counties --o
</source>

We can now visualize the suitability surface using module {{AddonCmd|r.futures.potsurface}}. It creates initial development potential (suitability) raster from predictors and model coefficients and serves only for evaluating development potential model. The values of the resulting raster range from 0 to 1.

<source lang="bash">
r.futures.potsurface input=potential.csv subregions=counties output=suitability
r.colors map=suitability color=byr
</source>

== Demand submodel ==
First we will mask out roads so that they don't influence into per capita land demand relation.
<source lang="bash">
v.to.rast input=roads type=line output=roads_mask use=val
r.mask roads_mask -i
</source>

We will use {{AddonCmd|r.futures.demand}} which derives the population vs. development relation. The relation can be linear/logarithmic/logarithmic2/exponential/exponential approach.
Look for examples of the different relations in the manual.

* linear: y = A + Bx
* logarithmic: y = A + Bln(x)
* logarithmic2: y = A + B * ln(x - C)        (requires SciPy)
* exponential: y = Ae^(BX)
* exp_approach: y = (1 - e^(-A(x - B))) + C        (requires SciPy)

The format of the input population CSV files is described in the manual. It is important to have synchronized categories of subregions and the column headers of the CSV files (in our case FIPS number). How to simply generate the list of years (for which demand is computed) is described in {{AddonCmd|r.futures.demand}} manual, for example run this in Python console:

<source lang="python">
','.join([str(i) for i in range(2011, 2036)])
</source>

Then we can create the DEMAND file:
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.demand development=urban_1992,urban_2001,urban_2011 subregions=counties observed_population=population_trend.csv projected_population=population_projection.csv simulation_times=2011,2012,2013,2014,2015,2016,2017,2018,2019,2020,2021,2022,2023,2024,2025,2026,2027,2028,2029,2030,2031,2032,2033,2034,2035 plot=plot_demand.pdf demand=demand.csv separator=comma
</source>

In your current working directory, you should find files <tt>plot_demand.png</tt> and <tt>demand.csv</tt>.

If you have SciPy installed, you can experiment with other methods for fitting the functions:
<source lang="bash">
r.futures.demand ... method=logarithmic2
r.futures.demand ... method=exp_approach
</source>
If necessary, you can create a set of demand files produced by fitting each method separately and
then pick for each county the method which seems best and manually create a new demand file.

When you are finished, remove the mask as it is not needed for the next steps.
<source lang="bash">
r.mask -r
</source>

== Patch calibration ==
Patch calibration can be a very time consuming computation.
Therefore we select only one county (Buncombe):

<source lang="bash">
v.to.rast input=counties type=area where="FIPS == 37021" use=attr attribute_column=FIPS output=calib_county
g.region raster=calib_county zoom=calib_county
</source>
to derive patches of new development by comparing historical and latest development.
We can keep only patches with minimum size 2 cells (1800 = 2 x 30 x 30 m).

<source lang="bash">
r.futures.calib development_start=urban_1992 development_end=urban_2011 subregions=counties patch_sizes=patches.txt patch_threshold=1800 -l
</source>
We obtained a file <tt>patches.txt</tt> (used later in the PGA) - a patch size distribution file - containing sizes of all found patches.

We can look at the distribution of the patch sizes:

<source lang="python">
from matplotlib import pyplot as plt
with open('patches.txt') as f:
patches = [int(patch) for patch in f.readlines()]
plt.hist(patches, 2000)
plt.xlim(0,50)
plt.show()
</source>

At this point, we start the calibration to get best parameters of patch shape
(for this tutorial, this step can be skipped and the suggested parameters are used).

<source lang="bash"
style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.calib development_start=urban_1992 development_end=urban_2011 subregions=calib_county patch_sizes=patches.txt calibration_results=calib.csv patch_threshold=1800 repeat=5 compactness_mean=0.1,0.3,0.5,0.7,0.9 compactness_range=0.05 discount_factor=0.1,0.3,0.5,0.7,0.9 predictors=road_dens_perc,forest_smooth_perc,dist_to_protected_km demand=demand.csv devpot_params=potential.csv num_neighbors=4 seed_search=2 development_pressure=devpressure_0_5 development_pressure_approach=gravity n_dev_neighbourhood=30 gamma=0.5 scaling_factor=0.1
</source>

== FUTURES simulation ==
We will switch back to our previous region:
<source lang="bash">
g.region raster=landuse_2011 -p
</source>

Now we have all the inputs necessary for running {{AddonCmd|r.futures.pga}}:

The entire command is here:
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.pga subregions=counties developed=urban_2011 predictors=slope,forest_smooth_perc,dist_interchanges_km,travel_time_cities devpot_params=potential.csv development_pressure=devpressure_1 n_dev_neighbourhood=10 development_pressure_approach=gravity gamma=1 scaling_factor=1 demand=demand.csv discount_factor=0.3 compactness_mean=0.2 compactness_range=0.1 patch_sizes=patches.txt num_neighbors=4 seed_search=2 random_seed=1 output=final output_series=final
</source>

=== Quick description ===
The command parameters and their values:
* raster map of counties with their categories
<code>
... subregions=counties ...
</code>

* raster of developed (1), undeveloped (0) and NULLs for undevelopable areas
<code>
... developed=urban_2011 ...
</code>

* predictors selected with {{AddonCmd|r.futures.potential}} and their coefficients in a <tt>potential.csv</tt> file. The order of predictors must match the order in the file and the categories of the counties must match raster <tt>counties</tt>.
<code>
... predictors=slope,forest_smooth_perc,dist_interchanges_km,travel_time_cities devpot_params=potential.csv ...
</code>

* initial development pressure computed by {{AddonCmd|r.futures.devpressure}}, it's important to set here the same parameters
<code>
... development_pressure=devpressure_1 n_dev_neighbourhood=10 development_pressure_approach=gravity gamma=1 scaling_factor=1 ...
</code>

* per capita land demand computed by {{AddonCmd|r.futures.demand}}, the categories of the counties must match raster <tt>counties</tt>.
<code>
... demand=demand.csv ...
</code>

* patch parameters from the calibration step
<code>
... discount_factor=0.3 compactness_mean=0.4 compactness_range=0.08 patch_sizes=patches.txt ...
</code>

* recommended parameters for patch growing algorithm
<code>
... num_neighbors=4 seed_search=2 ...
</code>

* set random seed for repeatable results or set flag <tt>-s</tt> to generate seed automatically
<code>
... random_seed=1 ...
</code>

* specify final output map and optionally basename for intermediate raster maps
<code>
output=final output_series=final
</code>

== Scenarios ==
Scenarios involving policies that encourage infill versus sprawl can be explored using the <tt>incentive_power</tt> parameter of {{AddonCmd|r.futures.pga}},
which uses a power function to transform the evenness of the probability gradient in POTENTIAL. You can change the power to a number between 0.25 and 4 to test urban sprawl/infill scenarios.
Higher power leads to infill behavior, lower power to urban sprawl.

== Postprocessing ==

Follow a [[Creating_animation_from_FUTURES_output_in_GRASS_GIS| tutorial how to make an animation from the results]].

= GRASS GIS Python API =

[[Category: Tutorial]]
[[Category: FUTURES]]
[[Category: Urban]]

Workshop on urban growth modeling with FUTURES

2016-03-22T19:04:29Z

⚠️Dbvanber: /* Launching and exploring data in GRASS */

{{ToModify}}
= Workshop introduction =
r.futures.* is an implementation of the '''FUT'''ure '''U'''rban-'''R'''egional '''E'''nvironment '''S'''imulation (FUTURES)[1] which is a model for multilevel simulations of emerging urban-rural landscape structure. FUTURES produces regional projections of landscape patterns using coupled submodels that integrate nonstationary drivers of land change: per capita demand (DEMAND submodel), site suitability (POTENTIAL submodel), and the spatial structure of conversion events (PGA submodel).

[1] Meentemeyer, R. K., Tang, W., Dorning, M. A., Vogler, J. B., Cunniffe, N. J., & Shoemaker, D. A. (2013). [http://www.tandfonline.com/doi/abs/10.1080/00045608.2012.707591 FUTURES: multilevel simulations of emerging urban-rural landscape structure using a stochastic patch-growing algorithm.] Annals of the Association of American Geographers, 103(4), 785-807

== Software ==
There are a number of software requirements to run FUTURES that will need to be download and installed. Required software includes:
* GRASS GIS 7
* addons
** {{AddonCmd|r.futures.pga}}
** {{AddonCmd|r.futures.potential}}
** {{AddonCmd|r.futures.potsurface}}
** {{AddonCmd|r.futures.demand}}
** {{AddonCmd|r.futures.devpressure}}
** {{AddonCmd|r.sample.category}}
* R (≥ 3.0.2) - needed for {{AddonCmd|r.futures.potential}} with packages:
**MuMIn, lme4, optparse, rgrass7
* SciPy - useful for {{AddonCmd|r.futures.demand}}

=== Installation ===
We use the R statistical software for our calculation of site suitability (i.e. development potential) in FUTURES. R is a free software environment for statistical computing and graphics. If you don't have R, or you have older an version, please download and install the software from [http://archive.linux.duke.edu/cran/ install R] and be sure to additionally add these required packages:
<pre>
install.packages(c("MuMIn", "lme4", "optparse", "rgrass7"))
</pre>

==== MS Windows ====
We will be using GRASS GIS 7.0.3 that can be found here in the [https://trac.osgeo.org/osgeo4w/ OSGeo4W] package manager.
Please install the latest stable GRASS GIS 7 version and the SciPy Python package using the ''Advanced install'' option.
A guide with step by step screen shot instructions is available [https://docs.google.com/presentation/d/1yEGpriBne7RvjB35HI6GecNwO1P1y2nRGqDThqoNnCE/edit?usp=sharing here].

In order for GRASS to be able to find R executables, GRASS must be on the PATH variable. Follow this [solution] to make R accessible from GRASS permanently.
A simple but temporary solution is to open GRASS GIS and paste this in the black terminal:
<pre>
set PATH=%PATH%;C:\Program Files\R\R-3.0.2\bin
</pre>
This has to be repeated after restarting GRASS session.

==== Ubuntu Linux ====
Install GRASS GIS from packages:
<pre>
sudo add-apt-repository ppa:ubuntugis/ubuntugis-unstable
sudo apt-get update
sudo apt-get install grass
</pre>

== Workshop data ==
The data that we will be using for the workshop can be download here: [http://fatra.cnr.ncsu.edu/futures/futures_ncspm_Asheville.zip sample dataset]. Please place these layers in your local GRASS directory:
* digital elevation model ([http://nationalmap.gov/elevation.html NED])
* [http://www.mrlc.gov/ NLCD] 2001, 2011
* NLCD 1992/2001 Retrofit Land Cover Change Product
* transportation network ([http://www.census.gov/geo/maps-data/data/tiger-line.html TIGER])
* county boundaries ([http://www.census.gov/geo/maps-data/data/tiger-line.html TIGER])
* protected areas ([http://www.conservationgateway.org/ConservationByGeography/NorthAmerica/UnitedStates/edc/reportsdata/terrestrial/secured/Pages/default.aspx Secured Lands])
* cities as points (USGS)

In addition, download [http://fatra.cnr.ncsu.edu/futures/futures_Asheville_files.zip population information as text files]:
* county population past estimates and future projections ([https://www.osbm.nc.gov/demog/county-projections NC OSBM]) per county (nonspatial)

= GRASS GIS introduction =
There are many advantages to using the open source GRASS GIS platform, but for many that are more familiar with ARCGis and QGis, the setup and implementation of spatial tools in GRASS can be confusing. Here we provide an overview of the GRASS GIS project: [https://grass.osgeo.org grass.osgeo.org] that might be helpful to review if you are a first time users. For this exercise it's not necessary to have a full understanding of how to use GRASS. However, you will need to know how to place your data in the correct GRASS database directory, as well as some basic GRASS functionality. Step by step instructions are provided below
== Setting up GRASS for the tutorial ==
GRASS uses unique database terminology and structure ([https://grass.osgeo.org/grass71/manuals/grass_database.html GRASS database]) that are important to understand for the set up of this tutorial, as you will need to place the required data (e.g. Mapset) in a specific GRASS database Location. In the following we review important terminology and give step by step direction on how to download and place you data in the correct location.

=== Important GRASS directory terminology ===
* A '''GRASS database''' consist of directory with specific Locations (projects) where data layer are stored
* '''Location''' hold all Mapsets in a specific directoy that have the same spatial projection (spatial reference system)
* '''Mapset''' are a collection of maps with the same spatial projection

=== Creating a GRASS database for the tutorial ===
You need to create a GRASS database with the Mapset that we will use for the tutorial before we can run the FUTURES model. Please Download the [http://fatra.cnr.ncsu.edu/futures/futures_ncspm_Asheville.zip workshop location], noting where the files are located on your local directory. Now, create (unless you already have it) a directory named <tt>grassdata</tt> (GRASS database) in your home folder (or Documents), unzip the downloaded data into this directory. You should now have a Location <tt>futures_ncspm</tt> in <tt>grassdata</tt>.

<center><gallery perrow=1 widths=500 heights=250>Image:GRASS FUTURES startup.png|GRASS GIS 7.0.3 startup dialog with downloaded Location and Mapsets for FUTURES workshop</gallery></center>

=== Launching and exploring data in GRASS ===
Now that we have the data in the correct GRASS database, we can launch the Graphical User Interface (GUI). The GUI interface allows you to display raster, vector data as well as navigate through zooming in and out. Advanced exploration and visualization, like many popular GIS software, is also possible in GRASS (e.g. queries, adding legend). The print screens below depicts how you can add different map layers (left) and display the metadata of your data layers.

<center><gallery perrow=2 widths=500 heights=250>Image:GRASS FUTURES wxGUI display.png|Layer Manager and Map Display overview. Annotations show how to add raster layer, query, add legend.
Image:wxGUI_metadata_rinfo.png|Show raster map metadata by right click on layer</gallery></center>

== GRASS functionality ==

* GRASS GIS has over [https://grass.osgeo.org/grass70/manuals/full_index.html 500 different modules] in the core distribution and over [https://grass.osgeo.org/grass70/manuals/addons/ 230 addon modules]
<center>
{| class="wikitable"
|-
! Prefix !! Function !! Example
|-
| r.* || raster processing || ''{{cmd|r.mapcalc}}'': map algebra
|-
| v.* || vector processing || ''{{cmd|v.clean}}'': topological cleaning
|-
| i.* || imagery processing || ''{{cmd|i.segment}}'': object recognition
|-
| db.* || database management || ''{{cmd|db.select}}'': select values from table
|-
| r3.* || 3D raster processing || ''{{cmd|r3.stats}}'': 3D raster statistics
|-
| t.* || temporal data processing || ''{{cmd|t.rast.aggregate}}'': temporal aggregation
|-
| g.* || general data management || ''{{cmd|g.rename}}'': renames map
|-
| d.* || display ||''{{cmd|d.rast}}'': display raster map
|}</center>
* GRASS modules have GUI and command line interface. In this workshop we use commands to describe the workflow, but we can use both GUI and command line depending on personal preference. Look how {{cmd|wxGUI.modules|version=71|desc=GUI and command line interface}} represent the same tool. ''Task:'' compute aspect (orientation) from provided digital elevation model using module {{cmd|r.slope.aspect}} using both module dialog and command line.
* How to find modules? Modules are organized by their functionality in wxGUI menu, or we can search for them in Search modules tab. If we already know which module to use, we can just type it in the wxGUI command console. <center><gallery perrow=3 widths=380 heights=190>Image:wxGUI_menu_rinfo.png|Modules can be found in wxGUI menu
Image:wxGUI_module_search.png|You can search modules by name, description or keywords in ''Search modules'' tab
Image:wxGUI_console_completion.png|By typing prefix r. we make a list of modules starting with that prefix to show up.</gallery></center>


* {{cmd|g.region|desc=Computational region}} - an important raster concept
** defined by region extent and raster resolution
** applies to all raster operations
** persists between GRASS session, can be different for different mapsets
** advantages: keeps your results consistent, avoid clipping, for computationally demanding tasks set region to smaller extent, check your result is good and then set the computational region to the entire study area and rerun analysis
** run <code>g.region -p</code> or in menu ''Settings'' - ''Region'' - ''Display region'' to see current region settings
[[File:WxGUI set region.png|700px|thumb|center|Simple ways to set computational region from GUI. On the left, set region to match raster map. On the right, select the highlighted option and then set region by drawing rectangle.]]

* GRASS 3D view

= Modeling with FUTURES =
== Initial steps and data preparation ==
First we will set the computational region of our analyses to an extent covering our study area and aligned with our base landuse rasters:
<source lang="bash">g.region raster=landuse_2011 -p</source>

We will derive urbanized areas from NLCD dataset for year 1992, 2001 and 2011
by extracting categories category 21 - 24 into a new binary map where developed is 1,
undeveloped 0 and NULL (no data) is area unsuitable for development (water, wetlands, protected areas).
First we will convert protected areas from vector to raster. We set
NULLs to zeros (for simpler raster algebra expression in the next step) using {{cmd|r.null}}:

<source lang="bash">
v.to.rast input=protected_areas output=protected_areas use=val
r.null map=protected_areas null=0
</source>

And then create rasters of developed/undeveloped areas using raster algebra:

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.mapcalc "urban_1992 = if(landuse_1992 >= 21 && landuse_1992 <= 24, 1, if(landuse_1992 == 11 || landuse_1992 >= 90 || protected_areas, null(), 0))"
r.mapcalc "urban_2001 = if(landuse_2001 >= 21 && landuse_2001 <= 24, 1, if(landuse_2001 == 11 || landuse_2001 >= 90 || protected_areas, null(), 0))"
r.mapcalc "urban_2011 = if(landuse_2011 >= 21 && landuse_2011 <= 24, 1, if(landuse_2011 == 11 || landuse_2011 >= 90 || protected_areas, null(), 0))"
</source>

We will convert vector counties to raster with the values of the FIPS attribute which links to population file:

<source lang="bash">
v.to.rast input=counties type=area use=attr attribute_column=FIPS output=counties
</source>

Before further steps, we will set our working directory so that the input population files and text files
we are going to create are saved in one directory and easily accessible.
You can do that from menu ''Settings'' → ''GRASS working environment'' → ''Change working directory''.
Select (or create) a directory and move there the downloaded files <tt>population_projection.csv</tt> and <tt>population_trend.csv</tt>.

== Potential submodel ==
Module {{AddonCmd|r.futures.potential}} implements POTENTIAL submodel as a part of FUTURES land change model. POTENTIAL is implemented using a set of coefficients that relate a selection of site suitability factors to the probability of a place becoming developed. This is implemented using the parameter table in combination with maps of those site suitability factors (mapped predictors). The coefficients are obtained by conducting multilevel logistic regression in R with package lme4 where the coefficients may vary by county. The best model is selected automatically using dredge function from package [https://cran.r-project.org/web/packages/MuMIn/index.html MuMIn].

First, we will derive couple of predictors.
=== Predictors ===
==== Slope ====
We will derive slope in degrees from digital elevation model using {{cmd|r.slope.aspect}} module:
<source lang="bash">r.slope.aspect elevation=elevation_30m slope=slope</source>

==== Distance from lakes/rivers ====
First we will extract [http://www.mrlc.gov/nlcd11_leg.php category ''Open Water''] from 2011 NLCD dataset:
<source lang="bash">
r.mapcalc "water = if(landuse_2011 == 11, 1, null())"
</source>

Then we compute the distance to water with module {{cmd|r.grow.distance}} and set color table to shades of blue:
<source lang="bash">
r.grow.distance input=water distance=dist_to_water
r.colors -n map=dist_to_water color=blues
</source>

==== Distance from protected areas ====
We will use raster protected of protected areas we already created, but we will set NULL values to zero.
We compute the distance to protected areas with module {{cmd|r.grow.distance}} and set color table from green to red:
<source lang="bash">
r.null map=protected_areas setnull=0
r.grow.distance input=protected_areas distance=dist_to_protected
r.colors map=dist_to_protected color=gyr
</source>

==== Forests ====
We will smooth the transition between forest and other land use, see NLCD [http://www.mrlc.gov/nlcd11_leg.php category ''Open Water'']:
<source lang="bash">
r.mapcalc "forest = if(landuse_2011 >= 41 && landuse_2011 <= 43, 1, 0)"
r.neighbors -c input=forest output=forest_smooth size=15 method=average
r.colors map=forest_smooth color=ndvi
</source>

==== Travel time to cities ====
Here we will compute travel time to cities (with population > 5000)
as cumulative cost distance where cost is defined as travel time on roads.
First we specify the speed on different types of roads.
We copy the roads raster into our mapset so that we can change it
by adding a new attribute field <tt>speed</tt>. Then we assign speed values (km/h) based on the type of road:

<source lang="bash">
g.copy vector=roads,myroads
v.db.addcolumn map=myroads columns="speed double precision"
v.db.update map=myroads column=speed value=50 where="MTFCC = 'S1400'"
v.db.update map=myroads column=speed value=100 where="MTFCC IN ('S1100', 'S1200')"
</source>

Now we rasterize the selected road types using the speed values from the attribute table as raster values.

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
v.to.rast input=myroads type=line where="MTFCC IN ('S1100', 'S1200', 'S1400')" output=roads_speed use=attr attribute_column=speed
</source>

We set the rest of the area to low speed and recompute the speed as time to travel through a 30m cell in minutes:

<source lang="bash">
r.null map=roads_speed null=5
r.mapcalc "roads_travel_time = 1.8 / roads_speed"
</source>

Finally we compute the travel time to larger cities using {{cmd|r.cost}}:

<source lang="bash">
r.cost input=roads_travel_time output=travel_time_cities start_points=cities
r.colors map=travel_time_cities color=byr
</source>

==== Road density ====
We will rasterize roads and use moving window analysis ({{cmd|r.neighbors}}) to compute road density:

<source lang="bash">
v.to.rast input=roads output=roads use=val type=line
r.null map=roads null=0
r.neighbors -c input=roads output=road_dens size=25 method=average
</source>

==== Distance to interchanges ====

We will consider TIGER roads of type <tt>Ramp</tt> as interchanges, rasterize them and compute euclidean distance to them:

<source lang="bash">
v.to.rast input=roads type=line where="MTFCC = 'S1630'" output=interchanges use=val
r.grow.distance -m input=interchanges distance=dist_interchanges
</source>

=== Development pressure ===

We compute development pressure with {{AddonCmd|r.futures.devpressure}}. Development pressure is a predictor based on number of neighboring developed cells within search distance, weighted by distance. The development pressure variable plays a special role in the model, allowing for a feedback between predicted change and change in subsequent steps.

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.devpressure -n input=urban_2011 output=devpressure_2 method=gravity size=7 gamma=2 scaling_factor=10
r.futures.devpressure -n input=urban_2011 output=devpressure_1 method=gravity size=10 gamma=1 scaling_factor=1
r.futures.devpressure -n input=urban_2011 output=devpressure_0_5 method=gravity size=30 gamma=0.5 scaling_factor=0.1
</source>

When gamma increases, development influence decreases more rapidly with distance.
Size is half the size of the moving window. When gamma is low, local development influences more distant places.
We will derive 3 layers with different gamma and size parameters for the potential statistical model.

=== Rescaling variables ===

First we will look at the ranges of our predictor variables by running a short Python code snippet in Python shell:

<source lang="python" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
for name in ['slope', 'dist_to_water', 'dist_to_protected', 'forest_smooth', 'travel_time_cities', 'road_dens', 'dist_interchanges', 'devpressure_0_5', 'devpressure_1']:
minmax = grass.raster_info(name)
print name, minmax['min'], minmax['max']
</source>

We will rescale some of our input variables:

<source lang="bash">
r.mapcalc "dist_to_water_km = dist_to_water / 1000"
r.mapcalc "dist_to_protected_km = dist_to_protected / 1000"
r.mapcalc "dist_interchanges_km = dist_interchanges / 1000"
r.mapcalc "road_dens_perc = road_dens * 100"
r.mapcalc "forest_smooth_perc = forest_smooth * 100"
</source>

=== Sampling ===
To sample only in the analyzed counties, we will clip development layer:

<source lang="bash">
r.mapcalc "urban_change_01_11 = if(urban_2011 == 1, if(urban_2001 == 0, 1, null()), 0)"
r.mapcalc "urban_change_clip = if(counties, urban_change_01_11)"
</source>

To estimate the number of sampling points, we can use {{cmd|r.report}} to report number of developed/undeveloped cells and their ratio.

<source lang="bash">
r.report map=urban_change_clip units=h,c,p
</source>

We will sample the predictors and the response variable with 5000 random points in undeveloped areas and 1000 points in developed area:

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.sample.category input=urban_change_clip output=sampling sampled=counties,devpressure_0_5,devpressure_1,devpressure_2,slope,road_dens_perc,forest_smooth_perc,dist_to_water_km,dist_to_protected_km,dist_interchanges_km,travel_time_cities npoints=5000,1000
</source>

The attribute table can be exported as CSV file (not necessary step):

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
v.db.select map=sampling columns=urban_change_clip,counties,devpressure_0_5,devpressure_1,slope,road_dens_perc,forest_smooth_perc,dist_to_water_km,dist_to_protected_km,dist_interchanges_km,travel_time_cities separator=comma file=samples.csv
</source>

=== Development potential ===
Now we find best model for predicting urbanization using {{AddonCmd|r.futures.potential}} which wraps an R script.

We can run R [http://www.inside-r.org/packages/cran/MuMIn/docs/dredge dredge] function to find "best" model. We can specify minimum and maximum number of predictors the final model should use.
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.potential -d input=sampling output=potential.csv columns=devpressure_1,slope,road_dens_perc,forest_smooth_perc,dist_to_water_km,dist_to_protected_km,dist_interchanges_km,travel_time_cities developed_column=urban_change_clip subregions_column=counties min_variables=4
</source>

Also, we can play with different combinations of predictors, for example:

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.potential input=sampling output=potential.csv columns=devpressure_2,road_dens_perc,slope,dist_interchanges_km,dist_to_water_km developed_column=urban_change_clip subregions_column=counties --o
r.futures.potential input=sampling output=potential.csv columns=devpressure_1,road_dens_perc,slope,dist_interchanges_km,dist_to_water_km developed_column=urban_change_clip subregions_column=counties --o
...
</source>

You can then open the output file <tt>potential.csv</tt>, which is a CSV file with tabs as separators.

For this tutorial, the final potential is created with:
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.potential input=sampling output=potential.csv columns=devpressure_2,road_dens_perc,slope,dist_interchanges_km,dist_to_water_km developed_column=urban_change_clip subregions_column=counties --o
</source>

We can now visualize the suitability surface using module {{AddonCmd|r.futures.potsurface}}. It creates initial development potential (suitability) raster from predictors and model coefficients and serves only for evaluating development potential model. The values of the resulting raster range from 0 to 1.

<source lang="bash">
r.futures.potsurface input=potential.csv subregions=counties output=suitability
r.colors map=suitability color=byr
</source>

== Demand submodel ==
First we will mask out roads so that they don't influence into per capita land demand relation.
<source lang="bash">
v.to.rast input=roads type=line output=roads_mask use=val
r.mask roads_mask -i
</source>

We will use {{AddonCmd|r.futures.demand}} which derives the population vs. development relation. The relation can be linear/logarithmic/logarithmic2/exponential/exponential approach.
Look for examples of the different relations in the manual.

* linear: y = A + Bx
* logarithmic: y = A + Bln(x)
* logarithmic2: y = A + B * ln(x - C)        (requires SciPy)
* exponential: y = Ae^(BX)
* exp_approach: y = (1 - e^(-A(x - B))) + C        (requires SciPy)

The format of the input population CSV files is described in the manual. It is important to have synchronized categories of subregions and the column headers of the CSV files (in our case FIPS number). How to simply generate the list of years (for which demand is computed) is described in {{AddonCmd|r.futures.demand}} manual, for example run this in Python console:

<source lang="python">
','.join([str(i) for i in range(2011, 2036)])
</source>

Then we can create the DEMAND file:
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.demand development=urban_1992,urban_2001,urban_2011 subregions=counties observed_population=population_trend.csv projected_population=population_projection.csv simulation_times=2011,2012,2013,2014,2015,2016,2017,2018,2019,2020,2021,2022,2023,2024,2025,2026,2027,2028,2029,2030,2031,2032,2033,2034,2035 plot=plot_demand.pdf demand=demand.csv separator=comma
</source>

In your current working directory, you should find files <tt>plot_demand.png</tt> and <tt>demand.csv</tt>.

If you have SciPy installed, you can experiment with other methods for fitting the functions:
<source lang="bash">
r.futures.demand ... method=logarithmic2
r.futures.demand ... method=exp_approach
</source>
If necessary, you can create a set of demand files produced by fitting each method separately and
then pick for each county the method which seems best and manually create a new demand file.

When you are finished, remove the mask as it is not needed for the next steps.
<source lang="bash">
r.mask -r
</source>

== Patch calibration ==
Patch calibration can be a very time consuming computation.
Therefore we select only one county (Buncombe):

<source lang="bash">
v.to.rast input=counties type=area where="FIPS == 37021" use=attr attribute_column=FIPS output=calib_county
g.region raster=calib_county zoom=calib_county
</source>
to derive patches of new development by comparing historical and latest development.
We can keep only patches with minimum size 2 cells (1800 = 2 x 30 x 30 m).

<source lang="bash">
r.futures.calib development_start=urban_1992 development_end=urban_2011 subregions=counties patch_sizes=patches.txt patch_threshold=1800 -l
</source>
We obtained a file <tt>patches.txt</tt> (used later in the PGA) - a patch size distribution file - containing sizes of all found patches.

We can look at the distribution of the patch sizes:

<source lang="python">
from matplotlib import pyplot as plt
with open('patches.txt') as f:
patches = [int(patch) for patch in f.readlines()]
plt.hist(patches, 2000)
plt.xlim(0,50)
plt.show()
</source>

At this point, we start the calibration to get best parameters of patch shape
(for this tutorial, this step can be skipped and the suggested parameters are used).

<source lang="bash"
style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.calib development_start=urban_1992 development_end=urban_2011 subregions=calib_county patch_sizes=patches.txt calibration_results=calib.csv patch_threshold=1800 repeat=5 compactness_mean=0.1,0.3,0.5,0.7,0.9 compactness_range=0.05 discount_factor=0.1,0.3,0.5,0.7,0.9 predictors=road_dens_perc,forest_smooth_perc,dist_to_protected_km demand=demand.csv devpot_params=potential.csv num_neighbors=4 seed_search=2 development_pressure=devpressure_0_5 development_pressure_approach=gravity n_dev_neighbourhood=30 gamma=0.5 scaling_factor=0.1
</source>

== FUTURES simulation ==
We will switch back to our previous region:
<source lang="bash">
g.region raster=landuse_2011 -p
</source>

Now we have all the inputs necessary for running {{AddonCmd|r.futures.pga}}:

The entire command is here:
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.pga subregions=counties developed=urban_2011 predictors=slope,forest_smooth_perc,dist_interchanges_km,travel_time_cities devpot_params=potential.csv development_pressure=devpressure_1 n_dev_neighbourhood=10 development_pressure_approach=gravity gamma=1 scaling_factor=1 demand=demand.csv discount_factor=0.3 compactness_mean=0.2 compactness_range=0.1 patch_sizes=patches.txt num_neighbors=4 seed_search=2 random_seed=1 output=final output_series=final
</source>

=== Quick description ===
The command parameters and their values:
* raster map of counties with their categories
<code>
... subregions=counties ...
</code>

* raster of developed (1), undeveloped (0) and NULLs for undevelopable areas
<code>
... developed=urban_2011 ...
</code>

* predictors selected with {{AddonCmd|r.futures.potential}} and their coefficients in a <tt>potential.csv</tt> file. The order of predictors must match the order in the file and the categories of the counties must match raster <tt>counties</tt>.
<code>
... predictors=slope,forest_smooth_perc,dist_interchanges_km,travel_time_cities devpot_params=potential.csv ...
</code>

* initial development pressure computed by {{AddonCmd|r.futures.devpressure}}, it's important to set here the same parameters
<code>
... development_pressure=devpressure_1 n_dev_neighbourhood=10 development_pressure_approach=gravity gamma=1 scaling_factor=1 ...
</code>

* per capita land demand computed by {{AddonCmd|r.futures.demand}}, the categories of the counties must match raster <tt>counties</tt>.
<code>
... demand=demand.csv ...
</code>

* patch parameters from the calibration step
<code>
... discount_factor=0.3 compactness_mean=0.4 compactness_range=0.08 patch_sizes=patches.txt ...
</code>

* recommended parameters for patch growing algorithm
<code>
... num_neighbors=4 seed_search=2 ...
</code>

* set random seed for repeatable results or set flag <tt>-s</tt> to generate seed automatically
<code>
... random_seed=1 ...
</code>

* specify final output map and optionally basename for intermediate raster maps
<code>
output=final output_series=final
</code>

== Scenarios ==
Scenarios involving policies that encourage infill versus sprawl can be explored using the <tt>incentive_power</tt> parameter of {{AddonCmd|r.futures.pga}},
which uses a power function to transform the evenness of the probability gradient in POTENTIAL. You can change the power to a number between 0.25 and 4 to test urban sprawl/infill scenarios.
Higher power leads to infill behavior, lower power to urban sprawl.

== Postprocessing ==

Follow a [[Creating_animation_from_FUTURES_output_in_GRASS_GIS| tutorial how to make an animation from the results]].

= GRASS GIS Python API =

[[Category: Tutorial]]
[[Category: FUTURES]]
[[Category: Urban]]

Workshop on urban growth modeling with FUTURES

2016-03-22T19:02:38Z

⚠️Dbvanber: /* Launching and exploring data in GRASS */

{{ToModify}}
= Workshop introduction =
r.futures.* is an implementation of the '''FUT'''ure '''U'''rban-'''R'''egional '''E'''nvironment '''S'''imulation (FUTURES)[1] which is a model for multilevel simulations of emerging urban-rural landscape structure. FUTURES produces regional projections of landscape patterns using coupled submodels that integrate nonstationary drivers of land change: per capita demand (DEMAND submodel), site suitability (POTENTIAL submodel), and the spatial structure of conversion events (PGA submodel).

[1] Meentemeyer, R. K., Tang, W., Dorning, M. A., Vogler, J. B., Cunniffe, N. J., & Shoemaker, D. A. (2013). [http://www.tandfonline.com/doi/abs/10.1080/00045608.2012.707591 FUTURES: multilevel simulations of emerging urban-rural landscape structure using a stochastic patch-growing algorithm.] Annals of the Association of American Geographers, 103(4), 785-807

== Software ==
There are a number of software requirements to run FUTURES that will need to be download and installed. Required software includes:
* GRASS GIS 7
* addons
** {{AddonCmd|r.futures.pga}}
** {{AddonCmd|r.futures.potential}}
** {{AddonCmd|r.futures.potsurface}}
** {{AddonCmd|r.futures.demand}}
** {{AddonCmd|r.futures.devpressure}}
** {{AddonCmd|r.sample.category}}
* R (≥ 3.0.2) - needed for {{AddonCmd|r.futures.potential}} with packages:
**MuMIn, lme4, optparse, rgrass7
* SciPy - useful for {{AddonCmd|r.futures.demand}}

=== Installation ===
We use the R statistical software for our calculation of site suitability (i.e. development potential) in FUTURES. R is a free software environment for statistical computing and graphics. If you don't have R, or you have older an version, please download and install the software from [http://archive.linux.duke.edu/cran/ install R] and be sure to additionally add these required packages:
<pre>
install.packages(c("MuMIn", "lme4", "optparse", "rgrass7"))
</pre>

==== MS Windows ====
We will be using GRASS GIS 7.0.3 that can be found here in the [https://trac.osgeo.org/osgeo4w/ OSGeo4W] package manager.
Please install the latest stable GRASS GIS 7 version and the SciPy Python package using the ''Advanced install'' option.
A guide with step by step screen shot instructions is available [https://docs.google.com/presentation/d/1yEGpriBne7RvjB35HI6GecNwO1P1y2nRGqDThqoNnCE/edit?usp=sharing here].

In order for GRASS to be able to find R executables, GRASS must be on the PATH variable. Follow this [solution] to make R accessible from GRASS permanently.
A simple but temporary solution is to open GRASS GIS and paste this in the black terminal:
<pre>
set PATH=%PATH%;C:\Program Files\R\R-3.0.2\bin
</pre>
This has to be repeated after restarting GRASS session.

==== Ubuntu Linux ====
Install GRASS GIS from packages:
<pre>
sudo add-apt-repository ppa:ubuntugis/ubuntugis-unstable
sudo apt-get update
sudo apt-get install grass
</pre>

== Workshop data ==
The data that we will be using for the workshop can be download here: [http://fatra.cnr.ncsu.edu/futures/futures_ncspm_Asheville.zip sample dataset]. Please place these layers in your local GRASS directory:
* digital elevation model ([http://nationalmap.gov/elevation.html NED])
* [http://www.mrlc.gov/ NLCD] 2001, 2011
* NLCD 1992/2001 Retrofit Land Cover Change Product
* transportation network ([http://www.census.gov/geo/maps-data/data/tiger-line.html TIGER])
* county boundaries ([http://www.census.gov/geo/maps-data/data/tiger-line.html TIGER])
* protected areas ([http://www.conservationgateway.org/ConservationByGeography/NorthAmerica/UnitedStates/edc/reportsdata/terrestrial/secured/Pages/default.aspx Secured Lands])
* cities as points (USGS)

In addition, download [http://fatra.cnr.ncsu.edu/futures/futures_Asheville_files.zip population information as text files]:
* county population past estimates and future projections ([https://www.osbm.nc.gov/demog/county-projections NC OSBM]) per county (nonspatial)

= GRASS GIS introduction =
There are many advantages to using the open source GRASS GIS platform, but for many that are more familiar with ARCGis and QGis, the setup and implementation of spatial tools in GRASS can be confusing. Here we provide an overview of the GRASS GIS project: [https://grass.osgeo.org grass.osgeo.org] that might be helpful to review if you are a first time users. For this exercise it's not necessary to have a full understanding of how to use GRASS. However, you will need to know how to place your data in the correct GRASS database directory, as well as some basic GRASS functionality. Step by step instructions are provided below
== Setting up GRASS for the tutorial ==
GRASS uses unique database terminology and structure ([https://grass.osgeo.org/grass71/manuals/grass_database.html GRASS database]) that are important to understand for the set up of this tutorial, as you will need to place the required data (e.g. Mapset) in a specific GRASS database Location. In the following we review important terminology and give step by step direction on how to download and place you data in the correct location.

=== Important GRASS directory terminology ===
* A '''GRASS database''' consist of directory with specific Locations (projects) where data layer are stored
* '''Location''' hold all Mapsets in a specific directoy that have the same spatial projection (spatial reference system)
* '''Mapset''' are a collection of maps with the same spatial projection

=== Creating a GRASS database for the tutorial ===
You need to create a GRASS database with the Mapset that we will use for the tutorial before we can run the FUTURES model. Please Download the [http://fatra.cnr.ncsu.edu/futures/futures_ncspm_Asheville.zip workshop location], noting where the files are located on your local directory. Now, create (unless you already have it) a directory named <tt>grassdata</tt> (GRASS database) in your home folder (or Documents), unzip the downloaded data into this directory. You should now have a Location <tt>futures_ncspm</tt> in <tt>grassdata</tt>.

<center><gallery perrow=1 widths=500 heights=250>Image:GRASS FUTURES startup.png|GRASS GIS 7.0.3 startup dialog with downloaded Location and Mapsets for FUTURES workshop</gallery></center>

=== Launching and exploring data in GRASS ===
Now that we have the data in the correct GRASS database, we can launch GRASS. The GUI interface allows you to display raster, vector data as well as navigate through zooming in and out. Advanced exploration and visualization, like many popular GIS software, is also possible in GRASS (e.g. queries, adding legend). The print screens below depict how you can add different map layer (left) and display the metadata of your data layers.

<center><gallery perrow=2 widths=500 heights=250>Image:GRASS FUTURES wxGUI display.png|Layer Manager and Map Display overview. Annotations show how to add raster layer, query, add legend.
Image:wxGUI_metadata_rinfo.png|Show raster map metadata by right click on layer</gallery></center>

== GRASS functionality ==

* GRASS GIS has over [https://grass.osgeo.org/grass70/manuals/full_index.html 500 different modules] in the core distribution and over [https://grass.osgeo.org/grass70/manuals/addons/ 230 addon modules]
<center>
{| class="wikitable"
|-
! Prefix !! Function !! Example
|-
| r.* || raster processing || ''{{cmd|r.mapcalc}}'': map algebra
|-
| v.* || vector processing || ''{{cmd|v.clean}}'': topological cleaning
|-
| i.* || imagery processing || ''{{cmd|i.segment}}'': object recognition
|-
| db.* || database management || ''{{cmd|db.select}}'': select values from table
|-
| r3.* || 3D raster processing || ''{{cmd|r3.stats}}'': 3D raster statistics
|-
| t.* || temporal data processing || ''{{cmd|t.rast.aggregate}}'': temporal aggregation
|-
| g.* || general data management || ''{{cmd|g.rename}}'': renames map
|-
| d.* || display ||''{{cmd|d.rast}}'': display raster map
|}</center>
* GRASS modules have GUI and command line interface. In this workshop we use commands to describe the workflow, but we can use both GUI and command line depending on personal preference. Look how {{cmd|wxGUI.modules|version=71|desc=GUI and command line interface}} represent the same tool. ''Task:'' compute aspect (orientation) from provided digital elevation model using module {{cmd|r.slope.aspect}} using both module dialog and command line.
* How to find modules? Modules are organized by their functionality in wxGUI menu, or we can search for them in Search modules tab. If we already know which module to use, we can just type it in the wxGUI command console. <center><gallery perrow=3 widths=380 heights=190>Image:wxGUI_menu_rinfo.png|Modules can be found in wxGUI menu
Image:wxGUI_module_search.png|You can search modules by name, description or keywords in ''Search modules'' tab
Image:wxGUI_console_completion.png|By typing prefix r. we make a list of modules starting with that prefix to show up.</gallery></center>


* {{cmd|g.region|desc=Computational region}} - an important raster concept
** defined by region extent and raster resolution
** applies to all raster operations
** persists between GRASS session, can be different for different mapsets
** advantages: keeps your results consistent, avoid clipping, for computationally demanding tasks set region to smaller extent, check your result is good and then set the computational region to the entire study area and rerun analysis
** run <code>g.region -p</code> or in menu ''Settings'' - ''Region'' - ''Display region'' to see current region settings
[[File:WxGUI set region.png|700px|thumb|center|Simple ways to set computational region from GUI. On the left, set region to match raster map. On the right, select the highlighted option and then set region by drawing rectangle.]]

* GRASS 3D view

= Modeling with FUTURES =
== Initial steps and data preparation ==
First we will set the computational region of our analyses to an extent covering our study area and aligned with our base landuse rasters:
<source lang="bash">g.region raster=landuse_2011 -p</source>

We will derive urbanized areas from NLCD dataset for year 1992, 2001 and 2011
by extracting categories category 21 - 24 into a new binary map where developed is 1,
undeveloped 0 and NULL (no data) is area unsuitable for development (water, wetlands, protected areas).
First we will convert protected areas from vector to raster. We set
NULLs to zeros (for simpler raster algebra expression in the next step) using {{cmd|r.null}}:

<source lang="bash">
v.to.rast input=protected_areas output=protected_areas use=val
r.null map=protected_areas null=0
</source>

And then create rasters of developed/undeveloped areas using raster algebra:

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.mapcalc "urban_1992 = if(landuse_1992 >= 21 && landuse_1992 <= 24, 1, if(landuse_1992 == 11 || landuse_1992 >= 90 || protected_areas, null(), 0))"
r.mapcalc "urban_2001 = if(landuse_2001 >= 21 && landuse_2001 <= 24, 1, if(landuse_2001 == 11 || landuse_2001 >= 90 || protected_areas, null(), 0))"
r.mapcalc "urban_2011 = if(landuse_2011 >= 21 && landuse_2011 <= 24, 1, if(landuse_2011 == 11 || landuse_2011 >= 90 || protected_areas, null(), 0))"
</source>

We will convert vector counties to raster with the values of the FIPS attribute which links to population file:

<source lang="bash">
v.to.rast input=counties type=area use=attr attribute_column=FIPS output=counties
</source>

Before further steps, we will set our working directory so that the input population files and text files
we are going to create are saved in one directory and easily accessible.
You can do that from menu ''Settings'' → ''GRASS working environment'' → ''Change working directory''.
Select (or create) a directory and move there the downloaded files <tt>population_projection.csv</tt> and <tt>population_trend.csv</tt>.

== Potential submodel ==
Module {{AddonCmd|r.futures.potential}} implements POTENTIAL submodel as a part of FUTURES land change model. POTENTIAL is implemented using a set of coefficients that relate a selection of site suitability factors to the probability of a place becoming developed. This is implemented using the parameter table in combination with maps of those site suitability factors (mapped predictors). The coefficients are obtained by conducting multilevel logistic regression in R with package lme4 where the coefficients may vary by county. The best model is selected automatically using dredge function from package [https://cran.r-project.org/web/packages/MuMIn/index.html MuMIn].

First, we will derive couple of predictors.
=== Predictors ===
==== Slope ====
We will derive slope in degrees from digital elevation model using {{cmd|r.slope.aspect}} module:
<source lang="bash">r.slope.aspect elevation=elevation_30m slope=slope</source>

==== Distance from lakes/rivers ====
First we will extract [http://www.mrlc.gov/nlcd11_leg.php category ''Open Water''] from 2011 NLCD dataset:
<source lang="bash">
r.mapcalc "water = if(landuse_2011 == 11, 1, null())"
</source>

Then we compute the distance to water with module {{cmd|r.grow.distance}} and set color table to shades of blue:
<source lang="bash">
r.grow.distance input=water distance=dist_to_water
r.colors -n map=dist_to_water color=blues
</source>

==== Distance from protected areas ====
We will use raster protected of protected areas we already created, but we will set NULL values to zero.
We compute the distance to protected areas with module {{cmd|r.grow.distance}} and set color table from green to red:
<source lang="bash">
r.null map=protected_areas setnull=0
r.grow.distance input=protected_areas distance=dist_to_protected
r.colors map=dist_to_protected color=gyr
</source>

==== Forests ====
We will smooth the transition between forest and other land use, see NLCD [http://www.mrlc.gov/nlcd11_leg.php category ''Open Water'']:
<source lang="bash">
r.mapcalc "forest = if(landuse_2011 >= 41 && landuse_2011 <= 43, 1, 0)"
r.neighbors -c input=forest output=forest_smooth size=15 method=average
r.colors map=forest_smooth color=ndvi
</source>

==== Travel time to cities ====
Here we will compute travel time to cities (with population > 5000)
as cumulative cost distance where cost is defined as travel time on roads.
First we specify the speed on different types of roads.
We copy the roads raster into our mapset so that we can change it
by adding a new attribute field <tt>speed</tt>. Then we assign speed values (km/h) based on the type of road:

<source lang="bash">
g.copy vector=roads,myroads
v.db.addcolumn map=myroads columns="speed double precision"
v.db.update map=myroads column=speed value=50 where="MTFCC = 'S1400'"
v.db.update map=myroads column=speed value=100 where="MTFCC IN ('S1100', 'S1200')"
</source>

Now we rasterize the selected road types using the speed values from the attribute table as raster values.

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
v.to.rast input=myroads type=line where="MTFCC IN ('S1100', 'S1200', 'S1400')" output=roads_speed use=attr attribute_column=speed
</source>

We set the rest of the area to low speed and recompute the speed as time to travel through a 30m cell in minutes:

<source lang="bash">
r.null map=roads_speed null=5
r.mapcalc "roads_travel_time = 1.8 / roads_speed"
</source>

Finally we compute the travel time to larger cities using {{cmd|r.cost}}:

<source lang="bash">
r.cost input=roads_travel_time output=travel_time_cities start_points=cities
r.colors map=travel_time_cities color=byr
</source>

==== Road density ====
We will rasterize roads and use moving window analysis ({{cmd|r.neighbors}}) to compute road density:

<source lang="bash">
v.to.rast input=roads output=roads use=val type=line
r.null map=roads null=0
r.neighbors -c input=roads output=road_dens size=25 method=average
</source>

==== Distance to interchanges ====

We will consider TIGER roads of type <tt>Ramp</tt> as interchanges, rasterize them and compute euclidean distance to them:

<source lang="bash">
v.to.rast input=roads type=line where="MTFCC = 'S1630'" output=interchanges use=val
r.grow.distance -m input=interchanges distance=dist_interchanges
</source>

=== Development pressure ===

We compute development pressure with {{AddonCmd|r.futures.devpressure}}. Development pressure is a predictor based on number of neighboring developed cells within search distance, weighted by distance. The development pressure variable plays a special role in the model, allowing for a feedback between predicted change and change in subsequent steps.

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.devpressure -n input=urban_2011 output=devpressure_2 method=gravity size=7 gamma=2 scaling_factor=10
r.futures.devpressure -n input=urban_2011 output=devpressure_1 method=gravity size=10 gamma=1 scaling_factor=1
r.futures.devpressure -n input=urban_2011 output=devpressure_0_5 method=gravity size=30 gamma=0.5 scaling_factor=0.1
</source>

When gamma increases, development influence decreases more rapidly with distance.
Size is half the size of the moving window. When gamma is low, local development influences more distant places.
We will derive 3 layers with different gamma and size parameters for the potential statistical model.

=== Rescaling variables ===

First we will look at the ranges of our predictor variables by running a short Python code snippet in Python shell:

<source lang="python" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
for name in ['slope', 'dist_to_water', 'dist_to_protected', 'forest_smooth', 'travel_time_cities', 'road_dens', 'dist_interchanges', 'devpressure_0_5', 'devpressure_1']:
minmax = grass.raster_info(name)
print name, minmax['min'], minmax['max']
</source>

We will rescale some of our input variables:

<source lang="bash">
r.mapcalc "dist_to_water_km = dist_to_water / 1000"
r.mapcalc "dist_to_protected_km = dist_to_protected / 1000"
r.mapcalc "dist_interchanges_km = dist_interchanges / 1000"
r.mapcalc "road_dens_perc = road_dens * 100"
r.mapcalc "forest_smooth_perc = forest_smooth * 100"
</source>

=== Sampling ===
To sample only in the analyzed counties, we will clip development layer:

<source lang="bash">
r.mapcalc "urban_change_01_11 = if(urban_2011 == 1, if(urban_2001 == 0, 1, null()), 0)"
r.mapcalc "urban_change_clip = if(counties, urban_change_01_11)"
</source>

To estimate the number of sampling points, we can use {{cmd|r.report}} to report number of developed/undeveloped cells and their ratio.

<source lang="bash">
r.report map=urban_change_clip units=h,c,p
</source>

We will sample the predictors and the response variable with 5000 random points in undeveloped areas and 1000 points in developed area:

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.sample.category input=urban_change_clip output=sampling sampled=counties,devpressure_0_5,devpressure_1,devpressure_2,slope,road_dens_perc,forest_smooth_perc,dist_to_water_km,dist_to_protected_km,dist_interchanges_km,travel_time_cities npoints=5000,1000
</source>

The attribute table can be exported as CSV file (not necessary step):

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
v.db.select map=sampling columns=urban_change_clip,counties,devpressure_0_5,devpressure_1,slope,road_dens_perc,forest_smooth_perc,dist_to_water_km,dist_to_protected_km,dist_interchanges_km,travel_time_cities separator=comma file=samples.csv
</source>

=== Development potential ===
Now we find best model for predicting urbanization using {{AddonCmd|r.futures.potential}} which wraps an R script.

We can run R [http://www.inside-r.org/packages/cran/MuMIn/docs/dredge dredge] function to find "best" model. We can specify minimum and maximum number of predictors the final model should use.
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.potential -d input=sampling output=potential.csv columns=devpressure_1,slope,road_dens_perc,forest_smooth_perc,dist_to_water_km,dist_to_protected_km,dist_interchanges_km,travel_time_cities developed_column=urban_change_clip subregions_column=counties min_variables=4
</source>

Also, we can play with different combinations of predictors, for example:

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.potential input=sampling output=potential.csv columns=devpressure_2,road_dens_perc,slope,dist_interchanges_km,dist_to_water_km developed_column=urban_change_clip subregions_column=counties --o
r.futures.potential input=sampling output=potential.csv columns=devpressure_1,road_dens_perc,slope,dist_interchanges_km,dist_to_water_km developed_column=urban_change_clip subregions_column=counties --o
...
</source>

You can then open the output file <tt>potential.csv</tt>, which is a CSV file with tabs as separators.

For this tutorial, the final potential is created with:
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.potential input=sampling output=potential.csv columns=devpressure_2,road_dens_perc,slope,dist_interchanges_km,dist_to_water_km developed_column=urban_change_clip subregions_column=counties --o
</source>

We can now visualize the suitability surface using module {{AddonCmd|r.futures.potsurface}}. It creates initial development potential (suitability) raster from predictors and model coefficients and serves only for evaluating development potential model. The values of the resulting raster range from 0 to 1.

<source lang="bash">
r.futures.potsurface input=potential.csv subregions=counties output=suitability
r.colors map=suitability color=byr
</source>

== Demand submodel ==
First we will mask out roads so that they don't influence into per capita land demand relation.
<source lang="bash">
v.to.rast input=roads type=line output=roads_mask use=val
r.mask roads_mask -i
</source>

We will use {{AddonCmd|r.futures.demand}} which derives the population vs. development relation. The relation can be linear/logarithmic/logarithmic2/exponential/exponential approach.
Look for examples of the different relations in the manual.

* linear: y = A + Bx
* logarithmic: y = A + Bln(x)
* logarithmic2: y = A + B * ln(x - C)        (requires SciPy)
* exponential: y = Ae^(BX)
* exp_approach: y = (1 - e^(-A(x - B))) + C        (requires SciPy)

The format of the input population CSV files is described in the manual. It is important to have synchronized categories of subregions and the column headers of the CSV files (in our case FIPS number). How to simply generate the list of years (for which demand is computed) is described in {{AddonCmd|r.futures.demand}} manual, for example run this in Python console:

<source lang="python">
','.join([str(i) for i in range(2011, 2036)])
</source>

Then we can create the DEMAND file:
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.demand development=urban_1992,urban_2001,urban_2011 subregions=counties observed_population=population_trend.csv projected_population=population_projection.csv simulation_times=2011,2012,2013,2014,2015,2016,2017,2018,2019,2020,2021,2022,2023,2024,2025,2026,2027,2028,2029,2030,2031,2032,2033,2034,2035 plot=plot_demand.pdf demand=demand.csv separator=comma
</source>

In your current working directory, you should find files <tt>plot_demand.png</tt> and <tt>demand.csv</tt>.

If you have SciPy installed, you can experiment with other methods for fitting the functions:
<source lang="bash">
r.futures.demand ... method=logarithmic2
r.futures.demand ... method=exp_approach
</source>
If necessary, you can create a set of demand files produced by fitting each method separately and
then pick for each county the method which seems best and manually create a new demand file.

When you are finished, remove the mask as it is not needed for the next steps.
<source lang="bash">
r.mask -r
</source>

== Patch calibration ==
Patch calibration can be a very time consuming computation.
Therefore we select only one county (Buncombe):

<source lang="bash">
v.to.rast input=counties type=area where="FIPS == 37021" use=attr attribute_column=FIPS output=calib_county
g.region raster=calib_county zoom=calib_county
</source>
to derive patches of new development by comparing historical and latest development.
We can keep only patches with minimum size 2 cells (1800 = 2 x 30 x 30 m).

<source lang="bash">
r.futures.calib development_start=urban_1992 development_end=urban_2011 subregions=counties patch_sizes=patches.txt patch_threshold=1800 -l
</source>
We obtained a file <tt>patches.txt</tt> (used later in the PGA) - a patch size distribution file - containing sizes of all found patches.

We can look at the distribution of the patch sizes:

<source lang="python">
from matplotlib import pyplot as plt
with open('patches.txt') as f:
patches = [int(patch) for patch in f.readlines()]
plt.hist(patches, 2000)
plt.xlim(0,50)
plt.show()
</source>

At this point, we start the calibration to get best parameters of patch shape
(for this tutorial, this step can be skipped and the suggested parameters are used).

<source lang="bash"
style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.calib development_start=urban_1992 development_end=urban_2011 subregions=calib_county patch_sizes=patches.txt calibration_results=calib.csv patch_threshold=1800 repeat=5 compactness_mean=0.1,0.3,0.5,0.7,0.9 compactness_range=0.05 discount_factor=0.1,0.3,0.5,0.7,0.9 predictors=road_dens_perc,forest_smooth_perc,dist_to_protected_km demand=demand.csv devpot_params=potential.csv num_neighbors=4 seed_search=2 development_pressure=devpressure_0_5 development_pressure_approach=gravity n_dev_neighbourhood=30 gamma=0.5 scaling_factor=0.1
</source>

== FUTURES simulation ==
We will switch back to our previous region:
<source lang="bash">
g.region raster=landuse_2011 -p
</source>

Now we have all the inputs necessary for running {{AddonCmd|r.futures.pga}}:

The entire command is here:
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.pga subregions=counties developed=urban_2011 predictors=slope,forest_smooth_perc,dist_interchanges_km,travel_time_cities devpot_params=potential.csv development_pressure=devpressure_1 n_dev_neighbourhood=10 development_pressure_approach=gravity gamma=1 scaling_factor=1 demand=demand.csv discount_factor=0.3 compactness_mean=0.2 compactness_range=0.1 patch_sizes=patches.txt num_neighbors=4 seed_search=2 random_seed=1 output=final output_series=final
</source>

=== Quick description ===
The command parameters and their values:
* raster map of counties with their categories
<code>
... subregions=counties ...
</code>

* raster of developed (1), undeveloped (0) and NULLs for undevelopable areas
<code>
... developed=urban_2011 ...
</code>

* predictors selected with {{AddonCmd|r.futures.potential}} and their coefficients in a <tt>potential.csv</tt> file. The order of predictors must match the order in the file and the categories of the counties must match raster <tt>counties</tt>.
<code>
... predictors=slope,forest_smooth_perc,dist_interchanges_km,travel_time_cities devpot_params=potential.csv ...
</code>

* initial development pressure computed by {{AddonCmd|r.futures.devpressure}}, it's important to set here the same parameters
<code>
... development_pressure=devpressure_1 n_dev_neighbourhood=10 development_pressure_approach=gravity gamma=1 scaling_factor=1 ...
</code>

* per capita land demand computed by {{AddonCmd|r.futures.demand}}, the categories of the counties must match raster <tt>counties</tt>.
<code>
... demand=demand.csv ...
</code>

* patch parameters from the calibration step
<code>
... discount_factor=0.3 compactness_mean=0.4 compactness_range=0.08 patch_sizes=patches.txt ...
</code>

* recommended parameters for patch growing algorithm
<code>
... num_neighbors=4 seed_search=2 ...
</code>

* set random seed for repeatable results or set flag <tt>-s</tt> to generate seed automatically
<code>
... random_seed=1 ...
</code>

* specify final output map and optionally basename for intermediate raster maps
<code>
output=final output_series=final
</code>

== Scenarios ==
Scenarios involving policies that encourage infill versus sprawl can be explored using the <tt>incentive_power</tt> parameter of {{AddonCmd|r.futures.pga}},
which uses a power function to transform the evenness of the probability gradient in POTENTIAL. You can change the power to a number between 0.25 and 4 to test urban sprawl/infill scenarios.
Higher power leads to infill behavior, lower power to urban sprawl.

== Postprocessing ==

Follow a [[Creating_animation_from_FUTURES_output_in_GRASS_GIS| tutorial how to make an animation from the results]].

= GRASS GIS Python API =

[[Category: Tutorial]]
[[Category: FUTURES]]
[[Category: Urban]]

Workshop on urban growth modeling with FUTURES

2016-03-22T18:59:32Z

⚠️Dbvanber: /* Creating a GRASS database for the tutorial */

{{ToModify}}
= Workshop introduction =
r.futures.* is an implementation of the '''FUT'''ure '''U'''rban-'''R'''egional '''E'''nvironment '''S'''imulation (FUTURES)[1] which is a model for multilevel simulations of emerging urban-rural landscape structure. FUTURES produces regional projections of landscape patterns using coupled submodels that integrate nonstationary drivers of land change: per capita demand (DEMAND submodel), site suitability (POTENTIAL submodel), and the spatial structure of conversion events (PGA submodel).

[1] Meentemeyer, R. K., Tang, W., Dorning, M. A., Vogler, J. B., Cunniffe, N. J., & Shoemaker, D. A. (2013). [http://www.tandfonline.com/doi/abs/10.1080/00045608.2012.707591 FUTURES: multilevel simulations of emerging urban-rural landscape structure using a stochastic patch-growing algorithm.] Annals of the Association of American Geographers, 103(4), 785-807

== Software ==
There are a number of software requirements to run FUTURES that will need to be download and installed. Required software includes:
* GRASS GIS 7
* addons
** {{AddonCmd|r.futures.pga}}
** {{AddonCmd|r.futures.potential}}
** {{AddonCmd|r.futures.potsurface}}
** {{AddonCmd|r.futures.demand}}
** {{AddonCmd|r.futures.devpressure}}
** {{AddonCmd|r.sample.category}}
* R (≥ 3.0.2) - needed for {{AddonCmd|r.futures.potential}} with packages:
**MuMIn, lme4, optparse, rgrass7
* SciPy - useful for {{AddonCmd|r.futures.demand}}

=== Installation ===
We use the R statistical software for our calculation of site suitability (i.e. development potential) in FUTURES. R is a free software environment for statistical computing and graphics. If you don't have R, or you have older an version, please download and install the software from [http://archive.linux.duke.edu/cran/ install R] and be sure to additionally add these required packages:
<pre>
install.packages(c("MuMIn", "lme4", "optparse", "rgrass7"))
</pre>

==== MS Windows ====
We will be using GRASS GIS 7.0.3 that can be found here in the [https://trac.osgeo.org/osgeo4w/ OSGeo4W] package manager.
Please install the latest stable GRASS GIS 7 version and the SciPy Python package using the ''Advanced install'' option.
A guide with step by step screen shot instructions is available [https://docs.google.com/presentation/d/1yEGpriBne7RvjB35HI6GecNwO1P1y2nRGqDThqoNnCE/edit?usp=sharing here].

In order for GRASS to be able to find R executables, GRASS must be on the PATH variable. Follow this [solution] to make R accessible from GRASS permanently.
A simple but temporary solution is to open GRASS GIS and paste this in the black terminal:
<pre>
set PATH=%PATH%;C:\Program Files\R\R-3.0.2\bin
</pre>
This has to be repeated after restarting GRASS session.

==== Ubuntu Linux ====
Install GRASS GIS from packages:
<pre>
sudo add-apt-repository ppa:ubuntugis/ubuntugis-unstable
sudo apt-get update
sudo apt-get install grass
</pre>

== Workshop data ==
The data that we will be using for the workshop can be download here: [http://fatra.cnr.ncsu.edu/futures/futures_ncspm_Asheville.zip sample dataset]. Please place these layers in your local GRASS directory:
* digital elevation model ([http://nationalmap.gov/elevation.html NED])
* [http://www.mrlc.gov/ NLCD] 2001, 2011
* NLCD 1992/2001 Retrofit Land Cover Change Product
* transportation network ([http://www.census.gov/geo/maps-data/data/tiger-line.html TIGER])
* county boundaries ([http://www.census.gov/geo/maps-data/data/tiger-line.html TIGER])
* protected areas ([http://www.conservationgateway.org/ConservationByGeography/NorthAmerica/UnitedStates/edc/reportsdata/terrestrial/secured/Pages/default.aspx Secured Lands])
* cities as points (USGS)

In addition, download [http://fatra.cnr.ncsu.edu/futures/futures_Asheville_files.zip population information as text files]:
* county population past estimates and future projections ([https://www.osbm.nc.gov/demog/county-projections NC OSBM]) per county (nonspatial)

= GRASS GIS introduction =
There are many advantages to using the open source GRASS GIS platform, but for many that are more familiar with ARCGis and QGis, the setup and implementation of spatial tools in GRASS can be confusing. Here we provide an overview of the GRASS GIS project: [https://grass.osgeo.org grass.osgeo.org] that might be helpful to review if you are a first time users. For this exercise it's not necessary to have a full understanding of how to use GRASS. However, you will need to know how to place your data in the correct GRASS database directory, as well as some basic GRASS functionality. Step by step instructions are provided below
== Setting up GRASS for the tutorial ==
GRASS uses unique database terminology and structure ([https://grass.osgeo.org/grass71/manuals/grass_database.html GRASS database]) that are important to understand for the set up of this tutorial, as you will need to place the required data (e.g. Mapset) in a specific GRASS database Location. In the following we review important terminology and give step by step direction on how to download and place you data in the correct location.

=== Important GRASS directory terminology ===
* A '''GRASS database''' consist of directory with specific Locations (projects) where data layer are stored
* '''Location''' hold all Mapsets in a specific directoy that have the same spatial projection (spatial reference system)
* '''Mapset''' are a collection of maps with the same spatial projection

=== Creating a GRASS database for the tutorial ===
You need to create a GRASS database with the Mapset that we will use for the tutorial before we can run the FUTURES model. Please Download the [http://fatra.cnr.ncsu.edu/futures/futures_ncspm_Asheville.zip workshop location], noting where the files are located on your local directory. Now, create (unless you already have it) a directory named <tt>grassdata</tt> (GRASS database) in your home folder (or Documents), unzip the downloaded data into this directory. You should now have a Location <tt>futures_ncspm</tt> in <tt>grassdata</tt>.

<center><gallery perrow=1 widths=500 heights=250>Image:GRASS FUTURES startup.png|GRASS GIS 7.0.3 startup dialog with downloaded Location and Mapsets for FUTURES workshop</gallery></center>

=== Launching and exploring data in GRASS ===
Now that we have the data in the correct GRASS database, we can launch GRASS. The GUI interface allows you to display raster, vector data as well as navigate through zooming in and out. Advanced exploration and visualization, like many popular GIS software, is also possible in GRASS (e.g. queries, adding legend). showing metadata

<center><gallery perrow=2 widths=500 heights=250>Image:GRASS FUTURES wxGUI display.png|Layer Manager and Map Display overview. Annotations show how to add raster layer, query, add legend.
Image:wxGUI_metadata_rinfo.png|Show raster map metadata by right click on layer</gallery></center>

* GRASS GIS has over [https://grass.osgeo.org/grass70/manuals/full_index.html 500 different modules] in the core distribution and over [https://grass.osgeo.org/grass70/manuals/addons/ 230 addon modules]
<center>
{| class="wikitable"
|-
! Prefix !! Function !! Example
|-
| r.* || raster processing || ''{{cmd|r.mapcalc}}'': map algebra
|-
| v.* || vector processing || ''{{cmd|v.clean}}'': topological cleaning
|-
| i.* || imagery processing || ''{{cmd|i.segment}}'': object recognition
|-
| db.* || database management || ''{{cmd|db.select}}'': select values from table
|-
| r3.* || 3D raster processing || ''{{cmd|r3.stats}}'': 3D raster statistics
|-
| t.* || temporal data processing || ''{{cmd|t.rast.aggregate}}'': temporal aggregation
|-
| g.* || general data management || ''{{cmd|g.rename}}'': renames map
|-
| d.* || display ||''{{cmd|d.rast}}'': display raster map
|}</center>
* GRASS modules have GUI and command line interface. In this workshop we use commands to describe the workflow, but we can use both GUI and command line depending on personal preference. Look how {{cmd|wxGUI.modules|version=71|desc=GUI and command line interface}} represent the same tool. ''Task:'' compute aspect (orientation) from provided digital elevation model using module {{cmd|r.slope.aspect}} using both module dialog and command line.
* How to find modules? Modules are organized by their functionality in wxGUI menu, or we can search for them in Search modules tab. If we already know which module to use, we can just type it in the wxGUI command console. <center><gallery perrow=3 widths=380 heights=190>Image:wxGUI_menu_rinfo.png|Modules can be found in wxGUI menu
Image:wxGUI_module_search.png|You can search modules by name, description or keywords in ''Search modules'' tab
Image:wxGUI_console_completion.png|By typing prefix r. we make a list of modules starting with that prefix to show up.</gallery></center>


* {{cmd|g.region|desc=Computational region}} - an important raster concept
** defined by region extent and raster resolution
** applies to all raster operations
** persists between GRASS session, can be different for different mapsets
** advantages: keeps your results consistent, avoid clipping, for computationally demanding tasks set region to smaller extent, check your result is good and then set the computational region to the entire study area and rerun analysis
** run <code>g.region -p</code> or in menu ''Settings'' - ''Region'' - ''Display region'' to see current region settings
[[File:WxGUI set region.png|700px|thumb|center|Simple ways to set computational region from GUI. On the left, set region to match raster map. On the right, select the highlighted option and then set region by drawing rectangle.]]

* GRASS 3D view

= Modeling with FUTURES =
== Initial steps and data preparation ==
First we will set the computational region of our analyses to an extent covering our study area and aligned with our base landuse rasters:
<source lang="bash">g.region raster=landuse_2011 -p</source>

We will derive urbanized areas from NLCD dataset for year 1992, 2001 and 2011
by extracting categories category 21 - 24 into a new binary map where developed is 1,
undeveloped 0 and NULL (no data) is area unsuitable for development (water, wetlands, protected areas).
First we will convert protected areas from vector to raster. We set
NULLs to zeros (for simpler raster algebra expression in the next step) using {{cmd|r.null}}:

<source lang="bash">
v.to.rast input=protected_areas output=protected_areas use=val
r.null map=protected_areas null=0
</source>

And then create rasters of developed/undeveloped areas using raster algebra:

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.mapcalc "urban_1992 = if(landuse_1992 >= 21 && landuse_1992 <= 24, 1, if(landuse_1992 == 11 || landuse_1992 >= 90 || protected_areas, null(), 0))"
r.mapcalc "urban_2001 = if(landuse_2001 >= 21 && landuse_2001 <= 24, 1, if(landuse_2001 == 11 || landuse_2001 >= 90 || protected_areas, null(), 0))"
r.mapcalc "urban_2011 = if(landuse_2011 >= 21 && landuse_2011 <= 24, 1, if(landuse_2011 == 11 || landuse_2011 >= 90 || protected_areas, null(), 0))"
</source>

We will convert vector counties to raster with the values of the FIPS attribute which links to population file:

<source lang="bash">
v.to.rast input=counties type=area use=attr attribute_column=FIPS output=counties
</source>

Before further steps, we will set our working directory so that the input population files and text files
we are going to create are saved in one directory and easily accessible.
You can do that from menu ''Settings'' → ''GRASS working environment'' → ''Change working directory''.
Select (or create) a directory and move there the downloaded files <tt>population_projection.csv</tt> and <tt>population_trend.csv</tt>.

== Potential submodel ==
Module {{AddonCmd|r.futures.potential}} implements POTENTIAL submodel as a part of FUTURES land change model. POTENTIAL is implemented using a set of coefficients that relate a selection of site suitability factors to the probability of a place becoming developed. This is implemented using the parameter table in combination with maps of those site suitability factors (mapped predictors). The coefficients are obtained by conducting multilevel logistic regression in R with package lme4 where the coefficients may vary by county. The best model is selected automatically using dredge function from package [https://cran.r-project.org/web/packages/MuMIn/index.html MuMIn].

First, we will derive couple of predictors.
=== Predictors ===
==== Slope ====
We will derive slope in degrees from digital elevation model using {{cmd|r.slope.aspect}} module:
<source lang="bash">r.slope.aspect elevation=elevation_30m slope=slope</source>

==== Distance from lakes/rivers ====
First we will extract [http://www.mrlc.gov/nlcd11_leg.php category ''Open Water''] from 2011 NLCD dataset:
<source lang="bash">
r.mapcalc "water = if(landuse_2011 == 11, 1, null())"
</source>

Then we compute the distance to water with module {{cmd|r.grow.distance}} and set color table to shades of blue:
<source lang="bash">
r.grow.distance input=water distance=dist_to_water
r.colors -n map=dist_to_water color=blues
</source>

==== Distance from protected areas ====
We will use raster protected of protected areas we already created, but we will set NULL values to zero.
We compute the distance to protected areas with module {{cmd|r.grow.distance}} and set color table from green to red:
<source lang="bash">
r.null map=protected_areas setnull=0
r.grow.distance input=protected_areas distance=dist_to_protected
r.colors map=dist_to_protected color=gyr
</source>

==== Forests ====
We will smooth the transition between forest and other land use, see NLCD [http://www.mrlc.gov/nlcd11_leg.php category ''Open Water'']:
<source lang="bash">
r.mapcalc "forest = if(landuse_2011 >= 41 && landuse_2011 <= 43, 1, 0)"
r.neighbors -c input=forest output=forest_smooth size=15 method=average
r.colors map=forest_smooth color=ndvi
</source>

==== Travel time to cities ====
Here we will compute travel time to cities (with population > 5000)
as cumulative cost distance where cost is defined as travel time on roads.
First we specify the speed on different types of roads.
We copy the roads raster into our mapset so that we can change it
by adding a new attribute field <tt>speed</tt>. Then we assign speed values (km/h) based on the type of road:

<source lang="bash">
g.copy vector=roads,myroads
v.db.addcolumn map=myroads columns="speed double precision"
v.db.update map=myroads column=speed value=50 where="MTFCC = 'S1400'"
v.db.update map=myroads column=speed value=100 where="MTFCC IN ('S1100', 'S1200')"
</source>

Now we rasterize the selected road types using the speed values from the attribute table as raster values.

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
v.to.rast input=myroads type=line where="MTFCC IN ('S1100', 'S1200', 'S1400')" output=roads_speed use=attr attribute_column=speed
</source>

We set the rest of the area to low speed and recompute the speed as time to travel through a 30m cell in minutes:

<source lang="bash">
r.null map=roads_speed null=5
r.mapcalc "roads_travel_time = 1.8 / roads_speed"
</source>

Finally we compute the travel time to larger cities using {{cmd|r.cost}}:

<source lang="bash">
r.cost input=roads_travel_time output=travel_time_cities start_points=cities
r.colors map=travel_time_cities color=byr
</source>

==== Road density ====
We will rasterize roads and use moving window analysis ({{cmd|r.neighbors}}) to compute road density:

<source lang="bash">
v.to.rast input=roads output=roads use=val type=line
r.null map=roads null=0
r.neighbors -c input=roads output=road_dens size=25 method=average
</source>

==== Distance to interchanges ====

We will consider TIGER roads of type <tt>Ramp</tt> as interchanges, rasterize them and compute euclidean distance to them:

<source lang="bash">
v.to.rast input=roads type=line where="MTFCC = 'S1630'" output=interchanges use=val
r.grow.distance -m input=interchanges distance=dist_interchanges
</source>

=== Development pressure ===

We compute development pressure with {{AddonCmd|r.futures.devpressure}}. Development pressure is a predictor based on number of neighboring developed cells within search distance, weighted by distance. The development pressure variable plays a special role in the model, allowing for a feedback between predicted change and change in subsequent steps.

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.devpressure -n input=urban_2011 output=devpressure_2 method=gravity size=7 gamma=2 scaling_factor=10
r.futures.devpressure -n input=urban_2011 output=devpressure_1 method=gravity size=10 gamma=1 scaling_factor=1
r.futures.devpressure -n input=urban_2011 output=devpressure_0_5 method=gravity size=30 gamma=0.5 scaling_factor=0.1
</source>

When gamma increases, development influence decreases more rapidly with distance.
Size is half the size of the moving window. When gamma is low, local development influences more distant places.
We will derive 3 layers with different gamma and size parameters for the potential statistical model.

=== Rescaling variables ===

First we will look at the ranges of our predictor variables by running a short Python code snippet in Python shell:

<source lang="python" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
for name in ['slope', 'dist_to_water', 'dist_to_protected', 'forest_smooth', 'travel_time_cities', 'road_dens', 'dist_interchanges', 'devpressure_0_5', 'devpressure_1']:
minmax = grass.raster_info(name)
print name, minmax['min'], minmax['max']
</source>

We will rescale some of our input variables:

<source lang="bash">
r.mapcalc "dist_to_water_km = dist_to_water / 1000"
r.mapcalc "dist_to_protected_km = dist_to_protected / 1000"
r.mapcalc "dist_interchanges_km = dist_interchanges / 1000"
r.mapcalc "road_dens_perc = road_dens * 100"
r.mapcalc "forest_smooth_perc = forest_smooth * 100"
</source>

=== Sampling ===
To sample only in the analyzed counties, we will clip development layer:

<source lang="bash">
r.mapcalc "urban_change_01_11 = if(urban_2011 == 1, if(urban_2001 == 0, 1, null()), 0)"
r.mapcalc "urban_change_clip = if(counties, urban_change_01_11)"
</source>

To estimate the number of sampling points, we can use {{cmd|r.report}} to report number of developed/undeveloped cells and their ratio.

<source lang="bash">
r.report map=urban_change_clip units=h,c,p
</source>

We will sample the predictors and the response variable with 5000 random points in undeveloped areas and 1000 points in developed area:

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.sample.category input=urban_change_clip output=sampling sampled=counties,devpressure_0_5,devpressure_1,devpressure_2,slope,road_dens_perc,forest_smooth_perc,dist_to_water_km,dist_to_protected_km,dist_interchanges_km,travel_time_cities npoints=5000,1000
</source>

The attribute table can be exported as CSV file (not necessary step):

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
v.db.select map=sampling columns=urban_change_clip,counties,devpressure_0_5,devpressure_1,slope,road_dens_perc,forest_smooth_perc,dist_to_water_km,dist_to_protected_km,dist_interchanges_km,travel_time_cities separator=comma file=samples.csv
</source>

=== Development potential ===
Now we find best model for predicting urbanization using {{AddonCmd|r.futures.potential}} which wraps an R script.

We can run R [http://www.inside-r.org/packages/cran/MuMIn/docs/dredge dredge] function to find "best" model. We can specify minimum and maximum number of predictors the final model should use.
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.potential -d input=sampling output=potential.csv columns=devpressure_1,slope,road_dens_perc,forest_smooth_perc,dist_to_water_km,dist_to_protected_km,dist_interchanges_km,travel_time_cities developed_column=urban_change_clip subregions_column=counties min_variables=4
</source>

Also, we can play with different combinations of predictors, for example:

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.potential input=sampling output=potential.csv columns=devpressure_2,road_dens_perc,slope,dist_interchanges_km,dist_to_water_km developed_column=urban_change_clip subregions_column=counties --o
r.futures.potential input=sampling output=potential.csv columns=devpressure_1,road_dens_perc,slope,dist_interchanges_km,dist_to_water_km developed_column=urban_change_clip subregions_column=counties --o
...
</source>

You can then open the output file <tt>potential.csv</tt>, which is a CSV file with tabs as separators.

For this tutorial, the final potential is created with:
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.potential input=sampling output=potential.csv columns=devpressure_2,road_dens_perc,slope,dist_interchanges_km,dist_to_water_km developed_column=urban_change_clip subregions_column=counties --o
</source>

We can now visualize the suitability surface using module {{AddonCmd|r.futures.potsurface}}. It creates initial development potential (suitability) raster from predictors and model coefficients and serves only for evaluating development potential model. The values of the resulting raster range from 0 to 1.

<source lang="bash">
r.futures.potsurface input=potential.csv subregions=counties output=suitability
r.colors map=suitability color=byr
</source>

== Demand submodel ==
First we will mask out roads so that they don't influence into per capita land demand relation.
<source lang="bash">
v.to.rast input=roads type=line output=roads_mask use=val
r.mask roads_mask -i
</source>

We will use {{AddonCmd|r.futures.demand}} which derives the population vs. development relation. The relation can be linear/logarithmic/logarithmic2/exponential/exponential approach.
Look for examples of the different relations in the manual.

* linear: y = A + Bx
* logarithmic: y = A + Bln(x)
* logarithmic2: y = A + B * ln(x - C)        (requires SciPy)
* exponential: y = Ae^(BX)
* exp_approach: y = (1 - e^(-A(x - B))) + C        (requires SciPy)

The format of the input population CSV files is described in the manual. It is important to have synchronized categories of subregions and the column headers of the CSV files (in our case FIPS number). How to simply generate the list of years (for which demand is computed) is described in {{AddonCmd|r.futures.demand}} manual, for example run this in Python console:

<source lang="python">
','.join([str(i) for i in range(2011, 2036)])
</source>

Then we can create the DEMAND file:
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.demand development=urban_1992,urban_2001,urban_2011 subregions=counties observed_population=population_trend.csv projected_population=population_projection.csv simulation_times=2011,2012,2013,2014,2015,2016,2017,2018,2019,2020,2021,2022,2023,2024,2025,2026,2027,2028,2029,2030,2031,2032,2033,2034,2035 plot=plot_demand.pdf demand=demand.csv separator=comma
</source>

In your current working directory, you should find files <tt>plot_demand.png</tt> and <tt>demand.csv</tt>.

If you have SciPy installed, you can experiment with other methods for fitting the functions:
<source lang="bash">
r.futures.demand ... method=logarithmic2
r.futures.demand ... method=exp_approach
</source>
If necessary, you can create a set of demand files produced by fitting each method separately and
then pick for each county the method which seems best and manually create a new demand file.

When you are finished, remove the mask as it is not needed for the next steps.
<source lang="bash">
r.mask -r
</source>

== Patch calibration ==
Patch calibration can be a very time consuming computation.
Therefore we select only one county (Buncombe):

<source lang="bash">
v.to.rast input=counties type=area where="FIPS == 37021" use=attr attribute_column=FIPS output=calib_county
g.region raster=calib_county zoom=calib_county
</source>
to derive patches of new development by comparing historical and latest development.
We can keep only patches with minimum size 2 cells (1800 = 2 x 30 x 30 m).

<source lang="bash">
r.futures.calib development_start=urban_1992 development_end=urban_2011 subregions=counties patch_sizes=patches.txt patch_threshold=1800 -l
</source>
We obtained a file <tt>patches.txt</tt> (used later in the PGA) - a patch size distribution file - containing sizes of all found patches.

We can look at the distribution of the patch sizes:

<source lang="python">
from matplotlib import pyplot as plt
with open('patches.txt') as f:
patches = [int(patch) for patch in f.readlines()]
plt.hist(patches, 2000)
plt.xlim(0,50)
plt.show()
</source>

At this point, we start the calibration to get best parameters of patch shape
(for this tutorial, this step can be skipped and the suggested parameters are used).

<source lang="bash"
style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.calib development_start=urban_1992 development_end=urban_2011 subregions=calib_county patch_sizes=patches.txt calibration_results=calib.csv patch_threshold=1800 repeat=5 compactness_mean=0.1,0.3,0.5,0.7,0.9 compactness_range=0.05 discount_factor=0.1,0.3,0.5,0.7,0.9 predictors=road_dens_perc,forest_smooth_perc,dist_to_protected_km demand=demand.csv devpot_params=potential.csv num_neighbors=4 seed_search=2 development_pressure=devpressure_0_5 development_pressure_approach=gravity n_dev_neighbourhood=30 gamma=0.5 scaling_factor=0.1
</source>

== FUTURES simulation ==
We will switch back to our previous region:
<source lang="bash">
g.region raster=landuse_2011 -p
</source>

Now we have all the inputs necessary for running {{AddonCmd|r.futures.pga}}:

The entire command is here:
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.pga subregions=counties developed=urban_2011 predictors=slope,forest_smooth_perc,dist_interchanges_km,travel_time_cities devpot_params=potential.csv development_pressure=devpressure_1 n_dev_neighbourhood=10 development_pressure_approach=gravity gamma=1 scaling_factor=1 demand=demand.csv discount_factor=0.3 compactness_mean=0.2 compactness_range=0.1 patch_sizes=patches.txt num_neighbors=4 seed_search=2 random_seed=1 output=final output_series=final
</source>

=== Quick description ===
The command parameters and their values:
* raster map of counties with their categories
<code>
... subregions=counties ...
</code>

* raster of developed (1), undeveloped (0) and NULLs for undevelopable areas
<code>
... developed=urban_2011 ...
</code>

* predictors selected with {{AddonCmd|r.futures.potential}} and their coefficients in a <tt>potential.csv</tt> file. The order of predictors must match the order in the file and the categories of the counties must match raster <tt>counties</tt>.
<code>
... predictors=slope,forest_smooth_perc,dist_interchanges_km,travel_time_cities devpot_params=potential.csv ...
</code>

* initial development pressure computed by {{AddonCmd|r.futures.devpressure}}, it's important to set here the same parameters
<code>
... development_pressure=devpressure_1 n_dev_neighbourhood=10 development_pressure_approach=gravity gamma=1 scaling_factor=1 ...
</code>

* per capita land demand computed by {{AddonCmd|r.futures.demand}}, the categories of the counties must match raster <tt>counties</tt>.
<code>
... demand=demand.csv ...
</code>

* patch parameters from the calibration step
<code>
... discount_factor=0.3 compactness_mean=0.4 compactness_range=0.08 patch_sizes=patches.txt ...
</code>

* recommended parameters for patch growing algorithm
<code>
... num_neighbors=4 seed_search=2 ...
</code>

* set random seed for repeatable results or set flag <tt>-s</tt> to generate seed automatically
<code>
... random_seed=1 ...
</code>

* specify final output map and optionally basename for intermediate raster maps
<code>
output=final output_series=final
</code>

== Scenarios ==
Scenarios involving policies that encourage infill versus sprawl can be explored using the <tt>incentive_power</tt> parameter of {{AddonCmd|r.futures.pga}},
which uses a power function to transform the evenness of the probability gradient in POTENTIAL. You can change the power to a number between 0.25 and 4 to test urban sprawl/infill scenarios.
Higher power leads to infill behavior, lower power to urban sprawl.

== Postprocessing ==

Follow a [[Creating_animation_from_FUTURES_output_in_GRASS_GIS| tutorial how to make an animation from the results]].

= GRASS GIS Python API =

[[Category: Tutorial]]
[[Category: FUTURES]]
[[Category: Urban]]

Workshop on urban growth modeling with FUTURES

2016-03-22T18:52:29Z

⚠️Dbvanber: /* Creating a GRASS database for the tutorial */

{{ToModify}}
= Workshop introduction =
r.futures.* is an implementation of the '''FUT'''ure '''U'''rban-'''R'''egional '''E'''nvironment '''S'''imulation (FUTURES)[1] which is a model for multilevel simulations of emerging urban-rural landscape structure. FUTURES produces regional projections of landscape patterns using coupled submodels that integrate nonstationary drivers of land change: per capita demand (DEMAND submodel), site suitability (POTENTIAL submodel), and the spatial structure of conversion events (PGA submodel).

[1] Meentemeyer, R. K., Tang, W., Dorning, M. A., Vogler, J. B., Cunniffe, N. J., & Shoemaker, D. A. (2013). [http://www.tandfonline.com/doi/abs/10.1080/00045608.2012.707591 FUTURES: multilevel simulations of emerging urban-rural landscape structure using a stochastic patch-growing algorithm.] Annals of the Association of American Geographers, 103(4), 785-807

== Software ==
There are a number of software requirements to run FUTURES that will need to be download and installed. Required software includes:
* GRASS GIS 7
* addons
** {{AddonCmd|r.futures.pga}}
** {{AddonCmd|r.futures.potential}}
** {{AddonCmd|r.futures.potsurface}}
** {{AddonCmd|r.futures.demand}}
** {{AddonCmd|r.futures.devpressure}}
** {{AddonCmd|r.sample.category}}
* R (≥ 3.0.2) - needed for {{AddonCmd|r.futures.potential}} with packages:
**MuMIn, lme4, optparse, rgrass7
* SciPy - useful for {{AddonCmd|r.futures.demand}}

=== Installation ===
We use the R statistical software for our calculation of site suitability (i.e. development potential) in FUTURES. R is a free software environment for statistical computing and graphics. If you don't have R, or you have older an version, please download and install the software from [http://archive.linux.duke.edu/cran/ install R] and be sure to additionally add these required packages:
<pre>
install.packages(c("MuMIn", "lme4", "optparse", "rgrass7"))
</pre>

==== MS Windows ====
We will be using GRASS GIS 7.0.3 that can be found here in the [https://trac.osgeo.org/osgeo4w/ OSGeo4W] package manager.
Please install the latest stable GRASS GIS 7 version and the SciPy Python package using the ''Advanced install'' option.
A guide with step by step screen shot instructions is available [https://docs.google.com/presentation/d/1yEGpriBne7RvjB35HI6GecNwO1P1y2nRGqDThqoNnCE/edit?usp=sharing here].

In order for GRASS to be able to find R executables, GRASS must be on the PATH variable. Follow this [solution] to make R accessible from GRASS permanently.
A simple but temporary solution is to open GRASS GIS and paste this in the black terminal:
<pre>
set PATH=%PATH%;C:\Program Files\R\R-3.0.2\bin
</pre>
This has to be repeated after restarting GRASS session.

==== Ubuntu Linux ====
Install GRASS GIS from packages:
<pre>
sudo add-apt-repository ppa:ubuntugis/ubuntugis-unstable
sudo apt-get update
sudo apt-get install grass
</pre>

== Workshop data ==
The data that we will be using for the workshop can be download here: [http://fatra.cnr.ncsu.edu/futures/futures_ncspm_Asheville.zip sample dataset]. Please place these layers in your local GRASS directory:
* digital elevation model ([http://nationalmap.gov/elevation.html NED])
* [http://www.mrlc.gov/ NLCD] 2001, 2011
* NLCD 1992/2001 Retrofit Land Cover Change Product
* transportation network ([http://www.census.gov/geo/maps-data/data/tiger-line.html TIGER])
* county boundaries ([http://www.census.gov/geo/maps-data/data/tiger-line.html TIGER])
* protected areas ([http://www.conservationgateway.org/ConservationByGeography/NorthAmerica/UnitedStates/edc/reportsdata/terrestrial/secured/Pages/default.aspx Secured Lands])
* cities as points (USGS)

In addition, download [http://fatra.cnr.ncsu.edu/futures/futures_Asheville_files.zip population information as text files]:
* county population past estimates and future projections ([https://www.osbm.nc.gov/demog/county-projections NC OSBM]) per county (nonspatial)

= GRASS GIS introduction =
There are many advantages to using the open source GRASS GIS platform, but for many that are more familiar with ARCGis and QGis, the setup and implementation of spatial tools in GRASS can be confusing. Here we provide an overview of the GRASS GIS project: [https://grass.osgeo.org grass.osgeo.org] that might be helpful to review if you are a first time users. For this exercise it's not necessary to have a full understanding of how to use GRASS. However, you will need to know how to place your data in the correct GRASS database directory, as well as some basic GRASS functionality. Step by step instructions are provided below
== Setting up GRASS for the tutorial ==
GRASS uses unique database terminology and structure ([https://grass.osgeo.org/grass71/manuals/grass_database.html GRASS database]) that are important to understand for the set up of this tutorial, as you will need to place the required data (e.g. Mapset) in a specific GRASS database Location. In the following we review important terminology and give step by step direction on how to download and place you data in the correct location.

=== Important GRASS directory terminology ===
* A '''GRASS database''' consist of directory with specific Locations (projects) where data layer are stored
* '''Location''' hold all Mapsets in a specific directoy that have the same spatial projection (spatial reference system)
* '''Mapset''' are a collection of maps with the same spatial projection

=== Creating a GRASS database for the tutorial ===
You need to create a GRASS database with the Mapset that we will use for the tutorial before we can run the FUTURES model. Please Download the [http://fatra.cnr.ncsu.edu/futures/futures_ncspm_Asheville.zip workshop location], noting where the files are located on your local directory. Now, create (unless you already have it) a directory named <tt>grassdata</tt> (GRASS database) in your home folder (or Documents), unzip the downloaded data into this directory. You should now have a Location <tt>futures_ncspm</tt> in <tt>grassdata</tt>.

<center><gallery perrow=1 widths=500 heights=250>Image:GRASS FUTURES startup.png|GRASS GIS 7.0.3 startup dialog with downloaded Location and Mapsets for FUTURES workshop</gallery></center>

* Launch GRASS and display raster, vector data, explore navigation, querying, adding legend, showing metadata

<center><gallery perrow=2 widths=500 heights=250>Image:GRASS FUTURES wxGUI display.png|Layer Manager and Map Display overview. Annotations show how to add raster layer, query, add legend.
Image:wxGUI_metadata_rinfo.png|Show raster map metadata by right click on layer</gallery></center>

* GRASS GIS has over [https://grass.osgeo.org/grass70/manuals/full_index.html 500 different modules] in the core distribution and over [https://grass.osgeo.org/grass70/manuals/addons/ 230 addon modules]
<center>
{| class="wikitable"
|-
! Prefix !! Function !! Example
|-
| r.* || raster processing || ''{{cmd|r.mapcalc}}'': map algebra
|-
| v.* || vector processing || ''{{cmd|v.clean}}'': topological cleaning
|-
| i.* || imagery processing || ''{{cmd|i.segment}}'': object recognition
|-
| db.* || database management || ''{{cmd|db.select}}'': select values from table
|-
| r3.* || 3D raster processing || ''{{cmd|r3.stats}}'': 3D raster statistics
|-
| t.* || temporal data processing || ''{{cmd|t.rast.aggregate}}'': temporal aggregation
|-
| g.* || general data management || ''{{cmd|g.rename}}'': renames map
|-
| d.* || display ||''{{cmd|d.rast}}'': display raster map
|}</center>
* GRASS modules have GUI and command line interface. In this workshop we use commands to describe the workflow, but we can use both GUI and command line depending on personal preference. Look how {{cmd|wxGUI.modules|version=71|desc=GUI and command line interface}} represent the same tool. ''Task:'' compute aspect (orientation) from provided digital elevation model using module {{cmd|r.slope.aspect}} using both module dialog and command line.
* How to find modules? Modules are organized by their functionality in wxGUI menu, or we can search for them in Search modules tab. If we already know which module to use, we can just type it in the wxGUI command console. <center><gallery perrow=3 widths=380 heights=190>Image:wxGUI_menu_rinfo.png|Modules can be found in wxGUI menu
Image:wxGUI_module_search.png|You can search modules by name, description or keywords in ''Search modules'' tab
Image:wxGUI_console_completion.png|By typing prefix r. we make a list of modules starting with that prefix to show up.</gallery></center>


* {{cmd|g.region|desc=Computational region}} - an important raster concept
** defined by region extent and raster resolution
** applies to all raster operations
** persists between GRASS session, can be different for different mapsets
** advantages: keeps your results consistent, avoid clipping, for computationally demanding tasks set region to smaller extent, check your result is good and then set the computational region to the entire study area and rerun analysis
** run <code>g.region -p</code> or in menu ''Settings'' - ''Region'' - ''Display region'' to see current region settings
[[File:WxGUI set region.png|700px|thumb|center|Simple ways to set computational region from GUI. On the left, set region to match raster map. On the right, select the highlighted option and then set region by drawing rectangle.]]

* GRASS 3D view

= Modeling with FUTURES =
== Initial steps and data preparation ==
First we will set the computational region of our analyses to an extent covering our study area and aligned with our base landuse rasters:
<source lang="bash">g.region raster=landuse_2011 -p</source>

We will derive urbanized areas from NLCD dataset for year 1992, 2001 and 2011
by extracting categories category 21 - 24 into a new binary map where developed is 1,
undeveloped 0 and NULL (no data) is area unsuitable for development (water, wetlands, protected areas).
First we will convert protected areas from vector to raster. We set
NULLs to zeros (for simpler raster algebra expression in the next step) using {{cmd|r.null}}:

<source lang="bash">
v.to.rast input=protected_areas output=protected_areas use=val
r.null map=protected_areas null=0
</source>

And then create rasters of developed/undeveloped areas using raster algebra:

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.mapcalc "urban_1992 = if(landuse_1992 >= 21 && landuse_1992 <= 24, 1, if(landuse_1992 == 11 || landuse_1992 >= 90 || protected_areas, null(), 0))"
r.mapcalc "urban_2001 = if(landuse_2001 >= 21 && landuse_2001 <= 24, 1, if(landuse_2001 == 11 || landuse_2001 >= 90 || protected_areas, null(), 0))"
r.mapcalc "urban_2011 = if(landuse_2011 >= 21 && landuse_2011 <= 24, 1, if(landuse_2011 == 11 || landuse_2011 >= 90 || protected_areas, null(), 0))"
</source>

We will convert vector counties to raster with the values of the FIPS attribute which links to population file:

<source lang="bash">
v.to.rast input=counties type=area use=attr attribute_column=FIPS output=counties
</source>

Before further steps, we will set our working directory so that the input population files and text files
we are going to create are saved in one directory and easily accessible.
You can do that from menu ''Settings'' → ''GRASS working environment'' → ''Change working directory''.
Select (or create) a directory and move there the downloaded files <tt>population_projection.csv</tt> and <tt>population_trend.csv</tt>.

== Potential submodel ==
Module {{AddonCmd|r.futures.potential}} implements POTENTIAL submodel as a part of FUTURES land change model. POTENTIAL is implemented using a set of coefficients that relate a selection of site suitability factors to the probability of a place becoming developed. This is implemented using the parameter table in combination with maps of those site suitability factors (mapped predictors). The coefficients are obtained by conducting multilevel logistic regression in R with package lme4 where the coefficients may vary by county. The best model is selected automatically using dredge function from package [https://cran.r-project.org/web/packages/MuMIn/index.html MuMIn].

First, we will derive couple of predictors.
=== Predictors ===
==== Slope ====
We will derive slope in degrees from digital elevation model using {{cmd|r.slope.aspect}} module:
<source lang="bash">r.slope.aspect elevation=elevation_30m slope=slope</source>

==== Distance from lakes/rivers ====
First we will extract [http://www.mrlc.gov/nlcd11_leg.php category ''Open Water''] from 2011 NLCD dataset:
<source lang="bash">
r.mapcalc "water = if(landuse_2011 == 11, 1, null())"
</source>

Then we compute the distance to water with module {{cmd|r.grow.distance}} and set color table to shades of blue:
<source lang="bash">
r.grow.distance input=water distance=dist_to_water
r.colors -n map=dist_to_water color=blues
</source>

==== Distance from protected areas ====
We will use raster protected of protected areas we already created, but we will set NULL values to zero.
We compute the distance to protected areas with module {{cmd|r.grow.distance}} and set color table from green to red:
<source lang="bash">
r.null map=protected_areas setnull=0
r.grow.distance input=protected_areas distance=dist_to_protected
r.colors map=dist_to_protected color=gyr
</source>

==== Forests ====
We will smooth the transition between forest and other land use, see NLCD [http://www.mrlc.gov/nlcd11_leg.php category ''Open Water'']:
<source lang="bash">
r.mapcalc "forest = if(landuse_2011 >= 41 && landuse_2011 <= 43, 1, 0)"
r.neighbors -c input=forest output=forest_smooth size=15 method=average
r.colors map=forest_smooth color=ndvi
</source>

==== Travel time to cities ====
Here we will compute travel time to cities (with population > 5000)
as cumulative cost distance where cost is defined as travel time on roads.
First we specify the speed on different types of roads.
We copy the roads raster into our mapset so that we can change it
by adding a new attribute field <tt>speed</tt>. Then we assign speed values (km/h) based on the type of road:

<source lang="bash">
g.copy vector=roads,myroads
v.db.addcolumn map=myroads columns="speed double precision"
v.db.update map=myroads column=speed value=50 where="MTFCC = 'S1400'"
v.db.update map=myroads column=speed value=100 where="MTFCC IN ('S1100', 'S1200')"
</source>

Now we rasterize the selected road types using the speed values from the attribute table as raster values.

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
v.to.rast input=myroads type=line where="MTFCC IN ('S1100', 'S1200', 'S1400')" output=roads_speed use=attr attribute_column=speed
</source>

We set the rest of the area to low speed and recompute the speed as time to travel through a 30m cell in minutes:

<source lang="bash">
r.null map=roads_speed null=5
r.mapcalc "roads_travel_time = 1.8 / roads_speed"
</source>

Finally we compute the travel time to larger cities using {{cmd|r.cost}}:

<source lang="bash">
r.cost input=roads_travel_time output=travel_time_cities start_points=cities
r.colors map=travel_time_cities color=byr
</source>

==== Road density ====
We will rasterize roads and use moving window analysis ({{cmd|r.neighbors}}) to compute road density:

<source lang="bash">
v.to.rast input=roads output=roads use=val type=line
r.null map=roads null=0
r.neighbors -c input=roads output=road_dens size=25 method=average
</source>

==== Distance to interchanges ====

We will consider TIGER roads of type <tt>Ramp</tt> as interchanges, rasterize them and compute euclidean distance to them:

<source lang="bash">
v.to.rast input=roads type=line where="MTFCC = 'S1630'" output=interchanges use=val
r.grow.distance -m input=interchanges distance=dist_interchanges
</source>

=== Development pressure ===

We compute development pressure with {{AddonCmd|r.futures.devpressure}}. Development pressure is a predictor based on number of neighboring developed cells within search distance, weighted by distance. The development pressure variable plays a special role in the model, allowing for a feedback between predicted change and change in subsequent steps.

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.devpressure -n input=urban_2011 output=devpressure_2 method=gravity size=7 gamma=2 scaling_factor=10
r.futures.devpressure -n input=urban_2011 output=devpressure_1 method=gravity size=10 gamma=1 scaling_factor=1
r.futures.devpressure -n input=urban_2011 output=devpressure_0_5 method=gravity size=30 gamma=0.5 scaling_factor=0.1
</source>

When gamma increases, development influence decreases more rapidly with distance.
Size is half the size of the moving window. When gamma is low, local development influences more distant places.
We will derive 3 layers with different gamma and size parameters for the potential statistical model.

=== Rescaling variables ===

First we will look at the ranges of our predictor variables by running a short Python code snippet in Python shell:

<source lang="python" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
for name in ['slope', 'dist_to_water', 'dist_to_protected', 'forest_smooth', 'travel_time_cities', 'road_dens', 'dist_interchanges', 'devpressure_0_5', 'devpressure_1']:
minmax = grass.raster_info(name)
print name, minmax['min'], minmax['max']
</source>

We will rescale some of our input variables:

<source lang="bash">
r.mapcalc "dist_to_water_km = dist_to_water / 1000"
r.mapcalc "dist_to_protected_km = dist_to_protected / 1000"
r.mapcalc "dist_interchanges_km = dist_interchanges / 1000"
r.mapcalc "road_dens_perc = road_dens * 100"
r.mapcalc "forest_smooth_perc = forest_smooth * 100"
</source>

=== Sampling ===
To sample only in the analyzed counties, we will clip development layer:

<source lang="bash">
r.mapcalc "urban_change_01_11 = if(urban_2011 == 1, if(urban_2001 == 0, 1, null()), 0)"
r.mapcalc "urban_change_clip = if(counties, urban_change_01_11)"
</source>

To estimate the number of sampling points, we can use {{cmd|r.report}} to report number of developed/undeveloped cells and their ratio.

<source lang="bash">
r.report map=urban_change_clip units=h,c,p
</source>

We will sample the predictors and the response variable with 5000 random points in undeveloped areas and 1000 points in developed area:

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.sample.category input=urban_change_clip output=sampling sampled=counties,devpressure_0_5,devpressure_1,devpressure_2,slope,road_dens_perc,forest_smooth_perc,dist_to_water_km,dist_to_protected_km,dist_interchanges_km,travel_time_cities npoints=5000,1000
</source>

The attribute table can be exported as CSV file (not necessary step):

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
v.db.select map=sampling columns=urban_change_clip,counties,devpressure_0_5,devpressure_1,slope,road_dens_perc,forest_smooth_perc,dist_to_water_km,dist_to_protected_km,dist_interchanges_km,travel_time_cities separator=comma file=samples.csv
</source>

=== Development potential ===
Now we find best model for predicting urbanization using {{AddonCmd|r.futures.potential}} which wraps an R script.

We can run R [http://www.inside-r.org/packages/cran/MuMIn/docs/dredge dredge] function to find "best" model. We can specify minimum and maximum number of predictors the final model should use.
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.potential -d input=sampling output=potential.csv columns=devpressure_1,slope,road_dens_perc,forest_smooth_perc,dist_to_water_km,dist_to_protected_km,dist_interchanges_km,travel_time_cities developed_column=urban_change_clip subregions_column=counties min_variables=4
</source>

Also, we can play with different combinations of predictors, for example:

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.potential input=sampling output=potential.csv columns=devpressure_2,road_dens_perc,slope,dist_interchanges_km,dist_to_water_km developed_column=urban_change_clip subregions_column=counties --o
r.futures.potential input=sampling output=potential.csv columns=devpressure_1,road_dens_perc,slope,dist_interchanges_km,dist_to_water_km developed_column=urban_change_clip subregions_column=counties --o
...
</source>

You can then open the output file <tt>potential.csv</tt>, which is a CSV file with tabs as separators.

For this tutorial, the final potential is created with:
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.potential input=sampling output=potential.csv columns=devpressure_2,road_dens_perc,slope,dist_interchanges_km,dist_to_water_km developed_column=urban_change_clip subregions_column=counties --o
</source>

We can now visualize the suitability surface using module {{AddonCmd|r.futures.potsurface}}. It creates initial development potential (suitability) raster from predictors and model coefficients and serves only for evaluating development potential model. The values of the resulting raster range from 0 to 1.

<source lang="bash">
r.futures.potsurface input=potential.csv subregions=counties output=suitability
r.colors map=suitability color=byr
</source>

== Demand submodel ==
First we will mask out roads so that they don't influence into per capita land demand relation.
<source lang="bash">
v.to.rast input=roads type=line output=roads_mask use=val
r.mask roads_mask -i
</source>

We will use {{AddonCmd|r.futures.demand}} which derives the population vs. development relation. The relation can be linear/logarithmic/logarithmic2/exponential/exponential approach.
Look for examples of the different relations in the manual.

* linear: y = A + Bx
* logarithmic: y = A + Bln(x)
* logarithmic2: y = A + B * ln(x - C)        (requires SciPy)
* exponential: y = Ae^(BX)
* exp_approach: y = (1 - e^(-A(x - B))) + C        (requires SciPy)

The format of the input population CSV files is described in the manual. It is important to have synchronized categories of subregions and the column headers of the CSV files (in our case FIPS number). How to simply generate the list of years (for which demand is computed) is described in {{AddonCmd|r.futures.demand}} manual, for example run this in Python console:

<source lang="python">
','.join([str(i) for i in range(2011, 2036)])
</source>

Then we can create the DEMAND file:
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.demand development=urban_1992,urban_2001,urban_2011 subregions=counties observed_population=population_trend.csv projected_population=population_projection.csv simulation_times=2011,2012,2013,2014,2015,2016,2017,2018,2019,2020,2021,2022,2023,2024,2025,2026,2027,2028,2029,2030,2031,2032,2033,2034,2035 plot=plot_demand.pdf demand=demand.csv separator=comma
</source>

In your current working directory, you should find files <tt>plot_demand.png</tt> and <tt>demand.csv</tt>.

If you have SciPy installed, you can experiment with other methods for fitting the functions:
<source lang="bash">
r.futures.demand ... method=logarithmic2
r.futures.demand ... method=exp_approach
</source>
If necessary, you can create a set of demand files produced by fitting each method separately and
then pick for each county the method which seems best and manually create a new demand file.

When you are finished, remove the mask as it is not needed for the next steps.
<source lang="bash">
r.mask -r
</source>

== Patch calibration ==
Patch calibration can be a very time consuming computation.
Therefore we select only one county (Buncombe):

<source lang="bash">
v.to.rast input=counties type=area where="FIPS == 37021" use=attr attribute_column=FIPS output=calib_county
g.region raster=calib_county zoom=calib_county
</source>
to derive patches of new development by comparing historical and latest development.
We can keep only patches with minimum size 2 cells (1800 = 2 x 30 x 30 m).

<source lang="bash">
r.futures.calib development_start=urban_1992 development_end=urban_2011 subregions=counties patch_sizes=patches.txt patch_threshold=1800 -l
</source>
We obtained a file <tt>patches.txt</tt> (used later in the PGA) - a patch size distribution file - containing sizes of all found patches.

We can look at the distribution of the patch sizes:

<source lang="python">
from matplotlib import pyplot as plt
with open('patches.txt') as f:
patches = [int(patch) for patch in f.readlines()]
plt.hist(patches, 2000)
plt.xlim(0,50)
plt.show()
</source>

At this point, we start the calibration to get best parameters of patch shape
(for this tutorial, this step can be skipped and the suggested parameters are used).

<source lang="bash"
style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.calib development_start=urban_1992 development_end=urban_2011 subregions=calib_county patch_sizes=patches.txt calibration_results=calib.csv patch_threshold=1800 repeat=5 compactness_mean=0.1,0.3,0.5,0.7,0.9 compactness_range=0.05 discount_factor=0.1,0.3,0.5,0.7,0.9 predictors=road_dens_perc,forest_smooth_perc,dist_to_protected_km demand=demand.csv devpot_params=potential.csv num_neighbors=4 seed_search=2 development_pressure=devpressure_0_5 development_pressure_approach=gravity n_dev_neighbourhood=30 gamma=0.5 scaling_factor=0.1
</source>

== FUTURES simulation ==
We will switch back to our previous region:
<source lang="bash">
g.region raster=landuse_2011 -p
</source>

Now we have all the inputs necessary for running {{AddonCmd|r.futures.pga}}:

The entire command is here:
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.pga subregions=counties developed=urban_2011 predictors=slope,forest_smooth_perc,dist_interchanges_km,travel_time_cities devpot_params=potential.csv development_pressure=devpressure_1 n_dev_neighbourhood=10 development_pressure_approach=gravity gamma=1 scaling_factor=1 demand=demand.csv discount_factor=0.3 compactness_mean=0.2 compactness_range=0.1 patch_sizes=patches.txt num_neighbors=4 seed_search=2 random_seed=1 output=final output_series=final
</source>

=== Quick description ===
The command parameters and their values:
* raster map of counties with their categories
<code>
... subregions=counties ...
</code>

* raster of developed (1), undeveloped (0) and NULLs for undevelopable areas
<code>
... developed=urban_2011 ...
</code>

* predictors selected with {{AddonCmd|r.futures.potential}} and their coefficients in a <tt>potential.csv</tt> file. The order of predictors must match the order in the file and the categories of the counties must match raster <tt>counties</tt>.
<code>
... predictors=slope,forest_smooth_perc,dist_interchanges_km,travel_time_cities devpot_params=potential.csv ...
</code>

* initial development pressure computed by {{AddonCmd|r.futures.devpressure}}, it's important to set here the same parameters
<code>
... development_pressure=devpressure_1 n_dev_neighbourhood=10 development_pressure_approach=gravity gamma=1 scaling_factor=1 ...
</code>

* per capita land demand computed by {{AddonCmd|r.futures.demand}}, the categories of the counties must match raster <tt>counties</tt>.
<code>
... demand=demand.csv ...
</code>

* patch parameters from the calibration step
<code>
... discount_factor=0.3 compactness_mean=0.4 compactness_range=0.08 patch_sizes=patches.txt ...
</code>

* recommended parameters for patch growing algorithm
<code>
... num_neighbors=4 seed_search=2 ...
</code>

* set random seed for repeatable results or set flag <tt>-s</tt> to generate seed automatically
<code>
... random_seed=1 ...
</code>

* specify final output map and optionally basename for intermediate raster maps
<code>
output=final output_series=final
</code>

== Scenarios ==
Scenarios involving policies that encourage infill versus sprawl can be explored using the <tt>incentive_power</tt> parameter of {{AddonCmd|r.futures.pga}},
which uses a power function to transform the evenness of the probability gradient in POTENTIAL. You can change the power to a number between 0.25 and 4 to test urban sprawl/infill scenarios.
Higher power leads to infill behavior, lower power to urban sprawl.

== Postprocessing ==

Follow a [[Creating_animation_from_FUTURES_output_in_GRASS_GIS| tutorial how to make an animation from the results]].

= GRASS GIS Python API =

[[Category: Tutorial]]
[[Category: FUTURES]]
[[Category: Urban]]

Workshop on urban growth modeling with FUTURES

2016-03-22T18:45:25Z

⚠️Dbvanber: /* Setting up GRASS for the tutorial */

{{ToModify}}
= Workshop introduction =
r.futures.* is an implementation of the '''FUT'''ure '''U'''rban-'''R'''egional '''E'''nvironment '''S'''imulation (FUTURES)[1] which is a model for multilevel simulations of emerging urban-rural landscape structure. FUTURES produces regional projections of landscape patterns using coupled submodels that integrate nonstationary drivers of land change: per capita demand (DEMAND submodel), site suitability (POTENTIAL submodel), and the spatial structure of conversion events (PGA submodel).

[1] Meentemeyer, R. K., Tang, W., Dorning, M. A., Vogler, J. B., Cunniffe, N. J., & Shoemaker, D. A. (2013). [http://www.tandfonline.com/doi/abs/10.1080/00045608.2012.707591 FUTURES: multilevel simulations of emerging urban-rural landscape structure using a stochastic patch-growing algorithm.] Annals of the Association of American Geographers, 103(4), 785-807

== Software ==
There are a number of software requirements to run FUTURES that will need to be download and installed. Required software includes:
* GRASS GIS 7
* addons
** {{AddonCmd|r.futures.pga}}
** {{AddonCmd|r.futures.potential}}
** {{AddonCmd|r.futures.potsurface}}
** {{AddonCmd|r.futures.demand}}
** {{AddonCmd|r.futures.devpressure}}
** {{AddonCmd|r.sample.category}}
* R (≥ 3.0.2) - needed for {{AddonCmd|r.futures.potential}} with packages:
**MuMIn, lme4, optparse, rgrass7
* SciPy - useful for {{AddonCmd|r.futures.demand}}

=== Installation ===
We use the R statistical software for our calculation of site suitability (i.e. development potential) in FUTURES. R is a free software environment for statistical computing and graphics. If you don't have R, or you have older an version, please download and install the software from [http://archive.linux.duke.edu/cran/ install R] and be sure to additionally add these required packages:
<pre>
install.packages(c("MuMIn", "lme4", "optparse", "rgrass7"))
</pre>

==== MS Windows ====
We will be using GRASS GIS 7.0.3 that can be found here in the [https://trac.osgeo.org/osgeo4w/ OSGeo4W] package manager.
Please install the latest stable GRASS GIS 7 version and the SciPy Python package using the ''Advanced install'' option.
A guide with step by step screen shot instructions is available [https://docs.google.com/presentation/d/1yEGpriBne7RvjB35HI6GecNwO1P1y2nRGqDThqoNnCE/edit?usp=sharing here].

In order for GRASS to be able to find R executables, GRASS must be on the PATH variable. Follow this [solution] to make R accessible from GRASS permanently.
A simple but temporary solution is to open GRASS GIS and paste this in the black terminal:
<pre>
set PATH=%PATH%;C:\Program Files\R\R-3.0.2\bin
</pre>
This has to be repeated after restarting GRASS session.

==== Ubuntu Linux ====
Install GRASS GIS from packages:
<pre>
sudo add-apt-repository ppa:ubuntugis/ubuntugis-unstable
sudo apt-get update
sudo apt-get install grass
</pre>

== Workshop data ==
The data that we will be using for the workshop can be download here: [http://fatra.cnr.ncsu.edu/futures/futures_ncspm_Asheville.zip sample dataset]. Please place these layers in your local GRASS directory:
* digital elevation model ([http://nationalmap.gov/elevation.html NED])
* [http://www.mrlc.gov/ NLCD] 2001, 2011
* NLCD 1992/2001 Retrofit Land Cover Change Product
* transportation network ([http://www.census.gov/geo/maps-data/data/tiger-line.html TIGER])
* county boundaries ([http://www.census.gov/geo/maps-data/data/tiger-line.html TIGER])
* protected areas ([http://www.conservationgateway.org/ConservationByGeography/NorthAmerica/UnitedStates/edc/reportsdata/terrestrial/secured/Pages/default.aspx Secured Lands])
* cities as points (USGS)

In addition, download [http://fatra.cnr.ncsu.edu/futures/futures_Asheville_files.zip population information as text files]:
* county population past estimates and future projections ([https://www.osbm.nc.gov/demog/county-projections NC OSBM]) per county (nonspatial)

= GRASS GIS introduction =
There are many advantages to using the open source GRASS GIS platform, but for many that are more familiar with ARCGis and QGis, the setup and implementation of spatial tools in GRASS can be confusing. Here we provide an overview of the GRASS GIS project: [https://grass.osgeo.org grass.osgeo.org] that might be helpful to review if you are a first time users. For this exercise it's not necessary to have a full understanding of how to use GRASS. However, you will need to know how to place your data in the correct GRASS database directory, as well as some basic GRASS functionality. Step by step instructions are provided below
== Setting up GRASS for the tutorial ==
GRASS uses unique database terminology and structure ([https://grass.osgeo.org/grass71/manuals/grass_database.html GRASS database]) that are important to understand for the set up of this tutorial, as you will need to place the required data (e.g. Mapset) in a specific GRASS database Location. In the following we review important terminology and give step by step direction on how to download and place you data in the correct location.

=== Important GRASS directory terminology ===
* A '''GRASS database''' consist of directory with specific Locations (projects) where data layer are stored
* '''Location''' hold all Mapsets in a specific directoy that have the same spatial projection (spatial reference system)
* '''Mapset''' are a collection of maps with the same spatial projection

=== Creating a GRASS database for the tutorial ===
You need to create a GRASS database with the Mapset that we will use for the tutorial before we can run the FUTURES model. Please Download the [http://fatra.cnr.ncsu.edu/futures/futures_ncspm_Asheville.zip workshop location], noting where the files are located on your local directory. Now, create (unless you already have it) a directory named <tt>grassdata</tt> (GRASS database) in your home folder (or Documents), unzip the downloaded data into this directory. You should now have a Location <tt>futures_ncspm</tt> in <tt>grassdata</tt>.
* Launch GRASS and display raster, vector data, explore navigation, querying, adding legend, showing metadata
<center><gallery perrow=3 widths=500 heights=250>Image:GRASS FUTURES startup.png|GRASS GIS 7.0.3 startup dialog with downloaded Location and Mapsets for FUTURES workshop
Image:GRASS FUTURES wxGUI display.png|Layer Manager and Map Display overview. Annotations show how to add raster layer, query, add legend.
Image:wxGUI_metadata_rinfo.png|Show raster map metadata by right click on layer</gallery></center>

* GRASS GIS has over [https://grass.osgeo.org/grass70/manuals/full_index.html 500 different modules] in the core distribution and over [https://grass.osgeo.org/grass70/manuals/addons/ 230 addon modules]
<center>
{| class="wikitable"
|-
! Prefix !! Function !! Example
|-
| r.* || raster processing || ''{{cmd|r.mapcalc}}'': map algebra
|-
| v.* || vector processing || ''{{cmd|v.clean}}'': topological cleaning
|-
| i.* || imagery processing || ''{{cmd|i.segment}}'': object recognition
|-
| db.* || database management || ''{{cmd|db.select}}'': select values from table
|-
| r3.* || 3D raster processing || ''{{cmd|r3.stats}}'': 3D raster statistics
|-
| t.* || temporal data processing || ''{{cmd|t.rast.aggregate}}'': temporal aggregation
|-
| g.* || general data management || ''{{cmd|g.rename}}'': renames map
|-
| d.* || display ||''{{cmd|d.rast}}'': display raster map
|}</center>
* GRASS modules have GUI and command line interface. In this workshop we use commands to describe the workflow, but we can use both GUI and command line depending on personal preference. Look how {{cmd|wxGUI.modules|version=71|desc=GUI and command line interface}} represent the same tool. ''Task:'' compute aspect (orientation) from provided digital elevation model using module {{cmd|r.slope.aspect}} using both module dialog and command line.
* How to find modules? Modules are organized by their functionality in wxGUI menu, or we can search for them in Search modules tab. If we already know which module to use, we can just type it in the wxGUI command console. <center><gallery perrow=3 widths=380 heights=190>Image:wxGUI_menu_rinfo.png|Modules can be found in wxGUI menu
Image:wxGUI_module_search.png|You can search modules by name, description or keywords in ''Search modules'' tab
Image:wxGUI_console_completion.png|By typing prefix r. we make a list of modules starting with that prefix to show up.</gallery></center>


* {{cmd|g.region|desc=Computational region}} - an important raster concept
** defined by region extent and raster resolution
** applies to all raster operations
** persists between GRASS session, can be different for different mapsets
** advantages: keeps your results consistent, avoid clipping, for computationally demanding tasks set region to smaller extent, check your result is good and then set the computational region to the entire study area and rerun analysis
** run <code>g.region -p</code> or in menu ''Settings'' - ''Region'' - ''Display region'' to see current region settings
[[File:WxGUI set region.png|700px|thumb|center|Simple ways to set computational region from GUI. On the left, set region to match raster map. On the right, select the highlighted option and then set region by drawing rectangle.]]

* GRASS 3D view

= Modeling with FUTURES =
== Initial steps and data preparation ==
First we will set the computational region of our analyses to an extent covering our study area and aligned with our base landuse rasters:
<source lang="bash">g.region raster=landuse_2011 -p</source>

We will derive urbanized areas from NLCD dataset for year 1992, 2001 and 2011
by extracting categories category 21 - 24 into a new binary map where developed is 1,
undeveloped 0 and NULL (no data) is area unsuitable for development (water, wetlands, protected areas).
First we will convert protected areas from vector to raster. We set
NULLs to zeros (for simpler raster algebra expression in the next step) using {{cmd|r.null}}:

<source lang="bash">
v.to.rast input=protected_areas output=protected_areas use=val
r.null map=protected_areas null=0
</source>

And then create rasters of developed/undeveloped areas using raster algebra:

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.mapcalc "urban_1992 = if(landuse_1992 >= 21 && landuse_1992 <= 24, 1, if(landuse_1992 == 11 || landuse_1992 >= 90 || protected_areas, null(), 0))"
r.mapcalc "urban_2001 = if(landuse_2001 >= 21 && landuse_2001 <= 24, 1, if(landuse_2001 == 11 || landuse_2001 >= 90 || protected_areas, null(), 0))"
r.mapcalc "urban_2011 = if(landuse_2011 >= 21 && landuse_2011 <= 24, 1, if(landuse_2011 == 11 || landuse_2011 >= 90 || protected_areas, null(), 0))"
</source>

We will convert vector counties to raster with the values of the FIPS attribute which links to population file:

<source lang="bash">
v.to.rast input=counties type=area use=attr attribute_column=FIPS output=counties
</source>

Before further steps, we will set our working directory so that the input population files and text files
we are going to create are saved in one directory and easily accessible.
You can do that from menu ''Settings'' → ''GRASS working environment'' → ''Change working directory''.
Select (or create) a directory and move there the downloaded files <tt>population_projection.csv</tt> and <tt>population_trend.csv</tt>.

== Potential submodel ==
Module {{AddonCmd|r.futures.potential}} implements POTENTIAL submodel as a part of FUTURES land change model. POTENTIAL is implemented using a set of coefficients that relate a selection of site suitability factors to the probability of a place becoming developed. This is implemented using the parameter table in combination with maps of those site suitability factors (mapped predictors). The coefficients are obtained by conducting multilevel logistic regression in R with package lme4 where the coefficients may vary by county. The best model is selected automatically using dredge function from package [https://cran.r-project.org/web/packages/MuMIn/index.html MuMIn].

First, we will derive couple of predictors.
=== Predictors ===
==== Slope ====
We will derive slope in degrees from digital elevation model using {{cmd|r.slope.aspect}} module:
<source lang="bash">r.slope.aspect elevation=elevation_30m slope=slope</source>

==== Distance from lakes/rivers ====
First we will extract [http://www.mrlc.gov/nlcd11_leg.php category ''Open Water''] from 2011 NLCD dataset:
<source lang="bash">
r.mapcalc "water = if(landuse_2011 == 11, 1, null())"
</source>

Then we compute the distance to water with module {{cmd|r.grow.distance}} and set color table to shades of blue:
<source lang="bash">
r.grow.distance input=water distance=dist_to_water
r.colors -n map=dist_to_water color=blues
</source>

==== Distance from protected areas ====
We will use raster protected of protected areas we already created, but we will set NULL values to zero.
We compute the distance to protected areas with module {{cmd|r.grow.distance}} and set color table from green to red:
<source lang="bash">
r.null map=protected_areas setnull=0
r.grow.distance input=protected_areas distance=dist_to_protected
r.colors map=dist_to_protected color=gyr
</source>

==== Forests ====
We will smooth the transition between forest and other land use, see NLCD [http://www.mrlc.gov/nlcd11_leg.php category ''Open Water'']:
<source lang="bash">
r.mapcalc "forest = if(landuse_2011 >= 41 && landuse_2011 <= 43, 1, 0)"
r.neighbors -c input=forest output=forest_smooth size=15 method=average
r.colors map=forest_smooth color=ndvi
</source>

==== Travel time to cities ====
Here we will compute travel time to cities (with population > 5000)
as cumulative cost distance where cost is defined as travel time on roads.
First we specify the speed on different types of roads.
We copy the roads raster into our mapset so that we can change it
by adding a new attribute field <tt>speed</tt>. Then we assign speed values (km/h) based on the type of road:

<source lang="bash">
g.copy vector=roads,myroads
v.db.addcolumn map=myroads columns="speed double precision"
v.db.update map=myroads column=speed value=50 where="MTFCC = 'S1400'"
v.db.update map=myroads column=speed value=100 where="MTFCC IN ('S1100', 'S1200')"
</source>

Now we rasterize the selected road types using the speed values from the attribute table as raster values.

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
v.to.rast input=myroads type=line where="MTFCC IN ('S1100', 'S1200', 'S1400')" output=roads_speed use=attr attribute_column=speed
</source>

We set the rest of the area to low speed and recompute the speed as time to travel through a 30m cell in minutes:

<source lang="bash">
r.null map=roads_speed null=5
r.mapcalc "roads_travel_time = 1.8 / roads_speed"
</source>

Finally we compute the travel time to larger cities using {{cmd|r.cost}}:

<source lang="bash">
r.cost input=roads_travel_time output=travel_time_cities start_points=cities
r.colors map=travel_time_cities color=byr
</source>

==== Road density ====
We will rasterize roads and use moving window analysis ({{cmd|r.neighbors}}) to compute road density:

<source lang="bash">
v.to.rast input=roads output=roads use=val type=line
r.null map=roads null=0
r.neighbors -c input=roads output=road_dens size=25 method=average
</source>

==== Distance to interchanges ====

We will consider TIGER roads of type <tt>Ramp</tt> as interchanges, rasterize them and compute euclidean distance to them:

<source lang="bash">
v.to.rast input=roads type=line where="MTFCC = 'S1630'" output=interchanges use=val
r.grow.distance -m input=interchanges distance=dist_interchanges
</source>

=== Development pressure ===

We compute development pressure with {{AddonCmd|r.futures.devpressure}}. Development pressure is a predictor based on number of neighboring developed cells within search distance, weighted by distance. The development pressure variable plays a special role in the model, allowing for a feedback between predicted change and change in subsequent steps.

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.devpressure -n input=urban_2011 output=devpressure_2 method=gravity size=7 gamma=2 scaling_factor=10
r.futures.devpressure -n input=urban_2011 output=devpressure_1 method=gravity size=10 gamma=1 scaling_factor=1
r.futures.devpressure -n input=urban_2011 output=devpressure_0_5 method=gravity size=30 gamma=0.5 scaling_factor=0.1
</source>

When gamma increases, development influence decreases more rapidly with distance.
Size is half the size of the moving window. When gamma is low, local development influences more distant places.
We will derive 3 layers with different gamma and size parameters for the potential statistical model.

=== Rescaling variables ===

First we will look at the ranges of our predictor variables by running a short Python code snippet in Python shell:

<source lang="python" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
for name in ['slope', 'dist_to_water', 'dist_to_protected', 'forest_smooth', 'travel_time_cities', 'road_dens', 'dist_interchanges', 'devpressure_0_5', 'devpressure_1']:
minmax = grass.raster_info(name)
print name, minmax['min'], minmax['max']
</source>

We will rescale some of our input variables:

<source lang="bash">
r.mapcalc "dist_to_water_km = dist_to_water / 1000"
r.mapcalc "dist_to_protected_km = dist_to_protected / 1000"
r.mapcalc "dist_interchanges_km = dist_interchanges / 1000"
r.mapcalc "road_dens_perc = road_dens * 100"
r.mapcalc "forest_smooth_perc = forest_smooth * 100"
</source>

=== Sampling ===
To sample only in the analyzed counties, we will clip development layer:

<source lang="bash">
r.mapcalc "urban_change_01_11 = if(urban_2011 == 1, if(urban_2001 == 0, 1, null()), 0)"
r.mapcalc "urban_change_clip = if(counties, urban_change_01_11)"
</source>

To estimate the number of sampling points, we can use {{cmd|r.report}} to report number of developed/undeveloped cells and their ratio.

<source lang="bash">
r.report map=urban_change_clip units=h,c,p
</source>

We will sample the predictors and the response variable with 5000 random points in undeveloped areas and 1000 points in developed area:

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.sample.category input=urban_change_clip output=sampling sampled=counties,devpressure_0_5,devpressure_1,devpressure_2,slope,road_dens_perc,forest_smooth_perc,dist_to_water_km,dist_to_protected_km,dist_interchanges_km,travel_time_cities npoints=5000,1000
</source>

The attribute table can be exported as CSV file (not necessary step):

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
v.db.select map=sampling columns=urban_change_clip,counties,devpressure_0_5,devpressure_1,slope,road_dens_perc,forest_smooth_perc,dist_to_water_km,dist_to_protected_km,dist_interchanges_km,travel_time_cities separator=comma file=samples.csv
</source>

=== Development potential ===
Now we find best model for predicting urbanization using {{AddonCmd|r.futures.potential}} which wraps an R script.

We can run R [http://www.inside-r.org/packages/cran/MuMIn/docs/dredge dredge] function to find "best" model. We can specify minimum and maximum number of predictors the final model should use.
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.potential -d input=sampling output=potential.csv columns=devpressure_1,slope,road_dens_perc,forest_smooth_perc,dist_to_water_km,dist_to_protected_km,dist_interchanges_km,travel_time_cities developed_column=urban_change_clip subregions_column=counties min_variables=4
</source>

Also, we can play with different combinations of predictors, for example:

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.potential input=sampling output=potential.csv columns=devpressure_2,road_dens_perc,slope,dist_interchanges_km,dist_to_water_km developed_column=urban_change_clip subregions_column=counties --o
r.futures.potential input=sampling output=potential.csv columns=devpressure_1,road_dens_perc,slope,dist_interchanges_km,dist_to_water_km developed_column=urban_change_clip subregions_column=counties --o
...
</source>

You can then open the output file <tt>potential.csv</tt>, which is a CSV file with tabs as separators.

For this tutorial, the final potential is created with:
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.potential input=sampling output=potential.csv columns=devpressure_2,road_dens_perc,slope,dist_interchanges_km,dist_to_water_km developed_column=urban_change_clip subregions_column=counties --o
</source>

We can now visualize the suitability surface using module {{AddonCmd|r.futures.potsurface}}. It creates initial development potential (suitability) raster from predictors and model coefficients and serves only for evaluating development potential model. The values of the resulting raster range from 0 to 1.

<source lang="bash">
r.futures.potsurface input=potential.csv subregions=counties output=suitability
r.colors map=suitability color=byr
</source>

== Demand submodel ==
First we will mask out roads so that they don't influence into per capita land demand relation.
<source lang="bash">
v.to.rast input=roads type=line output=roads_mask use=val
r.mask roads_mask -i
</source>

We will use {{AddonCmd|r.futures.demand}} which derives the population vs. development relation. The relation can be linear/logarithmic/logarithmic2/exponential/exponential approach.
Look for examples of the different relations in the manual.

* linear: y = A + Bx
* logarithmic: y = A + Bln(x)
* logarithmic2: y = A + B * ln(x - C)        (requires SciPy)
* exponential: y = Ae^(BX)
* exp_approach: y = (1 - e^(-A(x - B))) + C        (requires SciPy)

The format of the input population CSV files is described in the manual. It is important to have synchronized categories of subregions and the column headers of the CSV files (in our case FIPS number). How to simply generate the list of years (for which demand is computed) is described in {{AddonCmd|r.futures.demand}} manual, for example run this in Python console:

<source lang="python">
','.join([str(i) for i in range(2011, 2036)])
</source>

Then we can create the DEMAND file:
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.demand development=urban_1992,urban_2001,urban_2011 subregions=counties observed_population=population_trend.csv projected_population=population_projection.csv simulation_times=2011,2012,2013,2014,2015,2016,2017,2018,2019,2020,2021,2022,2023,2024,2025,2026,2027,2028,2029,2030,2031,2032,2033,2034,2035 plot=plot_demand.pdf demand=demand.csv separator=comma
</source>

In your current working directory, you should find files <tt>plot_demand.png</tt> and <tt>demand.csv</tt>.

If you have SciPy installed, you can experiment with other methods for fitting the functions:
<source lang="bash">
r.futures.demand ... method=logarithmic2
r.futures.demand ... method=exp_approach
</source>
If necessary, you can create a set of demand files produced by fitting each method separately and
then pick for each county the method which seems best and manually create a new demand file.

When you are finished, remove the mask as it is not needed for the next steps.
<source lang="bash">
r.mask -r
</source>

== Patch calibration ==
Patch calibration can be a very time consuming computation.
Therefore we select only one county (Buncombe):

<source lang="bash">
v.to.rast input=counties type=area where="FIPS == 37021" use=attr attribute_column=FIPS output=calib_county
g.region raster=calib_county zoom=calib_county
</source>
to derive patches of new development by comparing historical and latest development.
We can keep only patches with minimum size 2 cells (1800 = 2 x 30 x 30 m).

<source lang="bash">
r.futures.calib development_start=urban_1992 development_end=urban_2011 subregions=counties patch_sizes=patches.txt patch_threshold=1800 -l
</source>
We obtained a file <tt>patches.txt</tt> (used later in the PGA) - a patch size distribution file - containing sizes of all found patches.

We can look at the distribution of the patch sizes:

<source lang="python">
from matplotlib import pyplot as plt
with open('patches.txt') as f:
patches = [int(patch) for patch in f.readlines()]
plt.hist(patches, 2000)
plt.xlim(0,50)
plt.show()
</source>

At this point, we start the calibration to get best parameters of patch shape
(for this tutorial, this step can be skipped and the suggested parameters are used).

<source lang="bash"
style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.calib development_start=urban_1992 development_end=urban_2011 subregions=calib_county patch_sizes=patches.txt calibration_results=calib.csv patch_threshold=1800 repeat=5 compactness_mean=0.1,0.3,0.5,0.7,0.9 compactness_range=0.05 discount_factor=0.1,0.3,0.5,0.7,0.9 predictors=road_dens_perc,forest_smooth_perc,dist_to_protected_km demand=demand.csv devpot_params=potential.csv num_neighbors=4 seed_search=2 development_pressure=devpressure_0_5 development_pressure_approach=gravity n_dev_neighbourhood=30 gamma=0.5 scaling_factor=0.1
</source>

== FUTURES simulation ==
We will switch back to our previous region:
<source lang="bash">
g.region raster=landuse_2011 -p
</source>

Now we have all the inputs necessary for running {{AddonCmd|r.futures.pga}}:

The entire command is here:
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.pga subregions=counties developed=urban_2011 predictors=slope,forest_smooth_perc,dist_interchanges_km,travel_time_cities devpot_params=potential.csv development_pressure=devpressure_1 n_dev_neighbourhood=10 development_pressure_approach=gravity gamma=1 scaling_factor=1 demand=demand.csv discount_factor=0.3 compactness_mean=0.2 compactness_range=0.1 patch_sizes=patches.txt num_neighbors=4 seed_search=2 random_seed=1 output=final output_series=final
</source>

=== Quick description ===
The command parameters and their values:
* raster map of counties with their categories
<code>
... subregions=counties ...
</code>

* raster of developed (1), undeveloped (0) and NULLs for undevelopable areas
<code>
... developed=urban_2011 ...
</code>

* predictors selected with {{AddonCmd|r.futures.potential}} and their coefficients in a <tt>potential.csv</tt> file. The order of predictors must match the order in the file and the categories of the counties must match raster <tt>counties</tt>.
<code>
... predictors=slope,forest_smooth_perc,dist_interchanges_km,travel_time_cities devpot_params=potential.csv ...
</code>

* initial development pressure computed by {{AddonCmd|r.futures.devpressure}}, it's important to set here the same parameters
<code>
... development_pressure=devpressure_1 n_dev_neighbourhood=10 development_pressure_approach=gravity gamma=1 scaling_factor=1 ...
</code>

* per capita land demand computed by {{AddonCmd|r.futures.demand}}, the categories of the counties must match raster <tt>counties</tt>.
<code>
... demand=demand.csv ...
</code>

* patch parameters from the calibration step
<code>
... discount_factor=0.3 compactness_mean=0.4 compactness_range=0.08 patch_sizes=patches.txt ...
</code>

* recommended parameters for patch growing algorithm
<code>
... num_neighbors=4 seed_search=2 ...
</code>

* set random seed for repeatable results or set flag <tt>-s</tt> to generate seed automatically
<code>
... random_seed=1 ...
</code>

* specify final output map and optionally basename for intermediate raster maps
<code>
output=final output_series=final
</code>

== Scenarios ==
Scenarios involving policies that encourage infill versus sprawl can be explored using the <tt>incentive_power</tt> parameter of {{AddonCmd|r.futures.pga}},
which uses a power function to transform the evenness of the probability gradient in POTENTIAL. You can change the power to a number between 0.25 and 4 to test urban sprawl/infill scenarios.
Higher power leads to infill behavior, lower power to urban sprawl.

== Postprocessing ==

Follow a [[Creating_animation_from_FUTURES_output_in_GRASS_GIS| tutorial how to make an animation from the results]].

= GRASS GIS Python API =

[[Category: Tutorial]]
[[Category: FUTURES]]
[[Category: Urban]]

Workshop on urban growth modeling with FUTURES

2016-03-22T18:43:52Z

⚠️Dbvanber: /* GRASS directory system */

{{ToModify}}
= Workshop introduction =
r.futures.* is an implementation of the '''FUT'''ure '''U'''rban-'''R'''egional '''E'''nvironment '''S'''imulation (FUTURES)[1] which is a model for multilevel simulations of emerging urban-rural landscape structure. FUTURES produces regional projections of landscape patterns using coupled submodels that integrate nonstationary drivers of land change: per capita demand (DEMAND submodel), site suitability (POTENTIAL submodel), and the spatial structure of conversion events (PGA submodel).

[1] Meentemeyer, R. K., Tang, W., Dorning, M. A., Vogler, J. B., Cunniffe, N. J., & Shoemaker, D. A. (2013). [http://www.tandfonline.com/doi/abs/10.1080/00045608.2012.707591 FUTURES: multilevel simulations of emerging urban-rural landscape structure using a stochastic patch-growing algorithm.] Annals of the Association of American Geographers, 103(4), 785-807

== Software ==
There are a number of software requirements to run FUTURES that will need to be download and installed. Required software includes:
* GRASS GIS 7
* addons
** {{AddonCmd|r.futures.pga}}
** {{AddonCmd|r.futures.potential}}
** {{AddonCmd|r.futures.potsurface}}
** {{AddonCmd|r.futures.demand}}
** {{AddonCmd|r.futures.devpressure}}
** {{AddonCmd|r.sample.category}}
* R (≥ 3.0.2) - needed for {{AddonCmd|r.futures.potential}} with packages:
**MuMIn, lme4, optparse, rgrass7
* SciPy - useful for {{AddonCmd|r.futures.demand}}

=== Installation ===
We use the R statistical software for our calculation of site suitability (i.e. development potential) in FUTURES. R is a free software environment for statistical computing and graphics. If you don't have R, or you have older an version, please download and install the software from [http://archive.linux.duke.edu/cran/ install R] and be sure to additionally add these required packages:
<pre>
install.packages(c("MuMIn", "lme4", "optparse", "rgrass7"))
</pre>

==== MS Windows ====
We will be using GRASS GIS 7.0.3 that can be found here in the [https://trac.osgeo.org/osgeo4w/ OSGeo4W] package manager.
Please install the latest stable GRASS GIS 7 version and the SciPy Python package using the ''Advanced install'' option.
A guide with step by step screen shot instructions is available [https://docs.google.com/presentation/d/1yEGpriBne7RvjB35HI6GecNwO1P1y2nRGqDThqoNnCE/edit?usp=sharing here].

In order for GRASS to be able to find R executables, GRASS must be on the PATH variable. Follow this [solution] to make R accessible from GRASS permanently.
A simple but temporary solution is to open GRASS GIS and paste this in the black terminal:
<pre>
set PATH=%PATH%;C:\Program Files\R\R-3.0.2\bin
</pre>
This has to be repeated after restarting GRASS session.

==== Ubuntu Linux ====
Install GRASS GIS from packages:
<pre>
sudo add-apt-repository ppa:ubuntugis/ubuntugis-unstable
sudo apt-get update
sudo apt-get install grass
</pre>

== Workshop data ==
The data that we will be using for the workshop can be download here: [http://fatra.cnr.ncsu.edu/futures/futures_ncspm_Asheville.zip sample dataset]. Please place these layers in your local GRASS directory:
* digital elevation model ([http://nationalmap.gov/elevation.html NED])
* [http://www.mrlc.gov/ NLCD] 2001, 2011
* NLCD 1992/2001 Retrofit Land Cover Change Product
* transportation network ([http://www.census.gov/geo/maps-data/data/tiger-line.html TIGER])
* county boundaries ([http://www.census.gov/geo/maps-data/data/tiger-line.html TIGER])
* protected areas ([http://www.conservationgateway.org/ConservationByGeography/NorthAmerica/UnitedStates/edc/reportsdata/terrestrial/secured/Pages/default.aspx Secured Lands])
* cities as points (USGS)

In addition, download [http://fatra.cnr.ncsu.edu/futures/futures_Asheville_files.zip population information as text files]:
* county population past estimates and future projections ([https://www.osbm.nc.gov/demog/county-projections NC OSBM]) per county (nonspatial)

= GRASS GIS introduction =
There are many advantages to using the open source GRASS GIS platform, but for many that are more familiar with ARCGis and QGis, the setup and implementation of spatial tools in GRASS can be confusing. Here we provide an overview of the GRASS GIS project: [https://grass.osgeo.org grass.osgeo.org] that might be helpful to review if you are a first time users. For this exercise it's not necessary to have a full understanding of how to use GRASS. However, you will need to know how to place your data in the correct GRASS database directory, as well as some basic GRASS functionality. Step by step instructions are provided below
== Setting up GRASS for the tutorial ==
GRASS uses unique database terminology and structure ([https://grass.osgeo.org/grass71/manuals/grass_database.html GRASS database]) that are important to understand for the set up of this tutorial, as you will need to place the required data (e.g. Mapset) in a specific GRASS database Location.

=== Important GRASS directory terminology ===
* A '''GRASS database''' consist of directory with specific Locations (projects) where data layer are stored
* '''Location''' hold all Mapsets in a specific directoy that have the same spatial projection (spatial reference system)
* '''Mapset''' are a collection of maps with the same spatial projection

=== Creating a GRASS database for the tutorial ===
You need to create a GRASS database with the Mapset that we will use for the tutorial before we can run the FUTURES model. Please Download the [http://fatra.cnr.ncsu.edu/futures/futures_ncspm_Asheville.zip workshop location], noting where the files are located on your local directory. Now, create (unless you already have it) a directory named <tt>grassdata</tt> (GRASS database) in your home folder (or Documents), unzip the downloaded data into this directory. You should now have a Location <tt>futures_ncspm</tt> in <tt>grassdata</tt>.
* Launch GRASS and display raster, vector data, explore navigation, querying, adding legend, showing metadata
<center><gallery perrow=3 widths=500 heights=250>Image:GRASS FUTURES startup.png|GRASS GIS 7.0.3 startup dialog with downloaded Location and Mapsets for FUTURES workshop
Image:GRASS FUTURES wxGUI display.png|Layer Manager and Map Display overview. Annotations show how to add raster layer, query, add legend.
Image:wxGUI_metadata_rinfo.png|Show raster map metadata by right click on layer</gallery></center>

* GRASS GIS has over [https://grass.osgeo.org/grass70/manuals/full_index.html 500 different modules] in the core distribution and over [https://grass.osgeo.org/grass70/manuals/addons/ 230 addon modules]
<center>
{| class="wikitable"
|-
! Prefix !! Function !! Example
|-
| r.* || raster processing || ''{{cmd|r.mapcalc}}'': map algebra
|-
| v.* || vector processing || ''{{cmd|v.clean}}'': topological cleaning
|-
| i.* || imagery processing || ''{{cmd|i.segment}}'': object recognition
|-
| db.* || database management || ''{{cmd|db.select}}'': select values from table
|-
| r3.* || 3D raster processing || ''{{cmd|r3.stats}}'': 3D raster statistics
|-
| t.* || temporal data processing || ''{{cmd|t.rast.aggregate}}'': temporal aggregation
|-
| g.* || general data management || ''{{cmd|g.rename}}'': renames map
|-
| d.* || display ||''{{cmd|d.rast}}'': display raster map
|}</center>
* GRASS modules have GUI and command line interface. In this workshop we use commands to describe the workflow, but we can use both GUI and command line depending on personal preference. Look how {{cmd|wxGUI.modules|version=71|desc=GUI and command line interface}} represent the same tool. ''Task:'' compute aspect (orientation) from provided digital elevation model using module {{cmd|r.slope.aspect}} using both module dialog and command line.
* How to find modules? Modules are organized by their functionality in wxGUI menu, or we can search for them in Search modules tab. If we already know which module to use, we can just type it in the wxGUI command console. <center><gallery perrow=3 widths=380 heights=190>Image:wxGUI_menu_rinfo.png|Modules can be found in wxGUI menu
Image:wxGUI_module_search.png|You can search modules by name, description or keywords in ''Search modules'' tab
Image:wxGUI_console_completion.png|By typing prefix r. we make a list of modules starting with that prefix to show up.</gallery></center>


* {{cmd|g.region|desc=Computational region}} - an important raster concept
** defined by region extent and raster resolution
** applies to all raster operations
** persists between GRASS session, can be different for different mapsets
** advantages: keeps your results consistent, avoid clipping, for computationally demanding tasks set region to smaller extent, check your result is good and then set the computational region to the entire study area and rerun analysis
** run <code>g.region -p</code> or in menu ''Settings'' - ''Region'' - ''Display region'' to see current region settings
[[File:WxGUI set region.png|700px|thumb|center|Simple ways to set computational region from GUI. On the left, set region to match raster map. On the right, select the highlighted option and then set region by drawing rectangle.]]

* GRASS 3D view

= Modeling with FUTURES =
== Initial steps and data preparation ==
First we will set the computational region of our analyses to an extent covering our study area and aligned with our base landuse rasters:
<source lang="bash">g.region raster=landuse_2011 -p</source>

We will derive urbanized areas from NLCD dataset for year 1992, 2001 and 2011
by extracting categories category 21 - 24 into a new binary map where developed is 1,
undeveloped 0 and NULL (no data) is area unsuitable for development (water, wetlands, protected areas).
First we will convert protected areas from vector to raster. We set
NULLs to zeros (for simpler raster algebra expression in the next step) using {{cmd|r.null}}:

<source lang="bash">
v.to.rast input=protected_areas output=protected_areas use=val
r.null map=protected_areas null=0
</source>

And then create rasters of developed/undeveloped areas using raster algebra:

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.mapcalc "urban_1992 = if(landuse_1992 >= 21 && landuse_1992 <= 24, 1, if(landuse_1992 == 11 || landuse_1992 >= 90 || protected_areas, null(), 0))"
r.mapcalc "urban_2001 = if(landuse_2001 >= 21 && landuse_2001 <= 24, 1, if(landuse_2001 == 11 || landuse_2001 >= 90 || protected_areas, null(), 0))"
r.mapcalc "urban_2011 = if(landuse_2011 >= 21 && landuse_2011 <= 24, 1, if(landuse_2011 == 11 || landuse_2011 >= 90 || protected_areas, null(), 0))"
</source>

We will convert vector counties to raster with the values of the FIPS attribute which links to population file:

<source lang="bash">
v.to.rast input=counties type=area use=attr attribute_column=FIPS output=counties
</source>

Before further steps, we will set our working directory so that the input population files and text files
we are going to create are saved in one directory and easily accessible.
You can do that from menu ''Settings'' → ''GRASS working environment'' → ''Change working directory''.
Select (or create) a directory and move there the downloaded files <tt>population_projection.csv</tt> and <tt>population_trend.csv</tt>.

== Potential submodel ==
Module {{AddonCmd|r.futures.potential}} implements POTENTIAL submodel as a part of FUTURES land change model. POTENTIAL is implemented using a set of coefficients that relate a selection of site suitability factors to the probability of a place becoming developed. This is implemented using the parameter table in combination with maps of those site suitability factors (mapped predictors). The coefficients are obtained by conducting multilevel logistic regression in R with package lme4 where the coefficients may vary by county. The best model is selected automatically using dredge function from package [https://cran.r-project.org/web/packages/MuMIn/index.html MuMIn].

First, we will derive couple of predictors.
=== Predictors ===
==== Slope ====
We will derive slope in degrees from digital elevation model using {{cmd|r.slope.aspect}} module:
<source lang="bash">r.slope.aspect elevation=elevation_30m slope=slope</source>

==== Distance from lakes/rivers ====
First we will extract [http://www.mrlc.gov/nlcd11_leg.php category ''Open Water''] from 2011 NLCD dataset:
<source lang="bash">
r.mapcalc "water = if(landuse_2011 == 11, 1, null())"
</source>

Then we compute the distance to water with module {{cmd|r.grow.distance}} and set color table to shades of blue:
<source lang="bash">
r.grow.distance input=water distance=dist_to_water
r.colors -n map=dist_to_water color=blues
</source>

==== Distance from protected areas ====
We will use raster protected of protected areas we already created, but we will set NULL values to zero.
We compute the distance to protected areas with module {{cmd|r.grow.distance}} and set color table from green to red:
<source lang="bash">
r.null map=protected_areas setnull=0
r.grow.distance input=protected_areas distance=dist_to_protected
r.colors map=dist_to_protected color=gyr
</source>

==== Forests ====
We will smooth the transition between forest and other land use, see NLCD [http://www.mrlc.gov/nlcd11_leg.php category ''Open Water'']:
<source lang="bash">
r.mapcalc "forest = if(landuse_2011 >= 41 && landuse_2011 <= 43, 1, 0)"
r.neighbors -c input=forest output=forest_smooth size=15 method=average
r.colors map=forest_smooth color=ndvi
</source>

==== Travel time to cities ====
Here we will compute travel time to cities (with population > 5000)
as cumulative cost distance where cost is defined as travel time on roads.
First we specify the speed on different types of roads.
We copy the roads raster into our mapset so that we can change it
by adding a new attribute field <tt>speed</tt>. Then we assign speed values (km/h) based on the type of road:

<source lang="bash">
g.copy vector=roads,myroads
v.db.addcolumn map=myroads columns="speed double precision"
v.db.update map=myroads column=speed value=50 where="MTFCC = 'S1400'"
v.db.update map=myroads column=speed value=100 where="MTFCC IN ('S1100', 'S1200')"
</source>

Now we rasterize the selected road types using the speed values from the attribute table as raster values.

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
v.to.rast input=myroads type=line where="MTFCC IN ('S1100', 'S1200', 'S1400')" output=roads_speed use=attr attribute_column=speed
</source>

We set the rest of the area to low speed and recompute the speed as time to travel through a 30m cell in minutes:

<source lang="bash">
r.null map=roads_speed null=5
r.mapcalc "roads_travel_time = 1.8 / roads_speed"
</source>

Finally we compute the travel time to larger cities using {{cmd|r.cost}}:

<source lang="bash">
r.cost input=roads_travel_time output=travel_time_cities start_points=cities
r.colors map=travel_time_cities color=byr
</source>

==== Road density ====
We will rasterize roads and use moving window analysis ({{cmd|r.neighbors}}) to compute road density:

<source lang="bash">
v.to.rast input=roads output=roads use=val type=line
r.null map=roads null=0
r.neighbors -c input=roads output=road_dens size=25 method=average
</source>

==== Distance to interchanges ====

We will consider TIGER roads of type <tt>Ramp</tt> as interchanges, rasterize them and compute euclidean distance to them:

<source lang="bash">
v.to.rast input=roads type=line where="MTFCC = 'S1630'" output=interchanges use=val
r.grow.distance -m input=interchanges distance=dist_interchanges
</source>

=== Development pressure ===

We compute development pressure with {{AddonCmd|r.futures.devpressure}}. Development pressure is a predictor based on number of neighboring developed cells within search distance, weighted by distance. The development pressure variable plays a special role in the model, allowing for a feedback between predicted change and change in subsequent steps.

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.devpressure -n input=urban_2011 output=devpressure_2 method=gravity size=7 gamma=2 scaling_factor=10
r.futures.devpressure -n input=urban_2011 output=devpressure_1 method=gravity size=10 gamma=1 scaling_factor=1
r.futures.devpressure -n input=urban_2011 output=devpressure_0_5 method=gravity size=30 gamma=0.5 scaling_factor=0.1
</source>

When gamma increases, development influence decreases more rapidly with distance.
Size is half the size of the moving window. When gamma is low, local development influences more distant places.
We will derive 3 layers with different gamma and size parameters for the potential statistical model.

=== Rescaling variables ===

First we will look at the ranges of our predictor variables by running a short Python code snippet in Python shell:

<source lang="python" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
for name in ['slope', 'dist_to_water', 'dist_to_protected', 'forest_smooth', 'travel_time_cities', 'road_dens', 'dist_interchanges', 'devpressure_0_5', 'devpressure_1']:
minmax = grass.raster_info(name)
print name, minmax['min'], minmax['max']
</source>

We will rescale some of our input variables:

<source lang="bash">
r.mapcalc "dist_to_water_km = dist_to_water / 1000"
r.mapcalc "dist_to_protected_km = dist_to_protected / 1000"
r.mapcalc "dist_interchanges_km = dist_interchanges / 1000"
r.mapcalc "road_dens_perc = road_dens * 100"
r.mapcalc "forest_smooth_perc = forest_smooth * 100"
</source>

=== Sampling ===
To sample only in the analyzed counties, we will clip development layer:

<source lang="bash">
r.mapcalc "urban_change_01_11 = if(urban_2011 == 1, if(urban_2001 == 0, 1, null()), 0)"
r.mapcalc "urban_change_clip = if(counties, urban_change_01_11)"
</source>

To estimate the number of sampling points, we can use {{cmd|r.report}} to report number of developed/undeveloped cells and their ratio.

<source lang="bash">
r.report map=urban_change_clip units=h,c,p
</source>

We will sample the predictors and the response variable with 5000 random points in undeveloped areas and 1000 points in developed area:

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.sample.category input=urban_change_clip output=sampling sampled=counties,devpressure_0_5,devpressure_1,devpressure_2,slope,road_dens_perc,forest_smooth_perc,dist_to_water_km,dist_to_protected_km,dist_interchanges_km,travel_time_cities npoints=5000,1000
</source>

The attribute table can be exported as CSV file (not necessary step):

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
v.db.select map=sampling columns=urban_change_clip,counties,devpressure_0_5,devpressure_1,slope,road_dens_perc,forest_smooth_perc,dist_to_water_km,dist_to_protected_km,dist_interchanges_km,travel_time_cities separator=comma file=samples.csv
</source>

=== Development potential ===
Now we find best model for predicting urbanization using {{AddonCmd|r.futures.potential}} which wraps an R script.

We can run R [http://www.inside-r.org/packages/cran/MuMIn/docs/dredge dredge] function to find "best" model. We can specify minimum and maximum number of predictors the final model should use.
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.potential -d input=sampling output=potential.csv columns=devpressure_1,slope,road_dens_perc,forest_smooth_perc,dist_to_water_km,dist_to_protected_km,dist_interchanges_km,travel_time_cities developed_column=urban_change_clip subregions_column=counties min_variables=4
</source>

Also, we can play with different combinations of predictors, for example:

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.potential input=sampling output=potential.csv columns=devpressure_2,road_dens_perc,slope,dist_interchanges_km,dist_to_water_km developed_column=urban_change_clip subregions_column=counties --o
r.futures.potential input=sampling output=potential.csv columns=devpressure_1,road_dens_perc,slope,dist_interchanges_km,dist_to_water_km developed_column=urban_change_clip subregions_column=counties --o
...
</source>

You can then open the output file <tt>potential.csv</tt>, which is a CSV file with tabs as separators.

For this tutorial, the final potential is created with:
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.potential input=sampling output=potential.csv columns=devpressure_2,road_dens_perc,slope,dist_interchanges_km,dist_to_water_km developed_column=urban_change_clip subregions_column=counties --o
</source>

We can now visualize the suitability surface using module {{AddonCmd|r.futures.potsurface}}. It creates initial development potential (suitability) raster from predictors and model coefficients and serves only for evaluating development potential model. The values of the resulting raster range from 0 to 1.

<source lang="bash">
r.futures.potsurface input=potential.csv subregions=counties output=suitability
r.colors map=suitability color=byr
</source>

== Demand submodel ==
First we will mask out roads so that they don't influence into per capita land demand relation.
<source lang="bash">
v.to.rast input=roads type=line output=roads_mask use=val
r.mask roads_mask -i
</source>

We will use {{AddonCmd|r.futures.demand}} which derives the population vs. development relation. The relation can be linear/logarithmic/logarithmic2/exponential/exponential approach.
Look for examples of the different relations in the manual.

* linear: y = A + Bx
* logarithmic: y = A + Bln(x)
* logarithmic2: y = A + B * ln(x - C)        (requires SciPy)
* exponential: y = Ae^(BX)
* exp_approach: y = (1 - e^(-A(x - B))) + C        (requires SciPy)

The format of the input population CSV files is described in the manual. It is important to have synchronized categories of subregions and the column headers of the CSV files (in our case FIPS number). How to simply generate the list of years (for which demand is computed) is described in {{AddonCmd|r.futures.demand}} manual, for example run this in Python console:

<source lang="python">
','.join([str(i) for i in range(2011, 2036)])
</source>

Then we can create the DEMAND file:
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.demand development=urban_1992,urban_2001,urban_2011 subregions=counties observed_population=population_trend.csv projected_population=population_projection.csv simulation_times=2011,2012,2013,2014,2015,2016,2017,2018,2019,2020,2021,2022,2023,2024,2025,2026,2027,2028,2029,2030,2031,2032,2033,2034,2035 plot=plot_demand.pdf demand=demand.csv separator=comma
</source>

In your current working directory, you should find files <tt>plot_demand.png</tt> and <tt>demand.csv</tt>.

If you have SciPy installed, you can experiment with other methods for fitting the functions:
<source lang="bash">
r.futures.demand ... method=logarithmic2
r.futures.demand ... method=exp_approach
</source>
If necessary, you can create a set of demand files produced by fitting each method separately and
then pick for each county the method which seems best and manually create a new demand file.

When you are finished, remove the mask as it is not needed for the next steps.
<source lang="bash">
r.mask -r
</source>

== Patch calibration ==
Patch calibration can be a very time consuming computation.
Therefore we select only one county (Buncombe):

<source lang="bash">
v.to.rast input=counties type=area where="FIPS == 37021" use=attr attribute_column=FIPS output=calib_county
g.region raster=calib_county zoom=calib_county
</source>
to derive patches of new development by comparing historical and latest development.
We can keep only patches with minimum size 2 cells (1800 = 2 x 30 x 30 m).

<source lang="bash">
r.futures.calib development_start=urban_1992 development_end=urban_2011 subregions=counties patch_sizes=patches.txt patch_threshold=1800 -l
</source>
We obtained a file <tt>patches.txt</tt> (used later in the PGA) - a patch size distribution file - containing sizes of all found patches.

We can look at the distribution of the patch sizes:

<source lang="python">
from matplotlib import pyplot as plt
with open('patches.txt') as f:
patches = [int(patch) for patch in f.readlines()]
plt.hist(patches, 2000)
plt.xlim(0,50)
plt.show()
</source>

At this point, we start the calibration to get best parameters of patch shape
(for this tutorial, this step can be skipped and the suggested parameters are used).

<source lang="bash"
style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.calib development_start=urban_1992 development_end=urban_2011 subregions=calib_county patch_sizes=patches.txt calibration_results=calib.csv patch_threshold=1800 repeat=5 compactness_mean=0.1,0.3,0.5,0.7,0.9 compactness_range=0.05 discount_factor=0.1,0.3,0.5,0.7,0.9 predictors=road_dens_perc,forest_smooth_perc,dist_to_protected_km demand=demand.csv devpot_params=potential.csv num_neighbors=4 seed_search=2 development_pressure=devpressure_0_5 development_pressure_approach=gravity n_dev_neighbourhood=30 gamma=0.5 scaling_factor=0.1
</source>

== FUTURES simulation ==
We will switch back to our previous region:
<source lang="bash">
g.region raster=landuse_2011 -p
</source>

Now we have all the inputs necessary for running {{AddonCmd|r.futures.pga}}:

The entire command is here:
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.pga subregions=counties developed=urban_2011 predictors=slope,forest_smooth_perc,dist_interchanges_km,travel_time_cities devpot_params=potential.csv development_pressure=devpressure_1 n_dev_neighbourhood=10 development_pressure_approach=gravity gamma=1 scaling_factor=1 demand=demand.csv discount_factor=0.3 compactness_mean=0.2 compactness_range=0.1 patch_sizes=patches.txt num_neighbors=4 seed_search=2 random_seed=1 output=final output_series=final
</source>

=== Quick description ===
The command parameters and their values:
* raster map of counties with their categories
<code>
... subregions=counties ...
</code>

* raster of developed (1), undeveloped (0) and NULLs for undevelopable areas
<code>
... developed=urban_2011 ...
</code>

* predictors selected with {{AddonCmd|r.futures.potential}} and their coefficients in a <tt>potential.csv</tt> file. The order of predictors must match the order in the file and the categories of the counties must match raster <tt>counties</tt>.
<code>
... predictors=slope,forest_smooth_perc,dist_interchanges_km,travel_time_cities devpot_params=potential.csv ...
</code>

* initial development pressure computed by {{AddonCmd|r.futures.devpressure}}, it's important to set here the same parameters
<code>
... development_pressure=devpressure_1 n_dev_neighbourhood=10 development_pressure_approach=gravity gamma=1 scaling_factor=1 ...
</code>

* per capita land demand computed by {{AddonCmd|r.futures.demand}}, the categories of the counties must match raster <tt>counties</tt>.
<code>
... demand=demand.csv ...
</code>

* patch parameters from the calibration step
<code>
... discount_factor=0.3 compactness_mean=0.4 compactness_range=0.08 patch_sizes=patches.txt ...
</code>

* recommended parameters for patch growing algorithm
<code>
... num_neighbors=4 seed_search=2 ...
</code>

* set random seed for repeatable results or set flag <tt>-s</tt> to generate seed automatically
<code>
... random_seed=1 ...
</code>

* specify final output map and optionally basename for intermediate raster maps
<code>
output=final output_series=final
</code>

== Scenarios ==
Scenarios involving policies that encourage infill versus sprawl can be explored using the <tt>incentive_power</tt> parameter of {{AddonCmd|r.futures.pga}},
which uses a power function to transform the evenness of the probability gradient in POTENTIAL. You can change the power to a number between 0.25 and 4 to test urban sprawl/infill scenarios.
Higher power leads to infill behavior, lower power to urban sprawl.

== Postprocessing ==

Follow a [[Creating_animation_from_FUTURES_output_in_GRASS_GIS| tutorial how to make an animation from the results]].

= GRASS GIS Python API =

[[Category: Tutorial]]
[[Category: FUTURES]]
[[Category: Urban]]

Workshop on urban growth modeling with FUTURES

2016-03-22T18:42:58Z

⚠️Dbvanber: /* Creating a GRASS database for the tutorial */

{{ToModify}}
= Workshop introduction =
r.futures.* is an implementation of the '''FUT'''ure '''U'''rban-'''R'''egional '''E'''nvironment '''S'''imulation (FUTURES)[1] which is a model for multilevel simulations of emerging urban-rural landscape structure. FUTURES produces regional projections of landscape patterns using coupled submodels that integrate nonstationary drivers of land change: per capita demand (DEMAND submodel), site suitability (POTENTIAL submodel), and the spatial structure of conversion events (PGA submodel).

[1] Meentemeyer, R. K., Tang, W., Dorning, M. A., Vogler, J. B., Cunniffe, N. J., & Shoemaker, D. A. (2013). [http://www.tandfonline.com/doi/abs/10.1080/00045608.2012.707591 FUTURES: multilevel simulations of emerging urban-rural landscape structure using a stochastic patch-growing algorithm.] Annals of the Association of American Geographers, 103(4), 785-807

== Software ==
There are a number of software requirements to run FUTURES that will need to be download and installed. Required software includes:
* GRASS GIS 7
* addons
** {{AddonCmd|r.futures.pga}}
** {{AddonCmd|r.futures.potential}}
** {{AddonCmd|r.futures.potsurface}}
** {{AddonCmd|r.futures.demand}}
** {{AddonCmd|r.futures.devpressure}}
** {{AddonCmd|r.sample.category}}
* R (≥ 3.0.2) - needed for {{AddonCmd|r.futures.potential}} with packages:
**MuMIn, lme4, optparse, rgrass7
* SciPy - useful for {{AddonCmd|r.futures.demand}}

=== Installation ===
We use the R statistical software for our calculation of site suitability (i.e. development potential) in FUTURES. R is a free software environment for statistical computing and graphics. If you don't have R, or you have older an version, please download and install the software from [http://archive.linux.duke.edu/cran/ install R] and be sure to additionally add these required packages:
<pre>
install.packages(c("MuMIn", "lme4", "optparse", "rgrass7"))
</pre>

==== MS Windows ====
We will be using GRASS GIS 7.0.3 that can be found here in the [https://trac.osgeo.org/osgeo4w/ OSGeo4W] package manager.
Please install the latest stable GRASS GIS 7 version and the SciPy Python package using the ''Advanced install'' option.
A guide with step by step screen shot instructions is available [https://docs.google.com/presentation/d/1yEGpriBne7RvjB35HI6GecNwO1P1y2nRGqDThqoNnCE/edit?usp=sharing here].

In order for GRASS to be able to find R executables, GRASS must be on the PATH variable. Follow this [solution] to make R accessible from GRASS permanently.
A simple but temporary solution is to open GRASS GIS and paste this in the black terminal:
<pre>
set PATH=%PATH%;C:\Program Files\R\R-3.0.2\bin
</pre>
This has to be repeated after restarting GRASS session.

==== Ubuntu Linux ====
Install GRASS GIS from packages:
<pre>
sudo add-apt-repository ppa:ubuntugis/ubuntugis-unstable
sudo apt-get update
sudo apt-get install grass
</pre>

== Workshop data ==
The data that we will be using for the workshop can be download here: [http://fatra.cnr.ncsu.edu/futures/futures_ncspm_Asheville.zip sample dataset]. Please place these layers in your local GRASS directory:
* digital elevation model ([http://nationalmap.gov/elevation.html NED])
* [http://www.mrlc.gov/ NLCD] 2001, 2011
* NLCD 1992/2001 Retrofit Land Cover Change Product
* transportation network ([http://www.census.gov/geo/maps-data/data/tiger-line.html TIGER])
* county boundaries ([http://www.census.gov/geo/maps-data/data/tiger-line.html TIGER])
* protected areas ([http://www.conservationgateway.org/ConservationByGeography/NorthAmerica/UnitedStates/edc/reportsdata/terrestrial/secured/Pages/default.aspx Secured Lands])
* cities as points (USGS)

In addition, download [http://fatra.cnr.ncsu.edu/futures/futures_Asheville_files.zip population information as text files]:
* county population past estimates and future projections ([https://www.osbm.nc.gov/demog/county-projections NC OSBM]) per county (nonspatial)

= GRASS GIS introduction =
There are many advantages to using the open source GRASS GIS platform, but for many that are more familiar with ARCGis and QGis, the setup and implementation of spatial tools in GRASS can be confusing. Here we provide an overview of the GRASS GIS project: [https://grass.osgeo.org grass.osgeo.org] that might be helpful to review if you are a first time users. For this exercise it's not necessary to have a full understanding of how to use GRASS. However, you will need to know how to place your data in the correct GRASS database directory, as well as some basic GRASS functionality. Step by step instructions are provided below
== GRASS directory system ==
GRASS uses unique database terminology and structure ([https://grass.osgeo.org/grass71/manuals/grass_database.html GRASS database]) that are important to understand for the set up of this tutorial, as you will need to place the required data (e.g. Mapset) in a specific GRASS database Location.

=== Important GRASS directory terminology ===
* A '''GRASS database''' consist of directory with specific Locations (projects) where data layer are stored
* '''Location''' hold all Mapsets in a specific directoy that have the same spatial projection (spatial reference system)
* '''Mapset''' are a collection of maps with the same spatial projection

=== Creating a GRASS database for the tutorial ===
You need to create a GRASS database with the Mapset that we will use for the tutorial before we can run the FUTURES model. Please Download the [http://fatra.cnr.ncsu.edu/futures/futures_ncspm_Asheville.zip workshop location], noting where the files are located on your local directory. Now, create (unless you already have it) a directory named <tt>grassdata</tt> (GRASS database) in your home folder (or Documents), unzip the downloaded data into this directory. You should now have a Location <tt>futures_ncspm</tt> in <tt>grassdata</tt>.
* Launch GRASS and display raster, vector data, explore navigation, querying, adding legend, showing metadata
<center><gallery perrow=3 widths=500 heights=250>Image:GRASS FUTURES startup.png|GRASS GIS 7.0.3 startup dialog with downloaded Location and Mapsets for FUTURES workshop
Image:GRASS FUTURES wxGUI display.png|Layer Manager and Map Display overview. Annotations show how to add raster layer, query, add legend.
Image:wxGUI_metadata_rinfo.png|Show raster map metadata by right click on layer</gallery></center>

* GRASS GIS has over [https://grass.osgeo.org/grass70/manuals/full_index.html 500 different modules] in the core distribution and over [https://grass.osgeo.org/grass70/manuals/addons/ 230 addon modules]
<center>
{| class="wikitable"
|-
! Prefix !! Function !! Example
|-
| r.* || raster processing || ''{{cmd|r.mapcalc}}'': map algebra
|-
| v.* || vector processing || ''{{cmd|v.clean}}'': topological cleaning
|-
| i.* || imagery processing || ''{{cmd|i.segment}}'': object recognition
|-
| db.* || database management || ''{{cmd|db.select}}'': select values from table
|-
| r3.* || 3D raster processing || ''{{cmd|r3.stats}}'': 3D raster statistics
|-
| t.* || temporal data processing || ''{{cmd|t.rast.aggregate}}'': temporal aggregation
|-
| g.* || general data management || ''{{cmd|g.rename}}'': renames map
|-
| d.* || display ||''{{cmd|d.rast}}'': display raster map
|}</center>
* GRASS modules have GUI and command line interface. In this workshop we use commands to describe the workflow, but we can use both GUI and command line depending on personal preference. Look how {{cmd|wxGUI.modules|version=71|desc=GUI and command line interface}} represent the same tool. ''Task:'' compute aspect (orientation) from provided digital elevation model using module {{cmd|r.slope.aspect}} using both module dialog and command line.
* How to find modules? Modules are organized by their functionality in wxGUI menu, or we can search for them in Search modules tab. If we already know which module to use, we can just type it in the wxGUI command console. <center><gallery perrow=3 widths=380 heights=190>Image:wxGUI_menu_rinfo.png|Modules can be found in wxGUI menu
Image:wxGUI_module_search.png|You can search modules by name, description or keywords in ''Search modules'' tab
Image:wxGUI_console_completion.png|By typing prefix r. we make a list of modules starting with that prefix to show up.</gallery></center>


* {{cmd|g.region|desc=Computational region}} - an important raster concept
** defined by region extent and raster resolution
** applies to all raster operations
** persists between GRASS session, can be different for different mapsets
** advantages: keeps your results consistent, avoid clipping, for computationally demanding tasks set region to smaller extent, check your result is good and then set the computational region to the entire study area and rerun analysis
** run <code>g.region -p</code> or in menu ''Settings'' - ''Region'' - ''Display region'' to see current region settings
[[File:WxGUI set region.png|700px|thumb|center|Simple ways to set computational region from GUI. On the left, set region to match raster map. On the right, select the highlighted option and then set region by drawing rectangle.]]

* GRASS 3D view

= Modeling with FUTURES =
== Initial steps and data preparation ==
First we will set the computational region of our analyses to an extent covering our study area and aligned with our base landuse rasters:
<source lang="bash">g.region raster=landuse_2011 -p</source>

We will derive urbanized areas from NLCD dataset for year 1992, 2001 and 2011
by extracting categories category 21 - 24 into a new binary map where developed is 1,
undeveloped 0 and NULL (no data) is area unsuitable for development (water, wetlands, protected areas).
First we will convert protected areas from vector to raster. We set
NULLs to zeros (for simpler raster algebra expression in the next step) using {{cmd|r.null}}:

<source lang="bash">
v.to.rast input=protected_areas output=protected_areas use=val
r.null map=protected_areas null=0
</source>

And then create rasters of developed/undeveloped areas using raster algebra:

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.mapcalc "urban_1992 = if(landuse_1992 >= 21 && landuse_1992 <= 24, 1, if(landuse_1992 == 11 || landuse_1992 >= 90 || protected_areas, null(), 0))"
r.mapcalc "urban_2001 = if(landuse_2001 >= 21 && landuse_2001 <= 24, 1, if(landuse_2001 == 11 || landuse_2001 >= 90 || protected_areas, null(), 0))"
r.mapcalc "urban_2011 = if(landuse_2011 >= 21 && landuse_2011 <= 24, 1, if(landuse_2011 == 11 || landuse_2011 >= 90 || protected_areas, null(), 0))"
</source>

We will convert vector counties to raster with the values of the FIPS attribute which links to population file:

<source lang="bash">
v.to.rast input=counties type=area use=attr attribute_column=FIPS output=counties
</source>

Before further steps, we will set our working directory so that the input population files and text files
we are going to create are saved in one directory and easily accessible.
You can do that from menu ''Settings'' → ''GRASS working environment'' → ''Change working directory''.
Select (or create) a directory and move there the downloaded files <tt>population_projection.csv</tt> and <tt>population_trend.csv</tt>.

== Potential submodel ==
Module {{AddonCmd|r.futures.potential}} implements POTENTIAL submodel as a part of FUTURES land change model. POTENTIAL is implemented using a set of coefficients that relate a selection of site suitability factors to the probability of a place becoming developed. This is implemented using the parameter table in combination with maps of those site suitability factors (mapped predictors). The coefficients are obtained by conducting multilevel logistic regression in R with package lme4 where the coefficients may vary by county. The best model is selected automatically using dredge function from package [https://cran.r-project.org/web/packages/MuMIn/index.html MuMIn].

First, we will derive couple of predictors.
=== Predictors ===
==== Slope ====
We will derive slope in degrees from digital elevation model using {{cmd|r.slope.aspect}} module:
<source lang="bash">r.slope.aspect elevation=elevation_30m slope=slope</source>

==== Distance from lakes/rivers ====
First we will extract [http://www.mrlc.gov/nlcd11_leg.php category ''Open Water''] from 2011 NLCD dataset:
<source lang="bash">
r.mapcalc "water = if(landuse_2011 == 11, 1, null())"
</source>

Then we compute the distance to water with module {{cmd|r.grow.distance}} and set color table to shades of blue:
<source lang="bash">
r.grow.distance input=water distance=dist_to_water
r.colors -n map=dist_to_water color=blues
</source>

==== Distance from protected areas ====
We will use raster protected of protected areas we already created, but we will set NULL values to zero.
We compute the distance to protected areas with module {{cmd|r.grow.distance}} and set color table from green to red:
<source lang="bash">
r.null map=protected_areas setnull=0
r.grow.distance input=protected_areas distance=dist_to_protected
r.colors map=dist_to_protected color=gyr
</source>

==== Forests ====
We will smooth the transition between forest and other land use, see NLCD [http://www.mrlc.gov/nlcd11_leg.php category ''Open Water'']:
<source lang="bash">
r.mapcalc "forest = if(landuse_2011 >= 41 && landuse_2011 <= 43, 1, 0)"
r.neighbors -c input=forest output=forest_smooth size=15 method=average
r.colors map=forest_smooth color=ndvi
</source>

==== Travel time to cities ====
Here we will compute travel time to cities (with population > 5000)
as cumulative cost distance where cost is defined as travel time on roads.
First we specify the speed on different types of roads.
We copy the roads raster into our mapset so that we can change it
by adding a new attribute field <tt>speed</tt>. Then we assign speed values (km/h) based on the type of road:

<source lang="bash">
g.copy vector=roads,myroads
v.db.addcolumn map=myroads columns="speed double precision"
v.db.update map=myroads column=speed value=50 where="MTFCC = 'S1400'"
v.db.update map=myroads column=speed value=100 where="MTFCC IN ('S1100', 'S1200')"
</source>

Now we rasterize the selected road types using the speed values from the attribute table as raster values.

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
v.to.rast input=myroads type=line where="MTFCC IN ('S1100', 'S1200', 'S1400')" output=roads_speed use=attr attribute_column=speed
</source>

We set the rest of the area to low speed and recompute the speed as time to travel through a 30m cell in minutes:

<source lang="bash">
r.null map=roads_speed null=5
r.mapcalc "roads_travel_time = 1.8 / roads_speed"
</source>

Finally we compute the travel time to larger cities using {{cmd|r.cost}}:

<source lang="bash">
r.cost input=roads_travel_time output=travel_time_cities start_points=cities
r.colors map=travel_time_cities color=byr
</source>

==== Road density ====
We will rasterize roads and use moving window analysis ({{cmd|r.neighbors}}) to compute road density:

<source lang="bash">
v.to.rast input=roads output=roads use=val type=line
r.null map=roads null=0
r.neighbors -c input=roads output=road_dens size=25 method=average
</source>

==== Distance to interchanges ====

We will consider TIGER roads of type <tt>Ramp</tt> as interchanges, rasterize them and compute euclidean distance to them:

<source lang="bash">
v.to.rast input=roads type=line where="MTFCC = 'S1630'" output=interchanges use=val
r.grow.distance -m input=interchanges distance=dist_interchanges
</source>

=== Development pressure ===

We compute development pressure with {{AddonCmd|r.futures.devpressure}}. Development pressure is a predictor based on number of neighboring developed cells within search distance, weighted by distance. The development pressure variable plays a special role in the model, allowing for a feedback between predicted change and change in subsequent steps.

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.devpressure -n input=urban_2011 output=devpressure_2 method=gravity size=7 gamma=2 scaling_factor=10
r.futures.devpressure -n input=urban_2011 output=devpressure_1 method=gravity size=10 gamma=1 scaling_factor=1
r.futures.devpressure -n input=urban_2011 output=devpressure_0_5 method=gravity size=30 gamma=0.5 scaling_factor=0.1
</source>

When gamma increases, development influence decreases more rapidly with distance.
Size is half the size of the moving window. When gamma is low, local development influences more distant places.
We will derive 3 layers with different gamma and size parameters for the potential statistical model.

=== Rescaling variables ===

First we will look at the ranges of our predictor variables by running a short Python code snippet in Python shell:

<source lang="python" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
for name in ['slope', 'dist_to_water', 'dist_to_protected', 'forest_smooth', 'travel_time_cities', 'road_dens', 'dist_interchanges', 'devpressure_0_5', 'devpressure_1']:
minmax = grass.raster_info(name)
print name, minmax['min'], minmax['max']
</source>

We will rescale some of our input variables:

<source lang="bash">
r.mapcalc "dist_to_water_km = dist_to_water / 1000"
r.mapcalc "dist_to_protected_km = dist_to_protected / 1000"
r.mapcalc "dist_interchanges_km = dist_interchanges / 1000"
r.mapcalc "road_dens_perc = road_dens * 100"
r.mapcalc "forest_smooth_perc = forest_smooth * 100"
</source>

=== Sampling ===
To sample only in the analyzed counties, we will clip development layer:

<source lang="bash">
r.mapcalc "urban_change_01_11 = if(urban_2011 == 1, if(urban_2001 == 0, 1, null()), 0)"
r.mapcalc "urban_change_clip = if(counties, urban_change_01_11)"
</source>

To estimate the number of sampling points, we can use {{cmd|r.report}} to report number of developed/undeveloped cells and their ratio.

<source lang="bash">
r.report map=urban_change_clip units=h,c,p
</source>

We will sample the predictors and the response variable with 5000 random points in undeveloped areas and 1000 points in developed area:

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.sample.category input=urban_change_clip output=sampling sampled=counties,devpressure_0_5,devpressure_1,devpressure_2,slope,road_dens_perc,forest_smooth_perc,dist_to_water_km,dist_to_protected_km,dist_interchanges_km,travel_time_cities npoints=5000,1000
</source>

The attribute table can be exported as CSV file (not necessary step):

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
v.db.select map=sampling columns=urban_change_clip,counties,devpressure_0_5,devpressure_1,slope,road_dens_perc,forest_smooth_perc,dist_to_water_km,dist_to_protected_km,dist_interchanges_km,travel_time_cities separator=comma file=samples.csv
</source>

=== Development potential ===
Now we find best model for predicting urbanization using {{AddonCmd|r.futures.potential}} which wraps an R script.

We can run R [http://www.inside-r.org/packages/cran/MuMIn/docs/dredge dredge] function to find "best" model. We can specify minimum and maximum number of predictors the final model should use.
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.potential -d input=sampling output=potential.csv columns=devpressure_1,slope,road_dens_perc,forest_smooth_perc,dist_to_water_km,dist_to_protected_km,dist_interchanges_km,travel_time_cities developed_column=urban_change_clip subregions_column=counties min_variables=4
</source>

Also, we can play with different combinations of predictors, for example:

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.potential input=sampling output=potential.csv columns=devpressure_2,road_dens_perc,slope,dist_interchanges_km,dist_to_water_km developed_column=urban_change_clip subregions_column=counties --o
r.futures.potential input=sampling output=potential.csv columns=devpressure_1,road_dens_perc,slope,dist_interchanges_km,dist_to_water_km developed_column=urban_change_clip subregions_column=counties --o
...
</source>

You can then open the output file <tt>potential.csv</tt>, which is a CSV file with tabs as separators.

For this tutorial, the final potential is created with:
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.potential input=sampling output=potential.csv columns=devpressure_2,road_dens_perc,slope,dist_interchanges_km,dist_to_water_km developed_column=urban_change_clip subregions_column=counties --o
</source>

We can now visualize the suitability surface using module {{AddonCmd|r.futures.potsurface}}. It creates initial development potential (suitability) raster from predictors and model coefficients and serves only for evaluating development potential model. The values of the resulting raster range from 0 to 1.

<source lang="bash">
r.futures.potsurface input=potential.csv subregions=counties output=suitability
r.colors map=suitability color=byr
</source>

== Demand submodel ==
First we will mask out roads so that they don't influence into per capita land demand relation.
<source lang="bash">
v.to.rast input=roads type=line output=roads_mask use=val
r.mask roads_mask -i
</source>

We will use {{AddonCmd|r.futures.demand}} which derives the population vs. development relation. The relation can be linear/logarithmic/logarithmic2/exponential/exponential approach.
Look for examples of the different relations in the manual.

* linear: y = A + Bx
* logarithmic: y = A + Bln(x)
* logarithmic2: y = A + B * ln(x - C)        (requires SciPy)
* exponential: y = Ae^(BX)
* exp_approach: y = (1 - e^(-A(x - B))) + C        (requires SciPy)

The format of the input population CSV files is described in the manual. It is important to have synchronized categories of subregions and the column headers of the CSV files (in our case FIPS number). How to simply generate the list of years (for which demand is computed) is described in {{AddonCmd|r.futures.demand}} manual, for example run this in Python console:

<source lang="python">
','.join([str(i) for i in range(2011, 2036)])
</source>

Then we can create the DEMAND file:
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.demand development=urban_1992,urban_2001,urban_2011 subregions=counties observed_population=population_trend.csv projected_population=population_projection.csv simulation_times=2011,2012,2013,2014,2015,2016,2017,2018,2019,2020,2021,2022,2023,2024,2025,2026,2027,2028,2029,2030,2031,2032,2033,2034,2035 plot=plot_demand.pdf demand=demand.csv separator=comma
</source>

In your current working directory, you should find files <tt>plot_demand.png</tt> and <tt>demand.csv</tt>.

If you have SciPy installed, you can experiment with other methods for fitting the functions:
<source lang="bash">
r.futures.demand ... method=logarithmic2
r.futures.demand ... method=exp_approach
</source>
If necessary, you can create a set of demand files produced by fitting each method separately and
then pick for each county the method which seems best and manually create a new demand file.

When you are finished, remove the mask as it is not needed for the next steps.
<source lang="bash">
r.mask -r
</source>

== Patch calibration ==
Patch calibration can be a very time consuming computation.
Therefore we select only one county (Buncombe):

<source lang="bash">
v.to.rast input=counties type=area where="FIPS == 37021" use=attr attribute_column=FIPS output=calib_county
g.region raster=calib_county zoom=calib_county
</source>
to derive patches of new development by comparing historical and latest development.
We can keep only patches with minimum size 2 cells (1800 = 2 x 30 x 30 m).

<source lang="bash">
r.futures.calib development_start=urban_1992 development_end=urban_2011 subregions=counties patch_sizes=patches.txt patch_threshold=1800 -l
</source>
We obtained a file <tt>patches.txt</tt> (used later in the PGA) - a patch size distribution file - containing sizes of all found patches.

We can look at the distribution of the patch sizes:

<source lang="python">
from matplotlib import pyplot as plt
with open('patches.txt') as f:
patches = [int(patch) for patch in f.readlines()]
plt.hist(patches, 2000)
plt.xlim(0,50)
plt.show()
</source>

At this point, we start the calibration to get best parameters of patch shape
(for this tutorial, this step can be skipped and the suggested parameters are used).

<source lang="bash"
style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.calib development_start=urban_1992 development_end=urban_2011 subregions=calib_county patch_sizes=patches.txt calibration_results=calib.csv patch_threshold=1800 repeat=5 compactness_mean=0.1,0.3,0.5,0.7,0.9 compactness_range=0.05 discount_factor=0.1,0.3,0.5,0.7,0.9 predictors=road_dens_perc,forest_smooth_perc,dist_to_protected_km demand=demand.csv devpot_params=potential.csv num_neighbors=4 seed_search=2 development_pressure=devpressure_0_5 development_pressure_approach=gravity n_dev_neighbourhood=30 gamma=0.5 scaling_factor=0.1
</source>

== FUTURES simulation ==
We will switch back to our previous region:
<source lang="bash">
g.region raster=landuse_2011 -p
</source>

Now we have all the inputs necessary for running {{AddonCmd|r.futures.pga}}:

The entire command is here:
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.pga subregions=counties developed=urban_2011 predictors=slope,forest_smooth_perc,dist_interchanges_km,travel_time_cities devpot_params=potential.csv development_pressure=devpressure_1 n_dev_neighbourhood=10 development_pressure_approach=gravity gamma=1 scaling_factor=1 demand=demand.csv discount_factor=0.3 compactness_mean=0.2 compactness_range=0.1 patch_sizes=patches.txt num_neighbors=4 seed_search=2 random_seed=1 output=final output_series=final
</source>

=== Quick description ===
The command parameters and their values:
* raster map of counties with their categories
<code>
... subregions=counties ...
</code>

* raster of developed (1), undeveloped (0) and NULLs for undevelopable areas
<code>
... developed=urban_2011 ...
</code>

* predictors selected with {{AddonCmd|r.futures.potential}} and their coefficients in a <tt>potential.csv</tt> file. The order of predictors must match the order in the file and the categories of the counties must match raster <tt>counties</tt>.
<code>
... predictors=slope,forest_smooth_perc,dist_interchanges_km,travel_time_cities devpot_params=potential.csv ...
</code>

* initial development pressure computed by {{AddonCmd|r.futures.devpressure}}, it's important to set here the same parameters
<code>
... development_pressure=devpressure_1 n_dev_neighbourhood=10 development_pressure_approach=gravity gamma=1 scaling_factor=1 ...
</code>

* per capita land demand computed by {{AddonCmd|r.futures.demand}}, the categories of the counties must match raster <tt>counties</tt>.
<code>
... demand=demand.csv ...
</code>

* patch parameters from the calibration step
<code>
... discount_factor=0.3 compactness_mean=0.4 compactness_range=0.08 patch_sizes=patches.txt ...
</code>

* recommended parameters for patch growing algorithm
<code>
... num_neighbors=4 seed_search=2 ...
</code>

* set random seed for repeatable results or set flag <tt>-s</tt> to generate seed automatically
<code>
... random_seed=1 ...
</code>

* specify final output map and optionally basename for intermediate raster maps
<code>
output=final output_series=final
</code>

== Scenarios ==
Scenarios involving policies that encourage infill versus sprawl can be explored using the <tt>incentive_power</tt> parameter of {{AddonCmd|r.futures.pga}},
which uses a power function to transform the evenness of the probability gradient in POTENTIAL. You can change the power to a number between 0.25 and 4 to test urban sprawl/infill scenarios.
Higher power leads to infill behavior, lower power to urban sprawl.

== Postprocessing ==

Follow a [[Creating_animation_from_FUTURES_output_in_GRASS_GIS| tutorial how to make an animation from the results]].

= GRASS GIS Python API =

[[Category: Tutorial]]
[[Category: FUTURES]]
[[Category: Urban]]

Workshop on urban growth modeling with FUTURES

2016-03-22T18:40:58Z

⚠️Dbvanber: /* GRASS directory system */

{{ToModify}}
= Workshop introduction =
r.futures.* is an implementation of the '''FUT'''ure '''U'''rban-'''R'''egional '''E'''nvironment '''S'''imulation (FUTURES)[1] which is a model for multilevel simulations of emerging urban-rural landscape structure. FUTURES produces regional projections of landscape patterns using coupled submodels that integrate nonstationary drivers of land change: per capita demand (DEMAND submodel), site suitability (POTENTIAL submodel), and the spatial structure of conversion events (PGA submodel).

[1] Meentemeyer, R. K., Tang, W., Dorning, M. A., Vogler, J. B., Cunniffe, N. J., & Shoemaker, D. A. (2013). [http://www.tandfonline.com/doi/abs/10.1080/00045608.2012.707591 FUTURES: multilevel simulations of emerging urban-rural landscape structure using a stochastic patch-growing algorithm.] Annals of the Association of American Geographers, 103(4), 785-807

== Software ==
There are a number of software requirements to run FUTURES that will need to be download and installed. Required software includes:
* GRASS GIS 7
* addons
** {{AddonCmd|r.futures.pga}}
** {{AddonCmd|r.futures.potential}}
** {{AddonCmd|r.futures.potsurface}}
** {{AddonCmd|r.futures.demand}}
** {{AddonCmd|r.futures.devpressure}}
** {{AddonCmd|r.sample.category}}
* R (≥ 3.0.2) - needed for {{AddonCmd|r.futures.potential}} with packages:
**MuMIn, lme4, optparse, rgrass7
* SciPy - useful for {{AddonCmd|r.futures.demand}}

=== Installation ===
We use the R statistical software for our calculation of site suitability (i.e. development potential) in FUTURES. R is a free software environment for statistical computing and graphics. If you don't have R, or you have older an version, please download and install the software from [http://archive.linux.duke.edu/cran/ install R] and be sure to additionally add these required packages:
<pre>
install.packages(c("MuMIn", "lme4", "optparse", "rgrass7"))
</pre>

==== MS Windows ====
We will be using GRASS GIS 7.0.3 that can be found here in the [https://trac.osgeo.org/osgeo4w/ OSGeo4W] package manager.
Please install the latest stable GRASS GIS 7 version and the SciPy Python package using the ''Advanced install'' option.
A guide with step by step screen shot instructions is available [https://docs.google.com/presentation/d/1yEGpriBne7RvjB35HI6GecNwO1P1y2nRGqDThqoNnCE/edit?usp=sharing here].

In order for GRASS to be able to find R executables, GRASS must be on the PATH variable. Follow this [solution] to make R accessible from GRASS permanently.
A simple but temporary solution is to open GRASS GIS and paste this in the black terminal:
<pre>
set PATH=%PATH%;C:\Program Files\R\R-3.0.2\bin
</pre>
This has to be repeated after restarting GRASS session.

==== Ubuntu Linux ====
Install GRASS GIS from packages:
<pre>
sudo add-apt-repository ppa:ubuntugis/ubuntugis-unstable
sudo apt-get update
sudo apt-get install grass
</pre>

== Workshop data ==
The data that we will be using for the workshop can be download here: [http://fatra.cnr.ncsu.edu/futures/futures_ncspm_Asheville.zip sample dataset]. Please place these layers in your local GRASS directory:
* digital elevation model ([http://nationalmap.gov/elevation.html NED])
* [http://www.mrlc.gov/ NLCD] 2001, 2011
* NLCD 1992/2001 Retrofit Land Cover Change Product
* transportation network ([http://www.census.gov/geo/maps-data/data/tiger-line.html TIGER])
* county boundaries ([http://www.census.gov/geo/maps-data/data/tiger-line.html TIGER])
* protected areas ([http://www.conservationgateway.org/ConservationByGeography/NorthAmerica/UnitedStates/edc/reportsdata/terrestrial/secured/Pages/default.aspx Secured Lands])
* cities as points (USGS)

In addition, download [http://fatra.cnr.ncsu.edu/futures/futures_Asheville_files.zip population information as text files]:
* county population past estimates and future projections ([https://www.osbm.nc.gov/demog/county-projections NC OSBM]) per county (nonspatial)

= GRASS GIS introduction =
There are many advantages to using the open source GRASS GIS platform, but for many that are more familiar with ARCGis and QGis, the setup and implementation of spatial tools in GRASS can be confusing. Here we provide an overview of the GRASS GIS project: [https://grass.osgeo.org grass.osgeo.org] that might be helpful to review if you are a first time users. For this exercise it's not necessary to have a full understanding of how to use GRASS. However, you will need to know how to place your data in the correct GRASS database directory, as well as some basic GRASS functionality. Step by step instructions are provided below
== GRASS directory system ==
GRASS uses unique database terminology and structure ([https://grass.osgeo.org/grass71/manuals/grass_database.html GRASS database]) that are important to understand for the set up of this tutorial, as you will need to place the required data (e.g. Mapset) in a specific GRASS database Location.

=== Important GRASS directory terminology ===
* A '''GRASS database''' consist of directory with specific Locations (projects) where data layer are stored
* '''Location''' hold all Mapsets in a specific directoy that have the same spatial projection (spatial reference system)
* '''Mapset''' are a collection of maps with the same spatial projection

=== Creating a GRASS database for the tutorial ===
You need to create a GRASS database with the Mapset that we will use for the tutorial before we can run the FUTURES model. Please Download the [http://fatra.cnr.ncsu.edu/futures/futures_ncspm_Asheville.zip workshop location]. Create (unless you already have it) a directory named <tt>grassdata</tt> (GRASS database) in your home folder (or Documents), unzip the downloaded data into this directory. You should have now Location <tt>futures_ncspm</tt> in <tt>grassdata</tt>.
* Launch GRASS and display raster, vector data, explore navigation, querying, adding legend, showing metadata
<center><gallery perrow=3 widths=500 heights=250>Image:GRASS FUTURES startup.png|GRASS GIS 7.0.3 startup dialog with downloaded Location and Mapsets for FUTURES workshop
Image:GRASS FUTURES wxGUI display.png|Layer Manager and Map Display overview. Annotations show how to add raster layer, query, add legend.
Image:wxGUI_metadata_rinfo.png|Show raster map metadata by right click on layer</gallery></center>

* GRASS GIS has over [https://grass.osgeo.org/grass70/manuals/full_index.html 500 different modules] in the core distribution and over [https://grass.osgeo.org/grass70/manuals/addons/ 230 addon modules]
<center>
{| class="wikitable"
|-
! Prefix !! Function !! Example
|-
| r.* || raster processing || ''{{cmd|r.mapcalc}}'': map algebra
|-
| v.* || vector processing || ''{{cmd|v.clean}}'': topological cleaning
|-
| i.* || imagery processing || ''{{cmd|i.segment}}'': object recognition
|-
| db.* || database management || ''{{cmd|db.select}}'': select values from table
|-
| r3.* || 3D raster processing || ''{{cmd|r3.stats}}'': 3D raster statistics
|-
| t.* || temporal data processing || ''{{cmd|t.rast.aggregate}}'': temporal aggregation
|-
| g.* || general data management || ''{{cmd|g.rename}}'': renames map
|-
| d.* || display ||''{{cmd|d.rast}}'': display raster map
|}</center>
* GRASS modules have GUI and command line interface. In this workshop we use commands to describe the workflow, but we can use both GUI and command line depending on personal preference. Look how {{cmd|wxGUI.modules|version=71|desc=GUI and command line interface}} represent the same tool. ''Task:'' compute aspect (orientation) from provided digital elevation model using module {{cmd|r.slope.aspect}} using both module dialog and command line.
* How to find modules? Modules are organized by their functionality in wxGUI menu, or we can search for them in Search modules tab. If we already know which module to use, we can just type it in the wxGUI command console. <center><gallery perrow=3 widths=380 heights=190>Image:wxGUI_menu_rinfo.png|Modules can be found in wxGUI menu
Image:wxGUI_module_search.png|You can search modules by name, description or keywords in ''Search modules'' tab
Image:wxGUI_console_completion.png|By typing prefix r. we make a list of modules starting with that prefix to show up.</gallery></center>


* {{cmd|g.region|desc=Computational region}} - an important raster concept
** defined by region extent and raster resolution
** applies to all raster operations
** persists between GRASS session, can be different for different mapsets
** advantages: keeps your results consistent, avoid clipping, for computationally demanding tasks set region to smaller extent, check your result is good and then set the computational region to the entire study area and rerun analysis
** run <code>g.region -p</code> or in menu ''Settings'' - ''Region'' - ''Display region'' to see current region settings
[[File:WxGUI set region.png|700px|thumb|center|Simple ways to set computational region from GUI. On the left, set region to match raster map. On the right, select the highlighted option and then set region by drawing rectangle.]]

* GRASS 3D view

= Modeling with FUTURES =
== Initial steps and data preparation ==
First we will set the computational region of our analyses to an extent covering our study area and aligned with our base landuse rasters:
<source lang="bash">g.region raster=landuse_2011 -p</source>

We will derive urbanized areas from NLCD dataset for year 1992, 2001 and 2011
by extracting categories category 21 - 24 into a new binary map where developed is 1,
undeveloped 0 and NULL (no data) is area unsuitable for development (water, wetlands, protected areas).
First we will convert protected areas from vector to raster. We set
NULLs to zeros (for simpler raster algebra expression in the next step) using {{cmd|r.null}}:

<source lang="bash">
v.to.rast input=protected_areas output=protected_areas use=val
r.null map=protected_areas null=0
</source>

And then create rasters of developed/undeveloped areas using raster algebra:

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.mapcalc "urban_1992 = if(landuse_1992 >= 21 && landuse_1992 <= 24, 1, if(landuse_1992 == 11 || landuse_1992 >= 90 || protected_areas, null(), 0))"
r.mapcalc "urban_2001 = if(landuse_2001 >= 21 && landuse_2001 <= 24, 1, if(landuse_2001 == 11 || landuse_2001 >= 90 || protected_areas, null(), 0))"
r.mapcalc "urban_2011 = if(landuse_2011 >= 21 && landuse_2011 <= 24, 1, if(landuse_2011 == 11 || landuse_2011 >= 90 || protected_areas, null(), 0))"
</source>

We will convert vector counties to raster with the values of the FIPS attribute which links to population file:

<source lang="bash">
v.to.rast input=counties type=area use=attr attribute_column=FIPS output=counties
</source>

Before further steps, we will set our working directory so that the input population files and text files
we are going to create are saved in one directory and easily accessible.
You can do that from menu ''Settings'' → ''GRASS working environment'' → ''Change working directory''.
Select (or create) a directory and move there the downloaded files <tt>population_projection.csv</tt> and <tt>population_trend.csv</tt>.

== Potential submodel ==
Module {{AddonCmd|r.futures.potential}} implements POTENTIAL submodel as a part of FUTURES land change model. POTENTIAL is implemented using a set of coefficients that relate a selection of site suitability factors to the probability of a place becoming developed. This is implemented using the parameter table in combination with maps of those site suitability factors (mapped predictors). The coefficients are obtained by conducting multilevel logistic regression in R with package lme4 where the coefficients may vary by county. The best model is selected automatically using dredge function from package [https://cran.r-project.org/web/packages/MuMIn/index.html MuMIn].

First, we will derive couple of predictors.
=== Predictors ===
==== Slope ====
We will derive slope in degrees from digital elevation model using {{cmd|r.slope.aspect}} module:
<source lang="bash">r.slope.aspect elevation=elevation_30m slope=slope</source>

==== Distance from lakes/rivers ====
First we will extract [http://www.mrlc.gov/nlcd11_leg.php category ''Open Water''] from 2011 NLCD dataset:
<source lang="bash">
r.mapcalc "water = if(landuse_2011 == 11, 1, null())"
</source>

Then we compute the distance to water with module {{cmd|r.grow.distance}} and set color table to shades of blue:
<source lang="bash">
r.grow.distance input=water distance=dist_to_water
r.colors -n map=dist_to_water color=blues
</source>

==== Distance from protected areas ====
We will use raster protected of protected areas we already created, but we will set NULL values to zero.
We compute the distance to protected areas with module {{cmd|r.grow.distance}} and set color table from green to red:
<source lang="bash">
r.null map=protected_areas setnull=0
r.grow.distance input=protected_areas distance=dist_to_protected
r.colors map=dist_to_protected color=gyr
</source>

==== Forests ====
We will smooth the transition between forest and other land use, see NLCD [http://www.mrlc.gov/nlcd11_leg.php category ''Open Water'']:
<source lang="bash">
r.mapcalc "forest = if(landuse_2011 >= 41 && landuse_2011 <= 43, 1, 0)"
r.neighbors -c input=forest output=forest_smooth size=15 method=average
r.colors map=forest_smooth color=ndvi
</source>

==== Travel time to cities ====
Here we will compute travel time to cities (with population > 5000)
as cumulative cost distance where cost is defined as travel time on roads.
First we specify the speed on different types of roads.
We copy the roads raster into our mapset so that we can change it
by adding a new attribute field <tt>speed</tt>. Then we assign speed values (km/h) based on the type of road:

<source lang="bash">
g.copy vector=roads,myroads
v.db.addcolumn map=myroads columns="speed double precision"
v.db.update map=myroads column=speed value=50 where="MTFCC = 'S1400'"
v.db.update map=myroads column=speed value=100 where="MTFCC IN ('S1100', 'S1200')"
</source>

Now we rasterize the selected road types using the speed values from the attribute table as raster values.

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
v.to.rast input=myroads type=line where="MTFCC IN ('S1100', 'S1200', 'S1400')" output=roads_speed use=attr attribute_column=speed
</source>

We set the rest of the area to low speed and recompute the speed as time to travel through a 30m cell in minutes:

<source lang="bash">
r.null map=roads_speed null=5
r.mapcalc "roads_travel_time = 1.8 / roads_speed"
</source>

Finally we compute the travel time to larger cities using {{cmd|r.cost}}:

<source lang="bash">
r.cost input=roads_travel_time output=travel_time_cities start_points=cities
r.colors map=travel_time_cities color=byr
</source>

==== Road density ====
We will rasterize roads and use moving window analysis ({{cmd|r.neighbors}}) to compute road density:

<source lang="bash">
v.to.rast input=roads output=roads use=val type=line
r.null map=roads null=0
r.neighbors -c input=roads output=road_dens size=25 method=average
</source>

==== Distance to interchanges ====

We will consider TIGER roads of type <tt>Ramp</tt> as interchanges, rasterize them and compute euclidean distance to them:

<source lang="bash">
v.to.rast input=roads type=line where="MTFCC = 'S1630'" output=interchanges use=val
r.grow.distance -m input=interchanges distance=dist_interchanges
</source>

=== Development pressure ===

We compute development pressure with {{AddonCmd|r.futures.devpressure}}. Development pressure is a predictor based on number of neighboring developed cells within search distance, weighted by distance. The development pressure variable plays a special role in the model, allowing for a feedback between predicted change and change in subsequent steps.

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.devpressure -n input=urban_2011 output=devpressure_2 method=gravity size=7 gamma=2 scaling_factor=10
r.futures.devpressure -n input=urban_2011 output=devpressure_1 method=gravity size=10 gamma=1 scaling_factor=1
r.futures.devpressure -n input=urban_2011 output=devpressure_0_5 method=gravity size=30 gamma=0.5 scaling_factor=0.1
</source>

When gamma increases, development influence decreases more rapidly with distance.
Size is half the size of the moving window. When gamma is low, local development influences more distant places.
We will derive 3 layers with different gamma and size parameters for the potential statistical model.

=== Rescaling variables ===

First we will look at the ranges of our predictor variables by running a short Python code snippet in Python shell:

<source lang="python" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
for name in ['slope', 'dist_to_water', 'dist_to_protected', 'forest_smooth', 'travel_time_cities', 'road_dens', 'dist_interchanges', 'devpressure_0_5', 'devpressure_1']:
minmax = grass.raster_info(name)
print name, minmax['min'], minmax['max']
</source>

We will rescale some of our input variables:

<source lang="bash">
r.mapcalc "dist_to_water_km = dist_to_water / 1000"
r.mapcalc "dist_to_protected_km = dist_to_protected / 1000"
r.mapcalc "dist_interchanges_km = dist_interchanges / 1000"
r.mapcalc "road_dens_perc = road_dens * 100"
r.mapcalc "forest_smooth_perc = forest_smooth * 100"
</source>

=== Sampling ===
To sample only in the analyzed counties, we will clip development layer:

<source lang="bash">
r.mapcalc "urban_change_01_11 = if(urban_2011 == 1, if(urban_2001 == 0, 1, null()), 0)"
r.mapcalc "urban_change_clip = if(counties, urban_change_01_11)"
</source>

To estimate the number of sampling points, we can use {{cmd|r.report}} to report number of developed/undeveloped cells and their ratio.

<source lang="bash">
r.report map=urban_change_clip units=h,c,p
</source>

We will sample the predictors and the response variable with 5000 random points in undeveloped areas and 1000 points in developed area:

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.sample.category input=urban_change_clip output=sampling sampled=counties,devpressure_0_5,devpressure_1,devpressure_2,slope,road_dens_perc,forest_smooth_perc,dist_to_water_km,dist_to_protected_km,dist_interchanges_km,travel_time_cities npoints=5000,1000
</source>

The attribute table can be exported as CSV file (not necessary step):

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
v.db.select map=sampling columns=urban_change_clip,counties,devpressure_0_5,devpressure_1,slope,road_dens_perc,forest_smooth_perc,dist_to_water_km,dist_to_protected_km,dist_interchanges_km,travel_time_cities separator=comma file=samples.csv
</source>

=== Development potential ===
Now we find best model for predicting urbanization using {{AddonCmd|r.futures.potential}} which wraps an R script.

We can run R [http://www.inside-r.org/packages/cran/MuMIn/docs/dredge dredge] function to find "best" model. We can specify minimum and maximum number of predictors the final model should use.
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.potential -d input=sampling output=potential.csv columns=devpressure_1,slope,road_dens_perc,forest_smooth_perc,dist_to_water_km,dist_to_protected_km,dist_interchanges_km,travel_time_cities developed_column=urban_change_clip subregions_column=counties min_variables=4
</source>

Also, we can play with different combinations of predictors, for example:

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.potential input=sampling output=potential.csv columns=devpressure_2,road_dens_perc,slope,dist_interchanges_km,dist_to_water_km developed_column=urban_change_clip subregions_column=counties --o
r.futures.potential input=sampling output=potential.csv columns=devpressure_1,road_dens_perc,slope,dist_interchanges_km,dist_to_water_km developed_column=urban_change_clip subregions_column=counties --o
...
</source>

You can then open the output file <tt>potential.csv</tt>, which is a CSV file with tabs as separators.

For this tutorial, the final potential is created with:
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.potential input=sampling output=potential.csv columns=devpressure_2,road_dens_perc,slope,dist_interchanges_km,dist_to_water_km developed_column=urban_change_clip subregions_column=counties --o
</source>

We can now visualize the suitability surface using module {{AddonCmd|r.futures.potsurface}}. It creates initial development potential (suitability) raster from predictors and model coefficients and serves only for evaluating development potential model. The values of the resulting raster range from 0 to 1.

<source lang="bash">
r.futures.potsurface input=potential.csv subregions=counties output=suitability
r.colors map=suitability color=byr
</source>

== Demand submodel ==
First we will mask out roads so that they don't influence into per capita land demand relation.
<source lang="bash">
v.to.rast input=roads type=line output=roads_mask use=val
r.mask roads_mask -i
</source>

We will use {{AddonCmd|r.futures.demand}} which derives the population vs. development relation. The relation can be linear/logarithmic/logarithmic2/exponential/exponential approach.
Look for examples of the different relations in the manual.

* linear: y = A + Bx
* logarithmic: y = A + Bln(x)
* logarithmic2: y = A + B * ln(x - C)        (requires SciPy)
* exponential: y = Ae^(BX)
* exp_approach: y = (1 - e^(-A(x - B))) + C        (requires SciPy)

The format of the input population CSV files is described in the manual. It is important to have synchronized categories of subregions and the column headers of the CSV files (in our case FIPS number). How to simply generate the list of years (for which demand is computed) is described in {{AddonCmd|r.futures.demand}} manual, for example run this in Python console:

<source lang="python">
','.join([str(i) for i in range(2011, 2036)])
</source>

Then we can create the DEMAND file:
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.demand development=urban_1992,urban_2001,urban_2011 subregions=counties observed_population=population_trend.csv projected_population=population_projection.csv simulation_times=2011,2012,2013,2014,2015,2016,2017,2018,2019,2020,2021,2022,2023,2024,2025,2026,2027,2028,2029,2030,2031,2032,2033,2034,2035 plot=plot_demand.pdf demand=demand.csv separator=comma
</source>

In your current working directory, you should find files <tt>plot_demand.png</tt> and <tt>demand.csv</tt>.

If you have SciPy installed, you can experiment with other methods for fitting the functions:
<source lang="bash">
r.futures.demand ... method=logarithmic2
r.futures.demand ... method=exp_approach
</source>
If necessary, you can create a set of demand files produced by fitting each method separately and
then pick for each county the method which seems best and manually create a new demand file.

When you are finished, remove the mask as it is not needed for the next steps.
<source lang="bash">
r.mask -r
</source>

== Patch calibration ==
Patch calibration can be a very time consuming computation.
Therefore we select only one county (Buncombe):

<source lang="bash">
v.to.rast input=counties type=area where="FIPS == 37021" use=attr attribute_column=FIPS output=calib_county
g.region raster=calib_county zoom=calib_county
</source>
to derive patches of new development by comparing historical and latest development.
We can keep only patches with minimum size 2 cells (1800 = 2 x 30 x 30 m).

<source lang="bash">
r.futures.calib development_start=urban_1992 development_end=urban_2011 subregions=counties patch_sizes=patches.txt patch_threshold=1800 -l
</source>
We obtained a file <tt>patches.txt</tt> (used later in the PGA) - a patch size distribution file - containing sizes of all found patches.

We can look at the distribution of the patch sizes:

<source lang="python">
from matplotlib import pyplot as plt
with open('patches.txt') as f:
patches = [int(patch) for patch in f.readlines()]
plt.hist(patches, 2000)
plt.xlim(0,50)
plt.show()
</source>

At this point, we start the calibration to get best parameters of patch shape
(for this tutorial, this step can be skipped and the suggested parameters are used).

<source lang="bash"
style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.calib development_start=urban_1992 development_end=urban_2011 subregions=calib_county patch_sizes=patches.txt calibration_results=calib.csv patch_threshold=1800 repeat=5 compactness_mean=0.1,0.3,0.5,0.7,0.9 compactness_range=0.05 discount_factor=0.1,0.3,0.5,0.7,0.9 predictors=road_dens_perc,forest_smooth_perc,dist_to_protected_km demand=demand.csv devpot_params=potential.csv num_neighbors=4 seed_search=2 development_pressure=devpressure_0_5 development_pressure_approach=gravity n_dev_neighbourhood=30 gamma=0.5 scaling_factor=0.1
</source>

== FUTURES simulation ==
We will switch back to our previous region:
<source lang="bash">
g.region raster=landuse_2011 -p
</source>

Now we have all the inputs necessary for running {{AddonCmd|r.futures.pga}}:

The entire command is here:
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.pga subregions=counties developed=urban_2011 predictors=slope,forest_smooth_perc,dist_interchanges_km,travel_time_cities devpot_params=potential.csv development_pressure=devpressure_1 n_dev_neighbourhood=10 development_pressure_approach=gravity gamma=1 scaling_factor=1 demand=demand.csv discount_factor=0.3 compactness_mean=0.2 compactness_range=0.1 patch_sizes=patches.txt num_neighbors=4 seed_search=2 random_seed=1 output=final output_series=final
</source>

=== Quick description ===
The command parameters and their values:
* raster map of counties with their categories
<code>
... subregions=counties ...
</code>

* raster of developed (1), undeveloped (0) and NULLs for undevelopable areas
<code>
... developed=urban_2011 ...
</code>

* predictors selected with {{AddonCmd|r.futures.potential}} and their coefficients in a <tt>potential.csv</tt> file. The order of predictors must match the order in the file and the categories of the counties must match raster <tt>counties</tt>.
<code>
... predictors=slope,forest_smooth_perc,dist_interchanges_km,travel_time_cities devpot_params=potential.csv ...
</code>

* initial development pressure computed by {{AddonCmd|r.futures.devpressure}}, it's important to set here the same parameters
<code>
... development_pressure=devpressure_1 n_dev_neighbourhood=10 development_pressure_approach=gravity gamma=1 scaling_factor=1 ...
</code>

* per capita land demand computed by {{AddonCmd|r.futures.demand}}, the categories of the counties must match raster <tt>counties</tt>.
<code>
... demand=demand.csv ...
</code>

* patch parameters from the calibration step
<code>
... discount_factor=0.3 compactness_mean=0.4 compactness_range=0.08 patch_sizes=patches.txt ...
</code>

* recommended parameters for patch growing algorithm
<code>
... num_neighbors=4 seed_search=2 ...
</code>

* set random seed for repeatable results or set flag <tt>-s</tt> to generate seed automatically
<code>
... random_seed=1 ...
</code>

* specify final output map and optionally basename for intermediate raster maps
<code>
output=final output_series=final
</code>

== Scenarios ==
Scenarios involving policies that encourage infill versus sprawl can be explored using the <tt>incentive_power</tt> parameter of {{AddonCmd|r.futures.pga}},
which uses a power function to transform the evenness of the probability gradient in POTENTIAL. You can change the power to a number between 0.25 and 4 to test urban sprawl/infill scenarios.
Higher power leads to infill behavior, lower power to urban sprawl.

== Postprocessing ==

Follow a [[Creating_animation_from_FUTURES_output_in_GRASS_GIS| tutorial how to make an animation from the results]].

= GRASS GIS Python API =

[[Category: Tutorial]]
[[Category: FUTURES]]
[[Category: Urban]]

Workshop on urban growth modeling with FUTURES

2016-03-22T18:35:43Z

⚠️Dbvanber: /* GRASS directory */

{{ToModify}}
= Workshop introduction =
r.futures.* is an implementation of the '''FUT'''ure '''U'''rban-'''R'''egional '''E'''nvironment '''S'''imulation (FUTURES)[1] which is a model for multilevel simulations of emerging urban-rural landscape structure. FUTURES produces regional projections of landscape patterns using coupled submodels that integrate nonstationary drivers of land change: per capita demand (DEMAND submodel), site suitability (POTENTIAL submodel), and the spatial structure of conversion events (PGA submodel).

[1] Meentemeyer, R. K., Tang, W., Dorning, M. A., Vogler, J. B., Cunniffe, N. J., & Shoemaker, D. A. (2013). [http://www.tandfonline.com/doi/abs/10.1080/00045608.2012.707591 FUTURES: multilevel simulations of emerging urban-rural landscape structure using a stochastic patch-growing algorithm.] Annals of the Association of American Geographers, 103(4), 785-807

== Software ==
There are a number of software requirements to run FUTURES that will need to be download and installed. Required software includes:
* GRASS GIS 7
* addons
** {{AddonCmd|r.futures.pga}}
** {{AddonCmd|r.futures.potential}}
** {{AddonCmd|r.futures.potsurface}}
** {{AddonCmd|r.futures.demand}}
** {{AddonCmd|r.futures.devpressure}}
** {{AddonCmd|r.sample.category}}
* R (≥ 3.0.2) - needed for {{AddonCmd|r.futures.potential}} with packages:
**MuMIn, lme4, optparse, rgrass7
* SciPy - useful for {{AddonCmd|r.futures.demand}}

=== Installation ===
We use the R statistical software for our calculation of site suitability (i.e. development potential) in FUTURES. R is a free software environment for statistical computing and graphics. If you don't have R, or you have older an version, please download and install the software from [http://archive.linux.duke.edu/cran/ install R] and be sure to additionally add these required packages:
<pre>
install.packages(c("MuMIn", "lme4", "optparse", "rgrass7"))
</pre>

==== MS Windows ====
We will be using GRASS GIS 7.0.3 that can be found here in the [https://trac.osgeo.org/osgeo4w/ OSGeo4W] package manager.
Please install the latest stable GRASS GIS 7 version and the SciPy Python package using the ''Advanced install'' option.
A guide with step by step screen shot instructions is available [https://docs.google.com/presentation/d/1yEGpriBne7RvjB35HI6GecNwO1P1y2nRGqDThqoNnCE/edit?usp=sharing here].

In order for GRASS to be able to find R executables, GRASS must be on the PATH variable. Follow this [solution] to make R accessible from GRASS permanently.
A simple but temporary solution is to open GRASS GIS and paste this in the black terminal:
<pre>
set PATH=%PATH%;C:\Program Files\R\R-3.0.2\bin
</pre>
This has to be repeated after restarting GRASS session.

==== Ubuntu Linux ====
Install GRASS GIS from packages:
<pre>
sudo add-apt-repository ppa:ubuntugis/ubuntugis-unstable
sudo apt-get update
sudo apt-get install grass
</pre>

== Workshop data ==
The data that we will be using for the workshop can be download here: [http://fatra.cnr.ncsu.edu/futures/futures_ncspm_Asheville.zip sample dataset]. Please place these layers in your local GRASS directory:
* digital elevation model ([http://nationalmap.gov/elevation.html NED])
* [http://www.mrlc.gov/ NLCD] 2001, 2011
* NLCD 1992/2001 Retrofit Land Cover Change Product
* transportation network ([http://www.census.gov/geo/maps-data/data/tiger-line.html TIGER])
* county boundaries ([http://www.census.gov/geo/maps-data/data/tiger-line.html TIGER])
* protected areas ([http://www.conservationgateway.org/ConservationByGeography/NorthAmerica/UnitedStates/edc/reportsdata/terrestrial/secured/Pages/default.aspx Secured Lands])
* cities as points (USGS)

In addition, download [http://fatra.cnr.ncsu.edu/futures/futures_Asheville_files.zip population information as text files]:
* county population past estimates and future projections ([https://www.osbm.nc.gov/demog/county-projections NC OSBM]) per county (nonspatial)

= GRASS GIS introduction =
There are many advantages to using the open source GRASS GIS platform, but for many that are more familiar with ARCGis and QGis, the setup and implementation of spatial tools in GRASS can be confusing. Here we provide an overview of the GRASS GIS project: [https://grass.osgeo.org grass.osgeo.org] that might be helpful to review if you are a first time users. For this exercise it's not necessary to have a full understanding of how to use GRASS. However, you will need to know how to place your data in the correct GRASS database directory, as well as some basic GRASS functionality. Step by step instructions are provided below
== GRASS directory system ==
GRASS uses unique database terminology and structure that are important to understand [https://grass.osgeo.org/grass71/manuals/grass_database.html GRASS database] for the set up of this tutorial as you will need to place the required data (e.g. Mapset) in a specific GRASS database Location.

=== Important GRASS directory terminology ===
* A '''GRASS database''' consist of directory with specific Locations (projects) where data layer are stored
* '''Location''' hold all Mapsets in a specific directoy that have the same spatial projection (spatial reference system)
* '''Mapset''' are a collection of maps with the same spatial projection

To Download the [http://fatra.cnr.ncsu.edu/futures/futures_ncspm_Asheville.zip workshop location]. Create (unless you already have it) a directory named <tt>grassdata</tt> (GRASS database) in your home folder (or Documents), unzip the downloaded data into this directory. You should have now Location <tt>futures_ncspm</tt> in <tt>grassdata</tt>.
* Launch GRASS and display raster, vector data, explore navigation, querying, adding legend, showing metadata
<center><gallery perrow=3 widths=500 heights=250>Image:GRASS FUTURES startup.png|GRASS GIS 7.0.3 startup dialog with downloaded Location and Mapsets for FUTURES workshop
Image:GRASS FUTURES wxGUI display.png|Layer Manager and Map Display overview. Annotations show how to add raster layer, query, add legend.
Image:wxGUI_metadata_rinfo.png|Show raster map metadata by right click on layer</gallery></center>

* GRASS GIS has over [https://grass.osgeo.org/grass70/manuals/full_index.html 500 different modules] in the core distribution and over [https://grass.osgeo.org/grass70/manuals/addons/ 230 addon modules]
<center>
{| class="wikitable"
|-
! Prefix !! Function !! Example
|-
| r.* || raster processing || ''{{cmd|r.mapcalc}}'': map algebra
|-
| v.* || vector processing || ''{{cmd|v.clean}}'': topological cleaning
|-
| i.* || imagery processing || ''{{cmd|i.segment}}'': object recognition
|-
| db.* || database management || ''{{cmd|db.select}}'': select values from table
|-
| r3.* || 3D raster processing || ''{{cmd|r3.stats}}'': 3D raster statistics
|-
| t.* || temporal data processing || ''{{cmd|t.rast.aggregate}}'': temporal aggregation
|-
| g.* || general data management || ''{{cmd|g.rename}}'': renames map
|-
| d.* || display ||''{{cmd|d.rast}}'': display raster map
|}</center>
* GRASS modules have GUI and command line interface. In this workshop we use commands to describe the workflow, but we can use both GUI and command line depending on personal preference. Look how {{cmd|wxGUI.modules|version=71|desc=GUI and command line interface}} represent the same tool. ''Task:'' compute aspect (orientation) from provided digital elevation model using module {{cmd|r.slope.aspect}} using both module dialog and command line.
* How to find modules? Modules are organized by their functionality in wxGUI menu, or we can search for them in Search modules tab. If we already know which module to use, we can just type it in the wxGUI command console. <center><gallery perrow=3 widths=380 heights=190>Image:wxGUI_menu_rinfo.png|Modules can be found in wxGUI menu
Image:wxGUI_module_search.png|You can search modules by name, description or keywords in ''Search modules'' tab
Image:wxGUI_console_completion.png|By typing prefix r. we make a list of modules starting with that prefix to show up.</gallery></center>


* {{cmd|g.region|desc=Computational region}} - an important raster concept
** defined by region extent and raster resolution
** applies to all raster operations
** persists between GRASS session, can be different for different mapsets
** advantages: keeps your results consistent, avoid clipping, for computationally demanding tasks set region to smaller extent, check your result is good and then set the computational region to the entire study area and rerun analysis
** run <code>g.region -p</code> or in menu ''Settings'' - ''Region'' - ''Display region'' to see current region settings
[[File:WxGUI set region.png|700px|thumb|center|Simple ways to set computational region from GUI. On the left, set region to match raster map. On the right, select the highlighted option and then set region by drawing rectangle.]]

* GRASS 3D view

= Modeling with FUTURES =
== Initial steps and data preparation ==
First we will set the computational region of our analyses to an extent covering our study area and aligned with our base landuse rasters:
<source lang="bash">g.region raster=landuse_2011 -p</source>

We will derive urbanized areas from NLCD dataset for year 1992, 2001 and 2011
by extracting categories category 21 - 24 into a new binary map where developed is 1,
undeveloped 0 and NULL (no data) is area unsuitable for development (water, wetlands, protected areas).
First we will convert protected areas from vector to raster. We set
NULLs to zeros (for simpler raster algebra expression in the next step) using {{cmd|r.null}}:

<source lang="bash">
v.to.rast input=protected_areas output=protected_areas use=val
r.null map=protected_areas null=0
</source>

And then create rasters of developed/undeveloped areas using raster algebra:

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.mapcalc "urban_1992 = if(landuse_1992 >= 21 && landuse_1992 <= 24, 1, if(landuse_1992 == 11 || landuse_1992 >= 90 || protected_areas, null(), 0))"
r.mapcalc "urban_2001 = if(landuse_2001 >= 21 && landuse_2001 <= 24, 1, if(landuse_2001 == 11 || landuse_2001 >= 90 || protected_areas, null(), 0))"
r.mapcalc "urban_2011 = if(landuse_2011 >= 21 && landuse_2011 <= 24, 1, if(landuse_2011 == 11 || landuse_2011 >= 90 || protected_areas, null(), 0))"
</source>

We will convert vector counties to raster with the values of the FIPS attribute which links to population file:

<source lang="bash">
v.to.rast input=counties type=area use=attr attribute_column=FIPS output=counties
</source>

Before further steps, we will set our working directory so that the input population files and text files
we are going to create are saved in one directory and easily accessible.
You can do that from menu ''Settings'' → ''GRASS working environment'' → ''Change working directory''.
Select (or create) a directory and move there the downloaded files <tt>population_projection.csv</tt> and <tt>population_trend.csv</tt>.

== Potential submodel ==
Module {{AddonCmd|r.futures.potential}} implements POTENTIAL submodel as a part of FUTURES land change model. POTENTIAL is implemented using a set of coefficients that relate a selection of site suitability factors to the probability of a place becoming developed. This is implemented using the parameter table in combination with maps of those site suitability factors (mapped predictors). The coefficients are obtained by conducting multilevel logistic regression in R with package lme4 where the coefficients may vary by county. The best model is selected automatically using dredge function from package [https://cran.r-project.org/web/packages/MuMIn/index.html MuMIn].

First, we will derive couple of predictors.
=== Predictors ===
==== Slope ====
We will derive slope in degrees from digital elevation model using {{cmd|r.slope.aspect}} module:
<source lang="bash">r.slope.aspect elevation=elevation_30m slope=slope</source>

==== Distance from lakes/rivers ====
First we will extract [http://www.mrlc.gov/nlcd11_leg.php category ''Open Water''] from 2011 NLCD dataset:
<source lang="bash">
r.mapcalc "water = if(landuse_2011 == 11, 1, null())"
</source>

Then we compute the distance to water with module {{cmd|r.grow.distance}} and set color table to shades of blue:
<source lang="bash">
r.grow.distance input=water distance=dist_to_water
r.colors -n map=dist_to_water color=blues
</source>

==== Distance from protected areas ====
We will use raster protected of protected areas we already created, but we will set NULL values to zero.
We compute the distance to protected areas with module {{cmd|r.grow.distance}} and set color table from green to red:
<source lang="bash">
r.null map=protected_areas setnull=0
r.grow.distance input=protected_areas distance=dist_to_protected
r.colors map=dist_to_protected color=gyr
</source>

==== Forests ====
We will smooth the transition between forest and other land use, see NLCD [http://www.mrlc.gov/nlcd11_leg.php category ''Open Water'']:
<source lang="bash">
r.mapcalc "forest = if(landuse_2011 >= 41 && landuse_2011 <= 43, 1, 0)"
r.neighbors -c input=forest output=forest_smooth size=15 method=average
r.colors map=forest_smooth color=ndvi
</source>

==== Travel time to cities ====
Here we will compute travel time to cities (with population > 5000)
as cumulative cost distance where cost is defined as travel time on roads.
First we specify the speed on different types of roads.
We copy the roads raster into our mapset so that we can change it
by adding a new attribute field <tt>speed</tt>. Then we assign speed values (km/h) based on the type of road:

<source lang="bash">
g.copy vector=roads,myroads
v.db.addcolumn map=myroads columns="speed double precision"
v.db.update map=myroads column=speed value=50 where="MTFCC = 'S1400'"
v.db.update map=myroads column=speed value=100 where="MTFCC IN ('S1100', 'S1200')"
</source>

Now we rasterize the selected road types using the speed values from the attribute table as raster values.

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
v.to.rast input=myroads type=line where="MTFCC IN ('S1100', 'S1200', 'S1400')" output=roads_speed use=attr attribute_column=speed
</source>

We set the rest of the area to low speed and recompute the speed as time to travel through a 30m cell in minutes:

<source lang="bash">
r.null map=roads_speed null=5
r.mapcalc "roads_travel_time = 1.8 / roads_speed"
</source>

Finally we compute the travel time to larger cities using {{cmd|r.cost}}:

<source lang="bash">
r.cost input=roads_travel_time output=travel_time_cities start_points=cities
r.colors map=travel_time_cities color=byr
</source>

==== Road density ====
We will rasterize roads and use moving window analysis ({{cmd|r.neighbors}}) to compute road density:

<source lang="bash">
v.to.rast input=roads output=roads use=val type=line
r.null map=roads null=0
r.neighbors -c input=roads output=road_dens size=25 method=average
</source>

==== Distance to interchanges ====

We will consider TIGER roads of type <tt>Ramp</tt> as interchanges, rasterize them and compute euclidean distance to them:

<source lang="bash">
v.to.rast input=roads type=line where="MTFCC = 'S1630'" output=interchanges use=val
r.grow.distance -m input=interchanges distance=dist_interchanges
</source>

=== Development pressure ===

We compute development pressure with {{AddonCmd|r.futures.devpressure}}. Development pressure is a predictor based on number of neighboring developed cells within search distance, weighted by distance. The development pressure variable plays a special role in the model, allowing for a feedback between predicted change and change in subsequent steps.

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.devpressure -n input=urban_2011 output=devpressure_2 method=gravity size=7 gamma=2 scaling_factor=10
r.futures.devpressure -n input=urban_2011 output=devpressure_1 method=gravity size=10 gamma=1 scaling_factor=1
r.futures.devpressure -n input=urban_2011 output=devpressure_0_5 method=gravity size=30 gamma=0.5 scaling_factor=0.1
</source>

When gamma increases, development influence decreases more rapidly with distance.
Size is half the size of the moving window. When gamma is low, local development influences more distant places.
We will derive 3 layers with different gamma and size parameters for the potential statistical model.

=== Rescaling variables ===

First we will look at the ranges of our predictor variables by running a short Python code snippet in Python shell:

<source lang="python" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
for name in ['slope', 'dist_to_water', 'dist_to_protected', 'forest_smooth', 'travel_time_cities', 'road_dens', 'dist_interchanges', 'devpressure_0_5', 'devpressure_1']:
minmax = grass.raster_info(name)
print name, minmax['min'], minmax['max']
</source>

We will rescale some of our input variables:

<source lang="bash">
r.mapcalc "dist_to_water_km = dist_to_water / 1000"
r.mapcalc "dist_to_protected_km = dist_to_protected / 1000"
r.mapcalc "dist_interchanges_km = dist_interchanges / 1000"
r.mapcalc "road_dens_perc = road_dens * 100"
r.mapcalc "forest_smooth_perc = forest_smooth * 100"
</source>

=== Sampling ===
To sample only in the analyzed counties, we will clip development layer:

<source lang="bash">
r.mapcalc "urban_change_01_11 = if(urban_2011 == 1, if(urban_2001 == 0, 1, null()), 0)"
r.mapcalc "urban_change_clip = if(counties, urban_change_01_11)"
</source>

To estimate the number of sampling points, we can use {{cmd|r.report}} to report number of developed/undeveloped cells and their ratio.

<source lang="bash">
r.report map=urban_change_clip units=h,c,p
</source>

We will sample the predictors and the response variable with 5000 random points in undeveloped areas and 1000 points in developed area:

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.sample.category input=urban_change_clip output=sampling sampled=counties,devpressure_0_5,devpressure_1,devpressure_2,slope,road_dens_perc,forest_smooth_perc,dist_to_water_km,dist_to_protected_km,dist_interchanges_km,travel_time_cities npoints=5000,1000
</source>

The attribute table can be exported as CSV file (not necessary step):

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
v.db.select map=sampling columns=urban_change_clip,counties,devpressure_0_5,devpressure_1,slope,road_dens_perc,forest_smooth_perc,dist_to_water_km,dist_to_protected_km,dist_interchanges_km,travel_time_cities separator=comma file=samples.csv
</source>

=== Development potential ===
Now we find best model for predicting urbanization using {{AddonCmd|r.futures.potential}} which wraps an R script.

We can run R [http://www.inside-r.org/packages/cran/MuMIn/docs/dredge dredge] function to find "best" model. We can specify minimum and maximum number of predictors the final model should use.
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.potential -d input=sampling output=potential.csv columns=devpressure_1,slope,road_dens_perc,forest_smooth_perc,dist_to_water_km,dist_to_protected_km,dist_interchanges_km,travel_time_cities developed_column=urban_change_clip subregions_column=counties min_variables=4
</source>

Also, we can play with different combinations of predictors, for example:

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.potential input=sampling output=potential.csv columns=devpressure_2,road_dens_perc,slope,dist_interchanges_km,dist_to_water_km developed_column=urban_change_clip subregions_column=counties --o
r.futures.potential input=sampling output=potential.csv columns=devpressure_1,road_dens_perc,slope,dist_interchanges_km,dist_to_water_km developed_column=urban_change_clip subregions_column=counties --o
...
</source>

You can then open the output file <tt>potential.csv</tt>, which is a CSV file with tabs as separators.

For this tutorial, the final potential is created with:
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.potential input=sampling output=potential.csv columns=devpressure_2,road_dens_perc,slope,dist_interchanges_km,dist_to_water_km developed_column=urban_change_clip subregions_column=counties --o
</source>

We can now visualize the suitability surface using module {{AddonCmd|r.futures.potsurface}}. It creates initial development potential (suitability) raster from predictors and model coefficients and serves only for evaluating development potential model. The values of the resulting raster range from 0 to 1.

<source lang="bash">
r.futures.potsurface input=potential.csv subregions=counties output=suitability
r.colors map=suitability color=byr
</source>

== Demand submodel ==
First we will mask out roads so that they don't influence into per capita land demand relation.
<source lang="bash">
v.to.rast input=roads type=line output=roads_mask use=val
r.mask roads_mask -i
</source>

We will use {{AddonCmd|r.futures.demand}} which derives the population vs. development relation. The relation can be linear/logarithmic/logarithmic2/exponential/exponential approach.
Look for examples of the different relations in the manual.

* linear: y = A + Bx
* logarithmic: y = A + Bln(x)
* logarithmic2: y = A + B * ln(x - C)        (requires SciPy)
* exponential: y = Ae^(BX)
* exp_approach: y = (1 - e^(-A(x - B))) + C        (requires SciPy)

The format of the input population CSV files is described in the manual. It is important to have synchronized categories of subregions and the column headers of the CSV files (in our case FIPS number). How to simply generate the list of years (for which demand is computed) is described in {{AddonCmd|r.futures.demand}} manual, for example run this in Python console:

<source lang="python">
','.join([str(i) for i in range(2011, 2036)])
</source>

Then we can create the DEMAND file:
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.demand development=urban_1992,urban_2001,urban_2011 subregions=counties observed_population=population_trend.csv projected_population=population_projection.csv simulation_times=2011,2012,2013,2014,2015,2016,2017,2018,2019,2020,2021,2022,2023,2024,2025,2026,2027,2028,2029,2030,2031,2032,2033,2034,2035 plot=plot_demand.pdf demand=demand.csv separator=comma
</source>

In your current working directory, you should find files <tt>plot_demand.png</tt> and <tt>demand.csv</tt>.

If you have SciPy installed, you can experiment with other methods for fitting the functions:
<source lang="bash">
r.futures.demand ... method=logarithmic2
r.futures.demand ... method=exp_approach
</source>
If necessary, you can create a set of demand files produced by fitting each method separately and
then pick for each county the method which seems best and manually create a new demand file.

When you are finished, remove the mask as it is not needed for the next steps.
<source lang="bash">
r.mask -r
</source>

== Patch calibration ==
Patch calibration can be a very time consuming computation.
Therefore we select only one county (Buncombe):

<source lang="bash">
v.to.rast input=counties type=area where="FIPS == 37021" use=attr attribute_column=FIPS output=calib_county
g.region raster=calib_county zoom=calib_county
</source>
to derive patches of new development by comparing historical and latest development.
We can keep only patches with minimum size 2 cells (1800 = 2 x 30 x 30 m).

<source lang="bash">
r.futures.calib development_start=urban_1992 development_end=urban_2011 subregions=counties patch_sizes=patches.txt patch_threshold=1800 -l
</source>
We obtained a file <tt>patches.txt</tt> (used later in the PGA) - a patch size distribution file - containing sizes of all found patches.

We can look at the distribution of the patch sizes:

<source lang="python">
from matplotlib import pyplot as plt
with open('patches.txt') as f:
patches = [int(patch) for patch in f.readlines()]
plt.hist(patches, 2000)
plt.xlim(0,50)
plt.show()
</source>

At this point, we start the calibration to get best parameters of patch shape
(for this tutorial, this step can be skipped and the suggested parameters are used).

<source lang="bash"
style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.calib development_start=urban_1992 development_end=urban_2011 subregions=calib_county patch_sizes=patches.txt calibration_results=calib.csv patch_threshold=1800 repeat=5 compactness_mean=0.1,0.3,0.5,0.7,0.9 compactness_range=0.05 discount_factor=0.1,0.3,0.5,0.7,0.9 predictors=road_dens_perc,forest_smooth_perc,dist_to_protected_km demand=demand.csv devpot_params=potential.csv num_neighbors=4 seed_search=2 development_pressure=devpressure_0_5 development_pressure_approach=gravity n_dev_neighbourhood=30 gamma=0.5 scaling_factor=0.1
</source>

== FUTURES simulation ==
We will switch back to our previous region:
<source lang="bash">
g.region raster=landuse_2011 -p
</source>

Now we have all the inputs necessary for running {{AddonCmd|r.futures.pga}}:

The entire command is here:
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.pga subregions=counties developed=urban_2011 predictors=slope,forest_smooth_perc,dist_interchanges_km,travel_time_cities devpot_params=potential.csv development_pressure=devpressure_1 n_dev_neighbourhood=10 development_pressure_approach=gravity gamma=1 scaling_factor=1 demand=demand.csv discount_factor=0.3 compactness_mean=0.2 compactness_range=0.1 patch_sizes=patches.txt num_neighbors=4 seed_search=2 random_seed=1 output=final output_series=final
</source>

=== Quick description ===
The command parameters and their values:
* raster map of counties with their categories
<code>
... subregions=counties ...
</code>

* raster of developed (1), undeveloped (0) and NULLs for undevelopable areas
<code>
... developed=urban_2011 ...
</code>

* predictors selected with {{AddonCmd|r.futures.potential}} and their coefficients in a <tt>potential.csv</tt> file. The order of predictors must match the order in the file and the categories of the counties must match raster <tt>counties</tt>.
<code>
... predictors=slope,forest_smooth_perc,dist_interchanges_km,travel_time_cities devpot_params=potential.csv ...
</code>

* initial development pressure computed by {{AddonCmd|r.futures.devpressure}}, it's important to set here the same parameters
<code>
... development_pressure=devpressure_1 n_dev_neighbourhood=10 development_pressure_approach=gravity gamma=1 scaling_factor=1 ...
</code>

* per capita land demand computed by {{AddonCmd|r.futures.demand}}, the categories of the counties must match raster <tt>counties</tt>.
<code>
... demand=demand.csv ...
</code>

* patch parameters from the calibration step
<code>
... discount_factor=0.3 compactness_mean=0.4 compactness_range=0.08 patch_sizes=patches.txt ...
</code>

* recommended parameters for patch growing algorithm
<code>
... num_neighbors=4 seed_search=2 ...
</code>

* set random seed for repeatable results or set flag <tt>-s</tt> to generate seed automatically
<code>
... random_seed=1 ...
</code>

* specify final output map and optionally basename for intermediate raster maps
<code>
output=final output_series=final
</code>

== Scenarios ==
Scenarios involving policies that encourage infill versus sprawl can be explored using the <tt>incentive_power</tt> parameter of {{AddonCmd|r.futures.pga}},
which uses a power function to transform the evenness of the probability gradient in POTENTIAL. You can change the power to a number between 0.25 and 4 to test urban sprawl/infill scenarios.
Higher power leads to infill behavior, lower power to urban sprawl.

== Postprocessing ==

Follow a [[Creating_animation_from_FUTURES_output_in_GRASS_GIS| tutorial how to make an animation from the results]].

= GRASS GIS Python API =

[[Category: Tutorial]]
[[Category: FUTURES]]
[[Category: Urban]]

Workshop on urban growth modeling with FUTURES

2016-03-22T18:34:17Z

⚠️Dbvanber: /* GRASS directory */

{{ToModify}}
= Workshop introduction =
r.futures.* is an implementation of the '''FUT'''ure '''U'''rban-'''R'''egional '''E'''nvironment '''S'''imulation (FUTURES)[1] which is a model for multilevel simulations of emerging urban-rural landscape structure. FUTURES produces regional projections of landscape patterns using coupled submodels that integrate nonstationary drivers of land change: per capita demand (DEMAND submodel), site suitability (POTENTIAL submodel), and the spatial structure of conversion events (PGA submodel).

[1] Meentemeyer, R. K., Tang, W., Dorning, M. A., Vogler, J. B., Cunniffe, N. J., & Shoemaker, D. A. (2013). [http://www.tandfonline.com/doi/abs/10.1080/00045608.2012.707591 FUTURES: multilevel simulations of emerging urban-rural landscape structure using a stochastic patch-growing algorithm.] Annals of the Association of American Geographers, 103(4), 785-807

== Software ==
There are a number of software requirements to run FUTURES that will need to be download and installed. Required software includes:
* GRASS GIS 7
* addons
** {{AddonCmd|r.futures.pga}}
** {{AddonCmd|r.futures.potential}}
** {{AddonCmd|r.futures.potsurface}}
** {{AddonCmd|r.futures.demand}}
** {{AddonCmd|r.futures.devpressure}}
** {{AddonCmd|r.sample.category}}
* R (≥ 3.0.2) - needed for {{AddonCmd|r.futures.potential}} with packages:
**MuMIn, lme4, optparse, rgrass7
* SciPy - useful for {{AddonCmd|r.futures.demand}}

=== Installation ===
We use the R statistical software for our calculation of site suitability (i.e. development potential) in FUTURES. R is a free software environment for statistical computing and graphics. If you don't have R, or you have older an version, please download and install the software from [http://archive.linux.duke.edu/cran/ install R] and be sure to additionally add these required packages:
<pre>
install.packages(c("MuMIn", "lme4", "optparse", "rgrass7"))
</pre>

==== MS Windows ====
We will be using GRASS GIS 7.0.3 that can be found here in the [https://trac.osgeo.org/osgeo4w/ OSGeo4W] package manager.
Please install the latest stable GRASS GIS 7 version and the SciPy Python package using the ''Advanced install'' option.
A guide with step by step screen shot instructions is available [https://docs.google.com/presentation/d/1yEGpriBne7RvjB35HI6GecNwO1P1y2nRGqDThqoNnCE/edit?usp=sharing here].

In order for GRASS to be able to find R executables, GRASS must be on the PATH variable. Follow this [solution] to make R accessible from GRASS permanently.
A simple but temporary solution is to open GRASS GIS and paste this in the black terminal:
<pre>
set PATH=%PATH%;C:\Program Files\R\R-3.0.2\bin
</pre>
This has to be repeated after restarting GRASS session.

==== Ubuntu Linux ====
Install GRASS GIS from packages:
<pre>
sudo add-apt-repository ppa:ubuntugis/ubuntugis-unstable
sudo apt-get update
sudo apt-get install grass
</pre>

== Workshop data ==
The data that we will be using for the workshop can be download here: [http://fatra.cnr.ncsu.edu/futures/futures_ncspm_Asheville.zip sample dataset]. Please place these layers in your local GRASS directory:
* digital elevation model ([http://nationalmap.gov/elevation.html NED])
* [http://www.mrlc.gov/ NLCD] 2001, 2011
* NLCD 1992/2001 Retrofit Land Cover Change Product
* transportation network ([http://www.census.gov/geo/maps-data/data/tiger-line.html TIGER])
* county boundaries ([http://www.census.gov/geo/maps-data/data/tiger-line.html TIGER])
* protected areas ([http://www.conservationgateway.org/ConservationByGeography/NorthAmerica/UnitedStates/edc/reportsdata/terrestrial/secured/Pages/default.aspx Secured Lands])
* cities as points (USGS)

In addition, download [http://fatra.cnr.ncsu.edu/futures/futures_Asheville_files.zip population information as text files]:
* county population past estimates and future projections ([https://www.osbm.nc.gov/demog/county-projections NC OSBM]) per county (nonspatial)

= GRASS GIS introduction =
There are many advantages to using the open source GRASS GIS platform, but for many that are more familiar with ARCGis and QGis, the setup and implementation of spatial tools in GRASS can be confusing. Here we provide an overview of the GRASS GIS project: [https://grass.osgeo.org grass.osgeo.org] that might be helpful to review if you are a first time users. For this exercise it's not necessary to have a full understanding of how to use GRASS. However, you will need to know how to place your data in the correct GRASS database directory, as well as some basic GRASS functionality. Step by step instructions are provided below
== GRASS directory ==
GRASS uses unique database terminology and structure that are important to understand [https://grass.osgeo.org/grass71/manuals/grass_database.html GRASS database] for the set up of this tutorial as you will need to place the required data (e.g. Mapset) in a specific GRASS database Location.

=== Important GRASS directory terminology ===
* A '''GRASS database''' consist of directory with specific Locations (projects) where data layer are stored
* '''Location''' hold all Mapsets in a specific directoy that have the same spatial projection (spatial reference system)
* '''Mapset''' are a collection of maps with the same spatial projection

To Download the [http://fatra.cnr.ncsu.edu/futures/futures_ncspm_Asheville.zip workshop location]. Create (unless you already have it) a directory named <tt>grassdata</tt> (GRASS database) in your home folder (or Documents), unzip the downloaded data into this directory. You should have now Location <tt>futures_ncspm</tt> in <tt>grassdata</tt>.
* Launch GRASS and display raster, vector data, explore navigation, querying, adding legend, showing metadata
<center><gallery perrow=3 widths=500 heights=250>Image:GRASS FUTURES startup.png|GRASS GIS 7.0.3 startup dialog with downloaded Location and Mapsets for FUTURES workshop
Image:GRASS FUTURES wxGUI display.png|Layer Manager and Map Display overview. Annotations show how to add raster layer, query, add legend.
Image:wxGUI_metadata_rinfo.png|Show raster map metadata by right click on layer</gallery></center>

* GRASS GIS has over [https://grass.osgeo.org/grass70/manuals/full_index.html 500 different modules] in the core distribution and over [https://grass.osgeo.org/grass70/manuals/addons/ 230 addon modules]
<center>
{| class="wikitable"
|-
! Prefix !! Function !! Example
|-
| r.* || raster processing || ''{{cmd|r.mapcalc}}'': map algebra
|-
| v.* || vector processing || ''{{cmd|v.clean}}'': topological cleaning
|-
| i.* || imagery processing || ''{{cmd|i.segment}}'': object recognition
|-
| db.* || database management || ''{{cmd|db.select}}'': select values from table
|-
| r3.* || 3D raster processing || ''{{cmd|r3.stats}}'': 3D raster statistics
|-
| t.* || temporal data processing || ''{{cmd|t.rast.aggregate}}'': temporal aggregation
|-
| g.* || general data management || ''{{cmd|g.rename}}'': renames map
|-
| d.* || display ||''{{cmd|d.rast}}'': display raster map
|}</center>
* GRASS modules have GUI and command line interface. In this workshop we use commands to describe the workflow, but we can use both GUI and command line depending on personal preference. Look how {{cmd|wxGUI.modules|version=71|desc=GUI and command line interface}} represent the same tool. ''Task:'' compute aspect (orientation) from provided digital elevation model using module {{cmd|r.slope.aspect}} using both module dialog and command line.
* How to find modules? Modules are organized by their functionality in wxGUI menu, or we can search for them in Search modules tab. If we already know which module to use, we can just type it in the wxGUI command console. <center><gallery perrow=3 widths=380 heights=190>Image:wxGUI_menu_rinfo.png|Modules can be found in wxGUI menu
Image:wxGUI_module_search.png|You can search modules by name, description or keywords in ''Search modules'' tab
Image:wxGUI_console_completion.png|By typing prefix r. we make a list of modules starting with that prefix to show up.</gallery></center>


* {{cmd|g.region|desc=Computational region}} - an important raster concept
** defined by region extent and raster resolution
** applies to all raster operations
** persists between GRASS session, can be different for different mapsets
** advantages: keeps your results consistent, avoid clipping, for computationally demanding tasks set region to smaller extent, check your result is good and then set the computational region to the entire study area and rerun analysis
** run <code>g.region -p</code> or in menu ''Settings'' - ''Region'' - ''Display region'' to see current region settings
[[File:WxGUI set region.png|700px|thumb|center|Simple ways to set computational region from GUI. On the left, set region to match raster map. On the right, select the highlighted option and then set region by drawing rectangle.]]

* GRASS 3D view

= Modeling with FUTURES =
== Initial steps and data preparation ==
First we will set the computational region of our analyses to an extent covering our study area and aligned with our base landuse rasters:
<source lang="bash">g.region raster=landuse_2011 -p</source>

We will derive urbanized areas from NLCD dataset for year 1992, 2001 and 2011
by extracting categories category 21 - 24 into a new binary map where developed is 1,
undeveloped 0 and NULL (no data) is area unsuitable for development (water, wetlands, protected areas).
First we will convert protected areas from vector to raster. We set
NULLs to zeros (for simpler raster algebra expression in the next step) using {{cmd|r.null}}:

<source lang="bash">
v.to.rast input=protected_areas output=protected_areas use=val
r.null map=protected_areas null=0
</source>

And then create rasters of developed/undeveloped areas using raster algebra:

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.mapcalc "urban_1992 = if(landuse_1992 >= 21 && landuse_1992 <= 24, 1, if(landuse_1992 == 11 || landuse_1992 >= 90 || protected_areas, null(), 0))"
r.mapcalc "urban_2001 = if(landuse_2001 >= 21 && landuse_2001 <= 24, 1, if(landuse_2001 == 11 || landuse_2001 >= 90 || protected_areas, null(), 0))"
r.mapcalc "urban_2011 = if(landuse_2011 >= 21 && landuse_2011 <= 24, 1, if(landuse_2011 == 11 || landuse_2011 >= 90 || protected_areas, null(), 0))"
</source>

We will convert vector counties to raster with the values of the FIPS attribute which links to population file:

<source lang="bash">
v.to.rast input=counties type=area use=attr attribute_column=FIPS output=counties
</source>

Before further steps, we will set our working directory so that the input population files and text files
we are going to create are saved in one directory and easily accessible.
You can do that from menu ''Settings'' → ''GRASS working environment'' → ''Change working directory''.
Select (or create) a directory and move there the downloaded files <tt>population_projection.csv</tt> and <tt>population_trend.csv</tt>.

== Potential submodel ==
Module {{AddonCmd|r.futures.potential}} implements POTENTIAL submodel as a part of FUTURES land change model. POTENTIAL is implemented using a set of coefficients that relate a selection of site suitability factors to the probability of a place becoming developed. This is implemented using the parameter table in combination with maps of those site suitability factors (mapped predictors). The coefficients are obtained by conducting multilevel logistic regression in R with package lme4 where the coefficients may vary by county. The best model is selected automatically using dredge function from package [https://cran.r-project.org/web/packages/MuMIn/index.html MuMIn].

First, we will derive couple of predictors.
=== Predictors ===
==== Slope ====
We will derive slope in degrees from digital elevation model using {{cmd|r.slope.aspect}} module:
<source lang="bash">r.slope.aspect elevation=elevation_30m slope=slope</source>

==== Distance from lakes/rivers ====
First we will extract [http://www.mrlc.gov/nlcd11_leg.php category ''Open Water''] from 2011 NLCD dataset:
<source lang="bash">
r.mapcalc "water = if(landuse_2011 == 11, 1, null())"
</source>

Then we compute the distance to water with module {{cmd|r.grow.distance}} and set color table to shades of blue:
<source lang="bash">
r.grow.distance input=water distance=dist_to_water
r.colors -n map=dist_to_water color=blues
</source>

==== Distance from protected areas ====
We will use raster protected of protected areas we already created, but we will set NULL values to zero.
We compute the distance to protected areas with module {{cmd|r.grow.distance}} and set color table from green to red:
<source lang="bash">
r.null map=protected_areas setnull=0
r.grow.distance input=protected_areas distance=dist_to_protected
r.colors map=dist_to_protected color=gyr
</source>

==== Forests ====
We will smooth the transition between forest and other land use, see NLCD [http://www.mrlc.gov/nlcd11_leg.php category ''Open Water'']:
<source lang="bash">
r.mapcalc "forest = if(landuse_2011 >= 41 && landuse_2011 <= 43, 1, 0)"
r.neighbors -c input=forest output=forest_smooth size=15 method=average
r.colors map=forest_smooth color=ndvi
</source>

==== Travel time to cities ====
Here we will compute travel time to cities (with population > 5000)
as cumulative cost distance where cost is defined as travel time on roads.
First we specify the speed on different types of roads.
We copy the roads raster into our mapset so that we can change it
by adding a new attribute field <tt>speed</tt>. Then we assign speed values (km/h) based on the type of road:

<source lang="bash">
g.copy vector=roads,myroads
v.db.addcolumn map=myroads columns="speed double precision"
v.db.update map=myroads column=speed value=50 where="MTFCC = 'S1400'"
v.db.update map=myroads column=speed value=100 where="MTFCC IN ('S1100', 'S1200')"
</source>

Now we rasterize the selected road types using the speed values from the attribute table as raster values.

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
v.to.rast input=myroads type=line where="MTFCC IN ('S1100', 'S1200', 'S1400')" output=roads_speed use=attr attribute_column=speed
</source>

We set the rest of the area to low speed and recompute the speed as time to travel through a 30m cell in minutes:

<source lang="bash">
r.null map=roads_speed null=5
r.mapcalc "roads_travel_time = 1.8 / roads_speed"
</source>

Finally we compute the travel time to larger cities using {{cmd|r.cost}}:

<source lang="bash">
r.cost input=roads_travel_time output=travel_time_cities start_points=cities
r.colors map=travel_time_cities color=byr
</source>

==== Road density ====
We will rasterize roads and use moving window analysis ({{cmd|r.neighbors}}) to compute road density:

<source lang="bash">
v.to.rast input=roads output=roads use=val type=line
r.null map=roads null=0
r.neighbors -c input=roads output=road_dens size=25 method=average
</source>

==== Distance to interchanges ====

We will consider TIGER roads of type <tt>Ramp</tt> as interchanges, rasterize them and compute euclidean distance to them:

<source lang="bash">
v.to.rast input=roads type=line where="MTFCC = 'S1630'" output=interchanges use=val
r.grow.distance -m input=interchanges distance=dist_interchanges
</source>

=== Development pressure ===

We compute development pressure with {{AddonCmd|r.futures.devpressure}}. Development pressure is a predictor based on number of neighboring developed cells within search distance, weighted by distance. The development pressure variable plays a special role in the model, allowing for a feedback between predicted change and change in subsequent steps.

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.devpressure -n input=urban_2011 output=devpressure_2 method=gravity size=7 gamma=2 scaling_factor=10
r.futures.devpressure -n input=urban_2011 output=devpressure_1 method=gravity size=10 gamma=1 scaling_factor=1
r.futures.devpressure -n input=urban_2011 output=devpressure_0_5 method=gravity size=30 gamma=0.5 scaling_factor=0.1
</source>

When gamma increases, development influence decreases more rapidly with distance.
Size is half the size of the moving window. When gamma is low, local development influences more distant places.
We will derive 3 layers with different gamma and size parameters for the potential statistical model.

=== Rescaling variables ===

First we will look at the ranges of our predictor variables by running a short Python code snippet in Python shell:

<source lang="python" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
for name in ['slope', 'dist_to_water', 'dist_to_protected', 'forest_smooth', 'travel_time_cities', 'road_dens', 'dist_interchanges', 'devpressure_0_5', 'devpressure_1']:
minmax = grass.raster_info(name)
print name, minmax['min'], minmax['max']
</source>

We will rescale some of our input variables:

<source lang="bash">
r.mapcalc "dist_to_water_km = dist_to_water / 1000"
r.mapcalc "dist_to_protected_km = dist_to_protected / 1000"
r.mapcalc "dist_interchanges_km = dist_interchanges / 1000"
r.mapcalc "road_dens_perc = road_dens * 100"
r.mapcalc "forest_smooth_perc = forest_smooth * 100"
</source>

=== Sampling ===
To sample only in the analyzed counties, we will clip development layer:

<source lang="bash">
r.mapcalc "urban_change_01_11 = if(urban_2011 == 1, if(urban_2001 == 0, 1, null()), 0)"
r.mapcalc "urban_change_clip = if(counties, urban_change_01_11)"
</source>

To estimate the number of sampling points, we can use {{cmd|r.report}} to report number of developed/undeveloped cells and their ratio.

<source lang="bash">
r.report map=urban_change_clip units=h,c,p
</source>

We will sample the predictors and the response variable with 5000 random points in undeveloped areas and 1000 points in developed area:

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.sample.category input=urban_change_clip output=sampling sampled=counties,devpressure_0_5,devpressure_1,devpressure_2,slope,road_dens_perc,forest_smooth_perc,dist_to_water_km,dist_to_protected_km,dist_interchanges_km,travel_time_cities npoints=5000,1000
</source>

The attribute table can be exported as CSV file (not necessary step):

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
v.db.select map=sampling columns=urban_change_clip,counties,devpressure_0_5,devpressure_1,slope,road_dens_perc,forest_smooth_perc,dist_to_water_km,dist_to_protected_km,dist_interchanges_km,travel_time_cities separator=comma file=samples.csv
</source>

=== Development potential ===
Now we find best model for predicting urbanization using {{AddonCmd|r.futures.potential}} which wraps an R script.

We can run R [http://www.inside-r.org/packages/cran/MuMIn/docs/dredge dredge] function to find "best" model. We can specify minimum and maximum number of predictors the final model should use.
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.potential -d input=sampling output=potential.csv columns=devpressure_1,slope,road_dens_perc,forest_smooth_perc,dist_to_water_km,dist_to_protected_km,dist_interchanges_km,travel_time_cities developed_column=urban_change_clip subregions_column=counties min_variables=4
</source>

Also, we can play with different combinations of predictors, for example:

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.potential input=sampling output=potential.csv columns=devpressure_2,road_dens_perc,slope,dist_interchanges_km,dist_to_water_km developed_column=urban_change_clip subregions_column=counties --o
r.futures.potential input=sampling output=potential.csv columns=devpressure_1,road_dens_perc,slope,dist_interchanges_km,dist_to_water_km developed_column=urban_change_clip subregions_column=counties --o
...
</source>

You can then open the output file <tt>potential.csv</tt>, which is a CSV file with tabs as separators.

For this tutorial, the final potential is created with:
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.potential input=sampling output=potential.csv columns=devpressure_2,road_dens_perc,slope,dist_interchanges_km,dist_to_water_km developed_column=urban_change_clip subregions_column=counties --o
</source>

We can now visualize the suitability surface using module {{AddonCmd|r.futures.potsurface}}. It creates initial development potential (suitability) raster from predictors and model coefficients and serves only for evaluating development potential model. The values of the resulting raster range from 0 to 1.

<source lang="bash">
r.futures.potsurface input=potential.csv subregions=counties output=suitability
r.colors map=suitability color=byr
</source>

== Demand submodel ==
First we will mask out roads so that they don't influence into per capita land demand relation.
<source lang="bash">
v.to.rast input=roads type=line output=roads_mask use=val
r.mask roads_mask -i
</source>

We will use {{AddonCmd|r.futures.demand}} which derives the population vs. development relation. The relation can be linear/logarithmic/logarithmic2/exponential/exponential approach.
Look for examples of the different relations in the manual.

* linear: y = A + Bx
* logarithmic: y = A + Bln(x)
* logarithmic2: y = A + B * ln(x - C)        (requires SciPy)
* exponential: y = Ae^(BX)
* exp_approach: y = (1 - e^(-A(x - B))) + C        (requires SciPy)

The format of the input population CSV files is described in the manual. It is important to have synchronized categories of subregions and the column headers of the CSV files (in our case FIPS number). How to simply generate the list of years (for which demand is computed) is described in {{AddonCmd|r.futures.demand}} manual, for example run this in Python console:

<source lang="python">
','.join([str(i) for i in range(2011, 2036)])
</source>

Then we can create the DEMAND file:
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.demand development=urban_1992,urban_2001,urban_2011 subregions=counties observed_population=population_trend.csv projected_population=population_projection.csv simulation_times=2011,2012,2013,2014,2015,2016,2017,2018,2019,2020,2021,2022,2023,2024,2025,2026,2027,2028,2029,2030,2031,2032,2033,2034,2035 plot=plot_demand.pdf demand=demand.csv separator=comma
</source>

In your current working directory, you should find files <tt>plot_demand.png</tt> and <tt>demand.csv</tt>.

If you have SciPy installed, you can experiment with other methods for fitting the functions:
<source lang="bash">
r.futures.demand ... method=logarithmic2
r.futures.demand ... method=exp_approach
</source>
If necessary, you can create a set of demand files produced by fitting each method separately and
then pick for each county the method which seems best and manually create a new demand file.

When you are finished, remove the mask as it is not needed for the next steps.
<source lang="bash">
r.mask -r
</source>

== Patch calibration ==
Patch calibration can be a very time consuming computation.
Therefore we select only one county (Buncombe):

<source lang="bash">
v.to.rast input=counties type=area where="FIPS == 37021" use=attr attribute_column=FIPS output=calib_county
g.region raster=calib_county zoom=calib_county
</source>
to derive patches of new development by comparing historical and latest development.
We can keep only patches with minimum size 2 cells (1800 = 2 x 30 x 30 m).

<source lang="bash">
r.futures.calib development_start=urban_1992 development_end=urban_2011 subregions=counties patch_sizes=patches.txt patch_threshold=1800 -l
</source>
We obtained a file <tt>patches.txt</tt> (used later in the PGA) - a patch size distribution file - containing sizes of all found patches.

We can look at the distribution of the patch sizes:

<source lang="python">
from matplotlib import pyplot as plt
with open('patches.txt') as f:
patches = [int(patch) for patch in f.readlines()]
plt.hist(patches, 2000)
plt.xlim(0,50)
plt.show()
</source>

At this point, we start the calibration to get best parameters of patch shape
(for this tutorial, this step can be skipped and the suggested parameters are used).

<source lang="bash"
style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.calib development_start=urban_1992 development_end=urban_2011 subregions=calib_county patch_sizes=patches.txt calibration_results=calib.csv patch_threshold=1800 repeat=5 compactness_mean=0.1,0.3,0.5,0.7,0.9 compactness_range=0.05 discount_factor=0.1,0.3,0.5,0.7,0.9 predictors=road_dens_perc,forest_smooth_perc,dist_to_protected_km demand=demand.csv devpot_params=potential.csv num_neighbors=4 seed_search=2 development_pressure=devpressure_0_5 development_pressure_approach=gravity n_dev_neighbourhood=30 gamma=0.5 scaling_factor=0.1
</source>

== FUTURES simulation ==
We will switch back to our previous region:
<source lang="bash">
g.region raster=landuse_2011 -p
</source>

Now we have all the inputs necessary for running {{AddonCmd|r.futures.pga}}:

The entire command is here:
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.pga subregions=counties developed=urban_2011 predictors=slope,forest_smooth_perc,dist_interchanges_km,travel_time_cities devpot_params=potential.csv development_pressure=devpressure_1 n_dev_neighbourhood=10 development_pressure_approach=gravity gamma=1 scaling_factor=1 demand=demand.csv discount_factor=0.3 compactness_mean=0.2 compactness_range=0.1 patch_sizes=patches.txt num_neighbors=4 seed_search=2 random_seed=1 output=final output_series=final
</source>

=== Quick description ===
The command parameters and their values:
* raster map of counties with their categories
<code>
... subregions=counties ...
</code>

* raster of developed (1), undeveloped (0) and NULLs for undevelopable areas
<code>
... developed=urban_2011 ...
</code>

* predictors selected with {{AddonCmd|r.futures.potential}} and their coefficients in a <tt>potential.csv</tt> file. The order of predictors must match the order in the file and the categories of the counties must match raster <tt>counties</tt>.
<code>
... predictors=slope,forest_smooth_perc,dist_interchanges_km,travel_time_cities devpot_params=potential.csv ...
</code>

* initial development pressure computed by {{AddonCmd|r.futures.devpressure}}, it's important to set here the same parameters
<code>
... development_pressure=devpressure_1 n_dev_neighbourhood=10 development_pressure_approach=gravity gamma=1 scaling_factor=1 ...
</code>

* per capita land demand computed by {{AddonCmd|r.futures.demand}}, the categories of the counties must match raster <tt>counties</tt>.
<code>
... demand=demand.csv ...
</code>

* patch parameters from the calibration step
<code>
... discount_factor=0.3 compactness_mean=0.4 compactness_range=0.08 patch_sizes=patches.txt ...
</code>

* recommended parameters for patch growing algorithm
<code>
... num_neighbors=4 seed_search=2 ...
</code>

* set random seed for repeatable results or set flag <tt>-s</tt> to generate seed automatically
<code>
... random_seed=1 ...
</code>

* specify final output map and optionally basename for intermediate raster maps
<code>
output=final output_series=final
</code>

== Scenarios ==
Scenarios involving policies that encourage infill versus sprawl can be explored using the <tt>incentive_power</tt> parameter of {{AddonCmd|r.futures.pga}},
which uses a power function to transform the evenness of the probability gradient in POTENTIAL. You can change the power to a number between 0.25 and 4 to test urban sprawl/infill scenarios.
Higher power leads to infill behavior, lower power to urban sprawl.

== Postprocessing ==

Follow a [[Creating_animation_from_FUTURES_output_in_GRASS_GIS| tutorial how to make an animation from the results]].

= GRASS GIS Python API =

[[Category: Tutorial]]
[[Category: FUTURES]]
[[Category: Urban]]

Workshop on urban growth modeling with FUTURES

2016-03-22T18:32:40Z

⚠️Dbvanber: /* GRASS directory */

{{ToModify}}
= Workshop introduction =
r.futures.* is an implementation of the '''FUT'''ure '''U'''rban-'''R'''egional '''E'''nvironment '''S'''imulation (FUTURES)[1] which is a model for multilevel simulations of emerging urban-rural landscape structure. FUTURES produces regional projections of landscape patterns using coupled submodels that integrate nonstationary drivers of land change: per capita demand (DEMAND submodel), site suitability (POTENTIAL submodel), and the spatial structure of conversion events (PGA submodel).

[1] Meentemeyer, R. K., Tang, W., Dorning, M. A., Vogler, J. B., Cunniffe, N. J., & Shoemaker, D. A. (2013). [http://www.tandfonline.com/doi/abs/10.1080/00045608.2012.707591 FUTURES: multilevel simulations of emerging urban-rural landscape structure using a stochastic patch-growing algorithm.] Annals of the Association of American Geographers, 103(4), 785-807

== Software ==
There are a number of software requirements to run FUTURES that will need to be download and installed. Required software includes:
* GRASS GIS 7
* addons
** {{AddonCmd|r.futures.pga}}
** {{AddonCmd|r.futures.potential}}
** {{AddonCmd|r.futures.potsurface}}
** {{AddonCmd|r.futures.demand}}
** {{AddonCmd|r.futures.devpressure}}
** {{AddonCmd|r.sample.category}}
* R (≥ 3.0.2) - needed for {{AddonCmd|r.futures.potential}} with packages:
**MuMIn, lme4, optparse, rgrass7
* SciPy - useful for {{AddonCmd|r.futures.demand}}

=== Installation ===
We use the R statistical software for our calculation of site suitability (i.e. development potential) in FUTURES. R is a free software environment for statistical computing and graphics. If you don't have R, or you have older an version, please download and install the software from [http://archive.linux.duke.edu/cran/ install R] and be sure to additionally add these required packages:
<pre>
install.packages(c("MuMIn", "lme4", "optparse", "rgrass7"))
</pre>

==== MS Windows ====
We will be using GRASS GIS 7.0.3 that can be found here in the [https://trac.osgeo.org/osgeo4w/ OSGeo4W] package manager.
Please install the latest stable GRASS GIS 7 version and the SciPy Python package using the ''Advanced install'' option.
A guide with step by step screen shot instructions is available [https://docs.google.com/presentation/d/1yEGpriBne7RvjB35HI6GecNwO1P1y2nRGqDThqoNnCE/edit?usp=sharing here].

In order for GRASS to be able to find R executables, GRASS must be on the PATH variable. Follow this [solution] to make R accessible from GRASS permanently.
A simple but temporary solution is to open GRASS GIS and paste this in the black terminal:
<pre>
set PATH=%PATH%;C:\Program Files\R\R-3.0.2\bin
</pre>
This has to be repeated after restarting GRASS session.

==== Ubuntu Linux ====
Install GRASS GIS from packages:
<pre>
sudo add-apt-repository ppa:ubuntugis/ubuntugis-unstable
sudo apt-get update
sudo apt-get install grass
</pre>

== Workshop data ==
The data that we will be using for the workshop can be download here: [http://fatra.cnr.ncsu.edu/futures/futures_ncspm_Asheville.zip sample dataset]. Please place these layers in your local GRASS directory:
* digital elevation model ([http://nationalmap.gov/elevation.html NED])
* [http://www.mrlc.gov/ NLCD] 2001, 2011
* NLCD 1992/2001 Retrofit Land Cover Change Product
* transportation network ([http://www.census.gov/geo/maps-data/data/tiger-line.html TIGER])
* county boundaries ([http://www.census.gov/geo/maps-data/data/tiger-line.html TIGER])
* protected areas ([http://www.conservationgateway.org/ConservationByGeography/NorthAmerica/UnitedStates/edc/reportsdata/terrestrial/secured/Pages/default.aspx Secured Lands])
* cities as points (USGS)

In addition, download [http://fatra.cnr.ncsu.edu/futures/futures_Asheville_files.zip population information as text files]:
* county population past estimates and future projections ([https://www.osbm.nc.gov/demog/county-projections NC OSBM]) per county (nonspatial)

= GRASS GIS introduction =
There are many advantages to using the open source GRASS GIS platform, but for many that are more familiar with ARCGis and QGis, the setup and implementation of spatial tools in GRASS can be confusing. Here we provide an overview of the GRASS GIS project: [https://grass.osgeo.org grass.osgeo.org] that might be helpful to review if you are a first time users. For this exercise it's not necessary to have a full understanding of how to use GRASS. However, you will need to know how to place your data in the correct GRASS database directory, as well as some basic GRASS functionality. Step by step instructions are provided below
== GRASS directory ==
GRASS uses unique database terminology and structure that are important to understand [https://grass.osgeo.org/grass71/manuals/grass_database.html GRASS database] for the set up of this tutorial as you will need to place the required data (e.g. Mapset) in a specific GRASS database Location.

'''Important GRASS directory terminology'''
* A'''GRASS database''' consist of directory with specific Locations (projects) where data layer are stored
* '''Location''' hold all Mapsets in a specific directoy that have the same spatial projection (spatial reference system)
* '''Mapset''' are a collection of maps with the same spatial projection

To Download the [http://fatra.cnr.ncsu.edu/futures/futures_ncspm_Asheville.zip workshop location]. Create (unless you already have it) a directory named <tt>grassdata</tt> (GRASS database) in your home folder (or Documents), unzip the downloaded data into this directory. You should have now Location <tt>futures_ncspm</tt> in <tt>grassdata</tt>.
* Launch GRASS and display raster, vector data, explore navigation, querying, adding legend, showing metadata
<center><gallery perrow=3 widths=500 heights=250>Image:GRASS FUTURES startup.png|GRASS GIS 7.0.3 startup dialog with downloaded Location and Mapsets for FUTURES workshop
Image:GRASS FUTURES wxGUI display.png|Layer Manager and Map Display overview. Annotations show how to add raster layer, query, add legend.
Image:wxGUI_metadata_rinfo.png|Show raster map metadata by right click on layer</gallery></center>

* GRASS GIS has over [https://grass.osgeo.org/grass70/manuals/full_index.html 500 different modules] in the core distribution and over [https://grass.osgeo.org/grass70/manuals/addons/ 230 addon modules]
<center>
{| class="wikitable"
|-
! Prefix !! Function !! Example
|-
| r.* || raster processing || ''{{cmd|r.mapcalc}}'': map algebra
|-
| v.* || vector processing || ''{{cmd|v.clean}}'': topological cleaning
|-
| i.* || imagery processing || ''{{cmd|i.segment}}'': object recognition
|-
| db.* || database management || ''{{cmd|db.select}}'': select values from table
|-
| r3.* || 3D raster processing || ''{{cmd|r3.stats}}'': 3D raster statistics
|-
| t.* || temporal data processing || ''{{cmd|t.rast.aggregate}}'': temporal aggregation
|-
| g.* || general data management || ''{{cmd|g.rename}}'': renames map
|-
| d.* || display ||''{{cmd|d.rast}}'': display raster map
|}</center>
* GRASS modules have GUI and command line interface. In this workshop we use commands to describe the workflow, but we can use both GUI and command line depending on personal preference. Look how {{cmd|wxGUI.modules|version=71|desc=GUI and command line interface}} represent the same tool. ''Task:'' compute aspect (orientation) from provided digital elevation model using module {{cmd|r.slope.aspect}} using both module dialog and command line.
* How to find modules? Modules are organized by their functionality in wxGUI menu, or we can search for them in Search modules tab. If we already know which module to use, we can just type it in the wxGUI command console. <center><gallery perrow=3 widths=380 heights=190>Image:wxGUI_menu_rinfo.png|Modules can be found in wxGUI menu
Image:wxGUI_module_search.png|You can search modules by name, description or keywords in ''Search modules'' tab
Image:wxGUI_console_completion.png|By typing prefix r. we make a list of modules starting with that prefix to show up.</gallery></center>


* {{cmd|g.region|desc=Computational region}} - an important raster concept
** defined by region extent and raster resolution
** applies to all raster operations
** persists between GRASS session, can be different for different mapsets
** advantages: keeps your results consistent, avoid clipping, for computationally demanding tasks set region to smaller extent, check your result is good and then set the computational region to the entire study area and rerun analysis
** run <code>g.region -p</code> or in menu ''Settings'' - ''Region'' - ''Display region'' to see current region settings
[[File:WxGUI set region.png|700px|thumb|center|Simple ways to set computational region from GUI. On the left, set region to match raster map. On the right, select the highlighted option and then set region by drawing rectangle.]]

* GRASS 3D view

= Modeling with FUTURES =
== Initial steps and data preparation ==
First we will set the computational region of our analyses to an extent covering our study area and aligned with our base landuse rasters:
<source lang="bash">g.region raster=landuse_2011 -p</source>

We will derive urbanized areas from NLCD dataset for year 1992, 2001 and 2011
by extracting categories category 21 - 24 into a new binary map where developed is 1,
undeveloped 0 and NULL (no data) is area unsuitable for development (water, wetlands, protected areas).
First we will convert protected areas from vector to raster. We set
NULLs to zeros (for simpler raster algebra expression in the next step) using {{cmd|r.null}}:

<source lang="bash">
v.to.rast input=protected_areas output=protected_areas use=val
r.null map=protected_areas null=0
</source>

And then create rasters of developed/undeveloped areas using raster algebra:

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.mapcalc "urban_1992 = if(landuse_1992 >= 21 && landuse_1992 <= 24, 1, if(landuse_1992 == 11 || landuse_1992 >= 90 || protected_areas, null(), 0))"
r.mapcalc "urban_2001 = if(landuse_2001 >= 21 && landuse_2001 <= 24, 1, if(landuse_2001 == 11 || landuse_2001 >= 90 || protected_areas, null(), 0))"
r.mapcalc "urban_2011 = if(landuse_2011 >= 21 && landuse_2011 <= 24, 1, if(landuse_2011 == 11 || landuse_2011 >= 90 || protected_areas, null(), 0))"
</source>

We will convert vector counties to raster with the values of the FIPS attribute which links to population file:

<source lang="bash">
v.to.rast input=counties type=area use=attr attribute_column=FIPS output=counties
</source>

Before further steps, we will set our working directory so that the input population files and text files
we are going to create are saved in one directory and easily accessible.
You can do that from menu ''Settings'' → ''GRASS working environment'' → ''Change working directory''.
Select (or create) a directory and move there the downloaded files <tt>population_projection.csv</tt> and <tt>population_trend.csv</tt>.

== Potential submodel ==
Module {{AddonCmd|r.futures.potential}} implements POTENTIAL submodel as a part of FUTURES land change model. POTENTIAL is implemented using a set of coefficients that relate a selection of site suitability factors to the probability of a place becoming developed. This is implemented using the parameter table in combination with maps of those site suitability factors (mapped predictors). The coefficients are obtained by conducting multilevel logistic regression in R with package lme4 where the coefficients may vary by county. The best model is selected automatically using dredge function from package [https://cran.r-project.org/web/packages/MuMIn/index.html MuMIn].

First, we will derive couple of predictors.
=== Predictors ===
==== Slope ====
We will derive slope in degrees from digital elevation model using {{cmd|r.slope.aspect}} module:
<source lang="bash">r.slope.aspect elevation=elevation_30m slope=slope</source>

==== Distance from lakes/rivers ====
First we will extract [http://www.mrlc.gov/nlcd11_leg.php category ''Open Water''] from 2011 NLCD dataset:
<source lang="bash">
r.mapcalc "water = if(landuse_2011 == 11, 1, null())"
</source>

Then we compute the distance to water with module {{cmd|r.grow.distance}} and set color table to shades of blue:
<source lang="bash">
r.grow.distance input=water distance=dist_to_water
r.colors -n map=dist_to_water color=blues
</source>

==== Distance from protected areas ====
We will use raster protected of protected areas we already created, but we will set NULL values to zero.
We compute the distance to protected areas with module {{cmd|r.grow.distance}} and set color table from green to red:
<source lang="bash">
r.null map=protected_areas setnull=0
r.grow.distance input=protected_areas distance=dist_to_protected
r.colors map=dist_to_protected color=gyr
</source>

==== Forests ====
We will smooth the transition between forest and other land use, see NLCD [http://www.mrlc.gov/nlcd11_leg.php category ''Open Water'']:
<source lang="bash">
r.mapcalc "forest = if(landuse_2011 >= 41 && landuse_2011 <= 43, 1, 0)"
r.neighbors -c input=forest output=forest_smooth size=15 method=average
r.colors map=forest_smooth color=ndvi
</source>

==== Travel time to cities ====
Here we will compute travel time to cities (with population > 5000)
as cumulative cost distance where cost is defined as travel time on roads.
First we specify the speed on different types of roads.
We copy the roads raster into our mapset so that we can change it
by adding a new attribute field <tt>speed</tt>. Then we assign speed values (km/h) based on the type of road:

<source lang="bash">
g.copy vector=roads,myroads
v.db.addcolumn map=myroads columns="speed double precision"
v.db.update map=myroads column=speed value=50 where="MTFCC = 'S1400'"
v.db.update map=myroads column=speed value=100 where="MTFCC IN ('S1100', 'S1200')"
</source>

Now we rasterize the selected road types using the speed values from the attribute table as raster values.

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
v.to.rast input=myroads type=line where="MTFCC IN ('S1100', 'S1200', 'S1400')" output=roads_speed use=attr attribute_column=speed
</source>

We set the rest of the area to low speed and recompute the speed as time to travel through a 30m cell in minutes:

<source lang="bash">
r.null map=roads_speed null=5
r.mapcalc "roads_travel_time = 1.8 / roads_speed"
</source>

Finally we compute the travel time to larger cities using {{cmd|r.cost}}:

<source lang="bash">
r.cost input=roads_travel_time output=travel_time_cities start_points=cities
r.colors map=travel_time_cities color=byr
</source>

==== Road density ====
We will rasterize roads and use moving window analysis ({{cmd|r.neighbors}}) to compute road density:

<source lang="bash">
v.to.rast input=roads output=roads use=val type=line
r.null map=roads null=0
r.neighbors -c input=roads output=road_dens size=25 method=average
</source>

==== Distance to interchanges ====

We will consider TIGER roads of type <tt>Ramp</tt> as interchanges, rasterize them and compute euclidean distance to them:

<source lang="bash">
v.to.rast input=roads type=line where="MTFCC = 'S1630'" output=interchanges use=val
r.grow.distance -m input=interchanges distance=dist_interchanges
</source>

=== Development pressure ===

We compute development pressure with {{AddonCmd|r.futures.devpressure}}. Development pressure is a predictor based on number of neighboring developed cells within search distance, weighted by distance. The development pressure variable plays a special role in the model, allowing for a feedback between predicted change and change in subsequent steps.

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.devpressure -n input=urban_2011 output=devpressure_2 method=gravity size=7 gamma=2 scaling_factor=10
r.futures.devpressure -n input=urban_2011 output=devpressure_1 method=gravity size=10 gamma=1 scaling_factor=1
r.futures.devpressure -n input=urban_2011 output=devpressure_0_5 method=gravity size=30 gamma=0.5 scaling_factor=0.1
</source>

When gamma increases, development influence decreases more rapidly with distance.
Size is half the size of the moving window. When gamma is low, local development influences more distant places.
We will derive 3 layers with different gamma and size parameters for the potential statistical model.

=== Rescaling variables ===

First we will look at the ranges of our predictor variables by running a short Python code snippet in Python shell:

<source lang="python" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
for name in ['slope', 'dist_to_water', 'dist_to_protected', 'forest_smooth', 'travel_time_cities', 'road_dens', 'dist_interchanges', 'devpressure_0_5', 'devpressure_1']:
minmax = grass.raster_info(name)
print name, minmax['min'], minmax['max']
</source>

We will rescale some of our input variables:

<source lang="bash">
r.mapcalc "dist_to_water_km = dist_to_water / 1000"
r.mapcalc "dist_to_protected_km = dist_to_protected / 1000"
r.mapcalc "dist_interchanges_km = dist_interchanges / 1000"
r.mapcalc "road_dens_perc = road_dens * 100"
r.mapcalc "forest_smooth_perc = forest_smooth * 100"
</source>

=== Sampling ===
To sample only in the analyzed counties, we will clip development layer:

<source lang="bash">
r.mapcalc "urban_change_01_11 = if(urban_2011 == 1, if(urban_2001 == 0, 1, null()), 0)"
r.mapcalc "urban_change_clip = if(counties, urban_change_01_11)"
</source>

To estimate the number of sampling points, we can use {{cmd|r.report}} to report number of developed/undeveloped cells and their ratio.

<source lang="bash">
r.report map=urban_change_clip units=h,c,p
</source>

We will sample the predictors and the response variable with 5000 random points in undeveloped areas and 1000 points in developed area:

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.sample.category input=urban_change_clip output=sampling sampled=counties,devpressure_0_5,devpressure_1,devpressure_2,slope,road_dens_perc,forest_smooth_perc,dist_to_water_km,dist_to_protected_km,dist_interchanges_km,travel_time_cities npoints=5000,1000
</source>

The attribute table can be exported as CSV file (not necessary step):

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
v.db.select map=sampling columns=urban_change_clip,counties,devpressure_0_5,devpressure_1,slope,road_dens_perc,forest_smooth_perc,dist_to_water_km,dist_to_protected_km,dist_interchanges_km,travel_time_cities separator=comma file=samples.csv
</source>

=== Development potential ===
Now we find best model for predicting urbanization using {{AddonCmd|r.futures.potential}} which wraps an R script.

We can run R [http://www.inside-r.org/packages/cran/MuMIn/docs/dredge dredge] function to find "best" model. We can specify minimum and maximum number of predictors the final model should use.
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.potential -d input=sampling output=potential.csv columns=devpressure_1,slope,road_dens_perc,forest_smooth_perc,dist_to_water_km,dist_to_protected_km,dist_interchanges_km,travel_time_cities developed_column=urban_change_clip subregions_column=counties min_variables=4
</source>

Also, we can play with different combinations of predictors, for example:

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.potential input=sampling output=potential.csv columns=devpressure_2,road_dens_perc,slope,dist_interchanges_km,dist_to_water_km developed_column=urban_change_clip subregions_column=counties --o
r.futures.potential input=sampling output=potential.csv columns=devpressure_1,road_dens_perc,slope,dist_interchanges_km,dist_to_water_km developed_column=urban_change_clip subregions_column=counties --o
...
</source>

You can then open the output file <tt>potential.csv</tt>, which is a CSV file with tabs as separators.

For this tutorial, the final potential is created with:
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.potential input=sampling output=potential.csv columns=devpressure_2,road_dens_perc,slope,dist_interchanges_km,dist_to_water_km developed_column=urban_change_clip subregions_column=counties --o
</source>

We can now visualize the suitability surface using module {{AddonCmd|r.futures.potsurface}}. It creates initial development potential (suitability) raster from predictors and model coefficients and serves only for evaluating development potential model. The values of the resulting raster range from 0 to 1.

<source lang="bash">
r.futures.potsurface input=potential.csv subregions=counties output=suitability
r.colors map=suitability color=byr
</source>

== Demand submodel ==
First we will mask out roads so that they don't influence into per capita land demand relation.
<source lang="bash">
v.to.rast input=roads type=line output=roads_mask use=val
r.mask roads_mask -i
</source>

We will use {{AddonCmd|r.futures.demand}} which derives the population vs. development relation. The relation can be linear/logarithmic/logarithmic2/exponential/exponential approach.
Look for examples of the different relations in the manual.

* linear: y = A + Bx
* logarithmic: y = A + Bln(x)
* logarithmic2: y = A + B * ln(x - C)        (requires SciPy)
* exponential: y = Ae^(BX)
* exp_approach: y = (1 - e^(-A(x - B))) + C        (requires SciPy)

The format of the input population CSV files is described in the manual. It is important to have synchronized categories of subregions and the column headers of the CSV files (in our case FIPS number). How to simply generate the list of years (for which demand is computed) is described in {{AddonCmd|r.futures.demand}} manual, for example run this in Python console:

<source lang="python">
','.join([str(i) for i in range(2011, 2036)])
</source>

Then we can create the DEMAND file:
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.demand development=urban_1992,urban_2001,urban_2011 subregions=counties observed_population=population_trend.csv projected_population=population_projection.csv simulation_times=2011,2012,2013,2014,2015,2016,2017,2018,2019,2020,2021,2022,2023,2024,2025,2026,2027,2028,2029,2030,2031,2032,2033,2034,2035 plot=plot_demand.pdf demand=demand.csv separator=comma
</source>

In your current working directory, you should find files <tt>plot_demand.png</tt> and <tt>demand.csv</tt>.

If you have SciPy installed, you can experiment with other methods for fitting the functions:
<source lang="bash">
r.futures.demand ... method=logarithmic2
r.futures.demand ... method=exp_approach
</source>
If necessary, you can create a set of demand files produced by fitting each method separately and
then pick for each county the method which seems best and manually create a new demand file.

When you are finished, remove the mask as it is not needed for the next steps.
<source lang="bash">
r.mask -r
</source>

== Patch calibration ==
Patch calibration can be a very time consuming computation.
Therefore we select only one county (Buncombe):

<source lang="bash">
v.to.rast input=counties type=area where="FIPS == 37021" use=attr attribute_column=FIPS output=calib_county
g.region raster=calib_county zoom=calib_county
</source>
to derive patches of new development by comparing historical and latest development.
We can keep only patches with minimum size 2 cells (1800 = 2 x 30 x 30 m).

<source lang="bash">
r.futures.calib development_start=urban_1992 development_end=urban_2011 subregions=counties patch_sizes=patches.txt patch_threshold=1800 -l
</source>
We obtained a file <tt>patches.txt</tt> (used later in the PGA) - a patch size distribution file - containing sizes of all found patches.

We can look at the distribution of the patch sizes:

<source lang="python">
from matplotlib import pyplot as plt
with open('patches.txt') as f:
patches = [int(patch) for patch in f.readlines()]
plt.hist(patches, 2000)
plt.xlim(0,50)
plt.show()
</source>

At this point, we start the calibration to get best parameters of patch shape
(for this tutorial, this step can be skipped and the suggested parameters are used).

<source lang="bash"
style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.calib development_start=urban_1992 development_end=urban_2011 subregions=calib_county patch_sizes=patches.txt calibration_results=calib.csv patch_threshold=1800 repeat=5 compactness_mean=0.1,0.3,0.5,0.7,0.9 compactness_range=0.05 discount_factor=0.1,0.3,0.5,0.7,0.9 predictors=road_dens_perc,forest_smooth_perc,dist_to_protected_km demand=demand.csv devpot_params=potential.csv num_neighbors=4 seed_search=2 development_pressure=devpressure_0_5 development_pressure_approach=gravity n_dev_neighbourhood=30 gamma=0.5 scaling_factor=0.1
</source>

== FUTURES simulation ==
We will switch back to our previous region:
<source lang="bash">
g.region raster=landuse_2011 -p
</source>

Now we have all the inputs necessary for running {{AddonCmd|r.futures.pga}}:

The entire command is here:
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.pga subregions=counties developed=urban_2011 predictors=slope,forest_smooth_perc,dist_interchanges_km,travel_time_cities devpot_params=potential.csv development_pressure=devpressure_1 n_dev_neighbourhood=10 development_pressure_approach=gravity gamma=1 scaling_factor=1 demand=demand.csv discount_factor=0.3 compactness_mean=0.2 compactness_range=0.1 patch_sizes=patches.txt num_neighbors=4 seed_search=2 random_seed=1 output=final output_series=final
</source>

=== Quick description ===
The command parameters and their values:
* raster map of counties with their categories
<code>
... subregions=counties ...
</code>

* raster of developed (1), undeveloped (0) and NULLs for undevelopable areas
<code>
... developed=urban_2011 ...
</code>

* predictors selected with {{AddonCmd|r.futures.potential}} and their coefficients in a <tt>potential.csv</tt> file. The order of predictors must match the order in the file and the categories of the counties must match raster <tt>counties</tt>.
<code>
... predictors=slope,forest_smooth_perc,dist_interchanges_km,travel_time_cities devpot_params=potential.csv ...
</code>

* initial development pressure computed by {{AddonCmd|r.futures.devpressure}}, it's important to set here the same parameters
<code>
... development_pressure=devpressure_1 n_dev_neighbourhood=10 development_pressure_approach=gravity gamma=1 scaling_factor=1 ...
</code>

* per capita land demand computed by {{AddonCmd|r.futures.demand}}, the categories of the counties must match raster <tt>counties</tt>.
<code>
... demand=demand.csv ...
</code>

* patch parameters from the calibration step
<code>
... discount_factor=0.3 compactness_mean=0.4 compactness_range=0.08 patch_sizes=patches.txt ...
</code>

* recommended parameters for patch growing algorithm
<code>
... num_neighbors=4 seed_search=2 ...
</code>

* set random seed for repeatable results or set flag <tt>-s</tt> to generate seed automatically
<code>
... random_seed=1 ...
</code>

* specify final output map and optionally basename for intermediate raster maps
<code>
output=final output_series=final
</code>

== Scenarios ==
Scenarios involving policies that encourage infill versus sprawl can be explored using the <tt>incentive_power</tt> parameter of {{AddonCmd|r.futures.pga}},
which uses a power function to transform the evenness of the probability gradient in POTENTIAL. You can change the power to a number between 0.25 and 4 to test urban sprawl/infill scenarios.
Higher power leads to infill behavior, lower power to urban sprawl.

== Postprocessing ==

Follow a [[Creating_animation_from_FUTURES_output_in_GRASS_GIS| tutorial how to make an animation from the results]].

= GRASS GIS Python API =

[[Category: Tutorial]]
[[Category: FUTURES]]
[[Category: Urban]]

Workshop on urban growth modeling with FUTURES

2016-03-22T18:29:59Z

⚠️Dbvanber: /* GRASS GIS introduction */

{{ToModify}}
= Workshop introduction =
r.futures.* is an implementation of the '''FUT'''ure '''U'''rban-'''R'''egional '''E'''nvironment '''S'''imulation (FUTURES)[1] which is a model for multilevel simulations of emerging urban-rural landscape structure. FUTURES produces regional projections of landscape patterns using coupled submodels that integrate nonstationary drivers of land change: per capita demand (DEMAND submodel), site suitability (POTENTIAL submodel), and the spatial structure of conversion events (PGA submodel).

[1] Meentemeyer, R. K., Tang, W., Dorning, M. A., Vogler, J. B., Cunniffe, N. J., & Shoemaker, D. A. (2013). [http://www.tandfonline.com/doi/abs/10.1080/00045608.2012.707591 FUTURES: multilevel simulations of emerging urban-rural landscape structure using a stochastic patch-growing algorithm.] Annals of the Association of American Geographers, 103(4), 785-807

== Software ==
There are a number of software requirements to run FUTURES that will need to be download and installed. Required software includes:
* GRASS GIS 7
* addons
** {{AddonCmd|r.futures.pga}}
** {{AddonCmd|r.futures.potential}}
** {{AddonCmd|r.futures.potsurface}}
** {{AddonCmd|r.futures.demand}}
** {{AddonCmd|r.futures.devpressure}}
** {{AddonCmd|r.sample.category}}
* R (≥ 3.0.2) - needed for {{AddonCmd|r.futures.potential}} with packages:
**MuMIn, lme4, optparse, rgrass7
* SciPy - useful for {{AddonCmd|r.futures.demand}}

=== Installation ===
We use the R statistical software for our calculation of site suitability (i.e. development potential) in FUTURES. R is a free software environment for statistical computing and graphics. If you don't have R, or you have older an version, please download and install the software from [http://archive.linux.duke.edu/cran/ install R] and be sure to additionally add these required packages:
<pre>
install.packages(c("MuMIn", "lme4", "optparse", "rgrass7"))
</pre>

==== MS Windows ====
We will be using GRASS GIS 7.0.3 that can be found here in the [https://trac.osgeo.org/osgeo4w/ OSGeo4W] package manager.
Please install the latest stable GRASS GIS 7 version and the SciPy Python package using the ''Advanced install'' option.
A guide with step by step screen shot instructions is available [https://docs.google.com/presentation/d/1yEGpriBne7RvjB35HI6GecNwO1P1y2nRGqDThqoNnCE/edit?usp=sharing here].

In order for GRASS to be able to find R executables, GRASS must be on the PATH variable. Follow this [solution] to make R accessible from GRASS permanently.
A simple but temporary solution is to open GRASS GIS and paste this in the black terminal:
<pre>
set PATH=%PATH%;C:\Program Files\R\R-3.0.2\bin
</pre>
This has to be repeated after restarting GRASS session.

==== Ubuntu Linux ====
Install GRASS GIS from packages:
<pre>
sudo add-apt-repository ppa:ubuntugis/ubuntugis-unstable
sudo apt-get update
sudo apt-get install grass
</pre>

== Workshop data ==
The data that we will be using for the workshop can be download here: [http://fatra.cnr.ncsu.edu/futures/futures_ncspm_Asheville.zip sample dataset]. Please place these layers in your local GRASS directory:
* digital elevation model ([http://nationalmap.gov/elevation.html NED])
* [http://www.mrlc.gov/ NLCD] 2001, 2011
* NLCD 1992/2001 Retrofit Land Cover Change Product
* transportation network ([http://www.census.gov/geo/maps-data/data/tiger-line.html TIGER])
* county boundaries ([http://www.census.gov/geo/maps-data/data/tiger-line.html TIGER])
* protected areas ([http://www.conservationgateway.org/ConservationByGeography/NorthAmerica/UnitedStates/edc/reportsdata/terrestrial/secured/Pages/default.aspx Secured Lands])
* cities as points (USGS)

In addition, download [http://fatra.cnr.ncsu.edu/futures/futures_Asheville_files.zip population information as text files]:
* county population past estimates and future projections ([https://www.osbm.nc.gov/demog/county-projections NC OSBM]) per county (nonspatial)

= GRASS GIS introduction =
There are many advantages to using the open source GRASS GIS platform, but for many that are more familiar with ARCGis and QGis, the setup and implementation of spatial tools in GRASS can be confusing. Here we provide an overview of the GRASS GIS project: [https://grass.osgeo.org grass.osgeo.org] that might be helpful to review if you are a first time users. For this exercise it's not necessary to have a full understanding of how to use GRASS. However, you will need to know how to place your data in the correct GRASS database directory, as well as some basic GRASS functionality. Step by step instructions are provided below
== GRASS directory ==
GRASS uses unique database terminology and structure that are important to understand [https://grass.osgeo.org/grass71/manuals/grass_database.html GRASS database] for the set up of this tutorial as you will need to place the required data (e.g. Mapset) in a specific GRASS database Location.
** A''GRASS database'' consist of directory with specific Locations (projects) where data layer are stored
** ''Location'' hold all Mapsets in a specific directoy that have the same spatial projection (spatial reference system)
** ''Mapset'' are a collection of maps with the same spatial projection

To Download the [http://fatra.cnr.ncsu.edu/futures/futures_ncspm_Asheville.zip workshop location]. Create (unless you already have it) a directory named <tt>grassdata</tt> (GRASS database) in your home folder (or Documents), unzip the downloaded data into this directory. You should have now Location <tt>futures_ncspm</tt> in <tt>grassdata</tt>.
* Launch GRASS and display raster, vector data, explore navigation, querying, adding legend, showing metadata
<center><gallery perrow=3 widths=500 heights=250>Image:GRASS FUTURES startup.png|GRASS GIS 7.0.3 startup dialog with downloaded Location and Mapsets for FUTURES workshop
Image:GRASS FUTURES wxGUI display.png|Layer Manager and Map Display overview. Annotations show how to add raster layer, query, add legend.
Image:wxGUI_metadata_rinfo.png|Show raster map metadata by right click on layer</gallery></center>

* GRASS GIS has over [https://grass.osgeo.org/grass70/manuals/full_index.html 500 different modules] in the core distribution and over [https://grass.osgeo.org/grass70/manuals/addons/ 230 addon modules]
<center>
{| class="wikitable"
|-
! Prefix !! Function !! Example
|-
| r.* || raster processing || ''{{cmd|r.mapcalc}}'': map algebra
|-
| v.* || vector processing || ''{{cmd|v.clean}}'': topological cleaning
|-
| i.* || imagery processing || ''{{cmd|i.segment}}'': object recognition
|-
| db.* || database management || ''{{cmd|db.select}}'': select values from table
|-
| r3.* || 3D raster processing || ''{{cmd|r3.stats}}'': 3D raster statistics
|-
| t.* || temporal data processing || ''{{cmd|t.rast.aggregate}}'': temporal aggregation
|-
| g.* || general data management || ''{{cmd|g.rename}}'': renames map
|-
| d.* || display ||''{{cmd|d.rast}}'': display raster map
|}</center>
* GRASS modules have GUI and command line interface. In this workshop we use commands to describe the workflow, but we can use both GUI and command line depending on personal preference. Look how {{cmd|wxGUI.modules|version=71|desc=GUI and command line interface}} represent the same tool. ''Task:'' compute aspect (orientation) from provided digital elevation model using module {{cmd|r.slope.aspect}} using both module dialog and command line.
* How to find modules? Modules are organized by their functionality in wxGUI menu, or we can search for them in Search modules tab. If we already know which module to use, we can just type it in the wxGUI command console. <center><gallery perrow=3 widths=380 heights=190>Image:wxGUI_menu_rinfo.png|Modules can be found in wxGUI menu
Image:wxGUI_module_search.png|You can search modules by name, description or keywords in ''Search modules'' tab
Image:wxGUI_console_completion.png|By typing prefix r. we make a list of modules starting with that prefix to show up.</gallery></center>


* {{cmd|g.region|desc=Computational region}} - an important raster concept
** defined by region extent and raster resolution
** applies to all raster operations
** persists between GRASS session, can be different for different mapsets
** advantages: keeps your results consistent, avoid clipping, for computationally demanding tasks set region to smaller extent, check your result is good and then set the computational region to the entire study area and rerun analysis
** run <code>g.region -p</code> or in menu ''Settings'' - ''Region'' - ''Display region'' to see current region settings
[[File:WxGUI set region.png|700px|thumb|center|Simple ways to set computational region from GUI. On the left, set region to match raster map. On the right, select the highlighted option and then set region by drawing rectangle.]]

* GRASS 3D view

= Modeling with FUTURES =
== Initial steps and data preparation ==
First we will set the computational region of our analyses to an extent covering our study area and aligned with our base landuse rasters:
<source lang="bash">g.region raster=landuse_2011 -p</source>

We will derive urbanized areas from NLCD dataset for year 1992, 2001 and 2011
by extracting categories category 21 - 24 into a new binary map where developed is 1,
undeveloped 0 and NULL (no data) is area unsuitable for development (water, wetlands, protected areas).
First we will convert protected areas from vector to raster. We set
NULLs to zeros (for simpler raster algebra expression in the next step) using {{cmd|r.null}}:

<source lang="bash">
v.to.rast input=protected_areas output=protected_areas use=val
r.null map=protected_areas null=0
</source>

And then create rasters of developed/undeveloped areas using raster algebra:

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.mapcalc "urban_1992 = if(landuse_1992 >= 21 && landuse_1992 <= 24, 1, if(landuse_1992 == 11 || landuse_1992 >= 90 || protected_areas, null(), 0))"
r.mapcalc "urban_2001 = if(landuse_2001 >= 21 && landuse_2001 <= 24, 1, if(landuse_2001 == 11 || landuse_2001 >= 90 || protected_areas, null(), 0))"
r.mapcalc "urban_2011 = if(landuse_2011 >= 21 && landuse_2011 <= 24, 1, if(landuse_2011 == 11 || landuse_2011 >= 90 || protected_areas, null(), 0))"
</source>

We will convert vector counties to raster with the values of the FIPS attribute which links to population file:

<source lang="bash">
v.to.rast input=counties type=area use=attr attribute_column=FIPS output=counties
</source>

Before further steps, we will set our working directory so that the input population files and text files
we are going to create are saved in one directory and easily accessible.
You can do that from menu ''Settings'' → ''GRASS working environment'' → ''Change working directory''.
Select (or create) a directory and move there the downloaded files <tt>population_projection.csv</tt> and <tt>population_trend.csv</tt>.

== Potential submodel ==
Module {{AddonCmd|r.futures.potential}} implements POTENTIAL submodel as a part of FUTURES land change model. POTENTIAL is implemented using a set of coefficients that relate a selection of site suitability factors to the probability of a place becoming developed. This is implemented using the parameter table in combination with maps of those site suitability factors (mapped predictors). The coefficients are obtained by conducting multilevel logistic regression in R with package lme4 where the coefficients may vary by county. The best model is selected automatically using dredge function from package [https://cran.r-project.org/web/packages/MuMIn/index.html MuMIn].

First, we will derive couple of predictors.
=== Predictors ===
==== Slope ====
We will derive slope in degrees from digital elevation model using {{cmd|r.slope.aspect}} module:
<source lang="bash">r.slope.aspect elevation=elevation_30m slope=slope</source>

==== Distance from lakes/rivers ====
First we will extract [http://www.mrlc.gov/nlcd11_leg.php category ''Open Water''] from 2011 NLCD dataset:
<source lang="bash">
r.mapcalc "water = if(landuse_2011 == 11, 1, null())"
</source>

Then we compute the distance to water with module {{cmd|r.grow.distance}} and set color table to shades of blue:
<source lang="bash">
r.grow.distance input=water distance=dist_to_water
r.colors -n map=dist_to_water color=blues
</source>

==== Distance from protected areas ====
We will use raster protected of protected areas we already created, but we will set NULL values to zero.
We compute the distance to protected areas with module {{cmd|r.grow.distance}} and set color table from green to red:
<source lang="bash">
r.null map=protected_areas setnull=0
r.grow.distance input=protected_areas distance=dist_to_protected
r.colors map=dist_to_protected color=gyr
</source>

==== Forests ====
We will smooth the transition between forest and other land use, see NLCD [http://www.mrlc.gov/nlcd11_leg.php category ''Open Water'']:
<source lang="bash">
r.mapcalc "forest = if(landuse_2011 >= 41 && landuse_2011 <= 43, 1, 0)"
r.neighbors -c input=forest output=forest_smooth size=15 method=average
r.colors map=forest_smooth color=ndvi
</source>

==== Travel time to cities ====
Here we will compute travel time to cities (with population > 5000)
as cumulative cost distance where cost is defined as travel time on roads.
First we specify the speed on different types of roads.
We copy the roads raster into our mapset so that we can change it
by adding a new attribute field <tt>speed</tt>. Then we assign speed values (km/h) based on the type of road:

<source lang="bash">
g.copy vector=roads,myroads
v.db.addcolumn map=myroads columns="speed double precision"
v.db.update map=myroads column=speed value=50 where="MTFCC = 'S1400'"
v.db.update map=myroads column=speed value=100 where="MTFCC IN ('S1100', 'S1200')"
</source>

Now we rasterize the selected road types using the speed values from the attribute table as raster values.

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
v.to.rast input=myroads type=line where="MTFCC IN ('S1100', 'S1200', 'S1400')" output=roads_speed use=attr attribute_column=speed
</source>

We set the rest of the area to low speed and recompute the speed as time to travel through a 30m cell in minutes:

<source lang="bash">
r.null map=roads_speed null=5
r.mapcalc "roads_travel_time = 1.8 / roads_speed"
</source>

Finally we compute the travel time to larger cities using {{cmd|r.cost}}:

<source lang="bash">
r.cost input=roads_travel_time output=travel_time_cities start_points=cities
r.colors map=travel_time_cities color=byr
</source>

==== Road density ====
We will rasterize roads and use moving window analysis ({{cmd|r.neighbors}}) to compute road density:

<source lang="bash">
v.to.rast input=roads output=roads use=val type=line
r.null map=roads null=0
r.neighbors -c input=roads output=road_dens size=25 method=average
</source>

==== Distance to interchanges ====

We will consider TIGER roads of type <tt>Ramp</tt> as interchanges, rasterize them and compute euclidean distance to them:

<source lang="bash">
v.to.rast input=roads type=line where="MTFCC = 'S1630'" output=interchanges use=val
r.grow.distance -m input=interchanges distance=dist_interchanges
</source>

=== Development pressure ===

We compute development pressure with {{AddonCmd|r.futures.devpressure}}. Development pressure is a predictor based on number of neighboring developed cells within search distance, weighted by distance. The development pressure variable plays a special role in the model, allowing for a feedback between predicted change and change in subsequent steps.

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.devpressure -n input=urban_2011 output=devpressure_2 method=gravity size=7 gamma=2 scaling_factor=10
r.futures.devpressure -n input=urban_2011 output=devpressure_1 method=gravity size=10 gamma=1 scaling_factor=1
r.futures.devpressure -n input=urban_2011 output=devpressure_0_5 method=gravity size=30 gamma=0.5 scaling_factor=0.1
</source>

When gamma increases, development influence decreases more rapidly with distance.
Size is half the size of the moving window. When gamma is low, local development influences more distant places.
We will derive 3 layers with different gamma and size parameters for the potential statistical model.

=== Rescaling variables ===

First we will look at the ranges of our predictor variables by running a short Python code snippet in Python shell:

<source lang="python" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
for name in ['slope', 'dist_to_water', 'dist_to_protected', 'forest_smooth', 'travel_time_cities', 'road_dens', 'dist_interchanges', 'devpressure_0_5', 'devpressure_1']:
minmax = grass.raster_info(name)
print name, minmax['min'], minmax['max']
</source>

We will rescale some of our input variables:

<source lang="bash">
r.mapcalc "dist_to_water_km = dist_to_water / 1000"
r.mapcalc "dist_to_protected_km = dist_to_protected / 1000"
r.mapcalc "dist_interchanges_km = dist_interchanges / 1000"
r.mapcalc "road_dens_perc = road_dens * 100"
r.mapcalc "forest_smooth_perc = forest_smooth * 100"
</source>

=== Sampling ===
To sample only in the analyzed counties, we will clip development layer:

<source lang="bash">
r.mapcalc "urban_change_01_11 = if(urban_2011 == 1, if(urban_2001 == 0, 1, null()), 0)"
r.mapcalc "urban_change_clip = if(counties, urban_change_01_11)"
</source>

To estimate the number of sampling points, we can use {{cmd|r.report}} to report number of developed/undeveloped cells and their ratio.

<source lang="bash">
r.report map=urban_change_clip units=h,c,p
</source>

We will sample the predictors and the response variable with 5000 random points in undeveloped areas and 1000 points in developed area:

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.sample.category input=urban_change_clip output=sampling sampled=counties,devpressure_0_5,devpressure_1,devpressure_2,slope,road_dens_perc,forest_smooth_perc,dist_to_water_km,dist_to_protected_km,dist_interchanges_km,travel_time_cities npoints=5000,1000
</source>

The attribute table can be exported as CSV file (not necessary step):

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
v.db.select map=sampling columns=urban_change_clip,counties,devpressure_0_5,devpressure_1,slope,road_dens_perc,forest_smooth_perc,dist_to_water_km,dist_to_protected_km,dist_interchanges_km,travel_time_cities separator=comma file=samples.csv
</source>

=== Development potential ===
Now we find best model for predicting urbanization using {{AddonCmd|r.futures.potential}} which wraps an R script.

We can run R [http://www.inside-r.org/packages/cran/MuMIn/docs/dredge dredge] function to find "best" model. We can specify minimum and maximum number of predictors the final model should use.
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.potential -d input=sampling output=potential.csv columns=devpressure_1,slope,road_dens_perc,forest_smooth_perc,dist_to_water_km,dist_to_protected_km,dist_interchanges_km,travel_time_cities developed_column=urban_change_clip subregions_column=counties min_variables=4
</source>

Also, we can play with different combinations of predictors, for example:

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.potential input=sampling output=potential.csv columns=devpressure_2,road_dens_perc,slope,dist_interchanges_km,dist_to_water_km developed_column=urban_change_clip subregions_column=counties --o
r.futures.potential input=sampling output=potential.csv columns=devpressure_1,road_dens_perc,slope,dist_interchanges_km,dist_to_water_km developed_column=urban_change_clip subregions_column=counties --o
...
</source>

You can then open the output file <tt>potential.csv</tt>, which is a CSV file with tabs as separators.

For this tutorial, the final potential is created with:
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.potential input=sampling output=potential.csv columns=devpressure_2,road_dens_perc,slope,dist_interchanges_km,dist_to_water_km developed_column=urban_change_clip subregions_column=counties --o
</source>

We can now visualize the suitability surface using module {{AddonCmd|r.futures.potsurface}}. It creates initial development potential (suitability) raster from predictors and model coefficients and serves only for evaluating development potential model. The values of the resulting raster range from 0 to 1.

<source lang="bash">
r.futures.potsurface input=potential.csv subregions=counties output=suitability
r.colors map=suitability color=byr
</source>

== Demand submodel ==
First we will mask out roads so that they don't influence into per capita land demand relation.
<source lang="bash">
v.to.rast input=roads type=line output=roads_mask use=val
r.mask roads_mask -i
</source>

We will use {{AddonCmd|r.futures.demand}} which derives the population vs. development relation. The relation can be linear/logarithmic/logarithmic2/exponential/exponential approach.
Look for examples of the different relations in the manual.

* linear: y = A + Bx
* logarithmic: y = A + Bln(x)
* logarithmic2: y = A + B * ln(x - C)        (requires SciPy)
* exponential: y = Ae^(BX)
* exp_approach: y = (1 - e^(-A(x - B))) + C        (requires SciPy)

The format of the input population CSV files is described in the manual. It is important to have synchronized categories of subregions and the column headers of the CSV files (in our case FIPS number). How to simply generate the list of years (for which demand is computed) is described in {{AddonCmd|r.futures.demand}} manual, for example run this in Python console:

<source lang="python">
','.join([str(i) for i in range(2011, 2036)])
</source>

Then we can create the DEMAND file:
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.demand development=urban_1992,urban_2001,urban_2011 subregions=counties observed_population=population_trend.csv projected_population=population_projection.csv simulation_times=2011,2012,2013,2014,2015,2016,2017,2018,2019,2020,2021,2022,2023,2024,2025,2026,2027,2028,2029,2030,2031,2032,2033,2034,2035 plot=plot_demand.pdf demand=demand.csv separator=comma
</source>

In your current working directory, you should find files <tt>plot_demand.png</tt> and <tt>demand.csv</tt>.

If you have SciPy installed, you can experiment with other methods for fitting the functions:
<source lang="bash">
r.futures.demand ... method=logarithmic2
r.futures.demand ... method=exp_approach
</source>
If necessary, you can create a set of demand files produced by fitting each method separately and
then pick for each county the method which seems best and manually create a new demand file.

When you are finished, remove the mask as it is not needed for the next steps.
<source lang="bash">
r.mask -r
</source>

== Patch calibration ==
Patch calibration can be a very time consuming computation.
Therefore we select only one county (Buncombe):

<source lang="bash">
v.to.rast input=counties type=area where="FIPS == 37021" use=attr attribute_column=FIPS output=calib_county
g.region raster=calib_county zoom=calib_county
</source>
to derive patches of new development by comparing historical and latest development.
We can keep only patches with minimum size 2 cells (1800 = 2 x 30 x 30 m).

<source lang="bash">
r.futures.calib development_start=urban_1992 development_end=urban_2011 subregions=counties patch_sizes=patches.txt patch_threshold=1800 -l
</source>
We obtained a file <tt>patches.txt</tt> (used later in the PGA) - a patch size distribution file - containing sizes of all found patches.

We can look at the distribution of the patch sizes:

<source lang="python">
from matplotlib import pyplot as plt
with open('patches.txt') as f:
patches = [int(patch) for patch in f.readlines()]
plt.hist(patches, 2000)
plt.xlim(0,50)
plt.show()
</source>

At this point, we start the calibration to get best parameters of patch shape
(for this tutorial, this step can be skipped and the suggested parameters are used).

<source lang="bash"
style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.calib development_start=urban_1992 development_end=urban_2011 subregions=calib_county patch_sizes=patches.txt calibration_results=calib.csv patch_threshold=1800 repeat=5 compactness_mean=0.1,0.3,0.5,0.7,0.9 compactness_range=0.05 discount_factor=0.1,0.3,0.5,0.7,0.9 predictors=road_dens_perc,forest_smooth_perc,dist_to_protected_km demand=demand.csv devpot_params=potential.csv num_neighbors=4 seed_search=2 development_pressure=devpressure_0_5 development_pressure_approach=gravity n_dev_neighbourhood=30 gamma=0.5 scaling_factor=0.1
</source>

== FUTURES simulation ==
We will switch back to our previous region:
<source lang="bash">
g.region raster=landuse_2011 -p
</source>

Now we have all the inputs necessary for running {{AddonCmd|r.futures.pga}}:

The entire command is here:
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.pga subregions=counties developed=urban_2011 predictors=slope,forest_smooth_perc,dist_interchanges_km,travel_time_cities devpot_params=potential.csv development_pressure=devpressure_1 n_dev_neighbourhood=10 development_pressure_approach=gravity gamma=1 scaling_factor=1 demand=demand.csv discount_factor=0.3 compactness_mean=0.2 compactness_range=0.1 patch_sizes=patches.txt num_neighbors=4 seed_search=2 random_seed=1 output=final output_series=final
</source>

=== Quick description ===
The command parameters and their values:
* raster map of counties with their categories
<code>
... subregions=counties ...
</code>

* raster of developed (1), undeveloped (0) and NULLs for undevelopable areas
<code>
... developed=urban_2011 ...
</code>

* predictors selected with {{AddonCmd|r.futures.potential}} and their coefficients in a <tt>potential.csv</tt> file. The order of predictors must match the order in the file and the categories of the counties must match raster <tt>counties</tt>.
<code>
... predictors=slope,forest_smooth_perc,dist_interchanges_km,travel_time_cities devpot_params=potential.csv ...
</code>

* initial development pressure computed by {{AddonCmd|r.futures.devpressure}}, it's important to set here the same parameters
<code>
... development_pressure=devpressure_1 n_dev_neighbourhood=10 development_pressure_approach=gravity gamma=1 scaling_factor=1 ...
</code>

* per capita land demand computed by {{AddonCmd|r.futures.demand}}, the categories of the counties must match raster <tt>counties</tt>.
<code>
... demand=demand.csv ...
</code>

* patch parameters from the calibration step
<code>
... discount_factor=0.3 compactness_mean=0.4 compactness_range=0.08 patch_sizes=patches.txt ...
</code>

* recommended parameters for patch growing algorithm
<code>
... num_neighbors=4 seed_search=2 ...
</code>

* set random seed for repeatable results or set flag <tt>-s</tt> to generate seed automatically
<code>
... random_seed=1 ...
</code>

* specify final output map and optionally basename for intermediate raster maps
<code>
output=final output_series=final
</code>

== Scenarios ==
Scenarios involving policies that encourage infill versus sprawl can be explored using the <tt>incentive_power</tt> parameter of {{AddonCmd|r.futures.pga}},
which uses a power function to transform the evenness of the probability gradient in POTENTIAL. You can change the power to a number between 0.25 and 4 to test urban sprawl/infill scenarios.
Higher power leads to infill behavior, lower power to urban sprawl.

== Postprocessing ==

Follow a [[Creating_animation_from_FUTURES_output_in_GRASS_GIS| tutorial how to make an animation from the results]].

= GRASS GIS Python API =

[[Category: Tutorial]]
[[Category: FUTURES]]
[[Category: Urban]]

Workshop on urban growth modeling with FUTURES

2016-03-22T18:28:17Z

⚠️Dbvanber: /* GRASS GIS introduction */

{{ToModify}}
= Workshop introduction =
r.futures.* is an implementation of the '''FUT'''ure '''U'''rban-'''R'''egional '''E'''nvironment '''S'''imulation (FUTURES)[1] which is a model for multilevel simulations of emerging urban-rural landscape structure. FUTURES produces regional projections of landscape patterns using coupled submodels that integrate nonstationary drivers of land change: per capita demand (DEMAND submodel), site suitability (POTENTIAL submodel), and the spatial structure of conversion events (PGA submodel).

[1] Meentemeyer, R. K., Tang, W., Dorning, M. A., Vogler, J. B., Cunniffe, N. J., & Shoemaker, D. A. (2013). [http://www.tandfonline.com/doi/abs/10.1080/00045608.2012.707591 FUTURES: multilevel simulations of emerging urban-rural landscape structure using a stochastic patch-growing algorithm.] Annals of the Association of American Geographers, 103(4), 785-807

== Software ==
There are a number of software requirements to run FUTURES that will need to be download and installed. Required software includes:
* GRASS GIS 7
* addons
** {{AddonCmd|r.futures.pga}}
** {{AddonCmd|r.futures.potential}}
** {{AddonCmd|r.futures.potsurface}}
** {{AddonCmd|r.futures.demand}}
** {{AddonCmd|r.futures.devpressure}}
** {{AddonCmd|r.sample.category}}
* R (≥ 3.0.2) - needed for {{AddonCmd|r.futures.potential}} with packages:
**MuMIn, lme4, optparse, rgrass7
* SciPy - useful for {{AddonCmd|r.futures.demand}}

=== Installation ===
We use the R statistical software for our calculation of site suitability (i.e. development potential) in FUTURES. R is a free software environment for statistical computing and graphics. If you don't have R, or you have older an version, please download and install the software from [http://archive.linux.duke.edu/cran/ install R] and be sure to additionally add these required packages:
<pre>
install.packages(c("MuMIn", "lme4", "optparse", "rgrass7"))
</pre>

==== MS Windows ====
We will be using GRASS GIS 7.0.3 that can be found here in the [https://trac.osgeo.org/osgeo4w/ OSGeo4W] package manager.
Please install the latest stable GRASS GIS 7 version and the SciPy Python package using the ''Advanced install'' option.
A guide with step by step screen shot instructions is available [https://docs.google.com/presentation/d/1yEGpriBne7RvjB35HI6GecNwO1P1y2nRGqDThqoNnCE/edit?usp=sharing here].

In order for GRASS to be able to find R executables, GRASS must be on the PATH variable. Follow this [solution] to make R accessible from GRASS permanently.
A simple but temporary solution is to open GRASS GIS and paste this in the black terminal:
<pre>
set PATH=%PATH%;C:\Program Files\R\R-3.0.2\bin
</pre>
This has to be repeated after restarting GRASS session.

==== Ubuntu Linux ====
Install GRASS GIS from packages:
<pre>
sudo add-apt-repository ppa:ubuntugis/ubuntugis-unstable
sudo apt-get update
sudo apt-get install grass
</pre>

== Workshop data ==
The data that we will be using for the workshop can be download here: [http://fatra.cnr.ncsu.edu/futures/futures_ncspm_Asheville.zip sample dataset]. Please place these layers in your local GRASS directory:
* digital elevation model ([http://nationalmap.gov/elevation.html NED])
* [http://www.mrlc.gov/ NLCD] 2001, 2011
* NLCD 1992/2001 Retrofit Land Cover Change Product
* transportation network ([http://www.census.gov/geo/maps-data/data/tiger-line.html TIGER])
* county boundaries ([http://www.census.gov/geo/maps-data/data/tiger-line.html TIGER])
* protected areas ([http://www.conservationgateway.org/ConservationByGeography/NorthAmerica/UnitedStates/edc/reportsdata/terrestrial/secured/Pages/default.aspx Secured Lands])
* cities as points (USGS)

In addition, download [http://fatra.cnr.ncsu.edu/futures/futures_Asheville_files.zip population information as text files]:
* county population past estimates and future projections ([https://www.osbm.nc.gov/demog/county-projections NC OSBM]) per county (nonspatial)

= GRASS GIS introduction =
There are many advantages to using the open source GRASS GIS platform, but for many that are more familiar with ARCGis and QGis, the setup and implementation of spatial tools in GRASS can be confusing. Here we provide an overview of the GRASS GIS project: [https://grass.osgeo.org grass.osgeo.org] that might be helpful to review if you are a first time users. For this exercise it's not necessary to have a full understanding of how to use GRASS. However, you will need to know how to place your data in the correct GRASS database directory, as well as some basic GRASS functionality. Step by step instructions are provided below
* GRASS uses unique database terminology and structure that are important to understand [https://grass.osgeo.org/grass71/manuals/grass_database.html GRASS database] for the set up of this tutorial as you will need to place the required data (e.g. Mapset) in a specific GRASS database Location.
** A''GRASS database'' consist of directory with specific Locations (projects) where data layer are stored
** ''Location'' hold all Mapsets in a specific directoy that have the same spatial projection (spatial reference system)
** ''Mapset'' are a collection of maps with the same spatial projection

To Download the [http://fatra.cnr.ncsu.edu/futures/futures_ncspm_Asheville.zip workshop location]. Create (unless you already have it) a directory named <tt>grassdata</tt> (GRASS database) in your home folder (or Documents), unzip the downloaded data into this directory. You should have now Location <tt>futures_ncspm</tt> in <tt>grassdata</tt>.
* Launch GRASS and display raster, vector data, explore navigation, querying, adding legend, showing metadata
<center><gallery perrow=3 widths=500 heights=250>Image:GRASS FUTURES startup.png|GRASS GIS 7.0.3 startup dialog with downloaded Location and Mapsets for FUTURES workshop
Image:GRASS FUTURES wxGUI display.png|Layer Manager and Map Display overview. Annotations show how to add raster layer, query, add legend.
Image:wxGUI_metadata_rinfo.png|Show raster map metadata by right click on layer</gallery></center>

* GRASS GIS has over [https://grass.osgeo.org/grass70/manuals/full_index.html 500 different modules] in the core distribution and over [https://grass.osgeo.org/grass70/manuals/addons/ 230 addon modules]
<center>
{| class="wikitable"
|-
! Prefix !! Function !! Example
|-
| r.* || raster processing || ''{{cmd|r.mapcalc}}'': map algebra
|-
| v.* || vector processing || ''{{cmd|v.clean}}'': topological cleaning
|-
| i.* || imagery processing || ''{{cmd|i.segment}}'': object recognition
|-
| db.* || database management || ''{{cmd|db.select}}'': select values from table
|-
| r3.* || 3D raster processing || ''{{cmd|r3.stats}}'': 3D raster statistics
|-
| t.* || temporal data processing || ''{{cmd|t.rast.aggregate}}'': temporal aggregation
|-
| g.* || general data management || ''{{cmd|g.rename}}'': renames map
|-
| d.* || display ||''{{cmd|d.rast}}'': display raster map
|}</center>
* GRASS modules have GUI and command line interface. In this workshop we use commands to describe the workflow, but we can use both GUI and command line depending on personal preference. Look how {{cmd|wxGUI.modules|version=71|desc=GUI and command line interface}} represent the same tool. ''Task:'' compute aspect (orientation) from provided digital elevation model using module {{cmd|r.slope.aspect}} using both module dialog and command line.
* How to find modules? Modules are organized by their functionality in wxGUI menu, or we can search for them in Search modules tab. If we already know which module to use, we can just type it in the wxGUI command console. <center><gallery perrow=3 widths=380 heights=190>Image:wxGUI_menu_rinfo.png|Modules can be found in wxGUI menu
Image:wxGUI_module_search.png|You can search modules by name, description or keywords in ''Search modules'' tab
Image:wxGUI_console_completion.png|By typing prefix r. we make a list of modules starting with that prefix to show up.</gallery></center>


* {{cmd|g.region|desc=Computational region}} - an important raster concept
** defined by region extent and raster resolution
** applies to all raster operations
** persists between GRASS session, can be different for different mapsets
** advantages: keeps your results consistent, avoid clipping, for computationally demanding tasks set region to smaller extent, check your result is good and then set the computational region to the entire study area and rerun analysis
** run <code>g.region -p</code> or in menu ''Settings'' - ''Region'' - ''Display region'' to see current region settings
[[File:WxGUI set region.png|700px|thumb|center|Simple ways to set computational region from GUI. On the left, set region to match raster map. On the right, select the highlighted option and then set region by drawing rectangle.]]

* GRASS 3D view

= Modeling with FUTURES =
== Initial steps and data preparation ==
First we will set the computational region of our analyses to an extent covering our study area and aligned with our base landuse rasters:
<source lang="bash">g.region raster=landuse_2011 -p</source>

We will derive urbanized areas from NLCD dataset for year 1992, 2001 and 2011
by extracting categories category 21 - 24 into a new binary map where developed is 1,
undeveloped 0 and NULL (no data) is area unsuitable for development (water, wetlands, protected areas).
First we will convert protected areas from vector to raster. We set
NULLs to zeros (for simpler raster algebra expression in the next step) using {{cmd|r.null}}:

<source lang="bash">
v.to.rast input=protected_areas output=protected_areas use=val
r.null map=protected_areas null=0
</source>

And then create rasters of developed/undeveloped areas using raster algebra:

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.mapcalc "urban_1992 = if(landuse_1992 >= 21 && landuse_1992 <= 24, 1, if(landuse_1992 == 11 || landuse_1992 >= 90 || protected_areas, null(), 0))"
r.mapcalc "urban_2001 = if(landuse_2001 >= 21 && landuse_2001 <= 24, 1, if(landuse_2001 == 11 || landuse_2001 >= 90 || protected_areas, null(), 0))"
r.mapcalc "urban_2011 = if(landuse_2011 >= 21 && landuse_2011 <= 24, 1, if(landuse_2011 == 11 || landuse_2011 >= 90 || protected_areas, null(), 0))"
</source>

We will convert vector counties to raster with the values of the FIPS attribute which links to population file:

<source lang="bash">
v.to.rast input=counties type=area use=attr attribute_column=FIPS output=counties
</source>

Before further steps, we will set our working directory so that the input population files and text files
we are going to create are saved in one directory and easily accessible.
You can do that from menu ''Settings'' → ''GRASS working environment'' → ''Change working directory''.
Select (or create) a directory and move there the downloaded files <tt>population_projection.csv</tt> and <tt>population_trend.csv</tt>.

== Potential submodel ==
Module {{AddonCmd|r.futures.potential}} implements POTENTIAL submodel as a part of FUTURES land change model. POTENTIAL is implemented using a set of coefficients that relate a selection of site suitability factors to the probability of a place becoming developed. This is implemented using the parameter table in combination with maps of those site suitability factors (mapped predictors). The coefficients are obtained by conducting multilevel logistic regression in R with package lme4 where the coefficients may vary by county. The best model is selected automatically using dredge function from package [https://cran.r-project.org/web/packages/MuMIn/index.html MuMIn].

First, we will derive couple of predictors.
=== Predictors ===
==== Slope ====
We will derive slope in degrees from digital elevation model using {{cmd|r.slope.aspect}} module:
<source lang="bash">r.slope.aspect elevation=elevation_30m slope=slope</source>

==== Distance from lakes/rivers ====
First we will extract [http://www.mrlc.gov/nlcd11_leg.php category ''Open Water''] from 2011 NLCD dataset:
<source lang="bash">
r.mapcalc "water = if(landuse_2011 == 11, 1, null())"
</source>

Then we compute the distance to water with module {{cmd|r.grow.distance}} and set color table to shades of blue:
<source lang="bash">
r.grow.distance input=water distance=dist_to_water
r.colors -n map=dist_to_water color=blues
</source>

==== Distance from protected areas ====
We will use raster protected of protected areas we already created, but we will set NULL values to zero.
We compute the distance to protected areas with module {{cmd|r.grow.distance}} and set color table from green to red:
<source lang="bash">
r.null map=protected_areas setnull=0
r.grow.distance input=protected_areas distance=dist_to_protected
r.colors map=dist_to_protected color=gyr
</source>

==== Forests ====
We will smooth the transition between forest and other land use, see NLCD [http://www.mrlc.gov/nlcd11_leg.php category ''Open Water'']:
<source lang="bash">
r.mapcalc "forest = if(landuse_2011 >= 41 && landuse_2011 <= 43, 1, 0)"
r.neighbors -c input=forest output=forest_smooth size=15 method=average
r.colors map=forest_smooth color=ndvi
</source>

==== Travel time to cities ====
Here we will compute travel time to cities (with population > 5000)
as cumulative cost distance where cost is defined as travel time on roads.
First we specify the speed on different types of roads.
We copy the roads raster into our mapset so that we can change it
by adding a new attribute field <tt>speed</tt>. Then we assign speed values (km/h) based on the type of road:

<source lang="bash">
g.copy vector=roads,myroads
v.db.addcolumn map=myroads columns="speed double precision"
v.db.update map=myroads column=speed value=50 where="MTFCC = 'S1400'"
v.db.update map=myroads column=speed value=100 where="MTFCC IN ('S1100', 'S1200')"
</source>

Now we rasterize the selected road types using the speed values from the attribute table as raster values.

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
v.to.rast input=myroads type=line where="MTFCC IN ('S1100', 'S1200', 'S1400')" output=roads_speed use=attr attribute_column=speed
</source>

We set the rest of the area to low speed and recompute the speed as time to travel through a 30m cell in minutes:

<source lang="bash">
r.null map=roads_speed null=5
r.mapcalc "roads_travel_time = 1.8 / roads_speed"
</source>

Finally we compute the travel time to larger cities using {{cmd|r.cost}}:

<source lang="bash">
r.cost input=roads_travel_time output=travel_time_cities start_points=cities
r.colors map=travel_time_cities color=byr
</source>

==== Road density ====
We will rasterize roads and use moving window analysis ({{cmd|r.neighbors}}) to compute road density:

<source lang="bash">
v.to.rast input=roads output=roads use=val type=line
r.null map=roads null=0
r.neighbors -c input=roads output=road_dens size=25 method=average
</source>

==== Distance to interchanges ====

We will consider TIGER roads of type <tt>Ramp</tt> as interchanges, rasterize them and compute euclidean distance to them:

<source lang="bash">
v.to.rast input=roads type=line where="MTFCC = 'S1630'" output=interchanges use=val
r.grow.distance -m input=interchanges distance=dist_interchanges
</source>

=== Development pressure ===

We compute development pressure with {{AddonCmd|r.futures.devpressure}}. Development pressure is a predictor based on number of neighboring developed cells within search distance, weighted by distance. The development pressure variable plays a special role in the model, allowing for a feedback between predicted change and change in subsequent steps.

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.devpressure -n input=urban_2011 output=devpressure_2 method=gravity size=7 gamma=2 scaling_factor=10
r.futures.devpressure -n input=urban_2011 output=devpressure_1 method=gravity size=10 gamma=1 scaling_factor=1
r.futures.devpressure -n input=urban_2011 output=devpressure_0_5 method=gravity size=30 gamma=0.5 scaling_factor=0.1
</source>

When gamma increases, development influence decreases more rapidly with distance.
Size is half the size of the moving window. When gamma is low, local development influences more distant places.
We will derive 3 layers with different gamma and size parameters for the potential statistical model.

=== Rescaling variables ===

First we will look at the ranges of our predictor variables by running a short Python code snippet in Python shell:

<source lang="python" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
for name in ['slope', 'dist_to_water', 'dist_to_protected', 'forest_smooth', 'travel_time_cities', 'road_dens', 'dist_interchanges', 'devpressure_0_5', 'devpressure_1']:
minmax = grass.raster_info(name)
print name, minmax['min'], minmax['max']
</source>

We will rescale some of our input variables:

<source lang="bash">
r.mapcalc "dist_to_water_km = dist_to_water / 1000"
r.mapcalc "dist_to_protected_km = dist_to_protected / 1000"
r.mapcalc "dist_interchanges_km = dist_interchanges / 1000"
r.mapcalc "road_dens_perc = road_dens * 100"
r.mapcalc "forest_smooth_perc = forest_smooth * 100"
</source>

=== Sampling ===
To sample only in the analyzed counties, we will clip development layer:

<source lang="bash">
r.mapcalc "urban_change_01_11 = if(urban_2011 == 1, if(urban_2001 == 0, 1, null()), 0)"
r.mapcalc "urban_change_clip = if(counties, urban_change_01_11)"
</source>

To estimate the number of sampling points, we can use {{cmd|r.report}} to report number of developed/undeveloped cells and their ratio.

<source lang="bash">
r.report map=urban_change_clip units=h,c,p
</source>

We will sample the predictors and the response variable with 5000 random points in undeveloped areas and 1000 points in developed area:

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.sample.category input=urban_change_clip output=sampling sampled=counties,devpressure_0_5,devpressure_1,devpressure_2,slope,road_dens_perc,forest_smooth_perc,dist_to_water_km,dist_to_protected_km,dist_interchanges_km,travel_time_cities npoints=5000,1000
</source>

The attribute table can be exported as CSV file (not necessary step):

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
v.db.select map=sampling columns=urban_change_clip,counties,devpressure_0_5,devpressure_1,slope,road_dens_perc,forest_smooth_perc,dist_to_water_km,dist_to_protected_km,dist_interchanges_km,travel_time_cities separator=comma file=samples.csv
</source>

=== Development potential ===
Now we find best model for predicting urbanization using {{AddonCmd|r.futures.potential}} which wraps an R script.

We can run R [http://www.inside-r.org/packages/cran/MuMIn/docs/dredge dredge] function to find "best" model. We can specify minimum and maximum number of predictors the final model should use.
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.potential -d input=sampling output=potential.csv columns=devpressure_1,slope,road_dens_perc,forest_smooth_perc,dist_to_water_km,dist_to_protected_km,dist_interchanges_km,travel_time_cities developed_column=urban_change_clip subregions_column=counties min_variables=4
</source>

Also, we can play with different combinations of predictors, for example:

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.potential input=sampling output=potential.csv columns=devpressure_2,road_dens_perc,slope,dist_interchanges_km,dist_to_water_km developed_column=urban_change_clip subregions_column=counties --o
r.futures.potential input=sampling output=potential.csv columns=devpressure_1,road_dens_perc,slope,dist_interchanges_km,dist_to_water_km developed_column=urban_change_clip subregions_column=counties --o
...
</source>

You can then open the output file <tt>potential.csv</tt>, which is a CSV file with tabs as separators.

For this tutorial, the final potential is created with:
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.potential input=sampling output=potential.csv columns=devpressure_2,road_dens_perc,slope,dist_interchanges_km,dist_to_water_km developed_column=urban_change_clip subregions_column=counties --o
</source>

We can now visualize the suitability surface using module {{AddonCmd|r.futures.potsurface}}. It creates initial development potential (suitability) raster from predictors and model coefficients and serves only for evaluating development potential model. The values of the resulting raster range from 0 to 1.

<source lang="bash">
r.futures.potsurface input=potential.csv subregions=counties output=suitability
r.colors map=suitability color=byr
</source>

== Demand submodel ==
First we will mask out roads so that they don't influence into per capita land demand relation.
<source lang="bash">
v.to.rast input=roads type=line output=roads_mask use=val
r.mask roads_mask -i
</source>

We will use {{AddonCmd|r.futures.demand}} which derives the population vs. development relation. The relation can be linear/logarithmic/logarithmic2/exponential/exponential approach.
Look for examples of the different relations in the manual.

* linear: y = A + Bx
* logarithmic: y = A + Bln(x)
* logarithmic2: y = A + B * ln(x - C)        (requires SciPy)
* exponential: y = Ae^(BX)
* exp_approach: y = (1 - e^(-A(x - B))) + C        (requires SciPy)

The format of the input population CSV files is described in the manual. It is important to have synchronized categories of subregions and the column headers of the CSV files (in our case FIPS number). How to simply generate the list of years (for which demand is computed) is described in {{AddonCmd|r.futures.demand}} manual, for example run this in Python console:

<source lang="python">
','.join([str(i) for i in range(2011, 2036)])
</source>

Then we can create the DEMAND file:
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.demand development=urban_1992,urban_2001,urban_2011 subregions=counties observed_population=population_trend.csv projected_population=population_projection.csv simulation_times=2011,2012,2013,2014,2015,2016,2017,2018,2019,2020,2021,2022,2023,2024,2025,2026,2027,2028,2029,2030,2031,2032,2033,2034,2035 plot=plot_demand.pdf demand=demand.csv separator=comma
</source>

In your current working directory, you should find files <tt>plot_demand.png</tt> and <tt>demand.csv</tt>.

If you have SciPy installed, you can experiment with other methods for fitting the functions:
<source lang="bash">
r.futures.demand ... method=logarithmic2
r.futures.demand ... method=exp_approach
</source>
If necessary, you can create a set of demand files produced by fitting each method separately and
then pick for each county the method which seems best and manually create a new demand file.

When you are finished, remove the mask as it is not needed for the next steps.
<source lang="bash">
r.mask -r
</source>

== Patch calibration ==
Patch calibration can be a very time consuming computation.
Therefore we select only one county (Buncombe):

<source lang="bash">
v.to.rast input=counties type=area where="FIPS == 37021" use=attr attribute_column=FIPS output=calib_county
g.region raster=calib_county zoom=calib_county
</source>
to derive patches of new development by comparing historical and latest development.
We can keep only patches with minimum size 2 cells (1800 = 2 x 30 x 30 m).

<source lang="bash">
r.futures.calib development_start=urban_1992 development_end=urban_2011 subregions=counties patch_sizes=patches.txt patch_threshold=1800 -l
</source>
We obtained a file <tt>patches.txt</tt> (used later in the PGA) - a patch size distribution file - containing sizes of all found patches.

We can look at the distribution of the patch sizes:

<source lang="python">
from matplotlib import pyplot as plt
with open('patches.txt') as f:
patches = [int(patch) for patch in f.readlines()]
plt.hist(patches, 2000)
plt.xlim(0,50)
plt.show()
</source>

At this point, we start the calibration to get best parameters of patch shape
(for this tutorial, this step can be skipped and the suggested parameters are used).

<source lang="bash"
style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.calib development_start=urban_1992 development_end=urban_2011 subregions=calib_county patch_sizes=patches.txt calibration_results=calib.csv patch_threshold=1800 repeat=5 compactness_mean=0.1,0.3,0.5,0.7,0.9 compactness_range=0.05 discount_factor=0.1,0.3,0.5,0.7,0.9 predictors=road_dens_perc,forest_smooth_perc,dist_to_protected_km demand=demand.csv devpot_params=potential.csv num_neighbors=4 seed_search=2 development_pressure=devpressure_0_5 development_pressure_approach=gravity n_dev_neighbourhood=30 gamma=0.5 scaling_factor=0.1
</source>

== FUTURES simulation ==
We will switch back to our previous region:
<source lang="bash">
g.region raster=landuse_2011 -p
</source>

Now we have all the inputs necessary for running {{AddonCmd|r.futures.pga}}:

The entire command is here:
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.pga subregions=counties developed=urban_2011 predictors=slope,forest_smooth_perc,dist_interchanges_km,travel_time_cities devpot_params=potential.csv development_pressure=devpressure_1 n_dev_neighbourhood=10 development_pressure_approach=gravity gamma=1 scaling_factor=1 demand=demand.csv discount_factor=0.3 compactness_mean=0.2 compactness_range=0.1 patch_sizes=patches.txt num_neighbors=4 seed_search=2 random_seed=1 output=final output_series=final
</source>

=== Quick description ===
The command parameters and their values:
* raster map of counties with their categories
<code>
... subregions=counties ...
</code>

* raster of developed (1), undeveloped (0) and NULLs for undevelopable areas
<code>
... developed=urban_2011 ...
</code>

* predictors selected with {{AddonCmd|r.futures.potential}} and their coefficients in a <tt>potential.csv</tt> file. The order of predictors must match the order in the file and the categories of the counties must match raster <tt>counties</tt>.
<code>
... predictors=slope,forest_smooth_perc,dist_interchanges_km,travel_time_cities devpot_params=potential.csv ...
</code>

* initial development pressure computed by {{AddonCmd|r.futures.devpressure}}, it's important to set here the same parameters
<code>
... development_pressure=devpressure_1 n_dev_neighbourhood=10 development_pressure_approach=gravity gamma=1 scaling_factor=1 ...
</code>

* per capita land demand computed by {{AddonCmd|r.futures.demand}}, the categories of the counties must match raster <tt>counties</tt>.
<code>
... demand=demand.csv ...
</code>

* patch parameters from the calibration step
<code>
... discount_factor=0.3 compactness_mean=0.4 compactness_range=0.08 patch_sizes=patches.txt ...
</code>

* recommended parameters for patch growing algorithm
<code>
... num_neighbors=4 seed_search=2 ...
</code>

* set random seed for repeatable results or set flag <tt>-s</tt> to generate seed automatically
<code>
... random_seed=1 ...
</code>

* specify final output map and optionally basename for intermediate raster maps
<code>
output=final output_series=final
</code>

== Scenarios ==
Scenarios involving policies that encourage infill versus sprawl can be explored using the <tt>incentive_power</tt> parameter of {{AddonCmd|r.futures.pga}},
which uses a power function to transform the evenness of the probability gradient in POTENTIAL. You can change the power to a number between 0.25 and 4 to test urban sprawl/infill scenarios.
Higher power leads to infill behavior, lower power to urban sprawl.

== Postprocessing ==

Follow a [[Creating_animation_from_FUTURES_output_in_GRASS_GIS| tutorial how to make an animation from the results]].

= GRASS GIS Python API =

[[Category: Tutorial]]
[[Category: FUTURES]]
[[Category: Urban]]

Workshop on urban growth modeling with FUTURES

2016-03-22T17:58:41Z

⚠️Dbvanber: /* GRASS GIS introduction */

{{ToModify}}
= Workshop introduction =
r.futures.* is an implementation of the '''FUT'''ure '''U'''rban-'''R'''egional '''E'''nvironment '''S'''imulation (FUTURES)[1] which is a model for multilevel simulations of emerging urban-rural landscape structure. FUTURES produces regional projections of landscape patterns using coupled submodels that integrate nonstationary drivers of land change: per capita demand (DEMAND submodel), site suitability (POTENTIAL submodel), and the spatial structure of conversion events (PGA submodel).

[1] Meentemeyer, R. K., Tang, W., Dorning, M. A., Vogler, J. B., Cunniffe, N. J., & Shoemaker, D. A. (2013). [http://www.tandfonline.com/doi/abs/10.1080/00045608.2012.707591 FUTURES: multilevel simulations of emerging urban-rural landscape structure using a stochastic patch-growing algorithm.] Annals of the Association of American Geographers, 103(4), 785-807

== Software ==
There are a number of software requirements to run FUTURES that will need to be download and installed. Required software includes:
* GRASS GIS 7
* addons
** {{AddonCmd|r.futures.pga}}
** {{AddonCmd|r.futures.potential}}
** {{AddonCmd|r.futures.potsurface}}
** {{AddonCmd|r.futures.demand}}
** {{AddonCmd|r.futures.devpressure}}
** {{AddonCmd|r.sample.category}}
* R (≥ 3.0.2) - needed for {{AddonCmd|r.futures.potential}} with packages:
**MuMIn, lme4, optparse, rgrass7
* SciPy - useful for {{AddonCmd|r.futures.demand}}

=== Installation ===
We use the R statistical software for our calculation of site suitability (i.e. development potential) in FUTURES. R is a free software environment for statistical computing and graphics. If you don't have R, or you have older an version, please download and install the software from [http://archive.linux.duke.edu/cran/ install R] and be sure to additionally add these required packages:
<pre>
install.packages(c("MuMIn", "lme4", "optparse", "rgrass7"))
</pre>

==== MS Windows ====
We will be using GRASS GIS 7.0.3 that can be found here in the [https://trac.osgeo.org/osgeo4w/ OSGeo4W] package manager.
Please install the latest stable GRASS GIS 7 version and the SciPy Python package using the ''Advanced install'' option.
A guide with step by step screen shot instructions is available [https://docs.google.com/presentation/d/1yEGpriBne7RvjB35HI6GecNwO1P1y2nRGqDThqoNnCE/edit?usp=sharing here].

In order for GRASS to be able to find R executables, GRASS must be on the PATH variable. Follow this [solution] to make R accessible from GRASS permanently.
A simple but temporary solution is to open GRASS GIS and paste this in the black terminal:
<pre>
set PATH=%PATH%;C:\Program Files\R\R-3.0.2\bin
</pre>
This has to be repeated after restarting GRASS session.

==== Ubuntu Linux ====
Install GRASS GIS from packages:
<pre>
sudo add-apt-repository ppa:ubuntugis/ubuntugis-unstable
sudo apt-get update
sudo apt-get install grass
</pre>

== Workshop data ==
The data that we will be using for the workshop can be download here: [http://fatra.cnr.ncsu.edu/futures/futures_ncspm_Asheville.zip sample dataset]. Please place these layers in your local GRASS directory:
* digital elevation model ([http://nationalmap.gov/elevation.html NED])
* [http://www.mrlc.gov/ NLCD] 2001, 2011
* NLCD 1992/2001 Retrofit Land Cover Change Product
* transportation network ([http://www.census.gov/geo/maps-data/data/tiger-line.html TIGER])
* county boundaries ([http://www.census.gov/geo/maps-data/data/tiger-line.html TIGER])
* protected areas ([http://www.conservationgateway.org/ConservationByGeography/NorthAmerica/UnitedStates/edc/reportsdata/terrestrial/secured/Pages/default.aspx Secured Lands])
* cities as points (USGS)

In addition, download [http://fatra.cnr.ncsu.edu/futures/futures_Asheville_files.zip population information as text files]:
* county population past estimates and future projections ([https://www.osbm.nc.gov/demog/county-projections NC OSBM]) per county (nonspatial)

= GRASS GIS introduction =
There are many advantages to using the open source GRASS GIS platform, but for many that are more familiar with ARCGis and QGis, the setup and implementation of spatial tools in GRASS can be confusing. Here we provide an overview of the GRASS GIS project: [https://grass.osgeo.org grass.osgeo.org] that might be helpful to review if you are a first time users. For this exercise it's not necessary to have a full understanding of how to use GRASS. However, you will need to know how to place your data in the correct GRASS database directory, as well as some basic GRASS functionality. Step by step instructions are provided below
* Our overview of [https://grass.osgeo.org/grass71/manuals/grass_database.html GRASS database] will include:
** ''GRASS database'': directory with Locations (projects)
** ''Location'': directory with Mapsets, defined by projection (spatial reference system)
** ''Mapset'': collection of maps
* Download the [http://fatra.cnr.ncsu.edu/futures/futures_ncspm_Asheville.zip workshop location]. Create (unless you already have it) a directory named <tt>grassdata</tt> (GRASS database) in your home folder (or Documents), unzip the downloaded data into this directory. You should have now Location <tt>futures_ncspm</tt> in <tt>grassdata</tt>.
* Launch GRASS and display raster, vector data, explore navigation, querying, adding legend, showing metadata
<center><gallery perrow=3 widths=500 heights=250>Image:GRASS FUTURES startup.png|GRASS GIS 7.0.3 startup dialog with downloaded Location and Mapsets for FUTURES workshop
Image:GRASS FUTURES wxGUI display.png|Layer Manager and Map Display overview. Annotations show how to add raster layer, query, add legend.
Image:wxGUI_metadata_rinfo.png|Show raster map metadata by right click on layer</gallery></center>

* GRASS GIS has over [https://grass.osgeo.org/grass70/manuals/full_index.html 500 different modules] in the core distribution and over [https://grass.osgeo.org/grass70/manuals/addons/ 230 addon modules]
<center>
{| class="wikitable"
|-
! Prefix !! Function !! Example
|-
| r.* || raster processing || ''{{cmd|r.mapcalc}}'': map algebra
|-
| v.* || vector processing || ''{{cmd|v.clean}}'': topological cleaning
|-
| i.* || imagery processing || ''{{cmd|i.segment}}'': object recognition
|-
| db.* || database management || ''{{cmd|db.select}}'': select values from table
|-
| r3.* || 3D raster processing || ''{{cmd|r3.stats}}'': 3D raster statistics
|-
| t.* || temporal data processing || ''{{cmd|t.rast.aggregate}}'': temporal aggregation
|-
| g.* || general data management || ''{{cmd|g.rename}}'': renames map
|-
| d.* || display ||''{{cmd|d.rast}}'': display raster map
|}</center>
* GRASS modules have GUI and command line interface. In this workshop we use commands to describe the workflow, but we can use both GUI and command line depending on personal preference. Look how {{cmd|wxGUI.modules|version=71|desc=GUI and command line interface}} represent the same tool. ''Task:'' compute aspect (orientation) from provided digital elevation model using module {{cmd|r.slope.aspect}} using both module dialog and command line.
* How to find modules? Modules are organized by their functionality in wxGUI menu, or we can search for them in Search modules tab. If we already know which module to use, we can just type it in the wxGUI command console. <center><gallery perrow=3 widths=380 heights=190>Image:wxGUI_menu_rinfo.png|Modules can be found in wxGUI menu
Image:wxGUI_module_search.png|You can search modules by name, description or keywords in ''Search modules'' tab
Image:wxGUI_console_completion.png|By typing prefix r. we make a list of modules starting with that prefix to show up.</gallery></center>


* {{cmd|g.region|desc=Computational region}} - an important raster concept
** defined by region extent and raster resolution
** applies to all raster operations
** persists between GRASS session, can be different for different mapsets
** advantages: keeps your results consistent, avoid clipping, for computationally demanding tasks set region to smaller extent, check your result is good and then set the computational region to the entire study area and rerun analysis
** run <code>g.region -p</code> or in menu ''Settings'' - ''Region'' - ''Display region'' to see current region settings
[[File:WxGUI set region.png|700px|thumb|center|Simple ways to set computational region from GUI. On the left, set region to match raster map. On the right, select the highlighted option and then set region by drawing rectangle.]]

* GRASS 3D view

= Modeling with FUTURES =
== Initial steps and data preparation ==
First we will set the computational region of our analyses to an extent covering our study area and aligned with our base landuse rasters:
<source lang="bash">g.region raster=landuse_2011 -p</source>

We will derive urbanized areas from NLCD dataset for year 1992, 2001 and 2011
by extracting categories category 21 - 24 into a new binary map where developed is 1,
undeveloped 0 and NULL (no data) is area unsuitable for development (water, wetlands, protected areas).
First we will convert protected areas from vector to raster. We set
NULLs to zeros (for simpler raster algebra expression in the next step) using {{cmd|r.null}}:

<source lang="bash">
v.to.rast input=protected_areas output=protected_areas use=val
r.null map=protected_areas null=0
</source>

And then create rasters of developed/undeveloped areas using raster algebra:

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.mapcalc "urban_1992 = if(landuse_1992 >= 21 && landuse_1992 <= 24, 1, if(landuse_1992 == 11 || landuse_1992 >= 90 || protected_areas, null(), 0))"
r.mapcalc "urban_2001 = if(landuse_2001 >= 21 && landuse_2001 <= 24, 1, if(landuse_2001 == 11 || landuse_2001 >= 90 || protected_areas, null(), 0))"
r.mapcalc "urban_2011 = if(landuse_2011 >= 21 && landuse_2011 <= 24, 1, if(landuse_2011 == 11 || landuse_2011 >= 90 || protected_areas, null(), 0))"
</source>

We will convert vector counties to raster with the values of the FIPS attribute which links to population file:

<source lang="bash">
v.to.rast input=counties type=area use=attr attribute_column=FIPS output=counties
</source>

Before further steps, we will set our working directory so that the input population files and text files
we are going to create are saved in one directory and easily accessible.
You can do that from menu ''Settings'' → ''GRASS working environment'' → ''Change working directory''.
Select (or create) a directory and move there the downloaded files <tt>population_projection.csv</tt> and <tt>population_trend.csv</tt>.

== Potential submodel ==
Module {{AddonCmd|r.futures.potential}} implements POTENTIAL submodel as a part of FUTURES land change model. POTENTIAL is implemented using a set of coefficients that relate a selection of site suitability factors to the probability of a place becoming developed. This is implemented using the parameter table in combination with maps of those site suitability factors (mapped predictors). The coefficients are obtained by conducting multilevel logistic regression in R with package lme4 where the coefficients may vary by county. The best model is selected automatically using dredge function from package [https://cran.r-project.org/web/packages/MuMIn/index.html MuMIn].

First, we will derive couple of predictors.
=== Predictors ===
==== Slope ====
We will derive slope in degrees from digital elevation model using {{cmd|r.slope.aspect}} module:
<source lang="bash">r.slope.aspect elevation=elevation_30m slope=slope</source>

==== Distance from lakes/rivers ====
First we will extract [http://www.mrlc.gov/nlcd11_leg.php category ''Open Water''] from 2011 NLCD dataset:
<source lang="bash">
r.mapcalc "water = if(landuse_2011 == 11, 1, null())"
</source>

Then we compute the distance to water with module {{cmd|r.grow.distance}} and set color table to shades of blue:
<source lang="bash">
r.grow.distance input=water distance=dist_to_water
r.colors -n map=dist_to_water color=blues
</source>

==== Distance from protected areas ====
We will use raster protected of protected areas we already created, but we will set NULL values to zero.
We compute the distance to protected areas with module {{cmd|r.grow.distance}} and set color table from green to red:
<source lang="bash">
r.null map=protected_areas setnull=0
r.grow.distance input=protected_areas distance=dist_to_protected
r.colors map=dist_to_protected color=gyr
</source>

==== Forests ====
We will smooth the transition between forest and other land use, see NLCD [http://www.mrlc.gov/nlcd11_leg.php category ''Open Water'']:
<source lang="bash">
r.mapcalc "forest = if(landuse_2011 >= 41 && landuse_2011 <= 43, 1, 0)"
r.neighbors -c input=forest output=forest_smooth size=15 method=average
r.colors map=forest_smooth color=ndvi
</source>

==== Travel time to cities ====
Here we will compute travel time to cities (with population > 5000)
as cumulative cost distance where cost is defined as travel time on roads.
First we specify the speed on different types of roads.
We copy the roads raster into our mapset so that we can change it
by adding a new attribute field <tt>speed</tt>. Then we assign speed values (km/h) based on the type of road:

<source lang="bash">
g.copy vector=roads,myroads
v.db.addcolumn map=myroads columns="speed double precision"
v.db.update map=myroads column=speed value=50 where="MTFCC = 'S1400'"
v.db.update map=myroads column=speed value=100 where="MTFCC IN ('S1100', 'S1200')"
</source>

Now we rasterize the selected road types using the speed values from the attribute table as raster values.

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
v.to.rast input=myroads type=line where="MTFCC IN ('S1100', 'S1200', 'S1400')" output=roads_speed use=attr attribute_column=speed
</source>

We set the rest of the area to low speed and recompute the speed as time to travel through a 30m cell in minutes:

<source lang="bash">
r.null map=roads_speed null=5
r.mapcalc "roads_travel_time = 1.8 / roads_speed"
</source>

Finally we compute the travel time to larger cities using {{cmd|r.cost}}:

<source lang="bash">
r.cost input=roads_travel_time output=travel_time_cities start_points=cities
r.colors map=travel_time_cities color=byr
</source>

==== Road density ====
We will rasterize roads and use moving window analysis ({{cmd|r.neighbors}}) to compute road density:

<source lang="bash">
v.to.rast input=roads output=roads use=val type=line
r.null map=roads null=0
r.neighbors -c input=roads output=road_dens size=25 method=average
</source>

==== Distance to interchanges ====

We will consider TIGER roads of type <tt>Ramp</tt> as interchanges, rasterize them and compute euclidean distance to them:

<source lang="bash">
v.to.rast input=roads type=line where="MTFCC = 'S1630'" output=interchanges use=val
r.grow.distance -m input=interchanges distance=dist_interchanges
</source>

=== Development pressure ===

We compute development pressure with {{AddonCmd|r.futures.devpressure}}. Development pressure is a predictor based on number of neighboring developed cells within search distance, weighted by distance. The development pressure variable plays a special role in the model, allowing for a feedback between predicted change and change in subsequent steps.

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.devpressure -n input=urban_2011 output=devpressure_2 method=gravity size=7 gamma=2 scaling_factor=10
r.futures.devpressure -n input=urban_2011 output=devpressure_1 method=gravity size=10 gamma=1 scaling_factor=1
r.futures.devpressure -n input=urban_2011 output=devpressure_0_5 method=gravity size=30 gamma=0.5 scaling_factor=0.1
</source>

When gamma increases, development influence decreases more rapidly with distance.
Size is half the size of the moving window. When gamma is low, local development influences more distant places.
We will derive 3 layers with different gamma and size parameters for the potential statistical model.

=== Rescaling variables ===

First we will look at the ranges of our predictor variables by running a short Python code snippet in Python shell:

<source lang="python" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
for name in ['slope', 'dist_to_water', 'dist_to_protected', 'forest_smooth', 'travel_time_cities', 'road_dens', 'dist_interchanges', 'devpressure_0_5', 'devpressure_1']:
minmax = grass.raster_info(name)
print name, minmax['min'], minmax['max']
</source>

We will rescale some of our input variables:

<source lang="bash">
r.mapcalc "dist_to_water_km = dist_to_water / 1000"
r.mapcalc "dist_to_protected_km = dist_to_protected / 1000"
r.mapcalc "dist_interchanges_km = dist_interchanges / 1000"
r.mapcalc "road_dens_perc = road_dens * 100"
r.mapcalc "forest_smooth_perc = forest_smooth * 100"
</source>

=== Sampling ===
To sample only in the analyzed counties, we will clip development layer:

<source lang="bash">
r.mapcalc "urban_change_01_11 = if(urban_2011 == 1, if(urban_2001 == 0, 1, null()), 0)"
r.mapcalc "urban_change_clip = if(counties, urban_change_01_11)"
</source>

To estimate the number of sampling points, we can use {{cmd|r.report}} to report number of developed/undeveloped cells and their ratio.

<source lang="bash">
r.report map=urban_change_clip units=h,c,p
</source>

We will sample the predictors and the response variable with 5000 random points in undeveloped areas and 1000 points in developed area:

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.sample.category input=urban_change_clip output=sampling sampled=counties,devpressure_0_5,devpressure_1,devpressure_2,slope,road_dens_perc,forest_smooth_perc,dist_to_water_km,dist_to_protected_km,dist_interchanges_km,travel_time_cities npoints=5000,1000
</source>

The attribute table can be exported as CSV file (not necessary step):

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
v.db.select map=sampling columns=urban_change_clip,counties,devpressure_0_5,devpressure_1,slope,road_dens_perc,forest_smooth_perc,dist_to_water_km,dist_to_protected_km,dist_interchanges_km,travel_time_cities separator=comma file=samples.csv
</source>

=== Development potential ===
Now we find best model for predicting urbanization using {{AddonCmd|r.futures.potential}} which wraps an R script.

We can run R [http://www.inside-r.org/packages/cran/MuMIn/docs/dredge dredge] function to find "best" model. We can specify minimum and maximum number of predictors the final model should use.
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.potential -d input=sampling output=potential.csv columns=devpressure_1,slope,road_dens_perc,forest_smooth_perc,dist_to_water_km,dist_to_protected_km,dist_interchanges_km,travel_time_cities developed_column=urban_change_clip subregions_column=counties min_variables=4
</source>

Also, we can play with different combinations of predictors, for example:

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.potential input=sampling output=potential.csv columns=devpressure_2,road_dens_perc,slope,dist_interchanges_km,dist_to_water_km developed_column=urban_change_clip subregions_column=counties --o
r.futures.potential input=sampling output=potential.csv columns=devpressure_1,road_dens_perc,slope,dist_interchanges_km,dist_to_water_km developed_column=urban_change_clip subregions_column=counties --o
...
</source>

You can then open the output file <tt>potential.csv</tt>, which is a CSV file with tabs as separators.

For this tutorial, the final potential is created with:
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.potential input=sampling output=potential.csv columns=devpressure_2,road_dens_perc,slope,dist_interchanges_km,dist_to_water_km developed_column=urban_change_clip subregions_column=counties --o
</source>

We can now visualize the suitability surface using module {{AddonCmd|r.futures.potsurface}}. It creates initial development potential (suitability) raster from predictors and model coefficients and serves only for evaluating development potential model. The values of the resulting raster range from 0 to 1.

<source lang="bash">
r.futures.potsurface input=potential.csv subregions=counties output=suitability
r.colors map=suitability color=byr
</source>

== Demand submodel ==
First we will mask out roads so that they don't influence into per capita land demand relation.
<source lang="bash">
v.to.rast input=roads type=line output=roads_mask use=val
r.mask roads_mask -i
</source>

We will use {{AddonCmd|r.futures.demand}} which derives the population vs. development relation. The relation can be linear/logarithmic/logarithmic2/exponential/exponential approach.
Look for examples of the different relations in the manual.

* linear: y = A + Bx
* logarithmic: y = A + Bln(x)
* logarithmic2: y = A + B * ln(x - C)        (requires SciPy)
* exponential: y = Ae^(BX)
* exp_approach: y = (1 - e^(-A(x - B))) + C        (requires SciPy)

The format of the input population CSV files is described in the manual. It is important to have synchronized categories of subregions and the column headers of the CSV files (in our case FIPS number). How to simply generate the list of years (for which demand is computed) is described in {{AddonCmd|r.futures.demand}} manual, for example run this in Python console:

<source lang="python">
','.join([str(i) for i in range(2011, 2036)])
</source>

Then we can create the DEMAND file:
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.demand development=urban_1992,urban_2001,urban_2011 subregions=counties observed_population=population_trend.csv projected_population=population_projection.csv simulation_times=2011,2012,2013,2014,2015,2016,2017,2018,2019,2020,2021,2022,2023,2024,2025,2026,2027,2028,2029,2030,2031,2032,2033,2034,2035 plot=plot_demand.pdf demand=demand.csv separator=comma
</source>

In your current working directory, you should find files <tt>plot_demand.png</tt> and <tt>demand.csv</tt>.

If you have SciPy installed, you can experiment with other methods for fitting the functions:
<source lang="bash">
r.futures.demand ... method=logarithmic2
r.futures.demand ... method=exp_approach
</source>
If necessary, you can create a set of demand files produced by fitting each method separately and
then pick for each county the method which seems best and manually create a new demand file.

When you are finished, remove the mask as it is not needed for the next steps.
<source lang="bash">
r.mask -r
</source>

== Patch calibration ==
Patch calibration can be a very time consuming computation.
Therefore we select only one county (Buncombe):

<source lang="bash">
v.to.rast input=counties type=area where="FIPS == 37021" use=attr attribute_column=FIPS output=calib_county
g.region raster=calib_county zoom=calib_county
</source>
to derive patches of new development by comparing historical and latest development.
We can keep only patches with minimum size 2 cells (1800 = 2 x 30 x 30 m).

<source lang="bash">
r.futures.calib development_start=urban_1992 development_end=urban_2011 subregions=counties patch_sizes=patches.txt patch_threshold=1800 -l
</source>
We obtained a file <tt>patches.txt</tt> (used later in the PGA) - a patch size distribution file - containing sizes of all found patches.

We can look at the distribution of the patch sizes:

<source lang="python">
from matplotlib import pyplot as plt
with open('patches.txt') as f:
patches = [int(patch) for patch in f.readlines()]
plt.hist(patches, 2000)
plt.xlim(0,50)
plt.show()
</source>

At this point, we start the calibration to get best parameters of patch shape
(for this tutorial, this step can be skipped and the suggested parameters are used).

<source lang="bash"
style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.calib development_start=urban_1992 development_end=urban_2011 subregions=calib_county patch_sizes=patches.txt calibration_results=calib.csv patch_threshold=1800 repeat=5 compactness_mean=0.1,0.3,0.5,0.7,0.9 compactness_range=0.05 discount_factor=0.1,0.3,0.5,0.7,0.9 predictors=road_dens_perc,forest_smooth_perc,dist_to_protected_km demand=demand.csv devpot_params=potential.csv num_neighbors=4 seed_search=2 development_pressure=devpressure_0_5 development_pressure_approach=gravity n_dev_neighbourhood=30 gamma=0.5 scaling_factor=0.1
</source>

== FUTURES simulation ==
We will switch back to our previous region:
<source lang="bash">
g.region raster=landuse_2011 -p
</source>

Now we have all the inputs necessary for running {{AddonCmd|r.futures.pga}}:

The entire command is here:
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.pga subregions=counties developed=urban_2011 predictors=slope,forest_smooth_perc,dist_interchanges_km,travel_time_cities devpot_params=potential.csv development_pressure=devpressure_1 n_dev_neighbourhood=10 development_pressure_approach=gravity gamma=1 scaling_factor=1 demand=demand.csv discount_factor=0.3 compactness_mean=0.2 compactness_range=0.1 patch_sizes=patches.txt num_neighbors=4 seed_search=2 random_seed=1 output=final output_series=final
</source>

=== Quick description ===
The command parameters and their values:
* raster map of counties with their categories
<code>
... subregions=counties ...
</code>

* raster of developed (1), undeveloped (0) and NULLs for undevelopable areas
<code>
... developed=urban_2011 ...
</code>

* predictors selected with {{AddonCmd|r.futures.potential}} and their coefficients in a <tt>potential.csv</tt> file. The order of predictors must match the order in the file and the categories of the counties must match raster <tt>counties</tt>.
<code>
... predictors=slope,forest_smooth_perc,dist_interchanges_km,travel_time_cities devpot_params=potential.csv ...
</code>

* initial development pressure computed by {{AddonCmd|r.futures.devpressure}}, it's important to set here the same parameters
<code>
... development_pressure=devpressure_1 n_dev_neighbourhood=10 development_pressure_approach=gravity gamma=1 scaling_factor=1 ...
</code>

* per capita land demand computed by {{AddonCmd|r.futures.demand}}, the categories of the counties must match raster <tt>counties</tt>.
<code>
... demand=demand.csv ...
</code>

* patch parameters from the calibration step
<code>
... discount_factor=0.3 compactness_mean=0.4 compactness_range=0.08 patch_sizes=patches.txt ...
</code>

* recommended parameters for patch growing algorithm
<code>
... num_neighbors=4 seed_search=2 ...
</code>

* set random seed for repeatable results or set flag <tt>-s</tt> to generate seed automatically
<code>
... random_seed=1 ...
</code>

* specify final output map and optionally basename for intermediate raster maps
<code>
output=final output_series=final
</code>

== Scenarios ==
Scenarios involving policies that encourage infill versus sprawl can be explored using the <tt>incentive_power</tt> parameter of {{AddonCmd|r.futures.pga}},
which uses a power function to transform the evenness of the probability gradient in POTENTIAL. You can change the power to a number between 0.25 and 4 to test urban sprawl/infill scenarios.
Higher power leads to infill behavior, lower power to urban sprawl.

== Postprocessing ==

Follow a [[Creating_animation_from_FUTURES_output_in_GRASS_GIS| tutorial how to make an animation from the results]].

= GRASS GIS Python API =

[[Category: Tutorial]]
[[Category: FUTURES]]
[[Category: Urban]]

Workshop on urban growth modeling with FUTURES

2016-03-22T17:53:36Z

⚠️Dbvanber: /* Initial steps and data preparation */

{{ToModify}}
= Workshop introduction =
r.futures.* is an implementation of the '''FUT'''ure '''U'''rban-'''R'''egional '''E'''nvironment '''S'''imulation (FUTURES)[1] which is a model for multilevel simulations of emerging urban-rural landscape structure. FUTURES produces regional projections of landscape patterns using coupled submodels that integrate nonstationary drivers of land change: per capita demand (DEMAND submodel), site suitability (POTENTIAL submodel), and the spatial structure of conversion events (PGA submodel).

[1] Meentemeyer, R. K., Tang, W., Dorning, M. A., Vogler, J. B., Cunniffe, N. J., & Shoemaker, D. A. (2013). [http://www.tandfonline.com/doi/abs/10.1080/00045608.2012.707591 FUTURES: multilevel simulations of emerging urban-rural landscape structure using a stochastic patch-growing algorithm.] Annals of the Association of American Geographers, 103(4), 785-807

== Software ==
There are a number of software requirements to run FUTURES that will need to be download and installed. Required software includes:
* GRASS GIS 7
* addons
** {{AddonCmd|r.futures.pga}}
** {{AddonCmd|r.futures.potential}}
** {{AddonCmd|r.futures.potsurface}}
** {{AddonCmd|r.futures.demand}}
** {{AddonCmd|r.futures.devpressure}}
** {{AddonCmd|r.sample.category}}
* R (≥ 3.0.2) - needed for {{AddonCmd|r.futures.potential}} with packages:
**MuMIn, lme4, optparse, rgrass7
* SciPy - useful for {{AddonCmd|r.futures.demand}}

=== Installation ===
We use the R statistical software for our calculation of site suitability (i.e. development potential) in FUTURES. R is a free software environment for statistical computing and graphics. If you don't have R, or you have older an version, please download and install the software from [http://archive.linux.duke.edu/cran/ install R] and be sure to additionally add these required packages:
<pre>
install.packages(c("MuMIn", "lme4", "optparse", "rgrass7"))
</pre>

==== MS Windows ====
We will be using GRASS GIS 7.0.3 that can be found here in the [https://trac.osgeo.org/osgeo4w/ OSGeo4W] package manager.
Please install the latest stable GRASS GIS 7 version and the SciPy Python package using the ''Advanced install'' option.
A guide with step by step screen shot instructions is available [https://docs.google.com/presentation/d/1yEGpriBne7RvjB35HI6GecNwO1P1y2nRGqDThqoNnCE/edit?usp=sharing here].

In order for GRASS to be able to find R executables, GRASS must be on the PATH variable. Follow this [solution] to make R accessible from GRASS permanently.
A simple but temporary solution is to open GRASS GIS and paste this in the black terminal:
<pre>
set PATH=%PATH%;C:\Program Files\R\R-3.0.2\bin
</pre>
This has to be repeated after restarting GRASS session.

==== Ubuntu Linux ====
Install GRASS GIS from packages:
<pre>
sudo add-apt-repository ppa:ubuntugis/ubuntugis-unstable
sudo apt-get update
sudo apt-get install grass
</pre>

== Workshop data ==
The data that we will be using for the workshop can be download here: [http://fatra.cnr.ncsu.edu/futures/futures_ncspm_Asheville.zip sample dataset]. Please place these layers in your local GRASS directory:
* digital elevation model ([http://nationalmap.gov/elevation.html NED])
* [http://www.mrlc.gov/ NLCD] 2001, 2011
* NLCD 1992/2001 Retrofit Land Cover Change Product
* transportation network ([http://www.census.gov/geo/maps-data/data/tiger-line.html TIGER])
* county boundaries ([http://www.census.gov/geo/maps-data/data/tiger-line.html TIGER])
* protected areas ([http://www.conservationgateway.org/ConservationByGeography/NorthAmerica/UnitedStates/edc/reportsdata/terrestrial/secured/Pages/default.aspx Secured Lands])
* cities as points (USGS)

In addition, download [http://fatra.cnr.ncsu.edu/futures/futures_Asheville_files.zip population information as text files]:
* county population past estimates and future projections ([https://www.osbm.nc.gov/demog/county-projections NC OSBM]) per county (nonspatial)

= GRASS GIS introduction =
There are many advantages to using the open source GRASS GIS platform, but for many that are more familiar with ARCGis and QGis, the setup and implementation of spatial tools in GRASS can be confusing. Here we provide an overview of the GRASS GIS project: [https://grass.osgeo.org grass.osgeo.org] that might be helpful to review if you are a first time users. For this exercise it's not necessary to have a full understanding of how to use GRASS. However, you will need to know how to place your data in the correct GRASS database directory and for this we provide step by step instructions.
* Overview of [https://grass.osgeo.org/grass71/manuals/grass_database.html GRASS database].
** ''GRASS database'': directory with Locations (projects)
** ''Location'': directory with Mapsets, defined by projection (spatial reference system)
** ''Mapset'': collection of maps
* Download the [http://fatra.cnr.ncsu.edu/futures/futures_ncspm_Asheville.zip workshop location]. Create (unless you already have it) a directory named <tt>grassdata</tt> (GRASS database) in your home folder (or Documents), unzip the downloaded data into this directory. You should have now Location <tt>futures_ncspm</tt> in <tt>grassdata</tt>.
* Launch GRASS and display raster, vector data, explore navigation, querying, adding legend, showing metadata
<center><gallery perrow=3 widths=500 heights=250>Image:GRASS FUTURES startup.png|GRASS GIS 7.0.3 startup dialog with downloaded Location and Mapsets for FUTURES workshop
Image:GRASS FUTURES wxGUI display.png|Layer Manager and Map Display overview. Annotations show how to add raster layer, query, add legend.
Image:wxGUI_metadata_rinfo.png|Show raster map metadata by right click on layer</gallery></center>

* GRASS GIS has over [https://grass.osgeo.org/grass70/manuals/full_index.html 500 different modules] in the core distribution and over [https://grass.osgeo.org/grass70/manuals/addons/ 230 addon modules]
<center>
{| class="wikitable"
|-
! Prefix !! Function !! Example
|-
| r.* || raster processing || ''{{cmd|r.mapcalc}}'': map algebra
|-
| v.* || vector processing || ''{{cmd|v.clean}}'': topological cleaning
|-
| i.* || imagery processing || ''{{cmd|i.segment}}'': object recognition
|-
| db.* || database management || ''{{cmd|db.select}}'': select values from table
|-
| r3.* || 3D raster processing || ''{{cmd|r3.stats}}'': 3D raster statistics
|-
| t.* || temporal data processing || ''{{cmd|t.rast.aggregate}}'': temporal aggregation
|-
| g.* || general data management || ''{{cmd|g.rename}}'': renames map
|-
| d.* || display ||''{{cmd|d.rast}}'': display raster map
|}</center>
* GRASS modules have GUI and command line interface. In this workshop we use commands to describe the workflow, but we can use both GUI and command line depending on personal preference. Look how {{cmd|wxGUI.modules|version=71|desc=GUI and command line interface}} represent the same tool. ''Task:'' compute aspect (orientation) from provided digital elevation model using module {{cmd|r.slope.aspect}} using both module dialog and command line.
* How to find modules? Modules are organized by their functionality in wxGUI menu, or we can search for them in Search modules tab. If we already know which module to use, we can just type it in the wxGUI command console. <center><gallery perrow=3 widths=380 heights=190>Image:wxGUI_menu_rinfo.png|Modules can be found in wxGUI menu
Image:wxGUI_module_search.png|You can search modules by name, description or keywords in ''Search modules'' tab
Image:wxGUI_console_completion.png|By typing prefix r. we make a list of modules starting with that prefix to show up.</gallery></center>


* {{cmd|g.region|desc=Computational region}} - an important raster concept
** defined by region extent and raster resolution
** applies to all raster operations
** persists between GRASS session, can be different for different mapsets
** advantages: keeps your results consistent, avoid clipping, for computationally demanding tasks set region to smaller extent, check your result is good and then set the computational region to the entire study area and rerun analysis
** run <code>g.region -p</code> or in menu ''Settings'' - ''Region'' - ''Display region'' to see current region settings
[[File:WxGUI set region.png|700px|thumb|center|Simple ways to set computational region from GUI. On the left, set region to match raster map. On the right, select the highlighted option and then set region by drawing rectangle.]]

* GRASS 3D view

= Modeling with FUTURES =
== Initial steps and data preparation ==
First we will set the computational region of our analyses to an extent covering our study area and aligned with our base landuse rasters:
<source lang="bash">g.region raster=landuse_2011 -p</source>

We will derive urbanized areas from NLCD dataset for year 1992, 2001 and 2011
by extracting categories category 21 - 24 into a new binary map where developed is 1,
undeveloped 0 and NULL (no data) is area unsuitable for development (water, wetlands, protected areas).
First we will convert protected areas from vector to raster. We set
NULLs to zeros (for simpler raster algebra expression in the next step) using {{cmd|r.null}}:

<source lang="bash">
v.to.rast input=protected_areas output=protected_areas use=val
r.null map=protected_areas null=0
</source>

And then create rasters of developed/undeveloped areas using raster algebra:

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.mapcalc "urban_1992 = if(landuse_1992 >= 21 && landuse_1992 <= 24, 1, if(landuse_1992 == 11 || landuse_1992 >= 90 || protected_areas, null(), 0))"
r.mapcalc "urban_2001 = if(landuse_2001 >= 21 && landuse_2001 <= 24, 1, if(landuse_2001 == 11 || landuse_2001 >= 90 || protected_areas, null(), 0))"
r.mapcalc "urban_2011 = if(landuse_2011 >= 21 && landuse_2011 <= 24, 1, if(landuse_2011 == 11 || landuse_2011 >= 90 || protected_areas, null(), 0))"
</source>

We will convert vector counties to raster with the values of the FIPS attribute which links to population file:

<source lang="bash">
v.to.rast input=counties type=area use=attr attribute_column=FIPS output=counties
</source>

Before further steps, we will set our working directory so that the input population files and text files
we are going to create are saved in one directory and easily accessible.
You can do that from menu ''Settings'' → ''GRASS working environment'' → ''Change working directory''.
Select (or create) a directory and move there the downloaded files <tt>population_projection.csv</tt> and <tt>population_trend.csv</tt>.

== Potential submodel ==
Module {{AddonCmd|r.futures.potential}} implements POTENTIAL submodel as a part of FUTURES land change model. POTENTIAL is implemented using a set of coefficients that relate a selection of site suitability factors to the probability of a place becoming developed. This is implemented using the parameter table in combination with maps of those site suitability factors (mapped predictors). The coefficients are obtained by conducting multilevel logistic regression in R with package lme4 where the coefficients may vary by county. The best model is selected automatically using dredge function from package [https://cran.r-project.org/web/packages/MuMIn/index.html MuMIn].

First, we will derive couple of predictors.
=== Predictors ===
==== Slope ====
We will derive slope in degrees from digital elevation model using {{cmd|r.slope.aspect}} module:
<source lang="bash">r.slope.aspect elevation=elevation_30m slope=slope</source>

==== Distance from lakes/rivers ====
First we will extract [http://www.mrlc.gov/nlcd11_leg.php category ''Open Water''] from 2011 NLCD dataset:
<source lang="bash">
r.mapcalc "water = if(landuse_2011 == 11, 1, null())"
</source>

Then we compute the distance to water with module {{cmd|r.grow.distance}} and set color table to shades of blue:
<source lang="bash">
r.grow.distance input=water distance=dist_to_water
r.colors -n map=dist_to_water color=blues
</source>

==== Distance from protected areas ====
We will use raster protected of protected areas we already created, but we will set NULL values to zero.
We compute the distance to protected areas with module {{cmd|r.grow.distance}} and set color table from green to red:
<source lang="bash">
r.null map=protected_areas setnull=0
r.grow.distance input=protected_areas distance=dist_to_protected
r.colors map=dist_to_protected color=gyr
</source>

==== Forests ====
We will smooth the transition between forest and other land use, see NLCD [http://www.mrlc.gov/nlcd11_leg.php category ''Open Water'']:
<source lang="bash">
r.mapcalc "forest = if(landuse_2011 >= 41 && landuse_2011 <= 43, 1, 0)"
r.neighbors -c input=forest output=forest_smooth size=15 method=average
r.colors map=forest_smooth color=ndvi
</source>

==== Travel time to cities ====
Here we will compute travel time to cities (with population > 5000)
as cumulative cost distance where cost is defined as travel time on roads.
First we specify the speed on different types of roads.
We copy the roads raster into our mapset so that we can change it
by adding a new attribute field <tt>speed</tt>. Then we assign speed values (km/h) based on the type of road:

<source lang="bash">
g.copy vector=roads,myroads
v.db.addcolumn map=myroads columns="speed double precision"
v.db.update map=myroads column=speed value=50 where="MTFCC = 'S1400'"
v.db.update map=myroads column=speed value=100 where="MTFCC IN ('S1100', 'S1200')"
</source>

Now we rasterize the selected road types using the speed values from the attribute table as raster values.

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
v.to.rast input=myroads type=line where="MTFCC IN ('S1100', 'S1200', 'S1400')" output=roads_speed use=attr attribute_column=speed
</source>

We set the rest of the area to low speed and recompute the speed as time to travel through a 30m cell in minutes:

<source lang="bash">
r.null map=roads_speed null=5
r.mapcalc "roads_travel_time = 1.8 / roads_speed"
</source>

Finally we compute the travel time to larger cities using {{cmd|r.cost}}:

<source lang="bash">
r.cost input=roads_travel_time output=travel_time_cities start_points=cities
r.colors map=travel_time_cities color=byr
</source>

==== Road density ====
We will rasterize roads and use moving window analysis ({{cmd|r.neighbors}}) to compute road density:

<source lang="bash">
v.to.rast input=roads output=roads use=val type=line
r.null map=roads null=0
r.neighbors -c input=roads output=road_dens size=25 method=average
</source>

==== Distance to interchanges ====

We will consider TIGER roads of type <tt>Ramp</tt> as interchanges, rasterize them and compute euclidean distance to them:

<source lang="bash">
v.to.rast input=roads type=line where="MTFCC = 'S1630'" output=interchanges use=val
r.grow.distance -m input=interchanges distance=dist_interchanges
</source>

=== Development pressure ===

We compute development pressure with {{AddonCmd|r.futures.devpressure}}. Development pressure is a predictor based on number of neighboring developed cells within search distance, weighted by distance. The development pressure variable plays a special role in the model, allowing for a feedback between predicted change and change in subsequent steps.

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.devpressure -n input=urban_2011 output=devpressure_2 method=gravity size=7 gamma=2 scaling_factor=10
r.futures.devpressure -n input=urban_2011 output=devpressure_1 method=gravity size=10 gamma=1 scaling_factor=1
r.futures.devpressure -n input=urban_2011 output=devpressure_0_5 method=gravity size=30 gamma=0.5 scaling_factor=0.1
</source>

When gamma increases, development influence decreases more rapidly with distance.
Size is half the size of the moving window. When gamma is low, local development influences more distant places.
We will derive 3 layers with different gamma and size parameters for the potential statistical model.

=== Rescaling variables ===

First we will look at the ranges of our predictor variables by running a short Python code snippet in Python shell:

<source lang="python" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
for name in ['slope', 'dist_to_water', 'dist_to_protected', 'forest_smooth', 'travel_time_cities', 'road_dens', 'dist_interchanges', 'devpressure_0_5', 'devpressure_1']:
minmax = grass.raster_info(name)
print name, minmax['min'], minmax['max']
</source>

We will rescale some of our input variables:

<source lang="bash">
r.mapcalc "dist_to_water_km = dist_to_water / 1000"
r.mapcalc "dist_to_protected_km = dist_to_protected / 1000"
r.mapcalc "dist_interchanges_km = dist_interchanges / 1000"
r.mapcalc "road_dens_perc = road_dens * 100"
r.mapcalc "forest_smooth_perc = forest_smooth * 100"
</source>

=== Sampling ===
To sample only in the analyzed counties, we will clip development layer:

<source lang="bash">
r.mapcalc "urban_change_01_11 = if(urban_2011 == 1, if(urban_2001 == 0, 1, null()), 0)"
r.mapcalc "urban_change_clip = if(counties, urban_change_01_11)"
</source>

To estimate the number of sampling points, we can use {{cmd|r.report}} to report number of developed/undeveloped cells and their ratio.

<source lang="bash">
r.report map=urban_change_clip units=h,c,p
</source>

We will sample the predictors and the response variable with 5000 random points in undeveloped areas and 1000 points in developed area:

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.sample.category input=urban_change_clip output=sampling sampled=counties,devpressure_0_5,devpressure_1,devpressure_2,slope,road_dens_perc,forest_smooth_perc,dist_to_water_km,dist_to_protected_km,dist_interchanges_km,travel_time_cities npoints=5000,1000
</source>

The attribute table can be exported as CSV file (not necessary step):

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
v.db.select map=sampling columns=urban_change_clip,counties,devpressure_0_5,devpressure_1,slope,road_dens_perc,forest_smooth_perc,dist_to_water_km,dist_to_protected_km,dist_interchanges_km,travel_time_cities separator=comma file=samples.csv
</source>

=== Development potential ===
Now we find best model for predicting urbanization using {{AddonCmd|r.futures.potential}} which wraps an R script.

We can run R [http://www.inside-r.org/packages/cran/MuMIn/docs/dredge dredge] function to find "best" model. We can specify minimum and maximum number of predictors the final model should use.
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.potential -d input=sampling output=potential.csv columns=devpressure_1,slope,road_dens_perc,forest_smooth_perc,dist_to_water_km,dist_to_protected_km,dist_interchanges_km,travel_time_cities developed_column=urban_change_clip subregions_column=counties min_variables=4
</source>

Also, we can play with different combinations of predictors, for example:

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.potential input=sampling output=potential.csv columns=devpressure_2,road_dens_perc,slope,dist_interchanges_km,dist_to_water_km developed_column=urban_change_clip subregions_column=counties --o
r.futures.potential input=sampling output=potential.csv columns=devpressure_1,road_dens_perc,slope,dist_interchanges_km,dist_to_water_km developed_column=urban_change_clip subregions_column=counties --o
...
</source>

You can then open the output file <tt>potential.csv</tt>, which is a CSV file with tabs as separators.

For this tutorial, the final potential is created with:
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.potential input=sampling output=potential.csv columns=devpressure_2,road_dens_perc,slope,dist_interchanges_km,dist_to_water_km developed_column=urban_change_clip subregions_column=counties --o
</source>

We can now visualize the suitability surface using module {{AddonCmd|r.futures.potsurface}}. It creates initial development potential (suitability) raster from predictors and model coefficients and serves only for evaluating development potential model. The values of the resulting raster range from 0 to 1.

<source lang="bash">
r.futures.potsurface input=potential.csv subregions=counties output=suitability
r.colors map=suitability color=byr
</source>

== Demand submodel ==
First we will mask out roads so that they don't influence into per capita land demand relation.
<source lang="bash">
v.to.rast input=roads type=line output=roads_mask use=val
r.mask roads_mask -i
</source>

We will use {{AddonCmd|r.futures.demand}} which derives the population vs. development relation. The relation can be linear/logarithmic/logarithmic2/exponential/exponential approach.
Look for examples of the different relations in the manual.

* linear: y = A + Bx
* logarithmic: y = A + Bln(x)
* logarithmic2: y = A + B * ln(x - C)        (requires SciPy)
* exponential: y = Ae^(BX)
* exp_approach: y = (1 - e^(-A(x - B))) + C        (requires SciPy)

The format of the input population CSV files is described in the manual. It is important to have synchronized categories of subregions and the column headers of the CSV files (in our case FIPS number). How to simply generate the list of years (for which demand is computed) is described in {{AddonCmd|r.futures.demand}} manual, for example run this in Python console:

<source lang="python">
','.join([str(i) for i in range(2011, 2036)])
</source>

Then we can create the DEMAND file:
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.demand development=urban_1992,urban_2001,urban_2011 subregions=counties observed_population=population_trend.csv projected_population=population_projection.csv simulation_times=2011,2012,2013,2014,2015,2016,2017,2018,2019,2020,2021,2022,2023,2024,2025,2026,2027,2028,2029,2030,2031,2032,2033,2034,2035 plot=plot_demand.pdf demand=demand.csv separator=comma
</source>

In your current working directory, you should find files <tt>plot_demand.png</tt> and <tt>demand.csv</tt>.

If you have SciPy installed, you can experiment with other methods for fitting the functions:
<source lang="bash">
r.futures.demand ... method=logarithmic2
r.futures.demand ... method=exp_approach
</source>
If necessary, you can create a set of demand files produced by fitting each method separately and
then pick for each county the method which seems best and manually create a new demand file.

When you are finished, remove the mask as it is not needed for the next steps.
<source lang="bash">
r.mask -r
</source>

== Patch calibration ==
Patch calibration can be a very time consuming computation.
Therefore we select only one county (Buncombe):

<source lang="bash">
v.to.rast input=counties type=area where="FIPS == 37021" use=attr attribute_column=FIPS output=calib_county
g.region raster=calib_county zoom=calib_county
</source>
to derive patches of new development by comparing historical and latest development.
We can keep only patches with minimum size 2 cells (1800 = 2 x 30 x 30 m).

<source lang="bash">
r.futures.calib development_start=urban_1992 development_end=urban_2011 subregions=counties patch_sizes=patches.txt patch_threshold=1800 -l
</source>
We obtained a file <tt>patches.txt</tt> (used later in the PGA) - a patch size distribution file - containing sizes of all found patches.

We can look at the distribution of the patch sizes:

<source lang="python">
from matplotlib import pyplot as plt
with open('patches.txt') as f:
patches = [int(patch) for patch in f.readlines()]
plt.hist(patches, 2000)
plt.xlim(0,50)
plt.show()
</source>

At this point, we start the calibration to get best parameters of patch shape
(for this tutorial, this step can be skipped and the suggested parameters are used).

<source lang="bash"
style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.calib development_start=urban_1992 development_end=urban_2011 subregions=calib_county patch_sizes=patches.txt calibration_results=calib.csv patch_threshold=1800 repeat=5 compactness_mean=0.1,0.3,0.5,0.7,0.9 compactness_range=0.05 discount_factor=0.1,0.3,0.5,0.7,0.9 predictors=road_dens_perc,forest_smooth_perc,dist_to_protected_km demand=demand.csv devpot_params=potential.csv num_neighbors=4 seed_search=2 development_pressure=devpressure_0_5 development_pressure_approach=gravity n_dev_neighbourhood=30 gamma=0.5 scaling_factor=0.1
</source>

== FUTURES simulation ==
We will switch back to our previous region:
<source lang="bash">
g.region raster=landuse_2011 -p
</source>

Now we have all the inputs necessary for running {{AddonCmd|r.futures.pga}}:

The entire command is here:
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.pga subregions=counties developed=urban_2011 predictors=slope,forest_smooth_perc,dist_interchanges_km,travel_time_cities devpot_params=potential.csv development_pressure=devpressure_1 n_dev_neighbourhood=10 development_pressure_approach=gravity gamma=1 scaling_factor=1 demand=demand.csv discount_factor=0.3 compactness_mean=0.2 compactness_range=0.1 patch_sizes=patches.txt num_neighbors=4 seed_search=2 random_seed=1 output=final output_series=final
</source>

=== Quick description ===
The command parameters and their values:
* raster map of counties with their categories
<code>
... subregions=counties ...
</code>

* raster of developed (1), undeveloped (0) and NULLs for undevelopable areas
<code>
... developed=urban_2011 ...
</code>

* predictors selected with {{AddonCmd|r.futures.potential}} and their coefficients in a <tt>potential.csv</tt> file. The order of predictors must match the order in the file and the categories of the counties must match raster <tt>counties</tt>.
<code>
... predictors=slope,forest_smooth_perc,dist_interchanges_km,travel_time_cities devpot_params=potential.csv ...
</code>

* initial development pressure computed by {{AddonCmd|r.futures.devpressure}}, it's important to set here the same parameters
<code>
... development_pressure=devpressure_1 n_dev_neighbourhood=10 development_pressure_approach=gravity gamma=1 scaling_factor=1 ...
</code>

* per capita land demand computed by {{AddonCmd|r.futures.demand}}, the categories of the counties must match raster <tt>counties</tt>.
<code>
... demand=demand.csv ...
</code>

* patch parameters from the calibration step
<code>
... discount_factor=0.3 compactness_mean=0.4 compactness_range=0.08 patch_sizes=patches.txt ...
</code>

* recommended parameters for patch growing algorithm
<code>
... num_neighbors=4 seed_search=2 ...
</code>

* set random seed for repeatable results or set flag <tt>-s</tt> to generate seed automatically
<code>
... random_seed=1 ...
</code>

* specify final output map and optionally basename for intermediate raster maps
<code>
output=final output_series=final
</code>

== Scenarios ==
Scenarios involving policies that encourage infill versus sprawl can be explored using the <tt>incentive_power</tt> parameter of {{AddonCmd|r.futures.pga}},
which uses a power function to transform the evenness of the probability gradient in POTENTIAL. You can change the power to a number between 0.25 and 4 to test urban sprawl/infill scenarios.
Higher power leads to infill behavior, lower power to urban sprawl.

== Postprocessing ==

Follow a [[Creating_animation_from_FUTURES_output_in_GRASS_GIS| tutorial how to make an animation from the results]].

= GRASS GIS Python API =

[[Category: Tutorial]]
[[Category: FUTURES]]
[[Category: Urban]]

Workshop on urban growth modeling with FUTURES

2016-03-22T17:51:12Z

⚠️Dbvanber: /* Initial steps and data preparation */

{{ToModify}}
= Workshop introduction =
r.futures.* is an implementation of the '''FUT'''ure '''U'''rban-'''R'''egional '''E'''nvironment '''S'''imulation (FUTURES)[1] which is a model for multilevel simulations of emerging urban-rural landscape structure. FUTURES produces regional projections of landscape patterns using coupled submodels that integrate nonstationary drivers of land change: per capita demand (DEMAND submodel), site suitability (POTENTIAL submodel), and the spatial structure of conversion events (PGA submodel).

[1] Meentemeyer, R. K., Tang, W., Dorning, M. A., Vogler, J. B., Cunniffe, N. J., & Shoemaker, D. A. (2013). [http://www.tandfonline.com/doi/abs/10.1080/00045608.2012.707591 FUTURES: multilevel simulations of emerging urban-rural landscape structure using a stochastic patch-growing algorithm.] Annals of the Association of American Geographers, 103(4), 785-807

== Software ==
There are a number of software requirements to run FUTURES that will need to be download and installed. Required software includes:
* GRASS GIS 7
* addons
** {{AddonCmd|r.futures.pga}}
** {{AddonCmd|r.futures.potential}}
** {{AddonCmd|r.futures.potsurface}}
** {{AddonCmd|r.futures.demand}}
** {{AddonCmd|r.futures.devpressure}}
** {{AddonCmd|r.sample.category}}
* R (≥ 3.0.2) - needed for {{AddonCmd|r.futures.potential}} with packages:
**MuMIn, lme4, optparse, rgrass7
* SciPy - useful for {{AddonCmd|r.futures.demand}}

=== Installation ===
We use the R statistical software for our calculation of site suitability (i.e. development potential) in FUTURES. R is a free software environment for statistical computing and graphics. If you don't have R, or you have older an version, please download and install the software from [http://archive.linux.duke.edu/cran/ install R] and be sure to additionally add these required packages:
<pre>
install.packages(c("MuMIn", "lme4", "optparse", "rgrass7"))
</pre>

==== MS Windows ====
We will be using GRASS GIS 7.0.3 that can be found here in the [https://trac.osgeo.org/osgeo4w/ OSGeo4W] package manager.
Please install the latest stable GRASS GIS 7 version and the SciPy Python package using the ''Advanced install'' option.
A guide with step by step screen shot instructions is available [https://docs.google.com/presentation/d/1yEGpriBne7RvjB35HI6GecNwO1P1y2nRGqDThqoNnCE/edit?usp=sharing here].

In order for GRASS to be able to find R executables, GRASS must be on the PATH variable. Follow this [solution] to make R accessible from GRASS permanently.
A simple but temporary solution is to open GRASS GIS and paste this in the black terminal:
<pre>
set PATH=%PATH%;C:\Program Files\R\R-3.0.2\bin
</pre>
This has to be repeated after restarting GRASS session.

==== Ubuntu Linux ====
Install GRASS GIS from packages:
<pre>
sudo add-apt-repository ppa:ubuntugis/ubuntugis-unstable
sudo apt-get update
sudo apt-get install grass
</pre>

== Workshop data ==
The data that we will be using for the workshop can be download here: [http://fatra.cnr.ncsu.edu/futures/futures_ncspm_Asheville.zip sample dataset]. Please place these layers in your local GRASS directory:
* digital elevation model ([http://nationalmap.gov/elevation.html NED])
* [http://www.mrlc.gov/ NLCD] 2001, 2011
* NLCD 1992/2001 Retrofit Land Cover Change Product
* transportation network ([http://www.census.gov/geo/maps-data/data/tiger-line.html TIGER])
* county boundaries ([http://www.census.gov/geo/maps-data/data/tiger-line.html TIGER])
* protected areas ([http://www.conservationgateway.org/ConservationByGeography/NorthAmerica/UnitedStates/edc/reportsdata/terrestrial/secured/Pages/default.aspx Secured Lands])
* cities as points (USGS)

In addition, download [http://fatra.cnr.ncsu.edu/futures/futures_Asheville_files.zip population information as text files]:
* county population past estimates and future projections ([https://www.osbm.nc.gov/demog/county-projections NC OSBM]) per county (nonspatial)

= GRASS GIS introduction =
There are many advantages to using the open source GRASS GIS platform, but for many that are more familiar with ARCGis and QGis, the setup and implementation of spatial tools in GRASS can be confusing. Here we provide an overview of the GRASS GIS project: [https://grass.osgeo.org grass.osgeo.org] that might be helpful to review if you are a first time users. For this exercise it's not necessary to have a full understanding of how to use GRASS. However, you will need to know how to place your data in the correct GRASS database directory and for this we provide step by step instructions.
* Overview of [https://grass.osgeo.org/grass71/manuals/grass_database.html GRASS database].
** ''GRASS database'': directory with Locations (projects)
** ''Location'': directory with Mapsets, defined by projection (spatial reference system)
** ''Mapset'': collection of maps
* Download the [http://fatra.cnr.ncsu.edu/futures/futures_ncspm_Asheville.zip workshop location]. Create (unless you already have it) a directory named <tt>grassdata</tt> (GRASS database) in your home folder (or Documents), unzip the downloaded data into this directory. You should have now Location <tt>futures_ncspm</tt> in <tt>grassdata</tt>.
* Launch GRASS and display raster, vector data, explore navigation, querying, adding legend, showing metadata
<center><gallery perrow=3 widths=500 heights=250>Image:GRASS FUTURES startup.png|GRASS GIS 7.0.3 startup dialog with downloaded Location and Mapsets for FUTURES workshop
Image:GRASS FUTURES wxGUI display.png|Layer Manager and Map Display overview. Annotations show how to add raster layer, query, add legend.
Image:wxGUI_metadata_rinfo.png|Show raster map metadata by right click on layer</gallery></center>

* GRASS GIS has over [https://grass.osgeo.org/grass70/manuals/full_index.html 500 different modules] in the core distribution and over [https://grass.osgeo.org/grass70/manuals/addons/ 230 addon modules]
<center>
{| class="wikitable"
|-
! Prefix !! Function !! Example
|-
| r.* || raster processing || ''{{cmd|r.mapcalc}}'': map algebra
|-
| v.* || vector processing || ''{{cmd|v.clean}}'': topological cleaning
|-
| i.* || imagery processing || ''{{cmd|i.segment}}'': object recognition
|-
| db.* || database management || ''{{cmd|db.select}}'': select values from table
|-
| r3.* || 3D raster processing || ''{{cmd|r3.stats}}'': 3D raster statistics
|-
| t.* || temporal data processing || ''{{cmd|t.rast.aggregate}}'': temporal aggregation
|-
| g.* || general data management || ''{{cmd|g.rename}}'': renames map
|-
| d.* || display ||''{{cmd|d.rast}}'': display raster map
|}</center>
* GRASS modules have GUI and command line interface. In this workshop we use commands to describe the workflow, but we can use both GUI and command line depending on personal preference. Look how {{cmd|wxGUI.modules|version=71|desc=GUI and command line interface}} represent the same tool. ''Task:'' compute aspect (orientation) from provided digital elevation model using module {{cmd|r.slope.aspect}} using both module dialog and command line.
* How to find modules? Modules are organized by their functionality in wxGUI menu, or we can search for them in Search modules tab. If we already know which module to use, we can just type it in the wxGUI command console. <center><gallery perrow=3 widths=380 heights=190>Image:wxGUI_menu_rinfo.png|Modules can be found in wxGUI menu
Image:wxGUI_module_search.png|You can search modules by name, description or keywords in ''Search modules'' tab
Image:wxGUI_console_completion.png|By typing prefix r. we make a list of modules starting with that prefix to show up.</gallery></center>


* {{cmd|g.region|desc=Computational region}} - an important raster concept
** defined by region extent and raster resolution
** applies to all raster operations
** persists between GRASS session, can be different for different mapsets
** advantages: keeps your results consistent, avoid clipping, for computationally demanding tasks set region to smaller extent, check your result is good and then set the computational region to the entire study area and rerun analysis
** run <code>g.region -p</code> or in menu ''Settings'' - ''Region'' - ''Display region'' to see current region settings
[[File:WxGUI set region.png|700px|thumb|center|Simple ways to set computational region from GUI. On the left, set region to match raster map. On the right, select the highlighted option and then set region by drawing rectangle.]]

* GRASS 3D view

= Modeling with FUTURES =
== Initial steps and data preparation ==
First we will set the computational region of our analyses to an extent covering our study area. This also ensures that all data layers (i.e. cells) are aligned with our base landuse rasters:
<source lang="bash">g.region raster=landuse_2011 -p</source>

We will derive urbanized areas from NLCD dataset for year 1992, 2001 and 2011
by extracting categories category 21 - 24 into a new binary map where developed is 1,
undeveloped 0 and NULL (no data) is area unsuitable for development (water, wetlands, protected areas).
First we will convert protected areas from vector to raster. We set
NULLs to zeros (for simpler raster algebra expression in the next step) using {{cmd|r.null}}:

<source lang="bash">
v.to.rast input=protected_areas output=protected_areas use=val
r.null map=protected_areas null=0
</source>

And then create rasters of developed/undeveloped areas using raster algebra:

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.mapcalc "urban_1992 = if(landuse_1992 >= 21 && landuse_1992 <= 24, 1, if(landuse_1992 == 11 || landuse_1992 >= 90 || protected_areas, null(), 0))"
r.mapcalc "urban_2001 = if(landuse_2001 >= 21 && landuse_2001 <= 24, 1, if(landuse_2001 == 11 || landuse_2001 >= 90 || protected_areas, null(), 0))"
r.mapcalc "urban_2011 = if(landuse_2011 >= 21 && landuse_2011 <= 24, 1, if(landuse_2011 == 11 || landuse_2011 >= 90 || protected_areas, null(), 0))"
</source>

We will convert vector counties to raster with the values of the FIPS attribute which links to population file:

<source lang="bash">
v.to.rast input=counties type=area use=attr attribute_column=FIPS output=counties
</source>

Before further steps, we will set our working directory so that the input population files and text files
we are going to create are saved in one directory and easily accessible.
You can do that from menu ''Settings'' → ''GRASS working environment'' → ''Change working directory''.
Select (or create) a directory and move there the downloaded files <tt>population_projection.csv</tt> and <tt>population_trend.csv</tt>.

== Potential submodel ==
Module {{AddonCmd|r.futures.potential}} implements POTENTIAL submodel as a part of FUTURES land change model. POTENTIAL is implemented using a set of coefficients that relate a selection of site suitability factors to the probability of a place becoming developed. This is implemented using the parameter table in combination with maps of those site suitability factors (mapped predictors). The coefficients are obtained by conducting multilevel logistic regression in R with package lme4 where the coefficients may vary by county. The best model is selected automatically using dredge function from package [https://cran.r-project.org/web/packages/MuMIn/index.html MuMIn].

First, we will derive couple of predictors.
=== Predictors ===
==== Slope ====
We will derive slope in degrees from digital elevation model using {{cmd|r.slope.aspect}} module:
<source lang="bash">r.slope.aspect elevation=elevation_30m slope=slope</source>

==== Distance from lakes/rivers ====
First we will extract [http://www.mrlc.gov/nlcd11_leg.php category ''Open Water''] from 2011 NLCD dataset:
<source lang="bash">
r.mapcalc "water = if(landuse_2011 == 11, 1, null())"
</source>

Then we compute the distance to water with module {{cmd|r.grow.distance}} and set color table to shades of blue:
<source lang="bash">
r.grow.distance input=water distance=dist_to_water
r.colors -n map=dist_to_water color=blues
</source>

==== Distance from protected areas ====
We will use raster protected of protected areas we already created, but we will set NULL values to zero.
We compute the distance to protected areas with module {{cmd|r.grow.distance}} and set color table from green to red:
<source lang="bash">
r.null map=protected_areas setnull=0
r.grow.distance input=protected_areas distance=dist_to_protected
r.colors map=dist_to_protected color=gyr
</source>

==== Forests ====
We will smooth the transition between forest and other land use, see NLCD [http://www.mrlc.gov/nlcd11_leg.php category ''Open Water'']:
<source lang="bash">
r.mapcalc "forest = if(landuse_2011 >= 41 && landuse_2011 <= 43, 1, 0)"
r.neighbors -c input=forest output=forest_smooth size=15 method=average
r.colors map=forest_smooth color=ndvi
</source>

==== Travel time to cities ====
Here we will compute travel time to cities (with population > 5000)
as cumulative cost distance where cost is defined as travel time on roads.
First we specify the speed on different types of roads.
We copy the roads raster into our mapset so that we can change it
by adding a new attribute field <tt>speed</tt>. Then we assign speed values (km/h) based on the type of road:

<source lang="bash">
g.copy vector=roads,myroads
v.db.addcolumn map=myroads columns="speed double precision"
v.db.update map=myroads column=speed value=50 where="MTFCC = 'S1400'"
v.db.update map=myroads column=speed value=100 where="MTFCC IN ('S1100', 'S1200')"
</source>

Now we rasterize the selected road types using the speed values from the attribute table as raster values.

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
v.to.rast input=myroads type=line where="MTFCC IN ('S1100', 'S1200', 'S1400')" output=roads_speed use=attr attribute_column=speed
</source>

We set the rest of the area to low speed and recompute the speed as time to travel through a 30m cell in minutes:

<source lang="bash">
r.null map=roads_speed null=5
r.mapcalc "roads_travel_time = 1.8 / roads_speed"
</source>

Finally we compute the travel time to larger cities using {{cmd|r.cost}}:

<source lang="bash">
r.cost input=roads_travel_time output=travel_time_cities start_points=cities
r.colors map=travel_time_cities color=byr
</source>

==== Road density ====
We will rasterize roads and use moving window analysis ({{cmd|r.neighbors}}) to compute road density:

<source lang="bash">
v.to.rast input=roads output=roads use=val type=line
r.null map=roads null=0
r.neighbors -c input=roads output=road_dens size=25 method=average
</source>

==== Distance to interchanges ====

We will consider TIGER roads of type <tt>Ramp</tt> as interchanges, rasterize them and compute euclidean distance to them:

<source lang="bash">
v.to.rast input=roads type=line where="MTFCC = 'S1630'" output=interchanges use=val
r.grow.distance -m input=interchanges distance=dist_interchanges
</source>

=== Development pressure ===

We compute development pressure with {{AddonCmd|r.futures.devpressure}}. Development pressure is a predictor based on number of neighboring developed cells within search distance, weighted by distance. The development pressure variable plays a special role in the model, allowing for a feedback between predicted change and change in subsequent steps.

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.devpressure -n input=urban_2011 output=devpressure_2 method=gravity size=7 gamma=2 scaling_factor=10
r.futures.devpressure -n input=urban_2011 output=devpressure_1 method=gravity size=10 gamma=1 scaling_factor=1
r.futures.devpressure -n input=urban_2011 output=devpressure_0_5 method=gravity size=30 gamma=0.5 scaling_factor=0.1
</source>

When gamma increases, development influence decreases more rapidly with distance.
Size is half the size of the moving window. When gamma is low, local development influences more distant places.
We will derive 3 layers with different gamma and size parameters for the potential statistical model.

=== Rescaling variables ===

First we will look at the ranges of our predictor variables by running a short Python code snippet in Python shell:

<source lang="python" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
for name in ['slope', 'dist_to_water', 'dist_to_protected', 'forest_smooth', 'travel_time_cities', 'road_dens', 'dist_interchanges', 'devpressure_0_5', 'devpressure_1']:
minmax = grass.raster_info(name)
print name, minmax['min'], minmax['max']
</source>

We will rescale some of our input variables:

<source lang="bash">
r.mapcalc "dist_to_water_km = dist_to_water / 1000"
r.mapcalc "dist_to_protected_km = dist_to_protected / 1000"
r.mapcalc "dist_interchanges_km = dist_interchanges / 1000"
r.mapcalc "road_dens_perc = road_dens * 100"
r.mapcalc "forest_smooth_perc = forest_smooth * 100"
</source>

=== Sampling ===
To sample only in the analyzed counties, we will clip development layer:

<source lang="bash">
r.mapcalc "urban_change_01_11 = if(urban_2011 == 1, if(urban_2001 == 0, 1, null()), 0)"
r.mapcalc "urban_change_clip = if(counties, urban_change_01_11)"
</source>

To estimate the number of sampling points, we can use {{cmd|r.report}} to report number of developed/undeveloped cells and their ratio.

<source lang="bash">
r.report map=urban_change_clip units=h,c,p
</source>

We will sample the predictors and the response variable with 5000 random points in undeveloped areas and 1000 points in developed area:

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.sample.category input=urban_change_clip output=sampling sampled=counties,devpressure_0_5,devpressure_1,devpressure_2,slope,road_dens_perc,forest_smooth_perc,dist_to_water_km,dist_to_protected_km,dist_interchanges_km,travel_time_cities npoints=5000,1000
</source>

The attribute table can be exported as CSV file (not necessary step):

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
v.db.select map=sampling columns=urban_change_clip,counties,devpressure_0_5,devpressure_1,slope,road_dens_perc,forest_smooth_perc,dist_to_water_km,dist_to_protected_km,dist_interchanges_km,travel_time_cities separator=comma file=samples.csv
</source>

=== Development potential ===
Now we find best model for predicting urbanization using {{AddonCmd|r.futures.potential}} which wraps an R script.

We can run R [http://www.inside-r.org/packages/cran/MuMIn/docs/dredge dredge] function to find "best" model. We can specify minimum and maximum number of predictors the final model should use.
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.potential -d input=sampling output=potential.csv columns=devpressure_1,slope,road_dens_perc,forest_smooth_perc,dist_to_water_km,dist_to_protected_km,dist_interchanges_km,travel_time_cities developed_column=urban_change_clip subregions_column=counties min_variables=4
</source>

Also, we can play with different combinations of predictors, for example:

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.potential input=sampling output=potential.csv columns=devpressure_2,road_dens_perc,slope,dist_interchanges_km,dist_to_water_km developed_column=urban_change_clip subregions_column=counties --o
r.futures.potential input=sampling output=potential.csv columns=devpressure_1,road_dens_perc,slope,dist_interchanges_km,dist_to_water_km developed_column=urban_change_clip subregions_column=counties --o
...
</source>

You can then open the output file <tt>potential.csv</tt>, which is a CSV file with tabs as separators.

For this tutorial, the final potential is created with:
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.potential input=sampling output=potential.csv columns=devpressure_2,road_dens_perc,slope,dist_interchanges_km,dist_to_water_km developed_column=urban_change_clip subregions_column=counties --o
</source>

We can now visualize the suitability surface using module {{AddonCmd|r.futures.potsurface}}. It creates initial development potential (suitability) raster from predictors and model coefficients and serves only for evaluating development potential model. The values of the resulting raster range from 0 to 1.

<source lang="bash">
r.futures.potsurface input=potential.csv subregions=counties output=suitability
r.colors map=suitability color=byr
</source>

== Demand submodel ==
First we will mask out roads so that they don't influence into per capita land demand relation.
<source lang="bash">
v.to.rast input=roads type=line output=roads_mask use=val
r.mask roads_mask -i
</source>

We will use {{AddonCmd|r.futures.demand}} which derives the population vs. development relation. The relation can be linear/logarithmic/logarithmic2/exponential/exponential approach.
Look for examples of the different relations in the manual.

* linear: y = A + Bx
* logarithmic: y = A + Bln(x)
* logarithmic2: y = A + B * ln(x - C)        (requires SciPy)
* exponential: y = Ae^(BX)
* exp_approach: y = (1 - e^(-A(x - B))) + C        (requires SciPy)

The format of the input population CSV files is described in the manual. It is important to have synchronized categories of subregions and the column headers of the CSV files (in our case FIPS number). How to simply generate the list of years (for which demand is computed) is described in {{AddonCmd|r.futures.demand}} manual, for example run this in Python console:

<source lang="python">
','.join([str(i) for i in range(2011, 2036)])
</source>

Then we can create the DEMAND file:
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.demand development=urban_1992,urban_2001,urban_2011 subregions=counties observed_population=population_trend.csv projected_population=population_projection.csv simulation_times=2011,2012,2013,2014,2015,2016,2017,2018,2019,2020,2021,2022,2023,2024,2025,2026,2027,2028,2029,2030,2031,2032,2033,2034,2035 plot=plot_demand.pdf demand=demand.csv separator=comma
</source>

In your current working directory, you should find files <tt>plot_demand.png</tt> and <tt>demand.csv</tt>.

If you have SciPy installed, you can experiment with other methods for fitting the functions:
<source lang="bash">
r.futures.demand ... method=logarithmic2
r.futures.demand ... method=exp_approach
</source>
If necessary, you can create a set of demand files produced by fitting each method separately and
then pick for each county the method which seems best and manually create a new demand file.

When you are finished, remove the mask as it is not needed for the next steps.
<source lang="bash">
r.mask -r
</source>

== Patch calibration ==
Patch calibration can be a very time consuming computation.
Therefore we select only one county (Buncombe):

<source lang="bash">
v.to.rast input=counties type=area where="FIPS == 37021" use=attr attribute_column=FIPS output=calib_county
g.region raster=calib_county zoom=calib_county
</source>
to derive patches of new development by comparing historical and latest development.
We can keep only patches with minimum size 2 cells (1800 = 2 x 30 x 30 m).

<source lang="bash">
r.futures.calib development_start=urban_1992 development_end=urban_2011 subregions=counties patch_sizes=patches.txt patch_threshold=1800 -l
</source>
We obtained a file <tt>patches.txt</tt> (used later in the PGA) - a patch size distribution file - containing sizes of all found patches.

We can look at the distribution of the patch sizes:

<source lang="python">
from matplotlib import pyplot as plt
with open('patches.txt') as f:
patches = [int(patch) for patch in f.readlines()]
plt.hist(patches, 2000)
plt.xlim(0,50)
plt.show()
</source>

At this point, we start the calibration to get best parameters of patch shape
(for this tutorial, this step can be skipped and the suggested parameters are used).

<source lang="bash"
style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.calib development_start=urban_1992 development_end=urban_2011 subregions=calib_county patch_sizes=patches.txt calibration_results=calib.csv patch_threshold=1800 repeat=5 compactness_mean=0.1,0.3,0.5,0.7,0.9 compactness_range=0.05 discount_factor=0.1,0.3,0.5,0.7,0.9 predictors=road_dens_perc,forest_smooth_perc,dist_to_protected_km demand=demand.csv devpot_params=potential.csv num_neighbors=4 seed_search=2 development_pressure=devpressure_0_5 development_pressure_approach=gravity n_dev_neighbourhood=30 gamma=0.5 scaling_factor=0.1
</source>

== FUTURES simulation ==
We will switch back to our previous region:
<source lang="bash">
g.region raster=landuse_2011 -p
</source>

Now we have all the inputs necessary for running {{AddonCmd|r.futures.pga}}:

The entire command is here:
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.pga subregions=counties developed=urban_2011 predictors=slope,forest_smooth_perc,dist_interchanges_km,travel_time_cities devpot_params=potential.csv development_pressure=devpressure_1 n_dev_neighbourhood=10 development_pressure_approach=gravity gamma=1 scaling_factor=1 demand=demand.csv discount_factor=0.3 compactness_mean=0.2 compactness_range=0.1 patch_sizes=patches.txt num_neighbors=4 seed_search=2 random_seed=1 output=final output_series=final
</source>

=== Quick description ===
The command parameters and their values:
* raster map of counties with their categories
<code>
... subregions=counties ...
</code>

* raster of developed (1), undeveloped (0) and NULLs for undevelopable areas
<code>
... developed=urban_2011 ...
</code>

* predictors selected with {{AddonCmd|r.futures.potential}} and their coefficients in a <tt>potential.csv</tt> file. The order of predictors must match the order in the file and the categories of the counties must match raster <tt>counties</tt>.
<code>
... predictors=slope,forest_smooth_perc,dist_interchanges_km,travel_time_cities devpot_params=potential.csv ...
</code>

* initial development pressure computed by {{AddonCmd|r.futures.devpressure}}, it's important to set here the same parameters
<code>
... development_pressure=devpressure_1 n_dev_neighbourhood=10 development_pressure_approach=gravity gamma=1 scaling_factor=1 ...
</code>

* per capita land demand computed by {{AddonCmd|r.futures.demand}}, the categories of the counties must match raster <tt>counties</tt>.
<code>
... demand=demand.csv ...
</code>

* patch parameters from the calibration step
<code>
... discount_factor=0.3 compactness_mean=0.4 compactness_range=0.08 patch_sizes=patches.txt ...
</code>

* recommended parameters for patch growing algorithm
<code>
... num_neighbors=4 seed_search=2 ...
</code>

* set random seed for repeatable results or set flag <tt>-s</tt> to generate seed automatically
<code>
... random_seed=1 ...
</code>

* specify final output map and optionally basename for intermediate raster maps
<code>
output=final output_series=final
</code>

== Scenarios ==
Scenarios involving policies that encourage infill versus sprawl can be explored using the <tt>incentive_power</tt> parameter of {{AddonCmd|r.futures.pga}},
which uses a power function to transform the evenness of the probability gradient in POTENTIAL. You can change the power to a number between 0.25 and 4 to test urban sprawl/infill scenarios.
Higher power leads to infill behavior, lower power to urban sprawl.

== Postprocessing ==

Follow a [[Creating_animation_from_FUTURES_output_in_GRASS_GIS| tutorial how to make an animation from the results]].

= GRASS GIS Python API =

[[Category: Tutorial]]
[[Category: FUTURES]]
[[Category: Urban]]

Workshop on urban growth modeling with FUTURES

2016-03-22T17:04:01Z

⚠️Dbvanber: /* GRASS GIS introduction */

{{ToModify}}
= Workshop introduction =
r.futures.* is an implementation of the '''FUT'''ure '''U'''rban-'''R'''egional '''E'''nvironment '''S'''imulation (FUTURES)[1] which is a model for multilevel simulations of emerging urban-rural landscape structure. FUTURES produces regional projections of landscape patterns using coupled submodels that integrate nonstationary drivers of land change: per capita demand (DEMAND submodel), site suitability (POTENTIAL submodel), and the spatial structure of conversion events (PGA submodel).

[1] Meentemeyer, R. K., Tang, W., Dorning, M. A., Vogler, J. B., Cunniffe, N. J., & Shoemaker, D. A. (2013). [http://www.tandfonline.com/doi/abs/10.1080/00045608.2012.707591 FUTURES: multilevel simulations of emerging urban-rural landscape structure using a stochastic patch-growing algorithm.] Annals of the Association of American Geographers, 103(4), 785-807

== Software ==
There are a number of software requirements to run FUTURES that will need to be download and installed. Required software includes:
* GRASS GIS 7
* addons
** {{AddonCmd|r.futures.pga}}
** {{AddonCmd|r.futures.potential}}
** {{AddonCmd|r.futures.potsurface}}
** {{AddonCmd|r.futures.demand}}
** {{AddonCmd|r.futures.devpressure}}
** {{AddonCmd|r.sample.category}}
* R (≥ 3.0.2) - needed for {{AddonCmd|r.futures.potential}} with packages:
**MuMIn, lme4, optparse, rgrass7
* SciPy - useful for {{AddonCmd|r.futures.demand}}

=== Installation ===
We use the R statistical software for our calculation of site suitability (i.e. development potential) in FUTURES. R is a free software environment for statistical computing and graphics. If you don't have R, or you have older an version, please download and install the software from [http://archive.linux.duke.edu/cran/ install R] and be sure to additionally add these required packages:
<pre>
install.packages(c("MuMIn", "lme4", "optparse", "rgrass7"))
</pre>

==== MS Windows ====
We will be using GRASS GIS 7.0.3 that can be found here in the [https://trac.osgeo.org/osgeo4w/ OSGeo4W] package manager.
Please install the latest stable GRASS GIS 7 version and the SciPy Python package using the ''Advanced install'' option.
A guide with step by step screen shot instructions is available [https://docs.google.com/presentation/d/1yEGpriBne7RvjB35HI6GecNwO1P1y2nRGqDThqoNnCE/edit?usp=sharing here].

In order for GRASS to be able to find R executables, GRASS must be on the PATH variable. Follow this [solution] to make R accessible from GRASS permanently.
A simple but temporary solution is to open GRASS GIS and paste this in the black terminal:
<pre>
set PATH=%PATH%;C:\Program Files\R\R-3.0.2\bin
</pre>
This has to be repeated after restarting GRASS session.

==== Ubuntu Linux ====
Install GRASS GIS from packages:
<pre>
sudo add-apt-repository ppa:ubuntugis/ubuntugis-unstable
sudo apt-get update
sudo apt-get install grass
</pre>

== Workshop data ==
The data that we will be using for the workshop can be download here: [http://fatra.cnr.ncsu.edu/futures/futures_ncspm_Asheville.zip sample dataset]. Please place these layers in your local GRASS directory:
* digital elevation model ([http://nationalmap.gov/elevation.html NED])
* [http://www.mrlc.gov/ NLCD] 2001, 2011
* NLCD 1992/2001 Retrofit Land Cover Change Product
* transportation network ([http://www.census.gov/geo/maps-data/data/tiger-line.html TIGER])
* county boundaries ([http://www.census.gov/geo/maps-data/data/tiger-line.html TIGER])
* protected areas ([http://www.conservationgateway.org/ConservationByGeography/NorthAmerica/UnitedStates/edc/reportsdata/terrestrial/secured/Pages/default.aspx Secured Lands])
* cities as points (USGS)

In addition, download [http://fatra.cnr.ncsu.edu/futures/futures_Asheville_files.zip population information as text files]:
* county population past estimates and future projections ([https://www.osbm.nc.gov/demog/county-projections NC OSBM]) per county (nonspatial)

= GRASS GIS introduction =
There are many advantages to using the open source GRASS GIS platform, but for many that are more familiar with ARCGis and QGis, the setup and implementation of spatial tools in GRASS can be confusing. Here we provide an overview of the GRASS GIS project: [https://grass.osgeo.org grass.osgeo.org] that might be helpful to review if you are a first time users. For this exercise it's not necessary to have a full understanding of how to use GRASS. However, you will need to know how to place your data in the correct GRASS database directory and for this we provide step by step instructions.
* Overview of [https://grass.osgeo.org/grass71/manuals/grass_database.html GRASS database].
** ''GRASS database'': directory with Locations (projects)
** ''Location'': directory with Mapsets, defined by projection (spatial reference system)
** ''Mapset'': collection of maps
* Download the [http://fatra.cnr.ncsu.edu/futures/futures_ncspm_Asheville.zip workshop location]. Create (unless you already have it) a directory named <tt>grassdata</tt> (GRASS database) in your home folder (or Documents), unzip the downloaded data into this directory. You should have now Location <tt>futures_ncspm</tt> in <tt>grassdata</tt>.
* Launch GRASS and display raster, vector data, explore navigation, querying, adding legend, showing metadata
<center><gallery perrow=3 widths=500 heights=250>Image:GRASS FUTURES startup.png|GRASS GIS 7.0.3 startup dialog with downloaded Location and Mapsets for FUTURES workshop
Image:GRASS FUTURES wxGUI display.png|Layer Manager and Map Display overview. Annotations show how to add raster layer, query, add legend.
Image:wxGUI_metadata_rinfo.png|Show raster map metadata by right click on layer</gallery></center>

* GRASS GIS has over [https://grass.osgeo.org/grass70/manuals/full_index.html 500 different modules] in the core distribution and over [https://grass.osgeo.org/grass70/manuals/addons/ 230 addon modules]
<center>
{| class="wikitable"
|-
! Prefix !! Function !! Example
|-
| r.* || raster processing || ''{{cmd|r.mapcalc}}'': map algebra
|-
| v.* || vector processing || ''{{cmd|v.clean}}'': topological cleaning
|-
| i.* || imagery processing || ''{{cmd|i.segment}}'': object recognition
|-
| db.* || database management || ''{{cmd|db.select}}'': select values from table
|-
| r3.* || 3D raster processing || ''{{cmd|r3.stats}}'': 3D raster statistics
|-
| t.* || temporal data processing || ''{{cmd|t.rast.aggregate}}'': temporal aggregation
|-
| g.* || general data management || ''{{cmd|g.rename}}'': renames map
|-
| d.* || display ||''{{cmd|d.rast}}'': display raster map
|}</center>
* GRASS modules have GUI and command line interface. In this workshop we use commands to describe the workflow, but we can use both GUI and command line depending on personal preference. Look how {{cmd|wxGUI.modules|version=71|desc=GUI and command line interface}} represent the same tool. ''Task:'' compute aspect (orientation) from provided digital elevation model using module {{cmd|r.slope.aspect}} using both module dialog and command line.
* How to find modules? Modules are organized by their functionality in wxGUI menu, or we can search for them in Search modules tab. If we already know which module to use, we can just type it in the wxGUI command console. <center><gallery perrow=3 widths=380 heights=190>Image:wxGUI_menu_rinfo.png|Modules can be found in wxGUI menu
Image:wxGUI_module_search.png|You can search modules by name, description or keywords in ''Search modules'' tab
Image:wxGUI_console_completion.png|By typing prefix r. we make a list of modules starting with that prefix to show up.</gallery></center>


* {{cmd|g.region|desc=Computational region}} - an important raster concept
** defined by region extent and raster resolution
** applies to all raster operations
** persists between GRASS session, can be different for different mapsets
** advantages: keeps your results consistent, avoid clipping, for computationally demanding tasks set region to smaller extent, check your result is good and then set the computational region to the entire study area and rerun analysis
** run <code>g.region -p</code> or in menu ''Settings'' - ''Region'' - ''Display region'' to see current region settings
[[File:WxGUI set region.png|700px|thumb|center|Simple ways to set computational region from GUI. On the left, set region to match raster map. On the right, select the highlighted option and then set region by drawing rectangle.]]

* GRASS 3D view

= Modeling with FUTURES =
== Initial steps and data preparation ==
First we will set computational region of our analyses to an extent covering our study area and so that the cells are aligned with one of our landuse rasters:
<source lang="bash">g.region raster=landuse_2011 -p</source>

We will derive urbanized areas from NLCD dataset for year 1992, 2001 and 2011
by extracting categories category 21 - 24 into a new binary map where developed is 1,
undeveloped 0 and NULL (no data) is area unsuitable for development (water, wetlands, protected areas).
First we will convert protected areas from vector to raster. We set
NULLs to zeros (for simpler raster algebra expression in the next step) using {{cmd|r.null}}:

<source lang="bash">
v.to.rast input=protected_areas output=protected_areas use=val
r.null map=protected_areas null=0
</source>

And then create rasters of developed/undeveloped areas using raster algebra:

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.mapcalc "urban_1992 = if(landuse_1992 >= 21 && landuse_1992 <= 24, 1, if(landuse_1992 == 11 || landuse_1992 >= 90 || protected_areas, null(), 0))"
r.mapcalc "urban_2001 = if(landuse_2001 >= 21 && landuse_2001 <= 24, 1, if(landuse_2001 == 11 || landuse_2001 >= 90 || protected_areas, null(), 0))"
r.mapcalc "urban_2011 = if(landuse_2011 >= 21 && landuse_2011 <= 24, 1, if(landuse_2011 == 11 || landuse_2011 >= 90 || protected_areas, null(), 0))"
</source>

We will convert vector counties to raster with the values of the FIPS attribute which links to population file:

<source lang="bash">
v.to.rast input=counties type=area use=attr attribute_column=FIPS output=counties
</source>

Before further steps, we will set our working directory so that the input population files and text files
we are going to create are saved in one directory and easily accessible.
You can do that from menu ''Settings'' → ''GRASS working environment'' → ''Change working directory''.
Select (or create) a directory and move there the downloaded files <tt>population_projection.csv</tt> and <tt>population_trend.csv</tt>.

== Potential submodel ==
Module {{AddonCmd|r.futures.potential}} implements POTENTIAL submodel as a part of FUTURES land change model. POTENTIAL is implemented using a set of coefficients that relate a selection of site suitability factors to the probability of a place becoming developed. This is implemented using the parameter table in combination with maps of those site suitability factors (mapped predictors). The coefficients are obtained by conducting multilevel logistic regression in R with package lme4 where the coefficients may vary by county. The best model is selected automatically using dredge function from package [https://cran.r-project.org/web/packages/MuMIn/index.html MuMIn].

First, we will derive couple of predictors.
=== Predictors ===
==== Slope ====
We will derive slope in degrees from digital elevation model using {{cmd|r.slope.aspect}} module:
<source lang="bash">r.slope.aspect elevation=elevation_30m slope=slope</source>

==== Distance from lakes/rivers ====
First we will extract [http://www.mrlc.gov/nlcd11_leg.php category ''Open Water''] from 2011 NLCD dataset:
<source lang="bash">
r.mapcalc "water = if(landuse_2011 == 11, 1, null())"
</source>

Then we compute the distance to water with module {{cmd|r.grow.distance}} and set color table to shades of blue:
<source lang="bash">
r.grow.distance input=water distance=dist_to_water
r.colors -n map=dist_to_water color=blues
</source>

==== Distance from protected areas ====
We will use raster protected of protected areas we already created, but we will set NULL values to zero.
We compute the distance to protected areas with module {{cmd|r.grow.distance}} and set color table from green to red:
<source lang="bash">
r.null map=protected_areas setnull=0
r.grow.distance input=protected_areas distance=dist_to_protected
r.colors map=dist_to_protected color=gyr
</source>

==== Forests ====
We will smooth the transition between forest and other land use, see NLCD [http://www.mrlc.gov/nlcd11_leg.php category ''Open Water'']:
<source lang="bash">
r.mapcalc "forest = if(landuse_2011 >= 41 && landuse_2011 <= 43, 1, 0)"
r.neighbors -c input=forest output=forest_smooth size=15 method=average
r.colors map=forest_smooth color=ndvi
</source>

==== Travel time to cities ====
Here we will compute travel time to cities (with population > 5000)
as cumulative cost distance where cost is defined as travel time on roads.
First we specify the speed on different types of roads.
We copy the roads raster into our mapset so that we can change it
by adding a new attribute field <tt>speed</tt>. Then we assign speed values (km/h) based on the type of road:

<source lang="bash">
g.copy vector=roads,myroads
v.db.addcolumn map=myroads columns="speed double precision"
v.db.update map=myroads column=speed value=50 where="MTFCC = 'S1400'"
v.db.update map=myroads column=speed value=100 where="MTFCC IN ('S1100', 'S1200')"
</source>

Now we rasterize the selected road types using the speed values from the attribute table as raster values.

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
v.to.rast input=myroads type=line where="MTFCC IN ('S1100', 'S1200', 'S1400')" output=roads_speed use=attr attribute_column=speed
</source>

We set the rest of the area to low speed and recompute the speed as time to travel through a 30m cell in minutes:

<source lang="bash">
r.null map=roads_speed null=5
r.mapcalc "roads_travel_time = 1.8 / roads_speed"
</source>

Finally we compute the travel time to larger cities using {{cmd|r.cost}}:

<source lang="bash">
r.cost input=roads_travel_time output=travel_time_cities start_points=cities
r.colors map=travel_time_cities color=byr
</source>

==== Road density ====
We will rasterize roads and use moving window analysis ({{cmd|r.neighbors}}) to compute road density:

<source lang="bash">
v.to.rast input=roads output=roads use=val type=line
r.null map=roads null=0
r.neighbors -c input=roads output=road_dens size=25 method=average
</source>

==== Distance to interchanges ====

We will consider TIGER roads of type <tt>Ramp</tt> as interchanges, rasterize them and compute euclidean distance to them:

<source lang="bash">
v.to.rast input=roads type=line where="MTFCC = 'S1630'" output=interchanges use=val
r.grow.distance -m input=interchanges distance=dist_interchanges
</source>

=== Development pressure ===

We compute development pressure with {{AddonCmd|r.futures.devpressure}}. Development pressure is a predictor based on number of neighboring developed cells within search distance, weighted by distance. The development pressure variable plays a special role in the model, allowing for a feedback between predicted change and change in subsequent steps.

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.devpressure -n input=urban_2011 output=devpressure_2 method=gravity size=7 gamma=2 scaling_factor=10
r.futures.devpressure -n input=urban_2011 output=devpressure_1 method=gravity size=10 gamma=1 scaling_factor=1
r.futures.devpressure -n input=urban_2011 output=devpressure_0_5 method=gravity size=30 gamma=0.5 scaling_factor=0.1
</source>

When gamma increases, development influence decreases more rapidly with distance.
Size is half the size of the moving window. When gamma is low, local development influences more distant places.
We will derive 3 layers with different gamma and size parameters for the potential statistical model.

=== Rescaling variables ===

First we will look at the ranges of our predictor variables by running a short Python code snippet in Python shell:

<source lang="python" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
for name in ['slope', 'dist_to_water', 'dist_to_protected', 'forest_smooth', 'travel_time_cities', 'road_dens', 'dist_interchanges', 'devpressure_0_5', 'devpressure_1']:
minmax = grass.raster_info(name)
print name, minmax['min'], minmax['max']
</source>

We will rescale some of our input variables:

<source lang="bash">
r.mapcalc "dist_to_water_km = dist_to_water / 1000"
r.mapcalc "dist_to_protected_km = dist_to_protected / 1000"
r.mapcalc "dist_interchanges_km = dist_interchanges / 1000"
r.mapcalc "road_dens_perc = road_dens * 100"
r.mapcalc "forest_smooth_perc = forest_smooth * 100"
</source>

=== Sampling ===
To sample only in the analyzed counties, we will clip development layer:

<source lang="bash">
r.mapcalc "urban_change_01_11 = if(urban_2011 == 1, if(urban_2001 == 0, 1, null()), 0)"
r.mapcalc "urban_change_clip = if(counties, urban_change_01_11)"
</source>

To estimate the number of sampling points, we can use {{cmd|r.report}} to report number of developed/undeveloped cells and their ratio.

<source lang="bash">
r.report map=urban_change_clip units=h,c,p
</source>

We will sample the predictors and the response variable with 5000 random points in undeveloped areas and 1000 points in developed area:

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.sample.category input=urban_change_clip output=sampling sampled=counties,devpressure_0_5,devpressure_1,devpressure_2,slope,road_dens_perc,forest_smooth_perc,dist_to_water_km,dist_to_protected_km,dist_interchanges_km,travel_time_cities npoints=5000,1000
</source>

The attribute table can be exported as CSV file (not necessary step):

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
v.db.select map=sampling columns=urban_change_clip,counties,devpressure_0_5,devpressure_1,slope,road_dens_perc,forest_smooth_perc,dist_to_water_km,dist_to_protected_km,dist_interchanges_km,travel_time_cities separator=comma file=samples.csv
</source>

=== Development potential ===
Now we find best model for predicting urbanization using {{AddonCmd|r.futures.potential}} which wraps an R script.

We can run R [http://www.inside-r.org/packages/cran/MuMIn/docs/dredge dredge] function to find "best" model. We can specify minimum and maximum number of predictors the final model should use.
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.potential -d input=sampling output=potential.csv columns=devpressure_1,slope,road_dens_perc,forest_smooth_perc,dist_to_water_km,dist_to_protected_km,dist_interchanges_km,travel_time_cities developed_column=urban_change_clip subregions_column=counties min_variables=4
</source>

Also, we can play with different combinations of predictors, for example:

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.potential input=sampling output=potential.csv columns=devpressure_2,road_dens_perc,slope,dist_interchanges_km,dist_to_water_km developed_column=urban_change_clip subregions_column=counties --o
r.futures.potential input=sampling output=potential.csv columns=devpressure_1,road_dens_perc,slope,dist_interchanges_km,dist_to_water_km developed_column=urban_change_clip subregions_column=counties --o
...
</source>

You can then open the output file <tt>potential.csv</tt>, which is a CSV file with tabs as separators.

For this tutorial, the final potential is created with:
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.potential input=sampling output=potential.csv columns=devpressure_2,road_dens_perc,slope,dist_interchanges_km,dist_to_water_km developed_column=urban_change_clip subregions_column=counties --o
</source>

We can now visualize the suitability surface using module {{AddonCmd|r.futures.potsurface}}. It creates initial development potential (suitability) raster from predictors and model coefficients and serves only for evaluating development potential model. The values of the resulting raster range from 0 to 1.

<source lang="bash">
r.futures.potsurface input=potential.csv subregions=counties output=suitability
r.colors map=suitability color=byr
</source>

== Demand submodel ==
First we will mask out roads so that they don't influence into per capita land demand relation.
<source lang="bash">
v.to.rast input=roads type=line output=roads_mask use=val
r.mask roads_mask -i
</source>

We will use {{AddonCmd|r.futures.demand}} which derives the population vs. development relation. The relation can be linear/logarithmic/logarithmic2/exponential/exponential approach.
Look for examples of the different relations in the manual.

* linear: y = A + Bx
* logarithmic: y = A + Bln(x)
* logarithmic2: y = A + B * ln(x - C)        (requires SciPy)
* exponential: y = Ae^(BX)
* exp_approach: y = (1 - e^(-A(x - B))) + C        (requires SciPy)

The format of the input population CSV files is described in the manual. It is important to have synchronized categories of subregions and the column headers of the CSV files (in our case FIPS number). How to simply generate the list of years (for which demand is computed) is described in {{AddonCmd|r.futures.demand}} manual, for example run this in Python console:

<source lang="python">
','.join([str(i) for i in range(2011, 2036)])
</source>

Then we can create the DEMAND file:
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.demand development=urban_1992,urban_2001,urban_2011 subregions=counties observed_population=population_trend.csv projected_population=population_projection.csv simulation_times=2011,2012,2013,2014,2015,2016,2017,2018,2019,2020,2021,2022,2023,2024,2025,2026,2027,2028,2029,2030,2031,2032,2033,2034,2035 plot=plot_demand.pdf demand=demand.csv separator=comma
</source>

In your current working directory, you should find files <tt>plot_demand.png</tt> and <tt>demand.csv</tt>.

If you have SciPy installed, you can experiment with other methods for fitting the functions:
<source lang="bash">
r.futures.demand ... method=logarithmic2
r.futures.demand ... method=exp_approach
</source>
If necessary, you can create a set of demand files produced by fitting each method separately and
then pick for each county the method which seems best and manually create a new demand file.

When you are finished, remove the mask as it is not needed for the next steps.
<source lang="bash">
r.mask -r
</source>

== Patch calibration ==
Patch calibration can be a very time consuming computation.
Therefore we select only one county (Buncombe):

<source lang="bash">
v.to.rast input=counties type=area where="FIPS == 37021" use=attr attribute_column=FIPS output=calib_county
g.region raster=calib_county zoom=calib_county
</source>
to derive patches of new development by comparing historical and latest development.
We can keep only patches with minimum size 2 cells (1800 = 2 x 30 x 30 m).

<source lang="bash">
r.futures.calib development_start=urban_1992 development_end=urban_2011 subregions=counties patch_sizes=patches.txt patch_threshold=1800 -l
</source>
We obtained a file <tt>patches.txt</tt> (used later in the PGA) - a patch size distribution file - containing sizes of all found patches.

We can look at the distribution of the patch sizes:

<source lang="python">
from matplotlib import pyplot as plt
with open('patches.txt') as f:
patches = [int(patch) for patch in f.readlines()]
plt.hist(patches, 2000)
plt.xlim(0,50)
plt.show()
</source>

At this point, we start the calibration to get best parameters of patch shape
(for this tutorial, this step can be skipped and the suggested parameters are used).

<source lang="bash"
style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.calib development_start=urban_1992 development_end=urban_2011 subregions=calib_county patch_sizes=patches.txt calibration_results=calib.csv patch_threshold=1800 repeat=5 compactness_mean=0.1,0.3,0.5,0.7,0.9 compactness_range=0.05 discount_factor=0.1,0.3,0.5,0.7,0.9 predictors=road_dens_perc,forest_smooth_perc,dist_to_protected_km demand=demand.csv devpot_params=potential.csv num_neighbors=4 seed_search=2 development_pressure=devpressure_0_5 development_pressure_approach=gravity n_dev_neighbourhood=30 gamma=0.5 scaling_factor=0.1
</source>

== FUTURES simulation ==
We will switch back to our previous region:
<source lang="bash">
g.region raster=landuse_2011 -p
</source>

Now we have all the inputs necessary for running {{AddonCmd|r.futures.pga}}:

The entire command is here:
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.pga subregions=counties developed=urban_2011 predictors=slope,forest_smooth_perc,dist_interchanges_km,travel_time_cities devpot_params=potential.csv development_pressure=devpressure_1 n_dev_neighbourhood=10 development_pressure_approach=gravity gamma=1 scaling_factor=1 demand=demand.csv discount_factor=0.3 compactness_mean=0.2 compactness_range=0.1 patch_sizes=patches.txt num_neighbors=4 seed_search=2 random_seed=1 output=final output_series=final
</source>

=== Quick description ===
The command parameters and their values:
* raster map of counties with their categories
<code>
... subregions=counties ...
</code>

* raster of developed (1), undeveloped (0) and NULLs for undevelopable areas
<code>
... developed=urban_2011 ...
</code>

* predictors selected with {{AddonCmd|r.futures.potential}} and their coefficients in a <tt>potential.csv</tt> file. The order of predictors must match the order in the file and the categories of the counties must match raster <tt>counties</tt>.
<code>
... predictors=slope,forest_smooth_perc,dist_interchanges_km,travel_time_cities devpot_params=potential.csv ...
</code>

* initial development pressure computed by {{AddonCmd|r.futures.devpressure}}, it's important to set here the same parameters
<code>
... development_pressure=devpressure_1 n_dev_neighbourhood=10 development_pressure_approach=gravity gamma=1 scaling_factor=1 ...
</code>

* per capita land demand computed by {{AddonCmd|r.futures.demand}}, the categories of the counties must match raster <tt>counties</tt>.
<code>
... demand=demand.csv ...
</code>

* patch parameters from the calibration step
<code>
... discount_factor=0.3 compactness_mean=0.4 compactness_range=0.08 patch_sizes=patches.txt ...
</code>

* recommended parameters for patch growing algorithm
<code>
... num_neighbors=4 seed_search=2 ...
</code>

* set random seed for repeatable results or set flag <tt>-s</tt> to generate seed automatically
<code>
... random_seed=1 ...
</code>

* specify final output map and optionally basename for intermediate raster maps
<code>
output=final output_series=final
</code>

== Scenarios ==
Scenarios involving policies that encourage infill versus sprawl can be explored using the <tt>incentive_power</tt> parameter of {{AddonCmd|r.futures.pga}},
which uses a power function to transform the evenness of the probability gradient in POTENTIAL. You can change the power to a number between 0.25 and 4 to test urban sprawl/infill scenarios.
Higher power leads to infill behavior, lower power to urban sprawl.

== Postprocessing ==

Follow a [[Creating_animation_from_FUTURES_output_in_GRASS_GIS| tutorial how to make an animation from the results]].

= GRASS GIS Python API =

[[Category: Tutorial]]
[[Category: FUTURES]]
[[Category: Urban]]

Workshop on urban growth modeling with FUTURES

2016-03-22T17:02:48Z

⚠️Dbvanber: /* GRASS GIS introduction */

{{ToModify}}
= Workshop introduction =
r.futures.* is an implementation of the '''FUT'''ure '''U'''rban-'''R'''egional '''E'''nvironment '''S'''imulation (FUTURES)[1] which is a model for multilevel simulations of emerging urban-rural landscape structure. FUTURES produces regional projections of landscape patterns using coupled submodels that integrate nonstationary drivers of land change: per capita demand (DEMAND submodel), site suitability (POTENTIAL submodel), and the spatial structure of conversion events (PGA submodel).

[1] Meentemeyer, R. K., Tang, W., Dorning, M. A., Vogler, J. B., Cunniffe, N. J., & Shoemaker, D. A. (2013). [http://www.tandfonline.com/doi/abs/10.1080/00045608.2012.707591 FUTURES: multilevel simulations of emerging urban-rural landscape structure using a stochastic patch-growing algorithm.] Annals of the Association of American Geographers, 103(4), 785-807

== Software ==
There are a number of software requirements to run FUTURES that will need to be download and installed. Required software includes:
* GRASS GIS 7
* addons
** {{AddonCmd|r.futures.pga}}
** {{AddonCmd|r.futures.potential}}
** {{AddonCmd|r.futures.potsurface}}
** {{AddonCmd|r.futures.demand}}
** {{AddonCmd|r.futures.devpressure}}
** {{AddonCmd|r.sample.category}}
* R (≥ 3.0.2) - needed for {{AddonCmd|r.futures.potential}} with packages:
**MuMIn, lme4, optparse, rgrass7
* SciPy - useful for {{AddonCmd|r.futures.demand}}

=== Installation ===
We use the R statistical software for our calculation of site suitability (i.e. development potential) in FUTURES. R is a free software environment for statistical computing and graphics. If you don't have R, or you have older an version, please download and install the software from [http://archive.linux.duke.edu/cran/ install R] and be sure to additionally add these required packages:
<pre>
install.packages(c("MuMIn", "lme4", "optparse", "rgrass7"))
</pre>

==== MS Windows ====
We will be using GRASS GIS 7.0.3 that can be found here in the [https://trac.osgeo.org/osgeo4w/ OSGeo4W] package manager.
Please install the latest stable GRASS GIS 7 version and the SciPy Python package using the ''Advanced install'' option.
A guide with step by step screen shot instructions is available [https://docs.google.com/presentation/d/1yEGpriBne7RvjB35HI6GecNwO1P1y2nRGqDThqoNnCE/edit?usp=sharing here].

In order for GRASS to be able to find R executables, GRASS must be on the PATH variable. Follow this [solution] to make R accessible from GRASS permanently.
A simple but temporary solution is to open GRASS GIS and paste this in the black terminal:
<pre>
set PATH=%PATH%;C:\Program Files\R\R-3.0.2\bin
</pre>
This has to be repeated after restarting GRASS session.

==== Ubuntu Linux ====
Install GRASS GIS from packages:
<pre>
sudo add-apt-repository ppa:ubuntugis/ubuntugis-unstable
sudo apt-get update
sudo apt-get install grass
</pre>

== Workshop data ==
The data that we will be using for the workshop can be download here: [http://fatra.cnr.ncsu.edu/futures/futures_ncspm_Asheville.zip sample dataset]. Please place these layers in your local GRASS directory:
* digital elevation model ([http://nationalmap.gov/elevation.html NED])
* [http://www.mrlc.gov/ NLCD] 2001, 2011
* NLCD 1992/2001 Retrofit Land Cover Change Product
* transportation network ([http://www.census.gov/geo/maps-data/data/tiger-line.html TIGER])
* county boundaries ([http://www.census.gov/geo/maps-data/data/tiger-line.html TIGER])
* protected areas ([http://www.conservationgateway.org/ConservationByGeography/NorthAmerica/UnitedStates/edc/reportsdata/terrestrial/secured/Pages/default.aspx Secured Lands])
* cities as points (USGS)

In addition, download [http://fatra.cnr.ncsu.edu/futures/futures_Asheville_files.zip population information as text files]:
* county population past estimates and future projections ([https://www.osbm.nc.gov/demog/county-projections NC OSBM]) per county (nonspatial)

= GRASS GIS introduction =
There are many advantages to using the open source GRASS GIS platform, but for many that are more familiar with ARCGis and QGis, the setup and implementation of spatial tools in GRASS can be confusing. Here we provide an overview of the GRASS GIS project: [https://grass.osgeo.org grass.osgeo.org] that might be helpful to review if you are a first time users. For this exercise it's not necessary to have a full understanding of how to use GRASS. However, you will need to know how to place your data in the correct GRASS database directory.
* Overview of [https://grass.osgeo.org/grass71/manuals/grass_database.html GRASS database].
** ''GRASS database'': directory with Locations (projects)
** ''Location'': directory with Mapsets, defined by projection (spatial reference system)
** ''Mapset'': collection of maps
* Download the [http://fatra.cnr.ncsu.edu/futures/futures_ncspm_Asheville.zip workshop location]. Create (unless you already have it) a directory named <tt>grassdata</tt> (GRASS database) in your home folder (or Documents), unzip the downloaded data into this directory. You should have now Location <tt>futures_ncspm</tt> in <tt>grassdata</tt>.
* Launch GRASS and display raster, vector data, explore navigation, querying, adding legend, showing metadata
<center><gallery perrow=3 widths=500 heights=250>Image:GRASS FUTURES startup.png|GRASS GIS 7.0.3 startup dialog with downloaded Location and Mapsets for FUTURES workshop
Image:GRASS FUTURES wxGUI display.png|Layer Manager and Map Display overview. Annotations show how to add raster layer, query, add legend.
Image:wxGUI_metadata_rinfo.png|Show raster map metadata by right click on layer</gallery></center>

* GRASS GIS has over [https://grass.osgeo.org/grass70/manuals/full_index.html 500 different modules] in the core distribution and over [https://grass.osgeo.org/grass70/manuals/addons/ 230 addon modules]
<center>
{| class="wikitable"
|-
! Prefix !! Function !! Example
|-
| r.* || raster processing || ''{{cmd|r.mapcalc}}'': map algebra
|-
| v.* || vector processing || ''{{cmd|v.clean}}'': topological cleaning
|-
| i.* || imagery processing || ''{{cmd|i.segment}}'': object recognition
|-
| db.* || database management || ''{{cmd|db.select}}'': select values from table
|-
| r3.* || 3D raster processing || ''{{cmd|r3.stats}}'': 3D raster statistics
|-
| t.* || temporal data processing || ''{{cmd|t.rast.aggregate}}'': temporal aggregation
|-
| g.* || general data management || ''{{cmd|g.rename}}'': renames map
|-
| d.* || display ||''{{cmd|d.rast}}'': display raster map
|}</center>
* GRASS modules have GUI and command line interface. In this workshop we use commands to describe the workflow, but we can use both GUI and command line depending on personal preference. Look how {{cmd|wxGUI.modules|version=71|desc=GUI and command line interface}} represent the same tool. ''Task:'' compute aspect (orientation) from provided digital elevation model using module {{cmd|r.slope.aspect}} using both module dialog and command line.
* How to find modules? Modules are organized by their functionality in wxGUI menu, or we can search for them in Search modules tab. If we already know which module to use, we can just type it in the wxGUI command console. <center><gallery perrow=3 widths=380 heights=190>Image:wxGUI_menu_rinfo.png|Modules can be found in wxGUI menu
Image:wxGUI_module_search.png|You can search modules by name, description or keywords in ''Search modules'' tab
Image:wxGUI_console_completion.png|By typing prefix r. we make a list of modules starting with that prefix to show up.</gallery></center>


* {{cmd|g.region|desc=Computational region}} - an important raster concept
** defined by region extent and raster resolution
** applies to all raster operations
** persists between GRASS session, can be different for different mapsets
** advantages: keeps your results consistent, avoid clipping, for computationally demanding tasks set region to smaller extent, check your result is good and then set the computational region to the entire study area and rerun analysis
** run <code>g.region -p</code> or in menu ''Settings'' - ''Region'' - ''Display region'' to see current region settings
[[File:WxGUI set region.png|700px|thumb|center|Simple ways to set computational region from GUI. On the left, set region to match raster map. On the right, select the highlighted option and then set region by drawing rectangle.]]

* GRASS 3D view

= Modeling with FUTURES =
== Initial steps and data preparation ==
First we will set computational region of our analyses to an extent covering our study area and so that the cells are aligned with one of our landuse rasters:
<source lang="bash">g.region raster=landuse_2011 -p</source>

We will derive urbanized areas from NLCD dataset for year 1992, 2001 and 2011
by extracting categories category 21 - 24 into a new binary map where developed is 1,
undeveloped 0 and NULL (no data) is area unsuitable for development (water, wetlands, protected areas).
First we will convert protected areas from vector to raster. We set
NULLs to zeros (for simpler raster algebra expression in the next step) using {{cmd|r.null}}:

<source lang="bash">
v.to.rast input=protected_areas output=protected_areas use=val
r.null map=protected_areas null=0
</source>

And then create rasters of developed/undeveloped areas using raster algebra:

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.mapcalc "urban_1992 = if(landuse_1992 >= 21 && landuse_1992 <= 24, 1, if(landuse_1992 == 11 || landuse_1992 >= 90 || protected_areas, null(), 0))"
r.mapcalc "urban_2001 = if(landuse_2001 >= 21 && landuse_2001 <= 24, 1, if(landuse_2001 == 11 || landuse_2001 >= 90 || protected_areas, null(), 0))"
r.mapcalc "urban_2011 = if(landuse_2011 >= 21 && landuse_2011 <= 24, 1, if(landuse_2011 == 11 || landuse_2011 >= 90 || protected_areas, null(), 0))"
</source>

We will convert vector counties to raster with the values of the FIPS attribute which links to population file:

<source lang="bash">
v.to.rast input=counties type=area use=attr attribute_column=FIPS output=counties
</source>

Before further steps, we will set our working directory so that the input population files and text files
we are going to create are saved in one directory and easily accessible.
You can do that from menu ''Settings'' → ''GRASS working environment'' → ''Change working directory''.
Select (or create) a directory and move there the downloaded files <tt>population_projection.csv</tt> and <tt>population_trend.csv</tt>.

== Potential submodel ==
Module {{AddonCmd|r.futures.potential}} implements POTENTIAL submodel as a part of FUTURES land change model. POTENTIAL is implemented using a set of coefficients that relate a selection of site suitability factors to the probability of a place becoming developed. This is implemented using the parameter table in combination with maps of those site suitability factors (mapped predictors). The coefficients are obtained by conducting multilevel logistic regression in R with package lme4 where the coefficients may vary by county. The best model is selected automatically using dredge function from package [https://cran.r-project.org/web/packages/MuMIn/index.html MuMIn].

First, we will derive couple of predictors.
=== Predictors ===
==== Slope ====
We will derive slope in degrees from digital elevation model using {{cmd|r.slope.aspect}} module:
<source lang="bash">r.slope.aspect elevation=elevation_30m slope=slope</source>

==== Distance from lakes/rivers ====
First we will extract [http://www.mrlc.gov/nlcd11_leg.php category ''Open Water''] from 2011 NLCD dataset:
<source lang="bash">
r.mapcalc "water = if(landuse_2011 == 11, 1, null())"
</source>

Then we compute the distance to water with module {{cmd|r.grow.distance}} and set color table to shades of blue:
<source lang="bash">
r.grow.distance input=water distance=dist_to_water
r.colors -n map=dist_to_water color=blues
</source>

==== Distance from protected areas ====
We will use raster protected of protected areas we already created, but we will set NULL values to zero.
We compute the distance to protected areas with module {{cmd|r.grow.distance}} and set color table from green to red:
<source lang="bash">
r.null map=protected_areas setnull=0
r.grow.distance input=protected_areas distance=dist_to_protected
r.colors map=dist_to_protected color=gyr
</source>

==== Forests ====
We will smooth the transition between forest and other land use, see NLCD [http://www.mrlc.gov/nlcd11_leg.php category ''Open Water'']:
<source lang="bash">
r.mapcalc "forest = if(landuse_2011 >= 41 && landuse_2011 <= 43, 1, 0)"
r.neighbors -c input=forest output=forest_smooth size=15 method=average
r.colors map=forest_smooth color=ndvi
</source>

==== Travel time to cities ====
Here we will compute travel time to cities (with population > 5000)
as cumulative cost distance where cost is defined as travel time on roads.
First we specify the speed on different types of roads.
We copy the roads raster into our mapset so that we can change it
by adding a new attribute field <tt>speed</tt>. Then we assign speed values (km/h) based on the type of road:

<source lang="bash">
g.copy vector=roads,myroads
v.db.addcolumn map=myroads columns="speed double precision"
v.db.update map=myroads column=speed value=50 where="MTFCC = 'S1400'"
v.db.update map=myroads column=speed value=100 where="MTFCC IN ('S1100', 'S1200')"
</source>

Now we rasterize the selected road types using the speed values from the attribute table as raster values.

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
v.to.rast input=myroads type=line where="MTFCC IN ('S1100', 'S1200', 'S1400')" output=roads_speed use=attr attribute_column=speed
</source>

We set the rest of the area to low speed and recompute the speed as time to travel through a 30m cell in minutes:

<source lang="bash">
r.null map=roads_speed null=5
r.mapcalc "roads_travel_time = 1.8 / roads_speed"
</source>

Finally we compute the travel time to larger cities using {{cmd|r.cost}}:

<source lang="bash">
r.cost input=roads_travel_time output=travel_time_cities start_points=cities
r.colors map=travel_time_cities color=byr
</source>

==== Road density ====
We will rasterize roads and use moving window analysis ({{cmd|r.neighbors}}) to compute road density:

<source lang="bash">
v.to.rast input=roads output=roads use=val type=line
r.null map=roads null=0
r.neighbors -c input=roads output=road_dens size=25 method=average
</source>

==== Distance to interchanges ====

We will consider TIGER roads of type <tt>Ramp</tt> as interchanges, rasterize them and compute euclidean distance to them:

<source lang="bash">
v.to.rast input=roads type=line where="MTFCC = 'S1630'" output=interchanges use=val
r.grow.distance -m input=interchanges distance=dist_interchanges
</source>

=== Development pressure ===

We compute development pressure with {{AddonCmd|r.futures.devpressure}}. Development pressure is a predictor based on number of neighboring developed cells within search distance, weighted by distance. The development pressure variable plays a special role in the model, allowing for a feedback between predicted change and change in subsequent steps.

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.devpressure -n input=urban_2011 output=devpressure_2 method=gravity size=7 gamma=2 scaling_factor=10
r.futures.devpressure -n input=urban_2011 output=devpressure_1 method=gravity size=10 gamma=1 scaling_factor=1
r.futures.devpressure -n input=urban_2011 output=devpressure_0_5 method=gravity size=30 gamma=0.5 scaling_factor=0.1
</source>

When gamma increases, development influence decreases more rapidly with distance.
Size is half the size of the moving window. When gamma is low, local development influences more distant places.
We will derive 3 layers with different gamma and size parameters for the potential statistical model.

=== Rescaling variables ===

First we will look at the ranges of our predictor variables by running a short Python code snippet in Python shell:

<source lang="python" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
for name in ['slope', 'dist_to_water', 'dist_to_protected', 'forest_smooth', 'travel_time_cities', 'road_dens', 'dist_interchanges', 'devpressure_0_5', 'devpressure_1']:
minmax = grass.raster_info(name)
print name, minmax['min'], minmax['max']
</source>

We will rescale some of our input variables:

<source lang="bash">
r.mapcalc "dist_to_water_km = dist_to_water / 1000"
r.mapcalc "dist_to_protected_km = dist_to_protected / 1000"
r.mapcalc "dist_interchanges_km = dist_interchanges / 1000"
r.mapcalc "road_dens_perc = road_dens * 100"
r.mapcalc "forest_smooth_perc = forest_smooth * 100"
</source>

=== Sampling ===
To sample only in the analyzed counties, we will clip development layer:

<source lang="bash">
r.mapcalc "urban_change_01_11 = if(urban_2011 == 1, if(urban_2001 == 0, 1, null()), 0)"
r.mapcalc "urban_change_clip = if(counties, urban_change_01_11)"
</source>

To estimate the number of sampling points, we can use {{cmd|r.report}} to report number of developed/undeveloped cells and their ratio.

<source lang="bash">
r.report map=urban_change_clip units=h,c,p
</source>

We will sample the predictors and the response variable with 5000 random points in undeveloped areas and 1000 points in developed area:

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.sample.category input=urban_change_clip output=sampling sampled=counties,devpressure_0_5,devpressure_1,devpressure_2,slope,road_dens_perc,forest_smooth_perc,dist_to_water_km,dist_to_protected_km,dist_interchanges_km,travel_time_cities npoints=5000,1000
</source>

The attribute table can be exported as CSV file (not necessary step):

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
v.db.select map=sampling columns=urban_change_clip,counties,devpressure_0_5,devpressure_1,slope,road_dens_perc,forest_smooth_perc,dist_to_water_km,dist_to_protected_km,dist_interchanges_km,travel_time_cities separator=comma file=samples.csv
</source>

=== Development potential ===
Now we find best model for predicting urbanization using {{AddonCmd|r.futures.potential}} which wraps an R script.

We can run R [http://www.inside-r.org/packages/cran/MuMIn/docs/dredge dredge] function to find "best" model. We can specify minimum and maximum number of predictors the final model should use.
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.potential -d input=sampling output=potential.csv columns=devpressure_1,slope,road_dens_perc,forest_smooth_perc,dist_to_water_km,dist_to_protected_km,dist_interchanges_km,travel_time_cities developed_column=urban_change_clip subregions_column=counties min_variables=4
</source>

Also, we can play with different combinations of predictors, for example:

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.potential input=sampling output=potential.csv columns=devpressure_2,road_dens_perc,slope,dist_interchanges_km,dist_to_water_km developed_column=urban_change_clip subregions_column=counties --o
r.futures.potential input=sampling output=potential.csv columns=devpressure_1,road_dens_perc,slope,dist_interchanges_km,dist_to_water_km developed_column=urban_change_clip subregions_column=counties --o
...
</source>

You can then open the output file <tt>potential.csv</tt>, which is a CSV file with tabs as separators.

For this tutorial, the final potential is created with:
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.potential input=sampling output=potential.csv columns=devpressure_2,road_dens_perc,slope,dist_interchanges_km,dist_to_water_km developed_column=urban_change_clip subregions_column=counties --o
</source>

We can now visualize the suitability surface using module {{AddonCmd|r.futures.potsurface}}. It creates initial development potential (suitability) raster from predictors and model coefficients and serves only for evaluating development potential model. The values of the resulting raster range from 0 to 1.

<source lang="bash">
r.futures.potsurface input=potential.csv subregions=counties output=suitability
r.colors map=suitability color=byr
</source>

== Demand submodel ==
First we will mask out roads so that they don't influence into per capita land demand relation.
<source lang="bash">
v.to.rast input=roads type=line output=roads_mask use=val
r.mask roads_mask -i
</source>

We will use {{AddonCmd|r.futures.demand}} which derives the population vs. development relation. The relation can be linear/logarithmic/logarithmic2/exponential/exponential approach.
Look for examples of the different relations in the manual.

* linear: y = A + Bx
* logarithmic: y = A + Bln(x)
* logarithmic2: y = A + B * ln(x - C)        (requires SciPy)
* exponential: y = Ae^(BX)
* exp_approach: y = (1 - e^(-A(x - B))) + C        (requires SciPy)

The format of the input population CSV files is described in the manual. It is important to have synchronized categories of subregions and the column headers of the CSV files (in our case FIPS number). How to simply generate the list of years (for which demand is computed) is described in {{AddonCmd|r.futures.demand}} manual, for example run this in Python console:

<source lang="python">
','.join([str(i) for i in range(2011, 2036)])
</source>

Then we can create the DEMAND file:
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.demand development=urban_1992,urban_2001,urban_2011 subregions=counties observed_population=population_trend.csv projected_population=population_projection.csv simulation_times=2011,2012,2013,2014,2015,2016,2017,2018,2019,2020,2021,2022,2023,2024,2025,2026,2027,2028,2029,2030,2031,2032,2033,2034,2035 plot=plot_demand.pdf demand=demand.csv separator=comma
</source>

In your current working directory, you should find files <tt>plot_demand.png</tt> and <tt>demand.csv</tt>.

If you have SciPy installed, you can experiment with other methods for fitting the functions:
<source lang="bash">
r.futures.demand ... method=logarithmic2
r.futures.demand ... method=exp_approach
</source>
If necessary, you can create a set of demand files produced by fitting each method separately and
then pick for each county the method which seems best and manually create a new demand file.

When you are finished, remove the mask as it is not needed for the next steps.
<source lang="bash">
r.mask -r
</source>

== Patch calibration ==
Patch calibration can be a very time consuming computation.
Therefore we select only one county (Buncombe):

<source lang="bash">
v.to.rast input=counties type=area where="FIPS == 37021" use=attr attribute_column=FIPS output=calib_county
g.region raster=calib_county zoom=calib_county
</source>
to derive patches of new development by comparing historical and latest development.
We can keep only patches with minimum size 2 cells (1800 = 2 x 30 x 30 m).

<source lang="bash">
r.futures.calib development_start=urban_1992 development_end=urban_2011 subregions=counties patch_sizes=patches.txt patch_threshold=1800 -l
</source>
We obtained a file <tt>patches.txt</tt> (used later in the PGA) - a patch size distribution file - containing sizes of all found patches.

We can look at the distribution of the patch sizes:

<source lang="python">
from matplotlib import pyplot as plt
with open('patches.txt') as f:
patches = [int(patch) for patch in f.readlines()]
plt.hist(patches, 2000)
plt.xlim(0,50)
plt.show()
</source>

At this point, we start the calibration to get best parameters of patch shape
(for this tutorial, this step can be skipped and the suggested parameters are used).

<source lang="bash"
style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.calib development_start=urban_1992 development_end=urban_2011 subregions=calib_county patch_sizes=patches.txt calibration_results=calib.csv patch_threshold=1800 repeat=5 compactness_mean=0.1,0.3,0.5,0.7,0.9 compactness_range=0.05 discount_factor=0.1,0.3,0.5,0.7,0.9 predictors=road_dens_perc,forest_smooth_perc,dist_to_protected_km demand=demand.csv devpot_params=potential.csv num_neighbors=4 seed_search=2 development_pressure=devpressure_0_5 development_pressure_approach=gravity n_dev_neighbourhood=30 gamma=0.5 scaling_factor=0.1
</source>

== FUTURES simulation ==
We will switch back to our previous region:
<source lang="bash">
g.region raster=landuse_2011 -p
</source>

Now we have all the inputs necessary for running {{AddonCmd|r.futures.pga}}:

The entire command is here:
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.pga subregions=counties developed=urban_2011 predictors=slope,forest_smooth_perc,dist_interchanges_km,travel_time_cities devpot_params=potential.csv development_pressure=devpressure_1 n_dev_neighbourhood=10 development_pressure_approach=gravity gamma=1 scaling_factor=1 demand=demand.csv discount_factor=0.3 compactness_mean=0.2 compactness_range=0.1 patch_sizes=patches.txt num_neighbors=4 seed_search=2 random_seed=1 output=final output_series=final
</source>

=== Quick description ===
The command parameters and their values:
* raster map of counties with their categories
<code>
... subregions=counties ...
</code>

* raster of developed (1), undeveloped (0) and NULLs for undevelopable areas
<code>
... developed=urban_2011 ...
</code>

* predictors selected with {{AddonCmd|r.futures.potential}} and their coefficients in a <tt>potential.csv</tt> file. The order of predictors must match the order in the file and the categories of the counties must match raster <tt>counties</tt>.
<code>
... predictors=slope,forest_smooth_perc,dist_interchanges_km,travel_time_cities devpot_params=potential.csv ...
</code>

* initial development pressure computed by {{AddonCmd|r.futures.devpressure}}, it's important to set here the same parameters
<code>
... development_pressure=devpressure_1 n_dev_neighbourhood=10 development_pressure_approach=gravity gamma=1 scaling_factor=1 ...
</code>

* per capita land demand computed by {{AddonCmd|r.futures.demand}}, the categories of the counties must match raster <tt>counties</tt>.
<code>
... demand=demand.csv ...
</code>

* patch parameters from the calibration step
<code>
... discount_factor=0.3 compactness_mean=0.4 compactness_range=0.08 patch_sizes=patches.txt ...
</code>

* recommended parameters for patch growing algorithm
<code>
... num_neighbors=4 seed_search=2 ...
</code>

* set random seed for repeatable results or set flag <tt>-s</tt> to generate seed automatically
<code>
... random_seed=1 ...
</code>

* specify final output map and optionally basename for intermediate raster maps
<code>
output=final output_series=final
</code>

== Scenarios ==
Scenarios involving policies that encourage infill versus sprawl can be explored using the <tt>incentive_power</tt> parameter of {{AddonCmd|r.futures.pga}},
which uses a power function to transform the evenness of the probability gradient in POTENTIAL. You can change the power to a number between 0.25 and 4 to test urban sprawl/infill scenarios.
Higher power leads to infill behavior, lower power to urban sprawl.

== Postprocessing ==

Follow a [[Creating_animation_from_FUTURES_output_in_GRASS_GIS| tutorial how to make an animation from the results]].

= GRASS GIS Python API =

[[Category: Tutorial]]
[[Category: FUTURES]]
[[Category: Urban]]

Workshop on urban growth modeling with FUTURES

2016-03-22T16:59:41Z

⚠️Dbvanber: /* GRASS GIS introduction */

{{ToModify}}
= Workshop introduction =
r.futures.* is an implementation of the '''FUT'''ure '''U'''rban-'''R'''egional '''E'''nvironment '''S'''imulation (FUTURES)[1] which is a model for multilevel simulations of emerging urban-rural landscape structure. FUTURES produces regional projections of landscape patterns using coupled submodels that integrate nonstationary drivers of land change: per capita demand (DEMAND submodel), site suitability (POTENTIAL submodel), and the spatial structure of conversion events (PGA submodel).

[1] Meentemeyer, R. K., Tang, W., Dorning, M. A., Vogler, J. B., Cunniffe, N. J., & Shoemaker, D. A. (2013). [http://www.tandfonline.com/doi/abs/10.1080/00045608.2012.707591 FUTURES: multilevel simulations of emerging urban-rural landscape structure using a stochastic patch-growing algorithm.] Annals of the Association of American Geographers, 103(4), 785-807

== Software ==
There are a number of software requirements to run FUTURES that will need to be download and installed. Required software includes:
* GRASS GIS 7
* addons
** {{AddonCmd|r.futures.pga}}
** {{AddonCmd|r.futures.potential}}
** {{AddonCmd|r.futures.potsurface}}
** {{AddonCmd|r.futures.demand}}
** {{AddonCmd|r.futures.devpressure}}
** {{AddonCmd|r.sample.category}}
* R (≥ 3.0.2) - needed for {{AddonCmd|r.futures.potential}} with packages:
**MuMIn, lme4, optparse, rgrass7
* SciPy - useful for {{AddonCmd|r.futures.demand}}

=== Installation ===
We use the R statistical software for our calculation of site suitability (i.e. development potential) in FUTURES. R is a free software environment for statistical computing and graphics. If you don't have R, or you have older an version, please download and install the software from [http://archive.linux.duke.edu/cran/ install R] and be sure to additionally add these required packages:
<pre>
install.packages(c("MuMIn", "lme4", "optparse", "rgrass7"))
</pre>

==== MS Windows ====
We will be using GRASS GIS 7.0.3 that can be found here in the [https://trac.osgeo.org/osgeo4w/ OSGeo4W] package manager.
Please install the latest stable GRASS GIS 7 version and the SciPy Python package using the ''Advanced install'' option.
A guide with step by step screen shot instructions is available [https://docs.google.com/presentation/d/1yEGpriBne7RvjB35HI6GecNwO1P1y2nRGqDThqoNnCE/edit?usp=sharing here].

In order for GRASS to be able to find R executables, GRASS must be on the PATH variable. Follow this [solution] to make R accessible from GRASS permanently.
A simple but temporary solution is to open GRASS GIS and paste this in the black terminal:
<pre>
set PATH=%PATH%;C:\Program Files\R\R-3.0.2\bin
</pre>
This has to be repeated after restarting GRASS session.

==== Ubuntu Linux ====
Install GRASS GIS from packages:
<pre>
sudo add-apt-repository ppa:ubuntugis/ubuntugis-unstable
sudo apt-get update
sudo apt-get install grass
</pre>

== Workshop data ==
The data that we will be using for the workshop can be download here: [http://fatra.cnr.ncsu.edu/futures/futures_ncspm_Asheville.zip sample dataset]. Please place these layers in your local GRASS directory:
* digital elevation model ([http://nationalmap.gov/elevation.html NED])
* [http://www.mrlc.gov/ NLCD] 2001, 2011
* NLCD 1992/2001 Retrofit Land Cover Change Product
* transportation network ([http://www.census.gov/geo/maps-data/data/tiger-line.html TIGER])
* county boundaries ([http://www.census.gov/geo/maps-data/data/tiger-line.html TIGER])
* protected areas ([http://www.conservationgateway.org/ConservationByGeography/NorthAmerica/UnitedStates/edc/reportsdata/terrestrial/secured/Pages/default.aspx Secured Lands])
* cities as points (USGS)

In addition, download [http://fatra.cnr.ncsu.edu/futures/futures_Asheville_files.zip population information as text files]:
* county population past estimates and future projections ([https://www.osbm.nc.gov/demog/county-projections NC OSBM]) per county (nonspatial)

= GRASS GIS introduction =
There are many advantages to using the open source GRASS GIS platform, but for many that are more familiar with ARCGis and QGis, the setup and implementation of spatial tools in GRASS can be confusing. Here we provide an overview of GRASS GIS project: [https://grass.osgeo.org grass.osgeo.org] for first time users.
* Overview of [https://grass.osgeo.org/grass71/manuals/grass_database.html GRASS database].
** ''GRASS database'': directory with Locations (projects)
** ''Location'': directory with Mapsets, defined by projection (spatial reference system)
** ''Mapset'': collection of maps
* Download the [http://fatra.cnr.ncsu.edu/futures/futures_ncspm_Asheville.zip workshop location]. Create (unless you already have it) a directory named <tt>grassdata</tt> (GRASS database) in your home folder (or Documents), unzip the downloaded data into this directory. You should have now Location <tt>futures_ncspm</tt> in <tt>grassdata</tt>.
* Launch GRASS and display raster, vector data, explore navigation, querying, adding legend, showing metadata
<center><gallery perrow=3 widths=500 heights=250>Image:GRASS FUTURES startup.png|GRASS GIS 7.0.3 startup dialog with downloaded Location and Mapsets for FUTURES workshop
Image:GRASS FUTURES wxGUI display.png|Layer Manager and Map Display overview. Annotations show how to add raster layer, query, add legend.
Image:wxGUI_metadata_rinfo.png|Show raster map metadata by right click on layer</gallery></center>

* GRASS GIS has over [https://grass.osgeo.org/grass70/manuals/full_index.html 500 different modules] in the core distribution and over [https://grass.osgeo.org/grass70/manuals/addons/ 230 addon modules]
<center>
{| class="wikitable"
|-
! Prefix !! Function !! Example
|-
| r.* || raster processing || ''{{cmd|r.mapcalc}}'': map algebra
|-
| v.* || vector processing || ''{{cmd|v.clean}}'': topological cleaning
|-
| i.* || imagery processing || ''{{cmd|i.segment}}'': object recognition
|-
| db.* || database management || ''{{cmd|db.select}}'': select values from table
|-
| r3.* || 3D raster processing || ''{{cmd|r3.stats}}'': 3D raster statistics
|-
| t.* || temporal data processing || ''{{cmd|t.rast.aggregate}}'': temporal aggregation
|-
| g.* || general data management || ''{{cmd|g.rename}}'': renames map
|-
| d.* || display ||''{{cmd|d.rast}}'': display raster map
|}</center>
* GRASS modules have GUI and command line interface. In this workshop we use commands to describe the workflow, but we can use both GUI and command line depending on personal preference. Look how {{cmd|wxGUI.modules|version=71|desc=GUI and command line interface}} represent the same tool. ''Task:'' compute aspect (orientation) from provided digital elevation model using module {{cmd|r.slope.aspect}} using both module dialog and command line.
* How to find modules? Modules are organized by their functionality in wxGUI menu, or we can search for them in Search modules tab. If we already know which module to use, we can just type it in the wxGUI command console. <center><gallery perrow=3 widths=380 heights=190>Image:wxGUI_menu_rinfo.png|Modules can be found in wxGUI menu
Image:wxGUI_module_search.png|You can search modules by name, description or keywords in ''Search modules'' tab
Image:wxGUI_console_completion.png|By typing prefix r. we make a list of modules starting with that prefix to show up.</gallery></center>


* {{cmd|g.region|desc=Computational region}} - an important raster concept
** defined by region extent and raster resolution
** applies to all raster operations
** persists between GRASS session, can be different for different mapsets
** advantages: keeps your results consistent, avoid clipping, for computationally demanding tasks set region to smaller extent, check your result is good and then set the computational region to the entire study area and rerun analysis
** run <code>g.region -p</code> or in menu ''Settings'' - ''Region'' - ''Display region'' to see current region settings
[[File:WxGUI set region.png|700px|thumb|center|Simple ways to set computational region from GUI. On the left, set region to match raster map. On the right, select the highlighted option and then set region by drawing rectangle.]]

* GRASS 3D view

= Modeling with FUTURES =
== Initial steps and data preparation ==
First we will set computational region of our analyses to an extent covering our study area and so that the cells are aligned with one of our landuse rasters:
<source lang="bash">g.region raster=landuse_2011 -p</source>

We will derive urbanized areas from NLCD dataset for year 1992, 2001 and 2011
by extracting categories category 21 - 24 into a new binary map where developed is 1,
undeveloped 0 and NULL (no data) is area unsuitable for development (water, wetlands, protected areas).
First we will convert protected areas from vector to raster. We set
NULLs to zeros (for simpler raster algebra expression in the next step) using {{cmd|r.null}}:

<source lang="bash">
v.to.rast input=protected_areas output=protected_areas use=val
r.null map=protected_areas null=0
</source>

And then create rasters of developed/undeveloped areas using raster algebra:

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.mapcalc "urban_1992 = if(landuse_1992 >= 21 && landuse_1992 <= 24, 1, if(landuse_1992 == 11 || landuse_1992 >= 90 || protected_areas, null(), 0))"
r.mapcalc "urban_2001 = if(landuse_2001 >= 21 && landuse_2001 <= 24, 1, if(landuse_2001 == 11 || landuse_2001 >= 90 || protected_areas, null(), 0))"
r.mapcalc "urban_2011 = if(landuse_2011 >= 21 && landuse_2011 <= 24, 1, if(landuse_2011 == 11 || landuse_2011 >= 90 || protected_areas, null(), 0))"
</source>

We will convert vector counties to raster with the values of the FIPS attribute which links to population file:

<source lang="bash">
v.to.rast input=counties type=area use=attr attribute_column=FIPS output=counties
</source>

Before further steps, we will set our working directory so that the input population files and text files
we are going to create are saved in one directory and easily accessible.
You can do that from menu ''Settings'' → ''GRASS working environment'' → ''Change working directory''.
Select (or create) a directory and move there the downloaded files <tt>population_projection.csv</tt> and <tt>population_trend.csv</tt>.

== Potential submodel ==
Module {{AddonCmd|r.futures.potential}} implements POTENTIAL submodel as a part of FUTURES land change model. POTENTIAL is implemented using a set of coefficients that relate a selection of site suitability factors to the probability of a place becoming developed. This is implemented using the parameter table in combination with maps of those site suitability factors (mapped predictors). The coefficients are obtained by conducting multilevel logistic regression in R with package lme4 where the coefficients may vary by county. The best model is selected automatically using dredge function from package [https://cran.r-project.org/web/packages/MuMIn/index.html MuMIn].

First, we will derive couple of predictors.
=== Predictors ===
==== Slope ====
We will derive slope in degrees from digital elevation model using {{cmd|r.slope.aspect}} module:
<source lang="bash">r.slope.aspect elevation=elevation_30m slope=slope</source>

==== Distance from lakes/rivers ====
First we will extract [http://www.mrlc.gov/nlcd11_leg.php category ''Open Water''] from 2011 NLCD dataset:
<source lang="bash">
r.mapcalc "water = if(landuse_2011 == 11, 1, null())"
</source>

Then we compute the distance to water with module {{cmd|r.grow.distance}} and set color table to shades of blue:
<source lang="bash">
r.grow.distance input=water distance=dist_to_water
r.colors -n map=dist_to_water color=blues
</source>

==== Distance from protected areas ====
We will use raster protected of protected areas we already created, but we will set NULL values to zero.
We compute the distance to protected areas with module {{cmd|r.grow.distance}} and set color table from green to red:
<source lang="bash">
r.null map=protected_areas setnull=0
r.grow.distance input=protected_areas distance=dist_to_protected
r.colors map=dist_to_protected color=gyr
</source>

==== Forests ====
We will smooth the transition between forest and other land use, see NLCD [http://www.mrlc.gov/nlcd11_leg.php category ''Open Water'']:
<source lang="bash">
r.mapcalc "forest = if(landuse_2011 >= 41 && landuse_2011 <= 43, 1, 0)"
r.neighbors -c input=forest output=forest_smooth size=15 method=average
r.colors map=forest_smooth color=ndvi
</source>

==== Travel time to cities ====
Here we will compute travel time to cities (with population > 5000)
as cumulative cost distance where cost is defined as travel time on roads.
First we specify the speed on different types of roads.
We copy the roads raster into our mapset so that we can change it
by adding a new attribute field <tt>speed</tt>. Then we assign speed values (km/h) based on the type of road:

<source lang="bash">
g.copy vector=roads,myroads
v.db.addcolumn map=myroads columns="speed double precision"
v.db.update map=myroads column=speed value=50 where="MTFCC = 'S1400'"
v.db.update map=myroads column=speed value=100 where="MTFCC IN ('S1100', 'S1200')"
</source>

Now we rasterize the selected road types using the speed values from the attribute table as raster values.

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
v.to.rast input=myroads type=line where="MTFCC IN ('S1100', 'S1200', 'S1400')" output=roads_speed use=attr attribute_column=speed
</source>

We set the rest of the area to low speed and recompute the speed as time to travel through a 30m cell in minutes:

<source lang="bash">
r.null map=roads_speed null=5
r.mapcalc "roads_travel_time = 1.8 / roads_speed"
</source>

Finally we compute the travel time to larger cities using {{cmd|r.cost}}:

<source lang="bash">
r.cost input=roads_travel_time output=travel_time_cities start_points=cities
r.colors map=travel_time_cities color=byr
</source>

==== Road density ====
We will rasterize roads and use moving window analysis ({{cmd|r.neighbors}}) to compute road density:

<source lang="bash">
v.to.rast input=roads output=roads use=val type=line
r.null map=roads null=0
r.neighbors -c input=roads output=road_dens size=25 method=average
</source>

==== Distance to interchanges ====

We will consider TIGER roads of type <tt>Ramp</tt> as interchanges, rasterize them and compute euclidean distance to them:

<source lang="bash">
v.to.rast input=roads type=line where="MTFCC = 'S1630'" output=interchanges use=val
r.grow.distance -m input=interchanges distance=dist_interchanges
</source>

=== Development pressure ===

We compute development pressure with {{AddonCmd|r.futures.devpressure}}. Development pressure is a predictor based on number of neighboring developed cells within search distance, weighted by distance. The development pressure variable plays a special role in the model, allowing for a feedback between predicted change and change in subsequent steps.

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.devpressure -n input=urban_2011 output=devpressure_2 method=gravity size=7 gamma=2 scaling_factor=10
r.futures.devpressure -n input=urban_2011 output=devpressure_1 method=gravity size=10 gamma=1 scaling_factor=1
r.futures.devpressure -n input=urban_2011 output=devpressure_0_5 method=gravity size=30 gamma=0.5 scaling_factor=0.1
</source>

When gamma increases, development influence decreases more rapidly with distance.
Size is half the size of the moving window. When gamma is low, local development influences more distant places.
We will derive 3 layers with different gamma and size parameters for the potential statistical model.

=== Rescaling variables ===

First we will look at the ranges of our predictor variables by running a short Python code snippet in Python shell:

<source lang="python" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
for name in ['slope', 'dist_to_water', 'dist_to_protected', 'forest_smooth', 'travel_time_cities', 'road_dens', 'dist_interchanges', 'devpressure_0_5', 'devpressure_1']:
minmax = grass.raster_info(name)
print name, minmax['min'], minmax['max']
</source>

We will rescale some of our input variables:

<source lang="bash">
r.mapcalc "dist_to_water_km = dist_to_water / 1000"
r.mapcalc "dist_to_protected_km = dist_to_protected / 1000"
r.mapcalc "dist_interchanges_km = dist_interchanges / 1000"
r.mapcalc "road_dens_perc = road_dens * 100"
r.mapcalc "forest_smooth_perc = forest_smooth * 100"
</source>

=== Sampling ===
To sample only in the analyzed counties, we will clip development layer:

<source lang="bash">
r.mapcalc "urban_change_01_11 = if(urban_2011 == 1, if(urban_2001 == 0, 1, null()), 0)"
r.mapcalc "urban_change_clip = if(counties, urban_change_01_11)"
</source>

To estimate the number of sampling points, we can use {{cmd|r.report}} to report number of developed/undeveloped cells and their ratio.

<source lang="bash">
r.report map=urban_change_clip units=h,c,p
</source>

We will sample the predictors and the response variable with 5000 random points in undeveloped areas and 1000 points in developed area:

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.sample.category input=urban_change_clip output=sampling sampled=counties,devpressure_0_5,devpressure_1,devpressure_2,slope,road_dens_perc,forest_smooth_perc,dist_to_water_km,dist_to_protected_km,dist_interchanges_km,travel_time_cities npoints=5000,1000
</source>

The attribute table can be exported as CSV file (not necessary step):

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
v.db.select map=sampling columns=urban_change_clip,counties,devpressure_0_5,devpressure_1,slope,road_dens_perc,forest_smooth_perc,dist_to_water_km,dist_to_protected_km,dist_interchanges_km,travel_time_cities separator=comma file=samples.csv
</source>

=== Development potential ===
Now we find best model for predicting urbanization using {{AddonCmd|r.futures.potential}} which wraps an R script.

We can run R [http://www.inside-r.org/packages/cran/MuMIn/docs/dredge dredge] function to find "best" model. We can specify minimum and maximum number of predictors the final model should use.
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.potential -d input=sampling output=potential.csv columns=devpressure_1,slope,road_dens_perc,forest_smooth_perc,dist_to_water_km,dist_to_protected_km,dist_interchanges_km,travel_time_cities developed_column=urban_change_clip subregions_column=counties min_variables=4
</source>

Also, we can play with different combinations of predictors, for example:

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.potential input=sampling output=potential.csv columns=devpressure_2,road_dens_perc,slope,dist_interchanges_km,dist_to_water_km developed_column=urban_change_clip subregions_column=counties --o
r.futures.potential input=sampling output=potential.csv columns=devpressure_1,road_dens_perc,slope,dist_interchanges_km,dist_to_water_km developed_column=urban_change_clip subregions_column=counties --o
...
</source>

You can then open the output file <tt>potential.csv</tt>, which is a CSV file with tabs as separators.

For this tutorial, the final potential is created with:
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.potential input=sampling output=potential.csv columns=devpressure_2,road_dens_perc,slope,dist_interchanges_km,dist_to_water_km developed_column=urban_change_clip subregions_column=counties --o
</source>

We can now visualize the suitability surface using module {{AddonCmd|r.futures.potsurface}}. It creates initial development potential (suitability) raster from predictors and model coefficients and serves only for evaluating development potential model. The values of the resulting raster range from 0 to 1.

<source lang="bash">
r.futures.potsurface input=potential.csv subregions=counties output=suitability
r.colors map=suitability color=byr
</source>

== Demand submodel ==
First we will mask out roads so that they don't influence into per capita land demand relation.
<source lang="bash">
v.to.rast input=roads type=line output=roads_mask use=val
r.mask roads_mask -i
</source>

We will use {{AddonCmd|r.futures.demand}} which derives the population vs. development relation. The relation can be linear/logarithmic/logarithmic2/exponential/exponential approach.
Look for examples of the different relations in the manual.

* linear: y = A + Bx
* logarithmic: y = A + Bln(x)
* logarithmic2: y = A + B * ln(x - C)        (requires SciPy)
* exponential: y = Ae^(BX)
* exp_approach: y = (1 - e^(-A(x - B))) + C        (requires SciPy)

The format of the input population CSV files is described in the manual. It is important to have synchronized categories of subregions and the column headers of the CSV files (in our case FIPS number). How to simply generate the list of years (for which demand is computed) is described in {{AddonCmd|r.futures.demand}} manual, for example run this in Python console:

<source lang="python">
','.join([str(i) for i in range(2011, 2036)])
</source>

Then we can create the DEMAND file:
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.demand development=urban_1992,urban_2001,urban_2011 subregions=counties observed_population=population_trend.csv projected_population=population_projection.csv simulation_times=2011,2012,2013,2014,2015,2016,2017,2018,2019,2020,2021,2022,2023,2024,2025,2026,2027,2028,2029,2030,2031,2032,2033,2034,2035 plot=plot_demand.pdf demand=demand.csv separator=comma
</source>

In your current working directory, you should find files <tt>plot_demand.png</tt> and <tt>demand.csv</tt>.

If you have SciPy installed, you can experiment with other methods for fitting the functions:
<source lang="bash">
r.futures.demand ... method=logarithmic2
r.futures.demand ... method=exp_approach
</source>
If necessary, you can create a set of demand files produced by fitting each method separately and
then pick for each county the method which seems best and manually create a new demand file.

When you are finished, remove the mask as it is not needed for the next steps.
<source lang="bash">
r.mask -r
</source>

== Patch calibration ==
Patch calibration can be a very time consuming computation.
Therefore we select only one county (Buncombe):

<source lang="bash">
v.to.rast input=counties type=area where="FIPS == 37021" use=attr attribute_column=FIPS output=calib_county
g.region raster=calib_county zoom=calib_county
</source>
to derive patches of new development by comparing historical and latest development.
We can keep only patches with minimum size 2 cells (1800 = 2 x 30 x 30 m).

<source lang="bash">
r.futures.calib development_start=urban_1992 development_end=urban_2011 subregions=counties patch_sizes=patches.txt patch_threshold=1800 -l
</source>
We obtained a file <tt>patches.txt</tt> (used later in the PGA) - a patch size distribution file - containing sizes of all found patches.

We can look at the distribution of the patch sizes:

<source lang="python">
from matplotlib import pyplot as plt
with open('patches.txt') as f:
patches = [int(patch) for patch in f.readlines()]
plt.hist(patches, 2000)
plt.xlim(0,50)
plt.show()
</source>

At this point, we start the calibration to get best parameters of patch shape
(for this tutorial, this step can be skipped and the suggested parameters are used).

<source lang="bash"
style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.calib development_start=urban_1992 development_end=urban_2011 subregions=calib_county patch_sizes=patches.txt calibration_results=calib.csv patch_threshold=1800 repeat=5 compactness_mean=0.1,0.3,0.5,0.7,0.9 compactness_range=0.05 discount_factor=0.1,0.3,0.5,0.7,0.9 predictors=road_dens_perc,forest_smooth_perc,dist_to_protected_km demand=demand.csv devpot_params=potential.csv num_neighbors=4 seed_search=2 development_pressure=devpressure_0_5 development_pressure_approach=gravity n_dev_neighbourhood=30 gamma=0.5 scaling_factor=0.1
</source>

== FUTURES simulation ==
We will switch back to our previous region:
<source lang="bash">
g.region raster=landuse_2011 -p
</source>

Now we have all the inputs necessary for running {{AddonCmd|r.futures.pga}}:

The entire command is here:
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.pga subregions=counties developed=urban_2011 predictors=slope,forest_smooth_perc,dist_interchanges_km,travel_time_cities devpot_params=potential.csv development_pressure=devpressure_1 n_dev_neighbourhood=10 development_pressure_approach=gravity gamma=1 scaling_factor=1 demand=demand.csv discount_factor=0.3 compactness_mean=0.2 compactness_range=0.1 patch_sizes=patches.txt num_neighbors=4 seed_search=2 random_seed=1 output=final output_series=final
</source>

=== Quick description ===
The command parameters and their values:
* raster map of counties with their categories
<code>
... subregions=counties ...
</code>

* raster of developed (1), undeveloped (0) and NULLs for undevelopable areas
<code>
... developed=urban_2011 ...
</code>

* predictors selected with {{AddonCmd|r.futures.potential}} and their coefficients in a <tt>potential.csv</tt> file. The order of predictors must match the order in the file and the categories of the counties must match raster <tt>counties</tt>.
<code>
... predictors=slope,forest_smooth_perc,dist_interchanges_km,travel_time_cities devpot_params=potential.csv ...
</code>

* initial development pressure computed by {{AddonCmd|r.futures.devpressure}}, it's important to set here the same parameters
<code>
... development_pressure=devpressure_1 n_dev_neighbourhood=10 development_pressure_approach=gravity gamma=1 scaling_factor=1 ...
</code>

* per capita land demand computed by {{AddonCmd|r.futures.demand}}, the categories of the counties must match raster <tt>counties</tt>.
<code>
... demand=demand.csv ...
</code>

* patch parameters from the calibration step
<code>
... discount_factor=0.3 compactness_mean=0.4 compactness_range=0.08 patch_sizes=patches.txt ...
</code>

* recommended parameters for patch growing algorithm
<code>
... num_neighbors=4 seed_search=2 ...
</code>

* set random seed for repeatable results or set flag <tt>-s</tt> to generate seed automatically
<code>
... random_seed=1 ...
</code>

* specify final output map and optionally basename for intermediate raster maps
<code>
output=final output_series=final
</code>

== Scenarios ==
Scenarios involving policies that encourage infill versus sprawl can be explored using the <tt>incentive_power</tt> parameter of {{AddonCmd|r.futures.pga}},
which uses a power function to transform the evenness of the probability gradient in POTENTIAL. You can change the power to a number between 0.25 and 4 to test urban sprawl/infill scenarios.
Higher power leads to infill behavior, lower power to urban sprawl.

== Postprocessing ==

Follow a [[Creating_animation_from_FUTURES_output_in_GRASS_GIS| tutorial how to make an animation from the results]].

= GRASS GIS Python API =

[[Category: Tutorial]]
[[Category: FUTURES]]
[[Category: Urban]]

Workshop on urban growth modeling with FUTURES

2016-03-22T16:55:04Z

⚠️Dbvanber: /* Software */

{{ToModify}}
= Workshop introduction =
r.futures.* is an implementation of the '''FUT'''ure '''U'''rban-'''R'''egional '''E'''nvironment '''S'''imulation (FUTURES)[1] which is a model for multilevel simulations of emerging urban-rural landscape structure. FUTURES produces regional projections of landscape patterns using coupled submodels that integrate nonstationary drivers of land change: per capita demand (DEMAND submodel), site suitability (POTENTIAL submodel), and the spatial structure of conversion events (PGA submodel).

[1] Meentemeyer, R. K., Tang, W., Dorning, M. A., Vogler, J. B., Cunniffe, N. J., & Shoemaker, D. A. (2013). [http://www.tandfonline.com/doi/abs/10.1080/00045608.2012.707591 FUTURES: multilevel simulations of emerging urban-rural landscape structure using a stochastic patch-growing algorithm.] Annals of the Association of American Geographers, 103(4), 785-807

== Software ==
There are a number of software requirements to run FUTURES that will need to be download and installed. Required software includes:
* GRASS GIS 7
* addons
** {{AddonCmd|r.futures.pga}}
** {{AddonCmd|r.futures.potential}}
** {{AddonCmd|r.futures.potsurface}}
** {{AddonCmd|r.futures.demand}}
** {{AddonCmd|r.futures.devpressure}}
** {{AddonCmd|r.sample.category}}
* R (≥ 3.0.2) - needed for {{AddonCmd|r.futures.potential}} with packages:
**MuMIn, lme4, optparse, rgrass7
* SciPy - useful for {{AddonCmd|r.futures.demand}}

=== Installation ===
We use the R statistical software for our calculation of site suitability (i.e. development potential) in FUTURES. R is a free software environment for statistical computing and graphics. If you don't have R, or you have older an version, please download and install the software from [http://archive.linux.duke.edu/cran/ install R] and be sure to additionally add these required packages:
<pre>
install.packages(c("MuMIn", "lme4", "optparse", "rgrass7"))
</pre>

==== MS Windows ====
We will be using GRASS GIS 7.0.3 that can be found here in the [https://trac.osgeo.org/osgeo4w/ OSGeo4W] package manager.
Please install the latest stable GRASS GIS 7 version and the SciPy Python package using the ''Advanced install'' option.
A guide with step by step screen shot instructions is available [https://docs.google.com/presentation/d/1yEGpriBne7RvjB35HI6GecNwO1P1y2nRGqDThqoNnCE/edit?usp=sharing here].

In order for GRASS to be able to find R executables, GRASS must be on the PATH variable. Follow this [solution] to make R accessible from GRASS permanently.
A simple but temporary solution is to open GRASS GIS and paste this in the black terminal:
<pre>
set PATH=%PATH%;C:\Program Files\R\R-3.0.2\bin
</pre>
This has to be repeated after restarting GRASS session.

==== Ubuntu Linux ====
Install GRASS GIS from packages:
<pre>
sudo add-apt-repository ppa:ubuntugis/ubuntugis-unstable
sudo apt-get update
sudo apt-get install grass
</pre>

== Workshop data ==
The data that we will be using for the workshop can be download here: [http://fatra.cnr.ncsu.edu/futures/futures_ncspm_Asheville.zip sample dataset]. Please place these layers in your local GRASS directory:
* digital elevation model ([http://nationalmap.gov/elevation.html NED])
* [http://www.mrlc.gov/ NLCD] 2001, 2011
* NLCD 1992/2001 Retrofit Land Cover Change Product
* transportation network ([http://www.census.gov/geo/maps-data/data/tiger-line.html TIGER])
* county boundaries ([http://www.census.gov/geo/maps-data/data/tiger-line.html TIGER])
* protected areas ([http://www.conservationgateway.org/ConservationByGeography/NorthAmerica/UnitedStates/edc/reportsdata/terrestrial/secured/Pages/default.aspx Secured Lands])
* cities as points (USGS)

In addition, download [http://fatra.cnr.ncsu.edu/futures/futures_Asheville_files.zip population information as text files]:
* county population past estimates and future projections ([https://www.osbm.nc.gov/demog/county-projections NC OSBM]) per county (nonspatial)

= GRASS GIS introduction =
* Overview of GRASS GIS project: [https://grass.osgeo.org grass.osgeo.org]
* Overview of [https://grass.osgeo.org/grass71/manuals/grass_database.html GRASS database].
** ''GRASS database'': directory with Locations (projects)
** ''Location'': directory with Mapsets, defined by projection (spatial reference system)
** ''Mapset'': collection of maps
* Download the [http://fatra.cnr.ncsu.edu/futures/futures_ncspm_Asheville.zip workshop location]. Create (unless you already have it) a directory named <tt>grassdata</tt> (GRASS database) in your home folder (or Documents), unzip the downloaded data into this directory. You should have now Location <tt>futures_ncspm</tt> in <tt>grassdata</tt>.
* Launch GRASS and display raster, vector data, explore navigation, querying, adding legend, showing metadata
<center><gallery perrow=3 widths=500 heights=250>Image:GRASS FUTURES startup.png|GRASS GIS 7.0.3 startup dialog with downloaded Location and Mapsets for FUTURES workshop
Image:GRASS FUTURES wxGUI display.png|Layer Manager and Map Display overview. Annotations show how to add raster layer, query, add legend.
Image:wxGUI_metadata_rinfo.png|Show raster map metadata by right click on layer</gallery></center>

* GRASS GIS has over [https://grass.osgeo.org/grass70/manuals/full_index.html 500 different modules] in the core distribution and over [https://grass.osgeo.org/grass70/manuals/addons/ 230 addon modules]
<center>
{| class="wikitable"
|-
! Prefix !! Function !! Example
|-
| r.* || raster processing || ''{{cmd|r.mapcalc}}'': map algebra
|-
| v.* || vector processing || ''{{cmd|v.clean}}'': topological cleaning
|-
| i.* || imagery processing || ''{{cmd|i.segment}}'': object recognition
|-
| db.* || database management || ''{{cmd|db.select}}'': select values from table
|-
| r3.* || 3D raster processing || ''{{cmd|r3.stats}}'': 3D raster statistics
|-
| t.* || temporal data processing || ''{{cmd|t.rast.aggregate}}'': temporal aggregation
|-
| g.* || general data management || ''{{cmd|g.rename}}'': renames map
|-
| d.* || display ||''{{cmd|d.rast}}'': display raster map
|}</center>
* GRASS modules have GUI and command line interface. In this workshop we use commands to describe the workflow, but we can use both GUI and command line depending on personal preference. Look how {{cmd|wxGUI.modules|version=71|desc=GUI and command line interface}} represent the same tool. ''Task:'' compute aspect (orientation) from provided digital elevation model using module {{cmd|r.slope.aspect}} using both module dialog and command line.
* How to find modules? Modules are organized by their functionality in wxGUI menu, or we can search for them in Search modules tab. If we already know which module to use, we can just type it in the wxGUI command console. <center><gallery perrow=3 widths=380 heights=190>Image:wxGUI_menu_rinfo.png|Modules can be found in wxGUI menu
Image:wxGUI_module_search.png|You can search modules by name, description or keywords in ''Search modules'' tab
Image:wxGUI_console_completion.png|By typing prefix r. we make a list of modules starting with that prefix to show up.</gallery></center>


* {{cmd|g.region|desc=Computational region}} - an important raster concept
** defined by region extent and raster resolution
** applies to all raster operations
** persists between GRASS session, can be different for different mapsets
** advantages: keeps your results consistent, avoid clipping, for computationally demanding tasks set region to smaller extent, check your result is good and then set the computational region to the entire study area and rerun analysis
** run <code>g.region -p</code> or in menu ''Settings'' - ''Region'' - ''Display region'' to see current region settings
[[File:WxGUI set region.png|700px|thumb|center|Simple ways to set computational region from GUI. On the left, set region to match raster map. On the right, select the highlighted option and then set region by drawing rectangle.]]

* GRASS 3D view

= Modeling with FUTURES =
== Initial steps and data preparation ==
First we will set computational region of our analyses to an extent covering our study area and so that the cells are aligned with one of our landuse rasters:
<source lang="bash">g.region raster=landuse_2011 -p</source>

We will derive urbanized areas from NLCD dataset for year 1992, 2001 and 2011
by extracting categories category 21 - 24 into a new binary map where developed is 1,
undeveloped 0 and NULL (no data) is area unsuitable for development (water, wetlands, protected areas).
First we will convert protected areas from vector to raster. We set
NULLs to zeros (for simpler raster algebra expression in the next step) using {{cmd|r.null}}:

<source lang="bash">
v.to.rast input=protected_areas output=protected_areas use=val
r.null map=protected_areas null=0
</source>

And then create rasters of developed/undeveloped areas using raster algebra:

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.mapcalc "urban_1992 = if(landuse_1992 >= 21 && landuse_1992 <= 24, 1, if(landuse_1992 == 11 || landuse_1992 >= 90 || protected_areas, null(), 0))"
r.mapcalc "urban_2001 = if(landuse_2001 >= 21 && landuse_2001 <= 24, 1, if(landuse_2001 == 11 || landuse_2001 >= 90 || protected_areas, null(), 0))"
r.mapcalc "urban_2011 = if(landuse_2011 >= 21 && landuse_2011 <= 24, 1, if(landuse_2011 == 11 || landuse_2011 >= 90 || protected_areas, null(), 0))"
</source>

We will convert vector counties to raster with the values of the FIPS attribute which links to population file:

<source lang="bash">
v.to.rast input=counties type=area use=attr attribute_column=FIPS output=counties
</source>

Before further steps, we will set our working directory so that the input population files and text files
we are going to create are saved in one directory and easily accessible.
You can do that from menu ''Settings'' → ''GRASS working environment'' → ''Change working directory''.
Select (or create) a directory and move there the downloaded files <tt>population_projection.csv</tt> and <tt>population_trend.csv</tt>.

== Potential submodel ==
Module {{AddonCmd|r.futures.potential}} implements POTENTIAL submodel as a part of FUTURES land change model. POTENTIAL is implemented using a set of coefficients that relate a selection of site suitability factors to the probability of a place becoming developed. This is implemented using the parameter table in combination with maps of those site suitability factors (mapped predictors). The coefficients are obtained by conducting multilevel logistic regression in R with package lme4 where the coefficients may vary by county. The best model is selected automatically using dredge function from package [https://cran.r-project.org/web/packages/MuMIn/index.html MuMIn].

First, we will derive couple of predictors.
=== Predictors ===
==== Slope ====
We will derive slope in degrees from digital elevation model using {{cmd|r.slope.aspect}} module:
<source lang="bash">r.slope.aspect elevation=elevation_30m slope=slope</source>

==== Distance from lakes/rivers ====
First we will extract [http://www.mrlc.gov/nlcd11_leg.php category ''Open Water''] from 2011 NLCD dataset:
<source lang="bash">
r.mapcalc "water = if(landuse_2011 == 11, 1, null())"
</source>

Then we compute the distance to water with module {{cmd|r.grow.distance}} and set color table to shades of blue:
<source lang="bash">
r.grow.distance input=water distance=dist_to_water
r.colors -n map=dist_to_water color=blues
</source>

==== Distance from protected areas ====
We will use raster protected of protected areas we already created, but we will set NULL values to zero.
We compute the distance to protected areas with module {{cmd|r.grow.distance}} and set color table from green to red:
<source lang="bash">
r.null map=protected_areas setnull=0
r.grow.distance input=protected_areas distance=dist_to_protected
r.colors map=dist_to_protected color=gyr
</source>

==== Forests ====
We will smooth the transition between forest and other land use, see NLCD [http://www.mrlc.gov/nlcd11_leg.php category ''Open Water'']:
<source lang="bash">
r.mapcalc "forest = if(landuse_2011 >= 41 && landuse_2011 <= 43, 1, 0)"
r.neighbors -c input=forest output=forest_smooth size=15 method=average
r.colors map=forest_smooth color=ndvi
</source>

==== Travel time to cities ====
Here we will compute travel time to cities (with population > 5000)
as cumulative cost distance where cost is defined as travel time on roads.
First we specify the speed on different types of roads.
We copy the roads raster into our mapset so that we can change it
by adding a new attribute field <tt>speed</tt>. Then we assign speed values (km/h) based on the type of road:

<source lang="bash">
g.copy vector=roads,myroads
v.db.addcolumn map=myroads columns="speed double precision"
v.db.update map=myroads column=speed value=50 where="MTFCC = 'S1400'"
v.db.update map=myroads column=speed value=100 where="MTFCC IN ('S1100', 'S1200')"
</source>

Now we rasterize the selected road types using the speed values from the attribute table as raster values.

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
v.to.rast input=myroads type=line where="MTFCC IN ('S1100', 'S1200', 'S1400')" output=roads_speed use=attr attribute_column=speed
</source>

We set the rest of the area to low speed and recompute the speed as time to travel through a 30m cell in minutes:

<source lang="bash">
r.null map=roads_speed null=5
r.mapcalc "roads_travel_time = 1.8 / roads_speed"
</source>

Finally we compute the travel time to larger cities using {{cmd|r.cost}}:

<source lang="bash">
r.cost input=roads_travel_time output=travel_time_cities start_points=cities
r.colors map=travel_time_cities color=byr
</source>

==== Road density ====
We will rasterize roads and use moving window analysis ({{cmd|r.neighbors}}) to compute road density:

<source lang="bash">
v.to.rast input=roads output=roads use=val type=line
r.null map=roads null=0
r.neighbors -c input=roads output=road_dens size=25 method=average
</source>

==== Distance to interchanges ====

We will consider TIGER roads of type <tt>Ramp</tt> as interchanges, rasterize them and compute euclidean distance to them:

<source lang="bash">
v.to.rast input=roads type=line where="MTFCC = 'S1630'" output=interchanges use=val
r.grow.distance -m input=interchanges distance=dist_interchanges
</source>

=== Development pressure ===

We compute development pressure with {{AddonCmd|r.futures.devpressure}}. Development pressure is a predictor based on number of neighboring developed cells within search distance, weighted by distance. The development pressure variable plays a special role in the model, allowing for a feedback between predicted change and change in subsequent steps.

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.devpressure -n input=urban_2011 output=devpressure_2 method=gravity size=7 gamma=2 scaling_factor=10
r.futures.devpressure -n input=urban_2011 output=devpressure_1 method=gravity size=10 gamma=1 scaling_factor=1
r.futures.devpressure -n input=urban_2011 output=devpressure_0_5 method=gravity size=30 gamma=0.5 scaling_factor=0.1
</source>

When gamma increases, development influence decreases more rapidly with distance.
Size is half the size of the moving window. When gamma is low, local development influences more distant places.
We will derive 3 layers with different gamma and size parameters for the potential statistical model.

=== Rescaling variables ===

First we will look at the ranges of our predictor variables by running a short Python code snippet in Python shell:

<source lang="python" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
for name in ['slope', 'dist_to_water', 'dist_to_protected', 'forest_smooth', 'travel_time_cities', 'road_dens', 'dist_interchanges', 'devpressure_0_5', 'devpressure_1']:
minmax = grass.raster_info(name)
print name, minmax['min'], minmax['max']
</source>

We will rescale some of our input variables:

<source lang="bash">
r.mapcalc "dist_to_water_km = dist_to_water / 1000"
r.mapcalc "dist_to_protected_km = dist_to_protected / 1000"
r.mapcalc "dist_interchanges_km = dist_interchanges / 1000"
r.mapcalc "road_dens_perc = road_dens * 100"
r.mapcalc "forest_smooth_perc = forest_smooth * 100"
</source>

=== Sampling ===
To sample only in the analyzed counties, we will clip development layer:

<source lang="bash">
r.mapcalc "urban_change_01_11 = if(urban_2011 == 1, if(urban_2001 == 0, 1, null()), 0)"
r.mapcalc "urban_change_clip = if(counties, urban_change_01_11)"
</source>

To estimate the number of sampling points, we can use {{cmd|r.report}} to report number of developed/undeveloped cells and their ratio.

<source lang="bash">
r.report map=urban_change_clip units=h,c,p
</source>

We will sample the predictors and the response variable with 5000 random points in undeveloped areas and 1000 points in developed area:

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.sample.category input=urban_change_clip output=sampling sampled=counties,devpressure_0_5,devpressure_1,devpressure_2,slope,road_dens_perc,forest_smooth_perc,dist_to_water_km,dist_to_protected_km,dist_interchanges_km,travel_time_cities npoints=5000,1000
</source>

The attribute table can be exported as CSV file (not necessary step):

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
v.db.select map=sampling columns=urban_change_clip,counties,devpressure_0_5,devpressure_1,slope,road_dens_perc,forest_smooth_perc,dist_to_water_km,dist_to_protected_km,dist_interchanges_km,travel_time_cities separator=comma file=samples.csv
</source>

=== Development potential ===
Now we find best model for predicting urbanization using {{AddonCmd|r.futures.potential}} which wraps an R script.

We can run R [http://www.inside-r.org/packages/cran/MuMIn/docs/dredge dredge] function to find "best" model. We can specify minimum and maximum number of predictors the final model should use.
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.potential -d input=sampling output=potential.csv columns=devpressure_1,slope,road_dens_perc,forest_smooth_perc,dist_to_water_km,dist_to_protected_km,dist_interchanges_km,travel_time_cities developed_column=urban_change_clip subregions_column=counties min_variables=4
</source>

Also, we can play with different combinations of predictors, for example:

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.potential input=sampling output=potential.csv columns=devpressure_2,road_dens_perc,slope,dist_interchanges_km,dist_to_water_km developed_column=urban_change_clip subregions_column=counties --o
r.futures.potential input=sampling output=potential.csv columns=devpressure_1,road_dens_perc,slope,dist_interchanges_km,dist_to_water_km developed_column=urban_change_clip subregions_column=counties --o
...
</source>

You can then open the output file <tt>potential.csv</tt>, which is a CSV file with tabs as separators.

For this tutorial, the final potential is created with:
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.potential input=sampling output=potential.csv columns=devpressure_2,road_dens_perc,slope,dist_interchanges_km,dist_to_water_km developed_column=urban_change_clip subregions_column=counties --o
</source>

We can now visualize the suitability surface using module {{AddonCmd|r.futures.potsurface}}. It creates initial development potential (suitability) raster from predictors and model coefficients and serves only for evaluating development potential model. The values of the resulting raster range from 0 to 1.

<source lang="bash">
r.futures.potsurface input=potential.csv subregions=counties output=suitability
r.colors map=suitability color=byr
</source>

== Demand submodel ==
First we will mask out roads so that they don't influence into per capita land demand relation.
<source lang="bash">
v.to.rast input=roads type=line output=roads_mask use=val
r.mask roads_mask -i
</source>

We will use {{AddonCmd|r.futures.demand}} which derives the population vs. development relation. The relation can be linear/logarithmic/logarithmic2/exponential/exponential approach.
Look for examples of the different relations in the manual.

* linear: y = A + Bx
* logarithmic: y = A + Bln(x)
* logarithmic2: y = A + B * ln(x - C)        (requires SciPy)
* exponential: y = Ae^(BX)
* exp_approach: y = (1 - e^(-A(x - B))) + C        (requires SciPy)

The format of the input population CSV files is described in the manual. It is important to have synchronized categories of subregions and the column headers of the CSV files (in our case FIPS number). How to simply generate the list of years (for which demand is computed) is described in {{AddonCmd|r.futures.demand}} manual, for example run this in Python console:

<source lang="python">
','.join([str(i) for i in range(2011, 2036)])
</source>

Then we can create the DEMAND file:
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.demand development=urban_1992,urban_2001,urban_2011 subregions=counties observed_population=population_trend.csv projected_population=population_projection.csv simulation_times=2011,2012,2013,2014,2015,2016,2017,2018,2019,2020,2021,2022,2023,2024,2025,2026,2027,2028,2029,2030,2031,2032,2033,2034,2035 plot=plot_demand.pdf demand=demand.csv separator=comma
</source>

In your current working directory, you should find files <tt>plot_demand.png</tt> and <tt>demand.csv</tt>.

If you have SciPy installed, you can experiment with other methods for fitting the functions:
<source lang="bash">
r.futures.demand ... method=logarithmic2
r.futures.demand ... method=exp_approach
</source>
If necessary, you can create a set of demand files produced by fitting each method separately and
then pick for each county the method which seems best and manually create a new demand file.

When you are finished, remove the mask as it is not needed for the next steps.
<source lang="bash">
r.mask -r
</source>

== Patch calibration ==
Patch calibration can be a very time consuming computation.
Therefore we select only one county (Buncombe):

<source lang="bash">
v.to.rast input=counties type=area where="FIPS == 37021" use=attr attribute_column=FIPS output=calib_county
g.region raster=calib_county zoom=calib_county
</source>
to derive patches of new development by comparing historical and latest development.
We can keep only patches with minimum size 2 cells (1800 = 2 x 30 x 30 m).

<source lang="bash">
r.futures.calib development_start=urban_1992 development_end=urban_2011 subregions=counties patch_sizes=patches.txt patch_threshold=1800 -l
</source>
We obtained a file <tt>patches.txt</tt> (used later in the PGA) - a patch size distribution file - containing sizes of all found patches.

We can look at the distribution of the patch sizes:

<source lang="python">
from matplotlib import pyplot as plt
with open('patches.txt') as f:
patches = [int(patch) for patch in f.readlines()]
plt.hist(patches, 2000)
plt.xlim(0,50)
plt.show()
</source>

At this point, we start the calibration to get best parameters of patch shape
(for this tutorial, this step can be skipped and the suggested parameters are used).

<source lang="bash"
style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.calib development_start=urban_1992 development_end=urban_2011 subregions=calib_county patch_sizes=patches.txt calibration_results=calib.csv patch_threshold=1800 repeat=5 compactness_mean=0.1,0.3,0.5,0.7,0.9 compactness_range=0.05 discount_factor=0.1,0.3,0.5,0.7,0.9 predictors=road_dens_perc,forest_smooth_perc,dist_to_protected_km demand=demand.csv devpot_params=potential.csv num_neighbors=4 seed_search=2 development_pressure=devpressure_0_5 development_pressure_approach=gravity n_dev_neighbourhood=30 gamma=0.5 scaling_factor=0.1
</source>

== FUTURES simulation ==
We will switch back to our previous region:
<source lang="bash">
g.region raster=landuse_2011 -p
</source>

Now we have all the inputs necessary for running {{AddonCmd|r.futures.pga}}:

The entire command is here:
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.pga subregions=counties developed=urban_2011 predictors=slope,forest_smooth_perc,dist_interchanges_km,travel_time_cities devpot_params=potential.csv development_pressure=devpressure_1 n_dev_neighbourhood=10 development_pressure_approach=gravity gamma=1 scaling_factor=1 demand=demand.csv discount_factor=0.3 compactness_mean=0.2 compactness_range=0.1 patch_sizes=patches.txt num_neighbors=4 seed_search=2 random_seed=1 output=final output_series=final
</source>

=== Quick description ===
The command parameters and their values:
* raster map of counties with their categories
<code>
... subregions=counties ...
</code>

* raster of developed (1), undeveloped (0) and NULLs for undevelopable areas
<code>
... developed=urban_2011 ...
</code>

* predictors selected with {{AddonCmd|r.futures.potential}} and their coefficients in a <tt>potential.csv</tt> file. The order of predictors must match the order in the file and the categories of the counties must match raster <tt>counties</tt>.
<code>
... predictors=slope,forest_smooth_perc,dist_interchanges_km,travel_time_cities devpot_params=potential.csv ...
</code>

* initial development pressure computed by {{AddonCmd|r.futures.devpressure}}, it's important to set here the same parameters
<code>
... development_pressure=devpressure_1 n_dev_neighbourhood=10 development_pressure_approach=gravity gamma=1 scaling_factor=1 ...
</code>

* per capita land demand computed by {{AddonCmd|r.futures.demand}}, the categories of the counties must match raster <tt>counties</tt>.
<code>
... demand=demand.csv ...
</code>

* patch parameters from the calibration step
<code>
... discount_factor=0.3 compactness_mean=0.4 compactness_range=0.08 patch_sizes=patches.txt ...
</code>

* recommended parameters for patch growing algorithm
<code>
... num_neighbors=4 seed_search=2 ...
</code>

* set random seed for repeatable results or set flag <tt>-s</tt> to generate seed automatically
<code>
... random_seed=1 ...
</code>

* specify final output map and optionally basename for intermediate raster maps
<code>
output=final output_series=final
</code>

== Scenarios ==
Scenarios involving policies that encourage infill versus sprawl can be explored using the <tt>incentive_power</tt> parameter of {{AddonCmd|r.futures.pga}},
which uses a power function to transform the evenness of the probability gradient in POTENTIAL. You can change the power to a number between 0.25 and 4 to test urban sprawl/infill scenarios.
Higher power leads to infill behavior, lower power to urban sprawl.

== Postprocessing ==

Follow a [[Creating_animation_from_FUTURES_output_in_GRASS_GIS| tutorial how to make an animation from the results]].

= GRASS GIS Python API =

[[Category: Tutorial]]
[[Category: FUTURES]]
[[Category: Urban]]

Workshop on urban growth modeling with FUTURES

2016-03-22T16:54:46Z

⚠️Dbvanber: /* Installation */

{{ToModify}}
= Workshop introduction =
r.futures.* is an implementation of the '''FUT'''ure '''U'''rban-'''R'''egional '''E'''nvironment '''S'''imulation (FUTURES)[1] which is a model for multilevel simulations of emerging urban-rural landscape structure. FUTURES produces regional projections of landscape patterns using coupled submodels that integrate nonstationary drivers of land change: per capita demand (DEMAND submodel), site suitability (POTENTIAL submodel), and the spatial structure of conversion events (PGA submodel).

[1] Meentemeyer, R. K., Tang, W., Dorning, M. A., Vogler, J. B., Cunniffe, N. J., & Shoemaker, D. A. (2013). [http://www.tandfonline.com/doi/abs/10.1080/00045608.2012.707591 FUTURES: multilevel simulations of emerging urban-rural landscape structure using a stochastic patch-growing algorithm.] Annals of the Association of American Geographers, 103(4), 785-807

== Software ==
Required software includes:
* GRASS GIS 7
* addons
** {{AddonCmd|r.futures.pga}}
** {{AddonCmd|r.futures.potential}}
** {{AddonCmd|r.futures.potsurface}}
** {{AddonCmd|r.futures.demand}}
** {{AddonCmd|r.futures.devpressure}}
** {{AddonCmd|r.sample.category}}
* R (≥ 3.0.2) - needed for {{AddonCmd|r.futures.potential}} with packages:
**MuMIn, lme4, optparse, rgrass7
* SciPy - useful for {{AddonCmd|r.futures.demand}}

=== Installation ===
We use the R statistical software for our calculation of site suitability (i.e. development potential) in FUTURES. R is a free software environment for statistical computing and graphics. If you don't have R, or you have older an version, please download and install the software from [http://archive.linux.duke.edu/cran/ install R] and be sure to additionally add these required packages:
<pre>
install.packages(c("MuMIn", "lme4", "optparse", "rgrass7"))
</pre>

==== MS Windows ====
We will be using GRASS GIS 7.0.3 that can be found here in the [https://trac.osgeo.org/osgeo4w/ OSGeo4W] package manager.
Please install the latest stable GRASS GIS 7 version and the SciPy Python package using the ''Advanced install'' option.
A guide with step by step screen shot instructions is available [https://docs.google.com/presentation/d/1yEGpriBne7RvjB35HI6GecNwO1P1y2nRGqDThqoNnCE/edit?usp=sharing here].

In order for GRASS to be able to find R executables, GRASS must be on the PATH variable. Follow this [solution] to make R accessible from GRASS permanently.
A simple but temporary solution is to open GRASS GIS and paste this in the black terminal:
<pre>
set PATH=%PATH%;C:\Program Files\R\R-3.0.2\bin
</pre>
This has to be repeated after restarting GRASS session.

==== Ubuntu Linux ====
Install GRASS GIS from packages:
<pre>
sudo add-apt-repository ppa:ubuntugis/ubuntugis-unstable
sudo apt-get update
sudo apt-get install grass
</pre>

== Workshop data ==
The data that we will be using for the workshop can be download here: [http://fatra.cnr.ncsu.edu/futures/futures_ncspm_Asheville.zip sample dataset]. Please place these layers in your local GRASS directory:
* digital elevation model ([http://nationalmap.gov/elevation.html NED])
* [http://www.mrlc.gov/ NLCD] 2001, 2011
* NLCD 1992/2001 Retrofit Land Cover Change Product
* transportation network ([http://www.census.gov/geo/maps-data/data/tiger-line.html TIGER])
* county boundaries ([http://www.census.gov/geo/maps-data/data/tiger-line.html TIGER])
* protected areas ([http://www.conservationgateway.org/ConservationByGeography/NorthAmerica/UnitedStates/edc/reportsdata/terrestrial/secured/Pages/default.aspx Secured Lands])
* cities as points (USGS)

In addition, download [http://fatra.cnr.ncsu.edu/futures/futures_Asheville_files.zip population information as text files]:
* county population past estimates and future projections ([https://www.osbm.nc.gov/demog/county-projections NC OSBM]) per county (nonspatial)

= GRASS GIS introduction =
* Overview of GRASS GIS project: [https://grass.osgeo.org grass.osgeo.org]
* Overview of [https://grass.osgeo.org/grass71/manuals/grass_database.html GRASS database].
** ''GRASS database'': directory with Locations (projects)
** ''Location'': directory with Mapsets, defined by projection (spatial reference system)
** ''Mapset'': collection of maps
* Download the [http://fatra.cnr.ncsu.edu/futures/futures_ncspm_Asheville.zip workshop location]. Create (unless you already have it) a directory named <tt>grassdata</tt> (GRASS database) in your home folder (or Documents), unzip the downloaded data into this directory. You should have now Location <tt>futures_ncspm</tt> in <tt>grassdata</tt>.
* Launch GRASS and display raster, vector data, explore navigation, querying, adding legend, showing metadata
<center><gallery perrow=3 widths=500 heights=250>Image:GRASS FUTURES startup.png|GRASS GIS 7.0.3 startup dialog with downloaded Location and Mapsets for FUTURES workshop
Image:GRASS FUTURES wxGUI display.png|Layer Manager and Map Display overview. Annotations show how to add raster layer, query, add legend.
Image:wxGUI_metadata_rinfo.png|Show raster map metadata by right click on layer</gallery></center>

* GRASS GIS has over [https://grass.osgeo.org/grass70/manuals/full_index.html 500 different modules] in the core distribution and over [https://grass.osgeo.org/grass70/manuals/addons/ 230 addon modules]
<center>
{| class="wikitable"
|-
! Prefix !! Function !! Example
|-
| r.* || raster processing || ''{{cmd|r.mapcalc}}'': map algebra
|-
| v.* || vector processing || ''{{cmd|v.clean}}'': topological cleaning
|-
| i.* || imagery processing || ''{{cmd|i.segment}}'': object recognition
|-
| db.* || database management || ''{{cmd|db.select}}'': select values from table
|-
| r3.* || 3D raster processing || ''{{cmd|r3.stats}}'': 3D raster statistics
|-
| t.* || temporal data processing || ''{{cmd|t.rast.aggregate}}'': temporal aggregation
|-
| g.* || general data management || ''{{cmd|g.rename}}'': renames map
|-
| d.* || display ||''{{cmd|d.rast}}'': display raster map
|}</center>
* GRASS modules have GUI and command line interface. In this workshop we use commands to describe the workflow, but we can use both GUI and command line depending on personal preference. Look how {{cmd|wxGUI.modules|version=71|desc=GUI and command line interface}} represent the same tool. ''Task:'' compute aspect (orientation) from provided digital elevation model using module {{cmd|r.slope.aspect}} using both module dialog and command line.
* How to find modules? Modules are organized by their functionality in wxGUI menu, or we can search for them in Search modules tab. If we already know which module to use, we can just type it in the wxGUI command console. <center><gallery perrow=3 widths=380 heights=190>Image:wxGUI_menu_rinfo.png|Modules can be found in wxGUI menu
Image:wxGUI_module_search.png|You can search modules by name, description or keywords in ''Search modules'' tab
Image:wxGUI_console_completion.png|By typing prefix r. we make a list of modules starting with that prefix to show up.</gallery></center>


* {{cmd|g.region|desc=Computational region}} - an important raster concept
** defined by region extent and raster resolution
** applies to all raster operations
** persists between GRASS session, can be different for different mapsets
** advantages: keeps your results consistent, avoid clipping, for computationally demanding tasks set region to smaller extent, check your result is good and then set the computational region to the entire study area and rerun analysis
** run <code>g.region -p</code> or in menu ''Settings'' - ''Region'' - ''Display region'' to see current region settings
[[File:WxGUI set region.png|700px|thumb|center|Simple ways to set computational region from GUI. On the left, set region to match raster map. On the right, select the highlighted option and then set region by drawing rectangle.]]

* GRASS 3D view

= Modeling with FUTURES =
== Initial steps and data preparation ==
First we will set computational region of our analyses to an extent covering our study area and so that the cells are aligned with one of our landuse rasters:
<source lang="bash">g.region raster=landuse_2011 -p</source>

We will derive urbanized areas from NLCD dataset for year 1992, 2001 and 2011
by extracting categories category 21 - 24 into a new binary map where developed is 1,
undeveloped 0 and NULL (no data) is area unsuitable for development (water, wetlands, protected areas).
First we will convert protected areas from vector to raster. We set
NULLs to zeros (for simpler raster algebra expression in the next step) using {{cmd|r.null}}:

<source lang="bash">
v.to.rast input=protected_areas output=protected_areas use=val
r.null map=protected_areas null=0
</source>

And then create rasters of developed/undeveloped areas using raster algebra:

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.mapcalc "urban_1992 = if(landuse_1992 >= 21 && landuse_1992 <= 24, 1, if(landuse_1992 == 11 || landuse_1992 >= 90 || protected_areas, null(), 0))"
r.mapcalc "urban_2001 = if(landuse_2001 >= 21 && landuse_2001 <= 24, 1, if(landuse_2001 == 11 || landuse_2001 >= 90 || protected_areas, null(), 0))"
r.mapcalc "urban_2011 = if(landuse_2011 >= 21 && landuse_2011 <= 24, 1, if(landuse_2011 == 11 || landuse_2011 >= 90 || protected_areas, null(), 0))"
</source>

We will convert vector counties to raster with the values of the FIPS attribute which links to population file:

<source lang="bash">
v.to.rast input=counties type=area use=attr attribute_column=FIPS output=counties
</source>

Before further steps, we will set our working directory so that the input population files and text files
we are going to create are saved in one directory and easily accessible.
You can do that from menu ''Settings'' → ''GRASS working environment'' → ''Change working directory''.
Select (or create) a directory and move there the downloaded files <tt>population_projection.csv</tt> and <tt>population_trend.csv</tt>.

== Potential submodel ==
Module {{AddonCmd|r.futures.potential}} implements POTENTIAL submodel as a part of FUTURES land change model. POTENTIAL is implemented using a set of coefficients that relate a selection of site suitability factors to the probability of a place becoming developed. This is implemented using the parameter table in combination with maps of those site suitability factors (mapped predictors). The coefficients are obtained by conducting multilevel logistic regression in R with package lme4 where the coefficients may vary by county. The best model is selected automatically using dredge function from package [https://cran.r-project.org/web/packages/MuMIn/index.html MuMIn].

First, we will derive couple of predictors.
=== Predictors ===
==== Slope ====
We will derive slope in degrees from digital elevation model using {{cmd|r.slope.aspect}} module:
<source lang="bash">r.slope.aspect elevation=elevation_30m slope=slope</source>

==== Distance from lakes/rivers ====
First we will extract [http://www.mrlc.gov/nlcd11_leg.php category ''Open Water''] from 2011 NLCD dataset:
<source lang="bash">
r.mapcalc "water = if(landuse_2011 == 11, 1, null())"
</source>

Then we compute the distance to water with module {{cmd|r.grow.distance}} and set color table to shades of blue:
<source lang="bash">
r.grow.distance input=water distance=dist_to_water
r.colors -n map=dist_to_water color=blues
</source>

==== Distance from protected areas ====
We will use raster protected of protected areas we already created, but we will set NULL values to zero.
We compute the distance to protected areas with module {{cmd|r.grow.distance}} and set color table from green to red:
<source lang="bash">
r.null map=protected_areas setnull=0
r.grow.distance input=protected_areas distance=dist_to_protected
r.colors map=dist_to_protected color=gyr
</source>

==== Forests ====
We will smooth the transition between forest and other land use, see NLCD [http://www.mrlc.gov/nlcd11_leg.php category ''Open Water'']:
<source lang="bash">
r.mapcalc "forest = if(landuse_2011 >= 41 && landuse_2011 <= 43, 1, 0)"
r.neighbors -c input=forest output=forest_smooth size=15 method=average
r.colors map=forest_smooth color=ndvi
</source>

==== Travel time to cities ====
Here we will compute travel time to cities (with population > 5000)
as cumulative cost distance where cost is defined as travel time on roads.
First we specify the speed on different types of roads.
We copy the roads raster into our mapset so that we can change it
by adding a new attribute field <tt>speed</tt>. Then we assign speed values (km/h) based on the type of road:

<source lang="bash">
g.copy vector=roads,myroads
v.db.addcolumn map=myroads columns="speed double precision"
v.db.update map=myroads column=speed value=50 where="MTFCC = 'S1400'"
v.db.update map=myroads column=speed value=100 where="MTFCC IN ('S1100', 'S1200')"
</source>

Now we rasterize the selected road types using the speed values from the attribute table as raster values.

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
v.to.rast input=myroads type=line where="MTFCC IN ('S1100', 'S1200', 'S1400')" output=roads_speed use=attr attribute_column=speed
</source>

We set the rest of the area to low speed and recompute the speed as time to travel through a 30m cell in minutes:

<source lang="bash">
r.null map=roads_speed null=5
r.mapcalc "roads_travel_time = 1.8 / roads_speed"
</source>

Finally we compute the travel time to larger cities using {{cmd|r.cost}}:

<source lang="bash">
r.cost input=roads_travel_time output=travel_time_cities start_points=cities
r.colors map=travel_time_cities color=byr
</source>

==== Road density ====
We will rasterize roads and use moving window analysis ({{cmd|r.neighbors}}) to compute road density:

<source lang="bash">
v.to.rast input=roads output=roads use=val type=line
r.null map=roads null=0
r.neighbors -c input=roads output=road_dens size=25 method=average
</source>

==== Distance to interchanges ====

We will consider TIGER roads of type <tt>Ramp</tt> as interchanges, rasterize them and compute euclidean distance to them:

<source lang="bash">
v.to.rast input=roads type=line where="MTFCC = 'S1630'" output=interchanges use=val
r.grow.distance -m input=interchanges distance=dist_interchanges
</source>

=== Development pressure ===

We compute development pressure with {{AddonCmd|r.futures.devpressure}}. Development pressure is a predictor based on number of neighboring developed cells within search distance, weighted by distance. The development pressure variable plays a special role in the model, allowing for a feedback between predicted change and change in subsequent steps.

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.devpressure -n input=urban_2011 output=devpressure_2 method=gravity size=7 gamma=2 scaling_factor=10
r.futures.devpressure -n input=urban_2011 output=devpressure_1 method=gravity size=10 gamma=1 scaling_factor=1
r.futures.devpressure -n input=urban_2011 output=devpressure_0_5 method=gravity size=30 gamma=0.5 scaling_factor=0.1
</source>

When gamma increases, development influence decreases more rapidly with distance.
Size is half the size of the moving window. When gamma is low, local development influences more distant places.
We will derive 3 layers with different gamma and size parameters for the potential statistical model.

=== Rescaling variables ===

First we will look at the ranges of our predictor variables by running a short Python code snippet in Python shell:

<source lang="python" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
for name in ['slope', 'dist_to_water', 'dist_to_protected', 'forest_smooth', 'travel_time_cities', 'road_dens', 'dist_interchanges', 'devpressure_0_5', 'devpressure_1']:
minmax = grass.raster_info(name)
print name, minmax['min'], minmax['max']
</source>

We will rescale some of our input variables:

<source lang="bash">
r.mapcalc "dist_to_water_km = dist_to_water / 1000"
r.mapcalc "dist_to_protected_km = dist_to_protected / 1000"
r.mapcalc "dist_interchanges_km = dist_interchanges / 1000"
r.mapcalc "road_dens_perc = road_dens * 100"
r.mapcalc "forest_smooth_perc = forest_smooth * 100"
</source>

=== Sampling ===
To sample only in the analyzed counties, we will clip development layer:

<source lang="bash">
r.mapcalc "urban_change_01_11 = if(urban_2011 == 1, if(urban_2001 == 0, 1, null()), 0)"
r.mapcalc "urban_change_clip = if(counties, urban_change_01_11)"
</source>

To estimate the number of sampling points, we can use {{cmd|r.report}} to report number of developed/undeveloped cells and their ratio.

<source lang="bash">
r.report map=urban_change_clip units=h,c,p
</source>

We will sample the predictors and the response variable with 5000 random points in undeveloped areas and 1000 points in developed area:

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.sample.category input=urban_change_clip output=sampling sampled=counties,devpressure_0_5,devpressure_1,devpressure_2,slope,road_dens_perc,forest_smooth_perc,dist_to_water_km,dist_to_protected_km,dist_interchanges_km,travel_time_cities npoints=5000,1000
</source>

The attribute table can be exported as CSV file (not necessary step):

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
v.db.select map=sampling columns=urban_change_clip,counties,devpressure_0_5,devpressure_1,slope,road_dens_perc,forest_smooth_perc,dist_to_water_km,dist_to_protected_km,dist_interchanges_km,travel_time_cities separator=comma file=samples.csv
</source>

=== Development potential ===
Now we find best model for predicting urbanization using {{AddonCmd|r.futures.potential}} which wraps an R script.

We can run R [http://www.inside-r.org/packages/cran/MuMIn/docs/dredge dredge] function to find "best" model. We can specify minimum and maximum number of predictors the final model should use.
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.potential -d input=sampling output=potential.csv columns=devpressure_1,slope,road_dens_perc,forest_smooth_perc,dist_to_water_km,dist_to_protected_km,dist_interchanges_km,travel_time_cities developed_column=urban_change_clip subregions_column=counties min_variables=4
</source>

Also, we can play with different combinations of predictors, for example:

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.potential input=sampling output=potential.csv columns=devpressure_2,road_dens_perc,slope,dist_interchanges_km,dist_to_water_km developed_column=urban_change_clip subregions_column=counties --o
r.futures.potential input=sampling output=potential.csv columns=devpressure_1,road_dens_perc,slope,dist_interchanges_km,dist_to_water_km developed_column=urban_change_clip subregions_column=counties --o
...
</source>

You can then open the output file <tt>potential.csv</tt>, which is a CSV file with tabs as separators.

For this tutorial, the final potential is created with:
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.potential input=sampling output=potential.csv columns=devpressure_2,road_dens_perc,slope,dist_interchanges_km,dist_to_water_km developed_column=urban_change_clip subregions_column=counties --o
</source>

We can now visualize the suitability surface using module {{AddonCmd|r.futures.potsurface}}. It creates initial development potential (suitability) raster from predictors and model coefficients and serves only for evaluating development potential model. The values of the resulting raster range from 0 to 1.

<source lang="bash">
r.futures.potsurface input=potential.csv subregions=counties output=suitability
r.colors map=suitability color=byr
</source>

== Demand submodel ==
First we will mask out roads so that they don't influence into per capita land demand relation.
<source lang="bash">
v.to.rast input=roads type=line output=roads_mask use=val
r.mask roads_mask -i
</source>

We will use {{AddonCmd|r.futures.demand}} which derives the population vs. development relation. The relation can be linear/logarithmic/logarithmic2/exponential/exponential approach.
Look for examples of the different relations in the manual.

* linear: y = A + Bx
* logarithmic: y = A + Bln(x)
* logarithmic2: y = A + B * ln(x - C)        (requires SciPy)
* exponential: y = Ae^(BX)
* exp_approach: y = (1 - e^(-A(x - B))) + C        (requires SciPy)

The format of the input population CSV files is described in the manual. It is important to have synchronized categories of subregions and the column headers of the CSV files (in our case FIPS number). How to simply generate the list of years (for which demand is computed) is described in {{AddonCmd|r.futures.demand}} manual, for example run this in Python console:

<source lang="python">
','.join([str(i) for i in range(2011, 2036)])
</source>

Then we can create the DEMAND file:
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.demand development=urban_1992,urban_2001,urban_2011 subregions=counties observed_population=population_trend.csv projected_population=population_projection.csv simulation_times=2011,2012,2013,2014,2015,2016,2017,2018,2019,2020,2021,2022,2023,2024,2025,2026,2027,2028,2029,2030,2031,2032,2033,2034,2035 plot=plot_demand.pdf demand=demand.csv separator=comma
</source>

In your current working directory, you should find files <tt>plot_demand.png</tt> and <tt>demand.csv</tt>.

If you have SciPy installed, you can experiment with other methods for fitting the functions:
<source lang="bash">
r.futures.demand ... method=logarithmic2
r.futures.demand ... method=exp_approach
</source>
If necessary, you can create a set of demand files produced by fitting each method separately and
then pick for each county the method which seems best and manually create a new demand file.

When you are finished, remove the mask as it is not needed for the next steps.
<source lang="bash">
r.mask -r
</source>

== Patch calibration ==
Patch calibration can be a very time consuming computation.
Therefore we select only one county (Buncombe):

<source lang="bash">
v.to.rast input=counties type=area where="FIPS == 37021" use=attr attribute_column=FIPS output=calib_county
g.region raster=calib_county zoom=calib_county
</source>
to derive patches of new development by comparing historical and latest development.
We can keep only patches with minimum size 2 cells (1800 = 2 x 30 x 30 m).

<source lang="bash">
r.futures.calib development_start=urban_1992 development_end=urban_2011 subregions=counties patch_sizes=patches.txt patch_threshold=1800 -l
</source>
We obtained a file <tt>patches.txt</tt> (used later in the PGA) - a patch size distribution file - containing sizes of all found patches.

We can look at the distribution of the patch sizes:

<source lang="python">
from matplotlib import pyplot as plt
with open('patches.txt') as f:
patches = [int(patch) for patch in f.readlines()]
plt.hist(patches, 2000)
plt.xlim(0,50)
plt.show()
</source>

At this point, we start the calibration to get best parameters of patch shape
(for this tutorial, this step can be skipped and the suggested parameters are used).

<source lang="bash"
style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.calib development_start=urban_1992 development_end=urban_2011 subregions=calib_county patch_sizes=patches.txt calibration_results=calib.csv patch_threshold=1800 repeat=5 compactness_mean=0.1,0.3,0.5,0.7,0.9 compactness_range=0.05 discount_factor=0.1,0.3,0.5,0.7,0.9 predictors=road_dens_perc,forest_smooth_perc,dist_to_protected_km demand=demand.csv devpot_params=potential.csv num_neighbors=4 seed_search=2 development_pressure=devpressure_0_5 development_pressure_approach=gravity n_dev_neighbourhood=30 gamma=0.5 scaling_factor=0.1
</source>

== FUTURES simulation ==
We will switch back to our previous region:
<source lang="bash">
g.region raster=landuse_2011 -p
</source>

Now we have all the inputs necessary for running {{AddonCmd|r.futures.pga}}:

The entire command is here:
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.pga subregions=counties developed=urban_2011 predictors=slope,forest_smooth_perc,dist_interchanges_km,travel_time_cities devpot_params=potential.csv development_pressure=devpressure_1 n_dev_neighbourhood=10 development_pressure_approach=gravity gamma=1 scaling_factor=1 demand=demand.csv discount_factor=0.3 compactness_mean=0.2 compactness_range=0.1 patch_sizes=patches.txt num_neighbors=4 seed_search=2 random_seed=1 output=final output_series=final
</source>

=== Quick description ===
The command parameters and their values:
* raster map of counties with their categories
<code>
... subregions=counties ...
</code>

* raster of developed (1), undeveloped (0) and NULLs for undevelopable areas
<code>
... developed=urban_2011 ...
</code>

* predictors selected with {{AddonCmd|r.futures.potential}} and their coefficients in a <tt>potential.csv</tt> file. The order of predictors must match the order in the file and the categories of the counties must match raster <tt>counties</tt>.
<code>
... predictors=slope,forest_smooth_perc,dist_interchanges_km,travel_time_cities devpot_params=potential.csv ...
</code>

* initial development pressure computed by {{AddonCmd|r.futures.devpressure}}, it's important to set here the same parameters
<code>
... development_pressure=devpressure_1 n_dev_neighbourhood=10 development_pressure_approach=gravity gamma=1 scaling_factor=1 ...
</code>

* per capita land demand computed by {{AddonCmd|r.futures.demand}}, the categories of the counties must match raster <tt>counties</tt>.
<code>
... demand=demand.csv ...
</code>

* patch parameters from the calibration step
<code>
... discount_factor=0.3 compactness_mean=0.4 compactness_range=0.08 patch_sizes=patches.txt ...
</code>

* recommended parameters for patch growing algorithm
<code>
... num_neighbors=4 seed_search=2 ...
</code>

* set random seed for repeatable results or set flag <tt>-s</tt> to generate seed automatically
<code>
... random_seed=1 ...
</code>

* specify final output map and optionally basename for intermediate raster maps
<code>
output=final output_series=final
</code>

== Scenarios ==
Scenarios involving policies that encourage infill versus sprawl can be explored using the <tt>incentive_power</tt> parameter of {{AddonCmd|r.futures.pga}},
which uses a power function to transform the evenness of the probability gradient in POTENTIAL. You can change the power to a number between 0.25 and 4 to test urban sprawl/infill scenarios.
Higher power leads to infill behavior, lower power to urban sprawl.

== Postprocessing ==

Follow a [[Creating_animation_from_FUTURES_output_in_GRASS_GIS| tutorial how to make an animation from the results]].

= GRASS GIS Python API =

[[Category: Tutorial]]
[[Category: FUTURES]]
[[Category: Urban]]

Workshop on urban growth modeling with FUTURES

2016-03-22T16:51:30Z

⚠️Dbvanber: /* Workshop introduction */

{{ToModify}}
= Workshop introduction =
r.futures.* is an implementation of the '''FUT'''ure '''U'''rban-'''R'''egional '''E'''nvironment '''S'''imulation (FUTURES)[1] which is a model for multilevel simulations of emerging urban-rural landscape structure. FUTURES produces regional projections of landscape patterns using coupled submodels that integrate nonstationary drivers of land change: per capita demand (DEMAND submodel), site suitability (POTENTIAL submodel), and the spatial structure of conversion events (PGA submodel).

[1] Meentemeyer, R. K., Tang, W., Dorning, M. A., Vogler, J. B., Cunniffe, N. J., & Shoemaker, D. A. (2013). [http://www.tandfonline.com/doi/abs/10.1080/00045608.2012.707591 FUTURES: multilevel simulations of emerging urban-rural landscape structure using a stochastic patch-growing algorithm.] Annals of the Association of American Geographers, 103(4), 785-807

== Software ==
Required software includes:
* GRASS GIS 7
* addons
** {{AddonCmd|r.futures.pga}}
** {{AddonCmd|r.futures.potential}}
** {{AddonCmd|r.futures.potsurface}}
** {{AddonCmd|r.futures.demand}}
** {{AddonCmd|r.futures.devpressure}}
** {{AddonCmd|r.sample.category}}
* R (≥ 3.0.2) - needed for {{AddonCmd|r.futures.potential}} with packages:
**MuMIn, lme4, optparse, rgrass7
* SciPy - useful for {{AddonCmd|r.futures.demand}}

=== Installation ===
There are a number of software requirements to run FUTURES that will need to be download and installed.

We use the R statistical software for our calculation of site suitability (i.e. development potential) in FUTURES. R is a free software environment for statistical computing and graphics. If you don't have R, or you have older an version, please download and install the software from [http://archive.linux.duke.edu/cran/ install R] and be sure to additionally add these required packages:
<pre>
install.packages(c("MuMIn", "lme4", "optparse", "rgrass7"))
</pre>

==== MS Windows ====
We will be using GRASS GIS 7.0.3 that can be found here in the [https://trac.osgeo.org/osgeo4w/ OSGeo4W] package manager.
Please install the latest stable GRASS GIS 7 version and the SciPy Python package using the ''Advanced install'' option.
A guide with step by step screen shot instructions is available [https://docs.google.com/presentation/d/1yEGpriBne7RvjB35HI6GecNwO1P1y2nRGqDThqoNnCE/edit?usp=sharing here].

In order for GRASS to be able to find R executables, GRASS must be on the PATH variable. Follow this [solution] to make R accessible from GRASS permanently.
A simple but temporary solution is to open GRASS GIS and paste this in the black terminal:
<pre>
set PATH=%PATH%;C:\Program Files\R\R-3.0.2\bin
</pre>
This has to be repeated after restarting GRASS session.

==== Ubuntu Linux ====
Install GRASS GIS from packages:
<pre>
sudo add-apt-repository ppa:ubuntugis/ubuntugis-unstable
sudo apt-get update
sudo apt-get install grass
</pre>

== Workshop data ==
The data that we will be using for the workshop can be download here: [http://fatra.cnr.ncsu.edu/futures/futures_ncspm_Asheville.zip sample dataset]. Please place these layers in your local GRASS directory:
* digital elevation model ([http://nationalmap.gov/elevation.html NED])
* [http://www.mrlc.gov/ NLCD] 2001, 2011
* NLCD 1992/2001 Retrofit Land Cover Change Product
* transportation network ([http://www.census.gov/geo/maps-data/data/tiger-line.html TIGER])
* county boundaries ([http://www.census.gov/geo/maps-data/data/tiger-line.html TIGER])
* protected areas ([http://www.conservationgateway.org/ConservationByGeography/NorthAmerica/UnitedStates/edc/reportsdata/terrestrial/secured/Pages/default.aspx Secured Lands])
* cities as points (USGS)

In addition, download [http://fatra.cnr.ncsu.edu/futures/futures_Asheville_files.zip population information as text files]:
* county population past estimates and future projections ([https://www.osbm.nc.gov/demog/county-projections NC OSBM]) per county (nonspatial)

= GRASS GIS introduction =
* Overview of GRASS GIS project: [https://grass.osgeo.org grass.osgeo.org]
* Overview of [https://grass.osgeo.org/grass71/manuals/grass_database.html GRASS database].
** ''GRASS database'': directory with Locations (projects)
** ''Location'': directory with Mapsets, defined by projection (spatial reference system)
** ''Mapset'': collection of maps
* Download the [http://fatra.cnr.ncsu.edu/futures/futures_ncspm_Asheville.zip workshop location]. Create (unless you already have it) a directory named <tt>grassdata</tt> (GRASS database) in your home folder (or Documents), unzip the downloaded data into this directory. You should have now Location <tt>futures_ncspm</tt> in <tt>grassdata</tt>.
* Launch GRASS and display raster, vector data, explore navigation, querying, adding legend, showing metadata
<center><gallery perrow=3 widths=500 heights=250>Image:GRASS FUTURES startup.png|GRASS GIS 7.0.3 startup dialog with downloaded Location and Mapsets for FUTURES workshop
Image:GRASS FUTURES wxGUI display.png|Layer Manager and Map Display overview. Annotations show how to add raster layer, query, add legend.
Image:wxGUI_metadata_rinfo.png|Show raster map metadata by right click on layer</gallery></center>

* GRASS GIS has over [https://grass.osgeo.org/grass70/manuals/full_index.html 500 different modules] in the core distribution and over [https://grass.osgeo.org/grass70/manuals/addons/ 230 addon modules]
<center>
{| class="wikitable"
|-
! Prefix !! Function !! Example
|-
| r.* || raster processing || ''{{cmd|r.mapcalc}}'': map algebra
|-
| v.* || vector processing || ''{{cmd|v.clean}}'': topological cleaning
|-
| i.* || imagery processing || ''{{cmd|i.segment}}'': object recognition
|-
| db.* || database management || ''{{cmd|db.select}}'': select values from table
|-
| r3.* || 3D raster processing || ''{{cmd|r3.stats}}'': 3D raster statistics
|-
| t.* || temporal data processing || ''{{cmd|t.rast.aggregate}}'': temporal aggregation
|-
| g.* || general data management || ''{{cmd|g.rename}}'': renames map
|-
| d.* || display ||''{{cmd|d.rast}}'': display raster map
|}</center>
* GRASS modules have GUI and command line interface. In this workshop we use commands to describe the workflow, but we can use both GUI and command line depending on personal preference. Look how {{cmd|wxGUI.modules|version=71|desc=GUI and command line interface}} represent the same tool. ''Task:'' compute aspect (orientation) from provided digital elevation model using module {{cmd|r.slope.aspect}} using both module dialog and command line.
* How to find modules? Modules are organized by their functionality in wxGUI menu, or we can search for them in Search modules tab. If we already know which module to use, we can just type it in the wxGUI command console. <center><gallery perrow=3 widths=380 heights=190>Image:wxGUI_menu_rinfo.png|Modules can be found in wxGUI menu
Image:wxGUI_module_search.png|You can search modules by name, description or keywords in ''Search modules'' tab
Image:wxGUI_console_completion.png|By typing prefix r. we make a list of modules starting with that prefix to show up.</gallery></center>


* {{cmd|g.region|desc=Computational region}} - an important raster concept
** defined by region extent and raster resolution
** applies to all raster operations
** persists between GRASS session, can be different for different mapsets
** advantages: keeps your results consistent, avoid clipping, for computationally demanding tasks set region to smaller extent, check your result is good and then set the computational region to the entire study area and rerun analysis
** run <code>g.region -p</code> or in menu ''Settings'' - ''Region'' - ''Display region'' to see current region settings
[[File:WxGUI set region.png|700px|thumb|center|Simple ways to set computational region from GUI. On the left, set region to match raster map. On the right, select the highlighted option and then set region by drawing rectangle.]]

* GRASS 3D view

= Modeling with FUTURES =
== Initial steps and data preparation ==
First we will set computational region of our analyses to an extent covering our study area and so that the cells are aligned with one of our landuse rasters:
<source lang="bash">g.region raster=landuse_2011 -p</source>

We will derive urbanized areas from NLCD dataset for year 1992, 2001 and 2011
by extracting categories category 21 - 24 into a new binary map where developed is 1,
undeveloped 0 and NULL (no data) is area unsuitable for development (water, wetlands, protected areas).
First we will convert protected areas from vector to raster. We set
NULLs to zeros (for simpler raster algebra expression in the next step) using {{cmd|r.null}}:

<source lang="bash">
v.to.rast input=protected_areas output=protected_areas use=val
r.null map=protected_areas null=0
</source>

And then create rasters of developed/undeveloped areas using raster algebra:

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.mapcalc "urban_1992 = if(landuse_1992 >= 21 && landuse_1992 <= 24, 1, if(landuse_1992 == 11 || landuse_1992 >= 90 || protected_areas, null(), 0))"
r.mapcalc "urban_2001 = if(landuse_2001 >= 21 && landuse_2001 <= 24, 1, if(landuse_2001 == 11 || landuse_2001 >= 90 || protected_areas, null(), 0))"
r.mapcalc "urban_2011 = if(landuse_2011 >= 21 && landuse_2011 <= 24, 1, if(landuse_2011 == 11 || landuse_2011 >= 90 || protected_areas, null(), 0))"
</source>

We will convert vector counties to raster with the values of the FIPS attribute which links to population file:

<source lang="bash">
v.to.rast input=counties type=area use=attr attribute_column=FIPS output=counties
</source>

Before further steps, we will set our working directory so that the input population files and text files
we are going to create are saved in one directory and easily accessible.
You can do that from menu ''Settings'' → ''GRASS working environment'' → ''Change working directory''.
Select (or create) a directory and move there the downloaded files <tt>population_projection.csv</tt> and <tt>population_trend.csv</tt>.

== Potential submodel ==
Module {{AddonCmd|r.futures.potential}} implements POTENTIAL submodel as a part of FUTURES land change model. POTENTIAL is implemented using a set of coefficients that relate a selection of site suitability factors to the probability of a place becoming developed. This is implemented using the parameter table in combination with maps of those site suitability factors (mapped predictors). The coefficients are obtained by conducting multilevel logistic regression in R with package lme4 where the coefficients may vary by county. The best model is selected automatically using dredge function from package [https://cran.r-project.org/web/packages/MuMIn/index.html MuMIn].

First, we will derive couple of predictors.
=== Predictors ===
==== Slope ====
We will derive slope in degrees from digital elevation model using {{cmd|r.slope.aspect}} module:
<source lang="bash">r.slope.aspect elevation=elevation_30m slope=slope</source>

==== Distance from lakes/rivers ====
First we will extract [http://www.mrlc.gov/nlcd11_leg.php category ''Open Water''] from 2011 NLCD dataset:
<source lang="bash">
r.mapcalc "water = if(landuse_2011 == 11, 1, null())"
</source>

Then we compute the distance to water with module {{cmd|r.grow.distance}} and set color table to shades of blue:
<source lang="bash">
r.grow.distance input=water distance=dist_to_water
r.colors -n map=dist_to_water color=blues
</source>

==== Distance from protected areas ====
We will use raster protected of protected areas we already created, but we will set NULL values to zero.
We compute the distance to protected areas with module {{cmd|r.grow.distance}} and set color table from green to red:
<source lang="bash">
r.null map=protected_areas setnull=0
r.grow.distance input=protected_areas distance=dist_to_protected
r.colors map=dist_to_protected color=gyr
</source>

==== Forests ====
We will smooth the transition between forest and other land use, see NLCD [http://www.mrlc.gov/nlcd11_leg.php category ''Open Water'']:
<source lang="bash">
r.mapcalc "forest = if(landuse_2011 >= 41 && landuse_2011 <= 43, 1, 0)"
r.neighbors -c input=forest output=forest_smooth size=15 method=average
r.colors map=forest_smooth color=ndvi
</source>

==== Travel time to cities ====
Here we will compute travel time to cities (with population > 5000)
as cumulative cost distance where cost is defined as travel time on roads.
First we specify the speed on different types of roads.
We copy the roads raster into our mapset so that we can change it
by adding a new attribute field <tt>speed</tt>. Then we assign speed values (km/h) based on the type of road:

<source lang="bash">
g.copy vector=roads,myroads
v.db.addcolumn map=myroads columns="speed double precision"
v.db.update map=myroads column=speed value=50 where="MTFCC = 'S1400'"
v.db.update map=myroads column=speed value=100 where="MTFCC IN ('S1100', 'S1200')"
</source>

Now we rasterize the selected road types using the speed values from the attribute table as raster values.

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
v.to.rast input=myroads type=line where="MTFCC IN ('S1100', 'S1200', 'S1400')" output=roads_speed use=attr attribute_column=speed
</source>

We set the rest of the area to low speed and recompute the speed as time to travel through a 30m cell in minutes:

<source lang="bash">
r.null map=roads_speed null=5
r.mapcalc "roads_travel_time = 1.8 / roads_speed"
</source>

Finally we compute the travel time to larger cities using {{cmd|r.cost}}:

<source lang="bash">
r.cost input=roads_travel_time output=travel_time_cities start_points=cities
r.colors map=travel_time_cities color=byr
</source>

==== Road density ====
We will rasterize roads and use moving window analysis ({{cmd|r.neighbors}}) to compute road density:

<source lang="bash">
v.to.rast input=roads output=roads use=val type=line
r.null map=roads null=0
r.neighbors -c input=roads output=road_dens size=25 method=average
</source>

==== Distance to interchanges ====

We will consider TIGER roads of type <tt>Ramp</tt> as interchanges, rasterize them and compute euclidean distance to them:

<source lang="bash">
v.to.rast input=roads type=line where="MTFCC = 'S1630'" output=interchanges use=val
r.grow.distance -m input=interchanges distance=dist_interchanges
</source>

=== Development pressure ===

We compute development pressure with {{AddonCmd|r.futures.devpressure}}. Development pressure is a predictor based on number of neighboring developed cells within search distance, weighted by distance. The development pressure variable plays a special role in the model, allowing for a feedback between predicted change and change in subsequent steps.

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.devpressure -n input=urban_2011 output=devpressure_2 method=gravity size=7 gamma=2 scaling_factor=10
r.futures.devpressure -n input=urban_2011 output=devpressure_1 method=gravity size=10 gamma=1 scaling_factor=1
r.futures.devpressure -n input=urban_2011 output=devpressure_0_5 method=gravity size=30 gamma=0.5 scaling_factor=0.1
</source>

When gamma increases, development influence decreases more rapidly with distance.
Size is half the size of the moving window. When gamma is low, local development influences more distant places.
We will derive 3 layers with different gamma and size parameters for the potential statistical model.

=== Rescaling variables ===

First we will look at the ranges of our predictor variables by running a short Python code snippet in Python shell:

<source lang="python" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
for name in ['slope', 'dist_to_water', 'dist_to_protected', 'forest_smooth', 'travel_time_cities', 'road_dens', 'dist_interchanges', 'devpressure_0_5', 'devpressure_1']:
minmax = grass.raster_info(name)
print name, minmax['min'], minmax['max']
</source>

We will rescale some of our input variables:

<source lang="bash">
r.mapcalc "dist_to_water_km = dist_to_water / 1000"
r.mapcalc "dist_to_protected_km = dist_to_protected / 1000"
r.mapcalc "dist_interchanges_km = dist_interchanges / 1000"
r.mapcalc "road_dens_perc = road_dens * 100"
r.mapcalc "forest_smooth_perc = forest_smooth * 100"
</source>

=== Sampling ===
To sample only in the analyzed counties, we will clip development layer:

<source lang="bash">
r.mapcalc "urban_change_01_11 = if(urban_2011 == 1, if(urban_2001 == 0, 1, null()), 0)"
r.mapcalc "urban_change_clip = if(counties, urban_change_01_11)"
</source>

To estimate the number of sampling points, we can use {{cmd|r.report}} to report number of developed/undeveloped cells and their ratio.

<source lang="bash">
r.report map=urban_change_clip units=h,c,p
</source>

We will sample the predictors and the response variable with 5000 random points in undeveloped areas and 1000 points in developed area:

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.sample.category input=urban_change_clip output=sampling sampled=counties,devpressure_0_5,devpressure_1,devpressure_2,slope,road_dens_perc,forest_smooth_perc,dist_to_water_km,dist_to_protected_km,dist_interchanges_km,travel_time_cities npoints=5000,1000
</source>

The attribute table can be exported as CSV file (not necessary step):

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
v.db.select map=sampling columns=urban_change_clip,counties,devpressure_0_5,devpressure_1,slope,road_dens_perc,forest_smooth_perc,dist_to_water_km,dist_to_protected_km,dist_interchanges_km,travel_time_cities separator=comma file=samples.csv
</source>

=== Development potential ===
Now we find best model for predicting urbanization using {{AddonCmd|r.futures.potential}} which wraps an R script.

We can run R [http://www.inside-r.org/packages/cran/MuMIn/docs/dredge dredge] function to find "best" model. We can specify minimum and maximum number of predictors the final model should use.
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.potential -d input=sampling output=potential.csv columns=devpressure_1,slope,road_dens_perc,forest_smooth_perc,dist_to_water_km,dist_to_protected_km,dist_interchanges_km,travel_time_cities developed_column=urban_change_clip subregions_column=counties min_variables=4
</source>

Also, we can play with different combinations of predictors, for example:

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.potential input=sampling output=potential.csv columns=devpressure_2,road_dens_perc,slope,dist_interchanges_km,dist_to_water_km developed_column=urban_change_clip subregions_column=counties --o
r.futures.potential input=sampling output=potential.csv columns=devpressure_1,road_dens_perc,slope,dist_interchanges_km,dist_to_water_km developed_column=urban_change_clip subregions_column=counties --o
...
</source>

You can then open the output file <tt>potential.csv</tt>, which is a CSV file with tabs as separators.

For this tutorial, the final potential is created with:
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.potential input=sampling output=potential.csv columns=devpressure_2,road_dens_perc,slope,dist_interchanges_km,dist_to_water_km developed_column=urban_change_clip subregions_column=counties --o
</source>

We can now visualize the suitability surface using module {{AddonCmd|r.futures.potsurface}}. It creates initial development potential (suitability) raster from predictors and model coefficients and serves only for evaluating development potential model. The values of the resulting raster range from 0 to 1.

<source lang="bash">
r.futures.potsurface input=potential.csv subregions=counties output=suitability
r.colors map=suitability color=byr
</source>

== Demand submodel ==
First we will mask out roads so that they don't influence into per capita land demand relation.
<source lang="bash">
v.to.rast input=roads type=line output=roads_mask use=val
r.mask roads_mask -i
</source>

We will use {{AddonCmd|r.futures.demand}} which derives the population vs. development relation. The relation can be linear/logarithmic/logarithmic2/exponential/exponential approach.
Look for examples of the different relations in the manual.

* linear: y = A + Bx
* logarithmic: y = A + Bln(x)
* logarithmic2: y = A + B * ln(x - C)        (requires SciPy)
* exponential: y = Ae^(BX)
* exp_approach: y = (1 - e^(-A(x - B))) + C        (requires SciPy)

The format of the input population CSV files is described in the manual. It is important to have synchronized categories of subregions and the column headers of the CSV files (in our case FIPS number). How to simply generate the list of years (for which demand is computed) is described in {{AddonCmd|r.futures.demand}} manual, for example run this in Python console:

<source lang="python">
','.join([str(i) for i in range(2011, 2036)])
</source>

Then we can create the DEMAND file:
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.demand development=urban_1992,urban_2001,urban_2011 subregions=counties observed_population=population_trend.csv projected_population=population_projection.csv simulation_times=2011,2012,2013,2014,2015,2016,2017,2018,2019,2020,2021,2022,2023,2024,2025,2026,2027,2028,2029,2030,2031,2032,2033,2034,2035 plot=plot_demand.pdf demand=demand.csv separator=comma
</source>

In your current working directory, you should find files <tt>plot_demand.png</tt> and <tt>demand.csv</tt>.

If you have SciPy installed, you can experiment with other methods for fitting the functions:
<source lang="bash">
r.futures.demand ... method=logarithmic2
r.futures.demand ... method=exp_approach
</source>
If necessary, you can create a set of demand files produced by fitting each method separately and
then pick for each county the method which seems best and manually create a new demand file.

When you are finished, remove the mask as it is not needed for the next steps.
<source lang="bash">
r.mask -r
</source>

== Patch calibration ==
Patch calibration can be a very time consuming computation.
Therefore we select only one county (Buncombe):

<source lang="bash">
v.to.rast input=counties type=area where="FIPS == 37021" use=attr attribute_column=FIPS output=calib_county
g.region raster=calib_county zoom=calib_county
</source>
to derive patches of new development by comparing historical and latest development.
We can keep only patches with minimum size 2 cells (1800 = 2 x 30 x 30 m).

<source lang="bash">
r.futures.calib development_start=urban_1992 development_end=urban_2011 subregions=counties patch_sizes=patches.txt patch_threshold=1800 -l
</source>
We obtained a file <tt>patches.txt</tt> (used later in the PGA) - a patch size distribution file - containing sizes of all found patches.

We can look at the distribution of the patch sizes:

<source lang="python">
from matplotlib import pyplot as plt
with open('patches.txt') as f:
patches = [int(patch) for patch in f.readlines()]
plt.hist(patches, 2000)
plt.xlim(0,50)
plt.show()
</source>

At this point, we start the calibration to get best parameters of patch shape
(for this tutorial, this step can be skipped and the suggested parameters are used).

<source lang="bash"
style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.calib development_start=urban_1992 development_end=urban_2011 subregions=calib_county patch_sizes=patches.txt calibration_results=calib.csv patch_threshold=1800 repeat=5 compactness_mean=0.1,0.3,0.5,0.7,0.9 compactness_range=0.05 discount_factor=0.1,0.3,0.5,0.7,0.9 predictors=road_dens_perc,forest_smooth_perc,dist_to_protected_km demand=demand.csv devpot_params=potential.csv num_neighbors=4 seed_search=2 development_pressure=devpressure_0_5 development_pressure_approach=gravity n_dev_neighbourhood=30 gamma=0.5 scaling_factor=0.1
</source>

== FUTURES simulation ==
We will switch back to our previous region:
<source lang="bash">
g.region raster=landuse_2011 -p
</source>

Now we have all the inputs necessary for running {{AddonCmd|r.futures.pga}}:

The entire command is here:
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.pga subregions=counties developed=urban_2011 predictors=slope,forest_smooth_perc,dist_interchanges_km,travel_time_cities devpot_params=potential.csv development_pressure=devpressure_1 n_dev_neighbourhood=10 development_pressure_approach=gravity gamma=1 scaling_factor=1 demand=demand.csv discount_factor=0.3 compactness_mean=0.2 compactness_range=0.1 patch_sizes=patches.txt num_neighbors=4 seed_search=2 random_seed=1 output=final output_series=final
</source>

=== Quick description ===
The command parameters and their values:
* raster map of counties with their categories
<code>
... subregions=counties ...
</code>

* raster of developed (1), undeveloped (0) and NULLs for undevelopable areas
<code>
... developed=urban_2011 ...
</code>

* predictors selected with {{AddonCmd|r.futures.potential}} and their coefficients in a <tt>potential.csv</tt> file. The order of predictors must match the order in the file and the categories of the counties must match raster <tt>counties</tt>.
<code>
... predictors=slope,forest_smooth_perc,dist_interchanges_km,travel_time_cities devpot_params=potential.csv ...
</code>

* initial development pressure computed by {{AddonCmd|r.futures.devpressure}}, it's important to set here the same parameters
<code>
... development_pressure=devpressure_1 n_dev_neighbourhood=10 development_pressure_approach=gravity gamma=1 scaling_factor=1 ...
</code>

* per capita land demand computed by {{AddonCmd|r.futures.demand}}, the categories of the counties must match raster <tt>counties</tt>.
<code>
... demand=demand.csv ...
</code>

* patch parameters from the calibration step
<code>
... discount_factor=0.3 compactness_mean=0.4 compactness_range=0.08 patch_sizes=patches.txt ...
</code>

* recommended parameters for patch growing algorithm
<code>
... num_neighbors=4 seed_search=2 ...
</code>

* set random seed for repeatable results or set flag <tt>-s</tt> to generate seed automatically
<code>
... random_seed=1 ...
</code>

* specify final output map and optionally basename for intermediate raster maps
<code>
output=final output_series=final
</code>

== Scenarios ==
Scenarios involving policies that encourage infill versus sprawl can be explored using the <tt>incentive_power</tt> parameter of {{AddonCmd|r.futures.pga}},
which uses a power function to transform the evenness of the probability gradient in POTENTIAL. You can change the power to a number between 0.25 and 4 to test urban sprawl/infill scenarios.
Higher power leads to infill behavior, lower power to urban sprawl.

== Postprocessing ==

Follow a [[Creating_animation_from_FUTURES_output_in_GRASS_GIS| tutorial how to make an animation from the results]].

= GRASS GIS Python API =

[[Category: Tutorial]]
[[Category: FUTURES]]
[[Category: Urban]]

Workshop on urban growth modeling with FUTURES

2016-03-21T20:11:48Z

⚠️Dbvanber: /* Workshop data */

{{ToModify}}
= Workshop introduction =
r.futures.* is an implementation of FUTure Urban-Regional Environment Simulation (FUTURES)[1] which is a model for multilevel simulations of emerging urban-rural landscape structure. FUTURES produces regional projections of landscape patterns using coupled submodels that integrate nonstationary drivers of land change: per capita demand (DEMAND submodel), site suitability (POTENTIAL submodel), and the spatial structure of conversion events (PGA submodel).

[1] Meentemeyer, R. K., Tang, W., Dorning, M. A., Vogler, J. B., Cunniffe, N. J., & Shoemaker, D. A. (2013). [http://www.tandfonline.com/doi/abs/10.1080/00045608.2012.707591 FUTURES: multilevel simulations of emerging urban-rural landscape structure using a stochastic patch-growing algorithm.] Annals of the Association of American Geographers, 103(4), 785-807

== Software ==
Required software includes:
* GRASS GIS 7
* addons
** {{AddonCmd|r.futures.pga}}
** {{AddonCmd|r.futures.potential}}
** {{AddonCmd|r.futures.potsurface}}
** {{AddonCmd|r.futures.demand}}
** {{AddonCmd|r.futures.devpressure}}
** {{AddonCmd|r.sample.category}}
* R (≥ 3.0.2) - needed for {{AddonCmd|r.futures.potential}} with packages:
**MuMIn, lme4, optparse, rgrass7
* SciPy - useful for {{AddonCmd|r.futures.demand}}

=== Installation ===
There are a number of software requirements to run FUTURES that will need to be download and installed.

We use the R statistical software for our calculation of site suitability (i.e. development potential) in FUTURES. R is a free software environment for statistical computing and graphics. If you don't have R, or you have older an version, please download and install the software from [http://archive.linux.duke.edu/cran/ install R] and be sure to additionally add these required packages:
<pre>
install.packages(c("MuMIn", "lme4", "optparse", "rgrass7"))
</pre>

==== MS Windows ====
We will be using GRASS GIS 7.0.3 that can be found here in the [https://trac.osgeo.org/osgeo4w/ OSGeo4W] package manager.
Please install the latest stable GRASS GIS 7 version and the SciPy Python package using the ''Advanced install'' option.
A guide with step by step screen shot instructions is available [https://docs.google.com/presentation/d/1yEGpriBne7RvjB35HI6GecNwO1P1y2nRGqDThqoNnCE/edit?usp=sharing here].

In order for GRASS to be able to find R executables, GRASS must be on the PATH variable. Follow this [solution] to make R accessible from GRASS permanently.
A simple but temporary solution is to open GRASS GIS and paste this in the black terminal:
<pre>
set PATH=%PATH%;C:\Program Files\R\R-3.0.2\bin
</pre>
This has to be repeated after restarting GRASS session.

==== Ubuntu Linux ====
Install GRASS GIS from packages:
<pre>
sudo add-apt-repository ppa:ubuntugis/ubuntugis-unstable
sudo apt-get update
sudo apt-get install grass
</pre>

== Workshop data ==
The data that we will be using for the workshop can be download here: [http://fatra.cnr.ncsu.edu/futures/futures_ncspm_Asheville.zip sample dataset]. Please place these layers in your local GRASS directory:
* digital elevation model ([http://nationalmap.gov/elevation.html NED])
* [http://www.mrlc.gov/ NLCD] 2001, 2011
* NLCD 1992/2001 Retrofit Land Cover Change Product
* transportation network ([http://www.census.gov/geo/maps-data/data/tiger-line.html TIGER])
* county boundaries ([http://www.census.gov/geo/maps-data/data/tiger-line.html TIGER])
* protected areas ([http://www.conservationgateway.org/ConservationByGeography/NorthAmerica/UnitedStates/edc/reportsdata/terrestrial/secured/Pages/default.aspx Secured Lands])
* cities as points (USGS)

In addition, download [http://fatra.cnr.ncsu.edu/futures/futures_Asheville_files.zip population information as text files]:
* county population past estimates and future projections ([https://www.osbm.nc.gov/demog/county-projections NC OSBM]) per county (nonspatial)

= GRASS GIS introduction =
* Overview of GRASS GIS project: [https://grass.osgeo.org grass.osgeo.org]
* Overview of [https://grass.osgeo.org/grass71/manuals/grass_database.html GRASS database].
** ''GRASS database'': directory with Locations (projects)
** ''Location'': directory with Mapsets, defined by projection (spatial reference system)
** ''Mapset'': collection of maps
* Download the [http://fatra.cnr.ncsu.edu/futures/futures_ncspm_Asheville.zip workshop location]. Create (unless you already have it) a directory named <tt>grassdata</tt> (GRASS database) in your home folder (or Documents), unzip the downloaded data into this directory. You should have now Location <tt>futures_ncspm</tt> in <tt>grassdata</tt>.
* Launch GRASS and display raster, vector data, explore navigation, querying, adding legend, showing metadata
<center><gallery perrow=3 widths=500 heights=250>Image:GRASS FUTURES startup.png|GRASS GIS 7.0.3 startup dialog with downloaded Location and Mapsets for FUTURES workshop
Image:GRASS FUTURES wxGUI display.png|Layer Manager and Map Display overview. Annotations show how to add raster layer, query, add legend.
Image:wxGUI_metadata_rinfo.png|Show raster map metadata by right click on layer</gallery></center>

* GRASS GIS has over [https://grass.osgeo.org/grass70/manuals/full_index.html 500 different modules] in the core distribution and over [https://grass.osgeo.org/grass70/manuals/addons/ 230 addon modules]
<center>
{| class="wikitable"
|-
! Prefix !! Function !! Example
|-
| r.* || raster processing || ''{{cmd|r.mapcalc}}'': map algebra
|-
| v.* || vector processing || ''{{cmd|v.clean}}'': topological cleaning
|-
| i.* || imagery processing || ''{{cmd|i.segment}}'': object recognition
|-
| db.* || database management || ''{{cmd|db.select}}'': select values from table
|-
| r3.* || 3D raster processing || ''{{cmd|r3.stats}}'': 3D raster statistics
|-
| t.* || temporal data processing || ''{{cmd|t.rast.aggregate}}'': temporal aggregation
|-
| g.* || general data management || ''{{cmd|g.rename}}'': renames map
|-
| d.* || display ||''{{cmd|d.rast}}'': display raster map
|}</center>
* GRASS modules have GUI and command line interface. In this workshop we use commands to describe the workflow, but we can use both GUI and command line depending on personal preference. Look how {{cmd|wxGUI.modules|version=71|desc=GUI and command line interface}} represent the same tool. ''Task:'' compute aspect (orientation) from provided digital elevation model using module {{cmd|r.slope.aspect}} using both module dialog and command line.
* How to find modules? Modules are organized by their functionality in wxGUI menu, or we can search for them in Search modules tab. If we already know which module to use, we can just type it in the wxGUI command console. <center><gallery perrow=3 widths=380 heights=190>Image:wxGUI_menu_rinfo.png|Modules can be found in wxGUI menu
Image:wxGUI_module_search.png|You can search modules by name, description or keywords in ''Search modules'' tab
Image:wxGUI_console_completion.png|By typing prefix r. we make a list of modules starting with that prefix to show up.</gallery></center>


* {{cmd|g.region|desc=Computational region}} - an important raster concept
** defined by region extent and raster resolution
** applies to all raster operations
** persists between GRASS session, can be different for different mapsets
** advantages: keeps your results consistent, avoid clipping, for computationally demanding tasks set region to smaller extent, check your result is good and then set the computational region to the entire study area and rerun analysis
** run <code>g.region -p</code> or in menu ''Settings'' - ''Region'' - ''Display region'' to see current region settings
[[File:WxGUI set region.png|700px|thumb|center|Simple ways to set computational region from GUI. On the left, set region to match raster map. On the right, select the highlighted option and then set region by drawing rectangle.]]

* GRASS 3D view

= Modeling with FUTURES =
== Initial steps and data preparation ==
First we will set computational region of our analyses to an extent covering our study area and so that the cells are aligned with one of our landuse rasters:
<source lang="bash">g.region raster=landuse_2011 -p</source>

We will derive urbanized areas from NLCD dataset for year 1992, 2001 and 2011
by extracting categories category 21 - 24 into a new binary map where developed is 1,
undeveloped 0 and NULL (no data) is area unsuitable for development (water, wetlands, protected areas).
First we will convert protected areas from vector to raster. We set
NULLs to zeros (for simpler raster algebra expression in the next step) using {{cmd|r.null}}:

<source lang="bash">
v.to.rast input=protected_areas output=protected_areas use=val
r.null map=protected_areas null=0
</source>

And then create rasters of developed/undeveloped areas using raster algebra:

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.mapcalc "urban_1992 = if(landuse_1992 >= 21 && landuse_1992 <= 24, 1, if(landuse_1992 == 11 || landuse_1992 >= 90 || protected_areas, null(), 0))"
r.mapcalc "urban_2001 = if(landuse_2001 >= 21 && landuse_2001 <= 24, 1, if(landuse_2001 == 11 || landuse_2001 >= 90 || protected_areas, null(), 0))"
r.mapcalc "urban_2011 = if(landuse_2011 >= 21 && landuse_2011 <= 24, 1, if(landuse_2011 == 11 || landuse_2011 >= 90 || protected_areas, null(), 0))"
</source>

We will convert vector counties to raster with the values of the FIPS attribute which links to population file:

<source lang="bash">
v.to.rast input=counties type=area use=attr attribute_column=FIPS output=counties
</source>

Before further steps, we will set our working directory so that the input population files and text files
we are going to create are saved in one directory and easily accessible.
You can do that from menu ''Settings'' → ''GRASS working environment'' → ''Change working directory''.
Select (or create) a directory and move there the downloaded files <tt>population_projection.csv</tt> and <tt>population_trend.csv</tt>.

== Potential submodel ==
Module {{AddonCmd|r.futures.potential}} implements POTENTIAL submodel as a part of FUTURES land change model. POTENTIAL is implemented using a set of coefficients that relate a selection of site suitability factors to the probability of a place becoming developed. This is implemented using the parameter table in combination with maps of those site suitability factors (mapped predictors). The coefficients are obtained by conducting multilevel logistic regression in R with package lme4 where the coefficients may vary by county. The best model is selected automatically using dredge function from package [https://cran.r-project.org/web/packages/MuMIn/index.html MuMIn].

First, we will derive couple of predictors.
=== Predictors ===
==== Slope ====
We will derive slope in degrees from digital elevation model using {{cmd|r.slope.aspect}} module:
<source lang="bash">r.slope.aspect elevation=elevation_30m slope=slope</source>

==== Distance from lakes/rivers ====
First we will extract [http://www.mrlc.gov/nlcd11_leg.php category ''Open Water''] from 2011 NLCD dataset:
<source lang="bash">
r.mapcalc "water = if(landuse_2011 == 11, 1, null())"
</source>

Then we compute the distance to water with module {{cmd|r.grow.distance}} and set color table to shades of blue:
<source lang="bash">
r.grow.distance input=water distance=dist_to_water
r.colors -n map=dist_to_water color=blues
</source>

==== Distance from protected areas ====
We will use raster protected of protected areas we already created, but we will set NULL values to zero.
We compute the distance to protected areas with module {{cmd|r.grow.distance}} and set color table from green to red:
<source lang="bash">
r.null map=protected_areas setnull=0
r.grow.distance input=protected_areas distance=dist_to_protected
r.colors map=dist_to_protected color=gyr
</source>

==== Forests ====
We will smooth the transition between forest and other land use, see NLCD [http://www.mrlc.gov/nlcd11_leg.php category ''Open Water'']:
<source lang="bash">
r.mapcalc "forest = if(landuse_2011 >= 41 && landuse_2011 <= 43, 1, 0)"
r.neighbors -c input=forest output=forest_smooth size=15 method=average
r.colors map=forest_smooth color=ndvi
</source>

==== Travel time to cities ====
Here we will compute travel time to cities (with population > 5000)
as cumulative cost distance where cost is defined as travel time on roads.
First we specify the speed on different types of roads.
We copy the roads raster into our mapset so that we can change it
by adding a new attribute field <tt>speed</tt>. Then we assign speed values (km/h) based on the type of road:

<source lang="bash">
g.copy vector=roads,myroads
v.db.addcolumn map=myroads columns="speed double precision"
v.db.update map=myroads column=speed value=50 where="MTFCC = 'S1400'"
v.db.update map=myroads column=speed value=100 where="MTFCC IN ('S1100', 'S1200')"
</source>

Now we rasterize the selected road types using the speed values from the attribute table as raster values.

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
v.to.rast input=myroads type=line where="MTFCC IN ('S1100', 'S1200', 'S1400')" output=roads_speed use=attr attribute_column=speed
</source>

We set the rest of the area to low speed and recompute the speed as time to travel through a 30m cell in minutes:

<source lang="bash">
r.null map=roads_speed null=5
r.mapcalc "roads_travel_time = 1.8 / roads_speed"
</source>

Finally we compute the travel time to larger cities using {{cmd|r.cost}}:

<source lang="bash">
r.cost input=roads_travel_time output=travel_time_cities start_points=cities
r.colors map=travel_time_cities color=byr
</source>

==== Road density ====
We will rasterize roads and use moving window analysis ({{cmd|r.neighbors}}) to compute road density:

<source lang="bash">
v.to.rast input=roads output=roads use=val type=line
r.null map=roads null=0
r.neighbors -c input=roads output=road_dens size=25 method=average
</source>

==== Distance to interchanges ====

We will consider TIGER roads of type <tt>Ramp</tt> as interchanges, rasterize them and compute euclidean distance to them:

<source lang="bash">
v.to.rast input=roads type=line where="MTFCC = 'S1630'" output=interchanges use=val
r.grow.distance -m input=interchanges distance=dist_interchanges
</source>

=== Development pressure ===

We compute development pressure with {{AddonCmd|r.futures.devpressure}}. Development pressure is a predictor based on number of neighboring developed cells within search distance, weighted by distance. The development pressure variable plays a special role in the model, allowing for a feedback between predicted change and change in subsequent steps.

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.devpressure -n input=urban_2011 output=devpressure_2 method=gravity size=7 gamma=2 scaling_factor=10
r.futures.devpressure -n input=urban_2011 output=devpressure_1 method=gravity size=10 gamma=1 scaling_factor=1
r.futures.devpressure -n input=urban_2011 output=devpressure_0_5 method=gravity size=30 gamma=0.5 scaling_factor=0.1
</source>

When gamma increases, development influence decreases more rapidly with distance.
Size is half the size of the moving window. When gamma is low, local development influences more distant places.
We will derive 3 layers with different gamma and size parameters for the potential statistical model.

=== Rescaling variables ===

First we will look at the ranges of our predictor variables by running a short Python code snippet in Python shell:

<source lang="python" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
for name in ['slope', 'dist_to_water', 'dist_to_protected', 'forest_smooth', 'travel_time_cities', 'road_dens', 'dist_interchanges', 'devpressure_0_5', 'devpressure_1']:
minmax = grass.raster_info(name)
print name, minmax['min'], minmax['max']
</source>

We will rescale some of our input variables:

<source lang="bash">
r.mapcalc "dist_to_water_km = dist_to_water / 1000"
r.mapcalc "dist_to_protected_km = dist_to_protected / 1000"
r.mapcalc "dist_interchanges_km = dist_interchanges / 1000"
r.mapcalc "road_dens_perc = road_dens * 100"
r.mapcalc "forest_smooth_perc = forest_smooth * 100"
</source>

=== Sampling ===
To sample only in the analyzed counties, we will clip development layer:

<source lang="bash">
r.mapcalc "urban_change_01_11 = if(urban_2011 == 1, if(urban_2001 == 0, 1, null()), 0)"
r.mapcalc "urban_change_clip = if(counties, urban_change_01_11)"
</source>

To estimate the number of sampling points, we can use {{cmd|r.report}} to report number of developed/undeveloped cells and their ratio.

<source lang="bash">
r.report map=urban_change_clip units=h,c,p
</source>

We will sample the predictors and the response variable with 5000 random points in undeveloped areas and 1000 points in developed area:

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.sample.category input=urban_change_clip output=sampling sampled=counties,devpressure_0_5,devpressure_1,devpressure_2,slope,road_dens_perc,forest_smooth_perc,dist_to_water_km,dist_to_protected_km,dist_interchanges_km,travel_time_cities npoints=5000,1000
</source>

The attribute table can be exported as CSV file (not necessary step):

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
v.db.select map=sampling columns=urban_change_clip,counties,devpressure_0_5,devpressure_1,slope,road_dens_perc,forest_smooth_perc,dist_to_water_km,dist_to_protected_km,dist_interchanges_km,travel_time_cities separator=comma file=samples.csv
</source>

=== Development potential ===
Now we find best model for predicting urbanization using {{AddonCmd|r.futures.potential}} which wraps an R script.

We can run R [http://www.inside-r.org/packages/cran/MuMIn/docs/dredge dredge] function to find "best" model. We can specify minimum and maximum number of predictors the final model should use.
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.potential -d input=sampling output=potential.csv columns=devpressure_1,slope,road_dens_perc,forest_smooth_perc,dist_to_water_km,dist_to_protected_km,dist_interchanges_km,travel_time_cities developed_column=urban_change_clip subregions_column=counties min_variables=4
</source>

Also, we can play with different combinations of predictors, for example:

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.potential input=sampling output=potential.csv columns=devpressure_2,road_dens_perc,slope,dist_interchanges_km,dist_to_water_km developed_column=urban_change_clip subregions_column=counties --o
r.futures.potential input=sampling output=potential.csv columns=devpressure_1,road_dens_perc,slope,dist_interchanges_km,dist_to_water_km developed_column=urban_change_clip subregions_column=counties --o
...
</source>

You can then open the output file <tt>potential.csv</tt>, which is a CSV file with tabs as separators.

For this tutorial, the final potential is created with:
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.potential input=sampling output=potential.csv columns=devpressure_2,road_dens_perc,slope,dist_interchanges_km,dist_to_water_km developed_column=urban_change_clip subregions_column=counties --o
</source>

We can now visualize the suitability surface using module {{AddonCmd|r.futures.potsurface}}. It creates initial development potential (suitability) raster from predictors and model coefficients and serves only for evaluating development potential model. The values of the resulting raster range from 0 to 1.

<source lang="bash">
r.futures.potsurface input=potential.csv subregions=counties output=suitability
r.colors map=suitability color=byr
</source>

== Demand submodel ==
First we will mask out roads so that they don't influence into per capita land demand relation.
<source lang="bash">
v.to.rast input=roads type=line output=roads_mask use=val
r.mask roads_mask -i
</source>

We will use {{AddonCmd|r.futures.demand}} which derives the population vs. development relation. The relation can be linear/logarithmic/logarithmic2/exponential/exponential approach.
Look for examples of the different relations in the manual.

* linear: y = A + Bx
* logarithmic: y = A + Bln(x)
* logarithmic2: y = A + B * ln(x - C)        (requires SciPy)
* exponential: y = Ae^(BX)
* exp_approach: y = (1 - e^(-A(x - B))) + C        (requires SciPy)

The format of the input population CSV files is described in the manual. It is important to have synchronized categories of subregions and the column headers of the CSV files (in our case FIPS number). How to simply generate the list of years (for which demand is computed) is described in {{AddonCmd|r.futures.demand}} manual, for example run this in Python console:

<source lang="python">
','.join([str(i) for i in range(2011, 2036)])
</source>

Then we can create the DEMAND file:
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.demand development=urban_1992,urban_2001,urban_2011 subregions=counties observed_population=population_trend.csv projected_population=population_projection.csv simulation_times=2011,2012,2013,2014,2015,2016,2017,2018,2019,2020,2021,2022,2023,2024,2025,2026,2027,2028,2029,2030,2031,2032,2033,2034,2035 plot=plot_demand.pdf demand=demand.csv separator=comma
</source>

In your current working directory, you should find files <tt>plot_demand.png</tt> and <tt>demand.csv</tt>.

If you have SciPy installed, you can experiment with other methods for fitting the functions:
<source lang="bash">
r.futures.demand ... method=logarithmic2
r.futures.demand ... method=exp_approach
</source>
If necessary, you can create a set of demand files produced by fitting each method separately and
then pick for each county the method which seems best and manually create a new demand file.

When you are finished, remove the mask as it is not needed for the next steps.
<source lang="bash">
r.mask -r
</source>

== Patch calibration ==
Patch calibration can be a very time consuming computation.
Therefore we select only one county (Buncombe):

<source lang="bash">
v.to.rast input=counties type=area where="FIPS == 37021" use=attr attribute_column=FIPS output=calib_county
g.region raster=calib_county zoom=calib_county
</source>
to derive patches of new development by comparing historical and latest development.
We can keep only patches with minimum size 2 cells (1800 = 2 x 30 x 30 m).

<source lang="bash">
r.futures.calib development_start=urban_1992 development_end=urban_2011 subregions=counties patch_sizes=patches.txt patch_threshold=1800 -l
</source>
We obtained a file <tt>patches.txt</tt> (used later in the PGA) - a patch size distribution file - containing sizes of all found patches.

We can look at the distribution of the patch sizes:

<source lang="python">
from matplotlib import pyplot as plt
with open('patches.txt') as f:
patches = [int(patch) for patch in f.readlines()]
plt.hist(patches, 2000)
plt.xlim(0,50)
plt.show()
</source>

At this point, we start the calibration to get best parameters of patch shape
(for this tutorial, this step can be skipped and the suggested parameters are used).

<source lang="bash"
style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.calib development_start=urban_1992 development_end=urban_2011 subregions=calib_county patch_sizes=patches.txt calibration_results=calib.csv patch_threshold=1800 repeat=5 compactness_mean=0.1,0.3,0.5,0.7,0.9 compactness_range=0.05 discount_factor=0.1,0.3,0.5,0.7,0.9 predictors=road_dens_perc,forest_smooth_perc,dist_to_protected_km demand=demand.csv devpot_params=potential.csv num_neighbors=4 seed_search=2 development_pressure=devpressure_0_5 development_pressure_approach=gravity n_dev_neighbourhood=30 gamma=0.5 scaling_factor=0.1
</source>

== FUTURES simulation ==
We will switch back to our previous region:
<source lang="bash">
g.region raster=landuse_2011 -p
</source>

Now we have all the inputs necessary for running {{AddonCmd|r.futures.pga}}:

The entire command is here:
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.pga subregions=counties developed=urban_2011 predictors=slope,forest_smooth_perc,dist_interchanges_km,travel_time_cities devpot_params=potential.csv development_pressure=devpressure_1 n_dev_neighbourhood=10 development_pressure_approach=gravity gamma=1 scaling_factor=1 demand=demand.csv discount_factor=0.3 compactness_mean=0.2 compactness_range=0.1 patch_sizes=patches.txt num_neighbors=4 seed_search=2 random_seed=1 output=final output_series=final
</source>

=== Quick description ===
The command parameters and their values:
* raster map of counties with their categories
<code>
... subregions=counties ...
</code>

* raster of developed (1), undeveloped (0) and NULLs for undevelopable areas
<code>
... developed=urban_2011 ...
</code>

* predictors selected with {{AddonCmd|r.futures.potential}} and their coefficients in a <tt>potential.csv</tt> file. The order of predictors must match the order in the file and the categories of the counties must match raster <tt>counties</tt>.
<code>
... predictors=slope,forest_smooth_perc,dist_interchanges_km,travel_time_cities devpot_params=potential.csv ...
</code>

* initial development pressure computed by {{AddonCmd|r.futures.devpressure}}, it's important to set here the same parameters
<code>
... development_pressure=devpressure_1 n_dev_neighbourhood=10 development_pressure_approach=gravity gamma=1 scaling_factor=1 ...
</code>

* per capita land demand computed by {{AddonCmd|r.futures.demand}}, the categories of the counties must match raster <tt>counties</tt>.
<code>
... demand=demand.csv ...
</code>

* patch parameters from the calibration step
<code>
... discount_factor=0.3 compactness_mean=0.4 compactness_range=0.08 patch_sizes=patches.txt ...
</code>

* recommended parameters for patch growing algorithm
<code>
... num_neighbors=4 seed_search=2 ...
</code>

* set random seed for repeatable results or set flag <tt>-s</tt> to generate seed automatically
<code>
... random_seed=1 ...
</code>

* specify final output map and optionally basename for intermediate raster maps
<code>
output=final output_series=final
</code>

== Scenarios ==
Scenarios involving policies that encourage infill versus sprawl can be explored using the <tt>incentive_power</tt> parameter of {{AddonCmd|r.futures.pga}},
which uses a power function to transform the evenness of the probability gradient in POTENTIAL. You can change the power to a number between 0.25 and 4 to test urban sprawl/infill scenarios.
Higher power leads to infill behavior, lower power to urban sprawl.

== Postprocessing ==

Follow a [[Creating_animation_from_FUTURES_output_in_GRASS_GIS| tutorial how to make an animation from the results]].

= GRASS GIS Python API =

[[Category: Tutorial]]
[[Category: FUTURES]]
[[Category: Urban]]

Workshop on urban growth modeling with FUTURES

2016-03-21T20:11:20Z

⚠️Dbvanber:

{{ToModify}}
= Workshop introduction =
r.futures.* is an implementation of FUTure Urban-Regional Environment Simulation (FUTURES)[1] which is a model for multilevel simulations of emerging urban-rural landscape structure. FUTURES produces regional projections of landscape patterns using coupled submodels that integrate nonstationary drivers of land change: per capita demand (DEMAND submodel), site suitability (POTENTIAL submodel), and the spatial structure of conversion events (PGA submodel).

[1] Meentemeyer, R. K., Tang, W., Dorning, M. A., Vogler, J. B., Cunniffe, N. J., & Shoemaker, D. A. (2013). [http://www.tandfonline.com/doi/abs/10.1080/00045608.2012.707591 FUTURES: multilevel simulations of emerging urban-rural landscape structure using a stochastic patch-growing algorithm.] Annals of the Association of American Geographers, 103(4), 785-807

== Software ==
Required software includes:
* GRASS GIS 7
* addons
** {{AddonCmd|r.futures.pga}}
** {{AddonCmd|r.futures.potential}}
** {{AddonCmd|r.futures.potsurface}}
** {{AddonCmd|r.futures.demand}}
** {{AddonCmd|r.futures.devpressure}}
** {{AddonCmd|r.sample.category}}
* R (≥ 3.0.2) - needed for {{AddonCmd|r.futures.potential}} with packages:
**MuMIn, lme4, optparse, rgrass7
* SciPy - useful for {{AddonCmd|r.futures.demand}}

=== Installation ===
There are a number of software requirements to run FUTURES that will need to be download and installed.

We use the R statistical software for our calculation of site suitability (i.e. development potential) in FUTURES. R is a free software environment for statistical computing and graphics. If you don't have R, or you have older an version, please download and install the software from [http://archive.linux.duke.edu/cran/ install R] and be sure to additionally add these required packages:
<pre>
install.packages(c("MuMIn", "lme4", "optparse", "rgrass7"))
</pre>

==== MS Windows ====
We will be using GRASS GIS 7.0.3 that can be found here in the [https://trac.osgeo.org/osgeo4w/ OSGeo4W] package manager.
Please install the latest stable GRASS GIS 7 version and the SciPy Python package using the ''Advanced install'' option.
A guide with step by step screen shot instructions is available [https://docs.google.com/presentation/d/1yEGpriBne7RvjB35HI6GecNwO1P1y2nRGqDThqoNnCE/edit?usp=sharing here].

In order for GRASS to be able to find R executables, GRASS must be on the PATH variable. Follow this [solution] to make R accessible from GRASS permanently.
A simple but temporary solution is to open GRASS GIS and paste this in the black terminal:
<pre>
set PATH=%PATH%;C:\Program Files\R\R-3.0.2\bin
</pre>
This has to be repeated after restarting GRASS session.

==== Ubuntu Linux ====
Install GRASS GIS from packages:
<pre>
sudo add-apt-repository ppa:ubuntugis/ubuntugis-unstable
sudo apt-get update
sudo apt-get install grass
</pre>

== Workshop data ==
The data that we will be using for the workshop can be download here: [http://fatra.cnr.ncsu.edu/futures/futures_ncspm_Asheville.zip sample dataset]. Please download and place these layers in your local GRASS directory:
* digital elevation model ([http://nationalmap.gov/elevation.html NED])
* [http://www.mrlc.gov/ NLCD] 2001, 2011
* NLCD 1992/2001 Retrofit Land Cover Change Product
* transportation network ([http://www.census.gov/geo/maps-data/data/tiger-line.html TIGER])
* county boundaries ([http://www.census.gov/geo/maps-data/data/tiger-line.html TIGER])
* protected areas ([http://www.conservationgateway.org/ConservationByGeography/NorthAmerica/UnitedStates/edc/reportsdata/terrestrial/secured/Pages/default.aspx Secured Lands])
* cities as points (USGS)

In addition, download [http://fatra.cnr.ncsu.edu/futures/futures_Asheville_files.zip population information as text files]:
* county population past estimates and future projections ([https://www.osbm.nc.gov/demog/county-projections NC OSBM]) per county (nonspatial)

= GRASS GIS introduction =
* Overview of GRASS GIS project: [https://grass.osgeo.org grass.osgeo.org]
* Overview of [https://grass.osgeo.org/grass71/manuals/grass_database.html GRASS database].
** ''GRASS database'': directory with Locations (projects)
** ''Location'': directory with Mapsets, defined by projection (spatial reference system)
** ''Mapset'': collection of maps
* Download the [http://fatra.cnr.ncsu.edu/futures/futures_ncspm_Asheville.zip workshop location]. Create (unless you already have it) a directory named <tt>grassdata</tt> (GRASS database) in your home folder (or Documents), unzip the downloaded data into this directory. You should have now Location <tt>futures_ncspm</tt> in <tt>grassdata</tt>.
* Launch GRASS and display raster, vector data, explore navigation, querying, adding legend, showing metadata
<center><gallery perrow=3 widths=500 heights=250>Image:GRASS FUTURES startup.png|GRASS GIS 7.0.3 startup dialog with downloaded Location and Mapsets for FUTURES workshop
Image:GRASS FUTURES wxGUI display.png|Layer Manager and Map Display overview. Annotations show how to add raster layer, query, add legend.
Image:wxGUI_metadata_rinfo.png|Show raster map metadata by right click on layer</gallery></center>

* GRASS GIS has over [https://grass.osgeo.org/grass70/manuals/full_index.html 500 different modules] in the core distribution and over [https://grass.osgeo.org/grass70/manuals/addons/ 230 addon modules]
<center>
{| class="wikitable"
|-
! Prefix !! Function !! Example
|-
| r.* || raster processing || ''{{cmd|r.mapcalc}}'': map algebra
|-
| v.* || vector processing || ''{{cmd|v.clean}}'': topological cleaning
|-
| i.* || imagery processing || ''{{cmd|i.segment}}'': object recognition
|-
| db.* || database management || ''{{cmd|db.select}}'': select values from table
|-
| r3.* || 3D raster processing || ''{{cmd|r3.stats}}'': 3D raster statistics
|-
| t.* || temporal data processing || ''{{cmd|t.rast.aggregate}}'': temporal aggregation
|-
| g.* || general data management || ''{{cmd|g.rename}}'': renames map
|-
| d.* || display ||''{{cmd|d.rast}}'': display raster map
|}</center>
* GRASS modules have GUI and command line interface. In this workshop we use commands to describe the workflow, but we can use both GUI and command line depending on personal preference. Look how {{cmd|wxGUI.modules|version=71|desc=GUI and command line interface}} represent the same tool. ''Task:'' compute aspect (orientation) from provided digital elevation model using module {{cmd|r.slope.aspect}} using both module dialog and command line.
* How to find modules? Modules are organized by their functionality in wxGUI menu, or we can search for them in Search modules tab. If we already know which module to use, we can just type it in the wxGUI command console. <center><gallery perrow=3 widths=380 heights=190>Image:wxGUI_menu_rinfo.png|Modules can be found in wxGUI menu
Image:wxGUI_module_search.png|You can search modules by name, description or keywords in ''Search modules'' tab
Image:wxGUI_console_completion.png|By typing prefix r. we make a list of modules starting with that prefix to show up.</gallery></center>


* {{cmd|g.region|desc=Computational region}} - an important raster concept
** defined by region extent and raster resolution
** applies to all raster operations
** persists between GRASS session, can be different for different mapsets
** advantages: keeps your results consistent, avoid clipping, for computationally demanding tasks set region to smaller extent, check your result is good and then set the computational region to the entire study area and rerun analysis
** run <code>g.region -p</code> or in menu ''Settings'' - ''Region'' - ''Display region'' to see current region settings
[[File:WxGUI set region.png|700px|thumb|center|Simple ways to set computational region from GUI. On the left, set region to match raster map. On the right, select the highlighted option and then set region by drawing rectangle.]]

* GRASS 3D view

= Modeling with FUTURES =
== Initial steps and data preparation ==
First we will set computational region of our analyses to an extent covering our study area and so that the cells are aligned with one of our landuse rasters:
<source lang="bash">g.region raster=landuse_2011 -p</source>

We will derive urbanized areas from NLCD dataset for year 1992, 2001 and 2011
by extracting categories category 21 - 24 into a new binary map where developed is 1,
undeveloped 0 and NULL (no data) is area unsuitable for development (water, wetlands, protected areas).
First we will convert protected areas from vector to raster. We set
NULLs to zeros (for simpler raster algebra expression in the next step) using {{cmd|r.null}}:

<source lang="bash">
v.to.rast input=protected_areas output=protected_areas use=val
r.null map=protected_areas null=0
</source>

And then create rasters of developed/undeveloped areas using raster algebra:

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.mapcalc "urban_1992 = if(landuse_1992 >= 21 && landuse_1992 <= 24, 1, if(landuse_1992 == 11 || landuse_1992 >= 90 || protected_areas, null(), 0))"
r.mapcalc "urban_2001 = if(landuse_2001 >= 21 && landuse_2001 <= 24, 1, if(landuse_2001 == 11 || landuse_2001 >= 90 || protected_areas, null(), 0))"
r.mapcalc "urban_2011 = if(landuse_2011 >= 21 && landuse_2011 <= 24, 1, if(landuse_2011 == 11 || landuse_2011 >= 90 || protected_areas, null(), 0))"
</source>

We will convert vector counties to raster with the values of the FIPS attribute which links to population file:

<source lang="bash">
v.to.rast input=counties type=area use=attr attribute_column=FIPS output=counties
</source>

Before further steps, we will set our working directory so that the input population files and text files
we are going to create are saved in one directory and easily accessible.
You can do that from menu ''Settings'' → ''GRASS working environment'' → ''Change working directory''.
Select (or create) a directory and move there the downloaded files <tt>population_projection.csv</tt> and <tt>population_trend.csv</tt>.

== Potential submodel ==
Module {{AddonCmd|r.futures.potential}} implements POTENTIAL submodel as a part of FUTURES land change model. POTENTIAL is implemented using a set of coefficients that relate a selection of site suitability factors to the probability of a place becoming developed. This is implemented using the parameter table in combination with maps of those site suitability factors (mapped predictors). The coefficients are obtained by conducting multilevel logistic regression in R with package lme4 where the coefficients may vary by county. The best model is selected automatically using dredge function from package [https://cran.r-project.org/web/packages/MuMIn/index.html MuMIn].

First, we will derive couple of predictors.
=== Predictors ===
==== Slope ====
We will derive slope in degrees from digital elevation model using {{cmd|r.slope.aspect}} module:
<source lang="bash">r.slope.aspect elevation=elevation_30m slope=slope</source>

==== Distance from lakes/rivers ====
First we will extract [http://www.mrlc.gov/nlcd11_leg.php category ''Open Water''] from 2011 NLCD dataset:
<source lang="bash">
r.mapcalc "water = if(landuse_2011 == 11, 1, null())"
</source>

Then we compute the distance to water with module {{cmd|r.grow.distance}} and set color table to shades of blue:
<source lang="bash">
r.grow.distance input=water distance=dist_to_water
r.colors -n map=dist_to_water color=blues
</source>

==== Distance from protected areas ====
We will use raster protected of protected areas we already created, but we will set NULL values to zero.
We compute the distance to protected areas with module {{cmd|r.grow.distance}} and set color table from green to red:
<source lang="bash">
r.null map=protected_areas setnull=0
r.grow.distance input=protected_areas distance=dist_to_protected
r.colors map=dist_to_protected color=gyr
</source>

==== Forests ====
We will smooth the transition between forest and other land use, see NLCD [http://www.mrlc.gov/nlcd11_leg.php category ''Open Water'']:
<source lang="bash">
r.mapcalc "forest = if(landuse_2011 >= 41 && landuse_2011 <= 43, 1, 0)"
r.neighbors -c input=forest output=forest_smooth size=15 method=average
r.colors map=forest_smooth color=ndvi
</source>

==== Travel time to cities ====
Here we will compute travel time to cities (with population > 5000)
as cumulative cost distance where cost is defined as travel time on roads.
First we specify the speed on different types of roads.
We copy the roads raster into our mapset so that we can change it
by adding a new attribute field <tt>speed</tt>. Then we assign speed values (km/h) based on the type of road:

<source lang="bash">
g.copy vector=roads,myroads
v.db.addcolumn map=myroads columns="speed double precision"
v.db.update map=myroads column=speed value=50 where="MTFCC = 'S1400'"
v.db.update map=myroads column=speed value=100 where="MTFCC IN ('S1100', 'S1200')"
</source>

Now we rasterize the selected road types using the speed values from the attribute table as raster values.

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
v.to.rast input=myroads type=line where="MTFCC IN ('S1100', 'S1200', 'S1400')" output=roads_speed use=attr attribute_column=speed
</source>

We set the rest of the area to low speed and recompute the speed as time to travel through a 30m cell in minutes:

<source lang="bash">
r.null map=roads_speed null=5
r.mapcalc "roads_travel_time = 1.8 / roads_speed"
</source>

Finally we compute the travel time to larger cities using {{cmd|r.cost}}:

<source lang="bash">
r.cost input=roads_travel_time output=travel_time_cities start_points=cities
r.colors map=travel_time_cities color=byr
</source>

==== Road density ====
We will rasterize roads and use moving window analysis ({{cmd|r.neighbors}}) to compute road density:

<source lang="bash">
v.to.rast input=roads output=roads use=val type=line
r.null map=roads null=0
r.neighbors -c input=roads output=road_dens size=25 method=average
</source>

==== Distance to interchanges ====

We will consider TIGER roads of type <tt>Ramp</tt> as interchanges, rasterize them and compute euclidean distance to them:

<source lang="bash">
v.to.rast input=roads type=line where="MTFCC = 'S1630'" output=interchanges use=val
r.grow.distance -m input=interchanges distance=dist_interchanges
</source>

=== Development pressure ===

We compute development pressure with {{AddonCmd|r.futures.devpressure}}. Development pressure is a predictor based on number of neighboring developed cells within search distance, weighted by distance. The development pressure variable plays a special role in the model, allowing for a feedback between predicted change and change in subsequent steps.

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.devpressure -n input=urban_2011 output=devpressure_2 method=gravity size=7 gamma=2 scaling_factor=10
r.futures.devpressure -n input=urban_2011 output=devpressure_1 method=gravity size=10 gamma=1 scaling_factor=1
r.futures.devpressure -n input=urban_2011 output=devpressure_0_5 method=gravity size=30 gamma=0.5 scaling_factor=0.1
</source>

When gamma increases, development influence decreases more rapidly with distance.
Size is half the size of the moving window. When gamma is low, local development influences more distant places.
We will derive 3 layers with different gamma and size parameters for the potential statistical model.

=== Rescaling variables ===

First we will look at the ranges of our predictor variables by running a short Python code snippet in Python shell:

<source lang="python" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
for name in ['slope', 'dist_to_water', 'dist_to_protected', 'forest_smooth', 'travel_time_cities', 'road_dens', 'dist_interchanges', 'devpressure_0_5', 'devpressure_1']:
minmax = grass.raster_info(name)
print name, minmax['min'], minmax['max']
</source>

We will rescale some of our input variables:

<source lang="bash">
r.mapcalc "dist_to_water_km = dist_to_water / 1000"
r.mapcalc "dist_to_protected_km = dist_to_protected / 1000"
r.mapcalc "dist_interchanges_km = dist_interchanges / 1000"
r.mapcalc "road_dens_perc = road_dens * 100"
r.mapcalc "forest_smooth_perc = forest_smooth * 100"
</source>

=== Sampling ===
To sample only in the analyzed counties, we will clip development layer:

<source lang="bash">
r.mapcalc "urban_change_01_11 = if(urban_2011 == 1, if(urban_2001 == 0, 1, null()), 0)"
r.mapcalc "urban_change_clip = if(counties, urban_change_01_11)"
</source>

To estimate the number of sampling points, we can use {{cmd|r.report}} to report number of developed/undeveloped cells and their ratio.

<source lang="bash">
r.report map=urban_change_clip units=h,c,p
</source>

We will sample the predictors and the response variable with 5000 random points in undeveloped areas and 1000 points in developed area:

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.sample.category input=urban_change_clip output=sampling sampled=counties,devpressure_0_5,devpressure_1,devpressure_2,slope,road_dens_perc,forest_smooth_perc,dist_to_water_km,dist_to_protected_km,dist_interchanges_km,travel_time_cities npoints=5000,1000
</source>

The attribute table can be exported as CSV file (not necessary step):

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
v.db.select map=sampling columns=urban_change_clip,counties,devpressure_0_5,devpressure_1,slope,road_dens_perc,forest_smooth_perc,dist_to_water_km,dist_to_protected_km,dist_interchanges_km,travel_time_cities separator=comma file=samples.csv
</source>

=== Development potential ===
Now we find best model for predicting urbanization using {{AddonCmd|r.futures.potential}} which wraps an R script.

We can run R [http://www.inside-r.org/packages/cran/MuMIn/docs/dredge dredge] function to find "best" model. We can specify minimum and maximum number of predictors the final model should use.
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.potential -d input=sampling output=potential.csv columns=devpressure_1,slope,road_dens_perc,forest_smooth_perc,dist_to_water_km,dist_to_protected_km,dist_interchanges_km,travel_time_cities developed_column=urban_change_clip subregions_column=counties min_variables=4
</source>

Also, we can play with different combinations of predictors, for example:

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.potential input=sampling output=potential.csv columns=devpressure_2,road_dens_perc,slope,dist_interchanges_km,dist_to_water_km developed_column=urban_change_clip subregions_column=counties --o
r.futures.potential input=sampling output=potential.csv columns=devpressure_1,road_dens_perc,slope,dist_interchanges_km,dist_to_water_km developed_column=urban_change_clip subregions_column=counties --o
...
</source>

You can then open the output file <tt>potential.csv</tt>, which is a CSV file with tabs as separators.

For this tutorial, the final potential is created with:
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.potential input=sampling output=potential.csv columns=devpressure_2,road_dens_perc,slope,dist_interchanges_km,dist_to_water_km developed_column=urban_change_clip subregions_column=counties --o
</source>

We can now visualize the suitability surface using module {{AddonCmd|r.futures.potsurface}}. It creates initial development potential (suitability) raster from predictors and model coefficients and serves only for evaluating development potential model. The values of the resulting raster range from 0 to 1.

<source lang="bash">
r.futures.potsurface input=potential.csv subregions=counties output=suitability
r.colors map=suitability color=byr
</source>

== Demand submodel ==
First we will mask out roads so that they don't influence into per capita land demand relation.
<source lang="bash">
v.to.rast input=roads type=line output=roads_mask use=val
r.mask roads_mask -i
</source>

We will use {{AddonCmd|r.futures.demand}} which derives the population vs. development relation. The relation can be linear/logarithmic/logarithmic2/exponential/exponential approach.
Look for examples of the different relations in the manual.

* linear: y = A + Bx
* logarithmic: y = A + Bln(x)
* logarithmic2: y = A + B * ln(x - C)        (requires SciPy)
* exponential: y = Ae^(BX)
* exp_approach: y = (1 - e^(-A(x - B))) + C        (requires SciPy)

The format of the input population CSV files is described in the manual. It is important to have synchronized categories of subregions and the column headers of the CSV files (in our case FIPS number). How to simply generate the list of years (for which demand is computed) is described in {{AddonCmd|r.futures.demand}} manual, for example run this in Python console:

<source lang="python">
','.join([str(i) for i in range(2011, 2036)])
</source>

Then we can create the DEMAND file:
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.demand development=urban_1992,urban_2001,urban_2011 subregions=counties observed_population=population_trend.csv projected_population=population_projection.csv simulation_times=2011,2012,2013,2014,2015,2016,2017,2018,2019,2020,2021,2022,2023,2024,2025,2026,2027,2028,2029,2030,2031,2032,2033,2034,2035 plot=plot_demand.pdf demand=demand.csv separator=comma
</source>

In your current working directory, you should find files <tt>plot_demand.png</tt> and <tt>demand.csv</tt>.

If you have SciPy installed, you can experiment with other methods for fitting the functions:
<source lang="bash">
r.futures.demand ... method=logarithmic2
r.futures.demand ... method=exp_approach
</source>
If necessary, you can create a set of demand files produced by fitting each method separately and
then pick for each county the method which seems best and manually create a new demand file.

When you are finished, remove the mask as it is not needed for the next steps.
<source lang="bash">
r.mask -r
</source>

== Patch calibration ==
Patch calibration can be a very time consuming computation.
Therefore we select only one county (Buncombe):

<source lang="bash">
v.to.rast input=counties type=area where="FIPS == 37021" use=attr attribute_column=FIPS output=calib_county
g.region raster=calib_county zoom=calib_county
</source>
to derive patches of new development by comparing historical and latest development.
We can keep only patches with minimum size 2 cells (1800 = 2 x 30 x 30 m).

<source lang="bash">
r.futures.calib development_start=urban_1992 development_end=urban_2011 subregions=counties patch_sizes=patches.txt patch_threshold=1800 -l
</source>
We obtained a file <tt>patches.txt</tt> (used later in the PGA) - a patch size distribution file - containing sizes of all found patches.

We can look at the distribution of the patch sizes:

<source lang="python">
from matplotlib import pyplot as plt
with open('patches.txt') as f:
patches = [int(patch) for patch in f.readlines()]
plt.hist(patches, 2000)
plt.xlim(0,50)
plt.show()
</source>

At this point, we start the calibration to get best parameters of patch shape
(for this tutorial, this step can be skipped and the suggested parameters are used).

<source lang="bash"
style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.calib development_start=urban_1992 development_end=urban_2011 subregions=calib_county patch_sizes=patches.txt calibration_results=calib.csv patch_threshold=1800 repeat=5 compactness_mean=0.1,0.3,0.5,0.7,0.9 compactness_range=0.05 discount_factor=0.1,0.3,0.5,0.7,0.9 predictors=road_dens_perc,forest_smooth_perc,dist_to_protected_km demand=demand.csv devpot_params=potential.csv num_neighbors=4 seed_search=2 development_pressure=devpressure_0_5 development_pressure_approach=gravity n_dev_neighbourhood=30 gamma=0.5 scaling_factor=0.1
</source>

== FUTURES simulation ==
We will switch back to our previous region:
<source lang="bash">
g.region raster=landuse_2011 -p
</source>

Now we have all the inputs necessary for running {{AddonCmd|r.futures.pga}}:

The entire command is here:
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.pga subregions=counties developed=urban_2011 predictors=slope,forest_smooth_perc,dist_interchanges_km,travel_time_cities devpot_params=potential.csv development_pressure=devpressure_1 n_dev_neighbourhood=10 development_pressure_approach=gravity gamma=1 scaling_factor=1 demand=demand.csv discount_factor=0.3 compactness_mean=0.2 compactness_range=0.1 patch_sizes=patches.txt num_neighbors=4 seed_search=2 random_seed=1 output=final output_series=final
</source>

=== Quick description ===
The command parameters and their values:
* raster map of counties with their categories
<code>
... subregions=counties ...
</code>

* raster of developed (1), undeveloped (0) and NULLs for undevelopable areas
<code>
... developed=urban_2011 ...
</code>

* predictors selected with {{AddonCmd|r.futures.potential}} and their coefficients in a <tt>potential.csv</tt> file. The order of predictors must match the order in the file and the categories of the counties must match raster <tt>counties</tt>.
<code>
... predictors=slope,forest_smooth_perc,dist_interchanges_km,travel_time_cities devpot_params=potential.csv ...
</code>

* initial development pressure computed by {{AddonCmd|r.futures.devpressure}}, it's important to set here the same parameters
<code>
... development_pressure=devpressure_1 n_dev_neighbourhood=10 development_pressure_approach=gravity gamma=1 scaling_factor=1 ...
</code>

* per capita land demand computed by {{AddonCmd|r.futures.demand}}, the categories of the counties must match raster <tt>counties</tt>.
<code>
... demand=demand.csv ...
</code>

* patch parameters from the calibration step
<code>
... discount_factor=0.3 compactness_mean=0.4 compactness_range=0.08 patch_sizes=patches.txt ...
</code>

* recommended parameters for patch growing algorithm
<code>
... num_neighbors=4 seed_search=2 ...
</code>

* set random seed for repeatable results or set flag <tt>-s</tt> to generate seed automatically
<code>
... random_seed=1 ...
</code>

* specify final output map and optionally basename for intermediate raster maps
<code>
output=final output_series=final
</code>

== Scenarios ==
Scenarios involving policies that encourage infill versus sprawl can be explored using the <tt>incentive_power</tt> parameter of {{AddonCmd|r.futures.pga}},
which uses a power function to transform the evenness of the probability gradient in POTENTIAL. You can change the power to a number between 0.25 and 4 to test urban sprawl/infill scenarios.
Higher power leads to infill behavior, lower power to urban sprawl.

== Postprocessing ==

Follow a [[Creating_animation_from_FUTURES_output_in_GRASS_GIS| tutorial how to make an animation from the results]].

= GRASS GIS Python API =

[[Category: Tutorial]]
[[Category: FUTURES]]
[[Category: Urban]]

Workshop on urban growth modeling with FUTURES

2016-03-21T20:04:23Z

⚠️Dbvanber: /* Installation */

{{ToModify}}
= Workshop introduction =
r.futures.* is an implementation of FUTure Urban-Regional Environment Simulation (FUTURES)[1] which is a model for multilevel simulations of emerging urban-rural landscape structure. FUTURES produces regional projections of landscape patterns using coupled submodels that integrate nonstationary drivers of land change: per capita demand (DEMAND submodel), site suitability (POTENTIAL submodel), and the spatial structure of conversion events (PGA submodel).

[1] Meentemeyer, R. K., Tang, W., Dorning, M. A., Vogler, J. B., Cunniffe, N. J., & Shoemaker, D. A. (2013). [http://www.tandfonline.com/doi/abs/10.1080/00045608.2012.707591 FUTURES: multilevel simulations of emerging urban-rural landscape structure using a stochastic patch-growing algorithm.] Annals of the Association of American Geographers, 103(4), 785-807

== Software ==
Required software includes:
* GRASS GIS 7
* addons
** {{AddonCmd|r.futures.pga}}
** {{AddonCmd|r.futures.potential}}
** {{AddonCmd|r.futures.potsurface}}
** {{AddonCmd|r.futures.demand}}
** {{AddonCmd|r.futures.devpressure}}
** {{AddonCmd|r.sample.category}}
* R (≥ 3.0.2) - needed for {{AddonCmd|r.futures.potential}} with packages:
**MuMIn, lme4, optparse, rgrass7
* SciPy - useful for {{AddonCmd|r.futures.demand}}

=== Installation ===
There are a number of software requirements to run FUTURES that will need to be download and installed.

We use the R statistical software for our calculation of site suitability (i.e. development potential) in FUTURES. R is a free software environment for statistical computing and graphics. If you don't have R, or you have older an version, please download and install the software from [http://archive.linux.duke.edu/cran/ install R] and be sure to additionally add these required packages:
<pre>
install.packages(c("MuMIn", "lme4", "optparse", "rgrass7"))
</pre>

==== MS Windows ====
We will be using GRASS GIS 7.0.3 that can be found here in the [https://trac.osgeo.org/osgeo4w/ OSGeo4W] package manager.
Please install the latest stable GRASS GIS 7 version and the SciPy Python package using the ''Advanced install'' option.
A guide with step by step screen shot instructions is available [https://docs.google.com/presentation/d/1yEGpriBne7RvjB35HI6GecNwO1P1y2nRGqDThqoNnCE/edit?usp=sharing here].

In order for GRASS to be able to find R executables, GRASS must be on the PATH variable. Follow this [solution] to make R accessible from GRASS permanently.
A simple but temporary solution is to open GRASS GIS and paste this in the black terminal:
<pre>
set PATH=%PATH%;C:\Program Files\R\R-3.0.2\bin
</pre>
This has to be repeated after restarting GRASS session.

==== Ubuntu Linux ====
Install GRASS GIS from packages:
<pre>
sudo add-apt-repository ppa:ubuntugis/ubuntugis-unstable
sudo apt-get update
sudo apt-get install grass
</pre>

== Workshop data ==
Download [http://fatra.cnr.ncsu.edu/futures/futures_ncspm_Asheville.zip sample dataset] containing GRASS GIS location with:
* digital elevation model ([http://nationalmap.gov/elevation.html NED])
* [http://www.mrlc.gov/ NLCD] 2001, 2011
* NLCD 1992/2001 Retrofit Land Cover Change Product
* transportation network ([http://www.census.gov/geo/maps-data/data/tiger-line.html TIGER])
* county boundaries ([http://www.census.gov/geo/maps-data/data/tiger-line.html TIGER])
* protected areas ([http://www.conservationgateway.org/ConservationByGeography/NorthAmerica/UnitedStates/edc/reportsdata/terrestrial/secured/Pages/default.aspx Secured Lands])
* cities as points (USGS)

In addition, download [http://fatra.cnr.ncsu.edu/futures/futures_Asheville_files.zip population information as text files]:
* county population past estimates and future projections ([https://www.osbm.nc.gov/demog/county-projections NC OSBM]) per county (nonspatial)

= GRASS GIS introduction =
* Overview of GRASS GIS project: [https://grass.osgeo.org grass.osgeo.org]
* Overview of [https://grass.osgeo.org/grass71/manuals/grass_database.html GRASS database].
** ''GRASS database'': directory with Locations (projects)
** ''Location'': directory with Mapsets, defined by projection (spatial reference system)
** ''Mapset'': collection of maps
* Download the [http://fatra.cnr.ncsu.edu/futures/futures_ncspm_Asheville.zip workshop location]. Create (unless you already have it) a directory named <tt>grassdata</tt> (GRASS database) in your home folder (or Documents), unzip the downloaded data into this directory. You should have now Location <tt>futures_ncspm</tt> in <tt>grassdata</tt>.
* Launch GRASS and display raster, vector data, explore navigation, querying, adding legend, showing metadata
<center><gallery perrow=3 widths=500 heights=250>Image:GRASS FUTURES startup.png|GRASS GIS 7.0.3 startup dialog with downloaded Location and Mapsets for FUTURES workshop
Image:GRASS FUTURES wxGUI display.png|Layer Manager and Map Display overview. Annotations show how to add raster layer, query, add legend.
Image:wxGUI_metadata_rinfo.png|Show raster map metadata by right click on layer</gallery></center>

* GRASS GIS has over [https://grass.osgeo.org/grass70/manuals/full_index.html 500 different modules] in the core distribution and over [https://grass.osgeo.org/grass70/manuals/addons/ 230 addon modules]
<center>
{| class="wikitable"
|-
! Prefix !! Function !! Example
|-
| r.* || raster processing || ''{{cmd|r.mapcalc}}'': map algebra
|-
| v.* || vector processing || ''{{cmd|v.clean}}'': topological cleaning
|-
| i.* || imagery processing || ''{{cmd|i.segment}}'': object recognition
|-
| db.* || database management || ''{{cmd|db.select}}'': select values from table
|-
| r3.* || 3D raster processing || ''{{cmd|r3.stats}}'': 3D raster statistics
|-
| t.* || temporal data processing || ''{{cmd|t.rast.aggregate}}'': temporal aggregation
|-
| g.* || general data management || ''{{cmd|g.rename}}'': renames map
|-
| d.* || display ||''{{cmd|d.rast}}'': display raster map
|}</center>
* GRASS modules have GUI and command line interface. In this workshop we use commands to describe the workflow, but we can use both GUI and command line depending on personal preference. Look how {{cmd|wxGUI.modules|version=71|desc=GUI and command line interface}} represent the same tool. ''Task:'' compute aspect (orientation) from provided digital elevation model using module {{cmd|r.slope.aspect}} using both module dialog and command line.
* How to find modules? Modules are organized by their functionality in wxGUI menu, or we can search for them in Search modules tab. If we already know which module to use, we can just type it in the wxGUI command console. <center><gallery perrow=3 widths=380 heights=190>Image:wxGUI_menu_rinfo.png|Modules can be found in wxGUI menu
Image:wxGUI_module_search.png|You can search modules by name, description or keywords in ''Search modules'' tab
Image:wxGUI_console_completion.png|By typing prefix r. we make a list of modules starting with that prefix to show up.</gallery></center>


* {{cmd|g.region|desc=Computational region}} - an important raster concept
** defined by region extent and raster resolution
** applies to all raster operations
** persists between GRASS session, can be different for different mapsets
** advantages: keeps your results consistent, avoid clipping, for computationally demanding tasks set region to smaller extent, check your result is good and then set the computational region to the entire study area and rerun analysis
** run <code>g.region -p</code> or in menu ''Settings'' - ''Region'' - ''Display region'' to see current region settings
[[File:WxGUI set region.png|700px|thumb|center|Simple ways to set computational region from GUI. On the left, set region to match raster map. On the right, select the highlighted option and then set region by drawing rectangle.]]

* GRASS 3D view

= Modeling with FUTURES =
== Initial steps and data preparation ==
First we will set computational region of our analyses to an extent covering our study area and so that the cells are aligned with one of our landuse rasters:
<source lang="bash">g.region raster=landuse_2011 -p</source>

We will derive urbanized areas from NLCD dataset for year 1992, 2001 and 2011
by extracting categories category 21 - 24 into a new binary map where developed is 1,
undeveloped 0 and NULL (no data) is area unsuitable for development (water, wetlands, protected areas).
First we will convert protected areas from vector to raster. We set
NULLs to zeros (for simpler raster algebra expression in the next step) using {{cmd|r.null}}:

<source lang="bash">
v.to.rast input=protected_areas output=protected_areas use=val
r.null map=protected_areas null=0
</source>

And then create rasters of developed/undeveloped areas using raster algebra:

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.mapcalc "urban_1992 = if(landuse_1992 >= 21 && landuse_1992 <= 24, 1, if(landuse_1992 == 11 || landuse_1992 >= 90 || protected_areas, null(), 0))"
r.mapcalc "urban_2001 = if(landuse_2001 >= 21 && landuse_2001 <= 24, 1, if(landuse_2001 == 11 || landuse_2001 >= 90 || protected_areas, null(), 0))"
r.mapcalc "urban_2011 = if(landuse_2011 >= 21 && landuse_2011 <= 24, 1, if(landuse_2011 == 11 || landuse_2011 >= 90 || protected_areas, null(), 0))"
</source>

We will convert vector counties to raster with the values of the FIPS attribute which links to population file:

<source lang="bash">
v.to.rast input=counties type=area use=attr attribute_column=FIPS output=counties
</source>

Before further steps, we will set our working directory so that the input population files and text files
we are going to create are saved in one directory and easily accessible.
You can do that from menu ''Settings'' → ''GRASS working environment'' → ''Change working directory''.
Select (or create) a directory and move there the downloaded files <tt>population_projection.csv</tt> and <tt>population_trend.csv</tt>.

== Potential submodel ==
Module {{AddonCmd|r.futures.potential}} implements POTENTIAL submodel as a part of FUTURES land change model. POTENTIAL is implemented using a set of coefficients that relate a selection of site suitability factors to the probability of a place becoming developed. This is implemented using the parameter table in combination with maps of those site suitability factors (mapped predictors). The coefficients are obtained by conducting multilevel logistic regression in R with package lme4 where the coefficients may vary by county. The best model is selected automatically using dredge function from package [https://cran.r-project.org/web/packages/MuMIn/index.html MuMIn].

First, we will derive couple of predictors.
=== Predictors ===
==== Slope ====
We will derive slope in degrees from digital elevation model using {{cmd|r.slope.aspect}} module:
<source lang="bash">r.slope.aspect elevation=elevation_30m slope=slope</source>

==== Distance from lakes/rivers ====
First we will extract [http://www.mrlc.gov/nlcd11_leg.php category ''Open Water''] from 2011 NLCD dataset:
<source lang="bash">
r.mapcalc "water = if(landuse_2011 == 11, 1, null())"
</source>

Then we compute the distance to water with module {{cmd|r.grow.distance}} and set color table to shades of blue:
<source lang="bash">
r.grow.distance input=water distance=dist_to_water
r.colors -n map=dist_to_water color=blues
</source>

==== Distance from protected areas ====
We will use raster protected of protected areas we already created, but we will set NULL values to zero.
We compute the distance to protected areas with module {{cmd|r.grow.distance}} and set color table from green to red:
<source lang="bash">
r.null map=protected_areas setnull=0
r.grow.distance input=protected_areas distance=dist_to_protected
r.colors map=dist_to_protected color=gyr
</source>

==== Forests ====
We will smooth the transition between forest and other land use, see NLCD [http://www.mrlc.gov/nlcd11_leg.php category ''Open Water'']:
<source lang="bash">
r.mapcalc "forest = if(landuse_2011 >= 41 && landuse_2011 <= 43, 1, 0)"
r.neighbors -c input=forest output=forest_smooth size=15 method=average
r.colors map=forest_smooth color=ndvi
</source>

==== Travel time to cities ====
Here we will compute travel time to cities (with population > 5000)
as cumulative cost distance where cost is defined as travel time on roads.
First we specify the speed on different types of roads.
We copy the roads raster into our mapset so that we can change it
by adding a new attribute field <tt>speed</tt>. Then we assign speed values (km/h) based on the type of road:

<source lang="bash">
g.copy vector=roads,myroads
v.db.addcolumn map=myroads columns="speed double precision"
v.db.update map=myroads column=speed value=50 where="MTFCC = 'S1400'"
v.db.update map=myroads column=speed value=100 where="MTFCC IN ('S1100', 'S1200')"
</source>

Now we rasterize the selected road types using the speed values from the attribute table as raster values.

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
v.to.rast input=myroads type=line where="MTFCC IN ('S1100', 'S1200', 'S1400')" output=roads_speed use=attr attribute_column=speed
</source>

We set the rest of the area to low speed and recompute the speed as time to travel through a 30m cell in minutes:

<source lang="bash">
r.null map=roads_speed null=5
r.mapcalc "roads_travel_time = 1.8 / roads_speed"
</source>

Finally we compute the travel time to larger cities using {{cmd|r.cost}}:

<source lang="bash">
r.cost input=roads_travel_time output=travel_time_cities start_points=cities
r.colors map=travel_time_cities color=byr
</source>

==== Road density ====
We will rasterize roads and use moving window analysis ({{cmd|r.neighbors}}) to compute road density:

<source lang="bash">
v.to.rast input=roads output=roads use=val type=line
r.null map=roads null=0
r.neighbors -c input=roads output=road_dens size=25 method=average
</source>

==== Distance to interchanges ====

We will consider TIGER roads of type <tt>Ramp</tt> as interchanges, rasterize them and compute euclidean distance to them:

<source lang="bash">
v.to.rast input=roads type=line where="MTFCC = 'S1630'" output=interchanges use=val
r.grow.distance -m input=interchanges distance=dist_interchanges
</source>

=== Development pressure ===

We compute development pressure with {{AddonCmd|r.futures.devpressure}}. Development pressure is a predictor based on number of neighboring developed cells within search distance, weighted by distance. The development pressure variable plays a special role in the model, allowing for a feedback between predicted change and change in subsequent steps.

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.devpressure -n input=urban_2011 output=devpressure_2 method=gravity size=7 gamma=2 scaling_factor=10
r.futures.devpressure -n input=urban_2011 output=devpressure_1 method=gravity size=10 gamma=1 scaling_factor=1
r.futures.devpressure -n input=urban_2011 output=devpressure_0_5 method=gravity size=30 gamma=0.5 scaling_factor=0.1
</source>

When gamma increases, development influence decreases more rapidly with distance.
Size is half the size of the moving window. When gamma is low, local development influences more distant places.
We will derive 3 layers with different gamma and size parameters for the potential statistical model.

=== Rescaling variables ===

First we will look at the ranges of our predictor variables by running a short Python code snippet in Python shell:

<source lang="python" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
for name in ['slope', 'dist_to_water', 'dist_to_protected', 'forest_smooth', 'travel_time_cities', 'road_dens', 'dist_interchanges', 'devpressure_0_5', 'devpressure_1']:
minmax = grass.raster_info(name)
print name, minmax['min'], minmax['max']
</source>

We will rescale some of our input variables:

<source lang="bash">
r.mapcalc "dist_to_water_km = dist_to_water / 1000"
r.mapcalc "dist_to_protected_km = dist_to_protected / 1000"
r.mapcalc "dist_interchanges_km = dist_interchanges / 1000"
r.mapcalc "road_dens_perc = road_dens * 100"
r.mapcalc "forest_smooth_perc = forest_smooth * 100"
</source>

=== Sampling ===
To sample only in the analyzed counties, we will clip development layer:

<source lang="bash">
r.mapcalc "urban_change_01_11 = if(urban_2011 == 1, if(urban_2001 == 0, 1, null()), 0)"
r.mapcalc "urban_change_clip = if(counties, urban_change_01_11)"
</source>

To estimate the number of sampling points, we can use {{cmd|r.report}} to report number of developed/undeveloped cells and their ratio.

<source lang="bash">
r.report map=urban_change_clip units=h,c,p
</source>

We will sample the predictors and the response variable with 5000 random points in undeveloped areas and 1000 points in developed area:

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.sample.category input=urban_change_clip output=sampling sampled=counties,devpressure_0_5,devpressure_1,devpressure_2,slope,road_dens_perc,forest_smooth_perc,dist_to_water_km,dist_to_protected_km,dist_interchanges_km,travel_time_cities npoints=5000,1000
</source>

The attribute table can be exported as CSV file (not necessary step):

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
v.db.select map=sampling columns=urban_change_clip,counties,devpressure_0_5,devpressure_1,slope,road_dens_perc,forest_smooth_perc,dist_to_water_km,dist_to_protected_km,dist_interchanges_km,travel_time_cities separator=comma file=samples.csv
</source>

=== Development potential ===
Now we find best model for predicting urbanization using {{AddonCmd|r.futures.potential}} which wraps an R script.

We can run R [http://www.inside-r.org/packages/cran/MuMIn/docs/dredge dredge] function to find "best" model. We can specify minimum and maximum number of predictors the final model should use.
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.potential -d input=sampling output=potential.csv columns=devpressure_1,slope,road_dens_perc,forest_smooth_perc,dist_to_water_km,dist_to_protected_km,dist_interchanges_km,travel_time_cities developed_column=urban_change_clip subregions_column=counties min_variables=4
</source>

Also, we can play with different combinations of predictors, for example:

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.potential input=sampling output=potential.csv columns=devpressure_2,road_dens_perc,slope,dist_interchanges_km,dist_to_water_km developed_column=urban_change_clip subregions_column=counties --o
r.futures.potential input=sampling output=potential.csv columns=devpressure_1,road_dens_perc,slope,dist_interchanges_km,dist_to_water_km developed_column=urban_change_clip subregions_column=counties --o
...
</source>

You can then open the output file <tt>potential.csv</tt>, which is a CSV file with tabs as separators.

For this tutorial, the final potential is created with:
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.potential input=sampling output=potential.csv columns=devpressure_2,road_dens_perc,slope,dist_interchanges_km,dist_to_water_km developed_column=urban_change_clip subregions_column=counties --o
</source>

We can now visualize the suitability surface using module {{AddonCmd|r.futures.potsurface}}. It creates initial development potential (suitability) raster from predictors and model coefficients and serves only for evaluating development potential model. The values of the resulting raster range from 0 to 1.

<source lang="bash">
r.futures.potsurface input=potential.csv subregions=counties output=suitability
r.colors map=suitability color=byr
</source>

== Demand submodel ==
First we will mask out roads so that they don't influence into per capita land demand relation.
<source lang="bash">
v.to.rast input=roads type=line output=roads_mask use=val
r.mask roads_mask -i
</source>

We will use {{AddonCmd|r.futures.demand}} which derives the population vs. development relation. The relation can be linear/logarithmic/logarithmic2/exponential/exponential approach.
Look for examples of the different relations in the manual.

* linear: y = A + Bx
* logarithmic: y = A + Bln(x)
* logarithmic2: y = A + B * ln(x - C)        (requires SciPy)
* exponential: y = Ae^(BX)
* exp_approach: y = (1 - e^(-A(x - B))) + C        (requires SciPy)

The format of the input population CSV files is described in the manual. It is important to have synchronized categories of subregions and the column headers of the CSV files (in our case FIPS number). How to simply generate the list of years (for which demand is computed) is described in {{AddonCmd|r.futures.demand}} manual, for example run this in Python console:

<source lang="python">
','.join([str(i) for i in range(2011, 2036)])
</source>

Then we can create the DEMAND file:
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.demand development=urban_1992,urban_2001,urban_2011 subregions=counties observed_population=population_trend.csv projected_population=population_projection.csv simulation_times=2011,2012,2013,2014,2015,2016,2017,2018,2019,2020,2021,2022,2023,2024,2025,2026,2027,2028,2029,2030,2031,2032,2033,2034,2035 plot=plot_demand.pdf demand=demand.csv separator=comma
</source>

In your current working directory, you should find files <tt>plot_demand.png</tt> and <tt>demand.csv</tt>.

If you have SciPy installed, you can experiment with other methods for fitting the functions:
<source lang="bash">
r.futures.demand ... method=logarithmic2
r.futures.demand ... method=exp_approach
</source>
If necessary, you can create a set of demand files produced by fitting each method separately and
then pick for each county the method which seems best and manually create a new demand file.

When you are finished, remove the mask as it is not needed for the next steps.
<source lang="bash">
r.mask -r
</source>

== Patch calibration ==
Patch calibration can be a very time consuming computation.
Therefore we select only one county (Buncombe):

<source lang="bash">
v.to.rast input=counties type=area where="FIPS == 37021" use=attr attribute_column=FIPS output=calib_county
g.region raster=calib_county zoom=calib_county
</source>
to derive patches of new development by comparing historical and latest development.
We can keep only patches with minimum size 2 cells (1800 = 2 x 30 x 30 m).

<source lang="bash">
r.futures.calib development_start=urban_1992 development_end=urban_2011 subregions=counties patch_sizes=patches.txt patch_threshold=1800 -l
</source>
We obtained a file <tt>patches.txt</tt> (used later in the PGA) - a patch size distribution file - containing sizes of all found patches.

We can look at the distribution of the patch sizes:

<source lang="python">
from matplotlib import pyplot as plt
with open('patches.txt') as f:
patches = [int(patch) for patch in f.readlines()]
plt.hist(patches, 2000)
plt.xlim(0,50)
plt.show()
</source>

At this point, we start the calibration to get best parameters of patch shape
(for this tutorial, this step can be skipped and the suggested parameters are used).

<source lang="bash"
style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.calib development_start=urban_1992 development_end=urban_2011 subregions=calib_county patch_sizes=patches.txt calibration_results=calib.csv patch_threshold=1800 repeat=5 compactness_mean=0.1,0.3,0.5,0.7,0.9 compactness_range=0.05 discount_factor=0.1,0.3,0.5,0.7,0.9 predictors=road_dens_perc,forest_smooth_perc,dist_to_protected_km demand=demand.csv devpot_params=potential.csv num_neighbors=4 seed_search=2 development_pressure=devpressure_0_5 development_pressure_approach=gravity n_dev_neighbourhood=30 gamma=0.5 scaling_factor=0.1
</source>

== FUTURES simulation ==
We will switch back to our previous region:
<source lang="bash">
g.region raster=landuse_2011 -p
</source>

Now we have all the inputs necessary for running {{AddonCmd|r.futures.pga}}:

The entire command is here:
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.pga subregions=counties developed=urban_2011 predictors=slope,forest_smooth_perc,dist_interchanges_km,travel_time_cities devpot_params=potential.csv development_pressure=devpressure_1 n_dev_neighbourhood=10 development_pressure_approach=gravity gamma=1 scaling_factor=1 demand=demand.csv discount_factor=0.3 compactness_mean=0.2 compactness_range=0.1 patch_sizes=patches.txt num_neighbors=4 seed_search=2 random_seed=1 output=final output_series=final
</source>

=== Quick description ===
The command parameters and their values:
* raster map of counties with their categories
<code>
... subregions=counties ...
</code>

* raster of developed (1), undeveloped (0) and NULLs for undevelopable areas
<code>
... developed=urban_2011 ...
</code>

* predictors selected with {{AddonCmd|r.futures.potential}} and their coefficients in a <tt>potential.csv</tt> file. The order of predictors must match the order in the file and the categories of the counties must match raster <tt>counties</tt>.
<code>
... predictors=slope,forest_smooth_perc,dist_interchanges_km,travel_time_cities devpot_params=potential.csv ...
</code>

* initial development pressure computed by {{AddonCmd|r.futures.devpressure}}, it's important to set here the same parameters
<code>
... development_pressure=devpressure_1 n_dev_neighbourhood=10 development_pressure_approach=gravity gamma=1 scaling_factor=1 ...
</code>

* per capita land demand computed by {{AddonCmd|r.futures.demand}}, the categories of the counties must match raster <tt>counties</tt>.
<code>
... demand=demand.csv ...
</code>

* patch parameters from the calibration step
<code>
... discount_factor=0.3 compactness_mean=0.4 compactness_range=0.08 patch_sizes=patches.txt ...
</code>

* recommended parameters for patch growing algorithm
<code>
... num_neighbors=4 seed_search=2 ...
</code>

* set random seed for repeatable results or set flag <tt>-s</tt> to generate seed automatically
<code>
... random_seed=1 ...
</code>

* specify final output map and optionally basename for intermediate raster maps
<code>
output=final output_series=final
</code>

== Scenarios ==
Scenarios involving policies that encourage infill versus sprawl can be explored using the <tt>incentive_power</tt> parameter of {{AddonCmd|r.futures.pga}},
which uses a power function to transform the evenness of the probability gradient in POTENTIAL. You can change the power to a number between 0.25 and 4 to test urban sprawl/infill scenarios.
Higher power leads to infill behavior, lower power to urban sprawl.

== Postprocessing ==

Follow a [[Creating_animation_from_FUTURES_output_in_GRASS_GIS| tutorial how to make an animation from the results]].

= GRASS GIS Python API =

[[Category: Tutorial]]
[[Category: FUTURES]]
[[Category: Urban]]

Workshop on urban growth modeling with FUTURES

2016-03-21T20:03:24Z

⚠️Dbvanber:

{{ToModify}}
= Workshop introduction =
r.futures.* is an implementation of FUTure Urban-Regional Environment Simulation (FUTURES)[1] which is a model for multilevel simulations of emerging urban-rural landscape structure. FUTURES produces regional projections of landscape patterns using coupled submodels that integrate nonstationary drivers of land change: per capita demand (DEMAND submodel), site suitability (POTENTIAL submodel), and the spatial structure of conversion events (PGA submodel).

[1] Meentemeyer, R. K., Tang, W., Dorning, M. A., Vogler, J. B., Cunniffe, N. J., & Shoemaker, D. A. (2013). [http://www.tandfonline.com/doi/abs/10.1080/00045608.2012.707591 FUTURES: multilevel simulations of emerging urban-rural landscape structure using a stochastic patch-growing algorithm.] Annals of the Association of American Geographers, 103(4), 785-807

== Software ==
Required software includes:
* GRASS GIS 7
* addons
** {{AddonCmd|r.futures.pga}}
** {{AddonCmd|r.futures.potential}}
** {{AddonCmd|r.futures.potsurface}}
** {{AddonCmd|r.futures.demand}}
** {{AddonCmd|r.futures.devpressure}}
** {{AddonCmd|r.sample.category}}
* R (≥ 3.0.2) - needed for {{AddonCmd|r.futures.potential}} with packages:
**MuMIn, lme4, optparse, rgrass7
* SciPy - useful for {{AddonCmd|r.futures.demand}}

=== Installation ===
There are a number of software needed to run FUTURES that will need to be download and installed.

We use the R statistical software for our calculation of site suitability (i.e. development potential) in FUTURES. R is a free software environment for statistical computing and graphics. If you don't have R, or you have older an version, please download and install the software from [http://archive.linux.duke.edu/cran/ install R] and be sure to additionally add these required packages:
<pre>
install.packages(c("MuMIn", "lme4", "optparse", "rgrass7"))
</pre>

==== MS Windows ====
We will be using GRASS GIS 7.0.3 that can be found here in the [https://trac.osgeo.org/osgeo4w/ OSGeo4W] package manager.
Please install the latest stable GRASS GIS 7 version and the SciPy Python package using the ''Advanced install'' option.
A guide with step by step screen shot instructions is available [https://docs.google.com/presentation/d/1yEGpriBne7RvjB35HI6GecNwO1P1y2nRGqDThqoNnCE/edit?usp=sharing here].

In order for GRASS to be able to find R executables, GRASS must be on the PATH variable. Follow this [solution] to make R accessible from GRASS permanently.
A simple but temporary solution is to open GRASS GIS and paste this in the black terminal:
<pre>
set PATH=%PATH%;C:\Program Files\R\R-3.0.2\bin
</pre>
This has to be repeated after restarting GRASS session.

==== Ubuntu Linux ====
Install GRASS GIS from packages:
<pre>
sudo add-apt-repository ppa:ubuntugis/ubuntugis-unstable
sudo apt-get update
sudo apt-get install grass
</pre>

== Workshop data ==
Download [http://fatra.cnr.ncsu.edu/futures/futures_ncspm_Asheville.zip sample dataset] containing GRASS GIS location with:
* digital elevation model ([http://nationalmap.gov/elevation.html NED])
* [http://www.mrlc.gov/ NLCD] 2001, 2011
* NLCD 1992/2001 Retrofit Land Cover Change Product
* transportation network ([http://www.census.gov/geo/maps-data/data/tiger-line.html TIGER])
* county boundaries ([http://www.census.gov/geo/maps-data/data/tiger-line.html TIGER])
* protected areas ([http://www.conservationgateway.org/ConservationByGeography/NorthAmerica/UnitedStates/edc/reportsdata/terrestrial/secured/Pages/default.aspx Secured Lands])
* cities as points (USGS)

In addition, download [http://fatra.cnr.ncsu.edu/futures/futures_Asheville_files.zip population information as text files]:
* county population past estimates and future projections ([https://www.osbm.nc.gov/demog/county-projections NC OSBM]) per county (nonspatial)

= GRASS GIS introduction =
* Overview of GRASS GIS project: [https://grass.osgeo.org grass.osgeo.org]
* Overview of [https://grass.osgeo.org/grass71/manuals/grass_database.html GRASS database].
** ''GRASS database'': directory with Locations (projects)
** ''Location'': directory with Mapsets, defined by projection (spatial reference system)
** ''Mapset'': collection of maps
* Download the [http://fatra.cnr.ncsu.edu/futures/futures_ncspm_Asheville.zip workshop location]. Create (unless you already have it) a directory named <tt>grassdata</tt> (GRASS database) in your home folder (or Documents), unzip the downloaded data into this directory. You should have now Location <tt>futures_ncspm</tt> in <tt>grassdata</tt>.
* Launch GRASS and display raster, vector data, explore navigation, querying, adding legend, showing metadata
<center><gallery perrow=3 widths=500 heights=250>Image:GRASS FUTURES startup.png|GRASS GIS 7.0.3 startup dialog with downloaded Location and Mapsets for FUTURES workshop
Image:GRASS FUTURES wxGUI display.png|Layer Manager and Map Display overview. Annotations show how to add raster layer, query, add legend.
Image:wxGUI_metadata_rinfo.png|Show raster map metadata by right click on layer</gallery></center>

* GRASS GIS has over [https://grass.osgeo.org/grass70/manuals/full_index.html 500 different modules] in the core distribution and over [https://grass.osgeo.org/grass70/manuals/addons/ 230 addon modules]
<center>
{| class="wikitable"
|-
! Prefix !! Function !! Example
|-
| r.* || raster processing || ''{{cmd|r.mapcalc}}'': map algebra
|-
| v.* || vector processing || ''{{cmd|v.clean}}'': topological cleaning
|-
| i.* || imagery processing || ''{{cmd|i.segment}}'': object recognition
|-
| db.* || database management || ''{{cmd|db.select}}'': select values from table
|-
| r3.* || 3D raster processing || ''{{cmd|r3.stats}}'': 3D raster statistics
|-
| t.* || temporal data processing || ''{{cmd|t.rast.aggregate}}'': temporal aggregation
|-
| g.* || general data management || ''{{cmd|g.rename}}'': renames map
|-
| d.* || display ||''{{cmd|d.rast}}'': display raster map
|}</center>
* GRASS modules have GUI and command line interface. In this workshop we use commands to describe the workflow, but we can use both GUI and command line depending on personal preference. Look how {{cmd|wxGUI.modules|version=71|desc=GUI and command line interface}} represent the same tool. ''Task:'' compute aspect (orientation) from provided digital elevation model using module {{cmd|r.slope.aspect}} using both module dialog and command line.
* How to find modules? Modules are organized by their functionality in wxGUI menu, or we can search for them in Search modules tab. If we already know which module to use, we can just type it in the wxGUI command console. <center><gallery perrow=3 widths=380 heights=190>Image:wxGUI_menu_rinfo.png|Modules can be found in wxGUI menu
Image:wxGUI_module_search.png|You can search modules by name, description or keywords in ''Search modules'' tab
Image:wxGUI_console_completion.png|By typing prefix r. we make a list of modules starting with that prefix to show up.</gallery></center>


* {{cmd|g.region|desc=Computational region}} - an important raster concept
** defined by region extent and raster resolution
** applies to all raster operations
** persists between GRASS session, can be different for different mapsets
** advantages: keeps your results consistent, avoid clipping, for computationally demanding tasks set region to smaller extent, check your result is good and then set the computational region to the entire study area and rerun analysis
** run <code>g.region -p</code> or in menu ''Settings'' - ''Region'' - ''Display region'' to see current region settings
[[File:WxGUI set region.png|700px|thumb|center|Simple ways to set computational region from GUI. On the left, set region to match raster map. On the right, select the highlighted option and then set region by drawing rectangle.]]

* GRASS 3D view

= Modeling with FUTURES =
== Initial steps and data preparation ==
First we will set computational region of our analyses to an extent covering our study area and so that the cells are aligned with one of our landuse rasters:
<source lang="bash">g.region raster=landuse_2011 -p</source>

We will derive urbanized areas from NLCD dataset for year 1992, 2001 and 2011
by extracting categories category 21 - 24 into a new binary map where developed is 1,
undeveloped 0 and NULL (no data) is area unsuitable for development (water, wetlands, protected areas).
First we will convert protected areas from vector to raster. We set
NULLs to zeros (for simpler raster algebra expression in the next step) using {{cmd|r.null}}:

<source lang="bash">
v.to.rast input=protected_areas output=protected_areas use=val
r.null map=protected_areas null=0
</source>

And then create rasters of developed/undeveloped areas using raster algebra:

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.mapcalc "urban_1992 = if(landuse_1992 >= 21 && landuse_1992 <= 24, 1, if(landuse_1992 == 11 || landuse_1992 >= 90 || protected_areas, null(), 0))"
r.mapcalc "urban_2001 = if(landuse_2001 >= 21 && landuse_2001 <= 24, 1, if(landuse_2001 == 11 || landuse_2001 >= 90 || protected_areas, null(), 0))"
r.mapcalc "urban_2011 = if(landuse_2011 >= 21 && landuse_2011 <= 24, 1, if(landuse_2011 == 11 || landuse_2011 >= 90 || protected_areas, null(), 0))"
</source>

We will convert vector counties to raster with the values of the FIPS attribute which links to population file:

<source lang="bash">
v.to.rast input=counties type=area use=attr attribute_column=FIPS output=counties
</source>

Before further steps, we will set our working directory so that the input population files and text files
we are going to create are saved in one directory and easily accessible.
You can do that from menu ''Settings'' → ''GRASS working environment'' → ''Change working directory''.
Select (or create) a directory and move there the downloaded files <tt>population_projection.csv</tt> and <tt>population_trend.csv</tt>.

== Potential submodel ==
Module {{AddonCmd|r.futures.potential}} implements POTENTIAL submodel as a part of FUTURES land change model. POTENTIAL is implemented using a set of coefficients that relate a selection of site suitability factors to the probability of a place becoming developed. This is implemented using the parameter table in combination with maps of those site suitability factors (mapped predictors). The coefficients are obtained by conducting multilevel logistic regression in R with package lme4 where the coefficients may vary by county. The best model is selected automatically using dredge function from package [https://cran.r-project.org/web/packages/MuMIn/index.html MuMIn].

First, we will derive couple of predictors.
=== Predictors ===
==== Slope ====
We will derive slope in degrees from digital elevation model using {{cmd|r.slope.aspect}} module:
<source lang="bash">r.slope.aspect elevation=elevation_30m slope=slope</source>

==== Distance from lakes/rivers ====
First we will extract [http://www.mrlc.gov/nlcd11_leg.php category ''Open Water''] from 2011 NLCD dataset:
<source lang="bash">
r.mapcalc "water = if(landuse_2011 == 11, 1, null())"
</source>

Then we compute the distance to water with module {{cmd|r.grow.distance}} and set color table to shades of blue:
<source lang="bash">
r.grow.distance input=water distance=dist_to_water
r.colors -n map=dist_to_water color=blues
</source>

==== Distance from protected areas ====
We will use raster protected of protected areas we already created, but we will set NULL values to zero.
We compute the distance to protected areas with module {{cmd|r.grow.distance}} and set color table from green to red:
<source lang="bash">
r.null map=protected_areas setnull=0
r.grow.distance input=protected_areas distance=dist_to_protected
r.colors map=dist_to_protected color=gyr
</source>

==== Forests ====
We will smooth the transition between forest and other land use, see NLCD [http://www.mrlc.gov/nlcd11_leg.php category ''Open Water'']:
<source lang="bash">
r.mapcalc "forest = if(landuse_2011 >= 41 && landuse_2011 <= 43, 1, 0)"
r.neighbors -c input=forest output=forest_smooth size=15 method=average
r.colors map=forest_smooth color=ndvi
</source>

==== Travel time to cities ====
Here we will compute travel time to cities (with population > 5000)
as cumulative cost distance where cost is defined as travel time on roads.
First we specify the speed on different types of roads.
We copy the roads raster into our mapset so that we can change it
by adding a new attribute field <tt>speed</tt>. Then we assign speed values (km/h) based on the type of road:

<source lang="bash">
g.copy vector=roads,myroads
v.db.addcolumn map=myroads columns="speed double precision"
v.db.update map=myroads column=speed value=50 where="MTFCC = 'S1400'"
v.db.update map=myroads column=speed value=100 where="MTFCC IN ('S1100', 'S1200')"
</source>

Now we rasterize the selected road types using the speed values from the attribute table as raster values.

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
v.to.rast input=myroads type=line where="MTFCC IN ('S1100', 'S1200', 'S1400')" output=roads_speed use=attr attribute_column=speed
</source>

We set the rest of the area to low speed and recompute the speed as time to travel through a 30m cell in minutes:

<source lang="bash">
r.null map=roads_speed null=5
r.mapcalc "roads_travel_time = 1.8 / roads_speed"
</source>

Finally we compute the travel time to larger cities using {{cmd|r.cost}}:

<source lang="bash">
r.cost input=roads_travel_time output=travel_time_cities start_points=cities
r.colors map=travel_time_cities color=byr
</source>

==== Road density ====
We will rasterize roads and use moving window analysis ({{cmd|r.neighbors}}) to compute road density:

<source lang="bash">
v.to.rast input=roads output=roads use=val type=line
r.null map=roads null=0
r.neighbors -c input=roads output=road_dens size=25 method=average
</source>

==== Distance to interchanges ====

We will consider TIGER roads of type <tt>Ramp</tt> as interchanges, rasterize them and compute euclidean distance to them:

<source lang="bash">
v.to.rast input=roads type=line where="MTFCC = 'S1630'" output=interchanges use=val
r.grow.distance -m input=interchanges distance=dist_interchanges
</source>

=== Development pressure ===

We compute development pressure with {{AddonCmd|r.futures.devpressure}}. Development pressure is a predictor based on number of neighboring developed cells within search distance, weighted by distance. The development pressure variable plays a special role in the model, allowing for a feedback between predicted change and change in subsequent steps.

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.devpressure -n input=urban_2011 output=devpressure_2 method=gravity size=7 gamma=2 scaling_factor=10
r.futures.devpressure -n input=urban_2011 output=devpressure_1 method=gravity size=10 gamma=1 scaling_factor=1
r.futures.devpressure -n input=urban_2011 output=devpressure_0_5 method=gravity size=30 gamma=0.5 scaling_factor=0.1
</source>

When gamma increases, development influence decreases more rapidly with distance.
Size is half the size of the moving window. When gamma is low, local development influences more distant places.
We will derive 3 layers with different gamma and size parameters for the potential statistical model.

=== Rescaling variables ===

First we will look at the ranges of our predictor variables by running a short Python code snippet in Python shell:

<source lang="python" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
for name in ['slope', 'dist_to_water', 'dist_to_protected', 'forest_smooth', 'travel_time_cities', 'road_dens', 'dist_interchanges', 'devpressure_0_5', 'devpressure_1']:
minmax = grass.raster_info(name)
print name, minmax['min'], minmax['max']
</source>

We will rescale some of our input variables:

<source lang="bash">
r.mapcalc "dist_to_water_km = dist_to_water / 1000"
r.mapcalc "dist_to_protected_km = dist_to_protected / 1000"
r.mapcalc "dist_interchanges_km = dist_interchanges / 1000"
r.mapcalc "road_dens_perc = road_dens * 100"
r.mapcalc "forest_smooth_perc = forest_smooth * 100"
</source>

=== Sampling ===
To sample only in the analyzed counties, we will clip development layer:

<source lang="bash">
r.mapcalc "urban_change_01_11 = if(urban_2011 == 1, if(urban_2001 == 0, 1, null()), 0)"
r.mapcalc "urban_change_clip = if(counties, urban_change_01_11)"
</source>

To estimate the number of sampling points, we can use {{cmd|r.report}} to report number of developed/undeveloped cells and their ratio.

<source lang="bash">
r.report map=urban_change_clip units=h,c,p
</source>

We will sample the predictors and the response variable with 5000 random points in undeveloped areas and 1000 points in developed area:

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.sample.category input=urban_change_clip output=sampling sampled=counties,devpressure_0_5,devpressure_1,devpressure_2,slope,road_dens_perc,forest_smooth_perc,dist_to_water_km,dist_to_protected_km,dist_interchanges_km,travel_time_cities npoints=5000,1000
</source>

The attribute table can be exported as CSV file (not necessary step):

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
v.db.select map=sampling columns=urban_change_clip,counties,devpressure_0_5,devpressure_1,slope,road_dens_perc,forest_smooth_perc,dist_to_water_km,dist_to_protected_km,dist_interchanges_km,travel_time_cities separator=comma file=samples.csv
</source>

=== Development potential ===
Now we find best model for predicting urbanization using {{AddonCmd|r.futures.potential}} which wraps an R script.

We can run R [http://www.inside-r.org/packages/cran/MuMIn/docs/dredge dredge] function to find "best" model. We can specify minimum and maximum number of predictors the final model should use.
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.potential -d input=sampling output=potential.csv columns=devpressure_1,slope,road_dens_perc,forest_smooth_perc,dist_to_water_km,dist_to_protected_km,dist_interchanges_km,travel_time_cities developed_column=urban_change_clip subregions_column=counties min_variables=4
</source>

Also, we can play with different combinations of predictors, for example:

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.potential input=sampling output=potential.csv columns=devpressure_2,road_dens_perc,slope,dist_interchanges_km,dist_to_water_km developed_column=urban_change_clip subregions_column=counties --o
r.futures.potential input=sampling output=potential.csv columns=devpressure_1,road_dens_perc,slope,dist_interchanges_km,dist_to_water_km developed_column=urban_change_clip subregions_column=counties --o
...
</source>

You can then open the output file <tt>potential.csv</tt>, which is a CSV file with tabs as separators.

For this tutorial, the final potential is created with:
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.potential input=sampling output=potential.csv columns=devpressure_2,road_dens_perc,slope,dist_interchanges_km,dist_to_water_km developed_column=urban_change_clip subregions_column=counties --o
</source>

We can now visualize the suitability surface using module {{AddonCmd|r.futures.potsurface}}. It creates initial development potential (suitability) raster from predictors and model coefficients and serves only for evaluating development potential model. The values of the resulting raster range from 0 to 1.

<source lang="bash">
r.futures.potsurface input=potential.csv subregions=counties output=suitability
r.colors map=suitability color=byr
</source>

== Demand submodel ==
First we will mask out roads so that they don't influence into per capita land demand relation.
<source lang="bash">
v.to.rast input=roads type=line output=roads_mask use=val
r.mask roads_mask -i
</source>

We will use {{AddonCmd|r.futures.demand}} which derives the population vs. development relation. The relation can be linear/logarithmic/logarithmic2/exponential/exponential approach.
Look for examples of the different relations in the manual.

* linear: y = A + Bx
* logarithmic: y = A + Bln(x)
* logarithmic2: y = A + B * ln(x - C)        (requires SciPy)
* exponential: y = Ae^(BX)
* exp_approach: y = (1 - e^(-A(x - B))) + C        (requires SciPy)

The format of the input population CSV files is described in the manual. It is important to have synchronized categories of subregions and the column headers of the CSV files (in our case FIPS number). How to simply generate the list of years (for which demand is computed) is described in {{AddonCmd|r.futures.demand}} manual, for example run this in Python console:

<source lang="python">
','.join([str(i) for i in range(2011, 2036)])
</source>

Then we can create the DEMAND file:
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.demand development=urban_1992,urban_2001,urban_2011 subregions=counties observed_population=population_trend.csv projected_population=population_projection.csv simulation_times=2011,2012,2013,2014,2015,2016,2017,2018,2019,2020,2021,2022,2023,2024,2025,2026,2027,2028,2029,2030,2031,2032,2033,2034,2035 plot=plot_demand.pdf demand=demand.csv separator=comma
</source>

In your current working directory, you should find files <tt>plot_demand.png</tt> and <tt>demand.csv</tt>.

If you have SciPy installed, you can experiment with other methods for fitting the functions:
<source lang="bash">
r.futures.demand ... method=logarithmic2
r.futures.demand ... method=exp_approach
</source>
If necessary, you can create a set of demand files produced by fitting each method separately and
then pick for each county the method which seems best and manually create a new demand file.

When you are finished, remove the mask as it is not needed for the next steps.
<source lang="bash">
r.mask -r
</source>

== Patch calibration ==
Patch calibration can be a very time consuming computation.
Therefore we select only one county (Buncombe):

<source lang="bash">
v.to.rast input=counties type=area where="FIPS == 37021" use=attr attribute_column=FIPS output=calib_county
g.region raster=calib_county zoom=calib_county
</source>
to derive patches of new development by comparing historical and latest development.
We can keep only patches with minimum size 2 cells (1800 = 2 x 30 x 30 m).

<source lang="bash">
r.futures.calib development_start=urban_1992 development_end=urban_2011 subregions=counties patch_sizes=patches.txt patch_threshold=1800 -l
</source>
We obtained a file <tt>patches.txt</tt> (used later in the PGA) - a patch size distribution file - containing sizes of all found patches.

We can look at the distribution of the patch sizes:

<source lang="python">
from matplotlib import pyplot as plt
with open('patches.txt') as f:
patches = [int(patch) for patch in f.readlines()]
plt.hist(patches, 2000)
plt.xlim(0,50)
plt.show()
</source>

At this point, we start the calibration to get best parameters of patch shape
(for this tutorial, this step can be skipped and the suggested parameters are used).

<source lang="bash"
style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.calib development_start=urban_1992 development_end=urban_2011 subregions=calib_county patch_sizes=patches.txt calibration_results=calib.csv patch_threshold=1800 repeat=5 compactness_mean=0.1,0.3,0.5,0.7,0.9 compactness_range=0.05 discount_factor=0.1,0.3,0.5,0.7,0.9 predictors=road_dens_perc,forest_smooth_perc,dist_to_protected_km demand=demand.csv devpot_params=potential.csv num_neighbors=4 seed_search=2 development_pressure=devpressure_0_5 development_pressure_approach=gravity n_dev_neighbourhood=30 gamma=0.5 scaling_factor=0.1
</source>

== FUTURES simulation ==
We will switch back to our previous region:
<source lang="bash">
g.region raster=landuse_2011 -p
</source>

Now we have all the inputs necessary for running {{AddonCmd|r.futures.pga}}:

The entire command is here:
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.pga subregions=counties developed=urban_2011 predictors=slope,forest_smooth_perc,dist_interchanges_km,travel_time_cities devpot_params=potential.csv development_pressure=devpressure_1 n_dev_neighbourhood=10 development_pressure_approach=gravity gamma=1 scaling_factor=1 demand=demand.csv discount_factor=0.3 compactness_mean=0.2 compactness_range=0.1 patch_sizes=patches.txt num_neighbors=4 seed_search=2 random_seed=1 output=final output_series=final
</source>

=== Quick description ===
The command parameters and their values:
* raster map of counties with their categories
<code>
... subregions=counties ...
</code>

* raster of developed (1), undeveloped (0) and NULLs for undevelopable areas
<code>
... developed=urban_2011 ...
</code>

* predictors selected with {{AddonCmd|r.futures.potential}} and their coefficients in a <tt>potential.csv</tt> file. The order of predictors must match the order in the file and the categories of the counties must match raster <tt>counties</tt>.
<code>
... predictors=slope,forest_smooth_perc,dist_interchanges_km,travel_time_cities devpot_params=potential.csv ...
</code>

* initial development pressure computed by {{AddonCmd|r.futures.devpressure}}, it's important to set here the same parameters
<code>
... development_pressure=devpressure_1 n_dev_neighbourhood=10 development_pressure_approach=gravity gamma=1 scaling_factor=1 ...
</code>

* per capita land demand computed by {{AddonCmd|r.futures.demand}}, the categories of the counties must match raster <tt>counties</tt>.
<code>
... demand=demand.csv ...
</code>

* patch parameters from the calibration step
<code>
... discount_factor=0.3 compactness_mean=0.4 compactness_range=0.08 patch_sizes=patches.txt ...
</code>

* recommended parameters for patch growing algorithm
<code>
... num_neighbors=4 seed_search=2 ...
</code>

* set random seed for repeatable results or set flag <tt>-s</tt> to generate seed automatically
<code>
... random_seed=1 ...
</code>

* specify final output map and optionally basename for intermediate raster maps
<code>
output=final output_series=final
</code>

== Scenarios ==
Scenarios involving policies that encourage infill versus sprawl can be explored using the <tt>incentive_power</tt> parameter of {{AddonCmd|r.futures.pga}},
which uses a power function to transform the evenness of the probability gradient in POTENTIAL. You can change the power to a number between 0.25 and 4 to test urban sprawl/infill scenarios.
Higher power leads to infill behavior, lower power to urban sprawl.

== Postprocessing ==

Follow a [[Creating_animation_from_FUTURES_output_in_GRASS_GIS| tutorial how to make an animation from the results]].

= GRASS GIS Python API =

[[Category: Tutorial]]
[[Category: FUTURES]]
[[Category: Urban]]

Workshop on urban growth modeling with FUTURES

2016-03-21T20:02:22Z

⚠️Dbvanber: /* Installation */

{{ToModify}}
= Workshop introduction =
r.futures.* is an implementation of FUTure Urban-Regional Environment Simulation (FUTURES)[1] which is a model for multilevel simulations of emerging urban-rural landscape structure. FUTURES produces regional projections of landscape patterns using coupled submodels that integrate nonstationary drivers of land change: per capita demand (DEMAND submodel), site suitability (POTENTIAL submodel), and the spatial structure of conversion events (PGA submodel).

[1] Meentemeyer, R. K., Tang, W., Dorning, M. A., Vogler, J. B., Cunniffe, N. J., & Shoemaker, D. A. (2013). [http://www.tandfonline.com/doi/abs/10.1080/00045608.2012.707591 FUTURES: multilevel simulations of emerging urban-rural landscape structure using a stochastic patch-growing algorithm.] Annals of the Association of American Geographers, 103(4), 785-807

== Software ==
Required software includes:
* GRASS GIS 7
* addons
** {{AddonCmd|r.futures.pga}}
** {{AddonCmd|r.futures.potential}}
** {{AddonCmd|r.futures.potsurface}}
** {{AddonCmd|r.futures.demand}}
** {{AddonCmd|r.futures.devpressure}}
** {{AddonCmd|r.sample.category}}
* R (≥ 3.0.2) - needed for {{AddonCmd|r.futures.potential}} with packages:
**MuMIn, lme4, optparse, rgrass7
* SciPy - useful for {{AddonCmd|r.futures.demand}}

=== Installation ===
There are a number of software needed to run FUTURES that will need to be download and installed.

We use the R statistical software for our calculation of site suitability (i.e. development potential) in FUTURES. R is a free software environment for statistical computing and graphics. If you don't have R, or you have older an version, please download and install the software from [http://archive.linux.duke.edu/cran/ install R] and be sure to additionally add these required packages:
<pre>
install.packages(c("MuMIn", "lme4", "optparse", "rgrass7"))
</pre>

==== MS Windows ====
We will be using GRASS GIS 7.0.3 that can be found here [https://trac.osgeo.org/osgeo4w/ OSGeo4W] package manager.
Please install the latest stable GRASS GIS 7 version and the SciPy Python package using the ''Advanced install'' option.
A guide with step by step screen shot instructions is available [https://docs.google.com/presentation/d/1yEGpriBne7RvjB35HI6GecNwO1P1y2nRGqDThqoNnCE/edit?usp=sharing here].

In order for GRASS to be able to find R executables, GRASS must be on the PATH variable. Follow this [solution] to make R accessible from GRASS permanently.
A simple but temporary solution is to open GRASS GIS and paste this in the black terminal:
<pre>
set PATH=%PATH%;C:\Program Files\R\R-3.0.2\bin
</pre>
This has to be repeated after restarting GRASS session.

==== Ubuntu Linux ====
Install GRASS GIS from packages:
<pre>
sudo add-apt-repository ppa:ubuntugis/ubuntugis-unstable
sudo apt-get update
sudo apt-get install grass
</pre>

== Workshop data ==
Download [http://fatra.cnr.ncsu.edu/futures/futures_ncspm_Asheville.zip sample dataset] containing GRASS GIS location with:
* digital elevation model ([http://nationalmap.gov/elevation.html NED])
* [http://www.mrlc.gov/ NLCD] 2001, 2011
* NLCD 1992/2001 Retrofit Land Cover Change Product
* transportation network ([http://www.census.gov/geo/maps-data/data/tiger-line.html TIGER])
* county boundaries ([http://www.census.gov/geo/maps-data/data/tiger-line.html TIGER])
* protected areas ([http://www.conservationgateway.org/ConservationByGeography/NorthAmerica/UnitedStates/edc/reportsdata/terrestrial/secured/Pages/default.aspx Secured Lands])
* cities as points (USGS)

In addition, download [http://fatra.cnr.ncsu.edu/futures/futures_Asheville_files.zip population information as text files]:
* county population past estimates and future projections ([https://www.osbm.nc.gov/demog/county-projections NC OSBM]) per county (nonspatial)

= GRASS GIS introduction =
* Overview of GRASS GIS project: [https://grass.osgeo.org grass.osgeo.org]
* Overview of [https://grass.osgeo.org/grass71/manuals/grass_database.html GRASS database].
** ''GRASS database'': directory with Locations (projects)
** ''Location'': directory with Mapsets, defined by projection (spatial reference system)
** ''Mapset'': collection of maps
* Download the [http://fatra.cnr.ncsu.edu/futures/futures_ncspm_Asheville.zip workshop location]. Create (unless you already have it) a directory named <tt>grassdata</tt> (GRASS database) in your home folder (or Documents), unzip the downloaded data into this directory. You should have now Location <tt>futures_ncspm</tt> in <tt>grassdata</tt>.
* Launch GRASS and display raster, vector data, explore navigation, querying, adding legend, showing metadata
<center><gallery perrow=3 widths=500 heights=250>Image:GRASS FUTURES startup.png|GRASS GIS 7.0.3 startup dialog with downloaded Location and Mapsets for FUTURES workshop
Image:GRASS FUTURES wxGUI display.png|Layer Manager and Map Display overview. Annotations show how to add raster layer, query, add legend.
Image:wxGUI_metadata_rinfo.png|Show raster map metadata by right click on layer</gallery></center>

* GRASS GIS has over [https://grass.osgeo.org/grass70/manuals/full_index.html 500 different modules] in the core distribution and over [https://grass.osgeo.org/grass70/manuals/addons/ 230 addon modules]
<center>
{| class="wikitable"
|-
! Prefix !! Function !! Example
|-
| r.* || raster processing || ''{{cmd|r.mapcalc}}'': map algebra
|-
| v.* || vector processing || ''{{cmd|v.clean}}'': topological cleaning
|-
| i.* || imagery processing || ''{{cmd|i.segment}}'': object recognition
|-
| db.* || database management || ''{{cmd|db.select}}'': select values from table
|-
| r3.* || 3D raster processing || ''{{cmd|r3.stats}}'': 3D raster statistics
|-
| t.* || temporal data processing || ''{{cmd|t.rast.aggregate}}'': temporal aggregation
|-
| g.* || general data management || ''{{cmd|g.rename}}'': renames map
|-
| d.* || display ||''{{cmd|d.rast}}'': display raster map
|}</center>
* GRASS modules have GUI and command line interface. In this workshop we use commands to describe the workflow, but we can use both GUI and command line depending on personal preference. Look how {{cmd|wxGUI.modules|version=71|desc=GUI and command line interface}} represent the same tool. ''Task:'' compute aspect (orientation) from provided digital elevation model using module {{cmd|r.slope.aspect}} using both module dialog and command line.
* How to find modules? Modules are organized by their functionality in wxGUI menu, or we can search for them in Search modules tab. If we already know which module to use, we can just type it in the wxGUI command console. <center><gallery perrow=3 widths=380 heights=190>Image:wxGUI_menu_rinfo.png|Modules can be found in wxGUI menu
Image:wxGUI_module_search.png|You can search modules by name, description or keywords in ''Search modules'' tab
Image:wxGUI_console_completion.png|By typing prefix r. we make a list of modules starting with that prefix to show up.</gallery></center>


* {{cmd|g.region|desc=Computational region}} - an important raster concept
** defined by region extent and raster resolution
** applies to all raster operations
** persists between GRASS session, can be different for different mapsets
** advantages: keeps your results consistent, avoid clipping, for computationally demanding tasks set region to smaller extent, check your result is good and then set the computational region to the entire study area and rerun analysis
** run <code>g.region -p</code> or in menu ''Settings'' - ''Region'' - ''Display region'' to see current region settings
[[File:WxGUI set region.png|700px|thumb|center|Simple ways to set computational region from GUI. On the left, set region to match raster map. On the right, select the highlighted option and then set region by drawing rectangle.]]

* GRASS 3D view

= Modeling with FUTURES =
== Initial steps and data preparation ==
First we will set computational region of our analyses to an extent covering our study area and so that the cells are aligned with one of our landuse rasters:
<source lang="bash">g.region raster=landuse_2011 -p</source>

We will derive urbanized areas from NLCD dataset for year 1992, 2001 and 2011
by extracting categories category 21 - 24 into a new binary map where developed is 1,
undeveloped 0 and NULL (no data) is area unsuitable for development (water, wetlands, protected areas).
First we will convert protected areas from vector to raster. We set
NULLs to zeros (for simpler raster algebra expression in the next step) using {{cmd|r.null}}:

<source lang="bash">
v.to.rast input=protected_areas output=protected_areas use=val
r.null map=protected_areas null=0
</source>

And then create rasters of developed/undeveloped areas using raster algebra:

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.mapcalc "urban_1992 = if(landuse_1992 >= 21 && landuse_1992 <= 24, 1, if(landuse_1992 == 11 || landuse_1992 >= 90 || protected_areas, null(), 0))"
r.mapcalc "urban_2001 = if(landuse_2001 >= 21 && landuse_2001 <= 24, 1, if(landuse_2001 == 11 || landuse_2001 >= 90 || protected_areas, null(), 0))"
r.mapcalc "urban_2011 = if(landuse_2011 >= 21 && landuse_2011 <= 24, 1, if(landuse_2011 == 11 || landuse_2011 >= 90 || protected_areas, null(), 0))"
</source>

We will convert vector counties to raster with the values of the FIPS attribute which links to population file:

<source lang="bash">
v.to.rast input=counties type=area use=attr attribute_column=FIPS output=counties
</source>

Before further steps, we will set our working directory so that the input population files and text files
we are going to create are saved in one directory and easily accessible.
You can do that from menu ''Settings'' → ''GRASS working environment'' → ''Change working directory''.
Select (or create) a directory and move there the downloaded files <tt>population_projection.csv</tt> and <tt>population_trend.csv</tt>.

== Potential submodel ==
Module {{AddonCmd|r.futures.potential}} implements POTENTIAL submodel as a part of FUTURES land change model. POTENTIAL is implemented using a set of coefficients that relate a selection of site suitability factors to the probability of a place becoming developed. This is implemented using the parameter table in combination with maps of those site suitability factors (mapped predictors). The coefficients are obtained by conducting multilevel logistic regression in R with package lme4 where the coefficients may vary by county. The best model is selected automatically using dredge function from package [https://cran.r-project.org/web/packages/MuMIn/index.html MuMIn].

First, we will derive couple of predictors.
=== Predictors ===
==== Slope ====
We will derive slope in degrees from digital elevation model using {{cmd|r.slope.aspect}} module:
<source lang="bash">r.slope.aspect elevation=elevation_30m slope=slope</source>

==== Distance from lakes/rivers ====
First we will extract [http://www.mrlc.gov/nlcd11_leg.php category ''Open Water''] from 2011 NLCD dataset:
<source lang="bash">
r.mapcalc "water = if(landuse_2011 == 11, 1, null())"
</source>

Then we compute the distance to water with module {{cmd|r.grow.distance}} and set color table to shades of blue:
<source lang="bash">
r.grow.distance input=water distance=dist_to_water
r.colors -n map=dist_to_water color=blues
</source>

==== Distance from protected areas ====
We will use raster protected of protected areas we already created, but we will set NULL values to zero.
We compute the distance to protected areas with module {{cmd|r.grow.distance}} and set color table from green to red:
<source lang="bash">
r.null map=protected_areas setnull=0
r.grow.distance input=protected_areas distance=dist_to_protected
r.colors map=dist_to_protected color=gyr
</source>

==== Forests ====
We will smooth the transition between forest and other land use, see NLCD [http://www.mrlc.gov/nlcd11_leg.php category ''Open Water'']:
<source lang="bash">
r.mapcalc "forest = if(landuse_2011 >= 41 && landuse_2011 <= 43, 1, 0)"
r.neighbors -c input=forest output=forest_smooth size=15 method=average
r.colors map=forest_smooth color=ndvi
</source>

==== Travel time to cities ====
Here we will compute travel time to cities (with population > 5000)
as cumulative cost distance where cost is defined as travel time on roads.
First we specify the speed on different types of roads.
We copy the roads raster into our mapset so that we can change it
by adding a new attribute field <tt>speed</tt>. Then we assign speed values (km/h) based on the type of road:

<source lang="bash">
g.copy vector=roads,myroads
v.db.addcolumn map=myroads columns="speed double precision"
v.db.update map=myroads column=speed value=50 where="MTFCC = 'S1400'"
v.db.update map=myroads column=speed value=100 where="MTFCC IN ('S1100', 'S1200')"
</source>

Now we rasterize the selected road types using the speed values from the attribute table as raster values.

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
v.to.rast input=myroads type=line where="MTFCC IN ('S1100', 'S1200', 'S1400')" output=roads_speed use=attr attribute_column=speed
</source>

We set the rest of the area to low speed and recompute the speed as time to travel through a 30m cell in minutes:

<source lang="bash">
r.null map=roads_speed null=5
r.mapcalc "roads_travel_time = 1.8 / roads_speed"
</source>

Finally we compute the travel time to larger cities using {{cmd|r.cost}}:

<source lang="bash">
r.cost input=roads_travel_time output=travel_time_cities start_points=cities
r.colors map=travel_time_cities color=byr
</source>

==== Road density ====
We will rasterize roads and use moving window analysis ({{cmd|r.neighbors}}) to compute road density:

<source lang="bash">
v.to.rast input=roads output=roads use=val type=line
r.null map=roads null=0
r.neighbors -c input=roads output=road_dens size=25 method=average
</source>

==== Distance to interchanges ====

We will consider TIGER roads of type <tt>Ramp</tt> as interchanges, rasterize them and compute euclidean distance to them:

<source lang="bash">
v.to.rast input=roads type=line where="MTFCC = 'S1630'" output=interchanges use=val
r.grow.distance -m input=interchanges distance=dist_interchanges
</source>

=== Development pressure ===

We compute development pressure with {{AddonCmd|r.futures.devpressure}}. Development pressure is a predictor based on number of neighboring developed cells within search distance, weighted by distance. The development pressure variable plays a special role in the model, allowing for a feedback between predicted change and change in subsequent steps.

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.devpressure -n input=urban_2011 output=devpressure_2 method=gravity size=7 gamma=2 scaling_factor=10
r.futures.devpressure -n input=urban_2011 output=devpressure_1 method=gravity size=10 gamma=1 scaling_factor=1
r.futures.devpressure -n input=urban_2011 output=devpressure_0_5 method=gravity size=30 gamma=0.5 scaling_factor=0.1
</source>

When gamma increases, development influence decreases more rapidly with distance.
Size is half the size of the moving window. When gamma is low, local development influences more distant places.
We will derive 3 layers with different gamma and size parameters for the potential statistical model.

=== Rescaling variables ===

First we will look at the ranges of our predictor variables by running a short Python code snippet in Python shell:

<source lang="python" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
for name in ['slope', 'dist_to_water', 'dist_to_protected', 'forest_smooth', 'travel_time_cities', 'road_dens', 'dist_interchanges', 'devpressure_0_5', 'devpressure_1']:
minmax = grass.raster_info(name)
print name, minmax['min'], minmax['max']
</source>

We will rescale some of our input variables:

<source lang="bash">
r.mapcalc "dist_to_water_km = dist_to_water / 1000"
r.mapcalc "dist_to_protected_km = dist_to_protected / 1000"
r.mapcalc "dist_interchanges_km = dist_interchanges / 1000"
r.mapcalc "road_dens_perc = road_dens * 100"
r.mapcalc "forest_smooth_perc = forest_smooth * 100"
</source>

=== Sampling ===
To sample only in the analyzed counties, we will clip development layer:

<source lang="bash">
r.mapcalc "urban_change_01_11 = if(urban_2011 == 1, if(urban_2001 == 0, 1, null()), 0)"
r.mapcalc "urban_change_clip = if(counties, urban_change_01_11)"
</source>

To estimate the number of sampling points, we can use {{cmd|r.report}} to report number of developed/undeveloped cells and their ratio.

<source lang="bash">
r.report map=urban_change_clip units=h,c,p
</source>

We will sample the predictors and the response variable with 5000 random points in undeveloped areas and 1000 points in developed area:

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.sample.category input=urban_change_clip output=sampling sampled=counties,devpressure_0_5,devpressure_1,devpressure_2,slope,road_dens_perc,forest_smooth_perc,dist_to_water_km,dist_to_protected_km,dist_interchanges_km,travel_time_cities npoints=5000,1000
</source>

The attribute table can be exported as CSV file (not necessary step):

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
v.db.select map=sampling columns=urban_change_clip,counties,devpressure_0_5,devpressure_1,slope,road_dens_perc,forest_smooth_perc,dist_to_water_km,dist_to_protected_km,dist_interchanges_km,travel_time_cities separator=comma file=samples.csv
</source>

=== Development potential ===
Now we find best model for predicting urbanization using {{AddonCmd|r.futures.potential}} which wraps an R script.

We can run R [http://www.inside-r.org/packages/cran/MuMIn/docs/dredge dredge] function to find "best" model. We can specify minimum and maximum number of predictors the final model should use.
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.potential -d input=sampling output=potential.csv columns=devpressure_1,slope,road_dens_perc,forest_smooth_perc,dist_to_water_km,dist_to_protected_km,dist_interchanges_km,travel_time_cities developed_column=urban_change_clip subregions_column=counties min_variables=4
</source>

Also, we can play with different combinations of predictors, for example:

<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.potential input=sampling output=potential.csv columns=devpressure_2,road_dens_perc,slope,dist_interchanges_km,dist_to_water_km developed_column=urban_change_clip subregions_column=counties --o
r.futures.potential input=sampling output=potential.csv columns=devpressure_1,road_dens_perc,slope,dist_interchanges_km,dist_to_water_km developed_column=urban_change_clip subregions_column=counties --o
...
</source>

You can then open the output file <tt>potential.csv</tt>, which is a CSV file with tabs as separators.

For this tutorial, the final potential is created with:
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.potential input=sampling output=potential.csv columns=devpressure_2,road_dens_perc,slope,dist_interchanges_km,dist_to_water_km developed_column=urban_change_clip subregions_column=counties --o
</source>

We can now visualize the suitability surface using module {{AddonCmd|r.futures.potsurface}}. It creates initial development potential (suitability) raster from predictors and model coefficients and serves only for evaluating development potential model. The values of the resulting raster range from 0 to 1.

<source lang="bash">
r.futures.potsurface input=potential.csv subregions=counties output=suitability
r.colors map=suitability color=byr
</source>

== Demand submodel ==
First we will mask out roads so that they don't influence into per capita land demand relation.
<source lang="bash">
v.to.rast input=roads type=line output=roads_mask use=val
r.mask roads_mask -i
</source>

We will use {{AddonCmd|r.futures.demand}} which derives the population vs. development relation. The relation can be linear/logarithmic/logarithmic2/exponential/exponential approach.
Look for examples of the different relations in the manual.

* linear: y = A + Bx
* logarithmic: y = A + Bln(x)
* logarithmic2: y = A + B * ln(x - C)        (requires SciPy)
* exponential: y = Ae^(BX)
* exp_approach: y = (1 - e^(-A(x - B))) + C        (requires SciPy)

The format of the input population CSV files is described in the manual. It is important to have synchronized categories of subregions and the column headers of the CSV files (in our case FIPS number). How to simply generate the list of years (for which demand is computed) is described in {{AddonCmd|r.futures.demand}} manual, for example run this in Python console:

<source lang="python">
','.join([str(i) for i in range(2011, 2036)])
</source>

Then we can create the DEMAND file:
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.demand development=urban_1992,urban_2001,urban_2011 subregions=counties observed_population=population_trend.csv projected_population=population_projection.csv simulation_times=2011,2012,2013,2014,2015,2016,2017,2018,2019,2020,2021,2022,2023,2024,2025,2026,2027,2028,2029,2030,2031,2032,2033,2034,2035 plot=plot_demand.pdf demand=demand.csv separator=comma
</source>

In your current working directory, you should find files <tt>plot_demand.png</tt> and <tt>demand.csv</tt>.

If you have SciPy installed, you can experiment with other methods for fitting the functions:
<source lang="bash">
r.futures.demand ... method=logarithmic2
r.futures.demand ... method=exp_approach
</source>
If necessary, you can create a set of demand files produced by fitting each method separately and
then pick for each county the method which seems best and manually create a new demand file.

When you are finished, remove the mask as it is not needed for the next steps.
<source lang="bash">
r.mask -r
</source>

== Patch calibration ==
Patch calibration can be a very time consuming computation.
Therefore we select only one county (Buncombe):

<source lang="bash">
v.to.rast input=counties type=area where="FIPS == 37021" use=attr attribute_column=FIPS output=calib_county
g.region raster=calib_county zoom=calib_county
</source>
to derive patches of new development by comparing historical and latest development.
We can keep only patches with minimum size 2 cells (1800 = 2 x 30 x 30 m).

<source lang="bash">
r.futures.calib development_start=urban_1992 development_end=urban_2011 subregions=counties patch_sizes=patches.txt patch_threshold=1800 -l
</source>
We obtained a file <tt>patches.txt</tt> (used later in the PGA) - a patch size distribution file - containing sizes of all found patches.

We can look at the distribution of the patch sizes:

<source lang="python">
from matplotlib import pyplot as plt
with open('patches.txt') as f:
patches = [int(patch) for patch in f.readlines()]
plt.hist(patches, 2000)
plt.xlim(0,50)
plt.show()
</source>

At this point, we start the calibration to get best parameters of patch shape
(for this tutorial, this step can be skipped and the suggested parameters are used).

<source lang="bash"
style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.calib development_start=urban_1992 development_end=urban_2011 subregions=calib_county patch_sizes=patches.txt calibration_results=calib.csv patch_threshold=1800 repeat=5 compactness_mean=0.1,0.3,0.5,0.7,0.9 compactness_range=0.05 discount_factor=0.1,0.3,0.5,0.7,0.9 predictors=road_dens_perc,forest_smooth_perc,dist_to_protected_km demand=demand.csv devpot_params=potential.csv num_neighbors=4 seed_search=2 development_pressure=devpressure_0_5 development_pressure_approach=gravity n_dev_neighbourhood=30 gamma=0.5 scaling_factor=0.1
</source>

== FUTURES simulation ==
We will switch back to our previous region:
<source lang="bash">
g.region raster=landuse_2011 -p
</source>

Now we have all the inputs necessary for running {{AddonCmd|r.futures.pga}}:

The entire command is here:
<source lang="bash" style="white-space: pre-wrap;
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;">
r.futures.pga subregions=counties developed=urban_2011 predictors=slope,forest_smooth_perc,dist_interchanges_km,travel_time_cities devpot_params=potential.csv development_pressure=devpressure_1 n_dev_neighbourhood=10 development_pressure_approach=gravity gamma=1 scaling_factor=1 demand=demand.csv discount_factor=0.3 compactness_mean=0.2 compactness_range=0.1 patch_sizes=patches.txt num_neighbors=4 seed_search=2 random_seed=1 output=final output_series=final
</source>

=== Quick description ===
The command parameters and their values:
* raster map of counties with their categories
<code>
... subregions=counties ...
</code>

* raster of developed (1), undeveloped (0) and NULLs for undevelopable areas
<code>
... developed=urban_2011 ...
</code>

* predictors selected with {{AddonCmd|r.futures.potential}} and their coefficients in a <tt>potential.csv</tt> file. The order of predictors must match the order in the file and the categories of the counties must match raster <tt>counties</tt>.
<code>
... predictors=slope,forest_smooth_perc,dist_interchanges_km,travel_time_cities devpot_params=potential.csv ...
</code>

* initial development pressure computed by {{AddonCmd|r.futures.devpressure}}, it's important to set here the same parameters
<code>
... development_pressure=devpressure_1 n_dev_neighbourhood=10 development_pressure_approach=gravity gamma=1 scaling_factor=1 ...
</code>

* per capita land demand computed by {{AddonCmd|r.futures.demand}}, the categories of the counties must match raster <tt>counties</tt>.
<code>
... demand=demand.csv ...
</code>

* patch parameters from the calibration step
<code>
... discount_factor=0.3 compactness_mean=0.4 compactness_range=0.08 patch_sizes=patches.txt ...
</code>

* recommended parameters for patch growing algorithm
<code>
... num_neighbors=4 seed_search=2 ...
</code>

* set random seed for repeatable results or set flag <tt>-s</tt> to generate seed automatically
<code>
... random_seed=1 ...
</code>

* specify final output map and optionally basename for intermediate raster maps
<code>
output=final output_series=final
</code>

== Scenarios ==
Scenarios involving policies that encourage infill versus sprawl can be explored using the <tt>incentive_power</tt> parameter of {{AddonCmd|r.futures.pga}},
which uses a power function to transform the evenness of the probability gradient in POTENTIAL. You can change the power to a number between 0.25 and 4 to test urban sprawl/infill scenarios.
Higher power leads to infill behavior, lower power to urban sprawl.

== Postprocessing ==

Follow a [[Creating_animation_from_FUTURES_output_in_GRASS_GIS| tutorial how to make an animation from the results]].

= GRASS GIS Python API =

[[Category: Tutorial]]
[[Category: FUTURES]]
[[Category: Urban]]