PRSM Help

Participatory System Mapper

What is it?

The Participatory System Mapper (PRSM for short) is an app that runs in a web browser that makes it easy for a group of people working together to draw networks (or ‘maps’) of systems.

Maps

The network or map can be anything that has items (or ‘factors’ or ‘nodes’) connected by links (or ‘edges’). Here are some examples:

Systems

The software is aimed at people who are interested in understanding whole systems. Wikipedia defines a system as a group of interacting or interrelated entities that form a unified whole.

Participatory system mapping

The app is designed to enable groups of people, each using their own computer (or tablet) to collaborate in the drawing of a map. They may be sitting around a table, discussing the map as it is created face to face, or working remotely, using video conferencing or the chat feature that is built into the app. Everyone can participate because every edit (creating nodes and links, arranging them and so on) is broadcast to all the other participants as the changes are made (just as Google Docs does for text, for example).

When you start the app in your browser, a ‘room’ is created for you in which to draw your network. You can add other users to this room to share the work. Only those with access to the room can see what is being created.

Examples

Here are a few examples of what you can do with the app:

The first is a theory of change adapted from an NPC report.

NCP Example

The second is a system map about the environmental impact of goods transport developed by a small group of experts working together using the app.

SCandL Example

The third is a large network of 736 nodes and about 9000 links representing the team members playing in the 2019 football World Cup.

World Cup 2019 Example

Installation

No installation on your computer is needed. The software is a web app, which means that it can be accessed using a web browser by pasting this link into the address bar:

https://prsm.uk/prsm.html

You need a modern web browser such as Chrome, Firefox, Microsoft Edge or Safari. It will not work with Internet Explorer.

The software is free and available under an MIT license.

Basic use

When the app is started for the first time in your browser, there is an option to type in your name and then to follow a brief tour that shows you the main items on the web page.

Nav Bar icons

This introductory tour is only shown the very first time you use PRSM. If you want to view the tour again, click .

At the top of the screen are a row of buttons.

This what they do, from left to right:

To select a factor or a link, click on it. To select more than one, click on one factor or link and then hold down the pointer over the other. Or you can hold down the control (CTRL) key and click to add to the selection. At the bottom of the window is the status bar, which will show which factors and links have been selected. Clicking anywhere on the background will deselect the factors and links.

Each factor can be moved across the network pane by dragging it. The whole network can be moved by dragging the background.

Also at the bottom of the window on the right is a slider that will adjust the magnification: slide to the right to make the factors and links larger and to the left to make them smaller (or click on the + and - signs). To return the network to a size that will fit neatly in the window, double click anywhere on the network background. On a tablet or phone, you can zoom by using the ‘pinch’ gesture.

At the top left, you can enter a title for the map. Click on ‘Untitled map’ and type in your title. If you have created or used several maps (and they have titles), a small downward triangle will appear to the right of the title. Clicking on this shows a list of those previous maps, and clicking on one of those takes you away from the current map and loads the previous one (after you have confirmed that this is what you want to do).

Holding down the Shift key and then moving the mouse pointer will show a magnifying glass with an enlarged view of the part of the map under the pointer. You need to be using a keyboard for this.

Notes

If you select just one factor or one link, a small panel appears. This shows the factor or link label (if it has one), the time and date when the factor or link was created, when it was last modifed if it has been changed since it was created, some network statistics about the factor, and an area where you can type a note to show further information about the factor or link. For factors, there is also an open or closed padlock symbol. If this is shown closed, the factor will be locked into place on the network pane and cannot be dragged elsewhere.

If a factor or link has a note, a small ‘scroll’ icon is shown next to it.

A basic editor is provided for writing the Notes. You can format the text with bold, italic or underline, create bulletted or numbered lists, and add URLs to the text.

Sharing

If you use the link above to start the app, a new room is created for you. When you click on the share icon, a dialog box is shown that includes the name of the room in the link that is displayed:

Sharing box

Click the button to copy the web link to the clipboard, and then paste the link into an email or a text message. or just tell other participants the name of the room (which is a randomly generated set of 4 groups of three capital letters separated by hyphens). When they access the link, they will see whatever is in your app window.

There are two options for the sharing link. If you check the ‘Clone map’ box, the link will be to the map in a new room - any changes made to this new map will not happen in the original room. If you click the ‘View only’ box, the recipient of the link will not be able to make any changes to the map.

Avatars and pointers

When there are others in the room, the initial letters of their name appear in a circle at the top left - their avatar. If you hover the mouse pointer over the circle, their full name is shown (their real name or the name they have been given by the app). If they don’t do anything for 15 minutes, the avatar fades and, if they close their browser window, it disappears.

