curves
— Interpolation Curves¶
This module provide classes and helper functions to define interpolation curves and to interpolate values on such curves.
Variables and exception classes¶

curves.
MINDATE
¶ Midnight of the 1st January of the
datetime.MINYEAR
that is 1/1/1 00:00. It is used as default start_date forTransientCurve
objects.

curves.
MAXDATE
¶ Midnight of the 31rd December of the
datetime.MAXYEAR
that is 31/12/9999 00:00. It is used as default end_date forTransientCurve
objects.

NoInterpolCurveError:
The exception class for invalid interpolation in
TransientCurveList
objects denoting usually the imposibility to find a validTransientCurve
for a specified date.
Helper functions¶

curves.
read_meta_line
(fp)¶ Read one line from a file format header and return a (name, value) tuple, where name is lowercased. Returns (‘’, ‘’) if the next line is blank. Raises
ParsingError
if next line infp
is not a valid header line. (source code Copied from pthelma, time series class)
CurvePoint objects¶
Represents a point of a InterpolatingCurve
.
A point of a curve is defined by its two coordinates, which are named
independent
and dependent
, rather than X and Y, because
in stagedischarge curves the independent variable (stage) is plotted
vertically, and X and Y would be confusing.

class
curves.
CurvePoint
(independent, dependent)¶ 
independent
¶ The independent variable of the point (usually the abscissa or X).

dependent
¶ The dependent variable of the point (usually the ordinate or Y).

__eq__
(other)¶ Equality test between two
CurvePoint
instances (theself
and theother
).__eq__()
is a special class method, so you don’t have to call it. It is defined only to allow equality test like:point1==point2
. Two points are equal only and if only their coordinates differ less or equal than 0.001 that isx1x2<=0.001 AND y1y2<=0.001
.

v
([reverse=False])¶ Return coordinates as a tupple of (
independent
,dependent
) values. If parameterreverse
is set toTrue
returns the tuple in the reversed order.

InterpolatingCurve objects¶
Stores a curve representing the relationship between an independent and a dependent variable.
Use InterpolatingCurve
to store curves for stagedischarge,
dischargesediment discharge, reservoir stagesurface area, reservoir
stagevolume, and so on. InterpolatingCurve
has properties
for storing these curves and methods for interpolating values in the
curves.
A curve is defined by a set of points, an offset point, and a boolean specifying whether to interpolate with linear or with power functions.
Interpolating curve acts like Python lists. If a is an interpolating
curve, you can access curve points with a[0], a[1], …. To delete
a single point: del(a[1]). Slicing is valid. To delete all curve
points use del(a[:]). a[0]=point is valid only if point is a valid
CurvePoint
class object. The same for a[0:2] = [point1, point2].
len(a) is the total points count etc.

class
curves.
InterpolatingCurve
([logarithmic=False][, offset=CurvePoint(0,0)])¶ 
logarithmic
¶ Specifies whether the interpolation should be done with power function. Set
logarithmic
toTrue
to specify that the interpolation between points is to be done with power functions, and toFalse
to specify linear interpolation. Iflogarithmic
isTrue
, the curve’s segments appear as straight lines on loglog charts; otherwise, they appear as straight lines on linear charts.

offset
¶ Specifies the offsets for log curves.
offset
is aCurvePoint
object and it is used only iflogarithmic
isTrue
, and specifies the points at which the curve crosses the zero axes. For example, if X is the independent variable and Y is the dependent, then the curve crosses the X axis at point (X0, 0), where X0=``offset.independent``.

add
(*args)¶ Add
CurvePoint
objects to the list. If*args
contains only one argument, this should be aCurvePoint
object. If*args
contains two values, these should be the independent, dependent values, with this order. If*args
number is not 1 or 2 then aTypeError
is raised.

index
(value)¶ Returns the list index number of a curve point with
value
.value
should be aCurvePoint
object or else aTypeError
is raised.

insert
(i, value)¶ Insert the
value
at (before) thei
th position of the point list. value should be aCurvePoint
object or else aTypeError
is raised.

first
()¶ Retuns the first item of the curve points list. Equivalent with
curve[0]
.

last
()¶ Returns the last item of the curve points list. Equivalent with
curve[len(curve)1]
.

value_over_curve
(value[, reverse=False])¶ Check if
value
is greater than the last independent value of the curve. Ifreverse
is set toTrue
, dependent value is used instead of independent.

value_in_curve_range
(value[, reverse=False])¶ Check if
value
is between first and last curve point independent values. Ifreverse
is set toTrue
, dependent value is used instead of independent.

read_line
(line[, columns=(0, 1)])¶ Parse independent and dependent values from a string line. Values are separated by comma (,). Parsed values are added to the curve list by the
add()
method. By default the two first columns are read. If you specify a two integer values tuple other than (0,1), then these columns are used to parse values.

read_fp
(fp[, columns=(0, 1)])¶ Read points using the
read_line()
method from a filelike objectfp
. Parsing stops when EOF is reached or an empty line is read.read_fp()
does not clear the items list before reading.

