# Introduction to pRecipe

#### Mijael Rodrigo Vargas Godoy, Yannis Markonis

#### 2025-04-02

`pRecipe` was conceived back in 2020 as part of MRVG’s doctoral dissertation at the Faculty of Environmental Sciences, Czech University of Life Sciences Prague, Czechia. Designed with reproducible science in mind, `pRecipe` facilitates the download, exploration, visualization, and analysis of multiple precipitation data products across various spatiotemporal scales (Vargas Godoy and Markonis 2023).

~The Global Water Cycle Budget | Vargas Godoy et al. (2021)

“Like civilization and technology, our understanding of the global water cycle has been continuously evolving, and we have adapted our quantification methods to better exploit new technological resources. The accurate quantification of global water fluxes and storage is crucial in studying the global water cycle.”

# Before We Start

Like many other R packages, `pRecipe` has some system requirements:

- PROJ
- Geospatial Data Abstraction Library (GDAL)
- Network Common Data Form (NetCDF)

# Data

`pRecipe` database hosts 27 different precipitation datasets; six gauge-based, eight satellite-based, eight reanalysis, and five hydrological model precipitation products. Their specifications as available in the database, as well as links to their providers, and their respective references are detailed in the following subsections. We have already homogenized, compacted to a single file, and stored them in Zenodo repositories under the following naming convention:

`<dataset>-<version>_<variable>_<units>_<coverage>_<start date>_<end date>_<resolution>_<time step>.nc`

The `pRecipe` data collection was homogenized to these specifications:

- `<variable>` = total precipitation (tp)
- `<units>` = millimeters (mm)
- `<resolution>` = 0.25°

E.g., Daily GPCP v3.2 (Adler et al. 2018) would be:

`gpcp-v3-2_tp_mm_global_197901_202109_025_daily.nc`

## Gauge-Based Products

Dataset | Spatial Coverage | Highest Temporal Resolution Available | Record Length | Get Data | Reference
--- | --- | --- | --- | --- | ---
CPC-Global | Land | Daily | 1979/01-2023/09 | Download | P. Xie, Chen, and Shi (2010)
CRU TS v4.08 | Land | Monthly | 1901/01-2023/12 | Download | Harris et al. (2020)
EM-Earth | Land | Daily | 1950/01-2019/12 | Download | Tang, Clark, and Papalexiou (2022)
GHCN v2 | Land | Monthly | 1900/01-2015/05 | Download | Peterson and Vose (1997)
GPCC v2022 | Land | Daily | 1891/01-2020/10 | Download | Schneider et al. (2011)
PREC/L | Land | Monthly | 1948/01-2024/10 | Download | Chen et al. (2002)

## Satellite-Based Products

Dataset | Spatial Coverage | Highest Temporal Resolution Available | Record Length | Get Data | Reference
--- | --- | --- | --- | --- | ---
CHIRPS v2.0 | Land 50°SN | Daily | 1981/01-2023/08 | Download | Funk et al. (2015)
CMAP | Global | Monthly | 1979/01-2024/10 | Download | Pingping Xie and Arkin (1997)
CMORPH-CDR | Global 60°SN | Daily | 1998/01-2023/04 | Download | Joyce et al. (2004)
GPCP v3.2 | Global | Daily | 1979/01-2021/09 | Download | Adler et al. (2018)
GPM IMERGM Final v07 | Global | Daily | 1998/01-2024/06 | Download | Huffman et al. (2019)
GSMaP v8 | Global | Daily | 1998/01-2023/06 | Download | Kubota et al. (2020)
MSWEP v2.8 | Global | Daily | 1979/01-2024/11 | Download | Beck et al. (2019)
PERSIANN-CDR | Global 60°SN | Daily | 1983/01-2023/12 | Download | Ashouri et al. (2015)

## Reanalysis Products

