Returnperiod user guide

Getting started: a first frequency curve in two minutes

Returnperiod fits frequency curves to flood peaks and rainfall maxima, builds rainfall intensity-duration-frequency (IDF) curves and design storms from your own rainfall data, and sizes reservoir storage from an inflow record. It runs entirely in your browser.

1. Press Examples in the top bar and choose Annual peaks, 68 years (systematic record). The data appear on the left.
2. Press Ctrl/Cmd + Enter (or Run). A log-Pearson III curve is fitted with the Expected Moments Algorithm described in USGS Techniques and Methods 4-B5 (Bulletin 17C).
3. On the right read the probability plot, the quantile table with confidence limits, the fitted parameters and the checks on the fit.
4. Change the return periods, the distribution or the plotting position on the left and run again. Choose another example for rainfall IDF curves, an NRCS-style 24-hour storm or a reservoir.
5. Save downloads a Returnperiod document (JSON). Your work is also autosaved in this browser.

To use your own data, paste one annual peak per line, or "year, value". Values must be numbers; lines that are not understood are reported above the plot.

The workspace

The left rail lists the four workflows. Each workflow has inputs on the left and results on the right; on a phone the two stack.

The top bar holds the document title, Examples, Open, Save, Run (or Cancel while a run is in progress) and the help button. The status bar shows whether the calculation runs in a background worker, the domain-gate status, whether the document is autosaved, and the professional-use notice.

Keyboard shortcuts

Everything can be done from the keyboard: the workflow list, the fields and the buttons are ordinary controls with visible focus.

Entering data

Annual peaks. One value per line, or "year, value" (comma, tab or space separated). A first line with column names is skipped. Zero is allowed (see low outliers). A third cell beginning with H marks a historic flood.

Historical or missing-record information. For a record with a historic period or gaps, enter the length of that period in years and the perception threshold: the flow that any flood in that period would have exceeded to be noticed. Mark the floods above the threshold that you do have with H. The remaining years of that period are treated as "no flood above the threshold". The Back Creek example shows a broken record described this way.

Dated series. Paste "YYYY-MM-DD, value" rows into Import a dated series and extract annual maxima for water years or calendar years, or peaks over a threshold with a minimum separation in days between independent events.

Partial duration series. Choose the series type, paste the event peaks, and enter the threshold and the length of record in years.

IDF table. The first row lists the durations in minutes; each following row is one year. An optional first column (year) is ignored.

Inflow and storm tables. One inflow value per line; the NRCS construction takes "minutes, depth" lines; a custom storm takes "time, cumulative fraction".

Limits keep the browser tab inside its memory budget: 5,000 values for a frequency analysis, 100,000 events for a partial duration series, 400,000 dated rows, 250,000 reservoir periods and 5,000 storm blocks. Larger inputs are refused with a message instead of crashing the tab.

Distributions and fitting methods

Methods: method of moments (log-Pearson III uses the sample mean, the n-1 standard deviation and the bias-adjusted skew of equations 5 to 7 of Bulletin 17C), L-moments (unbiased sample L-moments; shape found by solving for L-skewness), and maximum likelihood (closed form for the lognormal, a one-dimensional root for Gumbel, simplex search for GEV and Pearson III). The Pearson III likelihood search is limited to absolute skew below 2 so the likelihood stays bounded.

The Expected Moments Algorithm applies to log-Pearson III only and is described below. For the other distributions and methods, zero or negative values cannot be logged and are removed with a note.

The Bulletin 17C procedure

With Log-Pearson III and Expected Moments Algorithm selected, the tool follows the procedure of USGS Techniques and Methods 4-B5:

