1. Tutorial and introduction to floodestimation

1.1. Installation and requirements

The floodestimation package can be installed on Windows, Mac OS and Linux operating systems from anaconda.org using the Conda package manager:

conda install -c https://conda.anaconda.org/openhydrology floodestimation

Or alternatively directly from the source code:

The floodestimation package has been tested with Python 3.3 and 3.4.

1.2. Typical workflow

A typical workflow for using the floodestimation package is as follows:

1. Start with an ungauged catchment with catchment details in a .CD3 or .xml-file, e.g. River Dee.CD3
2. Load the catchment
3. Estimate the median annual flood (QMED)
4. Estimate the flood growth curve
5. Estimate the flood frequency curve
6. Create an analysis report

1.2.1. Estimating QMED

Steps 1 to 3 could be coded as follows:

from floodestimation import db, loaders
from floodestimation.collections import CatchmentCollections
from floodestimation.analysis import QmedAnalysis

db_session = db.Session()

dee_catchment = loaders.from_file('River Dee.CD3')
gauged_catchments = CatchmentCollections(db_session)

qmed_analysis = QmedAnalysis(dee_catchment, gauged_catchments)
dee_catchment_qmed = qmed_analysis.qmed()

db_session.close()

Explained step by step:

db_session = db.Session()

This creates a connection with a sqlite database which will hold data on gauged catchments (catchment descriptors and annual maximum flow data). The Session object can be re-used throughout the program.

dee_catchment = loaders.from_file('River Dee.CD3')

This loads the catchment from the .CD3 file as an entities.Catchment object. See the reference manual for a detailed description of all object attributes.

gauged_catchments = CatchmentCollections(db_session)

This creates a collections.CatchmentCollections object for quick access to gauged catchment data stored in the database. The first time, when the database is still empty, the data will be automatically downloaded from the National River Flow Archive website. This might take a little while.

analysis = QmedAnalysis(dee_catchment, gauged_catchments)
dee_catchment_qmed = qmed_analysis.qmed()

The analysis.QmedAnalysis object provides a comprehensive set of methods to estimate QMED. The library will automatically identify the best method based on which data is available when calling qmed() without arguments. The following methods are available:

• Using annual maximum flow records (for gauged catchments)
• Using the Flood Estimation Handbook regression method (science report SC050050) based on catchment descriptors and further correction using nearby donor stations (if the gauged catchments collection is supplied)
• Emperical estimate using catchment surface area only
• Emperical estimated using the river channel width only

See the reference manual for a detailed description how to use the different methods.

1.2.2. Estimating the flood frequency curve

Step 4 and 5 can be done like this:

# continue from script above but keep database session open
# db_session.close()

from floodestimation.analysis import GrowthCurveAnalysis

gc_analysis = GrowthCurveAnalysis(dee_catchment, gauged_catchments)
dee_growth_curve = gc_analysis.growth_curve()
aeps = [0.5, 0.01, 0.005, 0.001]
dee_flood_flows = dee_catchment_qmed * dee_growth_curve(aeps)

for donor in gc_analysis.donor_catchments:
    print("{0:>6} {1:<20s} {2:.3f} {3:.3f}".
        format(donor.id, donor.location, donor.similarity_dist, donor.distance_to(dee_catchment)))

db_session.close()

Explained step by step:

gc_analysis = GrowthCurveAnalysis(dee_catchment, gauged_catchments)

Th analysis.GrowthCurveAnalysis provides methods to estimate growth curves for a catchment, using data from catchment itself or the collection of gauged catchments using a pooling group approach.

dee_growth_curve = gc_analysis.growth_curve()

Calling the analysis.GrowthCurveAnalysis.growth_curve() returns a growth curve method/function which can be used like this: flow = dee_growth_curve(aep=0.01). The method parameter aep can be a single annual exceedance probability (AEP) value or a list of values. If a list of values is provided the returned value is a numpy.ndarray of flows. The growth curve is estimated using one of the following methods:

• Pooling group statistical method: for ungauged catchments (science report SC050050). Hydrologically similar catchments are selected from the gauged_catchments collection.
• Enhanced single site analysis: for gauged catchments with a record length too small compared with the annual exceedance probabilty of interest. (science report SC050050). The analysis is similar to the pooling group approach except that the subject catchment has a significantly greater weighting in the pooling group than all other catchments.
• Single site analysis: uses flow data from the subject catchment only. This method is not typically used as the record length is typicaly too short.

The most suitable method is automatically used, unless the method is specified like this: growth_curve(method=...). See the reference manual for a detailed description how to use the different methods.

aeps = [0.5, 0.01, 0.005, 0.001]
dee_flood_flows = dee_catchment_qmed * dee_growth_curve(aeps)

The benefit of the numpy.ndarray return type is that we can do element-wise multiplication to obtain the flood frequency curve.

for donor in gc_analysis.donor_catchments:
    print("{0:>6} {1:<20s} {2:.3f} {3:.3f}".
        format(donor.id, donor.location, donor.similarity_dist, donor.distance_to(dee_catchment)))

The list of donor catchments used in the analysis can be accessed using the analysis.GrowthCurveAnalysis.donor_catchments attribute. This is a simple list of entities.Catchment objects with an additional attribute similarity_dist.