The other users’ mouse pointers are shown on the map. As you move your mouse pointer (or finger on a touchscreen), a small disc containing your initials moves on every other users’ map correspondingly. If you are talking with other users by audio or video link, you can use your mouse to point to things of interest, and the other users can see what you are pointing at.

You can ‘follow’ the mouse movements of another user by clicking on their avatar. When you do that, if that user moves to another part of the map, your map moves too, following that user’s mouse pointer. This can be very helpful if the other user is showing you something on the map. To stop following, just click anywhere on the map.

Using the mouse and touch

You can use the following mouse actions (or finger or pencil gestures on a tablet):

Copy and paste

You can copy selected factors to the clipboard and then paste them into either the same map (to duplicate them) or into another map in another browser window or tab.

To copy, first select the factors that you want copied (a long press on the factors). Then hold down the Command ⌘ or CTRL ⌃key and type C. If you copy more than one factor, all the links that go between the selected factors get copied too.

If you want to copy these factors and links into a new map, open a new tab in your browser, go to https://prsm.uk/prism.html, click on the map and type ⌘P or ⌃P. Or to duplicate the factors in the same map, just type ⌘P or ⌃P.

Double clicking on a factor or a link will bring up a small dialog that enables you to change the design of the factor or link - its colour, shape or the label.

See Styling the map for more on changing the look of factors and links.

The chat window

Clicking on the speech ballons at the bottom right opens up a chat window that you can use to type messages to other participants in your room.

If you haven’t provided your real name, the name at the top is initially randomly generated, but if you click on it, you can substitute your own. You can write messages in the box at the bottom and send them by clicking the paper plane button. Use the X to close the chat window.

You can choose to send your messages either to everyone or to one selected person (from among those online).

If someone has sent you a message but your chat window is closed, the button will gently pulse to remind you to open it:

Chat Window Button

File formats

The app can read files in its native format (files with the suffix ‘.prsm’), or in GRAPHML (.graphml), GML (.gml) or Comma Separated Values (.csv) formats. A CSV file must contain a two columns of values. Each row represents a link. In the first column is the label of the factor from which the link points, and in the second column is the label of the factor the link is pointing to. This very simple format is designed to allow straightforward imports from other software. Optionally, the third and fourth columns may contain an integer between 1 and 9 - if they do, the factor is styled with that style (styles are numbered from top left to bottom right as shown on the Factors tab). The fifth column may contain the style number for the link.

The app can create output files in the app’s own native format, as a GML file or as a CSV file. You can also save an image of the map as a Portable Network Graphics (.png) file. The image shows the same view of the map as you see on the screen (so, for example, it will not show factors that have been moved out of the app window).

Privacy and security

The only way to join the room and see the network is by using the randomly generated room name, and the chances of finding that name by trial and error is very, very small. The network is not stored on any server (there is a central server, but this is only used to broadcast encoded messages from one participant in a room to another). The server is located in Europe.

Styling the map

The view you see when you first open the app is intentionally very simple, but hidden away are many more features. To access these, click on the last, Settings, button on the top bar: . This will reveal a set of three tabs: Network, Factors and Links, with the Factors tab open.

The panel showing the tabs can moved across the network pane: drag it using the thin black strip at the top of the panel. This can be useful if the panel gets in the way of seeing the network.

Factors tab

There are 9 sample styles for how factors can look. If you select a factor from the network and then click on one of the 9 styles, the factor will change to resemble the style. As a short cut, if you click on the ‘Select all factors’ button at the bottom, and then click on a style, all the factors will change to the chosen style.

Double clicking on any of the 9 styles opens a dialog box to change the style:

There are options to change the colour of the background (the ‘fill’), the border and the font of the label, to change the shape, for example to a rectangle or a circle, to change the border from solid to dashed or dotted or none, and to change the font size of the label.

If you right click on one of the style samples, there is a menu with which you can either select all the Factors that have that style, or hide all those Factors from view.

Legend

You can also change the name of the style. If you do so, this name will appear on the network pane as one item in the ‘legend’. So, for example, if you had some factors that are Activities, some that are Change mechanisms, some Outcomes and some Impacts, you could give four of the styles these names, colour their fills red, orange, yellow and blue, and then apply these styles to the appropriate factors in the network. The legend will be automatically displayed on the network pane:

Legend

The legend can be moved by dragging the top of the Legend pane.

The Links tab is very similar to the Factors tab, except that it relates to the links. There are 9 link styles and each of these can be changed by double clicking the link style. There are options to change the colour of the link, whether it has an arrow at the end, whether it is solid, dashed or dotted, and to add a link label.

