(In)tervention (M)odel for (A)ir (P)ollution

Note: This is the documentation for the development version of InMAP. Documentation for other versions is available here.

About InMAP

InMAP is a multi-scale emissions-to-health impact model for fine particulate matter (PM_2.5) that mechanistically evaluates air quality and health benefits of perturbations to baseline emissions. A main simplification of InMAP compared to a comprehensive chemical transport model is that it does so on an annual-average basis rather than the highly time-resolved performance of a full CTM. The model incorporates annual-average parameters (e.g. transport, deposition, and reaction rates) from the a chemical transport model. Grid-cell size varies as shown in Figure 1, ranging from smaller grid cells in urban areas to larger grid cells in rural areas. This variable resolution grid is used to simulate population exposures to PM_2.5 with high spatial resolution while minimizing computational expense.

Figure 1: InMAP spatial discretization of the model domain into variable resolution grid cells. Left panel: full domain; right panel: a small section of the domain centered on the city of Los Angeles.

Getting InMAP

Go to releases to download the most recent release for your type of computer. For Mac systems, download the file with "darwin" in the name. You will need both the executable program and the input data ("evaldata_vX.X.X.zip"). All of the versions of the program are labeled "amd64" to denote that they are for 64-bit processors (i.e., all relatively recent notebook and desktop computers). It doesn't matter whether your computer processor is made by AMD or another brand, it should work either way.

Compiling from source

You can also compile InMAP from its source code. The instructions here are specific to Linux or Mac computers; other systems should work with minor changes to the commands below. Refer here for a list of theoretically supported systems.

Install the Go compiler. Make sure you install the correct version (64 bit) for your system. It may be useful to go through one of the tutorials to make sure the compiler is correctly installed.
Make sure your $PATH environment variable includes the directories $GOROOT/bin and $GOPATH/bin. On Linux or Macintosh systems, this can be done using the command export PATH=$PATH:$GOROOT/bin:$GOPATH/bin. On Windows systems, you can follow these directions.
Install the git and mercurial version control programs, if they are not already installed. If you are using a shared system or cluster, you may just need to load them with the commands module load git and module load hg.

Download and install the main program:

mkdir -p $GOPATH/src/github.com/spatialmodel # Create the directory for the code.
cd $GOPATH/src/github.com/spatialmodel # Move to the directory.
git clone https://github.com/spatialmodel/inmap.git # Download the code.
cd inmap # Move into the InMAP directory
go get github.com/golang/dep/cmd/dep # Install the program that will download the required libraries
dep ensure # Download the required libraries
go install ./inmap # Compile and install the InMAP executable.

Optional: run the tests and evaluations (this may take a while):
```
cd $GOPATH/src/github.com/spatialmodel/inmap
go test ./... -timeout="200h"
# or
go test ./... -short
```
To only run the tests and not the evaluations, run go test ./... -short. If you do run the evaluations, make sure you first download the evaluation data from the InMAP release page and set the evaldata environment variable to the location of the unzipped directory.

Running InMAP

Make sure that you have downloaded the InMAP input data files: evaldata_vX.X.X.zip from the InMAP release page, where X.X.X corresponds to a version number. The data files may need to be downloaded from a separate link included in the release information rather than directly from the release page.
Create an emissions scenario or use one of the evaluation emissions datasets available in the evaldata_vX.X.X.zip files on the InMAP release page. Emissions files should be in shapefile format where the attribute columns correspond to the names of emitted pollutants. The acceptable pollutant names are VOC, NOx, NH3, SOx, and PM2_5. Emissions units can be specified in the configuration file (discussed below) and can be short tons per year, kilograms per year, or micrograms per second. The model can handle multiple input emissions files, and emissions can be either elevated or ground level. Files with elevated emissions need to have attribute columns labeled "height", "diam", "temp", and "velocity" containing stack information in units of m, m, K, and m/s, respectively. Emissions will be allocated from the geometries in the shape file to the InMAP computational grid.
Make a copy of the configuration file template and edit it if desired, keeping in mind that you will either need to set the evaldata environment variable to the directory you downloaded the evaluation data to, or replace all instances of ${evaldata} in the configuration file with the path to that directory. You must also ensure that the directory OutputFile is to go in exists. Refer to the documentation here for information about other configuration options. The configuration file is a text file in TOML format, and any changes made to the file will need to conform to that format or the model will not run correctly and will produce an error.
Run the program:
```
 inmapXXX run steady --config=/path/to/configfile.toml
```
where inmapXXX is replaced with the executable file that you downloaded. For some systems you may need to type ./inmapXXX instead. If you compiled the program from source, the command will just be inmap for Linux or Mac systems and inmap.exe for Windows systems.

