Utils & Metrics

_1d

pyldl.algorithms.utils._1d(func)

_clip

pyldl.algorithms.utils._clip(func)

_reduction

pyldl.algorithms.utils._reduction(func)

binaryzation

pyldl.algorithms.utils.binaryzation(D: ndarray, method='threshold', param: any | None = None) → ndarray

Transform label distribution matrix to logical label matrix.

Parameters:

• D (np.ndarray) – Label distribution matrix (shape: \([n,\, l]\)).

• method ({'threshold', 'topk'}, optional) –

  Type of binaryzation method, defaults to ‘threshold’. The options are ‘threshold’ and ‘topk’, which can refer to:

  [BIN-KWT+24]

  Zhiqiang Kou, Jing Wang, Jiawei Tang, Yuheng Jia, Boyu Shi, and Xin Geng. Exploiting multi-label correlation in label distribution learning. In Proceedings of the International Joint Conference on Artificial Intelligence, 4326–4334. 2024. URL: https://doi.org/10.24963/ijcai.2024/478.

• param (any, optional) – Parameter of binaryzation method, defaults to None. If None, the default value is .5 for ‘threshold’ and \(\lfloor l / 2 \rfloor\) for ‘topk’.

Returns:

Logical label matrix (shape: \([n,\, l]\)).

Return type:

np.ndarray

csr2sparse

pyldl.algorithms.utils.csr2sparse(A)

estimate_alpha

pyldl.algorithms.utils.estimate_alpha(D: ndarray, max_iterations: int = 100, convergence_criterion=1e-07)

kernel

pyldl.algorithms.utils.kernel(X, Y=None, gamma: float | None = None)

kl_divergence\(\downarrow\)

pyldl.algorithms.utils.kl_divergence(D, D_pred)

pyldl.algorithms.utils.kl_divergence(X: ndarray, Y: ndarray | None = None, **kwargs)

Kullback-Leibler divergence. It is defined as:

\[\text{KLD}(\boldsymbol{u}, \, \boldsymbol{v}) = \sum^l_{j=1}u_j \ln \frac{u_j}{v_j}\text{.}\]

locass_proj

pyldl.algorithms.utils.locass_proj(D, k)

non_diagonal

pyldl.algorithms.utils.non_diagonal(X)

normalize

pyldl.algorithms.utils.normalize(D: ndarray) → ndarray

pairwise_cosine

pyldl.algorithms.utils.pairwise_cosine(X, Y=None, mode: str = 'similarity')

pyldl.algorithms.utils.pairwise_cosine(X: ndarray, Y: ndarray | None = None, **kwargs)

pairwise_euclidean

pyldl.algorithms.utils.pairwise_euclidean(X, Y=None)

pyldl.algorithms.utils.pairwise_euclidean(X: ndarray, Y: ndarray | None = None, **kwargs)

pairwise_pearsonr

pyldl.algorithms.utils.pairwise_pearsonr(X, Y=None)

pyldl.algorithms.utils.pairwise_pearsonr(X: ndarray, Y: ndarray | None = None, **kwargs)

proj

pyldl.algorithms.utils.proj(D: ndarray) → ndarray

This approach is proposed in paper [Con16].

Parameters:

D (np.ndarray) – Matrix \(\boldsymbol{D}\).

Returns:

The projection onto the probability simplex.

Return type:

np.ndarray

shannon_entropy

pyldl.algorithms.utils.shannon_entropy(D: ndarray)

soft_thresholding

pyldl.algorithms.utils.soft_thresholding(A: ndarray, tau: float) → ndarray

Soft thresholding operation. It is defined as \(\text{soft}(\boldsymbol{A}, \, \tau) = \text{sgn}(\boldsymbol{A}) \odot \max\lbrace \lvert \boldsymbol{A} \rvert - \tau, 0 \rbrace\), where \(\odot\) denotes element-wise multiplication.

Parameters:

• A (np.ndarray) – Matrix \(\boldsymbol{A}\).

• tau (float) – \(\tau\).

Returns:

The result of soft thresholding operation.

Return type:

np.ndarray

softmax

