{"Package":"SplitR","Type":"Package","Title":"Use the HYSPLIT model from inside R","Version":"0.4","Date":"2016-04-05","Author":"Richard Iannone ","Maintainer":"Richard Iannone ","Description":"Use the HYSPLIT model from inside R and do more with it.","License":"MIT + file LICENSE","Imports":"\ndownloader (>= 0.4),\ndplyr (>= 0.4.3),\nggmap (>= 2.6.1),\nleaflet (>= 1.0.0),\nlubridate (>= 1.5.0),\nscales (>= 0.4.0)","RoxygenNote":"5.0.1","repoType":"github","tarballUrl":"https://api.github.com/repos/rich-iannone/splitr/tarball/v0.4","readme":"

\n\n[![DOI](https://zenodo.org/badge/20543/rich-iannone/SplitR.svg)](https://zenodo.org/badge/latestdoi/20543/rich-iannone/SplitR)\n\n**SplitR** is an **R** package for conducting trajectory and dispersion modelling with **HYSPLIT**. You can determine where air (came from | is going), or, where gas-phase or particulate matter (came from | is going). It's a means to help explain how, where, and when chemicals and materials are atmospherically transported, dispersed, and deposited.\n\nThis model has many applications. Some have modeled the atmospheric transport of moisture to determine probable extreme rainfall locations leading to flood events ([Gustafsson et al., 2010](http://tellusa.net/index.php/tellusa/article/view/15715)). Similarly, [Creamean et al., 2013](http://science.sciencemag.org/content/339/6127/1572.full) have presented a direct link between long-range transported dust and biological aerosols affecting cloud ice formation and precipitation processes in western United States.\n\nOthers have successfully improved understanding of invasive species dispersal abilities to inform conservation and landscape management ([Lander et al., 2014](http://onlinelibrary.wiley.com/doi/10.1002/ece3.1206/abstract)). Along similar lines, the long-distance transport of high-risk plant pathogens can be modeled with **HYSPLIT** to assist with plant disease management decisions, such as applications of fungicide or pesticide to potentially-affected agricultural areas ([Schmale and Ross, 2015](http://www.annualreviews.org/doi/abs/10.1146/annurev-phyto-080614-115942?journalCode=phyto)).\n\n**SplitR** allows you to build and run **HYSPLIT** models in a fast, easy, and organized manner. A few or, perhaps, thousands of trajectory or dispersion runs can be conducted with minimal code. Because **SplitR** is an **R** interface to **HYSPLIT**, we can store output in memory and take advantage of the vast selection of **R** packages to perform statistical analyses and to generate visualizations. This package simplifies the process of running **HYSPLIT** models by providing a simple means to execute a range of runs and by automating the retrieval and storage of associated meteorological data files.\n\nSome of the things you can do with **SplitR** are:\n\n- create and execute model runs with an easily readable **magrittr** pipeline workflow\n- run multiple trajectory and dispersion model runs (forward or backward) with multiple temporal and spatial variations\n- visualize wind trajectories and particle positions throughout trajectory and dispersion runs\n- use the returned **dplyr** `tbl` data frame to `filter()`, `select()`, `group_by()`, `summarize()`, `mutate()`, and `transmute()` the model output data\n\n## **HYSPLIT** Trajectory Runs\n\nTo perform a series **HYSPLIT** trajectory model runs, one can simply use the **SplitR** `hysplit_trajectory()` function:\n\n```R\nlibrary(SplitR)\n\nsetwd(\"~/Documents/SplitR_wd\")\n\ntrajectory <- \n hysplit_trajectory(\n lat = 42.83752,\n lon = -80.30364,\n height = 50,\n duration = 24,\n run_period = \"2012-03-12\",\n daily_hours = c(0, 6, 12, 18),\n direction = \"forward\",\n met_type = \"gdas1\",\n extended_met = TRUE) \n```\n\nThis use of `hysplit_trajectory()` sets up four trajectory runs that start at 00:00, 06:00, 12:00, and 18:00 UTC on March 12, 2012 (using `run_period = \"2012-03-12\"` and `daily_hours = c(0, 6, 12, 18)`). Several years of runs can be initiated using `run_period = c(2012, 2014)`, model runs can be performed between a range of dates as well (`run_period = c(\"2012-03-12\", \"2013-05-23\")`). These runs are 24 h in duration (`duration = 24`). \n\nThe receptor/origin locations are set using `lat` and `lon` for the latitude(s) and longitude(s). The starting location of 42.83752ºN and 80.30364ºW is set here using `lat = 42.83752` and `lon = -80.30364`. Equal-length vectors of `lat` and `lon` values can be used here to create an ensemble of model runs. The starting height of 5 m above ground level is set by `height = 5`.\n\nThe model runs as set above are forward runs (moving forward in time, set here using `direction = \"forward\"`) and not backtrajectory runs (set with `direction = \"backward\"`).\n\nThe meteorological options include the type of met data to use. The 1º **GDAS** data is used here with `met_type = \"gdas1\"` but there is also the option to use **NCEP** reanalysis data with the `met_type = \"reanalysis\"` setting. The necessary meteorological data files relevant to the period being modelled will be downloaded from the **NOAA** FTP server if they are not present in the working directory,\n\nThe function will return a data frame containing trajectory information. The data frame (named here as the object `trajectory`) will be have the following columns when `extended_met` is set to `FALSE`:\n\n- `receptor` a numeric label for the receptor\n- `year`, `month`, `day`, `hour` integer values for date/time components\n- `hour.inc` the integer hour difference compared to the run starting time\n- `lat`, `lon`, `height` the latitude, longitude, and height (meters above ground level) of the air mass along the trajectory\n- `pressure` the air pressure along the trajectory (in hPa)\n- `date2` a POSIXct date-time value (in UTC) for the air mass along the trajectory\n- `date` a POSIXct date-time value (in UTC) for the time of release or time of incidence at the receptor site\n\nIf the model is run with `extended_met` set to `TRUE` then the following columns will also be available in the data frame:\n\n- `theta` the potential temperature (in K) along the trajectory\n- `air_temp` the ambient air temperature (in K) along the trajectory\n- `rainfall` the rate of rainfall (in mm/h) along the trajectory\n- `mixdepth` the mixing depth (or mixing height, in meters) along the trajectory\n- `rh` the relative humidity along the trajectory\n- `sp_humidity` the specific humidity (in g/kg) along the trajectory\n- `h2o_mixrate` the mixed layer depth (in meters) along the trajectory\n- `terr_msl` the terrain height at the location defined by `lat` and `long`\n- `sun_flux` the downward solar radiation flux (in watts) along the trajectory\n\nModels can also be defined and executed using a modeling object in a **magrittr** workflow. Here's an example:\n\n```R\nlibrary(SplitR)\nlibrary(magrittr)\n\nsetwd(\"~/Documents/SplitR_wd\")\n\n# Create the `trajectory_model` object, add\n# a grid of starting locations, add run\n# parameters, and execute the model runs\ntrajectory_model <-\n create_traj_model() %>%\n add_grid(\n lat = 49.0,\n lon = -123.0,\n range = c(0.8, 0.8),\n division = c(0.2, 0.2)) %>%\n add_params(\n height = 50,\n duration = 6,\n run_period = \"2015-07-01\",\n daily_hours = c(0, 12),\n direction = \"backward\",\n met_type = \"reanalysis\") %>%\n run_model\n```\n\nThis pipeline setup allows for more flexibility as **R** objects can be piped in for variation in the types of models created. The `create_traj_model()` function creates the trajectory model object. The `add_grid()` allows for the simple creation of a grid for multiple starting locations in an ensemble run. One or more `add_params()` statements can be used to write model parameters to the model object. Ending the pipeline with `run_model()` runs the model and creates results.\n\nThe trajectory data can be be extracted from the trajectory model object using `get_output_df()`...\n\n```R\n# Get a data frame containing the model results\ntrajectory_df <-\n trajectory_model %>% get_output_df\n```\n\n...and a **dplyr** `tbl` object is now available:\n\n```R\ntrajectory_df\n#> Source: local data frame [175 x 21]\n#> \n#> receptor year month day hour hour.inc lat lon height\n#> (int) (int) (int) (int) (int) (dbl) (dbl) (dbl) (dbl)\n#> 1 1 15 7 1 0 0 49.400 -123.400 50.0\n#> 2 1 15 7 1 1 1 49.359 -123.203 49.9\n#> 3 1 15 7 1 2 2 49.326 -123.039 49.3\n#> 4 1 15 7 1 3 3 49.300 -122.905 48.2\n#> 5 1 15 7 1 4 4 49.282 -122.800 46.7\n#> 6 1 15 7 1 5 5 49.268 -122.723 44.8\n#> 7 1 15 7 1 6 6 49.260 -122.672 42.5\n#> 8 2 15 7 1 0 0 49.400 -123.200 50.0\n#> 9 2 15 7 1 1 1 49.369 -123.008 49.9\n#> 10 2 15 7 1 2 2 49.346 -122.848 49.4\n#> .. ... ... ... ... ... ... ... ... ...\n#> Variables not shown: pressure (dbl), date2 (time), date (time), theta\n#> (dbl), air_temp (dbl), rainfall (dbl), mixdepth (dbl), rh (dbl),\n#> sp_humidity (dbl), h2o_mixrate (dbl), terr_msl (dbl), sun_flux (dbl)\n```\n\n#### Plotting Trajectory Data\n\nTrajectories can be plotted onto an interactive map. Use the `trajectory_plot()` function with either the `trajectory` data frame (created directly by the `hysplit_trajectory()` function), or, even better, with a trajectory model object.\n\n```R\nlibrary(SplitR)\nlibrary(magrittr)\n\n# Plot results using the trajectory data frame\ntrajectory_plot(trajectory)\n\n# Plot results using the trajectory model object\ntrajectory_model %>% trajectory_plot\n```\n\nThe visualization will appear in the **RStudio** Viewer:\n\n

\n\nThe trajectory points and paths are layers where their visibility can be toggled using the *Layers* icon at the top-right of the view. The following selection of basemaps is also provided:\n\n- CartoDB Dark Matter\n- CartoDB Positron\n- ESRI World Terrain\n- Stamen Toner\n\nClicking any of the points along the trajectory will provide an informative popup with time/position info and meteorological data for that location at that point in time:\n\n

\n\n## **HYSPLIT** Dispersion Runs\n\nDispersion models can also be conveniently built and executed using a **magrittr** workflow. Instantiate the dispersion model with the `create_disp_model()` function. Use one or more `add_params()` statements to write parameters to the model object. The `add_grid()` function here facilitates the creation of sampling grids. Using `add_emissions()` function anywhere in the pipeline will define emissions properties for one or more emitted pollutants. With `add_species()`, the physical properties and deposition parameters of one or more emitted species can be added to the model.\n\nAs with the trajectory model, the pipeline can ended with `run_model()`. To extract a data frame containing the modeled output data, use the `get_output_df()` function. An example is in order:\n\n```R\nlibrary(SplitR)\nlibrary(magrittr)\n\nsetwd(\"~/Documents/SplitR_wd\")\n\n# Create the `dispersion_model` object, add\n# a grid of starting locations, add run\n# parameters, and then execute the model run\ndispersion_model <-\n create_disp_model() %>%\n add_emissions(\n rate = 5,\n duration = 6,\n start_day = \"2015-07-01\",\n start_hour = 0) %>%\n add_species(\n pdiam = 1,\n density = 1,\n shape_factor = 1) %>%\n add_grid(\n range = c(0.5, 0.5),\n division = c(0.1, 0.1)) %>%\n add_params(\n lat = 49.0,\n lon = -123.0,\n height = 50,\n duration = 24,\n start_day = \"2015-07-01\",\n start_hour = 0,\n direction = \"forward\",\n met_type = \"reanalysis\") %>%\n run_model\n```\n\nThis dispersion model formally begins at 00:00 UTC on July 1, 2015 (using `start_day = \"2015-07-01\"` and `start_hour = 0`). The model run is a forward run (i.e., moving forward in time, with `direction = \"forward\"`) and not backwards (would be set as `direction = \"backward\"`). Essentially, running in forward mode means the starting location is a source of emissions; running backward means that the starting location is a receptor.\n\nThis run has been set to be modelled for 24 h (`duration = 24`). The starting location of 49.0ºN and 123.0ºW is set using `lat = 49.0` and `lon = -123.0`; the starting height of 50 m above ground level is set by `height = 50`. The meteorological options include the type of met data to use (global NCEP Reanalysis data is used here with `met_type = \"reanalysis`).\n\nA single emissions species is set to be emitted (using `add_emissions()`) for 6 hours (`duration = 6`) at an emission rate of 5 mass units per hour (`rate = 5`). Emissions begin at the same time as the start of the model (`start_day = \"2015-07-01\"` and `start_hour = 0`). The properties of the emitted pollutant are defined using `add_species()`. Here, the physical properties of particle diameter (in micrometers), density (in grams per cubic centimeter), and shape factor (value from 0 to 1), respectively, are defined with `pdiam = 1`, `density = 1`, and `shape_factor = 1`.\n\nIt should be noted that the order of `add_emissions()`, `add_species()`, `add_grid()`, and `add_params()` does not matter. There can even be several instances of each of these functions throughout the pipeline.\n\nAll meteorological data files needed to execute the model during the defined period will be downloaded from the **NOAA** FTP server if such files are not already present in the working directory.\n\nThe output data can be extracted from the dispersion model object...\n\n```R\n# Get a data frame containing the model results\ndispersion_df <-\n dispersion_model %>% get_output_df\n```\n\n...and the data is conveniently supplied as a **dplyr** `tbl`:\n\n```R\ndispersion_df\n#> Source: local data frame [54,063 x 5]\n#> \n#> particle_no lon lat height hour\n#> (int) (dbl) (dbl) (dbl) (int)\n#> 1 1 -122.8368 48.9499 711 1\n#> 2 2 -122.8419 48.9311 780 1\n#> 3 3 -122.8531 48.9108 848 1\n#> 4 4 -122.8401 48.9365 647 1\n#> 5 5 -122.8472 48.9389 124 1\n#> 6 6 -122.8124 48.9449 10 1\n#> 7 7 -122.8263 48.9316 935 1\n#> 8 8 -122.8144 48.9631 265 1\n#> 9 9 -122.8313 48.9465 278 1\n#> 10 10 -122.8105 48.9326 250 1\n#> .. ... ... ... ... ...\n```\n\n#### Plotting Dispersion Data\n\nDispersion data can also be plotted onto a map. Use the `dispersion_plot()` function with the dispersion model object.\n\n```R\nlibrary(SplitR)\nlibrary(magrittr)\n\n# Plot particle data onto a map\ndispersion_model %>% dispersion_plot\n```\n\nThe visualization will appear in the **RStudio** Viewer:\n\n

\n\nThe dispersed particles at every hour are present as map layers, where their visibility can be toggled using the *Layers* icon at the top-right of the view.\n\n## Installation\n\n**SplitR** is used in an **R** environment. If you don't have an **R** installation, it can be obtained from the [**Comprehensive R Archive Network (CRAN)**](http://cran.rstudio.com). It is recommended that [**RStudio**](http://www.rstudio.com/products/RStudio/) be used as the **R** IDE to take advantage of its ability to visualize output in its *Viewer* pane.\n\nYou can install the development version of **SplitR** from **GitHub** using the **devtools** package.\n\n```r\ndevtools::install_github('rich-iannone/SplitR')\n```","jobInfo":{"package":"splitr","version":"v0.4","parsingStatus":"success","parserVersion":1,"parsedAt":"2020-04-19T05:30:30+0000"}}

Description

Usage

Arguments