TwoPiece Distributions Implementation
Project description
twopiece: TwoPiece Distributions
 Homepage: https://github.com/quantgirluk/twopiece
 Pip Repository: twopiece
 Demo: Python Notebook
Overview
The twopiece library provides a Python implementation of the family of Two Piece distributions. It covers three subfamilies TwoPiece Scale, TwoPiece Shape, and Double TwoPiece. The following diagram shows how these families relate.
TwoPiece Scale
The family of two–piece scale distributions is a family of univariate three parameter locationscale models, where skewness is introduced by differing scale parameters either side of the mode.
Definition. Let $f: \mathbb{R} \mapsto \mathbb{R}_{+}$ be a unimodal symmetric (around zero) probability density function (pdf) from the locationscale family, possibly including a shape parameter $\delta$. Then, the pdf of a member of the twopiece family of distributions is given by
$$ s\left(x; \mu,\sigma_1,\sigma_2, \delta\right) = \begin{cases} \dfrac{2}{\sigma_1+\sigma_2}f\left(\dfrac{x\mu}{\sigma_1};\delta\right), \mbox{if } x < \mu, \ \dfrac{2}{\sigma_1+\sigma_2}f\left(\dfrac{x\mu}{\sigma_2};\delta\right), \mbox{if } x \geq \mu. \ \end{cases} $$
Example. If $f$ corresponds to the normal pdf, then $s$ corresponds to the pdf of the TwoPiece Normal distribution as proposed by Gustav Fechner in 1887.
TwoPiece Shape
The family of two–piece shape distributions is a family of univariate three parameter locationscale models, where skewness is introduced by differing shape parameters either side of the mode.
Definition. Let $f: \mathbb{R} \mapsto \mathbb{R}_{+}$ be a unimodal symmetric (around 0) probability density function (pdf) from the locationscale family which includes a shape parameter $\delta$. Then, the pdf of a member of the twopiece family of distributions is given by
$$ s\left(x; \mu,\sigma,\delta_1 \delta_2\right) = \begin{cases} \dfrac{2\epsilon}{\sigma}f\left(\dfrac{x\mu}{\sigma};\delta_1\right), \mbox{if } x < \mu, \ \dfrac{2(1 \epsilon)}{\sigma}f\left(\dfrac{x\mu}{\sigma};\delta_2\right), \mbox{if } x \geq \mu. \ \end{cases} $$
where
$$ \epsilon = \dfrac{f(0;\delta_2)}{f(0;\delta_1)+f(0;\delta_2)}. $$
Example. If $f$ corresponds to the Studentt pdf, then $s$ corresponds to the pdf of the TwoPiece Shape Studentt distribution. Note that $s$ has different shape parameter on each side mode but the same scale.
Double TwoPiece
The family of double two–piece distributions is obtained by using a density–based transformation of unimodal symmetric continuous distributions with a shape parameter. The resulting distributions contain five interpretable parameters that control the mode, as well as both scale and shape in each direction.
Definition. Let $f: \mathbb{R} \mapsto \mathbb{R}_{+}$ be a unimodal symmetric (around 0) probability density function (pdf) from the locationscale family which includes a shape parameter $\delta$. Then, the pdf of a member of the twopiece family of distributions is given by
$$ s\left(x; \mu,\sigma_1,\sigma_2, \delta_1, \delta_2 \right) = \begin{cases} \dfrac{2\epsilon}{\sigma_1}f\left(\dfrac{x\mu}{\sigma_1};\delta_1\right), \mbox{if } x < \mu, \ \dfrac{2(1 \epsilon)}{\sigma_2}f\left(\dfrac{x\mu}{\sigma_2};\delta_2\right), \mbox{if } x \geq \mu. \ \end{cases} $$
where
$$ \epsilon = \dfrac{\sigma_1f(0;\delta_2)}{\sigma_2f(0;\delta_1)+\sigma_1 f(0;\delta_2)}. $$
Example. If $f$ corresponds to the Studentt pdf then $s$ corresponds to the pdf of the Double TwoPiece Studentt distribution. Note that $s$ has different scale and shape on each side of the mode.
Notes
For technical details on this families of distributions we refer to the following two publications which serve as reference for our implementation.

Inference in TwoPiece LocationScale Models with Jeffreys Priors published in Bayesian Anal. Volume 9, Number 1 (2014), 122.

Bayesian modelling of skewness and kurtosis with TwoPiece Scale and shape distributions published in Electron. J. Statist., Volume 9, Number 2 (2015), 18841912.
For the R implementation we refer to the following packages.
twopiece has been developed and tested on Python 3.6, and 3.7.
Supported Distributions
Implementation is provided for the following distributions.
TwoPiece Scale
Name  Function  Parameters 

