flood estimation library documentation...flood estimation library documentation, release 0.1.2...

Flood Estimation LibraryDocumentation

Release 0.1.2

Neil Nutt, Florenz A.P. Hollebrandse

December 04, 2014

Contents

1 Tutorial and introduction to floodestimation 31.1 Installation and requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31.2 Typical workflow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

2 Reference manual 72.1 floodestimation.entities — Core components . . . . . . . . . . . . . . . . . . . . . . . 72.2 floodestimation.parsers — Parsing FEH data files . . . . . . . . . . . . . . . . . . . . . . 122.3 floodestimation.fehdata — Accessing gauged catchment data . . . . . . . . . . . . . . . . 142.4 floodestimation.db — Storing gauged catchment data in sqlite database . . . . . . . . . . . . 152.5 floodestimation.loaders — Loading catchment data quickly . . . . . . . . . . . . . . . . 162.6 floodestimation.collections — Common sets of catchments . . . . . . . . . . . . . . . 162.7 floodestimation.analysis — Flood estimation analyses . . . . . . . . . . . . . . . . . . . 17

3 Indices and tables 23

Python Module Index 25

i

Flood Estimation Library Documentation, Release 0.1.2

Contents:

Contents 1


2 Contents

CHAPTER 1

Tutorial and introduction to floodestimation

1.1 Installation and requirements

The floodestimation package is available for download on the Python Package Index (PyPI) website. Installationis straightforward and is typically done like this from a command prompt:

pip install floodestimation

On Windows pip is typically installed under C:\Program Files\Python33\Scripts\pip.exe or somewhere similar.

In case of downloading the package manually, the following other packages are required and must be availabe:

• numpy

• scipy

• appdirs

• sqlalchemy

• lmoments3

Installation packages for numpy and scipy for Windows are available on the Unoffical Windows Binaries for PythonExtension Packages website.

The floodestimation package has been tested with Python 3.3 to 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-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

3

http://www.lfd.uci.edu/~gholke/pythonlibs/

http://www.lfd.uci.edu/~gholke/pythonlibs/


1.2.1 Estimating QMED

Steps 1 to 3 could be coded as follows:

from floodestimation.loaders import load_catchmentfrom floodestimation import dbfrom floodestimation.collections import CatchmentCollectionsfrom floodestimation.analysis import QmedAnalysis

db_session = db.Session()

dee_catchment = load_catchment(’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 descriptorsand annual maximum flow data). The Session object can be re-used throughout the program.

dee_catchment = load_catchment(’River Dee.CD3’)

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

gauged_catchments = CatchmentCollections(db_session)

This creates a collections.CatchmentCollections object for quick access to gauged catchment data storedin the database. The first time, when the database is still empty, the data will be automatically downloaded from theNational 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 librarywill 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 de-scriptors 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:

4 Chapter 1. Tutorial and introduction to floodestimation

http://docs.sqlalchemy.org/en/rel_0_9/orm/session.html

http://www.ceh.ac.uk/data/nrfa/peakflow_overview.html

https://www.gov.uk/government/uploads/system/uploads/attachment_data/file/291096/scho0608boff-e-e.pdf


# 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 datafrom 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/functionwhich can be used like this: flow = dee_growth_curve(aep=0.01). The method parameter aep can be a single an-nual exceedance probability (AEP) value or a list of values. If a list of values is provided the returned value is anumpy.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 similarcatchments are selected from the gauged_catchments collection.

• Enhanced single site analysis: for gauged catchments with a record length too small compared with the annualexceedance probabilty of interest. (science report SC050050). The analysis is similar to the pooling groupapproach except that the subject catchment has a significantly greater weighting in the pooling group than allother catchments.

• Single site analysis: uses flow data from the subject catchment only. This method is not typically used as therecord 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 floodfrequency 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 theanalysis.GrowthCurveAnalysis.donor_catchments attribute. This is a simple list ofentities.Catchment objects with an additional attribute similarity_dist.

1.2. Typical workflow 5




6 Chapter 1. Tutorial and introduction to floodestimation

CHAPTER 2

Reference manual

2.1 floodestimation.entities — Core components

This module contains the core components or entities, including Catchment, AmaxRecord etc.

Note that all entities are subclasses of floodestimation.db.Base which is an SQL Alchemy base class toenable saving to a (sqlite) database. All class attributes therefore are sqlalchemy.Column objects e.g. Col-umn(Float), Column(String), etc. Attribute values can simply be set like normal, e.g. catchment.watercourse = “RiverDee”.

2.1.1 Catchment — The catchment object

