Docstoc

COMMANDS

Document Sample
COMMANDS Powered By Docstoc
					BenMAP Command Line Control File Format

US Version 2
October 4, 2006

Miscellaneous Statements

Comment statements will be supported at any point in the file. Lines beginning with a
pound character (#) will be considered comment lines and will be ignored during file
parsing.

Additionally, LOAD <filename> statements will be supported at any point in the file.
These work as string replacements – the contents of the file specified by <filename> are
simply inserted into the main file. Multi-level LOAD statements are supported, but no
attempt is made to detect cycles (two files referencing each other with LOAD statements,
for example).

The control file is, in general, not case sensitive. The case of user-defined strings
(variable values, etc.) will be preserved, however.

Overall Format

The overall format of the file will be a variable definitions section followed by a
commands section.

[Variable Definitions]

The variable definitions section is optional, and if present will consist of a single line
with the word “Variables” on it, followed by one or more lines that define variables. A
variable definition consists of a variable name and a variable value. When parsing lines
in the commands section of the control file, all occurrences of the variable name will be
replaced by the variable value.

All variable names must begin and end with the percent character (%).

VARIABLES

%BENMAPDIR%              C:\Program Files\Abt Associates Inc\BenMAP 2.4 US Version
%AQGDIR%                 %BENMAPDIR%\Air Quality Grids

Variable Name/Value replacement will be done in multiple passes (until no variable
names remain), so variable values may contain other variable names. No attempt will be
made to detect cycles, however, so be careful not to introduce them. For example, avoid
variable definitions like the following:

%BENMAPDIR%              %AQGDIR%\
%AQGDIR%               %BENMAPDIR%\Air Quality Grids

Variable values must be contained in a single line, and will consist of the first non-
whitespace character after the variable name through the newline character. Watch out
for undesired trailing whitespaces!

[Commands]

The commands section is required, and will consist of one or more command sections.
There are five types of command sections:

       SETACTIVESETUP
       CREATE AQG
       RUN CFG
       RUN APV
       GENERATE REPORT

We will go over each one in turn.

In general in command sections, there must be at least one whitespace between each
token (where a token is either a command, a parameter name, or a parameter value).
Additional whitespace is ignored, including newline characters. To include whitespace in
a parameter value, you must enclose the parameter in double quotes. The double quotes
will not be included in the parameter value in this case (If you wish to include beginning
and trailing double quotes in a parameter value, put two in a row at the beginning and end
– e.g. ““Look at all those double quotes.””).

COMMANDS

SETACTIVESETUP

       -ActiveSetup “United States”

For the US version of the BenMAP command line executable the only valid value is
United States. The SETACTIVESETUP section is required.

CREATE AQG

This section initiates the creation of one or more air quality grids (normally one,
potentially two in the case of monitor rollback grid creation – see below). It always starts
with the words CREATE AQG. It must then include the following options, in any order:

       -Filename <filename>
       -GridType <gridtype>
       -Pollutant <pollutant>
Supported GridType values are:

       REMSAD                  REMSAD grids.
       CAMx                    CAMx or UAM-V grids.
       CMAQ                    CMAQ grids.
       Shape                   Shapefile based grids.

The Grid Definition value must be one found in the United States database. The actual
values for this parameter are found on the Modify Setup screen in the Grid Definitions
list box.

If SHAPE is selected as the GridType value, a Shapefile name must also be included:

       -ShapefileName <filename>

Supported Pollutant values are:

       Ozone                   Ozone grids.
       PM10                    PM 10 grids.
       PM2.5                   PM 2.5 grids.

These values are also found on the Modify Setup screen in the Pollutants list box.

After these required options, the type of grid creation must be identified, and then the
parameters for that grid creation type must be specified. There are four air quality grid
creation types:

       ModelDirect
       MonitorDirect
       MonitorModelRelative
       MonitorRollback

Monitor Rollback is not supported in this version of the BenMAP Command Line
executable. Model Direct, Monitor Direct and Monitor Model Relative will be described
below.

ModelDirect

Initiates the creation of a model direct air quality grid. This creation type has two
required parameters and no optional parameters:

       -ModelFilename <filename>
       -DSNName <ODBC DSN name>

-DSNName can be “Excel Files”, “Text Files” or “MS Access Database”.
Example:

##
## Model Direct
##
CREATE AQG

-Filename       %AQGDIR%%MODELAQGNAME%
-GridType       "CAMx"
-Pollutant      Ozone

ModelDirect

-ModelFilename          "C:\BenMap_development\CommandLine\O3.xls"
-DSNName                "Excel Files"

MonitorDirect

Initiates the creation of a monitor direct air quality grid.

Required Parameters

        -MonitorDataType <DataSource descriptor>
        -InterpolationMethod <Interpolation Method>

MonitorDataType must be one of Library, DatabaseColumns, DatabaseRows, or
TextFile.
Interpolation method must be either ClosestMonitor or VNA.

If –MonitorDataType is Library then the following parameters are required:

        -MonitorDataSet <Monitor Dataset Name>
        -MonitorYear <Year>

-MonitorDataSet is the Dataset name of Monitor data stored in the BenMAP database.
These values can be found on the Modify Setup screen in Monitor Datasets list box.

-MonitorYear specifies the year of interest in the monitor library.

If –MonitorDataType is not Library then the following parameter is required.

        -MonitorFile <filename>

MonitorFile specifies a comma separated values (*.csv, generally) file containing monitor
data. This implies that the library of monitor data included with BenMAP is not being
used.
Optional Parameters

       -MaxDistance <real>

Specifies the maximum distance (in kilometers) to be used in ClosestMonitor
interpolation or VNA interpolation. Monitors outside this distance will not be considered
in the interpolation procedure.

       -MaxRelativeDistance <real>

Specifies the maximum relative distance to be used in VNA interpolation, where relative
distance is the multiple of the distance to the closest monitor used in the interpolation
procedure.

       -WeightingMethod <method>

Specifies the weighting procedure used for monitors in VNA interpolation. Supported
values are InverseDistance and InverseDistanceSquared. If this parameter is not
specified, InverseDistance weighting is used.

Example:

##
## Monitor Direct
##
CREATE AQG

-Filename       %AQGDIR%%MONITORAQGNAME2000%
-GridType       "CMAQ LC"
-Pollutant      PM2.5

MonitorDirect

-InterpolationMethod   ClosestMonitor
-MonitorDataType       Library
-MonitorDataSet        "EPA Standard Monitors"
-MonitorYear           2000

MonitorModelRelative

Initiates the creation of a monitor model relative air quality grid. This creation type has
all the same required and optional parameters as the MonitorDirect creation type. In
addition, it has two/three new required parameters.

Required Parameters
       -ScalingMethod <scaling method>

Supported scaling methods are Spatial, Temporal, and Both.

       -BaseYearFilename <filename>

Specifies the base year adjustment file to use in monitor scaling.

       -BaseYearDSNName <ODBC DSN Name>

Valid values are “Excel Files”, “Text Files” or “MS Access Database”.

When the ScalingMethod is Temporal or Both, the –FutureYearFileName and
FutureYearDSNName parameters is required. These specify the future year adjustment
file to use in monitor scaling.

Example:

##
## Monitor Model Relative
##
CREATE AQG

-Filename      %AQGDIR%%MONMODAQGNAME2000%
-GridType      "CAMx"
-Pollutant     Ozone

MonitorModelRelative

-InterpolationMethod   ClosestMonitor
-ScalingMethod         Spatial
-MonitorDataType       Library
-MonitorDataSet        "EPA Standard Monitors"
-MonitorYear           2000
-BaseYearFileName      "C:\BenMap_development\CommandLine\test_o3.xls"
-BaseYearDSNName       "Excel Files"

RUN CFG

The command line version of BenMAP does not support creation of new .cfg files, both
because this would be quite cumbersome to do in plain text, and because it probably is
not needed. Slight modifications of existing .cfg files are supported, and it is thought that
at this point this should be enough.

As such, the only required parameter to run a configuration is the configuration filename.
Optional parameters allow the slight modifications mentioned above.

Required Parameters

        -CFGFilename <filename>

Specifies the .cfg file to run.

        -ResultsFilename <filename>

Specifies the .cfgr file to save the results in.

Optional Parameters

        -BaselineAQG <filename>

Specifies the baseline air quality grid file to use when running the configuration –
overrides whatever value is present in the .cfg file.

        -ControlAQG <filename>

Specifies the control air quality grid file to use when running the configuration –
overrides whatever value is present in the .cfg file.

        -Year <Integer>

Year in which to run the configuration (this will affect the population numbers used) –
overrides whatever value is present in the .cfg file. Supported values are 1990 and up.

        -LatinHypercubePoints <integer>

Number of latin hypercube points to generate when running the configuration (zero
means run in point mode) – overrides whatever value is present in the .cfg file.

        -Threshold <real>

Threshold to use when running the configuration – overrides whatever value is present in
the .cfg file.

RUN APV

The command line version of BenMAP does not support creation of new .apv files, both
because this would be quite cumbersome to do in plain text, and because it probably is
not needed. Slight modifications of existing .apv files are supported, and it is thought
that at this point this should be enough.
As such, the only required parameter to run an APV configuration is the APV
configuration filename. Optional parameters allow the slight modifications mentioned
above.

Required Parameters

        -APVFilename <filename>

Specifies the .apv file to run.

        -ResultsFilename <filename>

Specifies the .apvr file to save the results in.

Optional Parameters

        -CFGRFilename <filename>

Specifies the .cfgr file to use when running the APV configuration – note that this file
must contain the same set of results which the .cfgr file originally used to generate the
.apv file contained. Overrides whatever value is present in the .apv file.

        -IncidenceAggregation <aggregation level>

Level to aggregate incidence results to before pooling them. Supported values are None,
County, State, and Nation. Overrides whatever value is present in the .apv file.

        -ValuationAggregation <aggregation level>

Level to aggregate valuation results to before pooling them. Supported values are None,
County, State, and Nation (though the value must be greater than or equal to
IncidenceAggregation). Overrides whatever value is present in the .apv file.

        -RandomSeed <integer>

Random seed to use for all procedures requiring pseudo-random numbers (e.g. monte
carlo procedures). Overrides the default behavior, which is to generate a new random
seed each time the APV configuration is run.

        -DollarYear <integer>

Year in which dollar figures should be reported. Supported values are 1980 – 2001.
Overrides whatever value is present in the .apv file.

GENERATE REPORT
Reports come in three main varieties – Audit Trail Reports, which can be generated from
any BenMAP file; Configuration Results Reports, which can be generated from .cfgr
files; and APV Configuration Results Reports, which can be generated from .apvr files.
All these report types need an input filename and an output filename. CFGR reports and
APVR reports additionally take many optional parameters.

The format for each report type is:

GENERATE REPORT <ReportType>

       -InputFile <filename>
       -ReportFile <filename>
       <optional parameters>

Supported ReportType values are: AuditTrail, CFGR, and APVR.

Example InputFile and ReportFile parameters.

-InputFile     %AQGDIR%\Baseline.aqg
-ReportFile    %BENMAPDIR%\Reports\Baseline.txt

GENERATE REPORT AuditTrail

       No additional parameters.

GENERATE REPORT CFGR

Optional Parameters

       -GridFields <comma separated field names>

Specifies the set of grid fields to include in the report. Grid fields include Column and
Row. If this parameter is not present, all fields will be included in the report.

       -CustomFields <comma separated field names>

Specifies the set of custom fields (C-R Function identifiers, in this case) to include in the
report. If this parameter is not present, all fields will be included in the report.

       -ResultFields <comma separated field names>

Specifies the set of result fields to include in the report. Result fields include Point
Estimate, Population, Delta, Mean, Standard Deviation, Variance, and Latin Hypercube
Points. If this parameter is not present, all fields will be included in the report.

       -Grouping <grouping method>
Specifies the grouping for the results – Gridcell, then C-R Function, or C-R Function,
then Gridcell. Supported values are GridcellFirst, GridcellLast. The default value is
GridcellFirst.

       -DecimalDigits <integer>

Specifies the number of digits after the decimal point to include in the report. Supported
values are zero to eight. The default value is four.

GENERATE REPORT APVR

Required Parameters

       -ResultType <result type>

Specifies the result type for which a report should be created. Supported result types are:
IncidenceResults, AggregatedIncidence, PooledIncidence,Valuation,
AggregatedValuation, PooledValuation, QALYValuation, AggregatedQALYValuation
and PooledQALYValuation.

Optional Parameters

All of the CFGR report parameters are supported for APVR reports as well, except that
Population and Delta are not supported ResultField elements.

       -Totals <total type>

Specifies the type of totals which should be included in the report. Supported types are
Dependent and Independent. Totals can only be generated for valuation results
(Valuation, AggregatedValuation, and PooledValuation result types).

				
DOCUMENT INFO
Shared By:
Categories:
Tags:
Stats:
views:3
posted:12/2/2011
language:English
pages:10