TwoPiece Normal  tpnorm  loc, sigma1, sigma2 
TwoPiece Laplace  tplaplace  loc, sigma1, sigma2 
TwoPiece Cauchy  tpcauchy  loc, sigma1, sigma2 
TwoPiece Logistic  tplogistic  loc, sigma1, sigma2 
TwoPiece Studentt  tpstudent  loc, sigma1, sigma2, shape 
TwoPiece Exponential Power  tpgennorm  loc, sigma1, sigma2, shape 
TwoPiece SinhArcSinh  tpsas  loc, sigma1, sigma2, shape 
TwoPiece Shape
Name  Function  Parameters 

TwoPieceShape Studentt  tpshastudent  loc, sigma, shape1, shape2 
TwoPieceShape Exponential Power  tpshagennorm  loc, sigma, shape1, shape2 
TwoPieceShape SinhArcSinh  tpshasas  loc, sigma, shape1, shape2 
Double TwoPiece
Name  Function  Parameters 

Double TwoPiece Studentt  dtpstudent  loc, sigma1, sigma2, shape1, shape2 
Double TwoPiece Exponential Power  dtpgennorm  loc, sigma1, sigma2, shape1, shape2 
Double TwoPiece SinhArcSinh  dtpsinhasinh  loc, sigma1, sigma2, shape1, shape2 
Main Features
We provide the following functionality for all the supported distributions.
Function  Method  Parameters 

Probability Density Function  x  
Cumulative Distribution Function  cdf  x 
Quantile Function  ppf  q 
Random Sample Generation  random_sample  size 
Quick Start
Install
We recommend install twopiece using pip as follows.
pip install twopiece
To illustrate usage twopiece scale distributions we will use the twopiece Normal, and twopiece Studentt. The behaviour is analogous for the rest of the supported distributions.
1. Create a twopiece instance
First, we load the family (scale, shape and double) of twopiece distributions that we want to use.
from twopiece.scale import *
from twopiece.shape import *
from twopiece.double import *
To create an instance we need to specify either 3, 4, or 5 parameters:
For the TwoPiece Normal we require:
 loc: which is the location parameter
 sigma1, sigma2 : which are both scale parameters
loc=0.0
sigma1=1.0
sigma2=1.0
dist = tpnorm(loc=loc, sigma1=sigma1, sigma2=sigma2)
For the TwoPiece Studentt we require:
 loc: which is the location parameter
 sigma1, sigma2 : which are both scale parameters
 shape : which defines the degrees of freedom for the tStudent distribution
loc=0.0
sigma1=1.0
sigma2=2.0
shape=3.0
dist = tpstudent(loc=loc, sigma1=sigma1, sigma2=sigma2, shape=shape)
For the Double TwoPiece Studentt we require:
 loc: which is the location parameter
 sigma1, sigma2 : which are both scale parameters
 shape1, shape2 : which define the degrees of freedom for the tStudent distribution on each side of the mode.
loc=0.0
sigma1=1.0
sigma2=2.0
shape1=3.0
shape2=10.0
dist = dtpstudent(loc=loc, sigma1=sigma1, sigma2=sigma2, shape1=shape1, shape2=shape2)
Hereafter we assume that there is a twopiece instance called dist.
2. Evaluate and visualise the probability density function (pdf)
We can evaluate the pdf on a single point or an array type object
dist.pdf(0)
dist.pdf([0.0,0.25,0.5])
To visualise the pdf use
x = arange(12, 12, 0.1)
y = dist.pdf(x)
plt.plot(x, y)
plt.show()
3. Evaluate the cumulative distribution function (cdf)
We can evaluate the cdf on a single point or an array type object
dist.cdf(0)
dist.cdf([0.0,0.25,0.5])
To visualise the cdf use
x = arange(12, 12, 0.1)
y = dist.cdf(x)
plt.plot(x, y)
plt.show()
4. Evaluate the quantile function (ppf)
We can evaluate the ppf on a single point or an array type object. Note that the ppf has support on [0,1].
dist.ppf(0.95)
dist.ppf([0.5, 0.9, 0.95])
To visualise the ppf use
x = arange(0.001, 0.999, 0.01)
y = dist.ppf(x)
plt.plot(x, y)
plt.show()
5. Generate a random sample
To generate a random sample we require:
 size: which is simply the size of the sample
sample = dist.random_sample(size = 100)
Project details
Release history Release notifications  RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.