class floodestimation.entities.Catchment(location=None, watercourse=None)Catchment object include FEH catchment descriptors and additional information describing the catchment.

Example:

>>> from floodestimation.entities import Catchment, Descriptors>>> catchment = Catchment("Aberdeen", "River Dee")>>> catchment.channel_width = 1>>> catchment.descriptors = Descriptors(dtm_area=1, bfihost=0.50, sprhost=50, saar=1000, farl=1, urbext=0}>>> catchment.qmed()0.2671386414098229

amax_recordsList of annual maximum flow records as AmaxRecord objects

areaCatchment area in km²

channel_widthWidth of the watercourse channel at the catchment outlet in m.

commentsList of comments

countryAbbreviation of country, e.g. gb, ni.

descriptorsFEH catchment descriptors (one-to-one relationship)

idGauging station number

7


is_suitable_for_poolingWhether this catchment’s annual maximum flow data can be used in pooling group analyses

is_suitable_for_qmedWhether this catchment can be used to estimate QMED at other similar catchments

locationCatchment outlet location name, e.g. Aberdeen

pointCoordinates of catchment outlet as Point object

pot_datasetPeaks-over-threshold dataset (one-to-one relationship)

qmed()Returns QMED estimate using best available methodology depending on what catchment attributes areavailable.

Returns QMED in m³/s

Return type float

watercourseName of watercourse at the catchment outlet, e.g. River Dee

2.1.2 Descriptors — A set of catchment descriptors

class floodestimation.entities.Descriptors(**kwargs)Set of FEH catchment descriptors.

This is the complete set of name = value pairs in the [DESCRIPTORS] block in a CD3 file. All other parametersare directly attributes of Catchment.

Descriptors are used as follows:

>>> from floodestimation.entities import Catchment>>> catchment = Catchment(...)>>> catchment.descriptors.dtm_area416.56>>> catchment.descriptors.centroid_ngr(317325, 699832)

altbarMean elevation in m

aspbarMean aspect (orientation) in degrees

aspvarAspect variance in degrees

bfihostBase flow index based on Hydrology of Soil Types (HOST) data. Value between 0 and 1.

catchment_idOne-to-one reference to corresponding Catchment object

centroid_ngrCatchment centre national grid reference as Point object. Catchment.country indicates coordinatesystem.

8 Chapter 2. Reference manual


dplbarMean drainage path length in km

dpsbarMean drainage path slope (dimensionless)

dtm_areaSurface area in km² based on digital terrain model data

farlLake, reservoir or loch flood attenuation index

fpextFloodplain extent parameter

ihdtm_ngrCatchment outlet national grid reference as Point object. Catchment.country indicates coordinatesystem.

ldpLongest drainage path length in km

propwetProportion of time soils are wet index

rmed_1dMedian annual maximum 1 day rainfall in mm

rmed_1hMedian annual maximum 1 hour rainfall in mm

rmed_2dMedian annual maximum 2 day rainfall in mm

saarStandard annual average rainfall in mm, 1961-1990 average

saar4170Standard annual average rainfall in mm, 1941-1970 average

sprhostStandard percentage runoff based on Hydrology of Soil Types (HOST) data. Value between 0 and 100.

urbconc1990Urbanisation concentration index, 1990 data

urbconc2000Urbanisation concentration index, 2000 data

urbextAlias for urbext2000

urbext1990Urbanisation extent index, 1990 data

urbext2000Urbanisation extent index, 2000 data

urbloc1990Urbanisation location within catchment index, 1990 data

urbloc2000Urbanisation location within catchment index, 2000 data

2.1. floodestimation.entities — Core components 9


2.1.3 AmaxRecord — Annual maximum flow records

class floodestimation.entities.AmaxRecord(date, flow, stage, flag=0)A single annual maximum flow record.

Catchment.amax_records is a list of AmaxRecord objects.

Example:

>>> from floodestimation.entities import AmaxRecord>>> from datetime import date>>> record = AmaxRecord(date=date(1999,12,31), flow=51.2, stage=1.23)

catchment_idMany-to-one reference to corresponding Catchment object

dateDate at which maximum flow occured

flagData quality flag. 0 (default): valid value, 1: invalid value, 2: rejected record.

flowObserved flow in m³/s

stageObserved water level in m above local datum

water_yearWater year or hydrological year (starts 1 October)

2.1.4 PotDataset — Peaks-over-threshold datasets

class floodestimation.entities.PotDataset(**kwargs)A peaks-over-threshold (POT) dataset including a list of PotRecord objects and some metadata such as startand end of record.

catchment_idOne-to-one reference to corresponding Catchment object