• User-set low-outlier threshold (default path). Enter a finite, positive discharge below the largest observation, in the displayed flow units. Observations strictly below it become flow intervals [0, threshold]; a peak equal to it stays exact. The perception floor is raised to that threshold, while higher historical thresholds remain in effect. Document the hydrological justification in the saved study and report. Bulletin 17C, printed p. 27, section “Zero Flows and Identifying Potentially Influential Low Floods,” allows an analyst-defined threshold where MGBT does not adequately identify PILFs, based on hydrological considerations, watershed knowledge and site characteristics, with a thoroughly documented justification. The Bulletin recommends MGBT for detection; choosing the manual path by default is this tool's policy. A blank threshold means no positive-flow screening, which is also a tool policy, not a Bulletin-prescribed default. Zero flows remain PILFs (p. 27); without a user threshold, only zeros are censored at the smallest positive systematic peak, with no automatic test of positive flows. At least three exactly known peaks must remain. EMA is still experimental and constrained fits are still refused, including Orestimba at its published 782 ft³/s threshold.
• Expected moments. Every year is a flow interval with a perception threshold. Known peaks are exact; years below a low-outlier threshold or years of a missing period are censored. The mean, standard deviation and skew are iterated using the incomplete-gamma expectations of censored years. The finite-sample factors in equations 7-2 and 7-3 are applied to the complete exact-plus-conditional moment sums, as printed on p. 80 and generalized in equation 7-15 on p. 83. This is a Bulletin-supported correction convention; the historical worked-example implementation uses exact-only corrections, so the Orestimba example is still not reproduced. With no censoring the result is the method of moments.
• Multiple Grubbs-Beck test. The outward sweep tests positive flows from the median downward at 0.5 percent. The inward sweep starts at full-record rank 1 at 10 percent and stops at its first failure (Bulletin 17C, p. 79). Zeros retain their ranks and are classified separately as low floods (p. 27). To evaluate inward stopping at zero ranks, the tool uses the limit of a common positive flow approaching zero in equations 6-1 to 6-3 (p. 78); this numerical convention is not specified by the Bulletin. The p-values are Monte Carlo estimates of the defining probability; the exact numerical integration of the original paper is not reproduced (see Limitations). Automatic detection still does not reproduce the published Orestimba count and threshold. You can switch the test off or enter your own threshold.
• Historical and missing records. Floods above the perception threshold outside the gaged record, and years known to have had no flood above it, enter through the threshold (see Entering data).
• Regional skew. Enter a regional skew and its mean square error (from a current regional study for your site). The station skew and the regional skew are weighted by their mean square errors (equation 7-20). By default, station-skew MSE uses the first-order asymptotic covariance method described in equations 7-21 to 7-30 (pp. 84-86). You may enter the value your regional study or software reports instead. The legacy regression that reproduces some published examples is a different method; neither choice establishes confidence-limit coverage.
• Skew limits. The skew is kept above about -1.41, and a negative skew is limited so the upper bound of the distribution stays above the largest observation.

If the regional and station skews differ by more than 0.5, look at the data and the watershed before relying on the weighted value, as the Guidelines advise.

Confidence limits

For log-Pearson III the limits use the normal approximation of equation 7-31, applied to the base-10 logarithm of each quantile: the limits are 10 raised to (estimate plus or minus z times the standard error). The variance of each quantile is derived by linearising the expected-moments estimating equations (the structure of equations 7-26 to 7-37 of the Guidelines) and includes the censoring thresholds and, when used, the uncertainty of the regional skew.

For GEV, Gumbel and lognormal, and as an option for log-Pearson III with other methods, parametric bootstrap limits are percentiles of quantiles from refits to samples drawn from the fitted distribution. The seed is fixed, so a run is repeatable.

The limits differ from the intervals printed in the published worked examples. Equations 7-33–7-34 give an improved interval form, but its covariance estimator and later refinements are not implemented here. Normal LP3 limits for MLE and L-moment fits reuse MOM covariance without independent coverage validation. Treat the limits as indicative.

Plotting positions and probability paper

The exceedance probability of the i-th largest of n values is (i - a) / (n + 1 - 2a). Weibull (a = 0) is the default of Bulletin 17C; Cunnane (0.40), Gringorten (0.44), Hazen (0.50) and Blom (0.375) are available. With historical information the tool uses the threshold-exceedance positions of appendix 5 (equations 5-1 and 5-2).

The plot has annual exceedance probability along the horizontal axis on a normal or Gumbel probability scale, with return periods along the top; the vertical axis is logarithmic or linear. Data points are open circles, historic floods are diamonds, the fitted curve is a solid line, other models you overlay are dashed, and the confidence limits are a shaded band. Export the plot as SVG or PNG.

Goodness of fit and checks

