Reasons is a digital argument mapping library designed for modern web browsers.
Argument mapping is the process of visually representating the logical structure of arguments. Argument maps are an important pedagogical tool in the analysis of argumentation and have been associated with substantial increases in student cognative gains.
Argument mapping forms the middle of the three stages of informal logical analysis - identification of truth claims within arguments, the analysis of logical structure, and synthesis of logcial structure into writen form. Reasons is designed to seemlessly integrate these stages into existing teaching pedagogies.
Download the library and add a reference to it and any initial data just before the </body> tag of a HTML page.
<html>
<body>
<div id="element"></div>
...
<script src="reasons.js"></script>
<script>
let graph = [
{id: 'p1', text: "Circular arguments work"},
{id: 'c1', text: "Circular arguments work"},
{from: 'p1', to: 'c1', type: "because"},
{from: 'c1', to: 'p1', type: "because"}
]
Reasons.mapper('#element').render(graph)
</script>
</body>
</html>Reasons needs to know the target #element of the DOM in which to render the argument map. You could use body to append the map to the HTML body tag or #id to append it to a specific element id. The optional graph is just an array of nodes and edges representing the logical structure of an argument. Nodes and edges are plain javascript objects representing propositional claims and inferential support.
Saving an argument map is left as an implementation detail. Mapper.export() will return a Graph array from the map's current state.
Reasons relies on a few simple commands to edit an argument map:
-
Double clicking/touching on an empty canvas will create a new reason node.
-
Double clicking/touching on an element will open the edit dialog.
ReturnorEscwill close the dialog. -
Dragging one reason onto another creates an inferential connection. Dragging reasons that share an inferential connection onto one another will create a conjoined reason.
-
A single click or
Tabwill select an element.DeleteorBackspacewill remove that element. -
Ctrl zor⌘ zor device shake will undo an action.Ctrl yor⌘ ywill redo it. -
Ctrl +or⌘ +or wheel or expand will zoom in.Ctrl -or⌘ -or wheel or pinch will zoom out.
Clone the repo and install the dependencies.
$ git clone https://github.com/davekinkead/reasons.git
$ npm install
Running the tests requires additional dev dependencies listed in the package.json file under dev-dependencies including JSDOM and Canvas. . You will need to install all these using the command:
$ npm install mocha --save-dev
$ npm install jsdom --save-dev
...
Then:
$ npm test
To get autobuilding to work, install workman
$ watchman-make --make "npm run" -p "lib/*.js" -t build
Reasons relies on the HTML5 Canvas library - as such, it will not work on legacy browsers. Touch events will be added in future releases. It has been tested and works on the following browsers:
- Chrome on OSX (60+)
- Firefox on OSX (54+)
- Safari on OSX (11+)
- Chrome on Windows
- Firefox on Windows
- Safari iOS (View only)
- Safari iOS (Touch)
- Internet Explorer on Windows
- Chrome on Android
We gladly accept feature requests and bug fixes. If you have questions or problems, please open an issue.
Please read CONTRIBUTING.md for details on our code of conduct, and the process for submitting pull requests to us.
If you are using this software in an academic capacity, please cite as:
Kinkead et al., (2019). Reasons: A digital argument mapping library for modern browsers. Journal of Open Source Software, 4(37), 1044, https://doi.org/10.21105/joss.01044