Package 'Rainmaker'

Title: Rainfall event processing
Description: Rainmaker is a collection of functions used to process instantaneous rainfall data to define event rainfall depths, rainfall intensities, rainfall erosivity and antecedent rainfall values. Event definition can be determined solely within rainmaker using the instantaneous rainfall data or can be focused directly on dates and times of interest (for example, using specific water quality sampling periods).
Authors: Steve Corsi [aut, cre], Rebecca Carvin [aut]
Maintainer: Steve Corsi <[email protected]>
License: file LICENSE
Version: 1.0.2
Built: 2024-11-15 02:50:05 UTC
Source: https://github.com/USGS-R/Rainmaker

Help Index


Rainmaker

Description

Rainmaker is a collection of functions used to process instantaneous rainfall data to define event rainfall depths, rainfall intensities and antecedent rainfall values. Event definition can be determined solely within rainmaker using the instantaneous rainfall data or can be focused directly on dates and times of interest (for example, using specific water quality sampling periods).

Details

Package: Rainmaker
Type: Package
Version: 1.0.0
Date: 2014-01-10
License: Unlimited for this package, dependencies have more restrictive licensing.
Copyright: This software is in the public domain because it contains materials that originally came from the United States Geological Survey, an agency of the United States Department of Interior. For more information, see the official USGS copyright policy at http://www.usgs.gov/visual-id/credit_usgs.html#copyright
LazyLoad: yes

Collection of functions..

Author(s)

Steve Corsi [email protected]


cedarq

Description

Instantaneous values of flow from Cedar Creek

Author(s)

Steve Corsi [email protected]


CedarRRain

Description

Instantaneous values of rainfall from Cedar Creek

Author(s)

Steve Corsi [email protected]


cedarSamples

Description

Beginning and ending dates and times for composite samples collected at Cedar Creek. This information can be used to determine rainfall for specific time periods using RMeventsSamples.

Author(s)

Steve Corsi [email protected]


Calculate events from discharge record

Description

Discharge event determination - calculates event start and end times based on discharge record.

Usage

discharge_events(
  df,
  ieHr = 6,
  qthresh,
  discharge = "Value",
  time = "pdate",
  ieHr_check = TRUE
)

Arguments

df

dataframe that contains discharge and timestamps

ieHr

numeric, Interevent period in hours, defaults to 6. The amount of time between discharge measurements above threshold required to be considered a new event.

qthresh

numeric, Discharge threshold value, over which an event is considered to be occuring.

discharge

string, Column name where discharge values are stored. Defaults to "Value".

time

string, column name where dates are stored as POSIXct values, defaults to "pdate".

ieHr_check

logical, whether to check the calculated events data frame for events that are closer together than ieHr. This can happen due to the start and end time corrections for the "tails" of the event. If TRUE, events closer than ieHr apart will be combined. If FALSE, events will be left as-is. See the details section below for more information.

Details

When a discharge measurement is above qthresh, the algorthim decides whether it belongs to a "new" event by looking backwards at the last measurement above qthresh. If the difference in time is greater than ieHr, then a new event begins. The start and end times of each event, however, are adjusted to the previous or next timestamp, respectively, to account for the "tails" of the event. The consequence of adjusting the start and end times, however, is that depending on the frequency of discharge observations, two observations above qthresh that are greater than ieHr apart (and therefore in seperate events) can have start and end times that are closer together than ieHr. If ieHr_check = TRUE (default), the algorithm makes a final pass through the events dataset and checks for any events that are closer in time than ieHr. If so, it will combine those events. If ieHr_check = FALSE, the algorithm will leave the events as-is, and depending on discharge measurement frequency and ieHr, you may see events that are closer together than ieHr. In most use-cases, ieHr_check = TRUE is appropriate. However, if discharge measurements are infrequent, and the adjustment to the start and end times are significant, the user may not want the secondary filter on the events.

Value

dataframe of all discharge events based on ieHr and qthresh criteria. Includes start and end times for each event.


precip_05408480

Description

Precip sample data from site 05408480

Author(s)

