arbitragelab.copula_approach.elliptical.student

T-Student copula implementation.

Module Contents

Classes

StudentCopula

Bivariate Student-t Copula, need degree of freedom nu.

Functions

fit_nu_for_t_copula(→ float)

Find the best fit value nu for Student-t copula.

class StudentCopula(nu: float = None, cov: numpy.array = None)

Bases: arbitragelab.copula_approach.base.Copula

Bivariate Student-t Copula, need degree of freedom nu.

__slots__ = ()

sample(num: int = None) → numpy.array

Generate pairs according to P.D.F., stored in a 2D np.array.

User may choose to side-load independent uniformly distributed data in [0, 1].

Parameters:

num – (int) Number of points to generate.

Return sample_pairs:

(np.array) Shape=(num, 2) array, sampled data for this copula.

c(u: float, v: float) → float

Calculate probability density of the bivariate copula: P(U=u, V=v).

Result is analytical.

Parameters:

• u – (float) A real number in [0, 1].

• v – (float) A real number in [0, 1].

Returns:

(float) The probability density (aka copula density).

C(u: float, v: float) → float

Calculate cumulative density of the bivariate copula: P(U<=u, V<=v).

Result is numerical. Calculated from definition of elliptical copula:

C(u, v) = Phi_nu_cor (inv_t(u, nu), inv_t(v, nu))

Where inv_t(u, nu) is the percentile function for a uni-variate Student-t distribution with DOF = nu. Phi_nu_cor is the bivariate Student-t CDF with covariance matrix = correlation matrix, DOF = nu. Here Phi_nu_cor is calculated numerically by double integration.

Parameters:

• u – (float) A real number in [0, 1].

• v – (float) A real number in [0, 1].

Returns:

(float) The cumulative density.

condi_cdf(u: float, v: float) → float

Calculate conditional probability function: P(U<=u | V=v).

Result is analytical.

Note: This probability is symmetric about (u, v).

Parameters:

• u – (float) A real number in [0, 1].

• v – (float) A real number in [0, 1].

Returns:

(float) The conditional probability.

static theta_hat(tau: float) → float

Calculate theta hat from Kendall’s tau from sample data.

Parameters:

tau – (float) Kendall’s tau from sample data.

Returns:

(float) The associated theta hat for this very copula.

fit(u: numpy.array, v: numpy.array) → float

Fit t-copula to empirical data (pseudo-observations) and find cov/rho params. Once fit, self.rho, self.cov is updated.

Parameters:

• u – (np.array) 1D vector data of X pseudo-observations. Need to be uniformly distributed [0, 1].

• v – (np.array) 1D vector data of Y pseudo-observations. Need to be uniformly distributed [0, 1].

Returns:

(float) Rho(correlation) parameter value.

describe() → pandas.Series

Print the description of the copula’s name and parameter as a pd.Series.

Note: the descriptive name is different from the copula’s class name, but its full actual name. E.g. The Student copula class has its descriptive name as ‘Bivariate Student-t Copula’.

Return description:

(pd.Series) The description of the copula, including its descriptive name, class name, and its parameter(s) when applicable.

get_cop_density(u: float, v: float, eps: float = 1e-05) → float

Get the copula density c(u, v).

Result is analytical. Also the u and v will be remapped into [eps, 1-eps] to avoid edge values that may result in infinity or NaN.

Parameters:

• u – (float) A real number in [0, 1].

• v – (float) A real number in [0, 1].

• eps – (float) Optional. The distance to the boundary 0 or 1, such that the value u, v will be mapped back. Defaults to 1e-5.

Returns:

(float) The probability density (aka copula density).

get_cop_eval(u: float, v: float, eps: float = 1e-05) → float

Get the evaluation of copula, equivalently the cumulative joint distribution C(u, v).

Result is analytical. Also the u and v will be remapped into [eps, 1-eps] to avoid edge values that may result in infinity or NaN.

Parameters:

• u – (float) A real number in [0, 1].

• v – (float) A real number in [0, 1].

• eps – (float) Optional. The distance to the boundary 0 or 1, such that the value u, v will be mapped back. Defaults to 1e-5.

Returns:

(float) The evaluation of copula (aka cumulative joint distribution).

get_condi_prob(u: float, v: float, eps: float = 1e-05) → float

Calculate conditional probability function: P(U<=u | V=v).

Result is analytical. Also the u and v will be remapped into [eps, 1-eps] to avoid edge values that may result in infinity or NaN.

Note: This probability is symmetric about (u, v).

Parameters:

• u – (float) A real number in [0, 1].

• v – (float) A real number in [0, 1].

• eps – (float) Optional. The distance to the boundary 0 or 1, such that the value u, v will be mapped back. Defaults to 1e-5.

Returns:

(float) The conditional probability.

get_log_likelihood_sum(u: numpy.array, v: numpy.array) → float

Get log-likelihood value sum.

Parameters:

• u – (np.array) 1D vector data of X pseudo-observations. Need to be uniformly distributed [0, 1].

• v – (np.array) 1D vector data of Y pseudo-observations. Need to be uniformly distributed [0, 1].

Returns:

(float) Log-likelihood sum value.

plot_cdf(plot_type: str = '3d', grid_size: int = 50, levels: list = None, **kwargs) → matplotlib.pyplot.axis

Plot either ‘3d’ or ‘contour’ plot of copula CDF.

Parameters:

• plot_type – (str) Either ‘3d’ or ‘contour’(2D) plot.

• grid_size – (int) Mesh grid granularity.

• kwargs – (dict) User-specified params for ‘ax.plot_surface’/’plt.contour’.

• levels – (list) List of float values that determine the number and levels of lines in a contour plot. If not provided, these are calculated automatically.

Returns:

(plt.axis) Axis object.

plot_scatter(num_points: int = 100) → matplotlib.axes.Axes

Plot copula scatter plot of generated pseudo-observations.

Parameters:

num_points – (int) Number of samples to generate.

Returns:

(plt.axis) Axis object.

plot_pdf(plot_type: str = '3d', grid_size: int = 50, levels: list = None, **kwargs) → matplotlib.figure.Figure

Plot either ‘3d’ or ‘contour’ plot of copula PDF.

Parameters:

• plot_type – (str) Either ‘3d’ or ‘contour’(2D) plot.

• grid_size – (int) Mesh grid granularity.

• levels – (list) List of float values that determine the number and levels of lines in a contour plot. If not provided, these are calculated automatically.

Returns:

(plt.axis) Axis object.

fit_nu_for_t_copula(u: numpy.array, v: numpy.array, nu_tol: float = None) → float

Find the best fit value nu for Student-t copula.

This method finds the best value of nu for a Student-t copula by maximum likelihood, using COBYLA method from scipy.optimize.minimize. nu’s fit range is [1, 15]. When the user wishes to use nu > 15, please delegate to Gaussian copula instead. This step is relatively slow.

Parameters:

• u – (np.array) 1D vector data of X pseudo-observations. Need to be uniformly distributed [0, 1].

• v – (np.array) 1D vector data of Y pseudo-observations. Need to be uniformly distributed [0, 1].

• nu_tol – (float) The final accuracy for finding nu.

Returns:

(float) The best fit of nu by maximum likelihood.