Adding New Methods, Functions, and Classes#
While adding code to SciPy is in most cases quite straight forward, there are a few places where that is not the case. This document contains detailed information on some specific situations where it may not be clear from the outset what is involved in the task.
Adding A New Statistics Distribution#
For hundreds of years statisticians, mathematicians and scientists have needed to understand, analyze and model data. This has led to a plethora of statisics distributions, many of which are related to others. Modeling of new types of data continues to give rise to new distributions, as does theoretical considerations being applied to new disciplines. SciPy models about a dozen discrete distributions Discrete Statistical Distributions and 100 continuous distributions Continuous Statistical Distributions.
To add a new distribution, a good reference is needed. Scipy typically uses [JKB] as its gold standard, with WikipediaDistributions articles often providing some extra details and/or graphical plots.
How to create a new continuous distribution#
There are a few steps to be done to add a continuous distribution to SciPy. (Adding a discrete distribution is similar). We’ll use the fictitious “Squirrel” distribution in the instructions below.
Before Implementation#
See if
Squirrel
has already been implemented–that saves a lot of effort!It may have been implemented with a different name.
It may have been implemented with a different parameterization (shape parameters).
It may be a specialization of a more general family of distributions.
It is very common for multiple disciplines to discover/rediscover a distribution (or a specialization or different parameterization). There are a few existing SciPy distributions which are specializations of other distributions. E.g. The
scipy.stats.arcsine
distribution is a specialization of thescipy.stats.beta
distribution. These duplications exist for (very!) historical and widespread usage reasons. At this time, adding new specializations/reparametrizations of existing distributions to SciPy is not supported, mainly due to the increase in user confusion resulting from such additions.Create a SciPy Issue on github, listing the distribution, references and reasons for its inclusion.
Implementation#
Find an already existing distribution similar to
Squirrel
. Use its code as a template forSquirrel
.Read the docstring for class
rv_continuous
in scipy/stats/_distn_infrastructure.py.Write the new code for class
squirrel_gen
and insert it into scipy/stats/_continuous_distns.py, which is in (mostly) alphabetical order by distribution name.Does the distribution have infinite support? If not, left and/or right endpoints
a
,b
need to be specified in the call tosquirrel_gen(name='squirrel', a=?, b=?)
.If the support depends upon the shape parameters,
squirrel_gen._get_support()
needs to be implemented.The default inherited
_argcheck()
implementation checks that the shape parameters are positive. Create a more appropriate implementation.If
squirrel_gen.ppf()
is expensive to compute relative tosquirrel_gen.pdf()
, consider setting themomtype
in the call tosquirrel_gen()
.If
squirrel_gen.rvs()
is expensive to compute, consider implementing a specificsquirrel_gen._rvs()
.Add the name to the listing in the docstring of scipy/stats/__init__.py.
Add the name and a good set of example shape parameters to the
distcont
list in scipy/stats/_distr_params.py. These shape parameters are used both for testing and automatic documentation generation.Add the name and an _invalid_ set of example shape parameters to the list in
invdistcont
, also in _distr_params.py. These shape parameters are also used for testing.Add a
TestSquirrel
class and any specific tests to scipy/stats/tests/test_distributions.py.Run and pass(!) the tests.
After Implementation#
Add a tutorial
doc/source/tutorial/stats/continuous_squirrel.rst
Add it to the listing of continuous distributions in doc/source/tutorial/stats/continuous.rst.
Update the
number of continuous distributions
in the example code in doc/source/tutorial/stats.rst.Build the documentation successfully.
Submit a PR.
References#
Johnson, Kotz, and Balakrishnan, “Continuous Univariate Distributions, Volume 1”, Second Edition, John Wiley and Sons, p. 173 (1994).