PECAS - for Spatial Economic Modelling
Model Development
Option Size Calibration Script
System Documentation Technical Note
WORKING DRAFT
Template Materials Providing Basic Descriptive Components
HBA Specto Incorporated
Calgary, Alberta
April 2009
PECAS Model Development: Trip Length Calibration Script
System Documentation Technical Note
Working Draft
ADM2
04.01.2009/KJS
File: PECAS Trip Length Calibration.01.doc
Page 2
Table of Contents
Section
Page
1. Introduction ………………………………………………….………………….................. 3
2. Overview …………………………………………………………….……………………… 3
3. Input Files ..…………................................................................................................. 4
4. Other Script Parameters …………………………………………………………………. 6
5. Program Mechanics ………………………………………………………………………. 8
6. Operating Notes ………………..………….................................................................. 8
PECAS Model Development: Trip Length Calibration Script
System Documentation Technical Note
Working Draft
ADM2
04.01.2009/KJS
File: PECAS Trip Length Calibration.01.doc
Page 3
1. Introduction
The Option Size Calibration script (OptionSizeCalib.py, commonly called OSC in this
document) is a Python script that repeatedly runs the AA module of PECAS to match
the production and consumption of commodities to specified target values. It does this
by adjusting the option sizes of the technology options described in TechnologyOptionsI.
2. Overview
To run, a standard installation of Python is needed. The script has been run on a
system with Python 2.5, but it should run on versions 2.3 or greater (the csv module
was added in 2.3).
In addition to the other files generally needed to run PECAS, one file needs to be
created for OSC; it is consistent with the other PECAS files (.CSV files with headers in
the first row, etc.) and is called OptionSizeCalibI.csv. In addition, the input
TechnologyOptionsI will need some reformatting to permit OSC to determine which
technology options effect which commodities.
OSC works by adjusting the technology option sizes in the technology options file to
match production and consumption targets. These targets are determined for each
activity at the geographic level of the entire model region; for instance, the total amount
of Retail Workers labour produced by households earning over $200K, or the total
amount of office space consumed by Business Services. Specifically, OSC adjusts
technology options pertaining to increased production or consumption of commodities
versus a baseline or a zero production / zero consumption option.
3. Input File layout
OptionSizeCalibI.csv is the target specification file, and should be laid out as follows:
Activity, Commodity, MorU, Target
PECAS Model Development: Trip Length Calibration Script
System Documentation Technical Note
Working Draft
ADM2
04.01.2009/KJS
File: PECAS Trip Length Calibration.01.doc
Page 4
Restaurants, White Collar Workers, U, -7239
Restaurants, Blue Collar Workers, U, -13
Restaurants, Service Workers, U, -49102
Restaurants, Retail Space, U, -45921022
Households 200K+, White Collar Workers, M, 18311
Households 200K+, Blue Collar Workers, M, 185
Households 200K+, Service Workers, M, 3191
Households 200K+, SFD Housing, U, -1829192
Households 200K+, Multifamily Housing, U, -515182
The first row is the header, and should include these names. Each row specifies, in turn,
the activity under consideration, the commodities, whether the commodity target relates
to the make or use of that commodity, and then the target for the total amount of the
commodity to be produced or consumed. The order of the lines is unimportant (except
for the header).
Each target represents the total production or consumption in the PECAS model region,
and should be expressed in the same units used for the commodity elsewhere.
The TechnologyOptionsI file also needs to be formatted for the option size calibration.
The OptionName field needs to be parsable, needs to describe the commodities
involved in the option, and needs to flag options where more of the commodities are
produced. An example with some of these names:
Activity, OptionName, OptionSize,…
Restaurants, Minimum Consumption, 1, …
Restaurants, more | White Collar Workers, 1, …
Restaurants, more | Retail Space, 1, …
Households 200K+, No workers, 1, …
Households 200K+, SFD Housing | more | Service Workers, 1, …
There are two important features in the OptionName field. One is the use of the pipe
character | as a separator between commodities in the individual technology option.
PECAS Model Development: Trip Length Calibration Script
System Documentation Technical Note
Working Draft
ADM2
04.01.2009/KJS
File: PECAS Trip Length Calibration.01.doc
Page 5
This permits easy parsing by OSC. The second is the use of the term “more”, which
tags options that increase production or consumption, and therefore the ones that will
be changed by OSC.
Multiple commodities can be increased with the same option; for instance, the last
option in the example above would increase both the consumption of SFD housing and
the production of service workers for households with incomes over $200K.
At this point, OSC is only capable of adjusting an increased production or consumption
technology option, one that exceeds the average consumption for a given
activity/commodity pair. Other technology options will be ignored, so the simplest set of
options is for a “more” and a “less” (or a “zero”) option, with no average
production/consumption average.
4. Other Script Settings
Other settings in the script are specified in the code itself. Given standard file names,
these should not have to be altered beyond verifying path names. These are specified
in the first few lines of code, and are commented. A Python script can be opened in any
text editor, and a typical Python installation will include IDLE, a text editor with Pythonspecific syntax highlighting.
The first parameters specify the file names; these should be fairly standard, but could
be changed if necessary. They are:

targetFile: the name of the file containing the trip length targets, described above
as OptionSizeCalibI.csv

techFile: the name of the file containing the technology options, a standard AA
input called TechnologyOptionsI.csv
PECAS Model Development: Trip Length Calibration Script
System Documentation Technical Note
Working Draft

ADM2
04.01.2009/KJS
File: PECAS Trip Length Calibration.01.doc
Page 6
sourceFile: the name of the output file containing zonal make and use of
commodities by activity, a standard AA output called ZonalMakeUse.csv

outFile: the output file that reports the results of running OSC – an ongoing track
of target values, model results and an error measure (error^2) for each
commodity and activity. The default is a file named OptionSizeCheck.csv,
although this could be anything the user wants. This file is overwritten each
iteration, but can be kept with the keepAllFiles parameter described below.

modelCommand: the name of the operating system command that runs AA, by
convention RunAA.cmd. Note that this command file should not include any
pauses, or else OSC will require user intervention between each run.
The second set of parameters adjust specific numerical limits of OSC’s adjustments to
parameters, and again should be fairly standard. They are:

maxUp and maxDown: the maximum amounts that parameters are adjusted up
or down from one iteration to the next. These should be chosen to prevent OSC
from adjusting the parameter between the endpoints; for instance, if 2.0 and 0.5
are chosen, in some circumstances a parameter could be too low and adjusted to
double the initial value, then appear too high and be reduced back to the initial
value and so on indefinitely. Default values are 5.0 and 0.15.

maxIts: the maximum number of iterations for OSC to run; it stops when this is
reached.

keepAllFiles: a Boolean value; if True then the techFile and outFile described
above will be copied (with an iteration number appended) each iteration of AA;
this permits tracking of OSC as it adjusts parameters.
5. Program Mechanics
PECAS Model Development: Trip Length Calibration Script
System Documentation Technical Note
Working Draft
ADM2
04.01.2009/KJS
File: PECAS Trip Length Calibration.01.doc
Page 7
When OSC runs, it iterates through a number of steps. The first step is to run AA. Next,
OSC builds a dictionary containing all of the targets specified in the target file.
ZonalMakeUse is next read in, and the dictionary values are compared to the model
output values.
The next step is to read the TechnologyOptionsI file, and at the same time to adjust the
OptionSizes in this file based on the model’s performance relative to the targets. The
option sizes are multiplied by an adjustment factor; in the most common case of a
technology option affecting a single commodity, this factor is the target production or
consumption divided by the model output production or consumption.
If more than one commodity is affected by an individual technology option, the
adjustment is the product of the factors described above for each commodity, raised to
the power of one divided by the number of commodities affected. (It can be seen that
the case described above is mathematically equivalent to this version.)
OSC will run until the number of iterations has been exhausted; this can lead to very
large or small option sizes. Provided that they do not cause numerical overflows in AA,
this is not a problem. Option sizes can be scaled for a given activity by a constant value
if they get too large or too small, and OSC can be run for fewer iterations or with tighter
controls on option adjustments.
6. Operating Notes
The use to date of OSC is on a constrained AA model with 0 iterations. At this point,
OSC is still being developed, so typical operational behaviour cannot be described. In
general, the targets tend to be met fairly quickly.