{"id":24314479,"url":"https://github.com/ayrna/dlordinal","last_synced_at":"2025-09-26T21:30:39.428Z","repository":{"id":208405166,"uuid":"707154421","full_name":"ayrna/dlordinal","owner":"ayrna","description":"Open-source Python toolkit focused on deep learning with ordinal methodologies","archived":false,"fork":false,"pushed_at":"2024-04-22T11:18:04.000Z","size":562,"stargazers_count":9,"open_issues_count":3,"forks_count":0,"subscribers_count":3,"default_branch":"main","last_synced_at":"2024-04-22T12:33:46.898Z","etag":null,"topics":["deep-learning","ordinal-classification","python","pytorch","scikit-learn"],"latest_commit_sha":null,"homepage":"","language":"Jupyter Notebook","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ayrna.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2023-10-19T10:31:59.000Z","updated_at":"2024-04-26T08:45:31.983Z","dependencies_parsed_at":"2023-12-20T12:33:29.555Z","dependency_job_id":"b8076fc5-52a4-46ad-a773-bf0bfae21d14","html_url":"https://github.com/ayrna/dlordinal","commit_stats":null,"previous_names":["ayrna/dlordinal"],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ayrna%2Fdlordinal","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ayrna%2Fdlordinal/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ayrna%2Fdlordinal/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ayrna%2Fdlordinal/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ayrna","download_url":"https://codeload.github.com/ayrna/dlordinal/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":234225335,"owners_count":18798965,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["deep-learning","ordinal-classification","python","pytorch","scikit-learn"],"created_at":"2025-01-17T10:13:38.966Z","updated_at":"2025-09-26T21:30:39.422Z","avatar_url":"https://github.com/ayrna.png","language":"Jupyter Notebook","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Welcome to `dlordinal`\n\n`dlordinal` is a Python library that unifies many recent deep ordinal classification methodologies available in the literature. Developed using PyTorch as underlying framework, it implements the top performing state-of-the-art deep learning techniques for ordinal classification problems. Ordinal approaches are designed to leverage the ordering information present in the target variable. Specifically, it includes loss functions, various output layers, dropout techniques, soft labelling methodologies, and other classification strategies, all of which are appropriately designed to incorporate the ordinal information. Furthermore, as the performance metrics to assess novel proposals in ordinal classification depend on the distance between target and predicted classes in the ordinal scale, suitable ordinal evaluation metrics are also included.\n\nThe latest `dlordinal` release is `v2.4.4`. You can view all the changes made in the current and previous versions in the [CHANGELOG](./CHANGELOG.md).\n\n| Overview  |                                                                                                                                          |\n|-----------|------------------------------------------------------------------------------------------------------------------------------------------|\n| **CI/CD** | [![Run Tests](https://github.com/ayrna/dlordinal/actions/workflows/run_tests.yml/badge.svg?branch=main)](https://github.com/ayrna/dlordinal/actions/workflows/run_tests.yml) [![!codecov](https://img.shields.io/codecov/c/github/ayrna/dlordinal?label=codecov\u0026logo=codecov)](https://codecov.io/gh/ayrna/dlordinal) [![!docs](https://readthedocs.org/projects/dlordinal/badge/?version=latest\u0026style=flat)](https://dlordinal.readthedocs.io/en/latest/)  [![!python](https://img.shields.io/badge/python-3.8%20%7C%203.9%20%7C%203.10%20%7C%203.11%20%7C%203.12%20%7C%203.13-blue)](https://www.python.org/) |\n| **Code**  | [![![pypi]](https://img.shields.io/pypi/v/dlordinal)](https://pypi.org/project/dlordinal/) [![![binder]](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/ayrna/dlordinal/main?filepath=tutorials) [![!black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black) [![Linter: Ruff](https://img.shields.io/badge/Linter-Ruff-brightgreen?style=flat-square)](https://github.com/charliermarsh/ruff)                     |\n\n\n## Table of Contents\n- [Welcome to `dlordinal`](#welcome-to-dlordinal)\n  - [Table of Contents](#table-of-contents)\n  - [⚙️ Installation](#️-installation)\n  - [🚀 Getting started](#-getting-started)\n    - [Loading an ordinal benchmark dataset](#loading-an-ordinal-benchmark-dataset)\n    - [Training a CNN model using the `skorch` library](#training-a-cnn-model-using-the-skorch-library)\n  - [📖 Documentation](#-documentation)\n  - [Collaborating](#collaborating)\n    - [Guidelines for code contributions](#guidelines-for-code-contributions)\n  - [Citation](#citation)\n\n## ⚙️ Installation\n\n`dlordinal v2.4.4` is the last version, supported from Python 3.8 to Python 3.12.\n\nThe easiest way to install `dlordinal` is via `pip`:\n\n```bash\npip install dlordinal\n```\n\n## 🚀 Getting started\n\nThe best place to get started with `dlordinal` is the [tutorials directory](https://github.com/ayrna/dlordinal/tree/main/tutorials).\n\nBelow we provide a quick example of how to use some elements of `dlordinal`, such as a dataset, a loss function or some metrics.\n\n### Loading an ordinal benchmark dataset\n\nThe FGNet is a well-known benchmark dataset that is commonly used to benchmark ordinal classification methodologies. The dataset is composed of facial images and is labelled with different age categories. It can be downloaded and loaded into Python by simply using the `dlordinal.datasets.FGNet` class.\n\n```python\nimport numpy as np\nfrom dlordinal.datasets import FGNet\nfrom torchvision.transforms import Compose, ToTensor\n\nfgnet_train = FGNet(\n    root=\"./datasets\",\n    train=True,\n    target_transform=np.array,\n    transform=Compose([ToTensor()]),\n)\nfgnet_test = FGNet(\n    root=\"./datasets\",\n    train=False,\n    target_transform=np.array,\n    transform=Compose([ToTensor()]),\n)\n\n```\n\n### Training a CNN model using the `skorch` library\n\nThis example shows how to train a CNN model using the `NeuralNetClassifier` from the `skorch` library and the `TriangularLoss` with ``CrossEntropyLoss`` from `dlordinal` as optimisation criterion.\n\n```python\nimport numpy as np\nfrom dlordinal.datasets import FGNet\nfrom dlordinal.losses import TriangularLoss\nfrom dlordinal.metrics import amae, mmae\nfrom skorch import NeuralNetClassifier\nfrom torch import nn\nfrom torch.optim import Adam\nfrom torchvision import models\nfrom torchvision.transforms import Compose, ToTensor\n\n# Download the FGNet dataset\nfgnet_train = FGNet(\n    root=\"./datasets\",\n    train=True,\n    target_transform=np.array,\n    transform=Compose([ToTensor()]),\n)\nfgnet_test = FGNet(\n    root=\"./datasets\",\n    train=False,\n    target_transform=np.array,\n    transform=Compose([ToTensor()]),\n)\n\nnum_classes_fgnet = len(fgnet_train.classes)\n\n# Model\nmodel = models.resnet18(weights=\"IMAGENET1K_V1\")\nmodel.fc = nn.Linear(model.fc.in_features, num_classes_fgnet)\n\n# Loss function\nloss_fn = TriangularLoss(base_loss=nn.CrossEntropyLoss(), num_classes=num_classes_fgnet)\n\n# Skorch estimator\nestimator = NeuralNetClassifier(\n    module=model,\n    criterion=loss_fn,\n    optimizer=Adam,\n    lr=1e-3,\n    max_epochs=25,\n)\n\nestimator.fit(X=fgnet_train, y=fgnet_train.targets)\ntrain_probs = estimator.predict_proba(fgnet_train)\ntest_probs = estimator.predict_proba(fgnet_test)\n\n# Metrics\namae_metric = amae(np.array(fgnet_test.targets), test_probs)\nmmae_metric = mmae(np.array(fgnet_test.targets), test_probs)\nprint(f\"Test AMAE: {amae_metric}, Test MMAE: {mmae_metric}\")\n```\n\n## 📖 Documentation\n\nYou can check the documentation [here](https://dlordinal.readthedocs.io/en/latest/).\n\n`Sphinx` is a documentation generator tool that is commonly used in the Python ecosystem. It allows developers to write documentation in a markup language called reStructuredText (reST) and generates HTML, PDF, and other formats from it. Sphinx provides a powerful and flexible way to document code, making it easier for developers to create comprehensive and user-friendly documentation for their projects.\n\nTo document `dlordinal`, it is necessary to install all documentation dependencies:\n\n```bash\npip install -e '.[docs]'\n```\n\nThen access the `docs/` directory:\n\n```bash\ndocs/\n↳ api.rst\n↳ conf.py\n↳ distributions.rst\n↳ references.bib\n↳ ...\n```\n\nIf a new module is created in the software project, the `api.rst` file must be modified to include the name of the new module:\n\n```plaintext\n.. _api:\n\n=============\nAPI Reference\n=============\n\nThis is the API for the **dlordinal** package.\n\n.. toctree::\n   :maxdepth: 2\n   :caption: Contents:\n\n   datasets\n   dropout\n   output_layers\n   losses\n   metrics\n   wrappers\n   soft_labelling\n   ***NEW_MODULE***\n```\n\nAfterwards, a new file in `.rst` format associated to the new module must be created, specifying the automatic inclusion of documentation from the module files containing a docstring, and the inclusion of the bibliography if it exists within any of them.\n\n```bash\ndocs/\n↳ api.rst\n↳ conf.py\n↳ distributions.rst\n↳ new_module.rst\n↳ references.bib\n↳ ...\n```\n\n```plaintext\n.. _new_module:\n\nNew Module\n==========\n\n.. automodule:: dlordinal.new_module\n    :members:\n\n.. footbibliography::\n\n```\n\nFinally, if any new bibliographic citations have been added, they should be included in the `references.bib` file.\n\n## Collaborating\n\nCode contributions to the dlordinal project are welcomed via pull requests.\nPlease, contact the maintainers (maybe opening an issue) before doing any work to make sure that your contributions align with the project.\n\n### Guidelines for code contributions\n\n* You can clone the repository and then install the library from the local repository folder:\n\n```bash\ngit clone git@github.com:ayrna/dlordinal.git\npip install ./dlordinal\n```\n\n* In order to set up the environment for development, install the project in editable mode and include the optional dev requirements:\n```bash\npip install -e '.[dev]'\n```\n* Install the pre-commit hooks before starting to make any modifications:\n```bash\npre-commit install\n```\n* Write code that is compatible with all supported versions of Python listed in the `pyproject.toml` file.\n* Create tests that cover the common cases and the corner cases of the code.\n* Preserve backwards-compatibility whenever possible, and make clear if something must change.\n* Document any portions of the code that might be less clear to others, especially to new developers.\n* Write API documentation as docstrings.\n\n## Citation\n\nIf you use dlordinal we would appreciate a citation of the following [paper](https://doi.org/10.1016/j.neucom.2024.129305)\n\n```bibtex\n@article{berchez2025dlordinal,\n  title={dlordinal: A Python package for deep ordinal classification},\n  author={B{\\'e}rchez-Moreno, Francisco and Ayll{\\'o}n-Gavil{\\'a}n, Rafael and Vargas, V{\\'\\i}ctor M and Guijo-Rubio, David and Herv{\\'a}s-Mart{\\'\\i}nez, C{\\'e}sar and Fern{\\'a}ndez, Juan C and Guti{\\'e}rrez, Pedro A},\n  journal={Neurocomputing},\n  pages={129305},\n  year={2025},\n  publisher={Elsevier},\n  doi={10.1016/j.neucom.2024.129305}\n}\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fayrna%2Fdlordinal","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fayrna%2Fdlordinal","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fayrna%2Fdlordinal/lists"}