continuous_periods()Return a list of continuous data periods by removing the data gaps from the overall record.

end_dateEnd date of flow record (inclusive)

pot_data_gapsList of peaks-over-threshold records as PotDataGap objects

pot_recordsList of peaks-over-threshold records as PotRecord objects

record_length()Return record length in years, including data gaps.

start_dateStart date of flow record

thresholdFlow threshold in m³/s



total_gap_length()Return the total length of POT gaps in years.

2.1.5 PotRecord — Peaks-over-threshold records

class floodestimation.entities.PotRecord(date, flow, stage)A single peaks-over-threshold (POT) flow record.

Example:

>>> from floodestimation.entities import PotRecord>>> from datetime import date>>> record = PotRecord(date=date(1999,12,31), flow=51.2, stage=1.23)


dateDate at which flow occured

flowObserved flow in m³/s

stageObserved water level in m above local datum

2.1.6 PotDataGap — Peaks-over-threshold data gaps

class floodestimation.entities.PotDataGap(**kwargs)A gap (period) in the peaks-over-threshold (POT) records.


end_dateEnd date of gap (inclusive)

gap_length()Return length of data gap in years.

start_dateStart date of gap

2.1.7 Comment — Catchment comments

class floodestimation.entities.Comment(title, content)Comments on cachment contained in CD3 file. Each comment has a title (normally one of station, catchment,qmed suitability and pooling suitability) and content.

Catchment.comments is a list of Comment objects.

Example:

>>> from floodestimation.entities import Comment>>> comment = Comment(title="station", content="Velocity-area station on a straight reach ...")


2.1. floodestimation.entities — Core components 11


contentComment, e.g. Velocity-area station on a straight reach ...

titleComment title, e.g. station

2.1.8 Point — Point coordinates

class floodestimation.entities.Point(x, y)Point coordinate object

Example:

>>> from floodestimation.entities import Point>>> point = Point(123000, 456000)

Coordinates systems are currently not supported. Instead use Catchment.country = ‘gb’ etc.

2.2 floodestimation.parsers — Parsing FEH data files

Parsers for FEH-style data files.

Module contains base parser class and subclassses for parsing CD3 files and AMAX files.

Example:

>>> from floodestimation import parsers>>> catchment = parsers.Cd3Parser().parse("17002.CD3")>>> catchment.amax_records = parsers.AmaxParser().parse("17002.AM")>>> catchment.id17002>>> catchment.watercourse’River Leven’>>> catchment.descriptors.dtm_area416.56>>> catchment.descriptors.centroid_ngr(317325, 699832)>>> catchment.amax_records[0].water_year1968>>> catchment.amax_records[0].flow34.995

2.2.1 FehFileParser — Base file parser class

class floodestimation.parsers.FehFileParserGeneric parser for FEH file format.

File consists typically of multiple sections as follows:

[Section Name]field, valueanother field, value 1, value 2[End]

object = NoneObject that will be returned at end of parsing.



parse(file_name)Parse entire file and return relevant object.

Parameters file_name (str) – File path

Returns Parsed object

static parse_feh_date_format(s)Return a date object from a string in FEH date format, e.g. 01 Jan 1970

Parameters s (str) – Formatted date string

Returns date object

Return type datetime.date

parsed_classClass of object to be returned by parser.

alias of object

2.2.2 Cd3Parser — Parsing catchment files

class floodestimation.parsers.Cd3ParserBases: floodestimation.parsers.FehFileParser




parse_feh_date_format(s)Return a date object from a string in FEH date format, e.g. 01 Jan 1970


Returns date object


parsed_classClass to be returned by parse(). In this case Catchment objects.

alias of Catchment

2.2.3 AmaxParser — Parsing annual maximum flow records

class floodestimation.parsers.AmaxParserBases: floodestimation.parsers.FehFileParser






2.2. floodestimation.parsers — Parsing FEH data files 13


Returns date object


parsed_classClass to be returned by parse(). In this case a list of AmaxRecord objects.

alias of list

2.2.4 PotParser — Parsing peaks-over-threshold (POT) records

class floodestimation.parsers.PotParserBases: floodestimation.parsers.FehFileParser






Returns date object


parsed_classClass to be returned by parse(). In this case a PotDataset objects.

alias of PotDataset

2.3 floodestimation.fehdata — Accessing gauged catchmentdata

This module provides methods to download a complete set of published gauged catchment data from the NationalRiver Flow Archive.

Downloaded data files are stored in a Cache folder under the user’s application data folder. On Windows, this is folderis located at C:\Users\{Username}\AppData\Local\Open Hydrology\fehdata\Cache.

