3. Model calibration
3.1. Set constants and verify
3.2. Coarse calibration
3.3. Fine calibration
3.4. Final calibration
3.5. Derive forecasting coefficients

Five coefficient values affect modeled urban growth of a study area. Known historical data is compared to simulated land cover in an effort to find the coefficient values that best model urban and related land cover change through time. These are measured using several Pearson r2 statistics, comparing measurements such as total number of urban pixels, edges, clusters and a spatial match comparison. For a more complete explanation see output statistic files.

Running SLEUTH in calibrate mode will perform brute force monte carlo runs through the historical data using every combination of the model coefficient values indicated. The CALIBRATION_*_START coefficient values (where "*" represents a coefficient type) will initialize the first simulation. A coefficient will then be increased by its _STEP value, and another simulation performed. This will continue until the coefficient _STOP value has been reached or exceeded. The incrementation will be repeated for all possible permutations of given ranges.

Calibration requires many (often thousands) of single simulations of land cover change. Because of this, output requirements can greatly add to the total application time. Many options are available for log and image file output during calibration. However, the fewer output files written, the more efficiently the code will run. It is important to understand the scenario file options to optimize it for your applications. To prevent overwriting, it is recommended to create, and in the scenario file point to, a unique output directory for each phase of model calibration and prediction.