Network tab

The Network tab enables you to change many aspects of the network visualisation, including where the Factors are placed and which are visible.

It is sometimes useful to get PSRM to layout Factors using an automatic procedure and then adjust their positions manually to achieve the desired placement. PRSM has the trophic algorithm built in. The trophic layout helps to reveal the causal structure of the map. With the trophic layout, the factors are arranged along the horizontal axis according to their positions (their trophic levels) in the overall causal flow within the system, making it easier to identify upstream and downstream factors; the linked chains of influence that connect them; and where policies act on the system within this overall causal structure (which may be upstream or downstream).

On the Network tab, there are controls for:

Drawing Mode

Switching ‘Show drawing layer’ ON reveals a group of buttons on the left that enable you to draw shapes, write text, and import images onto the network background.

Drawing layer

In drawing mode, the background has a faint square grid to help line up your drawing. When you draw, you are ‘painting’ on the background, which means that the shapes and text you apply can only be moved by erasing them and redrawing.

When you click on a drawing button, a small dialog box appears that can be used to adjust the drawing tool. For instance, the Line tool, which draws straight lines, has options for the line thickness and line colour.

To stop using a tool, either click on another one, or click a second time on that tool’s button.

The drawing tools are, in order from top to bottom:

Analysis

Once you have a map, you may want to examine it for themes and patterns. This is easiest if you examine portions of the map, or ‘sub-maps’, one at a time. As Barbrook-Johnson and Penn explain (Barbrook-Johnson, P., & Penn, A. (2021). Participatory systems mapping for complex energy policy evaluation. Evaluation, 27(1), 57–79.), network analysis can be combined with subjective information to answer a range of questions, as indicated in the table below.

Way to start Starting point options How to build Interpretation How to do it with PRSM
Stakeholder-suggested factors Intervention or controllable factors Downstream factors and edges What is the intervention or controllable factor affecting? Unexpected indirect effects? Select the intervention factor and choose ‘Show only Factors downstream’
For multiple factors create a union or intersection of multiple downstream submaps How are multiple interventions complementing or clashing with each other? Select all the interventions and choose ‘Show only Factors downstream’
Paths between intervention factors and outcome factors, including ego networks of factors on paths What does the intervention rely on to achieve its goals? What wider context might affect it? Select all the factors on the path(s) between the intervention(s) and the outcomes(s), and choose ‘Show only Factors 1 link away’ (or 2 or 3 links away)
Important or outcome factors Upstream factors and edges What is influencing the thing we care about? Constraints? Control? Buffered or buffeted? Select the intervention factor and choose ‘Show only Factors upstream’
For multiple factors create a union or intersection of ego networks. Or, pull out paths between outcomes. What trade-offs or synergies might there be between achieving the things we care about? Select all the interventions and choose ‘Show only Factors upstream’

Ego networks

What is influencing the thing we care about, what does it influence and how do those things interact? Select the factor and choose ‘Show only Factors 1 link away’ (or 2 or 3 links away)
Union or intersection of upstream factors and edges What factors influence multiple outcomes? Identify potential levers in the system, co-benefits, synergies, or risks. Select all the outcome factors and choose ‘Show only Factors upstream’
Vulnerable to change factors Up and/or downstream factors and edges What might mitigate change in this factor? What impact might change have? Select one or more factors and choose ‘Show only Factors 1 link away’ (or 2 or 3 links away)
Union/intersection multiple downstream sub maps Are there compound risks, how might interventions interact with external change? Select factors and choose ‘Show only Factors downstream’
System-suggested factors Influential (i.e. many outgoing connections) Downstream factors and edges What is this influential thing affecting? Vulnerability or lever? First, set ‘Size Factors to: Outputs’ to see which factors have many outgoing connections. Then select an influential factor and choose ‘Show only Factors downstream’.
Central to the map (i.e. well-connected, or bridging) Downstream and/or upstream factors and edges What is influencing this central factor? What influence does it have? Bottleneck, bridge, transmitter? First, set ‘Size Factors to: Centrality’ to see which factors are central. Then select a central factor and choose ‘Show only Factors upstream’.
Ego networks What does this factor bridge or connect? First, set ‘Size Factors to: Centrality’ to see which factors are central. Then select a central factor and choose ‘Show only Factors 1 link away’.
Influenced (i.e. many incoming connections) Upstream factors and edges What is influencing this highly influenced factor? Buffered or buffeted? First, set ‘Size Factors to: Inputs’ to see which factors have many incoming connections. Then select a factor and choose ‘Show only Factors upstream'.
Unusual network property Any of the above Does this factor play an important but counter-intuitive role in the system? Set ‘Size Factors to: Leverage’ to see which factors have either many incoming but few outgoing connections or few outgoing but many incoming connections.