The results list the Kolmogorov-Smirnov distance, the Anderson-Darling statistic, the probability-plot correlation coefficient, the log-likelihood and AIC and BIC. Because the parameters are estimated from the same data, the usual tabulated critical values do not apply. Set a number of bootstrap replicates to obtain p-values by simulation from the fitted model.

A Checks panel reports built-in sanity checks on your own fit: finite parameters, quantiles that increase with return period, plotting positions inside 0 and 1, EMA convergence, the skew limit and whether the largest value is consistent with the fitted tail. A warning does not mean the fit is wrong; it points to something to look at.

Partial duration series

Events above a threshold arrive at a rate of lambda per year (events divided by the years of record), and the excess over the threshold follows an exponential or generalised Pareto distribution. The annual exceedance probability of a level x is 1 - exp(-lambda S(x)), with S the survival function of one event. The table gives the level for each partial-duration return period together with the equivalent annual-maximum return period, 1 / (1 - exp(-1 / T)).

Choose the threshold so events are independent and the excess model fits; the minimum separation in days in the series import helps with independence. The tool does not choose a threshold for you.

IDF curves from your rainfall data

Enter annual maximum depths (or intensities) for several durations. For each duration the chosen distribution and method give the depth at every return period. An IDF equation is then fitted by least squares on logarithms:

where i is the intensity (depth per hour), t the duration in minutes and T the return period in years. The curves and the equation are plotted on logarithmic axes. A warning appears if fitted depths decrease with duration. No rainfall-frequency atlas data are built in; the curves come only from the maxima you enter.

Design storms

Alternating block. Cumulative depths for durations of one step, two steps and so on come from the IDF equation. The increments are sorted; the largest takes the peak position (a fraction of the duration) and the others alternate before and after it. When the duration-depth increments are nonincreasing, the k largest blocks add up to the depth of duration k times the step; otherwise that nesting property does not hold.

NRCS 24-hour distribution from duration depths. Enter the depths for 5, 10, 15, 30, 60, 120, 180, 360, 720 and 1440 minutes for one return period. The tool builds the cumulative distribution at 0.1-hour steps by the procedure of section 630.0407 of the National Engineering Handbook, Part 630, chapter 4: the ratios to the 24-hour depth set break points around hour 12, quadratic curves join them, the distribution is symmetric about hour 12, and the value at hour 12 is adjusted with the 6-minute ratio. The tabulated Type I, IA, II and III distributions are not included (see Limitations).

Your own table. Paste time and cumulative fraction pairs; the table is resampled linearly.

Reservoir yield

The sequent peak algorithm accumulates the deficit K(t) = max(0, K(t-1) + demand + loss - inflow(t)) over the record repeated twice, so a critical period that runs past the end of the record is not missed. The largest deficit is the storage needed for that demand with no failure. Enter a storage capacity to also get its safe yield (the largest constant demand it can supply through the record) and a behaviour simulation that starts full and reports time reliability, volumetric reliability and the largest shortfall. The storage-yield curve gives the storage needed for fractions of the mean inflow.

The record is historical; it does not describe future droughts. For long-term reliability use a long record or a synthetic one.

Files and exports

Document file. Save writes a JSON file with the format name returnperiod-document and a version number; it keeps everything you typed as text, so it reopens exactly as left. The file carries a copyright and terms notice field. Open reads only files of this format.

Exports. Probability plot, IDF chart, hyetograph and storage-yield chart as SVG; the probability plot as PNG; results as CSV (with a comment header) and a Markdown report; or print the page. Every export carries the footer "Made with Returnperiod · simulations4all.com" and the professional-use notice.

Domain gate. Runs and Verify checks acquire a signed token through the shared gate. Network failures and temporary server outages can use its last verified token for up to 24 hours; explicit refusals and invalid responses block runs. A retired tool-local cache cannot grant access. Leaving the tool stops its banner refreshes; reopening starts them again. Editing, Open, Save and the Guide remain available.

Browser storage. The document is autosaved in IndexedDB, with a small copy in local storage. Private browsing modes may block both; the status bar then says so and Save still works. No data leave your browser except the domain-gate token exchange.

Units and conventions

