This document gives a brief overview of how to use the RISN Editor. The Editor is under heavy development right now, so the features as described in this manual might now behave differently, or no longer exist. Further, there may be features that are present in the Editor that are not described in this manual.
As a quick reference, the current hotkeys are:
| Hotkey | Action |
|---|---|
| R | Create a new Representation schema. |
| S | Create a new R-Scheme schema. |
| D | Create a new R-Dimension schema. |
| Y/T | Create a new R-Symbol schema. |
| Q | Create a new Placeholder schema. |
| Ctrl D | Duplicate the selected schemas. |
| C | Connect two schemas. |
| A | Connect two schemas by anchoring. |
| G | Connect two schemas with a generic link (discouraged). |
| V | Remove all links between selected schemas. |
| X/Backspace | Delete all selected links, or schemas and links connected to them. |
Creating new schemas puts them under your cursor.
These are available when you have your cursor over the Model editor. See The Toolbar and The Model Editor for more details.
On the left of the Editor you have the model list. This list contains all the models you have built. Initially the list will be empty, but new models can be created by pressing the button in the bottom left corner. All models are initially called 'Model'.
Models appear in the left hand list in the order they are created. But you may reorder the Models by grabbing their 'handle' (the ⋮ to the left of the name) and dragging it into the desired position.
Rather than creating a new Model from nothing, you can duplicate an existing Model, using the button found next to the button. This will make an exact copy of the currently viewed Model, except the name will have '(Copy)' after it. The Models are entirely independent: changes made in one will not affect the other.
The button creates a new Folder. Folders can be arbitrarily nested, and are an excellent way of organising your models into sensible groups.
Models can be renamed by double-clicking on their existing name, and editing the name to be what you now want it to be. Several models can have the same name; this is perfectly fine for the Editor, but potentially confusing for you, so this is not recommended.
If the name of a Model is long, it will be truncated. The full name of the model is visible by hovering your cursor over the name or in the model slots inspector.
To switch between models, click on the model you wish to view. The currently viewed model be highlighted with a grey background, while all other models will have a white background.
Below the and buttons, we have buttons for importing and exporting Models. The button downloads a '.risn' file of the selected Model, with the name matching the Model's name. The button allows you to select '.risn' files from your computer, and add the contained Models to the RISN Editor. Models may also be imported by dragging '.risn' files onto an empty space in the Model list.
If you no longer need a model, you can delete it. This is done by making the model you wish to delete the viewed model (it will have a grey background in the model list), then clicking the button. You will be asked to confirm that you wish to delete the model. The model is permanently deleted. It cannot be recovered.
The Model list can be hidden using the 〈 button that floats at the top right of the list. A 〉 button will appear in the top left of the screen; this can be used to show the Model list again.
Across the top of most of the Editor (outside the Model list) there is the toolbar. All the core functionality of the Editor can be accessed via buttons found here. We shall discuss each button in turn.
Note that these buttons only work when there is an active model. If no model (in the model list) has a grey background, the buttons will not do anything.
|
The first two buttons in the toolbar should be familiar: undo, and redo. These buttons act per Model, so each Model maintains a separate history. The history is lost when the Editor is reloaded, and can only maintain 50 "steps". Any history further back is discarded. You can also undo using Cmd Z, and redo using Cmd Shift Z or Cmd Y. | |
|
These five buttons create a new schema in the Model. The kind of schema created is determined by the label – Representation, R-Scheme, R-Dimension, R-symbol, or Placeholder. The new schema is created at the 'origin', which is the top left of the Model editor (before zooming and panning). If any existing schemas were selected when this button is clicked, the created schema is automatically linked as a child of the selected schemas. The created schema becomes the new current selection. | |
|
Creates new schemas in the model that are an exact copy of your current selection.
If you have selected schemas with connections between them, these connections are duplicated.
Any connections these schemas have to | |
|
These three buttons are used to connect schemas together. The first button creates a Hierarchy connection (the 'typical' connection in RISN), the second button creates an 'anchored' connection, and the third creates a 'generic' connection, intended for internal use only. When clicking these buttons, you must have at least two schemas selected: fewer than two, and these buttons have no effect. The 'direction' of the connection is determined by the order in which the schemas were selected: the first selected schema is the 'parent', while the rest are the 'children'. The parent is connected from the bottom of the schema, while the children are connected from the top. If you have connected the schemas back to front, the connection will appear to 'cut through' the schemas; unlink them, select them in the opposite order, and click the button again to correct the direction. | |
|
Remove all the links between the selected schemas. Unlike the linking buttons above,
you can have two | |
|
This deletes the links currently selected, or the schemas currently selected along with all the links attached to them. | |
Grid |
Use this checkbox to toggle on or off the grid in the Model editor. |
After the buttons is a link to this manual.
Most of the screen in the Editor is dedicated to the Model editor. Here is where the effect of clicking buttons in the Toolbar, or pressing Hotkeys, will occur. Hotkeys are only active while your cursor is in the Model editor.
Navigating the Model is largely done with the mouse. Clicking and dragging anywhere outside of a schema will move the 'view' around. The scroll wheel is used to zoom in and out. Clicking a schema will cause it to become the only selected schema. Shift-clicking an unselected schema will add it to the current selection, while shift-clicking a selected schema will remove it from the current selection. Holding shift while clicking and dragging outside of a schema creates a 'selection rectangle', which will add any schemas inside it to the current selection. Dragging any schema in a selection will move every schema in that selection.
Schemas can be dragged around using the mouse. They can also be 'nudged' using the arrow keys; holding shift while nudging makes the movement smaller.
When using the hotkeys, any 'schema creation' hotkey will cause the schema to be added under the cursor. This is different to the toolbar, in which clicking a 'schema creation' button will add the schema at the 'origin' of the Model.
Sometimes it can be useful to have a background grid, on which you can position the schemas. You can hide or show this grid using the checkbox in the toolbar.
Below the Model editor is the Intelligence panel. By default, this is a bar along the bottom of the Model editor counting the number of errors, warnings, and insights it has detected. If the Editor is still working in the background, the icons will show a spinning ring. If the Editor has finished working, the first icon will be a 'stop sign with a cross', with a count indicating how many errors were detected; the second icon will be a 'warning sign with an exclamation mark', indicating how many warnings were detected; the third icon will be an 'eye', indicating how many insights it has found. If the icon is red, the Intelligence engine had to give up due to taking too long.
The label acts as a filter. Clicking on the label will show the inspector panel populated with the warnings, errors, or insights, depending on which filters are 'active'. A filter is active if it has a grey background. Errors are listed first, followed by warnings, followed by insights. If no filters are active, the panel is hidden.
An error, warning, or insight will display as a line of text: this is a high-level summary of what the Intelligence engine has found. You can click on the summary to select the relevant schemas. When the model no longer has the feature causing the error, warning, or insight, the message will go away.
On the left of the message is a small triangle: clicking this will reveal more details. Sometimes, for errors and warnings, this will include a suggestion on how to fix the problem. Click the triangle again to hide the details.
Warnings can be ignored. When viewing the details of the warning, following the detailed description of the problem, there is a checkbox labelled 'Ignore'. When this is checked, this warning will not count against the total number of warnings identified by the Intelligence engine. For example, if you have two warnings, but both are ignored, the warning count will be zero – but the ignored warning count will be two. Ignored warnings appear fainter than regular warnings. If the cause ignored warning is fixed and then reintroduced, the warning will remember that it was hidden.
On the far right is the Slots inspector. Each schema in the Model has associated 'slots': each slot holds one particular piece of information about that schema. When one schema in the Model editor is selected, the Slots inspector displays the information for that one schema. If multiple schemas are selected, the panel is empty. If no schemas are selected, information about the entire model is shown.
The Slots inspector can be hidden using the 〉 button that floats at the top left of the inspector. A 〈 button will appear in the top right of the screen; this can be used to show the Slots inspector again.
Note that these are available when no schemas are selected.
| Slot | Description |
|---|---|
| Name | Set the name of this model. |
| Notes | Add any other comments about this model here. |
| Slot | Description |
|---|---|
| Domain | Indicate the title of the diagram. |
| Display | Indicate the physical location of the diagram (e.g., top right image, Dropbox folder). |
| Notes | Add any other comments about this schema here. |
| Slot | Description |
|---|---|
| Concept | A description of the concept. |
| Graphic | The annotation used in the diagram that represents the concept. If the concept is represented then use ## to indicate that there is no graphic element for the concept. |
| Function | Specifies the role of the schema as semantic, auxiliary, or arbitrary. Select semantic if the schema is essential for the interpretation; auxiliary if the schema is to pragmatically aid the interpretation; and arbitrary if it only has a decoratively or aesthetic purpose. |
| Explicit? | Yes, if there is a graphic object for the concept. No, if there is not a graphic object for the concept. |
| Scope | Global if it affects the overall representation. Local, if it affects part of the representation. |
| Organisation | Indicated how the concept is related to the graphic. Summarises how all the pieces in the R-Scheme schema are put together. |
| Notes | Add any other comments about this schema here. |
| Slot | Description |
|---|---|
| Concept | A description of the concept. |
| Concept Scale | Indicates what kind of quantity is associated with the concept. If the concept is about categories or groups, use Nominal; for concepts that can be ordered, use Ordinal; if instances in the concept can be ordered at specific intervals, use Interval; and for instances of the concept whose proportions can be compared, use Ratio. |
| Concept Attributes | List of attributes that are relevant to the concept. They may not be present in the graphic. Example: maximum values, minimum values. |
| Graphic | The annotation used in the diagram that represents the concept. If the concept is represented then use ## to indicate that there is no graphic element for the concept. |
| Graphic Scale | Indicates what kind of quantity is associated with the graphic. If the graphic can be categorised or grouped, use Nominal; if the graphic that can be ordered, use Ordinal; if instances in the graphic can be ordered at specific intervals, use Interval; and for instances of the graphic whose proportions can be compared, use Ratio. |
| Graphic Attributes | Parts of the display that can potentially be meaningful. Example: blue, red. |
| Function | Specifies the role of the schema as semantic, auxiliary, or arbitrary. Select semantic if the schema is essential for the interpretation; auxiliary if the schema is to pragmatically aid the interpretation; and arbitrary if it only has a decoratively or aesthetic purpose. |
| Explicit? | Yes, if there is a graphic object for the concept. No, if there is not a graphic object for the concept. |
| Scope | Global if it affects the overall representation. Local, if it affects part of the representation. |
| Organisation | Indicated how the concept is related to the graphic. Summarises how all the pieces in the R-Dimension schema are put together. |
| Notes | Add any other comments about this schema here. |
| Slot | Description |
|---|---|
| Concept | A description of the concept. |
| Graphic | The annotation used in the diagram that represents the concept. If the concept is represented then use ## to indicate that there is no graphic element for the concept. |
| Is Class? | Yes, if this R-symbol is standing in for many closely related concepts. No, if this R-symbol is just for one concept. |
| Function | Specifies the role of the schema as semantic, auxiliary, or arbitrary. Select semantic if the schema is essential for the interpretation; auxiliary if the schema is to pragmatically aid the interpretation; and arbitrary if it only has a decoratively or aesthetic purpose. |
| Explicit? | Yes, if there is a graphic object for the concept. No, if there is not a graphic object for the concept. |
| Notes | Add any other comments about this schema here. |
| Slot | Description |
|---|---|
| Description | Briefly describe what you are omitting. |
| Omitted but understood? | If you are inserting this node because this interpretation is missing aspects that would go in the model, select No. If instead this aspect is being omitted purely for space/time/effort reasons, but the interpretation is complete, select Yes. |
| Notes | Add any other comments about this schema here. |
Both the connections have a Notes slot, just like all schemas.
The Hierarchy and Anchor connections have the following slot:
| Slot | Description |
|---|---|
| Label | The “order” of the connection. Is either a positive number (1, 2, ...) or blank; can be “blanked” using the button. |
The RISN model has properties we can compute, which have the potential to capture interesting information about the model. The metrics are shown under the ‘Notes’ box in the Model Inspector, initially hidden but clicking the arrow left of the word ‘Metrics’ toggles their visibility.
The table of Metrics can be downloaded using the button.
The table summarises the kinds of metrics we compute, and any potential trap when interpreting the values.
| Metric | Description |
|---|---|
| Schemas | Schemas come in five flavours, so we count how often each occurs (along with the total number of schemas). |
| Connections | Connections come in three flavours, so we count how often each occurs (along with the total number of connections). |
| Quantity Scales | We count how often each quantity scale is used, both in the concept and in the graphic of R-Dimension schemas. |
| Idioms | As the intelligence engine computes idioms, we update the counts for each in the metrics. |
| Connectedness | If a model is just barely connected (i.e., removing any connection will result in a disconnected, invalid model), the connectedness is 0. If the model is entirely connected (that is, every schema is connected to every other schema) then the connectedness is 1. If the model is disconnected (and thus invalid) this metric may be negative; it may also be positive because there are sufficiently many connections that it could be connected, but happens to not be. Thus, if the model is disconnected, this metric should be read with caution. |
| Branching Factor | Schemas may have children, in which case they can be said to ‘branch’; the branching factor is the number of children it has. We compute the mean, standard deviation, minimum, and maximum branching factor across the entire model. We also compute these values when we ignore the ‘leaves’ (which by definition have zero children). |
| Depth | Starting at the top Representation schema, we can travel through the model until we reach a schema with no children. The number of connections we travelled along to reach the leaf is the ‘depth’ – there are potentially many ways to reach the same leaf, so we only count the shortest way. If we repeat this for all leaves, we can compute the mean, standard deviation, minimum, and maximum depth of the model. |
| Parallel (additional) paths | Schemas can be accessed from the root Representation schema in at least one way, but there are potentially more ways than this. for example, an R-Dimension schema might be the product of two R-Dimensions, which are themselves reachable from the root. (For simplicity, assume they can be reached exactly one way from the root.) This means there are two ways to reach our product R-Dimension, and so we count this schema as having one additional ‘parallel’ path. We compute the mean, standard deviation, minimum, and maximum number of additional parallel paths. |