A typical data retrieval is as follows:

>>> from floodestimation import fehdata>>> fehdata.clear_cache()>>> fehdata.download_data()>>> fehdata.unzip_data()

Data files can then be accessed as follows:

>>> cd3_files = fehdata.cd3_files()>>> amax_files = fehdata.amax_files()

For parsing CD3 files and AMAX files see floodestimation.parsers.

floodestimation.fehdata.amax_files()Return all annual maximum flow (*.am) files in cache folder and sub folders.





Returns List of file paths

Return type list

floodestimation.fehdata.cd3_files()Return all catchment descriptor files (*.cd3) files in cache folder and sub folders.

Returns List of file paths

Return type list

floodestimation.fehdata.clear_cache()Delete all files from cache folder.

floodestimation.fehdata.download_data()Downloads complete station dataset including catchment descriptors and amax records. And saves it into acache folder.

floodestimation.fehdata.unzip_data()Extract all files from downloaded FEH data zip file.

2.4 floodestimation.db — Storing gauged catchment data insqlite database

This module provides a connection with an sqlite database to store (gauged) catchment data including annual maximumflow data and catchment descriptors.

The database connection usses the sqlalchemy package (docs) for interaction with a sqlite database. The module con-tains a Base class that all entities in floodestimation.entities are based on. This enables straightforwardretrieving and saving of data in relevant tables.

The sqlite database is saved in the user’s application data folder. On Windows, this is folder is located atC:\Users\{Username}\AppData\Local\Open Hydrology\fehdata\fehdata.sqlite.

The database is automatically created (if it does not exist yet) when importing the floodestimation package.

Interaction with the database is typically as follows:

from floodestimation import dbfrom floodestimation.entities import Catchment

# Once:session = db.Session()

# As and when required:session.add(Catchment(...)) # Load datacatchments = session.query(Catchment).filter_by(...) # Retrieve datasession.commit()

Typically a single session instance can be used throughout a program with commits (or rollbacks) as and when required.

class floodestimation.db.Base(**kwargs)Base class all entities that should be stored as a table in the database should be inheriting from. For example:

from floodestimation import db

class SomeEntity(db.Base):__tablename__ = ’some_entity’...

2.4. floodestimation.db — Storing gauged catchment data in sqlite database 15


2.5 floodestimation.loaders — Loading catchment data quickly

This module contains some convenience functions for quickly loading catchments (incl. annual maximum flow data)from CD3-files and to download all gauged catchments and save into a sqlite database.

floodestimation.loaders.gauged_catchments_to_db(session)Retrieves all gauged catchments (incl. catchment descriptors and annual maximum flow data) from the NationalRiver Flow Archive and saves it to a (sqlite) database.

Parameters session (sqlalchemy.orm.session.Session) – database session to use, typically floodesti-mation.db.Session()

floodestimation.loaders.load_catchment(cd3_file_path)Load catchment object from a .CD3 file. If there is also a corresponding .AM file (annual maximum flow data)or a .PT file (peaks over threshold data) in the same folder as the CD3 file, these datasets will also be loaded.

Parameters cd3_file_path (str) – File location of CD3 file

Returns Catchment object with the amax_records and pot_dataset attributes set (if data available).

Return type entities.Catchment

2.6 floodestimation.collections — Common sets of catch-ments

This module contains collections for easy retrieval of standard lists or scalars from the database with gauged catchmentdata.

class floodestimation.collections.CatchmentCollections(db_session, load_data=’auto’)Collections of frequently used floodestimation.entities.Catchment objects.

The collections objects must be passed a session to a database containing the data. This is typicallyfloodestimation.db.Session()

catchment_by_number(number)Return a single catchment by NRFA station number

Parameters number (int) – NRFA gauging station number

Returns relevant catchment if exist or None otherwise

Return type floodestimation.entities.Catchment

static delete_gauged_catchments()Delete all catchment data from the database

load_gauged_catchments()Load all catchment data into the database by downloading the data from the NRFA website

most_similar_catchments(subject_catchment, similarity_dist_function, records_limit=500, in-clude_subject_catchment=’auto’)

Return a list of catchments sorted by hydrological similarity defined by similarity_distance_function

Parameters

• subject_catchment (floodestimation.entities.Catchment) – subject catch-ment to find similar catchments for

• similarity_dist_function – a method returning a similarity distance measure with 2 argu-ments, both floodestimation.entities.Catchment objects



• include_subject_catchment (str) –

– auto: include subject catchment if suitable for pooling and if urbext < 0.03

– force: always include subject catchment

– exclude: do not include the subject catchment

