Flood Estimation Library Documentation

Flood Estimation LibraryDocumentation

Release 0.3.2

Neil Nutt, Florenz A.P. Hollebrandse

February 16, 2015

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 . . . . . . . . . . . . . . . . 152.4 floodestimation.db — Storing gauged catchment data in sqlite database . . . . . . . . . . . . 162.5 floodestimation.loaders — Loading catchment data quickly . . . . . . . . . . . . . . . . 162.6 floodestimation.collections — Common sets of catchments . . . . . . . . . . . . . . . 182.7 floodestimation.analysis — Flood estimation analyses . . . . . . . . . . . . . . . . . . . 19

3 Indices and tables 25

Python Module Index 27

i

ii

Flood Estimation Library Documentation, Release 0.3.2

Contents:

Contents 1


2 Contents

CHAPTER 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 bin-star.org using the Conda package manager:

conda install -c https://conda.binstar.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-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.loaders import load_catchmentfrom floodestimation import dbfrom floodestimation.collections import CatchmentCollectionsfrom floodestimation.analysis import QmedAnalysis

db_session = db.Session()

3

http://conda.pydata.org/miniconda.html


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:

# 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}".

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


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

idGauging station number

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

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

areaCatchment area in km²

pointCoordinates of catchment outlet as Point object

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

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

7


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

commentsList of comments

locationCatchment outlet location name, e.g. Aberdeen

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

amax_recordsList of annual maximum flow records as AmaxRecord objects

descriptorsFEH catchment descriptors (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

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)

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, anymapped columns or relationships.

catchment_idOne-to-one reference to corresponding Catchment object

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

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

8 Chapter 2. Reference manual


dtm_areaSurface area in km² based on digital terrain model data

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.

dplbarMean drainage path length in km

dpsbarMean drainage path slope (dimensionless)

farlLake, reservoir or loch flood attenuation index

fpextFloodplain extent parameter

ldpLongest drainage path length in km

propwetProportion of time soils are wet index

rmed_1hMedian annual maximum 1 hour rainfall in mm

rmed_1dMedian annual maximum 1 day 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

urbext1990Urbanisation extent index, 1990 data

urbloc1990Urbanisation location within catchment index, 1990 data

urbconc2000Urbanisation concentration index, 2000 data

2.1. floodestimation.entities — Core components 9


urbext2000Urbanisation extent index, 2000 data

urbloc2000Urbanisation location within catchment index, 2000 data

urbext(year)Estimate the urbext2000 parameter for a given year assuming a nation-wide urbanisation curve.

Methodology source: eqn 5.5, report FD1919/TR

Parameters year (float) – Year to provide estimate for

Returns Urban extent parameter

Return type float

2.1.3 AmaxRecord — Annual maximum flow records

class floodestimation.entities.AmaxRecord(date, flow, stage=None, 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

water_yearWater year or hydrological year (starts 1 October)

flowObserved flow in m³/s

stageObserved water level in m above local datum

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

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

start_dateStart date of flow record



end_dateEnd date of flow record (inclusive)

thresholdFlow threshold in m³/s

pot_recordsList of peaks-over-threshold records as PotRecord objects

pot_data_gapsList of peaks-over-threshold records as PotDataGap objects

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

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

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

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.

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, anymapped columns or relationships.


2.1. floodestimation.entities — Core components 11


start_dateStart date of gap

end_dateEnd date of gap (inclusive)

gap_length()Return length of data gap in years.

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 ...")


titleComment title, e.g. station

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

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]

parsed_classClass of object to be returned by parser.

alias of object

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

2.2.2 Cd3Parser — Parsing catchment files

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

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

alias of Catchment



2.2. floodestimation.parsers — Parsing FEH data files 13



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


Returns date object


2.2.3 AmaxParser — Parsing annual maximum flow records

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

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

alias of list






Returns date object


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

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

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

alias of PotDataset






Returns date object




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.download_data()Downloads complete station dataset including catchment descriptors and amax records. And saves it into acache folder.

floodestimation.fehdata.nrfa_metadata()Return metadata on the NRFA data.

Returned metadata is a dict with the following elements:

•url: string with NRFA data download URL

•version: string with NRFA version number, e.g. ‘3.3.4’

•published_on: datetime of data release/publication (only month and year are accurate, rest should beignored)

•downloaded_on: datetime of last download

Returns metadata

Return type dict

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

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

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

2.3. floodestimation.fehdata — Accessing gauged catchment data 15




Return type list

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’...

floodestimation.db.empty_db_tables()Empty all database tables.

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.from_file(cd3_file_path, incl_pot=True)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

• incl_pot (bool) – Whether to load the POT (peaks-over-threshold) data. Default: True.

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

Return type entities.Catchment

floodestimation.loaders.to_db(catchment, session, method=’create’, autocommit=False)Load catchment object into the database.

A catchment/station number (catchment.id) must be provided. If method is set to update, any existingcatchment in the database with the same catchment number will be updated.

Parameters

• catchment (entities.Catchment) – New catchment object to replace any existingcatchment in the database

• session (sqlalchemy.orm.session.Session) – Database session to use, typicallyfloodestimation.db.Session()

• method (str) –

– create: only new catchments will be loaded, it must not already exist in the database.

– update: any existing catchment in the database will be updated. Otherwise it will becreated.

• autocommit (bool) – Whether to commit the database session immediately. Default:False.

floodestimation.loaders.folder_to_db(path, session, method=’create’, autocommit=False,incl_pot=True)

Import an entire folder (incl. sub-folders) into the database

Parameters

• path (str) – Folder location

• session (sqlalchemy.orm.session.Session) – database session to use, typicallyfloodestimation.db.Session()






floodestimation.loaders.nrfa_to_db(session, method=’create’, autocommit=False,incl_pot=True)

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



2.5. floodestimation.loaders — Loading catchment data quickly 17






floodestimation.loaders.userdata_to_db(session, method=’update’, autocommit=False)Add catchments from a user folder to the database.

The user folder is specified in the config.ini file like this:

[import]folder = path/to/import/folder

If this configuration key does not exist this will be silently ignored.

Parameters






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()

Parameters

• db_session (sqlalchemy.orm.session.Session) – SQLAlchemy database ses-sion

• load_data (str) –

– auto: automatically load gauged catchment data from NRFA website if required

– force: delete all exsting data first

– manual: manually retrieve data

Returns a catchment collection object

Return type CatchmentCollections



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

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

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 having at least 10 years of data

– exclude: do not include the subject catchment

Returns list of catchments sorted by similarity

Type list of floodestimation.entities.Catchment

2.7 floodestimation.analysis — Flood estimation analyses

2.7.1 Analysis — Generic analysis object

class floodestimation.analysis.Analysis(year=None, results_log=None)Generic analysis object

Parameters

• year (float) – Year to base analysis on. Default: current year.

• results_log (dict) – Dict to store intermediate results

2.7. floodestimation.analysis — Flood estimation analyses 19


2.7.2 QmedAnalysis — Estimating the median annual flood

class floodestimation.analysis.QmedAnalysis(catchment, gauged_catchments=None,year=None, results_log=None)

Bases: floodestimation.analysis.Analysis

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, urbext2000=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}

Parameters

• catchment (entities.Catchment) – subject catchment

• gauged_catchments (collections.CatchmentCollections) – catchment collec-tions objects for retrieval of gauged data for donor analyses

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.

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=None

FEH 2008 regression methodology using Catchment.descriptors.Setting as_rural=True returns rural estimate and settingdonor_catchments to a specific list of Catchment object overridesautomatic selection of the most suitable donor catchment. An emptylist forces no donors to be used at all.

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: eqn. 8, Kjeldsen 2010

Returns urban adjustment factor

Return type float

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

2.7.3 GrowthCurveAnalysis — Estimating the flood growth curve

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

Bases: floodestimation.analysis.Analysis

Class to undertake a growth curve analysis.

Parameters

• catchment (entities.Catchment) – subject catchment

• gauged_catchments (collections.CatchmentCollections) – catchment collec-tions objects for retrieval of gauged data for donor analyses

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

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().

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

method method_options notesen-hanced_single_site

distr=’glo’as_rural=False

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’as_rural=False

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