interpolate
(value[, reverse=False])¶ Interpolates a value in the curve.
Call
interpolate()
to interpolate a value assumed as independent variable, in the curve and determine the corresponding value for the dependent variable. If the specified value lies outside the segments of the curve, extrapolation is performed.If
logarithmic
isTrue
, one of the points can be Offset. Although this is a valid, using it for interpolation would mean taking the logarithm of zero. Thus, the point is ignored; if the value must be interpolated in a segment havingoffset
as one of its ends, it is, instead, extrapolated in an adjacent segment. The result should be mathematically correct.If
logarithmic
isTrue
andvalue
to be interpolated plus theoffset
is less or equal than zero (offset+value<=0
), then afloat("NaN")
is return.If
reverse
set toTrue
, a reverse interpolation is performed (seereverseinterpolate()
)

reverseinterpolate
(value)¶ reverseinterpolate(value)
is equivalent withinterpolate(value, True)
. Determines the value of the independent variable given the value of the dependent variable.reverseinterpolate()
is the opposite ofinterpolate()
; it interpolates a value for the dependent variable into the curve and returns the corresponding value for the independent variable.reverseinterpolate()
will only work correctly if the curve represents a reversible function, i.e., if one and only one value of the independent variable corresponds to any given value of the dependent variable. If this condition does not hold, the behavior ofreverseinterpolate()
will be undefined (it will probably return one of the possible answers).The remarks in
interpolate()
about extrapolation are also true forreverseinterpolate()
.

TransientCurve objects¶
Stores a InterpolatingCurve
with a period of validity.
TransientCurve
is a InterpolatingCurve
class with the
additional properties start_date and end_date, which specify the period
of validity of this curve. TransientCurve
is useful for representing
stagedischarge curves.

class
curves.
TransientCurve
([logarithmic=False][, offset=CurvePoint(0,0)][, extension_line=False][, start_date=MINDATE][, end_date=MAXDATE])¶ 
logarithmic
¶

offset
¶ Inherited properties from
InterpolatingCurve
class. See the above class documentation for details.

extension_line
¶ Specifies a curve as extension line, usefull for stagedischarge curves definition.

start_date
¶ The starting date of the validity period for the curve. If no
start_date
specified thenMINDATE
is considered.

end_date
¶ The ending date of the validity period for the curve. If no
end_date
specified thenMAXDATE
is considered.

read_fp
(fp[, columns=(0, 1)])¶ Read meta and data from the filelike object
fp
. Meta and data sections are divided by a blank (empty) line. Meta section is formated in thename=value
style. Available meta tags to be parsed are:start_date
orstartdate
,end_date
orenddate
,logarithmic
,extension
,offset
, all are case insensitive. Dates are formated according to ISO:yyyymmdd HH:MM
,offset
is a floating point value and boolean values can beTrue
(case insensitive) in order to be activated. After meta section, data are read by the inheritedInterpolatingCurve.read_fp()
method.

TransientCurveList objects¶
Stores a set of curves.
TransientCurveList
stores a set of curves and provides interpolating
functions that interpolate a value to the chronologically appropriate
TransientCurve
. TransientCurveList
is mostly useful for sets of
stagedischarge curves.
TransientCurveList
acts exactly like a python list with items
of TransientCurve
objects. (See InterpolatingCurve
documentation for usage on list methods).

class
curves.
TransientCurveList
¶ 
addcurve
(curve)¶ Add the
TransientCurve
curve into the curve list by appending it. curve should be aTransientCurve
or else aTypeError
is raised.

add
([logarithmic=False][, offset=CurvePoint(0,0)][, extension_line=False][, start_date=MINDATE][, end_date=MAXDATE])¶ Creates a new
TransientCurve
, then adds it to the curve list by callingaddcurve()
method. SeeTransientCurve
for attributes description.

index
(value)¶ Returns the list index number of a curve point with value of value. value should be a
TransientCurve
object or else aTypeError
is raised.

insert
(i, value)¶ Insert the value at (before) the ith position of the point list. value should be a
TransientCurve
object or else aTypeError
is raised.

first
()¶ Retuns the first item of the curve points list. Equivalent with
list[0]
.

last
()¶ Returns the last item of the curve points list. Equivalent with
list[len(list)1]
.

find
(date[, extension_line=False])¶ Returns the appropriate
TransientCurve
curve for the specified datedate
searching in the list for nonextension lines. Ifextension_line
is set toTrue
, then the searching is executed only on extension lines of the list.

has_extension_lines
()¶ Returns
True
if extension lines are included in the list.

interpolate
(date, value)¶ Interpolate value
value
by choosing an appropriate curve fordate
date from the list. If value is less or equal than the last independent value for a normal curve, then the interpolation is done on the normal curve. If value is greater than that point then if no extension curves are defined, extrapolation is beeing performed. If extension curves exist, two cases are assessed: In the first case the value lies between the last point of the normal curve and the first point of the extension curve, an interpolation is performed between these two points. In the second case, the extension curve is used to do interpolation.Interpolation operations are performed with the help of the
InterpolatingCurve.interpolate()
method.

interpolate_ts
(timeseries)¶ Interpolates the values of a
timeseries.Timeseries
object. Both date and value of each timeseries record is beeing used in order to choose the appropriate curve and then applicate the interpolation algorithm on that curve. Null values give null values as well. The result is return by a new time series object holding the interpolated values. Calculations are performed with theinterpolate()
method of the current Class.

read_fp
(fp)¶ Load curve list data by reading the filelike object
fp
. A meta section is read then several curve data are read byTransientCurve
TransientCurve.read_fp()
. Curve data are separated from meta data by an empty (blank) line. The only meta data value parsed iscount
(case insensitive) holding the total number ofTransientCurve
objects in the list. All other meta data is ignored.read_fp()
does not clear the items list before reading.