Dataset | Spatial Coverage | Highest Temporal Resolution Available | Record Length | Get Data | Reference
--- | --- | --- | --- | --- | ---
20CR v3 | Global | Daily | 1836/01-2015/12 | Download | Slivinski et al. (2019)
ERA-20C | Global | Daily | 1900/01-2010/12 | Download | Poli et al. (2016)
ERA5 | Global | Monthly | 1959/01-2021/12 | Download | Hersbach et al. (2020)
ERA5-Land | Land | Monthly | 1959/01-2021/12 | Download | Muñoz-Sabater et al. (2021)
JRA-55 | Global | Daily | 1958/01-2023/09 | Download | Kobayashi et al. (2015)
MERRA-2 | Global | Daily | 1980/01-2024/10 | Download | Gelaro et al. (2017)
NCEP/NCAR R1 | Global | Daily | 1948/01-2023/12 | Download | Kalnay et al. (1996)
NCEP/DOE R2 | Global | Daily | 1979/01-2023/12 | Download | Kanamitsu et al. (2002)

## Hydrological Model Forcing

Dataset | Spatial Coverage | Highest Temporal Resolution Available | Record Length | Get Data | Reference
--- | --- | --- | --- | --- | ---
FLDAS | Land | Monthly | 1982/01-2024/10 | Download | McNally et al. (2017)
GLDAS CLSM v2.0 | Land | Daily | 1948/01-2014/12 | Download | Rodell et al. (2004)
GLDAS NOAH v2.0 | Land | Monthly | 1948/01-2014/12 | Download | Rodell et al. (2004)
GLDAS VIC v2.0 | Land | Monthly | 1948/01-2014/12 | Download | Rodell et al. (2004)
TerraClimate | Land | Monthly | 1958/01-2023/12 | Download | Abatzoglou et al. (2018)

# Introduction to pRecipe

In this introductory demo we will first download the GPM-IMERGM dataset. We will then subset the downloaded data over South America for the 2001-2015 period, and crop it to the national scale for Bolivia. In the next step, we will generate time series for our datasets and conclude with the visualization of our data.

NOTE: While the functions in `pRecipe` are intended to work directly with its data inventory. `pRecipe` can handle most other datasets in “.nc” format, as well as any other “.nc” file generated by its functions.

## Installation

    install.packages('pRecipe')
    library(pRecipe)

## Data Download

Downloading the entire data collection or only a few datasets is quite straightforward. You just call the `download_data` function, which has four arguments dataset, path, domain, and timestep.

- dataset is set to “all” by default, but you can specify the names of your datasets of interest only.
- path is set to “.” by default. I.e., the current working directory. By replacing it for [your_project_folder], the downloaded files will be stored in [your_project_folder] instead.
- domain is set to “raw” by default, but you can specify the domain of your interest only. E.g., “ocean” for ocean only datasets (For availability please check the Data section).
- timestep is set to “monthly” by default, but if you prefer you can also download annual data with “yearly”.

Let’s download the GPM-IMERGM dataset and inspect its content with `infoNC`:

    download_data(dataset = 'gpm-imerg')
    gpm_global <- raster::brick('gpm-imerg-v7_tp_mm_global_199801_202406_025_monthly.nc')
    infoNC(gpm_global)

    [1] "class      : RasterBrick "
    [2] "dimensions : 720, 1440, 1036800, 318  (nrow, ncol, ncell, nlayers)"
    [3] "resolution : 0.25, 0.25  (x, y)"
    [4] "extent     : -180, 180, -90, 90  (xmin, xmax, ymin, ymax)"
    [5] "crs        : +proj=longlat +datum=WGS84 +no_defs "
    [6] "source     : gpm-imerg_tp_mm_global_200006_202012_025_monthly.nc "
    [7] "names      : X1998.01.01, X1998.02.01, X1998.03.01, X1998.04.01, X1998.05.01, X1998.06.01, X1998.07.01, X1998.08.01, X1998.09.01, X1998.10.01, X1998.11.01, X1998.12.01, X1999.01.01, X1999.02.01, X1999.03.01, ... "
    [8] "Date/time  : 1998-01-01, 2024-06-01 (min, max)"
    [9] "varname    : tp "

## Processing

Once we have downloaded our database, we can start processing the data with:

- `crop_data` to crop the data using a shapefile.
- `fldmean` to generate a time series by taking the area weighted average over each timestep.
- `remap` to go from the native resolution (0.25°) to coarser ones (e.g., 0.5°, 1°, 1.5°, …).
- `subset_data` to subset the data in time and/or space.
- `yearstat` to aggregate the data from monthly into annual.

### Subset

To subset our data to a desired region and period of interest, we use the `subset_data` function, which has three arguments x, box, and yrs.