Returns list of catchments sorted by similarity

Type list of floodestimation.entities.Catchment

nearest_qmed_catchments(subject_catchment, limit=None, dist_limit=500)Return a list of catchments sorted by distance to subject_catchment and filtered to only include catch-ments suitable for QMED analyses.

Parameters

• subject_catchment (floodestimation.entities.Catchment) – catchment ob-ject to measure distances to

• limit (int) – maximum number of catchments to return. Default: None (returns all availablecatchments).

• dist_limit (float or int) – maximum distance in km. between subject and donor catchment.Default: 500 km. Increasing the maximum distance will increase computation time!

Returns list of catchments sorted by distance

Return type list of floodestimation.entities.Catchment

2.7 floodestimation.analysis — Flood estimation analyses

2.7.1 QmedAnalysis — Estimating the median annual flood

class floodestimation.analysis.QmedAnalysis(catchment, gauged_catchments=None)Class to undertake QMED analyses.

Example:

>>> from floodestimation.entities import Catchment, Descriptors>>> from floodestimation.analysis import QmedAnalysis>>> catchment = Catchment("Aberdeen", "River Dee")>>> catchment.descriptors = Descriptors(dtm_area=1, bfihost=0.50, sprhost=50, saar=1000, farl=1, urbext=0)>>> QmedAnalysis(catchment).qmed_all_methods(){’descriptors’: 0.5908579150223052, ’pot_records’: None, ’channel_width’: None,’descriptors_1999’: 0.2671386414098229, ’area’: 1.172, ’amax_records’: None}

catchment = NoneSubject catchment

donor_weighting = NoneMethod for weighting multiple QMED donors, options are:

•idw (default): Use an Inverse Distance Weighting (IDW) method. Donor catchments nearby havehigher weighting than catchments further away.

•equal: All donors have equal weights.

•first: Use only the first (nearest) donor catchment.

2.7. floodestimation.analysis — Flood estimation analyses 17


find_donor_catchments(limit=20, dist_limit=500)Return a suitable donor catchment to improve a QMED estimate based on catchment descriptors alone.

Parameters

• limit (int) – maximum number of catchments to return. Default: 20. Set to None to returnall available catchments.

• dist_limit (float or int) – maximum distance in km. between subject and donor catchment.Default: 500 km. Increasing the maximum distance will increase computation time!

Returns list of nearby catchments

Return type floodestimation.entities.Catchment

gauged_catchments = Nonecollections.CatchmentCollections object for retrieval of gauged data for donor based analy-ses (optional)

idw_power = NonePower parameter to use in IDW weighting method. Default: 3 (cubic). Higher powers results in higherweights for nearby donor catchments. A power of 1 indicates an inverse linear relationship betweendistance and weight.

qmed(method=’best’, **method_options)Return QMED estimate using best available methodology depending on what catchment attributes areavailable.

The preferred/best order of methods is defined by qmed_methods. Alternatively, a method can besupplied e.g. method=’descriptors_1999’ to force the use of a particular method.

method method_options notesamax_recordsn/a Simple median of annual maximum flow records using

Catchment.amax_records.pot_recordsn/a Uses peaks-over-threshold (POT) flow records. Suitable for flow records

shorter than 14 years.de-scrip-tors

Synonym for method=descriptors2008.

de-scrip-tors2008

as_rural=Falsedonor_catchments=[]

FEH 2008 regression methodology using Catchment.descriptors. Settingas_rural=True returns rural estimate and setting donor_catchments to aspecific list of Catchment object overrides automatic selection of themost suitable donor catchment.

de-scrip-tors1999

as_rural=False FEH 1999 regression methodology.

area n/a Simplified FEH 1999 regression methodology usingCachment.descriptors.dtm_area only.

chan-nel_width

n/a Emperical regression method using the river channel width only.

Parameters

• method (str) – methodology to use to estimate QMED. Default: automatically choose bestmethod.

• method_options (kwargs) – any optional parameters for the QMED method function, e.g.as_rural=True

Returns QMED in m³/s



Return type float

qmed_all_methods()Returns a dict of QMED methods using all available methods.

Available methods are defined in qmed_methods. The returned dict keys contain the method name, e.g.amax_record with value representing the corresponding QMED estimate in m³/s.

Returns dict of QMED estimates

Return type dict

urban_adj_factor()Return urban adjustment factor (UAF) used to adjust QMED and growth curves.

Methodology source: FEH, Vol. 3, p. 53

Returns urban adjustment factor

Return type float

2.7.2 GrowthCurveAnalysis — Estimating the flood growth curve

