---
title: "How to use oRus?"
author: ""
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{How to use oRus?}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include=FALSE}
knitr::opts_chunk$set(echo = TRUE)
```

## Data

**oRus** takes user stories need to follow the original template of:

> I as a `<who>`,
> want to `<what>`,
> so that `<why>`


Stories must be written in a text file, with one story per line. Having caps or
punctuation doesn't affect the result. User stories can only be processed in
English language. The following is a fragment of a file:


```
As a manager, I want to read working hours per employee from our database, so that we are working with current assignments.
As a manager, I want to use the current job assignments from our database, so that we use the most recent data.
As a manager, I want to read employee salaries from our HR database, so that we use up-to-date values.
```

<br />

## Processing

The format of your user stories determines how much they can be processed:

  * _Software engineering stories_ (traditional ones) can only be split into who-what-why, using the function `readStories()`.
  
  * _Operational Research stories_ must also follow the keywords and structure discussed in [2]. 
  As a result, you can divide stories into who-what-why, and then further into type of element
  (input, output, objective, constraint or scenario), and [perform further analysis](https://melvidoni.github.io/oRus/articles/working.html).
  

There are two options for processing the user stories for Operational Research. The first one is a completely automated process, that can be called as follows:

```
# CASE 1: DOING EVERYTHING AT ONCE

# You can call this function and do the whole process at a single time
# This returns two dataframes as a list, and also generates the excel report, and a pretty markdown report
stories <- analyseStories("myTextFile.txt", groupsNumber = 7, topGroups = 1, 
                          sheetFilePath = paste0(tempdir(), "myExcelReport.xlsx"),
                          reportFilePath = paste0(tempdir(), "myPrettyReport.html"),
                          outputType = "html_document")
```


The second allows you to analyse the stories, and then generate the report independently. The following is a code example:


```
# CASE 2: FIRST PROCESSING, THEN REPORT

# Otherwise, you can only get the dataframe
stories2 <- analyseStories("myTextFile.txt", groupsNumber = 7, topGroups = 1)

# And you can write the reports later
reportStories(stories2, sheetFilePath = paste0(tempdir(), "myExcelReport.xlsx"),
              reportFilePath = paste0(tempdir(), "myPrettyReport.html"),
              outputType = "html_document")
```

You can also ignore custom words when topic modelling, by using the function `createIgnoreWords()`.