#QuickLook versions#
- In
masterbranch, there is an older version of QuickLook which does not have all features, but it is (somehow) tested. It produces GIFs and needsimagemagick. This branch usesflex_81.pyreading routines by J. Brioude (NOAA). - In
newIObranch, there is a more developed version of QuickLook with some additional features, like integration over species, integration over height columns etc. This version produces MP4 and needsffmpegto run. This branch uses reading routines by J. Bukhardt. - For both versions it is recommended to have
Matplotlibversion >= 1.3
QuickLook currently supports FLEXPART up to version 9.0. Newer versions > 9.0 are not currently supported due to changes in structure in headers and grids. The main problem is that the length of version string in header in versions >9.0 is not fixed as in FLEXPART 9.0 and binary reader can thus read some rubbish instead of data. Hopefully, this will be somehow standardised soon.
- Support of MP4 (branch
newIO) - Some minor improvements according to tickets (branch
newIO) - Integration over vertical columns now added (branch
newIO) - Integration over subset of species (branch
newIO) - Integration over time (branches
masterandnewIO) - Age classes support added - remains to be tested for dry and wet deposition
- Wet and dry depositions (or their sum) now can be shown!
- Quicklook now supports multiple species!
- New possibilities of plotting gridded data added (pcolormesh and imshow), look into
config.py! - Options for NASA Bluemarble, shaded relief and etopo map backgrounds added, look into
config.py! - Test data for forward and backward runs added, see Test data and examples Section!
QuickLook is a free command-line tool for quick plotting of FLEXPART outputs. Like the following ones:)
It is written in pure Python 2.7, so no compilation nor installation is required. You just need to fulfill the prerequisites and install all libraries needed, see Section Prerequisites. After obtaining OuickLook from this repository, you can easily modify it according to your needs. The easiest way how to get QuickLook is to clone the git repository:
$ git clone https://radekhofman@bitbucket.org/radekhofman/quicklook.gitor you can download the repository as a zip archive from download page.
The software is still under development. The future development should be user-driven so do not hesitate to raise your questions, suggestions or report issues and bugs using issues reporting system. Registration to Bitbucket is not needed, just click + Create issue in the top right corner of the page.
QuickLook is distributed under GPL 2.0.
To run QuickLook you need Python 2.7 and following libraries:
- Numpy
- Matplotlib >1.3
- Basemap
For producing GIF animations you also need ImageMagick.
Reading of FLEXPART outputs is accomplished via flex_81.py module by J. Brioude (NOAA).
It is quite easy:) QuickLook is a command-line tool. To display a list of possible options, simply run
$ python quick_look.py -hYou shoule get something like this:
Usage: quick_look.py [options]
Created by Radek Hofman 2014
Options:
--version show program's version number and exit
-h, --help show this help message and exit
-e EXP_PATH, --explore=EXP_PATH
Prints info abou Flexpart output at EXP_PATH
-i INPUT, --input=INPUT
Flexpart output directory
-d DOMAIN, --domain=DOMAIN
Coordinates of the domain: ll_lon, ll_lat, ur_lon,
ur_lat
-m, --max_lat_lon Takes maximum available lat-lon domain (overrides -d)
-l LEVELS, --levels=LEVELS
Sets vertical level range: l0, l1 (l0,l1 >= 0, l0=l1
to select just one level, e.g. -l 0 0 sets the ground layer)
-t TYPE, --type=TYPE Flexpart output type [mother|nested]
-o OUTPUT, --output=OUTPUT
Images output directory
-r RECEPTORS, --receptors=RECEPTORS
File with receptors
-f DATAFACTOR, --datafactor=DATAFACTOR
Factor to multiply the data with
-u UNITLABEL, --unitlabel=UNITLABEL
String containing units of visualized quantity
-n FILENAME, --filename=FILENAME
Filename of resulting GIF
-q, --reverse Files are processes in reverse order
-x TITLE, --title=TITLE
Title of images
-z PROJECTION, --projection=PROJECTION
Map projection [cylindrical:cyl (default),
Marcator:merc]
-s SPECIES, --species=SPECIES
species to show (default is the first one - 1)
--conc Show concentrations/residence times (default)
--drydepo Show dry depo (can be combined with --wetdepo)
--wetdepo Show wet depo (can be combined with --drydepo)To get started, let's explore some FLEXPART outputs. To do so, execute command
$ python quick_look.py -e <path_to_output>where <path_to_output> is path to FLEXPART Output directory, e.g.
$ python quick_look.py -e /home/radek/run_1/OutputYou should get something like:
==================================================================
DOMAIN TYPE: mother
Header info FLEXPART V9.0:
Number of species: 1
1 TRACER
Domain:
Lon: -179.000 - 179.000 deg, step 1.000 deg
Lat: -90.000 - 89.000 deg, step 1.000 deg
Output levels:
0 100.0 m
1 500.0 m
2 1000.0 m
3 1500.0 m
4 2000.0 m
Run type:
Backward run
Output step:
-10800 sec (-3.00 hours)
Release dates:
From 2013/04/07 18:54 to 2013/04/08 06:54
==================================================================
==================================================================
DOMAIN TYPE: nested
Header info FLEXPART V9.0:
Number of species: 1
1 TRACER
Domain:
Lon: 110.000 - 170.000 deg, step 0.250 deg
Lat: 15.000 - 60.000 deg, step 0.200 deg
Output levels:
0 100.0 m
1 500.0 m
2 1000.0 m
3 1500.0 m
4 2000.0 m
Run type:
Backward run
Output step:
-10800 sec (-3.00 hours)
Release dates:
From 2013/04/07 18:54 to 2013/04/08 06:54
==================================================================
We see that we have a backward run of FLEXPART with a global mother and a smaller nested domain. The output time step is 3 hours and we have 5 vertical levels 0-4.
Now, when we know what we have, we can plot the results. We run:
$ python quick_look.py -i /home/radek/run_1/Output -t mother -m -l 0 4 -s 1This command says:
- Plot data from /home/radek/run_1/Output (
-i /home/radek/run_1/Output) - Use mother domain (
-t mother) - Take maximum available lon-lat range (
-m) - Show integrated values over all levels 0-4 (
-l 0 4) - Take output for species no. 1
The output should be as follows:
[INFO] - Species: 1 TRACER
[INFO] - Taking maximum available domain: (-179.0, -90.0, 179.0, 89.0)
[INFO] - No output path provided, results will be saved to /home/radek/run_1/Output
[INFO] - No filename provided, setting to anim_mother.gif
[INFO] - cylindrical projection will be used
[INFO] -- Minimum date value = 0.0000E+00
[INFO] -- Maximum value of data = 1.3717E+03
[INFO] -- Processing file 0 grid_time_20130327000000_001
[INFO] - Creating animation /home/radek/run_1/Output/mother_0-4_anim_mother.gif
[INFO] -- Processing file 0 grid_time_20130327000000_001
[INFO] -- Processing file 1 grid_time_20130327030000_001
[INFO] -- Processing file 2 grid_time_20130327060000_001
.
.
.
...Done!What we get is a bunch of PNGs with single time frames and a GIF animation. That was easy, wasn't it?:) Since we did not set any output directory, the output files (frames+animation) are stored in input path. Much better is to define a separate location for this using -o flag. We can also change the name of our animation using -n flag. The type of domain and selected vertical levels are appended automatically to the file name.
We can further improve our plot. For example, we can plot points of interest (PIO) into the plot by the means of providing a file using flag -r <file_with_POIs>. The format of the file should be as follows. Each PIO is on a separate line, where its longitude, latitude and label appear:
139.08 36.30 JPX38
To plot a sub-domain instead of the whole domain, use -d ll_lon, ll_lat, ur_lon, ur_lat, where parameters are longitude of lower-left corner, latitude of lower-left corner, longitude of upper-right corner and latitude of upper-right corner. This flag is overridden by -m flag taking maximum available domain. To select a range of vertical levels which are shown use -l <level1> <level2>. If you want to see just one particular level, then set level1=level2.
Title of plots can be set using -x <Title>. This will appear on all frames. Date-time stamp in the title is added automatically. You can also set units which will appear under the colorbar using -u <Units>.
If you need to multiply the data by a Factor before plotting, use -f <Factor>.
Particularly for backward runs is useful flag -q, which forces the output files to be processed in a backward manner.
To select which species to plot, use -s <species number>.
To change the map projection from default cylindrical to Mercator, use -z merc. Warning: Using of Mercator projection for a domain containing poles will raise an error.
To show dry/wet deposition instead of concentration/residence times, use --drydepo or --wetdepo. To show their sum use both, i.e. --drydepo --wetdepo.
Generally, virtually everything can be changed by modifying the source code of QuickLook. However, the goal is to provide a full control over the appearance of plots via a configuration file config.py, where you can configure some properties. I hope that the structure of the file is quite self-explanatory.
Test data for backward run of FLEXPART are available in test_data in the root of the repository. There are test data for both forward and backward runs. Forward run includes multiple species. For example, you can run the backward example by executing the following command from src directory:
$ python quick_look.py -i ../test_data/bwd_run -t mother -m -l 0 4 -r ../test_data/receprors.txt -x "Backward run from JPX38" -u "(mBq/GBq)" -o ../samples/An animation in samples should be produced.
- Prepare unit tests to maintain consistency in future development:)
- Enable users to easily access more parameters via config.py file
- Include flex-diff tool for plotting differences between two FLEXPART runs
- Improve ERROR and WARNING messages
If you have any special requirement, please let me know via issues reporting system:)