Model-Free Functional Chi-Squared and Exact Tests

Statistical hypothesis testing methods for inferring model-free functional dependency using asymptotic chi-squared or exact distributions. Functional test statistics are asymmetric and functionally optimal, unique from other related statistics. Tests in this package reveal evidence for causality based on the causality-by- functionality principle. They include asymptotic functional chi-squared tests (Zhang & Song 2013) , an adapted functional chi-squared test, and an exact functional test (Zhong & Song 2019) (Nguyen et al. 2020) . The normalized functional chi-squared test was used by Best Performer 'NMSUSongLab' in HPN-DREAM (DREAM8) Breast Cancer Network Inference Challenges (Hill et al. 2016) . A function index (Zhong & Song 2019) (Kumar et al. 2018) derived from the functional test statistic offers a new effect size measure for the strength of functional dependency, a better alternative to conditional entropy in many aspects. For continuous data, these tests offer an advantage over regression analysis when a parametric functional form cannot be assumed; for categorical data, they provide a novel means to assess directional dependency not possible with symmetrical Pearson's chi-squared or Fisher's exact tests.



Version 2.4.5-3 2018-12-04

  1. Updated simulate_tables() function to be more accurate when generating small tables where row and column variables are independent. Specifically, zero counts are now allowed.
  2. Updated tests for simulate_tables() in test_simulate.R.
  3. Introduced simulate_independent_tables() by reorganizing preivous code. Noise is now applied along both rows and columns (previously only along the rows). The funciton is in simulate_tables.R.
  4. Modified prelim.check() in simulate_tables.R.
  5. Updated manual page for simulate_tables() accordingly.
  6. Updated the examples in the manual of plot_tables().


  1. Added an argument in plot_table() to highlight row maxima with a box.


  1. Created version 2.4.5-3.
  2. Made "conditional function index" the default, previously "unconditional", in fun.chisq.test(). Specifically, set the default value of index.kind to "conditional". Previous "conditional function index", specified by index.kind="conditional", is now called "function index"; previous "function index", specified by index.kind="unconditional" is now called "unconditional function index". The "unconditional" option for function index will phase out in future versions of the function.
  3. Added a new vignette "Examples of discrete patterns".
  4. Updated vignettes to include table visualization by plot_table() function.

Version 2.4.5-2 2018-10-22

  1. Reintroduced a test source code file test_FunChisq.R back, which was accidentally deleted from the previous version.


  1. Added a plot_table() function to visualize a contingency table.


  1. Created version 2.4.5-2.
  2. Included conditional FunChisq R code.

Version 2.4.5-1 2018-06-16

  1. In the exact functional test C++ code, improved the numerical precision of the FunChisq statistic using an equivalent mathematical form already used in the R version. This fixed bugs in the exact functional test when the table is of certain dimension and sample size.

  2. Added a few more test cases for the exact functional test.

  3. Increased the maximum table size from 5x5 to 10x10 for the exact functional test.

  4. Added a warning message when asymptotic test is used in place of the exact test to avoid long computational time.

  5. Updated the DOI of the reference to exact functional test.

Version 2.4.5 2018-02-08

  1. Added a parameter "exact.mode.bound" in the fun.chisq.test() function to switch ON/OFF the fast branch-and-bound algorithm in the exact functional test.
  2. Updated testthat cases for exact functional test.

Version 2.4.4 2018-02-05

  1. Added a new reference (Zhong and Song, 2018) for exact functional test.
  2. Changed the package title to "Chi-Square and Exact Tests for Model-Free Functional Dependency"


  1. Included a reference for the simulate_tables() function that describes the strategies used by the function.


  1. Updated the functional indices to be more accurate when the number of row is less than the number of columns and also when conditioned on the column sum.


  1. Added "simulate.p.value" method option in fun.chisq.test() to calculate p-value with Monte carlo simulated distribution.


  1. Updated the vignette for choosing quantities for functional dependencies.


  1. Fixed a bug in simulating 'discontinuous' contingency tables when the number of column is two.
  2. Updated manuals.

Version 2.4.3 2017-04-27

  1. Fixed a bug in specifying the margin to apply noise in simulate_tables().
  2. Added a noise.model parameter in simulate_tables() to specify either the "house" or "candle" noise model for applying noise to contingency tables representing ordinal or categorical data.


  1. Revised package description and manuals.

Version 2.4.2 2017-04-20

  1. Renamed pattern type "nonmonotonic" to "" in simulate_tables(). The latter is mathematically correct.
  2. Added a "discontinuous" pattern type in simulate_tables().
  3. Added a new candle noise model for categorical variables.
  4. Sped up add.noise function code by taking advantage of vectorized multinomial distribution R function.

Version 2.4.1 2017-04-02

  1. Revised the manual for function simulate_tables()


  1. Suppressed warning messages when calling chisq.test() to compute chi-squares in function simulate_tables().
  2. Edited the manual for simulate_tables().
  3. Edited other manuals for improved consistency with R package reference format.

Version 2.4.0 2017-02-26 Changes

  1. Added a new R function simulate_tables() with supporting test functions.
  2. Added a new R function with supporting test functions.
  3. Introduced the use of 'R_registerRoutines' and 'R_useDynamicSymbols'.

