PRSM Help

Participatory System Mapper

What is it?

The Participatory System Mapper (PRSM for short) is a web app 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 on 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 that will show which factors and links have been selected. Clicking anywhere on the background will deselect all 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 on the black bar at the top, or anywhere on the network background (the latter will also deselect any selected factors or links). On a tablet, trackpad 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.

If a factor or link has a note, a small ‘card’ 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 weblinks (URLs) to the text.

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. The factor will have a small padlock symbol at the top left. Locking a factor is useful when you are doing analysis of the map (see the Analysis section below) and don’t want to lose the selection while investigating other factors.

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 ‘Copy to clipboard’ 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 letters separated by hyphens). When they access the link, they will see whatever is in your app window.

There are also three buttons on the right. If you click the ‘Clone map’ button, a browser tab will open with the same map but in a new room - any changes made to this new map will not appear in the original room. You can then send the web address to others, confidnet that they will not disturb the original map. If you click the ‘View only’ button, a copy of the map will be made in a new browser tab, but without any of the buttons that allow one to modify the map. You can use the web link of this map to distribute the map to people whom you wnat to look at the map, but not change it. If you click the ‘Data view’ button, the web link will be a a spreadsheet-like view of the factors and links in the map (see the section on the Data view).

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. (Copy and paste is not available with the Firefox browser.)

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/prsm.html, click on the map and type ⌘V or ⌃V. Or to duplicate the factors in the same map, just type ⌘V or ⌃V.

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 balloon 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 arrow 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

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 data are stored on a central server in encoded form. The server is located in Europe.

Files

Reading and Importing maps

The app can read files in its native format (files with the suffix ‘.prsm’), or in GRAPHML (.graphml), GML (.gml), GraphVix (.gv or .dot), Comma Separated Values (.csv) or Microsoft Excel (.xlsx) formats. Not all features of GraphML, GML and GraphViz formats are supported.

An Excel workbook should contain two spreadsheets, one named ‘Factors’ and the other named ‘Links’. Both should have a Header (i.e. first row) of column names, with the remaining rows containing data about each Factor or Link (in any order).

The Factors sheet must have a column headed ‘Label’. This column should contain text that will become the labels of the factors. It may, optionally, have:

All other columns are considered to be values of Attributes assigned to Factors and visible in the Data View of the map.

The Links sheet must have a column headed ‘From’ and another headed ‘To’. The contents of these columns should be text identical to one of the Labels in the Factors sheet. It may, optionally, have:

All other columns are considered to be values of Attributes assigned to Links and visible in the Data View of the map.

A CSV file must contain at least 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. Note: the CSV format is now deprciated, becuase the Excel format is easier to use and Excel can read and write CSV files. The CSV format may be removed in a future version.

Saving and Exporting maps

The app can create output files in the app’s own native format, as a GML file, GraphViz file, as CSV files, or as an Excel workbook.

The CSV output produces two files, one listing all the factors and the other all the links. The factor file starts with a header row with the names of the columns (Id,Label,Style,Note) and then describes each factor. The links file has a header: Source,Target,Type,Id,Label,Style,Note, where the Source and Target refer to the Ids listed in the factors CSV file.

You can also save a high resolution (600 dpi) 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).

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 four tabs: Factors, Links, Network and Analysis, 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 above the tab buttons. 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, 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. Clicking on the padlock symbol will lock all the factors with this style; clicking on it again will unlock them all.

If you right click (or CTRL 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 and what is shown in the window.

It is sometimes useful to get PSRM to arrange factors using an automatic procedure and then adjust their positions manually to achieve the desired placement. PRSM provides several layout algorithms:

There is no best layout algorithm that works for all networks; you need to see which one looks good for your map. If you don’t like the effect of an algorithm, you can choose another one, or use the Undo button on the top bar to revert the map to its original layout.

On the Network tab, there are controls for:

Analysis tab

The Analysis tab allows you to view portions of the map and to cluster factors to help with the analysis of the network (see the Analysis section below for help on how this can be useful).

The panel is divided into five sections:

Here is an example. The first is the original network. The second is the same network with Show all paths between Factors 1 and 7. The third is the same network with Show shortest path between Factors 1 and 7.

The above three options can be combined. For example, the shortest path between two Factors option may display two paths: one with a couple of links and another feedback path going in the reverse direction that winds around the map and includes many links. Because it consists of many links, the latter path may not be of much interest. Choosing both Show Shortest path and Show only Factors 2 links away will display just the direct path.

Drawing Mode

Switching ‘Show drawing layer’ ON reveals a group of buttons on the left that enables 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:

Analysing the map

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 and the changes to factors and links will immediately be 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.

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. To the right, there is a group of columns that show the format of the factors, a group of columns with various statistics about the factors and column showing the Notes attached to 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.

Only the first column of the Fornat and Statistics column groups are shown when the Data View is first opened. To reveal the other columns in each group, click on the to the right of the group heading. Similarly, the Notes column can be expanded to show more of the Notes.

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.

The values in columns with headings in black letters can be edited from the Data View, but the ones in columns with grey headings are read only.

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).

Top button bar

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

Filter
Filter

The first drop down menu includes all the columns (except those that are for colours; you cannot filter by colour). The second drop down menu has a set of conditions to apply to the values in the filter column. To the right of this is a text box where you can complete the condition. For example, to filter out all but those factors that have the word ‘climate’ in their label, you would use:

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 display 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 several modules: those that handle the main network pane (prsm.js), the background painting functions (paint.js), editing the styles (styles.js) (the default styles are in samples.js), the initial tour (tutorial.js), does tophic layout (trophic.js), does clustering (cluster.js), calulates the betweenness centrality (betweenness.js) and provides shared 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 and a JSDOC index here.

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