similarity_params = {‘saar’: (0.5, 0.37, <built-in function log>), ‘fpext’: (0.2, 0.04), ‘farl’: (0.1, 0.05), ‘dtm_area’: (3.2, 1.28, <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 structured



like this: {parameter: (weight, standard deviation, transform method)}. The transform method is optionaland is typically omitted or set to log.

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 urbext2000 < 0.03

• force: always include subject catchment

• exclude: do not include the subject catchment

2.7.4 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.

var = NoneSample L-variance (t2)

skew = NoneSample L-skew (t3)

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

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



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

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

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


CHAPTER 3

Indices and tables

• genindex

• modindex

• search

25


26 Chapter 3. Indices and tables

Python Module Index

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

27


28 Python Module Index

Index

Aaltbar (floodestimation.entities.Descriptors attribute), 9amax_files() (in module floodestimation.fehdata), 15amax_records (floodestimation.entities.Catchment

attribute), 8AmaxParser (class in floodestimation.parsers), 14AmaxRecord (class in floodestimation.entities), 10Analysis (class in floodestimation.analysis), 19area (floodestimation.entities.Catchment attribute), 7aspbar (floodestimation.entities.Descriptors attribute), 9aspvar (floodestimation.entities.Descriptors attribute), 9

BBase (class in floodestimation.db), 16bfihost (floodestimation.entities.Descriptors attribute), 9

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

tion.collections.CatchmentCollectionsmethod), 18

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

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

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), 18

cd3_files() (in module floodestimation.fehdata), 15Cd3Parser (class in floodestimation.parsers), 13centroid_ngr (floodestimation.entities.Descriptors at-

tribute), 8

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

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

8content (floodestimation.entities.Comment attribute), 12continuous_periods() (floodestimation.entities.PotDataset

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

Ddate (floodestimation.entities.AmaxRecord attribute), 10date (floodestimation.entities.PotRecord attribute), 11Descriptors (class in floodestimation.entities), 8descriptors (floodestimation.entities.Catchment attribute),

8distr (floodestimation.analysis.GrowthCurve attribute),

23distr_f (floodestimation.analysis.GrowthCurve attribute),

23distr_kurtosis (floodestimation.analysis.GrowthCurve at-

tribute), 24distributions (floodestima-

tion.analysis.GrowthCurveAnalysis attribute),22

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

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

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

8

Eempty_db_tables() (in module floodestimation.db), 16end_date (floodestimation.entities.PotDataGap attribute),

12

29


end_date (floodestimation.entities.PotDataset attribute),10

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

tion.analysis.GrowthCurveAnalysis method),23

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

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

Ggap_length() (floodestimation.entities.PotDataGap

method), 12growth_curve() (floodestima-

tion.analysis.GrowthCurveAnalysis method),22

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

22

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

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

tribute), 8is_suitable_for_pooling (floodestima-

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

tion.entities.Catchment attribute), 7

Kkurtosis (floodestimation.analysis.GrowthCurve at-

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

method), 24

Lldp (floodestimation.entities.Descriptors attribute), 9location (floodestimation.entities.Catchment attribute), 8

Mmethods (floodestimation.analysis.GrowthCurveAnalysis

attribute), 22most_similar_catchments() (floodestima-


Nnearest_qmed_catchments() (floodestima-


nrfa_metadata() (in module floodestimation.fehdata), 15nrfa_to_db() (in module floodestimation.loaders), 17

Oobject (floodestimation.parsers.FehFileParser attribute),

13

Pparams (floodestimation.analysis.GrowthCurve attribute),

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

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

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

tion.parsers.Cd3Parser method), 14parse_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

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), 7pot_data_gaps (floodestimation.entities.PotDataset

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

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

tribute), 11PotDataGap (class in floodestimation.entities), 11PotDataset (class in floodestimation.entities), 10

30 Index


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

Qqmed() (floodestimation.analysis.QmedAnalysis

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

tion.analysis.QmedAnalysis method), 21QmedAnalysis (class in floodestimation.analysis), 20

Rrecord_length() (floodestimation.entities.PotDataset

method), 11rmed_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-

tion.analysis.GrowthCurveAnalysis attribute),22

skew (floodestimation.analysis.GrowthCurve attribute),23

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),

11title (floodestimation.entities.Comment attribute), 12to_db() (in module floodestimation.loaders), 17total_gap_length() (floodestimation.entities.PotDataset

method), 11

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

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

tribute), 9

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

urbext() (floodestimation.entities.Descriptors method), 10urbext1990 (floodestimation.entities.Descriptors at-

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

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

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

tribute), 10userdata_to_db() (in module floodestimation.loaders), 18

Vvar (floodestimation.analysis.GrowthCurve attribute), 23

Wwater_year (floodestimation.entities.AmaxRecord at-

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

tribute), 8

Index 31

Documents

Flood Estimation Library Documentation