- x Raster* object or a data.table or a filename (character).
- box is the bounding box of the region of interest with the coordinates in degrees in the form (xmin, xmax, ymin, ymax).
- yrs is the period of interest with years in the form (start_year, end_year).

Let’s subset the GPM-IMERGM dataset over South America (-96, -30, -56, 24) for the 2001-2020 period, and inspect its content with `infoNC`:

    gpm_subset <- subset_data(gpm_global, box = c(-96, -30, -56, 24), yrs = c(2001, 2020))
    infoNC(gpm_subset)

    [1] "class      : RasterBrick "
    [2] "dimensions : 320, 264, 84480, 240  (nrow, ncol, ncell, nlayers)"
    [3] "resolution : 0.25, 0.25  (x, y)"
    [4] "extent     : -96, -30, -56, 24  (xmin, xmax, ymin, ymax)"
    [5] "crs        : +proj=longlat +datum=WGS84 +no_defs "
    [6] "source     : r_tmp_2024-12-05_204859.40679_5927_83505.grd "
    [7] "names      :  X2001.01.01,  X2001.02.01,  X2001.03.01,  X2001.04.01,  X2001.05.01,  X2001.06.01,  X2001.07.01,  X2001.08.01,  X2001.09.01,  X2001.10.01,  X2001.11.01,  X2001.12.01,  X2002.01.01,  X2002.02.01,  X2002.03.01, ... "
    [8] "min values :           0,           0,           0,           0,           0,           0,           0,           0,           0,           0,           0,           0,           0,           0,           0, ... "
    [9] "max values :    877.0017,    830.7960,    926.5452,    879.0210,   1614.3760,   1347.4813,   1298.2778,   1030.6008,   2121.5745,   1154.9041,   1012.2653,    937.1544,    983.7074,    828.4057,    712.0858, ... "
    [10] "time       : 2001-01-01, 2020-12-01 (min, max)"

### Crop

To further crop our data to a desired polygon other than a rectangle, we use the `crop_data` function, which has two arguments x, and y.

- x Raster* object or a data.table or a *.nc filename (character).
- y is a “.shp” filename (character).

Let’s crop our GPM-IMERG subset to cover only Bolivia with the respective shape file, and inspect its content with `infoNC`:

    gpm_bol <- crop_data(gpm_subset, "gadm41_BOL_0.shp")
    infoNC(gpm_bol)

    [1] "class      : RasterBrick "
    [2] "dimensions : 54, 50, 2700, 180  (nrow, ncol, ncell, nlayers)"
    [3] "resolution : 0.25, 0.25  (x, y)"
    [4] "extent     : -69.75, -57.25, -23, -9.5  (xmin, xmax, ymin, ymax)"
    [5] "crs        : +proj=longlat +datum=WGS84 +no_defs "
    [6] "source     : memory"
    [7] "names      :  X2001.01.01,  X2001.02.01,  X2001.03.01,  X2001.04.01,  X2001.05.01,  X2001.06.01,  X2001.07.01,  X2001.08.01,  X2001.09.01,  X2001.10.01,  X2001.11.01,  X2001.12.01,  X2002.01.01,  X2002.02.01,  X2002.03.01, ... "
    [8] "min values : 2.402562e+01, 4.327217e+01, 8.482053e+00, 9.562346e-01, 3.222862e-02, 0.000000e+00, 0.000000e+00, 5.553878e-03, 1.055679e-02, 4.221552e-02, 2.083128e-01, 8.674479e+00, 2.208736e+00, 1.188102e+01, 6.304548e+00, ... "
    [9] "max values :    512.37097,    585.90833,    509.95139,    418.54199,    243.92047,    124.44180,    201.84206,    109.64172,    167.08734,    303.71823,    439.69751,    497.84958,    485.17444,    565.73810,    572.18994, ... "
    [10] "time       : 2001-01-01, 2020-12-01 (min, max)"

### Generate Time series

To make a time series out of our data, we use the `fldmean` function, which has one argument x.

- x Raster* object or a data.table or a *.nc filename (character).

