Repository files navigation

A Python/C(++) implementation of Hartigan & Hartigan's dip test for unimodality.

The dip test measures multimodality in a sample by the maximum difference, overall sample points, between the empirical distribution function, and theunimodal distribution function that minimizes that maximum difference. Otherthan unimodality, it makes no further assumptions about the form of the nulldistribution.

This library provides two functions:

• dipstat
• diptest

The first only computes Hartigan's dip statistic.diptest computes both thestatistic and the p-value. The p-value can be computed using interpolation of acritical value table (default) or by bootstrapping the null hypothesis.Note that for larger samples (N > 1e5) this is quite compute and memory intensive.

importnumpyasnpimportdiptest# generate some bimodal random drawsN=1000hN=N//2x=np.empty(N,dtype=np.float64)x[:hN]=np.random.normal(0.4,1.0,hN)x[hN:]=np.random.normal(-0.4,1.0,hN)# only the dip statisticdip=diptest.dipstat(x)# both the dip statistic and p-valuedip,pval=diptest.diptest(x)

• numpy
• [Optional]OpenMP

Parallelisation of the p-value computation using bootstrapping is offered using OpenMP.OpenMP is disabled by default but can be enabled, see installation sectionbelow.Multi-threading can be turned off by setting the number of threads equal to 1. See the docstring ofdiptest for details.

diptest can be installed from PyPi using:

    pip install diptest

Wheels containing the pre-compiled extension are available for:

• Windows x84-64 - CPython 3.8 - 3.12
• Linux x84-64 - CPython 3.8 - 3.12
• MacOS x84-64 - CPython 3.8 - 3.12
• MacOS ARM-64 - CPython 3.8 - 3.12

Note that the wheels vendor/ships OpenMP with the extension to provide parallelisation out-of-the-box.If you run into issue with multiple versions of OpenMP being loaded you have two options: build from source or install a non-bundled wheel.

We provide the same wheels without OpenMP bundled here:https://github.com/RUrlus/diptest/releasesYou than install the wheel that corresponds to your Python and OS.For example, for CPython 3.11 and MacOS ARM:

pip install diptest-0.8.0-cp311-cp311-macosx_11_0_arm64.whl

If you have a C/C++ compiler available it is advised to install withoutthe wheel as this enables architecture specific optimisations.

    pip install diptest --no-binary diptest

Compatible compilers through Pybind11:

• Clang/LLVM 3.3 or newer (for Apple Xcode's clang, this is 5.0.0 or newer)
• GCC 4.8 or newer
• Microsoft Visual Studio 2015 Update 3 or newer
• Intel classic C++ compiler 18 or newer (ICC 20.2 tested in CI)
• Cygwin/GCC (previously tested on 2.5.1)
• NVCC (CUDA 11.0 tested in CI)
• NVIDIA PGI (20.9 tested in CI)

To disable OpenMP use:

    SKBUILD_CMAKE_ARGS="-DDIPTEST_DISABLE_OPENMP=ON" pip install diptest --no-binary diptest

To enable a debug build use:

    SKBUILD_CMAKE_ARGS="-DCMAKE_BUILD_TYPE=Debug" pip install diptest --no-binary diptest

To enable the debug print statements use:

    SKBUILD_CMAKE_ARGS="-DDIPTEST_ENABLE_DEBUG=ON" pip install diptest --no-binary diptest

then call the function with debug argument set to a value greater than zero:

diptest(x,debug=1)

Hartigan, J. A., & Hartigan, P. M. (1985). The Dip Test of Unimodality. TheAnnals of Statistics.

Hartigan, P. M. (1985). Computation of the Dip Statistic to Test forUnimodality. Journal of the Royal Statistical Society. Series C (AppliedStatistics), 34(3), 320-325.

diptest is just a Python port ofMartin Maechler's R module of the samename.The package wrapping the C implementation was originally written byAlistair Muldal.The fork is an update with a number of changes:

• Fixes a buffer overrun issue in_dip.c by reverting to the original C implementation
• Python bindings using Pybind11 (C++) instead of Cython
• P-value computation using bootstrapping has been moved down to C++ with optional parallelisation support through OpenMP
• Removed overhead caused by debug branching statements by placing them under a compile-time definition
• Added tests and wheel support
• C implementation of diptest was rewritten in C++ byProdromos Kolyvakis

diptest is free software: you can redistribute it and/or modify it under theterms of the GNU General Public License as published by the Free SoftwareFoundation, either version 3 of the License, or (at your option) any laterversion.