Package: objective-thresholds
OBJECTIVE LOW FLOW THRESHOLD IDENTIFICATION USING BREAKPOINT ANALYSISDescriptionobjective_thresholdsis a Python package for objective threshold level calculation based on a flow duration curve (FDC). At the time of publication this package contains tools for threshold calculation for low flow analysis, contained in the accompanyinglowflowmodule. The functions included in the module allow for the computation of a single threshold value (functionthreshold) on a given lower range of the FDC, or multiple (functionmultiple) thresholds if additional division is needed (i.e., “shallow” and “deep” low flows). Further implementations and modules will be added in the future to allow for additional threshold calculations and analysis at full range of FDC.How to cite.If you useobjective_thresholdsin a scientific publication, please include the reference below:Raczyński K., Dyer J., 2022, Development of an Objective Low Flow Identification Method Using Breakpoint Analysis, Journal to be determined, XX(XX), doi: XXXX.XX/XX.XX/xx.Website:Official repository website address:https://github.com/chrisrac/objective_thresholds/InstallationWith pip:
pip install objective_thresholdsDependenciesTheobjective_thresholdspackage requires the following:Python 3.4+PandasNumPyJenkspyUsageTheobjective_thresholdspackage currently includes the modulelowflowwith two functions available. To use the package, once installed it should be imported to Python:
import objective_thresholds.lowflow as olf
The functionthresholdallows for the computation of low flow thresholds using breakpoints through the application of the Fisher-Jenks algorithm, which is applied to the lower range of the FDC (calculated from provided dataset:input_data).  By default, the lowest 35% of the FDC is used for low flow threshold calculations, and one threshold value is returned. The function accepts as input any array-like data, including: lists, pandas Series, numpy array, or slices of pandas DataFrame. Optionally, thelimitof the lower FDC can be set by the user if a value other than the default 35thpercentile is needed. If the input data are highly discretized (contains numerous repetitive values), themethodargument controls the result:
•leave– breaks the computation, Exception is returned;
•max– the maximum value in the lower FDC range is returned;
•median– the median value in the lower FDC range is returned.
Thethresholdfunction returns one float or int type value representing the identified threshold, depending on the input data type. Some examples of usage:# importing lowflow module from objective_thresholds package>>>importobjective_thresholds.lowflowasolf>>>importpandasaspd# importing example data from testdata.csv file (available at source repository)>>>data=pd.read_csv('home/testdata.csv')# checking data structure>>>data.head()idflow1flow2002.712.84110.310.34220.160.18330.230.26440.260.28# calculating threshold value for first data series using default settings (35th percentile; limit=0.35)>>>threshold_value=olf.threshold(data['flow1'])# results in: 0.13# modifying range of lower FDC to 50th percentile>>>threshold_50p=olf.threshold(data['flow1'],limit=0.5)# results in: 0.19# an Exception is raised if fewer than 5 unique values are present>>>threshold_10p=olf.threshold(data['flow2'],limit=0.10)Exception:UniquevaluesoflowerFDCrangearelessthan5andusedmethodis"leave",nothresholdsarereturned.# controlling output by changing the method for discretized datathreshold_max=olf.threshold(data['flow2'],limit=0.10,method='max')# results in: 0.11The functionmultipleallows for the computation of multiple low flow thresholds using breakpoints through the application of the Fisher-Jenks algorithm, which is applied to the lower range of the FDC (provided asinput_data).  By default, the lowest 35% of the FDC is used for low flow threshold calculations, and multiple threshold values are returned. This function is to be used when at least two thresholds are needed, such as when dividing the lower FDC range into “shallow” and “deep” low flow events. The function accepts as input any array-like data, including: lists, pandas Series, numpy array, or slices of pandas DataFrame. Argument breaks controls the number of thresholds to be returned.  Optionally, thelimitof the lower FDC can be set by the user if a value other than the default 35thpercentile is needed.. If the input data are highly discretized (contains numerous repetitive values), themethodargument controls the result:
•leave– breaks the computation, Exception is returned;
•max– the maximum value in the lower FDC range is returned;
•median– the median value in the lower FDC range is returned.
Note that the implementation of the max or median arguments causes themultiplefunction to return a single value, regardless of the number of breakpoints requested.
Themultiplefunction returns a list of float or int type values, depending on the input data type, representing the identified thresholds. Some examples of usage:# importing lowflow module from objective_thresholds package>>>importobjective_thresholds.lowflowasolf>>>importpandasaspd# importing example data from testdata.csv file (available at source repository)>>>data=pd.read_csv('home/testdata.csv')# checking data structure>>>data.head()idflow1flow2002.712.84110.310.34220.160.18330.230.26440.260.28# calculating threshold value for first data series using default settings (limit=0.35; breaks=2)>>>threshold_value=olf.multiple(data['flow1'])# results in: [0.1, 0.16]# modifying range of lower FDC to 50th percentile>>>threshold_50p=olf.multiple(data['flow1'],limit=0.5)# results in: [0.14, 0.24]# modifying the number of thresholds to be returned>>>threshold_3th=olf.multiple(data['flow1'],breaks=3)# results in: [0.09, 0.13, 0.17]# an Exception is raised if fewer than 5 unique values are present>>>threshold_10p=olf.multiple(data['flow2'],limit=0.10)Exception:UniquevaluesoflowerFDCrangearelessthan5andusedmethodis"leave",nothresholdsarereturned.# controlling output by changing the method for discretized datathreshold_max=olf.multiple(data['flow2'],limit=0.10,method='median',breaks=6)# results in: 0.08 as only one value is returned by max or median method, regardless of breaks settingLicenseCopyright (c) 2022, Raczynski K., Dyer J.Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.