Let’s generate the time series for our three different GPM-IMERGM datasets (Global, South America, and Bolivia), and inspect its first 12 rows:

    gpm_global_ts <- fldmean(gpm_global)
    head(gpm_global_ts, 12)

              date    value
            <Date>    <num>
     1: 1998-01-01 82.64305
     2: 1998-02-01 78.81371
     3: 1998-03-01 87.46418
     4: 1998-04-01 86.26875
     5: 1998-05-01 89.34600
     6: 1998-06-01 83.88119
     7: 1998-07-01 87.55151
     8: 1998-08-01 87.38290
     9: 1998-09-01 82.47541
    10: 1998-10-01 82.77823
    11: 1998-11-01 80.51179
    12: 1998-12-01 85.23061

    gpm_subset_ts <- fldmean(gpm_subset)
    head(gpm_subset_ts, 12)

              date     value
            <Date>     <num>
     1: 2001-01-01  95.95988
     2: 2001-02-01  85.44723
     3: 2001-03-01 108.46433
     4: 2001-04-01  99.11680
     5: 2001-05-01 114.35870
     6: 2001-06-01  87.50668
     7: 2001-07-01  95.68529
     8: 2001-08-01  84.40069
     9: 2001-09-01  90.51047
    10: 2001-10-01 104.37209
    11: 2001-11-01  98.31326
    12: 2001-12-01 107.36328

    gpm_bol_ts <- fldmean(gpm_bol)
    head(gpm_bol_ts, 12)

              date     value
            <Date>     <num>
     1: 2001-01-01 218.27810
     2: 2001-02-01 177.55739
     3: 2001-03-01 154.74973
     4: 2001-04-01  82.46497
     5: 2001-05-01  56.24647
     6: 2001-06-01  23.71866
     7: 2001-07-01  27.05753
     8: 2001-08-01  17.00265
     9: 2001-09-01  51.99784
    10: 2001-10-01  94.54848
    11: 2001-11-01 151.14781
    12: 2001-12-01 153.45496

## Visualize

Either after we have processed our data as required or right after downloaded, we have different options to visualize our data:

- `plot_box` to see a seasonal boxplot.
- `plot_density` to see the empirical density of monthly precipitation.
- `plot_heatmap` to see a heatmap of all monthly values.
- `plot_line` to see the average time series.
- `plot_map` to see the Cartesian lon-lat map of the first raster layer.
- `plot_summary` to see line, heatmap, box, and density plot together in a single plot.
- `plot_taylor` to see a Taylor Diagram (requires a referential dataset).

Let’s plot our three different GPM-IMERGM datasets (Global, South America, and Bolivia)

### Maps

To see a map of any dataset raw or processed, we use `plot_map`.

    plot_map(gpm_global)

    plot_map(gpm_subset)

    plot_map(gpm_bol)

### Time Series Visuals

#### Line

    plot_line(gpm_global_ts)

    plot_line(gpm_subset_ts)

    plot_line(gpm_bol_ts)

#### Heatmap

    plot_heatmap(gpm_global_ts)

    plot_heatmap(gpm_subset_ts)

    plot_heatmap(gpm_bol_ts)

#### Boxplot

    plot_box(gpm_global_ts)

    plot_box(gpm_subset_ts)

    plot_box(gpm_bol_ts)

#### Density

    plot_density(gpm_global_ts)

    plot_density(gpm_subset_ts)

    plot_density(gpm_bol_ts)

#### Summary

    plot_summary(gpm_global_ts)
    #plot_summary(gpm_subset_ts)
    #plot_summary(gpm_cz_ts)

# Coming Soon

More functions for data processing and analysis.

# Citation

If you acquire precipitation data products from `pRecipe`, we ask that you acknowledge us in your use of the data. We would also appreciate receiving a copy of the relevant publications. This will help pRecipe to justify keeping the data freely available online in the future. Thank you!

# References