Version 2.3.4 Changes 2016-10-01

  1. Added keywords to the package manual.

Version 2.3.3 Changes 2016-09-02

  1. Updated the vignettes.

Version 2.3.2 Changes 2016-08-29

  1. Updated the reference section to fix the year of Pearson's chi-square test paper which was published in 1900 not 1990.


  1. Now check all options for the method argument so that only valid methods are allowed.

Version 2.3.1 Changes 2016-05-01

  1. Expanded test.interactions() to test many-to-one combinatorial interactions in C++ via Rcpp.

Version 2.3.0 (not deposited to CRAN) Changes 2016-04-30

  1. Data frame input is now converted to numeric matrix before exact functional test.
  2. Added function test.interactions() to test pairwise (one-to-one) interactions, implemented in C++ via Rcpp for computational efficiency.

Version 2.2.4 Changes 2016-04-21

  1. Added vignette "Which statistic to use for functional dependency from fun.chisq.test()?"
  2. Updated references and description.

Version 2.2.3 Changes 2016-03-31

  1. Use [[Rcpp::export]] to automatically generate R interface.


  1. Revised the code to remove dependency on RcppClassic.


  1. Revised help documentation and included new references.

Version 2.2.2 Changes 2016-02-07

  1. Handled a special case for the normalized FunChisq when the degrees of freedom are zero.


  1. Renamed the "type" argument to "alternative" in fun.chisq.test().
  2. Revised values of the "method" argument in fun.chisq.test(). Previous values ("default" and "normalized") are still supported but obsolete.
  3. Added the "log.p" argument in both and cp.chisq.test().
  4. Updated the documentation.


  1. Added a new argument "index.kind" to fun.chisq.test() to specify the function index kind: "unconditional" or "conditional" on a given marginal of Y.


  1. Fixed a bug in cp.chisq.test().

Version 2.2.1 Changes 2016-01-25

  1. Fixed a bug introduced in the previous version.
  2. Updated package description to be more reflective of recent additions.
  3. Included missing references.

Version 2.2.0 Changes 2016-01-23

  1. Improved code efficiency for fun.chisq.test().
  2. Now fun.chisq.test() returns an estimate of function index between 0 and 1, in analogy to Cramer's V, but asymmetrical.
  3. Added additional test examples for fun.chisq.test().


  1. Added type argument to fun.chisq.test() to specify functional or non-constant functional chi-squares.
  2. Added log.p argument to fun.chisq.test() to obtain log of p-value to improve accuracy when sample size is large and p-value is close to zero.

2015-07-03 (Unpublished version 2.1.1 )

  1. Added cp.chisq.test() for comparative chi-square test, not considering functional dependencies.
  2. Added test examples for cp.chisq.test().

Version 2.1.0 2015-06-29 Changes

  1. Substantially reduced the run time of exact functional test by designing a better branch and bound strategy.
  2. Enabled C++11 compling by adding two files (Makevars and
  3. Fixed a bug occured under WIN32 using long double by adding define.h to specify double precision for WIN32 and long double precision for WIN64.
  4. Increased float comparison precision by considering a tolerance.
  5. Imported pnorm() and pchisq() from the "stats" package.

Version 2.0.2 2015-03-03 Changes

  1. Updated documentation for the package and its functions.
  2. Fixed a testing issue under r-release-linux-ix86 flavor.

Version 2.0.1 2015-02-23 Changes

  1. Removed assert() function from StatDistribution.cpp.
  2. Removed Makevar and files.
  3. Removed all iostream and sstream and cassert.
  4. Removed TransitionTableIO.cpp.
  5. In the testthat examples, signif(x,8) is used to compare 8 significant digits of the results.
  6. Added a normalized functional chi-square test example.

Version 2.0.0 2015-02-12 Changes

  1. Added a new exact functional test as a method option to fun.chisq.test(). The exact functional test is an exact version of FunChisq test, it is more precise to detect functional dependencies in small sample-sized contingency tables.
  2. Added a new comparative functional chi-square test for detecting heterogeneity in functional dependencies among contingency tables.
  3. Revised the examples and documentation to improve usability.
  4. Added automated test cases into the package.
  5. Started the NEWS file.

Version 1.0 2014-03-08 Changes

  1. The first release of this package implements the functional chi-square test and a normalized version.

Reference manual

It appears you don't have a PDF plugin for this browser. You can click here to download the reference manual.


2.5.2 by Joe Song, 8 months ago

Browse source code at

Authors: Yang Zhang [aut] , Hua Zhong [aut] , Hien Nguyen [aut] , Ruby Sharma [aut] , Sajal Kumar [aut] , Joe Song [aut, cre]

Documentation:   PDF Manual  

LGPL (>= 3) license

Imports Rcpp, Rdpack, stats, dqrng

Suggests Ckmeans.1d.dp, DescTools, DiffXTables, GridOnClusters, infotheo, knitr, rmarkdown, testthat

Linking to BH, Rcpp

Suggested by DiffXTables, GridOnClusters.

See at CRAN