Metadata-Version: 2.3
Name: ekuru_ltn
Version: 3.1.0
Summary: A parser for FOL that utilizes NLTK Logic Module to parse and fuzzify FOL rules.
License: Apache 2.0
Author: Emre Kuru
Author-email: emre.kuru@ozu.edu.tr
Requires-Python: >=3.11.0,<4.0.0
Classifier: License :: Other/Proprietary License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Dist: hyperopt (>=0.2.7,<0.3.0)
Requires-Dist: nbconvert (>=7.16.4,<8.0.0)
Requires-Dist: nbformat (>=5.10.4,<6.0.0)
Requires-Dist: pykeen (>=1.10.2,<2.0.0)
Requires-Dist: pyparsing (>=3.1.2,<4.0.0)
Requires-Dist: pyyaml (>=6.0.2,<7.0.0)
Requires-Dist: seaborn (>=0.13.2,<0.14.0)
Requires-Dist: setuptools (>=78.0.0,<79.0.0)
Requires-Dist: tatsu (>=5.12.1,<6.0.0)
Requires-Dist: torch (>=2.3.1,<3.0.0)
Requires-Dist: torchviz (>=0.0.3,<0.0.4)
Requires-Dist: ucimlrepo (>=0.0.7,<0.0.8)
Description-Content-Type: text/markdown

# Logic Tensor Network Implementation (LTN_Imp)

## Overview

This repository contains an implementation of **Logic Tensor Networks (LTN)** for **Symbolic Knowledge Injection (SKI)** into machine learning models. It is particularly relevant for **neuro-symbolic AI**, where structured domain knowledge is integrated into data-driven models to enhance interpretability, performance, and robustness.

This implementation has been used in the research paper:

> **Neuro-symbolic AI for Supporting Chronic Disease Diagnosis and Monitoring**\
> *Matteo Magnini, Giovanni Ciatto, Ahmet Emre Kuru, Christel Sirocchi, and Sara Montagna*

For full reproducibility of the results reported in the paper, please refer to the commit:

> [Commit ](https://github.com/emrekuruu/LTN_Imp/tree/d363aff892f417d770b86253aa8011c4754e8987)[`d363aff892f417d770b86253aa8011c4754e8987`](https://github.com/emrekuruu/LTN_Imp/tree/d363aff892f417d770b86253aa8011c4754e8987)

Here, on the **main branch**, you can find the maintained and refactored codebase.
Experiments on the Pima Indians Diabetes dataset are provided in the [`examples/medical/diabetes/demo.ipynb`](https://github.com/emrekuruu/LTN_Imp/tree/main/examples/medical/diabetes/demo.ipynb) notebook.

### Results summary of model performance against different data perturbations
![image](examples/medical/diabetes/robustness_metrics.png)
                                 
Each dot represents the average performance of the model with 30 seeds on the same experiment configuration.

## Features

- **LTN-based Knowledge Injection**: Implements logic-based constraints in neural networks.
- **Medical AI Applications**: Evaluates SKI on medical datasets, focusing on chronic disease prediction.
- **Performance & Robustness Analysis**: Compares LTN with classical ML models in terms of accuracy, recall, and adherence to clinical guidelines.
- **Reproducible Experiments**: Code used to generate results in the referenced paper.

## Requirements

To set up the environment, install the necessary dependencies using Poetry:

```bash
poetry install
```

## Usage

### Running Experiments

To reproduce the experiments from the referenced paper, use the provided Jupyter Notebook:

> [`examples/medical/diabetes/demo.ipynb`](https://github.com/emrekuruu/LTN_Imp/blob/d363aff892f417d770b86253aa8011c4754e8987/examples/medical/diabetes/demo.ipynb)

This notebook walks through the process of training and evaluating the LTN model, comparing it against classical ML baselines while considering:

- **Predictive performance** (Accuracy, Recall, F1-score, MCC)
- **Logical adherence** to clinical rules
- **Robustness** under data perturbation (noise injection, missing data, label flipping)

## Datasets

The primary dataset used in the experiments is:

- **Pima Indians Diabetes (PID) dataset**: A benchmark dataset for diabetes prediction.

## Model Architectures

The following models are implemented and compared:

- **Classic ML Models:**
  - K-Nearest Neighbors (KNN)
  - Decision Tree (DT)
  - Random Forest (RF)
  - Logistic Regression (LR)
  - Multi-Layer Perceptron (MLP)
- **Logic Tensor Network (LTN)**: Incorporates symbolic knowledge via logical constraints.

## Results Summary

The key findings from the experiments include:

- **LTN improves recall and balanced accuracy**, making it more suitable for medical AI applications where false negatives must be minimized.
- **LTN exhibits higher adherence to clinical rules**, ensuring predictions align with medical guidelines.
- **LTN demonstrates robustness to data perturbations**, maintaining stable performance even with missing or noisy data.

For detailed results, refer to the paper.

## Acknowledgments

Special thanks to the authors of the referenced paper and the contributors of the **LTN_Imp** repository.

## License

This repository is released under the Apache 2.0 license.

---

For any issues or questions, feel free to open an [issue](https://github.com/emrekuruu/LTN_Imp/issues).



## Project structure
Overview:

```bash
<root directory>
├── ltn_imp/             # main package (should be named after your project)
│   ├── __init__.py         # python package marker
│   └── __main__.py         # application entry point
│   └── fuzzy_operators     # folder for all of the fuzzy operators
│   └── parsing             # folder for the parser utilizing NLTK Logic and all the needed files
│   
├── test/                   # test package contains unit tests
│   ├── parsing_tests       # folder for unit tests for parser
│   └── learning_tests      # folder for unit tests for fuzzy operators in optimization
│   
├── .github/                # configuration of GitHub CI
│   └── workflows/          # configuration of GitHub Workflows
│       └──  check.yml       # runs tests on multiple OS and versions of Python
│
├── LICENSE                 # license file (Apache 2.0 by default)
├── pyproject.toml          # declares build dependencies
└── poetry.toml             # Poetry settings
```
