1. Tom Roche
  2. lightningNOx


lightningNOx / README.rst

(part of the AQMEII-NA_N2O family of projects)


Code in this repository supports the CMAQ workflow=`inline with parameters`_ for users to preprocess lightning-NO:sub:x observations and related data into a form consumable by CCTM. Hopefully it will soon migrate to a repository managed by CMAS or EPA.


initial commit

Provenance of files used for initial commit:

  1. I downloaded and expanded the CMAQ-5.0.1 tarballs as suggested on the CMAQ wiki.

  2. I defined the environment variables M3HOME and M3DATA as directed on the CMAQ wiki.

  3. I ran the following bash session:

    $ mkdir -p ~/code/lightningNOx/ # new dir/folder, not in tarball tree
    $ pushd ~/code/lightningNOx/
    $ git init
    # if tarsplat on remote host, use `rsync -avh --append`
    $ cp -r ${M3HOME}/scripts/lnox/* ./
    $ rm -fr ./R-out/
    $ rm -fr ./R-scripts/.Rhistory
    $ mv ./README ./README.0
    $ chmod 444 ./README.0
    $ chmod 444 R-scripts/*.dump
    $ chmod 444 R-scripts/README
    # get ICCG inputs: they are small enough to manage in repo
    $ mkdir -p ./ICCG_in/
    $ cp ${M3DATA}/raw/lnox/input/* ./ICCG_in/
    $ chmod 444  ./ICCG_in/*
    # ocean mask, NLDN inputs are too large

code structure

The current code generates Makefiles to build the various lightning-NO:sub:x artifacts. The primary generators are

  • Makefile.template: this template Makefile composes make variables, targets, rules, and recipes that encode all information required to build lightning-NO:sub:x artifacts for a given temporality (or time period) except the temporal information itself, which is present only as template values.
  • config_lNOx.sh contains one or more temporalities over which it iterates, instantiating a Makefile for each temporality by writing the temporal template values.

The primary generators drive one or more secondary generators for either

  • getting (whether creating or retrieving)
  • plotting

each of the major types of lightning-NO:sub:x artifacts:

  1. mask files. These are spatial artifacts; assuming that lightning NOx is being built for a normal CMAQ run with a single spatiality, only one mask file will need to be built. Building the mask file requires as input a MET_CRO_2D file (or METCRO2D) file, which is assumed to be provided with the rest of the meteorology for one's CMAQ run. The METCRO2D file is only accessed for its (IOAPI-provided, horizontal) grid information; since (again) that information is supposed to be constant over a CMAQ run, any METCRO2D for any temporality in the run should suffice.
  2. ICCG files. These are temporal artifacts, but have inputs for only 'summer' and 'winter', so the user must arbitrarily map their temporality to that space (in config_lNOx.sh).
  3. flash-totals files. These can be either downloaded or built, however the current code only supports download. (That being said, (Rob Pinder's?) code from the tarballs "benchmark" is in this repo, and could be presumably be recruited to build monthly flash-totals from "raw" NLDN data if required.)
  1. flash-parameters files. These are the current primary output of this project, providing lightning-NO:sub:x data suitable for input to CCTM.

Secondary generators are either

  • a pair of (bash, R) scripts, s.t. the bash script takes and processes arguments from make (failing fast on error), passing them to the R script, which does the real work. (This is done because I find argument handling in R more tedious than argument handling in bash.) This process generates mask and ICCG artifacts, and plots all of the artifacts.
  • a bash script driving LTNG_2D_DATA, to generate flash-parameters files.
  • a bash script driving wget, to download flash-totals files.

The current code also incorporates (Rob Pinder's?) previous code for building LTNG_2D_DATA (and the Makefile mechanism ensures that it's only built once).

use on HPCC

The repository code is setup to build/run "out of the box" on EPA HPCC (as of Mar 2014). Unfortunately

  • amad1 has both a {working, not too downlevel}{Intel Fortran, R}, but lacks the necessary links to Dave Wong's magic IOAPI and netCDF libraries.
  • infinity has the magic libraries and matching Intel Fortran, but its R is broken WRT R package=rgdal, which breaks R package=raster (used for regridding)

which complicates the process. Nevertheless, to build/run the tarballs "benchmark", one should be able to (on HPCC)

  1. Unpack the CMAQ-5.0.1 tarballs to a shared space (i.e., on /project), and record the location.
  2. Clone the repository to shared space, and record location.
  3. In Makefile.template, edit the paths to
  1. (beginning the trickier part) Open a shell on infinity, and run (filling-in the envvar appropriately)
    • ls -al $PROJECT_DIR/config_lNOx.sh
  2. Presuming that's found, run config_lNOx.sh
    • $PROJECT_DIR/config_lNOx.sh
    • ... which should build LTNG_2D_DATA, then die when it hits R.
  3. Open a shell on amad1 (or other HPCC box with a working R as defined above), and delete two files created by the previous invocation of config_lNOx.sh:
    • rm $PROJECT_DIR/Makefiles/Makefile.2006.06
    • rm $PROJECT_DIR/config_lNOx.sh.log
  4. In the same R-worthy shell, run (again) config_lNOx.sh:
    • $PROJECT_DIR/config_lNOx.sh
    • ... which should build the remaining artifacts, producing something like (paths depending on Makefile changes you might make)
path size
$PROJECT_DIR/ICCG_out/iccg.2006.06.csv 1453750
$PROJECT_DIR/mask_out/mask.csv 363420
$PROJECT_DIR/LTNG_2D_DATA_out/LTNG_RATIO.2006.06.ioapi 4404668
$PROJECT_DIR/NLDN_in/NLDN.2006.06.ioapi 560160
$PROJECT_DIR/ICCG_out/iccg.2006.06.pdf 460445
$PROJECT_DIR/LTNG_2D_DATA_out/lNOx_parms.2006.06.pdf 3636240
$PROJECT_DIR/mask_out/mask.pdf 448648
$PROJECT_DIR/NLDN_out/NLDN.2006.06.pdf 346148


  1. Move all these TODOs to this project's issue tracker.
  2. all users: document (uber.config.cmaq.*, config.cmaq*) from CMAQ-build
  3. Project needs extensive refactoring! lotsa common code :-(
    • write/use more functions, put in 'source'able files, call from {payload, main loop}
    • note lotsa functions in previous version of make_lNOx_parameters.sh that should probably be recovered!
    • R scripts in this project: fix/use common plotting functions, undo row-reversal in get.* functions
  1. Add info on running this code to this README (or to my lightning-NO:sub:`x wikipage <https://bitbucket.org/tlroche/aqmeii-na_n2o/wiki/lightning_NOx_over_AQMEII-NA_2008>`_ and point here).
  2. R scripts in this project: need better arg parsing. Currently all use vanilla R commandArgs, which are completely positional. Instead, use R package=optparse: see
  3. all my bash scripts (this project and beyond):
    • need better arg parsing: use built-in getopts (though it can't handle long options)
    • if calling a function=$CMD && 'tee-ing eval' (e.g., doing eval $CMD 2>&1 | tee -a $LOG_FP), make sure that $CMD is not writing log within its body (producing doubled lines in log)
    • if calling a function=$CMD && not 'tee-ing eval', make sure that $CMD is writing log within its body (to ensure completeness of log)
  4. make_mask.R: complete vectorization: still loops to calculate weights.
  5. all plot*.R: make subtitles plot
  6. support workflow=[download NLDN hourly, use to build NLDN monthly]. Currently I only support downloading NLDN monthly.