PyLDL

Label distribution learning (LDL) and label enhancement (LE) toolkit implemented in python, including:

• LDL algorithms:
  • (Geng, Yin, and Zhou 2013) [TPAMI]: CPNN$^1$.
  • (Geng and Hou 2015) [IJCAI]: LDSVR.
  • ⭐(Geng 2016) [TKDE]: SA_BFGS, SA_IIS, AA_KNN, AA_BP, PT_Bayes, and PT_SVM.
  • (Yang, Sun, and Sun 2017) [AAAI]: BCPNN and ACPNN.
  • (Xu and Zhou 2017) [IJCAI]: IncomLDL$^2$.
  • (Shen et al. 2017) [NeurIPS]: LDLF.
  • (Zhao and Zhou 2018) [AAAI]: LALOT.
  • (Jia et al. 2018) [AAAI]: LDLLC$^\dagger$.
  • (Chen et al. 2018) [Neurocomputing]: StructTree and StructRF.
  • (Ren et al. 2019a) [IJCAI]: LDLSF.
  • (Ren et al. 2019b) [IJCAI]: LDL_LCLR$^\dagger$.
  • (Wang and Geng 2019) [IJCAI]: LDL4C$^{3\dagger}$.
  • (González et al. 2021a) [Inf. Sci.]: SSG_LDL$^{4}$.
  • (González et al. 2021b) [Inf. Fusion]: DF_LDL.
  • (Wang and Geng 2021a) [IJCAI]: LDL_HR$^{3^\dagger}$.
  • (Wang and Geng 2021b) [ICML]: LDLM$^{3^\dagger}$.
  • (Jia et al. 2021) [TKDE]: LDL_SCL.
  • (Liu et al. 2021) [KBS]: BD_LDL.
  • (Żychowski and Mańdziuk 2021) [Appl. Soft Comput.]: Duo_LDL.
  • (Li et al. 2022) [CVPR]: unimodal_loss$^1$ and concentrated_loss$^1$.
  • (Jia et al. 2023a) [TKDE]: LDL_LRR$^\dagger$.
  • (Jia et al. 2023b) [TNNLS]: LDL_DPA$^\dagger$.
  • (Wen et al. 2023) [ICCV]: cad$^1$, qfd2$^1$, and cjs$^1$.
  • (Li and Chen 2024) [IJCAI]: WInLDL$^2$.
  • (Kou et al. 2024) [IJCAI]: TLRLDL$^\dagger$ and TKLRLDL$^\dagger$.
  • (Lin et al. 2024) [TBD]: LDL_HVLC$^\dagger$.
  • (Wu, Li, and Jia 2025) [TBD]: LDL_DA$^5$.
  • (Wang et al. 2025) [Pattern Recognit.]: RKNN_LDL$^\dagger$.
  • (Tan et al. 2025) [KBS]: RG4LDL.
  • (Wu, Li, and Jia 2025) [ICML]: S_LRR, S_SCL, S_KLD, S_CJS and S_QFD2.
  • (Li et al. 2025) [ICML]: Delta_LDL.
  • ... and many more LDL algorithms are included! Discover them in the pyldl.algorithms module! 🚀
• LE algorithms:
  • (Xu, Liu, and Geng 2019) [TKDE]: FCM, KM, LP, ML, and GLLE.
  • (Xu et al. 2020) [ICML]: LEVI.
  • (Zheng, Zhu, and Tang 2023) [CVPR]: LIBLE.
  • (Wang et al. 2023) [IJCAI]: ConLE.
• LDL metrics: chebyshev, clark, canberra, kl_divergence, cosine, intersection, etc.
• Structured LDL datasets: Human_Gene, Movie, Natural_Scene, s-BU_3DFE, s-JAFFE, Yeast, etc.
• LDL applications:
  • Facial emotion recognition (supported datasets: JAFFE and BU-3DFE).
  • (Shirani et al. 2019) [ACL]: Emphasis selection (supported datasets: SemEval2020; pre-trained GloVe embeddings can be downloaded here).
  • (Wu et al. 2019) [ICCV]: Lesion counting (supported datasets: ACNE04).
  • (Chen et al. 2020) [CVPR]: Facial emotion recognition with auxiliary label space graphs (supported datasets: CK+; OpenFace can be downloaded here, and the required models can be downloaded here).

