masterbranch, there is an older version of QuickLook which does not have all features, but it is (somehow) tested. It produces GIFs and needs
imagemagick. This branch uses
flex_81.pyreading routines by J. Brioude (NOAA).
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 needs
ffmpegto run. This branch uses reading routines by J. Bukhardt.
- For both versions it is recommended to have
Matplotlibversion >= 1.3
QuickLook and FLEXPART versions
QuickLook currently supports FLEXPART up to version 9.0. Newer versions > 9.0 are not currently supported due to changes in structure in
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
- Some minor improvements according to tickets (branch
- Integration over vertical columns now added (branch
- Integration over subset of species (branch
- Integration over time (branches
- 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
- Options for NASA Bluemarble, shaded relief and etopo map backgrounds added, look into
- 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://email@example.com/radekhofman/quicklook.git
or 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:
For producing GIF animations you also need ImageMagick.
Reading of FLEXPART outputs is accomplished via flex_81.py module by J. Brioude (NOAA).
How to use QuickLook?
It is quite easy:) QuickLook is a command-line tool. To display a list of possible options, simply run
$ python quick_look.py -h
You 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)
Explore FLEXPART outputs
To get started, let's explore some FLEXPART outputs. To do so, execute command
$ python quick_look.py -e <path_to_output>
<path_to_output> is path to FLEXPART Output directory, e.g.
$ python quick_look.py -e /home/radek/run_1/Output
You 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 1
This command says:
- Plot data from /home/radek/run_1/Output (
- Use mother domain (
- Take maximum available lon-lat range (
- 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
If you need to multiply the data by a Factor before plotting, use
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
--wetdepo. To show their sum use both, i.e.
Configuring and modifying QuickLook
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 and examples
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
$ 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:)