jointPeaks: Construct Joint Peak Object and Empirical Probabilities

In MGBT: Multiple Grubbs-Beck Low-Outlier Test

Construct Joint Peak Object and Empirical Probabilities

Description

Construct a joint peak object by retrieval of peak streamflows for two sites and joining the union of the peaks by water year and create empirical probabilities of the bivariate relation. This function is especially helpful when one is studying joint probabilities in peaks.

Usage

jointPeaks(Asite_no="--", Bsite_no="--", appearsSystematic=FALSE, a=0,
           Adf=NULL, Bdf=NULL, ...)

Arguments

Asite_no	The “A site” (think horizontal axis) siteNumber (dataRetrieval parlance) and usually required for this function as a character identifier of a streamgage and is usually an 8 digit number (USGS data tables use site_no as the column title). The default is deliberate to provide flexibility if Adf is provided;
Bsite_no	The “B site” (think horizontal axis) siteNumber (dataRetrieval parlance) and usually required for this function as a character identifier of a streamgage and is usually an 8 digit number (USGS data tables use site_no as the column title). The default is deliberate to provide flexibility if Bdf is provided;
appearsSystematic	Whereas one might want only to do the univariate marginal distributional analysis and not rely on non-systematic record without more sophisticated analysis methods of censored information, a decision is made to have the default for this argument false so as to maximize information into the deep tail of the bivariate relation between the peaks at the two sites. Remember that if copulas were to be used in analyses of the joint distribution that such operations are in probability space and not the real space of the analysis. We think better deep-tail information is available if the default is false. See also the splitPeakCodes function for more information on appearsSystematic;
a	A value for the plotting-position formula from package lmomco pp function, default is a = 0, which returns the Weibull plotting positions;
Adf	An optional data frame of “peaks” to supercede the retrieval of peaks. This feature is useful if a user want to inject another quantity, such as flood volume, into this function. The Adf is required to have a water_yr, peak_dt, peak_va, appearsSystematic, and nwiscda_sqmi or columns not actually needed such as the user could also provide dev_lat_va, dev_long_va;
Bdf	An optional data frame of “peaks” to supercede the retrieval of peaks. This feature is useful if a user want to inject another quantity, such as flood volume, into this function. The Bdf is required to have a water_yr, peak_dt, peak_va, appearsSystematic, and nwiscda_sqmi or columns not actually needed such as the user could also provide dev_lat_va, dev_long_va; and
...	Other arguments to pass (if ever needed).

Value

A list is returned with elements:

Asite_no	Data frame of the entire period of record for the Asite_no streamgage after the splitPeakCodes call with the addition of decimal latitude and longitude values and the contributing drainage area from the attribution information from the dataRetrieval::readNWISpeak();
Bsite_no	Data frame of the entire period of record for the Bsite_no streamgage after the splitPeakCodes call with the addition of decimal latitude and longitude values and the contributing drainage area from the attribution information from the dataRetrieval::readNWISpeak();
AB	Data frame as the joint peak object containing the pairwise matches in peaks and influenced or not by appearsSystematic argument. The data frame contains the water_yr (USGS definition of October 1 through September and numbered by the year for which it ends), both site numbers (Asite_no, Bsite_no), the contributing drainage areas from USGS database (Anwiscda_sqmi, Bnwiscda_sqmi), the date of the peaks (Apeak_dt, Bpeak_dt) (as character to thus support incomplete dates but still retained to maximize pair-wise peak counts), the peak values (Apeak_va, Bpeak_va), absolute number of days in the water year between the peaks (absdays_between_pks), nonexceedance probabilities by plotting position between the peaks (these are useful for bivariate copula analyses) (U [site A], V [site B]), and a cex column of a scaled symbol size based on the absdays_between_pks. The cex have a minimum of 1 and maximum of 2 and if the days between peak is NA, the cex is set to 0.9. This preprocessing to have the cex makes it easier for the user to produce diagnostic plots.

Author(s)

W.H. Asquith

Source

Original R by WHA for this package.

See Also

splitPeakCodes

Examples

## Not run: 
AB <- jointPeaks("08167000", "08167500") # 
## End(Not run)

MGBT documentation built on Oct. 5, 2026, 9:07 a.m.