$^1$ Technically, these methods are only suitable for totally ordered labels.

$^2$ These are algorithms for incomplete LDL, so you should use pyldl.utils.random_missing to generate the missing label distribution matrix and the corresponding mask matrix in the experiments. Here is a demo on using the incomplete LDL algorithms.

$^3$ These are LDL classifiers, so you should use predict_proba to get label distributions and predict to get predicted labels.

$^4$ These are oversampling algorithms for LDL, therefore you should use fit_transform to generate synthetic samples.

$^5$ To use domain adaptation methods for LDL, you need to provide the source domain data via parameters sX and sy of the fit method. Here is a demo on domain adaptation for LDL.

$^\dagger$ These methods involve imposing constraints on model parameters, like regularization. Therefore, it is recommended to carefully tune the hyperparameters and apply feature preprocessing techniques like StandardScaler or MinMaxScaler before conducting experiments to achieve the expected performance.

❗ News

• 0.1.0: PyLDL now supports both TensorFlow and PyTorch backends through Keras 3. You can switch between the two backends by setting the KERAS_BACKEND environment variable:

import os
os.environ["KERAS_BACKEND"] = "torch"

Installation

PyLDL is now available on PyPI. Use the following command to install.

pip install python-ldl

To install the newest version, you can clone this repo and run the setup.py file.

python setup.py install

Usage

Here is an example of using PyLDL.

from pyldl.utils import load_dataset
from pyldl.algorithms import SA_BFGS
from pyldl.metrics import score

from sklearn.model_selection import train_test_split

dataset_name = 'SJAFFE'
X, D = load_dataset(dataset_name)
X_train, X_test, D_train, D_test = train_test_split(X, D)

model = SA_BFGS()
model.fit(X_train, D_train)

D_pred = model.predict(X_test)
print(score(D_test, D_pred))

For those who would like to use the original implementation:

1. Install MATLAB.
2. Install MATLAB engine for python.
3. Download LDL Package here.
4. Get the package directory of PyLDL (...\Lib\site-packages\pyldl).
5. Place the LDLPackage_v1.2 folder into the matlab_algorithms folder.

Now, you can load the original implementation of the method, e.g.:

from pyldl.matlab_algorithms import SA_IIS

You can visualize the performance of any model on the artificial dataset (Geng 2016) with the pyldl.utils.plot_artificial function, e.g.:

from pyldl.algorithms import LDSVR, SA_BFGS, SA_IIS, AA_KNN, PT_Bayes, GLLE, LIBLE
from pyldl.utils import plot_artificial

methods = ['LDSVR', 'SA_BFGS', 'SA_IIS', 'AA_KNN', 'PT_Bayes', 'GLLE', 'LIBLE']

plot_artificial(model=None, figname='GT')
for i in methods:
    plot_artificial(model=eval(f'{i}()'), figname=i)

The output images are as follows.

(Ground Truth)	LDSVR

SA_BFGS	SA_IIS

AA_KNN	PT_Bayes

GLLE	LIBLE

Refer to the docs for more detailed information. Enjoy! :)

Experiments

For each algorithm, a ten-fold cross validation is performed, repeated 10 times with s-JAFFE dataset and the average metrics are recorded. Therefore, the results do not fully describe the performance of the model.

Results of ours are as follows.

Results of the original MATLAB implementation (Geng 2016) are as follows.

Requirements

Cython
matplotlib
numba
numpy
qpsolvers
quadprog
requests
scikit-fuzzy
scikit-learn
scipy

If you use TensorFlow backend, you also need to install:

tensorflow
tensorflow-probability

If you use PyTorch backend, you also need to install:

torch