• Values have the unit you label them with; Returnperiod does no unit conversion. Return periods are in years.
• AEP is the annual exceedance probability; the return period is 1 / AEP. A 100-year flood has AEP 0.01.
• Log-Pearson III moments are of base-10 logarithms. Lognormal parameters are of natural logarithms.
• Skew is the third standardised moment. Positive skew means a long upper tail.
• GEV shape follows Hosking's sign: x(F) = location + (scale / shape) (1 - (-ln F)^shape).
• Water years run from October to September and are named for the year in which they end.

Limitations: what Returnperiod does not do

• EMA and automatic low-outlier selection are experimental: the published censored-record benchmarks remain unresolved. Fits that activate a skew or data-support constraint are unsupported and refused; no frequency estimates are released for them. Unconstrained fits are preliminary estimates, not a validated agency workflow.
• Normal LP3 confidence limits for MLE and L-moment fits reuse MOM covariance and have no independent coverage validation. Prefer bootstrap estimates and treat uncertainty as indicative.
• Storm duration must be an integer multiple of its time step. Cumulative rainfall must be finite and nondecreasing; incompatible inputs are refused.
• Reservoir sizing assumes an indefinitely repeated record. Demand plus losses exceeding inflow has no finite required capacity. Safe yield accounts for losses.
• Confidence limits for the log-Pearson III fit use the normal approximation of Bulletin 17C eq. 7-31 on an asymptotic variance derived here; they are narrower and more symmetric than the intervals in the published examples, which use an improved procedure (Cohn and others, 2001; Cohn, written communication, 2015) whose interval form appears in equations 7-33–7-34; its covariance and later refinements are not implemented here.
• The Multiple Grubbs-Beck p-values are Monte Carlo estimates of the definition in Bulletin 17C appendix 6; the exact numerical integration of Cohn and others (2013) is not in the Guidelines. Back Creek low-outlier selection agrees, but its tail quantiles and confidence limits are not a reproduction of the published results; Orestimba remains unresolved (PENDING SOURCE).
• Regional skew values and their mean square errors are user entered. Use values from a current USGS regional skew study for the site.
• The built-in NRCS 24-hour distribution is built from duration ratios (NEH 630.0407). The tabulated Type I, IA, II and III distributions are not included (PENDING SOURCE); paste a table if you have one.
• No rainfall-frequency atlas data is included. IDF curves come only from the rainfall maxima you enter.
• It does not choose distributions, thresholds or regional skews for you, and it does not test for trends, mixed populations or non-stationarity.
• It does not estimate floods for ungaged sites, regulated flows or urban watersheds, and it does not run rainfall-runoff models.
• Only openly specified formats are read and written (CSV and the tool's own JSON).
• Results depend on the data you enter. Check the data first.

Troubleshooting

Compared with other tools

Desktop flood-frequency programs from federal agencies, spreadsheet templates and general statistics packages can all fit these distributions. Returnperiod differs in running in a browser without installation and in putting frequency analysis, IDF curves, design storms and reservoir storage in one document. It does not match them everywhere: it has no import of agency data files or web services, no regional skew studies, no record extension from a nearby site, no trend tests, and its confidence limits and low-outlier p-values are approximations as described under Limitations. Where a result matters, compare it with the program your agency requires.

How we verify Returnperiod

The Verify page runs 141 reference cases in your browser and shows, for each, what is checked, the independent reference, the value the tool computes, the difference and the tolerance. The same cases run in the test suite before every release, so what you see is what is tested.

The references are of three kinds: closed forms and identities written out in the case (for example the plotting-position formula and the L-moment definitions evaluated over all subsets); an external numerical library run on the same inputs, with its licence notice recorded on the Verify page; and the worked examples of USGS Techniques and Methods 4-B5 (Bulletin 17C) and the NRCS National Engineering Handbook Part 630 chapter 4, cited by table and printed page. Where the tool does not reproduce a published number the case says so, and cases whose source could not be opened are marked PENDING SOURCE with no value.

The published Moose River estimates are reproduced, and the NRCS construction reproduces all 241 published cumulative values of its worked example. Press Run all checks for a summary such as "all checks pass on this browser", then print the page for a record.

Professional-use notice

Returnperiod results are for education and preliminary design. They must be checked by a qualified professional and are not a substitute for code-compliant design or licensed engineering judgement. Returnperiod is not certified, and nothing it produces is accepted by any regulator or agency as an official flood-frequency, rainfall-frequency or design-storm determination.