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.
Squirrelhas 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.arcsinedistribution is a specialization of the
scipy.stats.betadistribution. 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.
Find an already existing distribution similar to
Squirrel. Use its code as a template for
Read the docstring for class
Write the new code for class
squirrel_genand 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
bneed to be specified in the call to
squirrel_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.
squirrel_gen.ppf()is expensive to compute relative to
squirrel_gen.pdf(), consider setting the
momtypein the call to
squirrel_gen.rvs()is expensive to compute, consider implementing a specific
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
distcontlist 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.
TestSquirrelclass and any specific tests to scipy/stats/tests/test_distributions.py.
Run and pass(!) the tests.
Add a tutorial
Add it to the listing of continuous distributions in doc/source/tutorial/stats/continuous.rst.
number of continuous distributionsin the example code in doc/source/tutorial/stats.rst.
Build the documentation successfully.
Submit a PR.
Johnson, Kotz, and Balakrishnan, “Continuous Univariate Distributions, Volume 1”, Second Edition, John Wiley and Sons, p. 173 (1994).