---
title: "How does oRus Works?"
author: ""
output: rmarkdown::html_vignette
vignette: >
%\VignetteIndexEntry{How does oRus Works?}
%\VignetteEngine{knitr::rmarkdown}
%\VignetteEncoding{UTF-8}
---
```{r setup, include=FALSE}
knitr::opts_chunk$set(echo = TRUE)
```
**oRus** provides three key functionalities:
1. Groups ORUS by the element of the model that is being addressed (input, output, objectives, constraints, and scenarios). This is done by analysing the presence of the keywords discussed in [2]. Furthermore, input and output ORUS are broke down into feature and source/visualisation type.
2. Searches for inconsistencies and issues within the stories. In particular, it looks for:
a. Potential conflicting objectives (with both minimisation and maximisation stories) or vague objectives (with keywords that do not indicate the search direction).
b. Incomplete input features (which ORUS, classified as inputs, do not have a declared source location).
c. Incomplete output features (writing destination and visualisation style).
3. Groups ORUSs by \"conceptual groups\", i.e. stories that may be related in terms of business logic. This is done through topic modelling: analysing the similarity and frequency of the words used in the text (without considering keywords).
## Features Discussion
In particular, _feature (1)_ has several advantages. First, it provides a pre-classification of stories; this assists in the translation from user stories to the mathematical model, by clearly stating which ORUS belongs to each type. Second, as a result of that, it helps to detect unrefined stories: incorrect classifications may indicate that an ORUS could be translated into more than one element, hence being an epic. Third, the input and output subdivision allows further analysing these cases, assisting feature (2.b, 2.c).
_Feature (2.b) and (2.c)_ allow discovering missing information: before starting coding, all data sources must be identified. This can contribute to the negotiation with the client, by listing all types of input data, access privileges requirements, and possible integration with other systems. In addition to that, _feature (2.c)_ also allows identifying gaps in the elicitation of features related to visualisation. This is important for mathematical models, as they are used to support decisions, and thus, visualisation of results becomes essential to the user.
Similar to this, _feature (2.a)_ assists the modeller in a more in-depth analysis of the code. Having both minimisation and maximisation objectives may imply stakeholders with different ideas, or a deficient elicitation; however, it can also point to a multi-objective model. Furthermore vague objectives, those with keywords that do not imply an optimisation direction, can be a hindrance, and imply that further clarification is required.
Finally, _feature (3)_ can assist the modeller in understanding the business logic and how stories relate to each other. This classification can be helpful when organising the iterations of the development lifecycle, assisting the modeller to decide in which order they can be implemented. Implementations iterations can be organised by type of story, or by "conceptual group" (stories with a stronger coupling in terms of business logic). This feature supports the latter.
**oRus** follows a very straightforward process for feature (3), common for natural language processing; this is simplified in Figure 1. It uses LDA (Latent Dirichlet Allocation to perform a topic modelling with the "what" section of the ORUS. The number of groups (or topics) to be used needs to be defined by the modeller; however, this is an intrinsic characteristic of LDA topic modelling.
## Example Report
Finally, the modeller can also choose to obtain a report summarising the ORUS analysis produced throughout features (1-3) of the package. In particular, the report can be generated in different formats (HTML, PDF, Word document). The following is an excerpt of a generated report:
