Merge pull request #271 from dice-group/develop

Merge before the new release

README.md

@@ -1,28 +1,64 @@
 # Ontolearn
 
-Ontolearn is an open-source software library for explainable structured machine learning in Python.
-
+*Ontolearn* is an open-source software library for explainable structured machine learning in Python.
+It contains the following (ready-to-apply) algorithms that learn OWL class expressions from positive and negative examples:
+- **NCES2** → (soon) [Neural Class Expression Synthesis in ALCHIQ(D)](https://papers.dice-research.org/2023/ECML_NCES2/NCES2_public.pdf)
+- **Drill** → [Deep Reinforcement Learning for Refinement Operators in ALC](https://arxiv.org/pdf/2106.15373.pdf)
+- **NCES** → [Neural Class Expression Synthesis](https://link.springer.com/chapter/10.1007/978-3-031-33455-9_13)
+- **NERO** → (soon) [Learning Permutation-Invariant Embeddings for Description Logic Concepts](https://github.com/dice-group/Nero)
+- **EvoLearner** → [An evolutionary approach to learn concepts in ALCQ(D)](https://dl.acm.org/doi/abs/10.1145/3485447.3511925)
+- **CLIP** → (soon) [Learning Concept Lengths Accelerates Concept Learning in ALC](https://link.springer.com/chapter/10.1007/978-3-031-06981-9_14)
+- **CELOE** → [Class Expression Learning for Ontology Engineering](https://www.sciencedirect.com/science/article/abs/pii/S1570826811000023)
+- **OCEL** → A limited version of CELOE
+
+You can find more details about *Ontolearn* and these algorithms and their variations in the [documentation](https://ontolearn-docs-dice-group.netlify.app/index.html).
+
+Quick navigation: 
+- [Installation](#installation)
+- [Usage](#usage)
+- [Relevant Papers](#relevant-papers)
+## Installation
+For detailed instructions please refer to the [installation guide](https://ontolearn-docs-dice-group.netlify.app/usage/installation.html) in the documentation.
+
+### Installation from source
+
+Make sure to set up a virtual python environment like [Anaconda](https://www.anaconda.com/) 
+before continuing with the installation. 
+
+
+To successfully pass all the tests you need to download some external resources in advance 
+(see [_Download external files_](#download-external-files-link-files)). We recommend to
+download them all. Also, install _java_ and _curl_ if you don't have them in your system:
+
+```commandline
+sudo apt install openjdk-11-jdk
+sudo apt install curl
+```
 
-### Installation
+A quick start up will be as follows:
 
 ```shell
-git clone https://github.com/dice-group/Ontolearn.git
-cd Ontolearn
-conda create --name temp python=3.8
-conda activate temp
-conda env update --name temp
+git clone https://github.com/dice-group/Ontolearn.git && conda create --name onto python=3.8 && conda activate onto 
+# Incase needed
+# conda env update --name onto
 python -c 'from setuptools import setup; setup()' develop
 python -c "import ontolearn"
 python -m pytest tests # Partial test with pytest
 tox  # full test with tox
 ```
-
 #### Installation via pip
+
 ```shell
-pip install ontolearn  # currently it is only a place holder https://pypi.org/project/ontolearn/
+pip install ontolearn  # more on https://pypi.org/project/ontolearn/
 ```
+## Usage
+
+In the [examples](https://github.com/dice-group/Ontolearn/tree/develop/examples) folder, you can find examples on how to use
+the learning algorithms. Also in the [tests](https://github.com/dice-group/Ontolearn/tree/develop/tests) folder we have added some test cases.
 
-### Examples
+For more detailed instructions we suggest to follow the [guides](https://ontolearn-docs-dice-group.netlify.app/usage/03_algorithm.html) in the documentation.
+
+Below we give a simple example on using CELOE to learn class expressions for a small dataset.
 ```python
 from ontolearn.concept_learner import CELOE
 from ontolearn.model_adapter import ModelAdapter
@@ -53,57 +89,121 @@ dlsr = DLSyntaxObjectRenderer()
 for desc in model.best_hypotheses(1):
     print('The result:', dlsr.render(desc.concept), 'has quality', desc.quality)
 ```
-### Download external files (.link files)
+The goal in this example is to learn a class expression for the concept "father". 
+The output is as follows:
+```
+The result: (¬female) ⊓ (∃ hasChild.⊤) has quality 1.0
+```
+
+For a quick start on how to use NCES, please refer to the notebook [simple usage NCES](examples/simple-usage-NCES.ipynb)
+
+----------------------------------------------------------------------------
+
+#### Download external files (.link files)
 
 Some resources like pre-calculated embeddings or `pre_trained_agents`
 are not included in the Git repository directly. Use the following
 command to download them from our data server.
 
+For Drill:
 ```shell
 ./big_gitext/download_big.sh examples/pre_trained_agents.zip.link
 ./big_gitext/download_big.sh -A  # to download them all into examples folder
 ```
 
+For NCES:
+```shell
+./big_gitext/download_nces_data
+```
+
 To update or upload resource files, follow the instructions
 [here](https://github.com/dice-group/Ontolearn-internal/wiki/Upload-big-data-to-hobbitdata)
-and use the following command.
+and use the following command (only for Drill):
 
 ```shell
 ./big_gitext/upload_big.sh pre_trained_agents.zip
 ```
+----------------------------------------------------------------------------
+#### Building (sdist and bdist_wheel)
+You can use <code>tox</code> to build sdist and bdist_wheel packages for Ontolearn.
+- "sdist" is short for "source distribution" and is useful for distribution of packages that will be installed from source.
+- "bdist_wheel" is short for "built distribution wheel" and is useful for distributing packages that include large amounts of compiled code, as well as for distributing packages that have complex dependencies.
 
-### Building (sdist and bdist_wheel)
-
+To build and compile the necessary components of Ontolearn, use:
 ```shell
 tox -e build
 ```
 
-#### Building the docs
-
+To automatically build and test the documentation of Ontolearn, use:
 ```shell
 tox -e docs
 ```
 
-## How to cite
+----------------------------------------------------------------------------
+
+#### Simple Linting
+
+Using the following command will run the linting tool [flake8](https://flake8.pycqa.org/) on the source code.
+```shell
+tox -e lint --
+```
+----------------------------------------------------------------------------
+
+#### Contribution
+Feel free to create a pull request!
+
+
+## Relevant papers
+
+- [NCES2](https://papers.dice-research.org/2023/ECML_NCES2/NCES2_public.pdf): Neural Class Expression Synthesis in ALCHIQ(D)
+- [NCES](https://link.springer.com/chapter/10.1007/978-3-031-33455-9_13): Neural Class Expression Synthesis
+- [Evolearner](https://doi.org/10.1145/3485447.3511925): Learning description logics with evolutionary algorithms.
+- [CLIP](https://link.springer.com/chapter/10.1007/978-3-031-06981-9_14): Learning Concept Lengths Accelerates Concept Learning in ALC.
+### Citing
 Currently, we are working on our manuscript describing our framework. 
-If you really like our work and want to cite it now, feel free to chose one :) 
+If you find our work useful in your research, please consider citing the respective paper:
 ```
-# Evolearner
+
+# NCES2
+@inproceedings{kouagou2023nces2,
+author={Kouagou, N'Dah Jean and Heindorf, Stefan and Demir, Caglar and Ngonga Ngomo, Axel-Cyrille},
+title={Neural Class Expression Synthesis in ALCHIQ(D)},
+url = {https://papers.dice-research.org/2023/ECML_NCES2/NCES2_public.pdf},
+booktitle={Machine Learning and Knowledge Discovery in Databases},
+year={2023},
+publisher={Springer Nature Switzerland},
+address="Cham"
+}
+
+# NCES
+@inproceedings{kouagou2023neural,
+  title={Neural class expression synthesis},
+  author={Kouagou, N’Dah Jean and Heindorf, Stefan and Demir, Caglar and Ngonga Ngomo, Axel-Cyrille},
+  booktitle={European Semantic Web Conference},
+  pages={209--226},
+  year={2023},
+  publisher={Springer Nature Switzerland}
+}
+
+# EvoLearner
 @inproceedings{heindorf2022evolearner,
   title={Evolearner: Learning description logics with evolutionary algorithms},
   author={Heindorf, Stefan and Bl{\"u}baum, Lukas and D{\"u}sterhus, Nick and Werner, Till and Golani, Varun Nandkumar and Demir, Caglar and Ngonga Ngomo, Axel-Cyrille},
   booktitle={Proceedings of the ACM Web Conference 2022},
   pages={818--828},
   year={2022}
 }
+
+
 # CLIP
 @inproceedings{kouagou2022learning,
   title={Learning Concept Lengths Accelerates Concept Learning in ALC},
-  author={Kouagou, N and Heindorf, Stefan and Demir, Caglar and Ngonga Ngomo, Axel-Cyrille},
+  author={Kouagou, N’Dah Jean and Heindorf, Stefan and Demir, Caglar and Ngonga Ngomo, Axel-Cyrille},
   booktitle={European Semantic Web Conference},
   pages={236--252},
   year={2022},
-  organization={Springer}
+  publisher={Springer Nature Switzerland}
 }
 ```
+
 For any further questions, please contact:  ```[email protected]```

big_gitext/download_nces_data

@@ -0,0 +1,3 @@
+! wget https://hobbitdata.informatik.uni-leipzig.de/NCES_Ontolearn_Data/NCESData.zip -O ./NCESData.zip
+! unzip -o ./NCESData.zip
+! rm -f ./NCESData.zip