Utils & Metrics¶
betainc¶
- pyldl.algorithms.utils.betainc(alpha, beta, x)[source]¶
Compute the regularized incomplete beta function.
- Parameters:
alpha (np.ndarray or tensor) – First beta-shape parameter.
beta (np.ndarray or tensor) – Second beta-shape parameter.
x (np.ndarray or tensor) – Evaluation points.
- Returns:
Beta cumulative distribution values.
- Return type:
np.ndarray or tensor
binaryzation¶
- pyldl.algorithms.utils.binaryzation(D: ndarray, method='threshold', param: any | None = None) ndarray[source]¶
Transform label distribution matrix to logical label matrix.
- Parameters:
D (np.ndarray) – Label distribution matrix (shape: \([n, c]\)).
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 c / 2 \rfloor\) for ‘topk’.
- Returns:
Logical label matrix (shape: \([n, c]\)).
- Return type:
np.ndarray
digamma¶
estimate_alpha¶
- pyldl.algorithms.utils.estimate_alpha(D, max_iterations: int = 100, convergence_criterion=1e-07)[source]¶
Estimate Dirichlet concentration parameters from label distributions.
- Parameters:
D (np.ndarray or tensor) – Label distribution matrix.
max_iterations (int) – Maximum number of fixed-point iterations, defaults to 100.
convergence_criterion (float) – Convergence threshold, defaults to 1e-7.
- Returns:
Estimated Dirichlet concentration vector.
- Return type:
np.ndarray or tensor
gammaln¶
inv_digamma¶
- pyldl.algorithms.utils.inv_digamma(y, max_iterations: int = 2)[source]¶
Compute the inverse digamma function using Newton iterations.
- Parameters:
y (np.ndarray or tensor) – Digamma values.
max_iterations (int) – Maximum number of Newton iterations, defaults to 2.
- Returns:
Inverse-digamma values.
- Return type:
np.ndarray or tensor
kernel¶
- pyldl.algorithms.utils.kernel(X, Y=None, gamma: float | None = None)[source]¶
Compute an RBF kernel matrix between rows of two matrices.
- Parameters:
X (np.ndarray) – First input matrix.
Y (np.ndarray or None) – Second input matrix; if None, use
X, defaults to None.gamma (float or None) – RBF kernel coefficient; if None, estimate it from pairwise distances, defaults to None.
- Returns:
RBF kernel matrix.
- Return type:
np.ndarray
kl_divergence\(\downarrow\)¶
locass_proj¶
non_diagonal¶
normalize¶
pairwise_cosine¶
- pyldl.algorithms.utils.pairwise_cosine(X, Y=None, mode: str = 'similarity')[source]¶
Compute pairwise cosine similarities or distances between rows of two matrices.
- Parameters:
X (np.ndarray) – First input matrix.
Y (np.ndarray or None) – Second input matrix; if None, use
X, defaults to None.mode ({'similarity', 'distance'}) – Return mode, either
'similarity'or'distance', defaults to'similarity'.
- Returns:
Pairwise cosine similarity or distance matrix.
- Return type:
np.ndarray
pairwise_euclidean¶
- pyldl.algorithms.utils.pairwise_euclidean(X, Y=None)[source]¶
Compute pairwise Euclidean distances between rows of two matrices.
- Parameters:
X (np.ndarray) – First input matrix.
Y (np.ndarray or None) – Second input matrix; if None, use
X, defaults to None.
- Returns:
Pairwise Euclidean distance matrix.
- Return type:
np.ndarray
pairwise_pearsonr¶
- pyldl.algorithms.utils.pairwise_pearsonr(X, Y=None)[source]¶
Compute pairwise Pearson correlation coefficients between rows of two matrices.
- Parameters:
X (np.ndarray) – First input matrix.
Y (np.ndarray or None) – Second input matrix; if None, use
X, defaults to None.
- Returns:
Pairwise Pearson correlation matrix.
- Return type:
np.ndarray
proj¶
shannon_entropy¶
soft_thresholding¶
- pyldl.algorithms.utils.soft_thresholding(A: ndarray, tau: float) ndarray[source]¶
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¶
solvel21¶
- pyldl.algorithms.utils.solvel21(A: ndarray, tau: float) ndarray[source]¶
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[source]¶
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
trigamma¶
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)[source]¶
Generate artificial label distributions from polynomial feature interactions. The generation process is provided in [LDL-Gen16].
- Parameters:
X (np.ndarray) – Feature matrix.
a – Coefficient of the linear term, defaults to 1.
b – Coefficient of the quadratic term, defaults to 0.5.
c – Coefficient of the cubic term, defaults to 0.2.
d – Constant term, defaults to 1.
w1 – Weights for the first label, defaults to
[[4., 2., 1.]].w2 – Weights for the second label, defaults to
[[1., 2., 4.]].w3 – Weights for the third label, defaults to
[[1., 4., 2.]].lambda1 – Coupling coefficient for the second label, defaults to 0.01.
lambda2 – Coupling coefficient for the third label, defaults to 0.01.
- Returns:
Artificial label distribution matrix.
- Return type:
np.ndarray
download_dataset¶
emphasize¶
gaussian_noise¶
- pyldl.utils.gaussian_noise(D: ndarray, mode=None, mean: float = 0.0, std: float = 0.1, p: float = 5.0)[source]¶
Add Gaussian noise to label distributions and renormalize them.
- Parameters:
D (np.ndarray) – Label distribution matrix.
mode ({None, 'gcia'}) –
Noise mode, defaults to None. Mode ‘gcia’ refers to Generative Calibration of Inaccurate Annotators. See the following reference for details:
[NOISE-HLLJ24]Liang He, Yunan Lu, Weiwei Li, and Xiuyi Jia. Generative calibration of inaccurate annotation for label distribution learning. In Proceedings of the AAAI Conference on Artificial Intelligence, 12394–12401. 2024. URL: https://doi.org/10.1609/aaai.v38i11.29131.
mean (float) – Mean of the noise in the default mode, defaults to 0.
std (float) – Standard deviation of the noise in the default mode, defaults to 0.1.
p (float) – Annotator professionalism level in GCIA mode, defaults to 5.; larger values produce more noise.
- Returns:
Noisy label distribution matrix.
- Return type:
np.ndarray
load_dataset¶
- pyldl.utils.load_dataset(name, dir='datasets', mode='D')[source]¶
Load a dataset from a local
.matfile, downloading it when necessary. If the dataset is not found in the directory, and it is available in the PyLDL GitHub repository, it will be downloaded automatically.- Parameters:
name (str) – Name of the dataset (without the
.matextension).dir (str) – Directory where the dataset is stored (or will be downloaded to), defaults to ‘datasets’.
mode ({'D', 'G'}) – Mode of the dataset to load, defaults to ‘D’. ‘D’ is for label distribution, and ‘G’ is for generalized label distribution.
make_ldl¶
- pyldl.utils.make_ldl(n_samples=200, random_state=None, **kwargs)[source]¶
Generate random features and artificial label distributions using the
artificial()function.- Parameters:
n_samples (int) – Number of samples to generate, defaults to 200.
random_state (int or None) – Seed for NumPy’s random number generator, defaults to None.
kwargs – Additional keyword arguments passed to
artificial().
- Returns:
Generated feature matrix and label distribution matrix.
- Return type:
tuple[np.ndarray, np.ndarray]
plot_artificial¶
- pyldl.utils.plot_artificial(grid_size=50, model=None, file_name=None, *, noise=False, noise_func_args=None, **kwargs)[source]¶
Plot predictions or perturbations on the artificial LDL dataset as a 3D color surface.
- Parameters:
grid_size (int) – Number of points along each feature axis, defaults to 50.
model (BaseLDL or BaseLE or None) – Optional LDL or LE model used to generate predictions, defaults to None.
file_name (str or None) – Output file name without extension; if None, display the figure, defaults to None.
noise (bool) – Whether to apply the default noise transformations, defaults to False.
noise_func_args (list or None) – Noise functions and their keyword arguments, defaults to None.
kwargs – Additional keyword arguments passed to
artificial().
random_exchange¶
random_missing¶
- pyldl.utils.random_missing(D, rate=0.8, weighted=False, return_mask=True)[source]¶
Randomly set entries of label distributions to zero. This setting is useful for simulating incomplete label distributions. See [INCOM-LDL-XZ17] for details.
- Parameters:
D (np.ndarray) – Label distribution matrix.
rate (float) – Proportion of entries to remove, in the range (0, 1), defaults to 0.8.
weighted (bool) –
Whether to select entries according to value-based weights, defaults to False. This setting can refer to:
[NOISE-LC24]Xiang Li and Songcan Chen. No regularization is needed: efficient and effective incomplete label distribution learning. In Proceedings of the International Joint Conference on Artificial Intelligence, 4470–4478. 2024. URL: https://doi.org/10.24963/ijcai.2024/494.
return_mask (bool) – Whether to return the missing-entry mask, defaults to True.
- Returns:
The incomplete distribution, optionally together with its boolean mask.
- Return type:
np.ndarray or tuple[np.ndarray, np.ndarray]
regressor2ldl¶
- pyldl.utils.regressor2ldl(regressor) BaseLDL[source]¶
Wrap a scikit-learn regressor as a PyLDL label distribution learner.
- Parameters:
regressor (sklearn.base.RegressorMixin) – Scikit-learn regressor used for multi-output prediction.
- Returns:
A PyLDL model backed by the supplied regressor.
- Return type:
accuracy\(\uparrow\)¶
canberra\(\downarrow\)¶
chebyshev\(\downarrow\)¶
chi2\(\downarrow\)¶
clark\(\downarrow\)¶
cosine\(\uparrow\)¶
divisiveness_error\(\downarrow\)¶
dpa\(\uparrow\)¶
- pyldl.metrics.dpa(D, D_pred)[source]¶
Degree percentile average (DPA) is proposed in paper [LDL-JQLL24]. It is defined as:
\[\text{DPA}(\boldsymbol{u}, \boldsymbol{v}) = \frac{1}{c} \sum_{j=1}^{c} u_j \rho(v_j)\text{,}\]where \(\rho(\cdot)\) is the rank of the element in the vector.
error_probability\(\downarrow\)¶
euclidean\(\downarrow\)¶
fidelity\(\uparrow\)¶
hamming\(\downarrow\)¶
intersection\(\uparrow\)¶
jaccard\(\uparrow\)¶
js_divergence\(\downarrow\)¶
- pyldl.metrics.js_divergence(D, D_pred)[source]¶
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¶
jsd_dirichlet_variance¶
kendall\(\uparrow\)¶
kendallT\(\uparrow\)¶
match_m\(\uparrow\)¶
max_roc_auc\(\uparrow\)¶
mean_absolute_error\(\downarrow\)¶
mean_squared_error\(\downarrow\)¶
mu\(\uparrow\)¶
- pyldl.metrics.mu(D, D_pred)[source]¶
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\)¶
nu2\(\uparrow\)¶
nu3\(\uparrow\)¶
ood_error\(\downarrow\)¶
precision\(\uparrow\)¶
score¶
sensitivity\(\uparrow\)¶
sorensen\(\downarrow\)¶
spearman\(\uparrow\)¶
- pyldl.metrics.spearman(D, D_pred, transpose=False)[source]¶
Spearman’s rank correlation coefficient. It is defined as:
\[\text{Spear.}(\boldsymbol{u}, \boldsymbol{v}) = 1 - \frac{6 \sum_{j=1}^{c} (\rho(u_j) - \rho(v_j))^2 }{c(c^2 - 1)}\text{,}\]where \(\rho(\cdot)\) is the rank of the element in the vector.
spearmanT\(\uparrow\)¶
specificity\(\uparrow\)¶
subset_accuracy\(\uparrow\)¶
top_k\(\uparrow\)¶
wave_hedges\(\downarrow\)¶
worst_kl_divergence¶
youden_index\(\uparrow\)¶
zero_one_loss\(\downarrow\)¶
References¶
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.
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.
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.