DEV Community

Daniēls Zeps
Daniēls Zeps

Posted on

Audit System - NewStarT (Custom OWL)

#django #opensource #python #tutorial

NewStarT Audit is an open-source no-coding shell of a rule-based expert system developed within the project NewStart (lzp-2022/1-0350) focused to enhance the competition of regional tourism products. The system is made using Django framework and is designed to provide an audit of products/ services to identify their correct category and quality level. Data can be imported using OWL ontology or added manually using Django admin template. The shell is developed as a Django app and can be integrated into other Django projects. The key features of the system are depicted in another article https://medium.com/@DanielsZeps/newstart-audit-system-360fcc5630b6.

This article is a setup guide for developers. The source code of the project, is available on GitHub and Docker.

This article covers the following subjects:

  1. Setting up the project using an example with tourism product assessment ontology;
  2. Creating your own custom ontology.

1. Setting up the system

1.1. Setting up with Docker

System image is available on Docker. It has no external connections and sets up automatically once the image is ran.
https://hub.docker.com/r/flpp20191/new-start-audit

1.2. Local setup

Prerequisites:

  • Python 3.10+
  • Django version: 5.2.11+
  • pip

1.3. Setting up using GitHub repository

The first step is downloading the project from GitHub repository using git or downloading the .zip archive. After that you need to go to the root folder with manage.py file.

git clone https://github.com/flpp20191/NewStarT_Audit
cd NewStarT_Audit
Enter fullscreen mode Exit fullscreen mode

If you want to set up virtual environment, the information is available on GitHub.
After this you need to install dependencies, by running pip install -r requirements.txt, which will install the necessary Python packages.

1.4. System environment variables

To set up system environment variables you must run the next command, which will copy predefined variables to root.

# On maxOS/Linux
cd root
cp ./Example/.env.example .env
# On Windows
cd root
copy ./Example/.env.example .env
Enter fullscreen mode Exit fullscreen mode

If you are planning to run the shell on a public server, you should generate a new SECRET_KEY and replace it in the .env file. By default the shell uses Sqlite3 database. If you are running it locally, it will work well enough, but you can change the database in the .env file to use your preferred database, for example MySQL.

from django.core.management.utils import get_random_secret_key; print(get_random_secret_key())
Enter fullscreen mode Exit fullscreen mode

The previous Python code will output a secure key that you should copy and paste into your .env file under the SECRET_KEY variable:

SECRET_KEY=placeholder_generated_secret_key
Enter fullscreen mode Exit fullscreen mode

Users can choose to recalculate their score if changes have been made to questions/conditions by admin. To prevent overloading DB, users can do it once every 5 minutes. Admin can change this time in system environment variables by changing SCORE_UPDATE_DELAY.
If you are adding this Django app to an existing project, you might need to remake the migration files, because they might not be compatible with your current project database.

1.5. Running the project

To make sure that the project is fully set up, you need to run:

python manage.py setup
python manage.py createsuperuser
python manage.py runserver
Enter fullscreen mode Exit fullscreen mode

These commands will run the initial setup of the app, create a superuser account and run the server.
Command "runserver" will start the app on a localhost, which you can access by http://127.0.0.1:8000/. You can use the login information you input when you ran the "createsuperuser" command to login into the system. This will let you access a blank project with no data.

1.6. Data import (using UI)

After login into the system as a superuser, you can go to "OWL management", to upload an OWL file.
You can use "Example/NewStarT.owl" and "Example/NewStarT.yml" to test out the data adding on tourism data.

OWL file upload
This also will allow you to upload a costume ontology file. If you used "Example/template.owl" as the base for your ontologies, you can continue with default configurations. Making your own ontology, is described later in the article.

Default upload configurations

LANGUAGE: 'en' #Language tag used for labels
HAS_CATEGORY: #Object property that point to category
- https://newstart.rta.lv#hasCategory
HAS_GROUP #Grouping object property
- https://newstart.rta.lv#hasGroup
HAS_HINT_TEXT #Hint text
- https://newstart.rta.lv#hasMesurement
HAS_QUESTION_TYPE: true
QUESTION_TYPE #Question types (INTERVAL/LIKERT)
  INTERVAL #If questions have interval answer types
    MAX #Max allowed interval value
    - https://newstart.rta.lv#hasMaxAllowedValue
    MIN #Min allowed interval value
    - https://newstart.rta.lv#hasMinAllowedValue
  LIKERT: #If questions have Likert answer types
    #Anwer that should be selected as Likert answer
    LIKERT_ANSWER_PROPERTY:
    - https://newstart.rta.lv#hasExpectedAnswer
    #List of choices for a Likert question
    LIKERT_CHOICES:
    - https://newstart.rta.lv#hasAnswerOptions
    #String used to split up choices
    SEPERATOR: '

            '
  # Highlighted questions
  MANDATORY:
  - https://newstart.rta.lv#isMandatory
  # Answer type indicator (Yes/No, Likert, Interval)
  PROPERTIES:
  # Class objects that indicate an answer type
  - https://newstart.rta.lv#hasAnswerType
  TYPES:
    # Class IRI
    interval:
    - https://newstart.rta.lv#interval
    likert:
    - https://newstart.rta.lv#likert
    yes_no:
    - https://newstart.rta.lv#yesno
Enter fullscreen mode Exit fullscreen mode

1.7. Data import (using admin CMD)

System admin/superuser can upload an existing OWL file into the system, by following prompts in the CMD. The system lets the user to determine what properties correlate to which DB constraints, and imports data based on this information. The system comes with an OWL file example from the NewStarT project and a OWL template file for a custom ontology construction.
The OWL file only requires Category->Question restraint. All other functions for the audit are optional.

Question(Class)->hasCategory->SomeCategory(Class)
Enter fullscreen mode Exit fullscreen mode

You can run the command to add the OWL file from the NewStarT Audit project to test out the system.

python manage.py uploadOwl --filepath Example/NewStarT.owl --language en --make_config --config_filename Example/conf_output.yml --conf Example/conf.yml
Enter fullscreen mode Exit fullscreen mode

OWL import result using Example data
Data that is required for recommendation system to function are: Category, Question and Subtheme. Condition is an object property that connects, questions to Category.

Data structure
In case data structure gets updated, the system uses IRIs to store OWL references, so the file can be imported again and only the new OWL entries will be modified. If an IRI is not present in the OWL file, it will be left untouched.
OWL file example

2. Creating your custom ontology

2.1. Creating an ontology using OWL

To create your custom ontology, you don't need to use specific IRIs. You have to have simply a consistent relationship structure.
The Question and Category hierarchy will be created using hierarchy presented in the OWL file. A question can appear in multiple questionnaires depending on how your hierarchy is organised.
The database data will be created based on your ontology and upload configurations you used.

Category hierarchy in OWL compare to Audit
Category hierarchy in OWL compare to Audit

2.2. Adding relationships

You have to add a relationship from question to category, to show what category a question indicates. It has to be an object property and it should follow this syntax:

Question(Class)->hasCategory->SomeCategory(Class)
Enter fullscreen mode Exit fullscreen mode

For example, if food business locally sources their food, it is more likely to be a "Home café".
hasCategory relationship example

2.3. Specifying question types

By default it is assumed that a question is a "Yes/No" question, but you can specify what question type is expected for a specific question.
To do that you need to create Classes for each question type (already present in "template.owl"):

  • Yes/No;
  • Likert;
  • Interval.

And use an object property to indicate question type. For example in the:

Question(Class)->hasExpectedAnswerType->YesNo(Class)
Enter fullscreen mode Exit fullscreen mode

This is required, because otherwise system has no way of knowing, how a question should be imported.
You can add "Not" to the relationship, to indicate a inverse relationship to a category.

LIKERT - requirements

To use Likert questions, two additional relationships need to be added.

  • Has answer options (Data Property)
  • Has expected answer (Data Property)

Relationship "hasAnswerOptions" indicates, what will appear in the Liker scale dropdown. Relationship "expectedAnswer" is the threshold that a user has to select to match the result. In this example, in a tier 3 camping site at least 80% of trailers have to have access to electricity.

Likert choices

INTERVAL- requirements

To use Interval questions, two additional relationships need to be added.

  • Has min answer(Data Property)
  • Has max answer(Data Property)

Min answer, indicates minimal acceptable answer. Max answer indicates max inclusive answer.
Interval example

2.4. Additional properties

Since the NewStarT system needed some of these utility properties, they have been also added to this Audit system.

Hint text (object property)
Shows expected answer format, for example "meters" or "minutes".

Question(Class)->hasHintText->Meters(Class)
Enter fullscreen mode Exit fullscreen mode

Hint text example

Group (object property)
Groups questions in block, to improve readability. For example "By cooking technology" in Canteen characteristics.

Question(Class)->hasSpecialization->"By target group"(Class)
Enter fullscreen mode Exit fullscreen mode

Group example

Highlighting (data property)
Indicates answer scores for questions that are more important.

Question(Class)->isMandatory->true(bool)
Enter fullscreen mode Exit fullscreen mode

Score higlighting

If you have any follow up questions reach out to us through our GitHub page: https://github.com/flpp20191/NewStarT_Audit

Suggestions

When making a custom OWL file, if you are new to using OWL, we advise you to use WebProtégé, since its UI is simpler and less overwhelming.
Advanced users should use https://protege.stanford.edu/. It lets you use more of the systems functions, which are not present in the web version.

Acknowledgement

This research was funded by the "Fundamental and Applied Research (FLPP)", project "Digital Twin to Promote the Development of Tourism Competitiveness and Complementarity: the Use Case in Latgale region", project No. lzp-2022/1–0350

Top comments (0)