Steve Corsi [email protected]


RMarf

Description

This function computes antecedent rainfall for Rainmaker event files or any file with a list of specified dates.

Input files must have a as.POSIXctformatted date/time column. This format can be achieved by using the RMprep function The name of the rainfall column can also be changed as desired using the RMprep funtion

Subset the data by antecedent time period (can also assign to a df if you like) then define ARF values for the subset. Do this for all date periods in the sample file.

Usage

RMarf(
  df,
  date = "date",
  rain = "rain",
  df.events,
  sdate = "StartDate",
  days = c(0.5, 1, 2, 3, 5, 10, 15, 20),
  varnameout = "ARF"
)

Arguments

df

dataframe Unit values rain file

date

string Date column name in df as POSIX

rain

string Column in df with instantaneous rain values

df.events

dataframe with dates/times for events

sdate

string Name of start date column in df.events rain file as POSIX

days

vector of times in days for summing antecedent rainfall

varnameout

string prefix for resulting antecedent rainfall variable names

Value

df.events dataframe

Examples

RDB <- CedarRRain
RDB2 <- RMprep(RDB,prep.type=1,date.type=1,dates.in="CST.Time",tz="CST6CDT")
RDB3 <- subset(RDB2,
 upload.ph3_site_basin_cedar_creek.Id.0....Geographical.Mean.kg.m.2.>-1)
event.list <- RMevents(df=RDB3,ieHr=6,
rainthresh=0.2,
rain="upload.ph3_site_basin_cedar_creek.Id.0....Geographical.Mean.kg.m.2.")
events.0.2 <- event.list$storms2
intensities <- RMintensity(RDB3,date="pdate",
rain="upload.ph3_site_basin_cedar_creek.Id.0....Geographical.Mean.kg.m.2.",
events.0.2,sdate="StartDate",edate="EndDate",depth="rain",xmin=c(5,15,30))
ARFrain <- RMarf(df = RDB3,
                 date = "pdate",
                 rain="upload.ph3_site_basin_cedar_creek.Id.0....Geographical.Mean.kg.m.2.",
                 df.events=intensities,sdate="StartDate",days=c(1,3,5),varnameout="ARF")

RMerosivity

Description

This function computes the erosive power of the rainfall

Usage

RMerosivity(df, ieHr, method, rain = "rain", StormSummary = StormSummary)

Arguments

df

dataframe with instantaneous rainfall and events calculated. This is the 'tipsbystorm' output from RMevents, or the third list component from the output of RMevents. This dataframe must include colums for rain values, dates, 'dif_time' or the time elapsed from one tip (row) to the next, and 'event' which numbers each row or tip by which event to which it belongs (starting at 1).

ieHr

time between events in hours

method

choose which energy equation to use (see below for more details)

rain

string, column name of rainfall unit values, defaults to "rain"

StormSummary

dataframe output by RMIntense

method=1: McGregor (1995) Supercedes Brown and Foster equation (1987), which superceded Agriculture Handbook 537 (1979).

method=2: Wischmeier, Agriculture Handbook 537 (1979, 1981), correct computation of formula 2 found in AH537

method=3: Original Rainmaker (1997) USGS Wisconsin Water Science Center, based on equation in Agriculture Handbook 537. Storms with I30>2.5 are incorrectly computed.

References

McGregor, K. C., R. L. Binger, A. J. Bowie, and G. R. Foster. 1995. Erosivity index values for northern Mississippi. Trans. Amer. Soc. Agric. Eng. 38:1039-1047;

Wischmeier, W. H. and D. D. Smith. 1978. Predicting rainfall erosion losses-A guide to conservation planning. U.S. Department of Agriculture, Agriculture Handbook 537, 58 pp.

Wischmeier, W. H. and D. D. Smith. 1981. Supplement and Errata for "Predicting rainfall erosion losses-A guide to conservation planning". U.S. Department of Agriculture, Agriculture Handbook 537, 58 pp.