class floodestimation.analysis.GrowthCurveAnalysis(catchment,gauged_catchments=None)

Class to undertake a growth curve analysis.

catchment = NoneSubject catchment

distributions = (‘glo’, ‘gev’)Available distribution functions for growth curves

donor_catchments = NoneList of donor catchments. Either set manually or by callingGrowthCurveAnalysis.find_donor_catchments() or implicitly when callinggrowth_curve().

find_donor_catchments(include_subject_catchment=’auto’)Find list of suitable donor cachments, ranked by hydrological similarity distance measure. Thismethod is implicitly called when calling the growth_curve() method unless the attributedonor_catchments is set manually.

The results are stored in donor_catchments. The (list of)floodestimation.entities.Catchment will have an additional attributesimilarity_dist.

Parameters include_subject_catchment (str) –

• auto: include subject catchment if suitable for pooling and if urbext < 0.03

• force: always include subject catchment

• exclude: do not include the subject catchment

gauged_cachments = Nonecollections.CatchmentCollections object for retrieval of gauged data for donor based analy-ses (optional)

growth_curve(method=’best’, **method_options)Return QMED estimate using best available methodology depending on what catchment attributes areavailable.



method method_optionsnotesen-hanced_single_site

distr=’glo’ Preferred method for gauged catchments (i.e. withCatchment.amax_record).

single_site distr=’glo’ Alternative method for gauged catchments. Uses AMAX datafrom subject station only.

pooling_group distr=’glo’ Only possible method for ungauged catchments.

Parameters

• method (str) – methodology to use to estimate the growth curve. Default: automaticallychoose best method.

• method_options (kwargs) – any optional parameters for the growth curve method function

Returns Inverse cumulative distribution function, callable class with one parameter aep (annualexceedance probability)

Type GrowthCurve

methods = (‘enhanced_single_site’, ‘single_site’, ‘pooling_group’)Methods available to estimate the growth curve

similarity_params = {‘fpext’: (0.2, 0.04), ‘dtm_area’: (3.2, 1.28, <built-in function log>), ‘farl’: (0.1, 0.05), ‘saar’: (0.5, 0.37, <built-in function log>)}Dict of weighting factors and standard deviation for catchment descriptors to use in calculating the simi-larity distance measure between the subject catchment and each donor catchment. The dict is structuredlike this: {parameter: (weight, standard deviation, transform method)}. The transform method is optionaland is typically omitted or set to log.

2.7.3 GrowthCurve — The flood growth curve object

class floodestimation.analysis.GrowthCurve(distr, var, skew, kurtosis=None)Growth curve constructed using sample L-VAR and L-SKEW.

The GrowthCurve class is callable, i.e. it can be used as a function. It has one parameter aep, which is an annualexceedance probability and can be either a single value or a list of values. In the latter case, a numpy ndarrayis returned.

Example:

>>> from floodestimation.analysis import GrowthCurve>>> growth_curve = GrowthCurve(distr=’glo’, var=0.2, skew=-0.1, kurtosis=0.185)>>> growth_curve(aep=0.5)1.0>>> growth_curve(aep=[0.1, 0.01, 0.001])array([ 1.38805928, 1.72475593, 1.98119739])>>> growth_curve.params[1.0, 0.1967263286166932, 0.1]>>> growth_curve.distr_kurtosis0.175>>> growth_curve.kurtosis_fit()0.010000000000000009

distr = NoneStatistical distribution function abbreviation, e.g. ‘glo’, ‘gev’. Any supported by the lmoments3 packagecan be used.

distr_f = NoneStatistical distribution as scipy rv_continous class, extended with L-moment methods.



distr_kurtosis = NoneThe distribution’s L-kurtosis which may be different from the sample L-kurtosis (t4).

kurtosis = NoneSample L-kurtosis (t4, not used to create distribution function)

kurtosis_fit()Estimate the goodness of fit by calculating the difference between sample L-kurtosis and distribution func-tion L-kurtosis.

Returns Goodness of fit measure

Return type float

params = NoneDistribution function parameter. Except for the loc parameter, all other parameters are estimated using thesample variance and skew linear moments.

skew = NoneSample L-skew (t3)

var = NoneSample L-variance (t2)


CHAPTER 3

Indices and tables

• genindex

• modindex

• search

23


24 Chapter 3. Indices and tables

Python Module Index

ffloodestimation.collections, 16floodestimation.db, 15floodestimation.entities, 7floodestimation.fehdata, 14floodestimation.loaders, 16floodestimation.parsers, 12

25


26 Python Module Index

Index

