Tells Your User Story Graphically
This program turns user stories into a conceptual model containing entities and relationships.
- Text file (.txt, .csv, etc.) containing one user story per line
- Report of user story parsing, and conceptual model creation
- Manchester Ontology (.omn) describing the conceptual model
- (Optional) Prolog (.pl) arguments
- (Optional) JSON (.json) of the user stories parts' information
- (Optional) Statistics about the user stories
- Returns the mined user stories, ontology, prolog and matrix of weights, which can be used by other tools
Two scientific papers were published on Visual Narrator:
- M. Robeer, G. Lucassen, J. M. E. M. van Der Werf, F. Dalpiaz, and S. Brinkkemper (2016). Automated Extraction of Conceptual Models from User Stories via NLP. In 2016 IEEE 24th International Requirements Engineering (RE) Conference (pp. 196-205). IEEE. [pdf]
- G. Lucassen, M. Robeer, F. Dalpiaz, J. M. E. M. van der Werf, and S. Brinkkemper (2017). Extracting conceptual models from user stories with Visual Narrator. Requirements Engineering. [url]
The main dependency for the program is its Natural Language Processor (NLP) spaCy. To run the program, you need:
- Python >= 3.6 (under development using 3.7.3)
- spaCy >= 2.1.2 (under development using 2.1.4; language model 'en_core_web_md')
- NumPy >= 1.16.2
- Pandas >= 0.24.2
- Jinja2 >= 2.10
Running the program can be done in three ways: (1) from the command line, (2) using method VisualNarrator().run(), (3) serving VisualNarrator as a REST API.
With the program main directory as current directory, run the program by executing:
python run.py <INPUT FILE> [<arguments>]First, install as a package pip install git+https://github.com/MarcelRobeer/VisualNarrator (or download and run python setup.py install in the VisualNarrator folder).
Next, import the VisualNarrator class from vn.vn and run VisualNarrator().run():
from vn.vn import VisualNarrator
visualnarrator = VisualNarrator(<ARGUMENTS>)
visualnarrator.run(<INPUT FILE>, <SYSTEM_NAME>)Arguments may be supplied to VisualNarrator(**args) to re-use and for a single run to run(*args, **kwargs). Execute help(visualnarrator) to see all (optional) arguments.
Allows a user to POST their user story file to /mine/ and retrieve a JSON response. It requires three dependencies (fastapi, uvicorn and python-multipart), and can then be run using uvicorn. Execute the following in your terminal:
pip install fastapi uvicorn python-multipart
uvicorn vn.ui.api:vn_app --reloadThe REST API is then accessible at http://127.0.0.1:8000/ where documentation on the API can be found at http://127.0.0.1:8000/docs/.
For details on arguments, see our documentation here.
Command line:
python run.py example_stories.txt -n "TicketSystem" -u --jsonFrom method:
from vn.vn import VisualNarrator
visualnarrator = VisualNarrator(json = True)
visualnarrator.run("example_stories.txt", "TicketSystem", print_us = True)The classes in the program are based on the following conceptual model:
The Reader starts by reading the input file line by line and generates a list of sentences. These sentences are then enriched using Natural Language Processing, adding Part-of-Speech tags, dependencies, named entity recognition, etc. Subsequently, the StoryMiner uses these enriched sentences to create UserStory objects. The User Story objects contain all the information that could be mined from the sentence. These are then used to attach weight to each term in the User Story, creating Term-by-US Matrix in the Matrix class. The Constructor then constructs patterns out of each user story, using the Term-by-US Matrix to attach a weight to each token. The Constructor forms a model for an ontology, which is then used by the Generator to generate a Manchester Ontology file (.omn) and optionally a Prolog file (.pl). Finally, these files are printed to an actual file by the Writer in the '/ontologies' and '/prolog' folders respectively. Optionally, the UserStory objects can be output to a JSON file so they can be used in other applications.