Renard, K. G., G. R. Foster, G. A. Weesies, D. K. McCool, and D. C. Yoder. 1997. Predicting soil erosion by water: A guide to conservation planning with the Revised Soil Loss Equation (RUSLE). U.S. Department of Agriculture, Agriculture Handbook 703, 404 pp.


RMevents

Description

Compute rainfall event variables based on time series of rain data with only one rain gage or one mean radar rain column.

Usage

RMevents(df, ieHr = 6, rainthresh = 5.1, rain = "rain", time = "pdate")

Arguments

df

dataframe with rainfall

ieHr

numeric Interevent period in hours, defaults to 6,

rainthresh

numeric Minimum event depth in units of the rain column, default is given as 5.1 assuming millimeters (0.2")

rain

string Column name of rainfall unit values, defaults to "rain"

time

string column with as.POSIXctdate, defaults to "pdate"

Details

Rainfall event determination

Value

list of all rain events that surpass rainthresh (storms2) and all rain events (storms). Also returns all a data frame of all rain observations > 0 with the associated date/time and assigned event number (tipsbystorm) and the minimum time difference between observations (timeInterval)

Examples

RDB <- CedarRRain
RDB2 <- RMprep(RDB,
               prep.type = 1,
               date.type = 1,
               dates.in = "CST.Time",
               tz = "CST6CDT")
event.list <- RMevents(df = RDB2,
                       ieHr = 6,
                       rainthresh = 0.2,
                       rain = "upload.ph3_site_basin_cedar_creek.Id.0....Geographical.Mean.kg.m.2.")
events.0.2 <- event.list$storms2

RMevents_sample

Description

Compute rainfall event variables based on time series of rain data with only one rain gage or one mean radar rain column. The function does not calculate events based on the rain data itself (such as in RMevents), but rather calculates event variables based on an input of sample/event start and end times.

Usage

RMevents_sample(
  dfrain,
  ieHr = 6,
  rain = "rain",
  time = "pdate",
  dfsamples,
  bdate = "bpdate",
  edate = "epdate"
)

Arguments

dfrain

dataframe with rainfall

ieHr

numeric Interevent period in hours, defaults to 6,

rain

string Column name of rainfall unit values, defaults to "rain"

time

string column with as.POSIXctdate, defaults to "pdate"

dfsamples

dataframe with the beginning and ending dates and times of sampling periods in POSIXct format

bdate

character column name in dfsamples for the beginning of the sampling period

edate

character column name in dfsamples for the ending of the sampling period

Value

list of storms and storms2

Examples

RDB <- CedarRRain
cedarSamples <- cedarSamples
names(RDB)[2] <- "UVRain"
RDB2 <- RMprep(RDB,prep.type=1,date.type=1,
               dates.in="CST.Time",tz="CST6CDT")
eventListSamples <- RMevents_sample(df=RDB2,ieHr=6,
                                    rain="UVRain",
                                    time="pdate",
                                    dfsamples=cedarSamples,
                                    bdate="pSstart",edate="pSend")

RMevents.plot

Description

Function to graph rainfall for a given x-day window around specified event periods

Usage

RMevents.plot(
  df,
  date = "pdate",
  rain = "rain",
  df.events,
  sdate = "StartDate",
  edate = "EndDate",
  depth = "depth",
  plot.buffer = 3,
  site.name = ""
)

Arguments

df

dataframe with unit value rainfall data

date

string Date column in df as POSIX

rain

string Column in df with instantaneous rain values

df.events

dateframe with start and end dates/times for events

sdate

string Start date column in df.events rain file as POSIX

edate

string End date column in df.events rain file as POSIX

depth

string column in df.events with event rain depth

plot.buffer

numeric Used to define plotting window in days. Graphs will include data Time period preceding beginning of event for including in the graphs

site.name

string

Examples

RDB <- CedarRRain
RDB2 <- RMprep(RDB, prep.type = 1, date.type = 1,
               dates.in = "CST.Time", tz = "CST6CDT")
RDB3 <- subset(RDB2,
 upload.ph3_site_basin_cedar_creek.Id.0....Geographical.Mean.kg.m.2. > -1)
event.list <- RMevents(df=RDB3,
                       ieHr=6,
                       rainthresh=0.2,
rain="upload.ph3_site_basin_cedar_creek.Id.0....Geographical.Mean.kg.m.2.")
events.0.2 <- event.list$storms2
# pdf("events.pdf")
RMevents.plot(RDB3,date="pdate",
rain="upload.ph3_site_basin_cedar_creek.Id.0....Geographical.Mean.kg.m.2.",
df.events=events.0.2,sdate="StartDate","EndDate",depth= "rain",plot.buffer=2,
site.name="Example Site")
# dev.off()

RMevents.plotQ

Description

Function to graph rainfall and flow for a given x-day window around specified event periods

Usage

RMevents.plotQ(
  df,
  dfQ,
  date = "pdate",
  Qdate = "pdate",
  rain = "rain",
  Q = "Q",
  df.events,
  sdate = "StartDate",
  edate = "EndDate",
  erain = "depth",
  plot.buffer = 3,
  logy = "",
  site.name = "",
  SampleInfo,
  sampbdate = "",
  sampedate = ""
)

Arguments

df

dataframe with unit value rainfall data

dfQ

dataframe with unit value Q data

date

string Date column in df as POSIXct

Qdate

string Date column in dfQ as POSIXct

rain

string Column in df with instantaneous rain values

Q

string Column in dfQ with instantaneous Q values

df.events

dataframe with start and end dates/times for events

sdate

string Start date column in df.events rain file as POSIXct

edate

string End date column in df.events as POSIXct

erain

string Event rainfall depth column in df.events

plot.buffer

numeric Used to define plotting window in days. Graphs will include

logy

string "y" if log y-axis for Q or "" if linear axis. Will default to "".

site.name

site name as data type character

SampleInfo

if TRUE then sample start and end dates/times are plotted on the hydrograph; if FALSE then sample start and end dates/times are not plotted on the hydrograph.

sampbdate

character column name in df.events for the beginning of the sampling period

sampedate

character column name in df.events for the ending of the sampling period

Value

plots of rainfall events and discharge

Examples

#Example 1 - Rainfall/Q plots without sample start/end arrows
RDB <- CedarRRain
dfQ <- cedarq
dfQ <- RMprep(dfQ,prep.type=1,date.type=3,tz="CST6CDT")
RDB2 <- RMprep(RDB,prep.type=1,date.type=1,dates.in="CST.Time",tz="CST6CDT")
RDB3 <- subset(RDB2,
upload.ph3_site_basin_cedar_creek.Id.0....Geographical.Mean.kg.m.2.>-1)
event.list <- RMevents(df=RDB3,ieHr=6,rainthresh=0.2,
rain="upload.ph3_site_basin_cedar_creek.Id.0....Geographical.Mean.kg.m.2.")
events.0.2 <- event.list$storms2
site.name <- "Example Site"
SampleInfo <- FALSE

RMevents.plotQ(RDB3,dfQ,
rain="upload.ph3_site_basin_cedar_creek.Id.0....Geographical.Mean.kg.m.2.",
df.events=events.0.2,erain="rain",
site.name=site.name,SampleInfo=SampleInfo)

#Example 2- Rainfall/Q plots with sample start/end arrows
RDB <- CedarRRain
cedarSamples <- cedarSamples
names(RDB)[2] <- "UVRain"
RDB2 <- RMprep(RDB,
               prep.type=1,
               date.type=1,
               dates.in="CST.Time",
               tz="CST6CDT")
eventListSamples <- RMevents_sample(df=RDB2,
                                    ieHr=6,
                                    rain="UVRain",
                                    time="pdate",
                                    dfsamples=cedarSamples,
                                    bdate="pSstart",edate="pSend")
dfQ <- cedarq
dfQ <- RMprep(dfQ,prep.type=1,date.type=3,tz="CST6CDT")
site.name <- "Example Site"
SampleInfo <- TRUE
sampbdate <- "pSstart"
sampedate <- "pSend"
#RMevents.plotQ(RDB2,
#                dfQ,
#                rain="UVRain",
#                df.events=eventListSamples,
#                sdate="Braindate",
#                edate="Eraindate",
#                erain="depth",logy="",site.name=site.name,
#                sampbdate="pSstart",sampedate="pSend")

RMintensity

Description

Function to compute maximum x-minute rainfall intensities in units of depth/hr

Usage

RMintensity(
  df,
  date = "r.date",
  rain = "rain",
  df.events,
  sdate = "StartDate",
  edate = "EndDate",
  depth = "depth",
  xmin = c(60, 180, 360)
)

Arguments

df

dataframe

date

string Date column name in df as POSIX

rain

string Column name in df with instantaneous rain values

df.events

dateframe with start and end dates/times for events

sdate

string Start date column in df.events rain file as POSIX

edate

string End date column in df.events rain file as POSIX

depth

string rain depth in event file, defaults to "depth",

xmin

vector vector of values representing X-minute max rainfall requested

Value

df.events dataframe, X-hour maximum rainfall intensities

Examples

RDB <- CedarRRain
RDB2 <- RMprep(RDB,
               prep.type=1,
               date.type=1,
               dates.in="CST.Time",tz="CST6CDT")
RDB3 <- subset(RDB2,
upload.ph3_site_basin_cedar_creek.Id.0....Geographical.Mean.kg.m.2.>-1)
event.list <- RMevents(df=RDB3,
                       ieHr=6,
                       rainthresh=0.2,
rain="upload.ph3_site_basin_cedar_creek.Id.0....Geographical.Mean.kg.m.2.")
events.0.2 <- event.list$storms2
intensities <- RMintensity(RDB3,date="pdate",
rain="upload.ph3_site_basin_cedar_creek.Id.0....Geographical.Mean.kg.m.2.",
events.0.2,sdate="StartDate",edate="EndDate",depth="rain",xmin=c(5,15,30))

RMprep function

Description

This function is used to prepare data files for Rainmaker functions. Dates are transformed to as.POSIXctdates using the as.POSIXct function Multiple common date formats are included as options for tranformation The original date column is transformed to a character variable. Column header names are changed to desired names

Usage

RMprep(
  df,
  prep.type = 1,
  date.type = 1,
  dates.in = "default",
  dates.out = "pdate",
  cnames.in = "",
  cnames.new = "rain",
  tz = ""
)

Arguments

df

dataframe

prep.type

numeric 1=date to as.POSIXct 2=name change, 3=both

date.type

numeric 1=mm/dd/YYYY hh:mm, 2=YYYY-mm-ddTHH:MM, 3=RDB_example1: 2 columns, Date and Time Date=m/d/Y; time=h:mm, 4=RDB_example2: 4 columns, Year, Month, Day and Minute Date=m/d/Y; time=h:mm, 5=Lake level from Great Lakes "Tides and Currents", Date=YYYYMMDD; Time = H:MM

dates.in

string Vector of column names for date/time definition. Defaults are as follows for different date.type options date.type=1: One column name -> "GMT.Time", date.type=2: One column name -> "GMT.Time", date.type=3: two column names -> c("DATE","TIME"), date.type=4: four column names > c("YEAR","MONTH","DAY","MINUTE"), date.type=5: two column names -> c("Date","Time"), If no value is given, the defaults given above are used. Enter value as c("name1","name2",...)

dates.out

string Column name of output dates, defaults to 'pdate' which is used elsewhere in Rainmaker.

cnames.in

string Column names of the input data which should be changed.

cnames.new

string New column names for the columns specified in cnames.in.

tz

string time zone, CST6CDT for central time. For other times use values in the TZ* column here: http://en.wikipedia.org/wiki/List_of_zoneinfo_time_zones

Value

df dataframe

Examples

RDB <- cedarq
RDB2 <- RMprep(RDB,prep.type=1,date.type=3,tz="CST6CDT")
RDB <- CedarRRain
RDB2 <- RMprep(RDB,prep.type=1,date.type=1,dates.in="CST.Time",tz="CST6CDT")