With thanks to Alex Penn and Pete Barbrook-Johnson for the original of this table.

Data View

As well as the map view described above, PRSM also provides an alternative Data View. This shows the Factors and Links in tables like a spreadsheet. You can make changes in the Data View - changes to Factors and Links are passed over to the Map view. For some tasks, the Data View is more convenient than the Map, especially when one wants to summarise or make changes to lots of Factors or Links at the same time.

To see a Data View, open a PRSM map, click on the Share button at the top, check the box labelled ‘Data View’ in the dialog that appears, and then click on the ‘Copy to clipboard’ button to copy the URL shown. Open a new tab in your browser and paste the URL into the address bar.

Data View

The main part of the Data View when opened shows a table with one row for each of the Factors in the map. On the left are the Factors’ labels. There is then a group of columns that show the format of the Factors, and then on the right, a group of columns with various statistics about the Factors. At the bottom of the table are summaries (counts of how many factors there are, the average betweenness centrality, and so on). If there are too many Factors to fit in the window, you can scroll the table to the top or bottom.

Use the small triangles in the column headings to sort the table according to the values in that column - one click for ascending and two for descending.

Some columns need further explanation:

Above the table, there are tabs labelled ‘Factors’ and ‘Links’. Clicking the Links tab displays a similar table but with one row for each Link:

Data View Links Tab

Most of the cells in the Format section of these tables are editable (columns with headings in bold have editable cells; those with headings in grey are not). To edit a cell, click it. Depending on the column, you can then edit the text (e.g. the Label), select from a drop down menu (e.g. Shape) or enter a number (e.g. Font size).

At the top right is a row of buttons. These are:

Filter
Filter

The rightmost ☒ is a button to dismiss the filter (or you can click the filter button again).

Using the Filter and Select

The Filter and the Select column can be used in combination. For example, suppose you wanted to make all the Factors that influenced 2 or more other factors larger than the rest, to emphasise them in the Map view. This is what you could do:

  1. Click on the Filter button. Set up a filter with Out-degree >= 2
  2. Click on the Select all check box at the top of the first column
  3. Click on one of the cells in the Relative Size column. Edit the value to ‘5’
  4. Look at the Map view. Observe that all the Factors with 3 or more links pointing away from them are now larger than the rest.
OutDegreeFilter

Another, more complicated example: Show only those Factors in the map with a value of Betweenness Centrality greater than some threshold, together with the links that go between these Factors, and hide all other Factors and Links.

  1. In the Data view, sort the Factors by Betweenness (click on the sorting triangle in the column header).
  2. Click the checkbox in the Hidden column header. This hides every Factor in the map (If you glance at the map now, you’ll find that it is apparently empty)
  3. Open the Filter (click on the Filter button at the top), and filter using ‘Betweenness’ ‘>=’ ‘70’ (or whatever threshold value you choose).
  4. Uncheck the cells in the Hidden column in each of the rows that are now visible. This reveals the Factors on the Map that have a Betweenness Centrality greater than the threshold, and the Links between them.

Source Code

(The following is intended for developers who want to extend PRSM)

The program code is available on GitHub.

The javascript (ES6) code in sub-directory js is divided into five modules: one that handles the main network pane (prsm.js), one that manages the background painting functions (paint.js), one that creates and edits the styles (styles.js) (the default styles are in samples.js), one that handles the tour (tutorial.js) and one that includes common utility functions (utils.js). The HTML file that displays in the browser is in the html directory.

PRSM uses two important packages: yjs and vis-network. The former handles the sharing between participants’ browsers and the latter draws the network. A few other packages are used for dealing with touch input (Hammer), drawing emojis, and parsing XML file input.

These components are assembled using parcel and the bundled file is placed in the dist directory. So that users have an easy URL to access (i.e. not needing to include dist in the link), there is an .htaccess file that rewrites URLs from what the user puts into their browser to the correct location.

To install the code, use git to clone the repo to your local disk and change to the cloned directory. Then install the required packages with

npm install

and build the distribution with

npm run build

Documentation can be found in the doc directory.

See package.json for other npm commands.

Acknowledgements

With thanks to all who helped inspire, suggest features for, comment on, and test PRSM, including the members of CECAN, CRESS, Risk Solutions, and Robin Gilbert.

Bug reports and feature requests

Please report problems, suggestions and praise to nigel@prsm.uk