The above command runs the model in the most typical mode. For alternative run modes and other command options refer here.
View the program output. The output files are in shapefile format which can be viewed in most GIS programs. One free GIS program is QGIS. By default, the InMAP only outputs ground-level, but this can be changed using the configuration file.

Output variables are specified as OutputVariables in the configuration file. Each output variable is defined in the configuration file by its name and an expression that can be used to calculate it (in the form VariableName = "Expression"). Output variable names can be chosen by the user, but their corresponding expressions must consist of variables that are understood by InMAP. Note that output variable names should have a length of 10 characters or less because there is a limit on the allowed length of shapefile field names.

In the case of a variable that is built into the model, e.g. WindSpeed, an acceptable entry in the configuration file would be WindSpeed = "WindSpeed". If double WindSpeed is desired as an output variable, an acceptable entry in the configuration file would be DoubleWind = "WindSpeed*2". A user-defined variable such as DoubleWind can then appear in an separate expression, e.g. ExpTwoWind = "exp(DoubleWind)" where the DoubleWind is exponentiated. Note that expressions can include functions such as exp(). For more information on the available functions refer to the source code documentation (here).

Output variable expressions are, by default, evaluated within each grid cell. By surrounding an expression with braces ({...}), InMAP can instead perform summary calculations (evaluating the expression across all grid cells). InMAP has a built-in function sum() that can be used for such grid level calculations. For example, an expression for a variable NPctWNoLat, representing the percentage of the total US population that is Non-Latino White, would be NPctWNoLat = "{sum(WhiteNoLat) / sum(TotalPop)}". Only the part of the expression inside of the braces is evaluated at the grid level. NPctWNoLat could then be used as a variable in expressions evaluated at the grid cell level, e.g, WhNoLatDiff = "PctWhNoLat - NPctWNoLat", representing the difference between the percentage of the population of each grid cell that is white and the percentage of the total US population that is white.

There is a complete list of built-in variables here. Some examples include:
- Pollutant concentrations in units of μg m^-3:
  - VOC (VOC)
    - NO_x (NOx)
    - NH₃ (NH3)
    - SO_x (SOx)
    - Total PM_2.5 (TotalPM25; The sum of all PM_2.5 components)
    - Primary PM_2.5 (PrimaryPM25)
    - Particulate sulfate (pSO4)
    - Particulate nitrate (pNO3)
    - Particulate ammonium (pNH4)
    - Secondary organic aerosol (SOA)
- Populations of different demographic subgroups are in units of people per grid cell. The included populations may vary depending on input data, but in the default dataset as of this writing the groups included are:
  - total population (TotalPop)
  - people identifying as Asian (Asian), Black (Black), Latino (Latino), Native American or American Indian (Native), and Non-Latino White (WhiteNoLat).
- Mortality rates for the total population and/or different demographic subgroups, which can be used to perform health impact calculations, are in units of deaths per year per 100,000 people. Each mortality rate is mapped to a unique corresponding population group in the configuration file, e.g. AllCause = "TotalPop" or AsianMort = "Asian". Each mortality rate will be weighted by its corresponding population group when mortality rates are allocated to the grid cell level. The included mortality rates may vary depending on input data, but in the default dataset as of this writing baseline mortality rates are included for the following groups:
  - total poplation (AllCause)
  - people identifying as asian (AsianMort), black (BlackMort), latino (LatinoMort), native american or american indian (NativeMort), and non-latino white (WhNoLMort).
- Numbers of deaths attributable to PM_2.5 in each of the populations are obtained by defining an expression in the configuration file based on the variables TotalPM25, the population variable of interest, and the overall or population-specific mortality rate. For example, deaths among the total population could be calculated with the following entry in the configuration file: TotalPopD = "coxHazard(loglogRR(TotalPM25), TotalPop, AllCause)". Numbers of deaths are measured in units of deaths/year.

Running the preprocessor

InMAP includes a preprocessor to convert chemical transport model (CTM) output into InMAP meteorology and baseline chemistry input data. Unlike the main InMAP model, the preprocessor only needs to be run once for each spatiotemporal domain. Users that would like to use a different spatial or temporal domain than what is included with the InMAP download can obtain CTM output for that domain and run the preprocessor themselves. The WRF-Chem and GEOS-Chem CTMs are currently supported. Information on how to run the preprocessor is here, and information regarding preprocessor configuration is here.

API

The InMAP package is split into an executable program and an application programming interface (API). The documentation here shows the functions available in the API and how they work.

khoin / inmap