Abatzoglou, John T, Solomon Z Dobrowski, Sean A Parks, and Katherine C Hegewisch. 2018. “TerraClimate, a High-Resolution Global Dataset of Monthly Climate and Climatic Water Balance from 1958–2015.” Scientific Data 5 (1): 1–12.
Adler, Robert F., Mathew R. P. Sapiano, George J. Huffman, Jian-Jian Wang, Guojun Gu, David Bolvin, Long Chiu, et al. 2018. “The Global Precipitation Climatology Project (GPCP) Monthly Analysis (New Version 2.3) and a Review of 2017 Global Precipitation.” Atmosphere 9 (4): 138. https://doi.org/10.3390/atmos9040138.
Ashouri, Hamed, Kuo-Lin Hsu, Soroosh Sorooshian, Dan K. Braithwaite, Kenneth R. Knapp, L. Dewayne Cecil, Brian R. Nelson, and Olivier P. Prat. 2015. “PERSIANN-CDR: Daily Precipitation Climate Data Record from Multisatellite Observations for Hydrological and Climate Studies.” Bulletin of the American Meteorological Society 96 (1): 69–83.
Beck, Hylke E, Eric F Wood, Ming Pan, Colby K Fisher, Diego G Miralles, Albert IJM Van Dijk, Tim R McVicar, and Robert F Adler. 2019. “MSWEP V2 Global 3-Hourly 0.1 Precipitation: Methodology and Quantitative Assessment.” Bulletin of the American Meteorological Society 100 (3): 473–500.
Chen, Mingyue, Pingping Xie, John E. Janowiak, and Phillip A. Arkin. 2002. “Global Land Precipitation: A 50-Yr Monthly Analysis Based on Gauge Observations.” Journal of Hydrometeorology 3 (3): 249–66.
Funk, Chris, Pete Peterson, Martin Landsfeld, Diego Pedreros, James Verdin, Shraddhanand Shukla, Gregory Husak, et al. 2015. “The Climate Hazards Infrared Precipitation with Stations—a New Environmental Record for Monitoring Extremes.” Scientific Data 2 (1): 150066. https://doi.org/10.1038/sdata.2015.66.
Gelaro, Ronald, Will McCarty, Max J. Suárez, Ricardo Todling, Andrea Molod, Lawrence Takacs, Cynthia A. Randles, et al. 2017. “The Modern-Era Retrospective Analysis for Research and Applications, Version 2 (MERRA-2).” Journal of Climate 30 (14): 5419–54. https://doi.org/10.1175/JCLI-D-16-0758.1.
Harris, Ian, Timothy J Osborn, Phil Jones, and David Lister. 2020. “Version 4 of the CRU TS Monthly High-Resolution Gridded Multivariate Climate Dataset.” Scientific Data 7 (1): 1–18.
Hersbach, Hans, Bill Bell, Paul Berrisford, Shoji Hirahara, András Horányi, Joaquín Muñoz-Sabater, Julien Nicolas, et al. 2020. “The ERA5 Global Reanalysis.” Quarterly Journal of the Royal Meteorological Society 146 (730): 1999–2049.
Huffman, G. J., E. F. Stocker, D. T. Bolvin, E. J. Nelkin, and Jackson Tan. 2019. GPM IMERG Final Precipitation L3 1 Month 0.1 Degree x 0.1 Degree V06, Greenbelt, MD, Goddard Earth Sciences Data and Information Services Center (GES DISC).
Joyce, Robert J, John E Janowiak, Phillip A Arkin, and Pingping Xie. 2004. “CMORPH: A Method That Produces Global Precipitation Estimates from Passive Microwave and Infrared Data at High Spatial and Temporal Resolution.” Journal of Hydrometeorology 5 (3): 487–503.
Kalnay, Eugenia, Masao Kanamitsu, Robert Kistler, William Collins, Dennis Deaven, Lev Gandin, Mark Iredell, Suranjana Saha, Glenn White, and John Woollen. 1996. “The NCEP/NCAR 40-Year Reanalysis Project.” Bulletin of the American Meteorological Society 77 (3): 437–72.
Kanamitsu, Masao, Wesley Ebisuzaki, Jack Woollen, Shi-Keng Yang, J. J. Hnilo, M. Fiorino, and G. L. Potter. 2002. “Ncep–Doe Amip-Ii Reanalysis (r-2).” Bulletin of the American Meteorological Society 83 (11): 1631–44.
Kobayashi, Shinya, Yukinari Ota, Yayoi Harada, Ayataka Ebita, Masami Moriya, Hirokatsu Onoda, Kazutoshi Onogi, et al. 2015. “The JRA-55 Reanalysis: General Specifications and Basic Characteristics.” Journal of the Meteorological Society of Japan. Ser. II 93 (1): 5–48. https://doi.org/10.2151/jmsj.2015-001.
Kubota, Takuji, Kazumasa Aonashi, Tomoo Ushio, Shoichi Shige, Yukari N. Takayabu, Misako Kachi, Yoriko Arai, et al. 2020. “Global Satellite Mapping of Precipitation (GSMaP) Products in the GPM Era.” In Satellite Precipitation Measurement: Volume 1, edited by Vincenzo Levizzani, Christopher Kidd, Dalia B. Kirschbaum, Christian D. Kummerow, Kenji Nakamura, and F. Joseph Turk, 355–73. Cham: Springer International Publishing. https://doi.org/10.1007/978-3-030-24568-9_20.
McNally, Amy, Kristi Arsenault, Sujay Kumar, Shraddhanand Shukla, Pete Peterson, Shugong Wang, Chris Funk, Christa D. Peters-Lidard, and James P. Verdin. 2017. “A Land Data Assimilation System for Sub-Saharan Africa Food and Water Security Applications.” Scientific Data 4 (1): 170012. https://doi.org/10.1038/sdata.2017.12.
Muñoz-Sabater, Joaquı́n, Emanuel Dutra, Anna Agustı́-Panareda, Clément Albergel, Gabriele Arduini, Gianpaolo Balsamo, Souhail Boussetta, et al. 2021. “ERA5-Land: A State-of-the-Art Global Reanalysis Dataset for Land Applications.” Earth System Science Data 13 (9): 4349–83.
Peterson, Thomas C., and Russell S. Vose. 1997. “An Overview of the Global Historical Climatology Network Temperature Database.” Bulletin of the American Meteorological Society 78 (12): 2837–50.
Poli, Paul, Hans Hersbach, Dick P Dee, Paul Berrisford, Adrian J Simmons, Frédéric Vitart, Patrick Laloyaux, et al. 2016. “ERA-20C: An Atmospheric Reanalysis of the Twentieth Century.” Journal of Climate 29 (11): 4083–97.
Rodell, Matthew, P. R. Houser, U. E. A. Jambor, J. Gottschalck, K. Mitchell, C.-J. Meng, K. Arsenault, B. Cosgrove, J. Radakovich, and M. Bosilovich. 2004. “The Global Land Data Assimilation System.” Bulletin of the American Meteorological Society 85 (3): 381–94.
Schneider, Udo, Andreas Becker, Peter Finger, Anja Meyer-Christoffer, Bruno Rudolf, and Markus Ziese. 2011. “GPCC Full Data Reanalysis Version 6.0 at 0.5: Monthly Land-Surface Precipitation from Rain-Gauges Built on GTS-Based and Historic Data.” GPCC Data Rep., Doi 10.
Slivinski, Laura C, Gilbert P Compo, Jeffrey S Whitaker, Prashant D Sardeshmukh, Benjamin S Giese, Chesley McColl, Rob Allan, et al. 2019. “Towards a More Reliable Historical Reanalysis: Improvements for Version 3 of the Twentieth Century Reanalysis System.” Quarterly Journal of the Royal Meteorological Society 145 (724): 2876–2908.
Tang, Guoqiang, Martyn P. Clark, and Simon Michael Papalexiou. 2022. “EM-Earth: The Ensemble Meteorological Dataset for Planet Earth.” Bulletin of the American Meteorological Society 103 (4): E996–1018. https://doi.org/10.1175/BAMS-D-21-0106.1.
Vargas Godoy, Mijael Rodrigo, and Yannis Markonis. 2023. “pRecipe: A Global Precipitation Climatology Toolbox and Database.” Environmental Modelling & Software 165: 105711.
Vargas Godoy, Mijael Rodrigo, Yannis Markonis, Martin Hanel, Jan Kyselỳ, and Simon Michael Papalexiou. 2021. “The Global Water Cycle Budget: A Chronological Review.” Surveys in Geophysics 42 (5): 1075–1107.
Xie, P., M. Chen, and W. Shi. 2010. “CPC Global Unified Gauge-Based Analysis of Daily Precipitation.” In Preprints, 24th Conf. On Hydrology, Atlanta, GA, Amer. Metero. Soc. Vol. 2.
Xie, Pingping, and Phillip A. Arkin. 1997. “Global Precipitation: A 17-Year Monthly Analysis Based on Gauge Observations, Satellite Estimates, and Numerical Model Outputs.” Bulletin of the American Meteorological Society 78 (11): 2539–58.