R interface to HYSPLIT for scalable trajectory computing

Installation

How to run the program

The main arguments required to run a set of trajectories are --from, which specifies the starting date(s); --to, which specifies the ending date(s) and --byhour, --byday, --bymonth and --byyear, which specifies the intervals of time separating the first and last date(s) of the set. The latter four arguments take integers, e.g. --by_hour 1 indicates to run one trajectory per hour between the starting and ending date(s) and times(s). --from and --to take dates and hours in the format YYYY-MM-DD-hh-mm, i.e. the year, month, day, hour and minute (in 24-hour format). In addition, the argument --duration indicates how long each trajectory calculation should last, and whether it should go forwards or backwards in time, e.g. --duartion -24 indicates that each trajectory is computed up to 24 hours before its starting time.

A series of examples are provided below. Example 1 goes over the different types of output obtained form the program while the others focus on different combinations of days, months, etc. that can be done.

Note: it is also possible to run a single trajectory by simply specifying the same dates and times in --from and --to.

Example 1: Running a sequence of trajectories separated by a single unit of time

One possible use of this program is to run a set of trajectory calculations from one point in time to another, separated regularly by a single "unit of time". For example, one may wish to run trajectories at October 22nd 2013 at 06:00h, October 22nd 2013 at 07:00h, etc., until October 25th 2013 at 06:00h, 24 hours backwards, starting at altitudes of 500, 1000 and 2000m AGL from coordinates (5.745974, -53.934047). In such case, the arguments --from and --to simply indicate the starting and ending times, and --byhour 1 indicates that we want one trajectory per hour between those two time points:

./Hysplit_wind_analysis.R --from 2013-10-22-06-00 --to 2013-10-25-06-00 --lat 5.745974 --lon -53.934047 --altitude 500,1000,2000 --duration -24 --byhour 1

First of all, the program will download any necessary meteorological files from the NOAA's servers. For large runs, this can take some time, so please be patient. Luckily once they are downloaded, running any trajectories involving these files will be much quicker (unless you delete them, which is not recommended).

Afterwards the program will compute all trajectories and then produce the first plot, which are rasterized trajectory plots containing the trajectory density at each raster cell. These are provided for each starting height separately:

Secondly, a map with all trajectories plotted is also provided:

The next output are circular histogram, indicating the proportion of trajectories going in each direction:

In a set of forwards trajectories, the histogram indicates the positions at which the winds starting from the point of origin arrived after the indicated number of hours. In a set of backwards trajectories, the histogram indicates the positions from which the winds arriving to the point of origin started.

Lastly, an "altitudinal profile" plot is provided, which indicates the mean height (± standard error) of each group of trajectories at the different hours of the duration of the run:

Example 2: Running trajectories across multiple units of time

Instead of being interested in a single, "continuous" set of trajectories, one may be interested in a set of trajectories repeated across a larger interval. For example, one may want to compute trajectories for all hours between 10:00 and 18:00 from days 1st to 10th of April, May and June, for years 2000 to 2022. In this case, we have a smaller sequence (from 10:00 to 18:00 by one hour) that then repeats in a larger one (from 1st to 10th day of the month, by one day), then another one (from April to June, month by month) and finally another one (from 2000 to 2002, year by year). To do this, the arguments --from and --to need to indicate, respectively, the smaller and larger element of each of the sequences, and then we indicate the step size with the arguments byhour, byday, bymonth and byyear:

./Hysplit_wind_analysis.R --from 2000-04-01-10-00 --to 2002-06-10-18-00 --lat 5.745974 --lon -53.934047 --altitude 500,1000,2000 --duration -24 --byyear 1 --bymonth 1 --byday 1 --byhour 1

Troubleshooting

Meteorological files not downloading properly

When a run will require meteorological files that need to be downloaded, there is a chance that if the Internet connection is not working properly the file download will halt, and the program will exit with an error.

If this happens, one needs to go to the HYSPLIT installation folder, enter the working folder and remove the incomplete meterological file. These files are identified by the .gbl extension and are named starting with RP and then indicating the year and the month. If the file is not removed, HYSPLIT will think it already has it and try to compute the trajectories, but then it will give an error, as some data will be missing.

If downloading the files is giving problems, you may also try to download them (in Linux) by running the following from the working/ directory of your hysplit installation:

for ((year=1948; year<2023; year++)); do for month in 01 02 03 04 05 06 07 08 09 10 11 12; do wget ftp://ftp.arl.noaa.gov/pub/archives/reanalysis/RP${year}${month}.gbl; done; done

This will download the entire Reanalysis database from 1948 to 2022, but you may adjust this to download only the files you need. Note that the full database until 2022 takes about 102GB of disk space.

Citation

If you use this program please cite at least one of these articles: