Repository files navigation

LaMa is a Thematic Labelling web application that can facilitate easier analysis of texts by allowing to add labels to these text artifacts and group the created labels into themes. This tool was developed by a team of nine students for the Final Bachelor Project at the Eindhoven University of Technology.

The tool was created to facilitate collaboration and peer feedback on labelled artifacts. LaMa allows for the user to label text in order to find patterns in qualitative data. Using this tool will allow for an easier, faster, and more structured way for one or more people to label a given text and resolve any conflicts that arise between labels. Additionally, it provides an free and open-source alternative for the commercial tools, such asAtlas.ti andmaxQDA.

This project builds upon the already existingLabeling Machine tool by extending it and adding new functionalities, which include but are not limited to a new API and remaking the User Interface (UI).

1. Dependencies
2. Installation
3. User Manual
4. Testing
5. Acknowledgements

For deployment using docker:

1. Docker ≥ 20.10 (with compose plugin)
2. Git ≥ 2.37.0

For development these are the dependencies/tools without which LaMa may not work:

1. NodeJS ≥ 16.15
2. AngularCLI ≥ 13.3.10
3. Python ≥ 3.10
4. pip ≥ 22.1.2
5. Docker ≥ 20.10 (with compose plugin)
6. IDE (optional, but recommended for easier development. We recommendPyCharm for Backend andVSCode for Frontend)

Assuming that you have all the necessary dependencies installed.

1. Clone repository
2. Navigate to the repository in a terminal
3. To start the application run:

docker compose --env-file .env -f Docker/docker-compose.yml up --build -d

4. To shut down the application run:

docker compose --env-file .env -f Docker/docker-compose.yml down

You should now have LaMa running in your browser. By default, the frontend server runs onlocalhost and default login credentials areadmin as username &password as password.

Database:

1. Open a terminal in the root directory of the repository
2. Start the database with:

docker compose --env-file .env -f Docker/docker-compose-db.yml up --build -d

3. Shut down the database with:

docker compose --env-file .env -f Docker/docker-compose-db.yml down

Frontend:

1. Open a terminal in the frontend directory
2. Runnpm i
3. Create the environment variables,npx tsx .\src\setenv.ts
4. Runng serve
5. The frontend server will run on localhost:4200

Backend:

1. Set theFLASK_ENV environment variable todevelopment
2. Open a terminal in the backend directory
3. On your first time create a virtual environment withpython -m venv venv
4. Activate your virtual environment,.\venv\Scripts\activate on Windows orsource venv/bin/activate on Linux
5. Runpip install -r requirements.txt
6. Run the following commands:

flask db-safe initflask db migrateflask db upgradeflask db-safe add-super-adminflask run --host=0.0.0.0

7. On teardown do not forget to revert theFLASK_ENV environment variable toproduction, and rundeactivate to deactivate the virtual environment

The Environment variables can be found in the .env file in the root of the repository. Here all of the default values for the necessary variables are set. If one wants to change any of these variables they should change the values in this file.

The file is divided into sections:

1. Database - these are all the variables that have anything to do with the database, such as the database port, database login details etc.
2. PhPMyadmin - this is where the port for the phpmyadmin is defined
3. LaMa Config - these variables defines the superadmin username and password. Please, note that a superadmin is created by default who has access of all the projects and their contents. The AUTO_APPROVAL variable determines whether new accounts are approved by default, or must be approved by super admins, it should parse as a boolean.
4. Flask Server - these are the variables needed to run the flask server.
5. Frontend Server - these are two variables for the urls to the backend server. The frontend uses these variables to interact with the apis provided by the backend.

With the database running do the following:

1. Go the PMA, which runs on localhost:81 by default.
2. In the lama database, check all tables anddrop them. Youwill lose all your data.
3. Go to the import tab, choose thesample.sql file found in the root of the repository, and press Go.

The sample database contains one project on the topic of restaurant reviews, and this project already has some labelled artifacts. The three main criteria for reviews are the food, service, and decor. There are two users with the following login details:

• Username:admin Password:password
• Username:John Doe Password:Testing123

Projects are the fundamental building block of the tool, functionalities are on a per project basis. There are 2 ways to participate in a project:

• Create your own project
• Join an existing project