Since the urban growth module of SLEUTH is its most basic component, the following instructions on how to calibrate the model will use urban growth only. The steps of calibration are the same when the Deltatron module is incorporated, but the output file control_stats.log will vary slightly. (For more information see: SLEUTH functions.

3.1. Set constants and verify

3.1.1. Create a scenario file for your data
The scenario.demo50_calibrate file is an example of how a file could be set up for first phase, or coarse, calibration. In order to make the code run more efficiently and, cut down on i/o requirements, all of the output file flags are set to "NO" except for the LOGGING(YES/NO) flag. If statistics for a few specific calibration runs are desired, these can be run independently of the calibration step in calibration or test mode with the desired flags set to "YES". (Test mode will produce annual images of land cover change, calibration mode will not.)

The easiest way to create a scenario file for your data set is to edit the scenario.demo50_calibrate file included with SLEUTH3.0beta. A scenario file must begin with the keyword "scenario.". Customizing this file will require, at the very least, editing the input and output path names and input file name flags to represent your data. Be sure to become familiar with the different functions and output controlled by the scenario file. This can be done by reading the comments contained in the provided scenario file. In addition, intelligently altering the variables and flags contained in the file, and examining the results, is recommended in order to become familiar with how SLEUTH functionality and output is controlled.

1. Create a copy of scenario.demo50_calibrate using a unique name
   Filename example: scenario.mydata_coarse
2. Edit INPUT_DIR flag to point to your input data directory
3. Edit OUTPUT_DIR flag to point to a desired output directory
4. Edit input image flags to represent your file names

3.1.2. Run a test on your data

1. Execute a test run
   prompt% ../grow test scenario.mydata_coarse
2. Monitor progress
   If the ECHO flag is set to "YES" growth years should be printed to the screen as the model executes.
3. The NUMBER_OF_ITERATIONS flag may be set to one (1)
4. Examine output
   SLEUTH output should make sense relative to it's input. For example, the output images will not necessarily look realistic because the coefficients used were not calibrated for the data set. However, growth should be logical - not occurring in excluded areas but spreading from existing urban edges, etc. The LOG_0 file will record what was contained in the scenario file used for the application, what files were read in, what their values were, and some basic calculations on the data.
5. Repeat steps 1-3 as many times as desired, changing the scenario file flags between runs
   • if more growth is desired increase the coefficient *_START values
   • test will always use only the *_START values
   • the *_START values must be less than the *_STOP values
     

3.2. Coarse calibration

3.2.1. Modify scenario file for coarse calibration

1. Create a copy of, or modify the scenario file used for testing in the previous step
   Filename example: scenario.mydata_coarse
   
2. Check MONTE_CARLO_ITERATIONS flag setting
   This should be set to a low number (~4-5)
   
3. Set initial coefficient settings for calibration
   Coefficient value ranges: {0-100}.
   For coarse calibration it is recommended to set all coefficients to {0-100,25} where the first number (0) is the _START value, the second number (100) is the _STOP value, and the third (25) is the _STEP
   • The downloaded scenario.demo50_calibrate file calibration coefficient settings are set for a coarse calibration and may be used as an example.

3.2.2. Run a coarse calibration on your data

1. Execute a calibration run
   prompt% ../grow calibrate scenario.mydata_coarse
2. Monitor progress
   If ECHO flag is set to "YES" growth years should be printed to the screen as the model executes.
3. Time passes...
4. Examine output
   The primary file used for coefficient range selection is the control_stats.log file. For more information on how ranges are selected see selecting ranges.
   

3.3. Fine calibration

3.3.1. Modify scenario file for fine calibration

1. Create a copy of, or modify, the scenario file used in the previous step
   Filename example: scenario.mydata_fine
   
2. Edit INPUT_DIR flag to point to the directory of your 1/2 resolution images
3. Edit OUTPUT_DIR flag to point to a desired output directory
4. Edit input image flags to represent your file names
5. Check MONTE_CARLO_ITERATIONS flag setting
   This should be set to a low number (~7-8)
   
6. Set coefficient settings for fine calibration
   These values should define a narrowed coefficient range derived from the coarse phase of calibration.

3.3.2. Run a fine calibration on your data

1. Execute a calibration run
   prompt% ../grow calibrate scenario.mydata_fine
2. Monitor progress
   If ECHO flag is set to "YES" growth years should be printed to the screen as the model executes.
3. More time passes...
4. Examine output
   The primary file used for coefficient range selection is the control_stats.log file. For more information on how ranges are selected see selecting coefficients.

3.4. Final calibration

3.4.1. Modify scenario file for final calibration

1. Create a copy of or modify the scenario file used in the previous step
   Filename example: scenario.mydata_final
   
2. Edit INPUT_DIR flag to point to the directory of your full resolution images
3. Edit OUTPUT_DIR flag to point to a desired output directory
4. Edit input image flags to represent your file names
5. Check MONTE_CARLO_ITERATIONS flag setting
   This should be set to ~8-10
   
6. Set coefficient settings for final calibration
   These values should define a narrowed coefficient range derived from the fine phase of calibration.

3.4.2. Run a final calibration on your data

1. Execute a calibration run
   prompt% ../grow calibrate scenario.mydata_final
2. Monitor progress
   If ECHO flag is set to "YES" growth years should be printed to the screen as the model executes.
3. A lot more time passes...
4. Examine output
   The primary file used for coefficient range selection is the control_stats.log file. For more information on how ranges are selected see selecting coefficients.

3.5. Derive forecasting coefficients
The calibration process produces initializing coefficient values that best simulate historical growth for a region. However, due to SLEUTH's self-modification qualities, coefficient values at the START_DATE of a run may be altered by the STOP_DATE. For forecast initialization, the STOP_DATE values from the best calibrated coefficients are desired. Using the best coefficients derived from calibration and running SLEUTH for the historical time period will produce a single set of STOP_DATE coefficients to initialize forecasting. However, due to the random variability of the model, averaged coefficient results of many monte carlo iterations will produce a more robust forecasting coefficient set.

3.4.1. Modify scenario file

1. Create a copy of or modify the scenario file used in the previous step
   Filename example: scenario.mydata
   
2. The INPUT_DIR flag should point to the directory of your full resolution images
3. The OUTPUT_DIR flag should point to a desired output directory
4. The input image flags should represent your full size file names
5. Check MONTE_CARLO_ITERATIONS flag setting
   This should be set very high (e.g.; 100 or greater))
   
6. Set initializing coefficient settings
   These values should define a single set of best coefficient values derived from the final phase of calibration. The _START and _STOP values should be equal, and the _STEP value should be one (1).
7. Set the WRITE_AVG_FILE(YES/NO) flag to "YES"
   (The coeff.log file may also be used to find the STOP_DATE coefficient values.)

3.4.2. Find forecasting coefficients

1. Execute a calibration run
   prompt% ../grow calibrate scenario.mydata
2. Monitor progress
   If ECHO flag is set to "YES" growth years should be printed to the screen as the model executes.
3. Examine output
   The file used to store coefficient values is the avg.log file. For more information on how to use this file see selecting coefficients.