pyldl.algorithms.utils.softmax(D: ndarray) → ndarray

solvel21

pyldl.algorithms.utils.solvel21(A: ndarray, tau: float) → ndarray

This approach is proposed in paper [CY14].

The solution to the optimization problem \(\mathop{\arg\min}_{\boldsymbol{X}} \Vert \boldsymbol{X} - \boldsymbol{A} \Vert_\text{F}^2 + \tau \Vert \boldsymbol{X} \Vert_{2,\,1}\) is given by the following formula:

\[\begin{split}\vec{x}_{\bullet j}^{\ast} = \left\{ \begin{aligned} & \frac{\Vert \vec{a}_{\bullet j} \Vert - \tau}{\Vert \vec{a}_{\bullet j} \Vert} \vec{a}_{\bullet j}, & \tau \le \Vert \vec{a}_{\bullet j} \Vert \\ & 0, & \text{otherwise} \end{aligned} \right.\text{.}\end{split}\]

where \(\vec{x}_{\bullet j}\) is the \(j\)-th column of matrix \(\boldsymbol{X}\), and \(\vec{a}_{\bullet j}\) is the \(j\)-th column of matrix \(\boldsymbol{A}\).

Parameters:

• A (np.ndarray) – Matrix \(\boldsymbol{A}\).

• tau (float) – \(\tau\).

Returns:

The solution to the optimization problem.

Return type:

np.ndarray

svt

pyldl.algorithms.utils.svt(A: ndarray, tau: float) → ndarray

Singular value thresholding (SVT) is proposed in paper [CCS10].

The solution to the optimization problem \(\mathop{\arg\min}_{\boldsymbol{X}} \Vert \boldsymbol{X} - \boldsymbol{A} \Vert_\text{F}^2 + \tau \Vert \boldsymbol{X} \Vert_{\ast}\) is given by \(\boldsymbol{U} \max \lbrace \boldsymbol{\Sigma} - \tau, 0 \rbrace \boldsymbol{V}^\top\), where \(\boldsymbol{A} = \boldsymbol{U} \boldsymbol{\Sigma} \boldsymbol{V}^\top\) is the singular value decomposition of matrix \(\boldsymbol{A}\).

Parameters:

• A (np.ndarray) – Matrix \(\boldsymbol{A}\).

• tau (float) – \(\tau\).

Returns:

The solution to the optimization problem.

Return type:

np.ndarray

_random_mask

pyldl.utils._random_mask(D, rate, weighted)

_weighted_mask

pyldl.utils._weighted_mask(D, rate)

artificial

pyldl.utils.artificial(X, a=1.0, b=0.5, c=0.2, d=1.0, w1=array([[4., 2., 1.]]), w2=array([[1., 2., 4.]]), w3=array([[1., 4., 2.]]), lambda1=0.01, lambda2=0.01)

download_dataset

pyldl.utils.download_dataset(name, dataset_path)

emphasize

pyldl.utils.emphasize(D, rate=0.5, **kwargs)

gaussian_noise

pyldl.utils.gaussian_noise(D: ndarray, mean: float = 0.0, std: float = 0.1)

load_dataset

pyldl.utils.load_dataset(name, dir='dataset', mode='D')

make_ldl

pyldl.utils.make_ldl(n_samples=200, random_state=None, **kwargs)

plot_artificial

pyldl.utils.plot_artificial(n_samples=50, model=None, file_name=None, *, noise=False, noise_func_args=None, **kwargs)

random_exchange

pyldl.utils.random_exchange(D, rate=0.2, weighted=False, return_mask=True)

random_missing

pyldl.utils.random_missing(D, rate=0.8, weighted=False, return_mask=True)

regressor2ldl

pyldl.utils.regressor2ldl(regressor) → BaseLDL

_nu

pyldl.metrics._nu(D, D_pred, type=None, min_beta=3.0)

pyldl.metrics._nu(X: ndarray, Y: ndarray | None = None, **kwargs)

_register

pyldl.metrics._register(prefix, larger=False, name=None)

_uniform_vector

pyldl.metrics._uniform_vector(shape, scale=0.0)

accuracy\(\uparrow\)

pyldl.metrics.accuracy(y, y_pred)

canberra\(\downarrow\)

pyldl.metrics.canberra(D, D_pred)

pyldl.metrics.canberra(X: ndarray, Y: ndarray | None = None, **kwargs)

Canberra distance. It is defined as:

\[\text{Can.}(\boldsymbol{u}, \, \boldsymbol{v}) = \sum^l_{j=1}\frac{\left\vert u_j - v_j \right\vert}{u_j + v_j}\text{.}\]

chebyshev\(\downarrow\)

pyldl.metrics.chebyshev(D, D_pred)

pyldl.metrics.chebyshev(X: ndarray, Y: ndarray | None = None, **kwargs)

Chebyshev distance. It is defined as:

\[\text{Cheby.}(\boldsymbol{u}, \, \boldsymbol{v}) = \max_j \left\vert u_j - v_j \right\vert\text{.}\]

chi2\(\downarrow\)

pyldl.metrics.chi2(D, D_pred)

pyldl.metrics.chi2(X: ndarray, Y: ndarray | None = None, **kwargs)

Chi-squared distance. It is defined as:

\[\chi^2(\boldsymbol{u}, \, \boldsymbol{v}) = \sum^l_{j=1}\frac{\left( u_j - v_j \right)^2}{u_j + v_j}\text{.}\]

clark\(\downarrow\)

pyldl.metrics.clark(D, D_pred)

pyldl.metrics.clark(X: ndarray, Y: ndarray | None = None, **kwargs)

Clark distance. It is defined as:

\[\text{Clark}(\boldsymbol{u}, \, \boldsymbol{v}) = \sqrt{\sum^l_{j=1}\frac{\left( u_j - v_j \right)^2}{\left( u_j + v_j \right)^2}}\text{.}\]

cosine\(\uparrow\)

pyldl.metrics.cosine(D, D_pred)

pyldl.metrics.cosine(X: ndarray, Y: ndarray | None = None, **kwargs)

Cosine similarity. It is defined as:

\[\text{Cosine}(\boldsymbol{u}, \, \boldsymbol{v}) = \frac{\sum^l_{j=1}u_j v_j}{\sqrt{\sum^l_{j=1}u_j^2}\sqrt{\sum^l_{j=1}v_j^2}}\text{.}\]

divisiveness_error\(\downarrow\)

pyldl.metrics.divisiveness_error(D, D_pred, pos, neg)

pyldl.metrics.divisiveness_error(X: ndarray, Y: ndarray | None = None, **kwargs)

dpa\(\uparrow\)

pyldl.metrics.dpa(D, D_pred)

pyldl.metrics.dpa(X: ndarray, Y: ndarray | None = None, **kwargs)

Degree percentile average (DPA) is proposed in paper [LDL-JQLL24]. It is defined as:

\[\text{DPA}(\boldsymbol{u}, \, \boldsymbol{v}) = \frac{1}{l} \sum_{j=1}^{l} u_j \rho(v_j)\text{,}\]

where \(\rho(\cdot)\) is the rank of the element in the vector.

error_probability\(\downarrow\)

pyldl.metrics.error_probability(D, D_pred)

pyldl.metrics.error_probability(X: ndarray, Y: ndarray | None = None, **kwargs)

Error probability. It is defined as:

\[\text{Err. prob.}(\boldsymbol{u}, \, \boldsymbol{v}) = 1 - u_{\arg\max(\boldsymbol{v})}\text{.}\]

euclidean\(\downarrow\)

pyldl.metrics.euclidean(D, D_pred)

pyldl.metrics.euclidean(X: ndarray, Y: ndarray | None = None, **kwargs)

Euclidean distance. It is defined as:

\[\text{Eucl.}(\boldsymbol{u}, \, \boldsymbol{v}) = \sqrt{\sum^l_{j=1}\left( u_j - v_j \right)^2}\text{.}\]

fidelity\(\uparrow\)

pyldl.metrics.fidelity(D, D_pred)

pyldl.metrics.fidelity(X: ndarray, Y: ndarray | None = None, **kwargs)

Fidelity similarity. It is defined as:

\[\text{Fid.}(\boldsymbol{u}, \, \boldsymbol{v}) = \sum^l_{j=1} \sqrt{u_j v_j}\text{.}\]

hamming\(\downarrow\)

pyldl.metrics.hamming(L, L_pred)

pyldl.metrics.hamming(X: ndarray, Y: ndarray | None = None, **kwargs)

intersection\(\uparrow\)

pyldl.metrics.intersection(D, D_pred)

pyldl.metrics.intersection(X: ndarray, Y: ndarray | None = None, **kwargs)

Intersection similarity. It is defined as:

\[\text{Int.}(\boldsymbol{u}, \, \boldsymbol{v}) = \sum^l_{j=1} \min\left(u_j, \, v_j\right)\text{.}\]

jaccard\(\uparrow\)

pyldl.metrics.jaccard(L, L_pred)

pyldl.metrics.jaccard(X: ndarray, Y: ndarray | None = None, **kwargs)

js_divergence\(\downarrow\)

pyldl.metrics.js_divergence(D, D_pred)

pyldl.metrics.js_divergence(X: ndarray, Y: ndarray | None = None, **kwargs)

Jensen-Shannon divergence. It is defined as:

\[\text{JSD}(\boldsymbol{u}, \, \boldsymbol{v}) = \frac{1}{2}\text{KLD}\left(\boldsymbol{u} \bigg\Vert \frac{1}{2}(\boldsymbol{u} + \boldsymbol{v}) \right) + \frac{1}{2}\text{KLD}\left(\boldsymbol{v} \bigg\Vert \frac{1}{2}(\boldsymbol{u} + \boldsymbol{v}) \right)\text{.}\]

jsd_dirichlet_expectation

pyldl.metrics.jsd_dirichlet_expectation(alpha, beta)

jsd_dirichlet_variance

pyldl.metrics.jsd_dirichlet_variance(alpha, beta)

kendall\(\uparrow\)

pyldl.metrics.kendall(D, D_pred, transpose=False)

pyldl.metrics.kendall(X: ndarray, Y: ndarray | None = None, **kwargs)

Kendall’s rank correlation coefficient. It is defined as:

\[\text{Ken.}(\boldsymbol{u}, \, \boldsymbol{v}) = \frac{2 \sum_{j < k} \text{sgn}(u_j - u_k) \text{sgn}(v_j - v_k) }{l (l-1)}\text{.}\]

kendallT\(\uparrow\)

pyldl.metrics.kendallT(G, G_pred)

match_m\(\uparrow\)

pyldl.metrics.match_m(D, D_pred, m=None)

max_roc_auc\(\uparrow\)

pyldl.metrics.max_roc_auc(D, D_pred)

mean_absolute_error\(\downarrow\)

pyldl.metrics.mean_absolute_error(D, D_pred, mode='macro')

mean_squared_error\(\downarrow\)

pyldl.metrics.mean_squared_error(D, D_pred, mode='macro')

mu\(\uparrow\)

pyldl.metrics.mu(D, D_pred)

pyldl.metrics.mu(X: ndarray, Y: ndarray | None = None, **kwargs)

The \(\mu\) metric is proposed in paper [LDL-LWLJ25]. Its KL-divergence-based form is defined as:

\[\mu(\boldsymbol{U}, \, \boldsymbol{V}) = \frac{1}{\delta_0} \int_0^{\delta_0} \frac{1}{n} \sum_{i=1}^{n} \mathbb{I} (\text{KLD}(\boldsymbol{u}_i, \, \boldsymbol{v}_i) \le \delta) \mathrm{d}\delta\text{,}\]

where \(\delta_0 = \mathbb{E}_n[\text{KLD}(\boldsymbol{u}_i, \, \boldsymbol{c})]\) and \(\boldsymbol{c}\) is a uniform vector.

nu1\(\uparrow\)

pyldl.metrics.nu1(D, D_pred, *args, **kwargs)

nu2\(\uparrow\)

pyldl.metrics.nu2(D, D_pred, *args, **kwargs)

nu3\(\uparrow\)

pyldl.metrics.nu3(D, D_pred)

ood_error\(\downarrow\)

pyldl.metrics.ood_error(G, G_pred)

pyldl.metrics.ood_error(X: ndarray, Y: ndarray | None = None, **kwargs)

precision\(\uparrow\)

pyldl.metrics.precision(y, y_pred)

score

pyldl.metrics.score(target: ndarray, pred: ndarray, metrics: list | None = None, return_dict: bool = False)

sensitivity\(\uparrow\)

pyldl.metrics.sensitivity(y, y_pred)

sorensen\(\downarrow\)

pyldl.metrics.sorensen(D, D_pred)

pyldl.metrics.sorensen(X: ndarray, Y: ndarray | None = None, **kwargs)

Sørensen's distance. It is defined as:

\[\text{S}\phi\text{ren.}(\boldsymbol{u}, \, \boldsymbol{v}) = \frac{\sum^l_{j=1}\left\vert u_j - v_j \right\vert}{\sum^l_{j=1}\left( u_j + v_j \right)}\text{.}\]

spearman\(\uparrow\)

pyldl.metrics.spearman(D, D_pred, transpose=False)

pyldl.metrics.spearman(X: ndarray, Y: ndarray | None = None, **kwargs)

Spearman’s rank correlation coefficient. It is defined as:

\[\text{Spear.}(\boldsymbol{u}, \, \boldsymbol{v}) = 1 - \frac{6 \sum_{j=1}^{l} (\rho(u_j) - \rho(v_j))^2 }{l(l^2 - 1)}\text{,}\]

where \(\rho(\cdot)\) is the rank of the element in the vector.

spearmanT\(\uparrow\)

pyldl.metrics.spearmanT(G, G_pred)

specificity\(\uparrow\)

pyldl.metrics.specificity(y, y_pred)

subset_accuracy\(\uparrow\)

pyldl.metrics.subset_accuracy(L, L_pred)

pyldl.metrics.subset_accuracy(X: ndarray, Y: ndarray | None = None, **kwargs)

top_k\(\uparrow\)

pyldl.metrics.top_k(D, D_pred, k=None, mode='f1_score')

wave_hedges\(\downarrow\)

pyldl.metrics.wave_hedges(D, D_pred)

pyldl.metrics.wave_hedges(X: ndarray, Y: ndarray | None = None, **kwargs)

Wave-Hedges distance. It is defined as:

\[\text{WHD}(\boldsymbol{u}, \, \boldsymbol{v}) = \sum^l_{j=1}\frac{\left| u_j - v_j \right|}{\max (u_j, \, v_j)}\text{.}\]

worst_kl_divergence

pyldl.metrics.worst_kl_divergence(D: ndarray)

youden_index\(\uparrow\)

pyldl.metrics.youden_index(y, y_pred)

zero_one_loss\(\downarrow\)

pyldl.metrics.zero_one_loss(D, D_pred)

pyldl.metrics.zero_one_loss(X: ndarray, Y: ndarray | None = None, **kwargs)

0/1 loss. It is defined as:

\[\text{0/1 loss}(\boldsymbol{u}, \, \boldsymbol{v}) = \delta(\arg\max(\boldsymbol{u}), \, \arg\max(\boldsymbol{v}))\text{,}\]

where \(\delta(\cdot, \, \cdot)\) is the Kronecker delta function.

References

[Con16]

Laurent Condat. Fast projection onto the simplex and the l1 ball. Mathematical Programming, 158(1):575–585, 2016. URL: https://doi.org/10.1007/s10107-015-0946-6.

[CY14]

Jinhui Chen and Jian Yang. Robust subspace segmentation via low-rank representation. IEEE Transactions on Cybernetics, 44(8):1432–1445, 2014. URL: https://doi.org/10.1109/TCYB.2013.2286106.

[CCS10]

Jian-Feng Cai, Emmanuel J Candès, and Zuowei Shen. A singular value thresholding algorithm for matrix completion. SIAM Journal on Optimization, 20(4):1956–1982, 2010. URL: https://doi.org/10.1137/080738970.