Aaltbar (floodestimation.entities.Descriptors attribute), 8amax_files() (in module floodestimation.fehdata), 14amax_records (floodestimation.entities.Catchment

attribute), 7AmaxParser (class in floodestimation.parsers), 13AmaxRecord (class in floodestimation.entities), 10area (floodestimation.entities.Catchment attribute), 7aspbar (floodestimation.entities.Descriptors attribute), 8aspvar (floodestimation.entities.Descriptors attribute), 8

BBase (class in floodestimation.db), 15bfihost (floodestimation.entities.Descriptors attribute), 8

CCatchment (class in floodestimation.entities), 7catchment (floodestima-

tion.analysis.GrowthCurveAnalysis attribute),19

catchment (floodestimation.analysis.QmedAnalysis at-tribute), 17

catchment_by_number() (floodestima-tion.collections.CatchmentCollectionsmethod), 16

catchment_id (floodestimation.entities.AmaxRecord at-tribute), 10

catchment_id (floodestimation.entities.Comment at-tribute), 11

catchment_id (floodestimation.entities.Descriptorsattribute), 8

catchment_id (floodestimation.entities.PotDataGap at-tribute), 11

catchment_id (floodestimation.entities.PotDataset at-tribute), 10

catchment_id (floodestimation.entities.PotRecord at-tribute), 11

CatchmentCollections (class in floodestima-tion.collections), 16

cd3_files() (in module floodestimation.fehdata), 15

Cd3Parser (class in floodestimation.parsers), 13centroid_ngr (floodestimation.entities.Descriptors at-

tribute), 8channel_width (floodestimation.entities.Catchment at-

tribute), 7clear_cache() (in module floodestimation.fehdata), 15Comment (class in floodestimation.entities), 11comments (floodestimation.entities.Catchment attribute),

7content (floodestimation.entities.Comment attribute), 11continuous_periods() (floodestimation.entities.PotDataset

method), 10country (floodestimation.entities.Catchment attribute), 7

Ddate (floodestimation.entities.AmaxRecord attribute), 10date (floodestimation.entities.PotRecord attribute), 11delete_gauged_catchments() (floodestima-

tion.collections.CatchmentCollections staticmethod), 16

Descriptors (class in floodestimation.entities), 8descriptors (floodestimation.entities.Catchment attribute),

7distr (floodestimation.analysis.GrowthCurve attribute),

20distr_f (floodestimation.analysis.GrowthCurve attribute),

