CausalMapFunctions.Rmd

---
title: "Causal Map Functions"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Causal Map Functions}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

```{r setup, echo=FALSE}
library(CausalMapFunctions)
```


## A set of functions for manipulating and simplifying causal maps.


These functions are used in the [Causal Map app](https://causalmap.app/).


The app itself is currently hosted [here](https://causalmap.shinyapps.io/CausalMap2/).



The main functions input and output objects of the class `mapfile`, which are lists of five tables. 

Statement tables are used in Causal Map as the underlying data which is to be coded into causal links. So each link refers to a quote from a particular statement. Statements are optional and this package can be used without them.

The package also contains some UI functions used in the Causal Map Viewer which provide plot and table outputs.

In this package, nodes are called `factors` and the edges are called `links`.

## **Motivation**

There are many existing tools for analysing systems diagrams and also undirected graphs, we identified a need for a tool for analysing the kind of causal maps produced in evaluation research such as programme theories where:

- there may be many causal factors, with long text labels
- the text labels are important because they may be used for searching and filtering
- causal factors may be nested into causal hierarchies
- there may be many co-terminal links between pairs of factors which should sometimes merged and sometimes not
- the main focus is often on a flow of influence from a small set of intervention variables to a small set of focused variables downstream of them, such as key outcomes

## **Features**

- As well as an interactive map, the package wraps DiagrammeR, graphviz, visNetwork and igraph to produce left-to-right layouts which are particularly suitable for directed maps.
- The new metric `Path robustness` is implemented alongside familiar node and graph metrics.
- For hierarchical coding, tools are provided to zoom in and out of individual hierarchies and entire maps.

## **How it works**

A family of functions `pipe_*` are provided (manipulate, calculate, hide, combine...) to implement successive filtering operations on a mapfile. 

So you import/load data as a mapfile and all your work steps are then just applying successive filters.

Each filter returns another mapfile, suitably filtered.

All of these filters can be produced and edited either in a chain of actual R functions or in the simplified text format which is processed by the parser.


Import or load a mapfile / Filter it / Filter it / Filter it / Output an interactive map, a print map or a table.

## **Parser**

There is also a parser which takes text strings with a simpler command syntax as input and outputs one of these main functions for each line of text. This parser is used to read text commands from the input window in Causal Map Viewer and manipulate the output map with the corresponding functions. The input text can also consist of several lines, and the commands are applied one by one in sequence, in a pipeline of commands, such that after each command, such as each command starts with the map defined by the previous line and produces a new one.

## **Output functions**

There are three output functions. Two are thin wrappers around visNetwork, DiagrammeR and DT, allowing a graph to be displayed using any of these three visualisation engines.

### **Additional fields**

Some of the commands such as path tracing create additional fields or variables for each factor and/or link. For example, when filtering by label, fields are created which can then be used to apply formatting.