Package: pyfunnel
pyfunnelA cross-platform C-based software for comparing two(x, y)data sets given tolerances inxandydirections.PrinciplesOverallA so-called funnel is generated around the reference(x, y)data points.
The funnel is sized according to the absolute or relative tolerance in
bothxandydirections.
The algorithm then checks if any test data points are inside the funnel,
and reports these points in the fileerrors.csvin the output directory.
Four other files are stored in the output directory: reference data points,
test data points, lower bounds and upper bounds of the funnel.One potential application is to validate the development of building
HVAC control sequences. By comparing data curves from real operation with
data curves from simulation, one can verify if the control sequences
have been implemented such that they produce a similar control response
than a simulation model that is considered to be the original specification.Method to Compute the FunnelThe funnel is computed as follows.Tolerance areas (based on L1-norm) are built around each reference data point.The tolerance parameters correspond to the half-width and half-height of the
tolerance areas. They default to 0.When usingatolxandatoly, the tolerance is considered as absolute
(same unit asxandy).When usingltolxandltoly, the tolerance is considered relative
to the local value ofxandy.When usingrtolxandrtoly, the tolerance is considered relative
to the range ofxandy. This option is available mainly for compatibility with
the algorithm implemented incsv-comparefor relative comparison. It should be used with caution.The algorithm selects which corners of the tolerance rectangles
are used to build the envelopes based on the change in the derivative sign at
each reference point.Intersection boundary points are computed when a selected corner
happens not to be in the logical order with the next one on thexscale
(i.e., at a local extremum).
New envelopes are then built encompassing all boundary points, and points strictly
within the envelopes are dropped.The comparison then simply consists of interpolating the upper and lower envelopes
at thextest values and comparing the yieldedy_upandy_lowvalues with theytest values.
By convention, the error ismax(0, y - y_up) - min(0, y - y_low)and hence it is always positive.How to RunSystem RequirementsThe software is tested on the following platforms.Linux x64Windows x64macOSA Python binding is available to access the library. It is compatible with Python 2 and 3.InstallingThe Python binding is delivered as a package namedpyfunnel, available on PyPI.For development, additional dependencies are needed and can be installed withpip install -r requirements.txtMain FunctionsThe software is primarily intended to be used by means of a Python binding.
The packagepyfunnelprovides the following functions.compareAndReport: callsfunnelbinary with list-like objects asx,yreference and test values.
Outputserrors.csv,lowerBound.csv,upperBound.csv,reference.csv,test.csvinto the output directory (./resultsby default).plot_funnel: plotsfunnelresults stored in the directory which path is provided as argument.
Displays plot in default browser. See function docstring for further details.The modulepyfunnel.pycan also be run with the following command line interface.usage: pyfunnel.py [-h] --reference REFERENCE --test TEST [--output OUTPUT] [--atolx ATOLX] [--atoly ATOLY] [--ltolx LTOLX] [--ltoly LTOLY] [--rtolx RTOLX] [--rtoly RTOLY]

Run funnel binary from terminal.

Output `errors.csv`, `lowerBound.csv`, `upperBound.csv`, `reference.csv`, `test.csv` into the output directory (`./results` by default).

optional arguments:
  -h, --help            show this help message and exit
  --output OUTPUT       Path of directory to store output data
  --atolx ATOLX         Absolute tolerance along x axis
  --atoly ATOLY         Absolute tolerance along y axis
  --ltolx LTOLX         Relative tolerance along x axis (relatively to the local value)
  --ltoly LTOLY         Relative tolerance along y axis (relatively to the local value)
  --rtolx RTOLX         Relative tolerance along x axis (relatively to the range)
  --rtoly RTOLY         Relative tolerance along y axis (relatively to the range)

required named arguments:
  --reference REFERENCE
                        Path of CSV file with reference data
  --test TEST           Path of CSV file with test data

Full documentation at https://github.com/lbl-srg/funnelExampleFrom a Python shell with./tests/test_binas the current working directory, run>>>importpandasaspd>>>importpyfunnel>>>ref=pd.read_csv('trended.csv')>>>test=pd.read_csv('simulated.csv')>>>pyfunnel.compareAndReport(xReference=ref.iloc(axis=1)[0],yReference=ref.iloc(axis=1)[1],...xTest=test.iloc(axis=1)[0],yTest=test.iloc(axis=1)[1],atolx=0.002,atoly=0.002)>>>pyfunnel.plot_funnel('results')Or from a terminal with./tests/test_binas the current working directory, run$ python ../../pyfunnel/pyfunnel.py --reference trended.csv --test simulated.csv --atolx 0.002 --atoly 0.002Build from SourceSystem RequirementsThe cross-platform build system relies on CMake version3.11.*.The distributed binaries are built with Microsoft Visual Studio C/C++ compiler
(Windows), Clang (macOS) and GCC (Linux).ProcedureTo compile, link and install, from the top-level directory, run the following commandsmkdir build
cd build
cmake ..                           (add `-A x64` on Windows to compile in 64 bits)
cmake --build . --target install   (add `--config Release` on Windows)To run the tests, from./buildrunctest                               (add `-C Release` on Windows)LicenseModified 3-clause BSD, seeLICENSE.txt.CopyrightSeeCOPYRIGHT.txt.