Creating a project can be done through theCreate project button at the top right of the screen, this opens a menu in which settings of the project can be configured.

To join an existing project the project admin of that project needs to add your account through theproject setting menu of the project. The project settings menu can be opened through thesetting (gear icon) in the menu bar on the left after opening the project.

After participating in a project, for any functionality first artifacts have to be added. Artifacts can be added by navigating to theArtifact management page, from the navigation menu on the left after opening the project. On the artifact management page click theAdd artifact button at the top right, and upload a.txt file containing the artifact(s).

After having uploaded artifacts it is possible to start labelling them. Navigate using thenavigation menu on the left to thelabelling page. An artifact will be shown here. To label an artifact, select labels from thedropdown menu below the artifact text.

New labels can be created using theadd label button above the dropdown menu. The remark text-field can be used to add comments on why a certain label was selected.

Note: Labels have a label type, this is a way grouping of labels. To label an artifact the user should select a label from each label type. Label types are specified during the project creation, and are not adjustable afterwards.

After different users have labelled an artifact there could be conflict between the labels that have been assigned. Artifacts with different labels appear in theconflict resolution page. Here users can modify the labelling given to ensure that there is conformity between the assigned labels.

Clicking theresolve conflict button will resolve the conflict if the labels are consistent.

For a full list of features we refer the reader to theSoftware User Manual (SUM), below we will briefly describe some of the more important advanced features for common use cases.

• Artifacts can be viewed on theartifact management page. Additional info about labels given to artifacts can be seen by clicking on an artifact.
• Segments from an artifact can be transformed into a new artifact, this operation is referred to as"split". Splitting of artifacts is done by highlighting the portion of the artifact to be split on the labelling page, and then clicking thescissor icon in the top right.
• The label management page displays all labels in a project, changes can be made to labels, such as editing names, merging labels.
• Themes can be created to provide a logical grouping of labels, allowing for better analysis. Themes are created on thetheme management page. Labels are assigned to themes on the label management page, or the theme management page.
• Themes can be logically grouped with other themes to create a hierarchical view of the elements within a project.
• Artifacts, labels and themes store change history. This can be inspected by clicking theclock icon when viewing the aforementioned elements.
• Various projectstatistics can be viewed on the statistics page. The user can navigate to the statistics page using the navigation menu on the left side of the screen.
• The hierarchy and status of labels and themes can be visualized by clicking theTheme hierarchy button on the theme management page. A visualization will be displayed showing how the different elements are related to another, and their current status.

1. Navigate to the frontend folder on the terminal
2. To install the required libraries run the command:

npm install

2. After this command has executed succesfully, run the front-end test cases using the command:

ng test

1. Navigate to the backend folder on the terminal
2. To install the required dependencies run the command:

pip install -r requirements.txt

3. After this command has executed succesfully, run the back-end test cases using the command:

pytest -rA

(if pytest has not been added to your path, instead run: python -m pytest -rA)

Please use the following Bibtex for citing this work.

@article{lama2023,   author = {Victoria Bogachenkova and Eduardo Costa Martins and Jarl Jansen and Ana-Maria Olteniceanu and Bartjan Henkemans and Chinno Lavin and Linh Nguyen and Thea Bradley and Veerle Fürst and Hossain Muhammad Muctadir and Mark van den Brand and Loek Cleophas and Alexander Serebrenik},   title = {LaMa: a thematic labelling web application},   journal = {Journal of Open Source Software},   doi = {10.21105/joss.05135},   url = {https://doi.org/10.21105/joss.05135},   year = {2023},   publisher = {The Open Journal},   volume = {8},  number = {85},   pages = {5135} }

LaMa was developed based on a web application calledLabeling Machine, which is forked from an earlier version of theLabeling Machine. Development of LaMa was partially funded by NWO (the Dutch national research council) under the NWO AES Perspective program (Digital Twin), project code P18-03 P3. We acknowledge the contribution of the nine bachelor students fromEindhoven University of Technology, the Netherlands V. Bogachenkova, T. Bradley, E.J. Costa Martins, V. Fürst, B. Henkemans, J.L.O. Jansen, L.C. Lavin, L.V. Nguyen, and A. Olteniceanu, who contributed to this project significantly as part of their final project of the bachelors program in computer science.