20distr_kurtosis (floodestimation.analysis.GrowthCurve at-

tribute), 20distributions (floodestima-


donor_catchments (floodestima-tion.analysis.GrowthCurveAnalysis attribute),19

donor_weighting (floodestima-tion.analysis.QmedAnalysis attribute), 17

download_data() (in module floodestimation.fehdata), 15dplbar (floodestimation.entities.Descriptors attribute), 8dpsbar (floodestimation.entities.Descriptors attribute), 9

27


dtm_area (floodestimation.entities.Descriptors attribute),9

Eend_date (floodestimation.entities.PotDataGap attribute),

11end_date (floodestimation.entities.PotDataset attribute),

10

Ffarl (floodestimation.entities.Descriptors attribute), 9FehFileParser (class in floodestimation.parsers), 12find_donor_catchments() (floodestima-

tion.analysis.GrowthCurveAnalysis method),19

find_donor_catchments() (floodestima-tion.analysis.QmedAnalysis method), 17

flag (floodestimation.entities.AmaxRecord attribute), 10floodestimation.collections (module), 16floodestimation.db (module), 15floodestimation.entities (module), 7floodestimation.fehdata (module), 14floodestimation.loaders (module), 16floodestimation.parsers (module), 12flow (floodestimation.entities.AmaxRecord attribute), 10flow (floodestimation.entities.PotRecord attribute), 11fpext (floodestimation.entities.Descriptors attribute), 9

Ggap_length() (floodestimation.entities.PotDataGap

method), 11gauged_cachments (floodestima-


gauged_catchments (floodestima-tion.analysis.QmedAnalysis attribute), 18

gauged_catchments_to_db() (in module floodestima-tion.loaders), 16

growth_curve() (floodestima-tion.analysis.GrowthCurveAnalysis method),19

GrowthCurve (class in floodestimation.analysis), 20GrowthCurveAnalysis (class in floodestimation.analysis),

19

Iid (floodestimation.entities.Catchment attribute), 7idw_power (floodestimation.analysis.QmedAnalysis at-

tribute), 18ihdtm_ngr (floodestimation.entities.Descriptors at-

tribute), 9is_suitable_for_pooling (floodestima-

tion.entities.Catchment attribute), 8

is_suitable_for_qmed (floodestima-tion.entities.Catchment attribute), 8

Kkurtosis (floodestimation.analysis.GrowthCurve at-

tribute), 21kurtosis_fit() (floodestimation.analysis.GrowthCurve

method), 21

Lldp (floodestimation.entities.Descriptors attribute), 9load_catchment() (in module floodestimation.loaders), 16load_gauged_catchments() (floodestima-

tion.collections.CatchmentCollectionsmethod), 16

location (floodestimation.entities.Catchment attribute), 8

Mmethods (floodestimation.analysis.GrowthCurveAnalysis

attribute), 20most_similar_catchments() (floodestima-


Nnearest_qmed_catchments() (floodestima-


Oobject (floodestimation.parsers.FehFileParser attribute),

12

Pparams (floodestimation.analysis.GrowthCurve attribute),

21parse() (floodestimation.parsers.AmaxParser method), 13parse() (floodestimation.parsers.Cd3Parser method), 13parse() (floodestimation.parsers.FehFileParser method),

12parse() (floodestimation.parsers.PotParser method), 14parse_feh_date_format() (floodestima-

tion.parsers.AmaxParser method), 13parse_feh_date_format() (floodestima-

tion.parsers.Cd3Parser method), 13parse_feh_date_format() (floodestima-

tion.parsers.FehFileParser static method),13

parse_feh_date_format() (floodestima-tion.parsers.PotParser method), 14

parsed_class (floodestimation.parsers.AmaxParserattribute), 14

parsed_class (floodestimation.parsers.Cd3Parser at-tribute), 13

28 Index


parsed_class (floodestimation.parsers.FehFileParser at-tribute), 13

parsed_class (floodestimation.parsers.PotParser at-tribute), 14

Point (class in floodestimation.entities), 12point (floodestimation.entities.Catchment attribute), 8pot_data_gaps (floodestimation.entities.PotDataset

attribute), 10pot_dataset (floodestimation.entities.Catchment at-

tribute), 8pot_records (floodestimation.entities.PotDataset at-

tribute), 10PotDataGap (class in floodestimation.entities), 11PotDataset (class in floodestimation.entities), 10PotParser (class in floodestimation.parsers), 14PotRecord (class in floodestimation.entities), 11propwet (floodestimation.entities.Descriptors attribute), 9

Qqmed() (floodestimation.analysis.QmedAnalysis

method), 18qmed() (floodestimation.entities.Catchment method), 8qmed_all_methods() (floodestima-

tion.analysis.QmedAnalysis method), 19QmedAnalysis (class in floodestimation.analysis), 17

Rrecord_length() (floodestimation.entities.PotDataset

method), 10rmed_1d (floodestimation.entities.Descriptors attribute),

9rmed_1h (floodestimation.entities.Descriptors attribute),

9rmed_2d (floodestimation.entities.Descriptors attribute),

9

Ssaar (floodestimation.entities.Descriptors attribute), 9saar4170 (floodestimation.entities.Descriptors attribute),

9similarity_params (floodestima-


skew (floodestimation.analysis.GrowthCurve attribute),21

sprhost (floodestimation.entities.Descriptors attribute), 9stage (floodestimation.entities.AmaxRecord attribute), 10stage (floodestimation.entities.PotRecord attribute), 11start_date (floodestimation.entities.PotDataGap at-

tribute), 11start_date (floodestimation.entities.PotDataset attribute),

10

Tthreshold (floodestimation.entities.PotDataset attribute),

10title (floodestimation.entities.Comment attribute), 12total_gap_length() (floodestimation.entities.PotDataset

method), 10

Uunzip_data() (in module floodestimation.fehdata), 15urban_adj_factor() (floodestima-

tion.analysis.QmedAnalysis method), 19urbconc1990 (floodestimation.entities.Descriptors at-

tribute), 9urbconc2000 (floodestimation.entities.Descriptors at-

tribute), 9urbext (floodestimation.entities.Descriptors attribute), 9urbext1990 (floodestimation.entities.Descriptors at-

tribute), 9urbext2000 (floodestimation.entities.Descriptors at-

tribute), 9urbloc1990 (floodestimation.entities.Descriptors at-

tribute), 9urbloc2000 (floodestimation.entities.Descriptors at-

tribute), 9

Vvar (floodestimation.analysis.GrowthCurve attribute), 21

Wwater_year (floodestimation.entities.AmaxRecord at-

tribute), 10watercourse (floodestimation.entities.Catchment at-

tribute), 8

Index 29

flood estimation library documentation...flood estimation library documentation, release 0.1.2...

Documents