better documentation for edge types #996

EagleoutIce · 2024-09-19T21:00:26Z

We get (automatically generated):

This document was generated automatically from '/home/limerent/GitHub/phd/flowr/src/documentation/print-dataflow-graph-wiki.ts' on 2024-09-19, 20:55:33 UTC presenting an overview of flowR's dataflow graph (version: 2.0.25, samples generated with R version 4.4.1).

This page briefly summarizes flowR's dataflow graph, represented by DataflowGraph in ./src/dataflow/graph/graph.ts.
In case you want to manually build such a graph (e.g., for testing), you can use the builder in ./src/dataflow/graph/dataflowgraph-builder.ts.
This wiki page focuses on explaining what such a dataflow graph looks like!

flowchart LR
    1{{"`#91;RNumber#93; 3
      (1)
      *1.6*`"}}
    0["`#91;RSymbol#93; x
      (0)
      *1.1*`"]
    2[["`#91;RBinaryOp#93; #60;#45;
      (2)
      *1.1-6*
    (0, 1)`"]]
    4(["`#91;RSymbol#93; x
      (4)
      *2.6*`"])
    5{{"`#91;RNumber#93; 1
      (5)
      *2.10*`"}}
    6[["`#91;RBinaryOp#93; #43;
      (6)
      *2.6-10*
    (4, 5)`"]]
    3["`#91;RSymbol#93; y
      (3)
      *2.1*`"]
    7[["`#91;RBinaryOp#93; #60;#45;
      (7)
      *2.1-10*
    (3, 6)`"]]
    8(["`#91;RSymbol#93; y
      (8)
      *3.1*`"])
    0 -->|"defined-by"| 1
    0 -->|"defined-by"| 2
    2 -->|"argument"| 1
    2 -->|"returns, argument"| 0
    4 -->|"reads"| 0
    6 -->|"reads, argument"| 4
    6 -->|"reads, argument"| 5
    3 -->|"defined-by"| 6
    3 -->|"defined-by"| 7
    7 -->|"argument"| 6
    7 -->|"returns, argument"| 3
    8 -->|"reads"| 3

R Code of the Dataflow Graph

The analysis required 11.22 ms (including parsing and normalization) within the generation environment.

x <- 3
y <- x + 1
y

Mermaid Code (without markings)

flowchart LR
    1{{"`#91;RNumber#93; 3
      (1)
      *1.6*`"}}
    0["`#91;RSymbol#93; x
      (0)
      *1.1*`"]
    2[["`#91;RBinaryOp#93; #60;#45;
      (2)
      *1.1-6*
    (0, 1)`"]]
    4(["`#91;RSymbol#93; x
      (4)
      *2.6*`"])
    5{{"`#91;RNumber#93; 1
      (5)
      *2.10*`"}}
    6[["`#91;RBinaryOp#93; #43;
      (6)
      *2.6-10*
    (4, 5)`"]]
    3["`#91;RSymbol#93; y
      (3)
      *2.1*`"]
    7[["`#91;RBinaryOp#93; #60;#45;
      (7)
      *2.1-10*
    (3, 6)`"]]
    8(["`#91;RSymbol#93; y
      (8)
      *3.1*`"])
    0 -->|"defined-by"| 1
    0 -->|"defined-by"| 2
    2 -->|"argument"| 1
    2 -->|"returns, argument"| 0
    4 -->|"reads"| 0
    6 -->|"reads, argument"| 4
    6 -->|"reads, argument"| 5
    3 -->|"defined-by"| 6
    3 -->|"defined-by"| 7
    7 -->|"argument"| 6
    7 -->|"returns, argument"| 3
    8 -->|"reads"| 3

The above dataflow graph showcases the general gist. We define a dataflow graph as a directed graph $G = (V, E)$, differentiating between 5 types of vertices $V$ and
18 types of edges $E$ allowing each vertex to have a single, and each edge to have multiple distinct types.

Vertex Types

The following vertices types exist:

Value
Use
FunctionCall
VariableDefinition
FunctionDefinition

Edge Types

The following edges types exist, internally we use bitmasks to represent multiple types in a compact form:

Reads ($1$)
DefinedBy ($2$)
Calls ($4$)
Returns ($8$)
DefinesOnCall ($16$)
DefinedByOnCall ($32$)
Argument ($64$)
SideEffectOnCall ($128$)
NonStandardEvaluation ($256$)

From an implementation perspective all of these types are represented by respective interfaces, see ./src/dataflow/graph/vertex.ts and ./src/dataflow/graph/edge.ts.

The following sections present details on the different types of vertices and edges, including examples and explanations.

Vertices

1) Value Vertex

Type: value

flowchart LR
    0{{"`#91;RNumber#93; 42
      (0)
      *1.1-2*`"}}
    style 0 stroke:black,stroke-width:7px;

R Code of the Dataflow Graph

The analysis required 1.48 ms (including parsing and normalization) within the generation environment.
The following marks are used in the graph to highlight sub-parts (uses ids): 0.

Mermaid Code (without markings)

flowchart LR
    0{{"`#91;RNumber#93; 42
      (0)
      *1.1-2*`"}}

Describes a constant value (numbers, logicals, strings, ...)

2) Use Vertex

Type: use

flowchart LR
    0(["`#91;RSymbol#93; x
      (0)
      *1.1*`"])
    style 0 stroke:black,stroke-width:7px;

R Code of the Dataflow Graph

The analysis required 1.20 ms (including parsing and normalization) within the generation environment.
The following marks are used in the graph to highlight sub-parts (uses ids): 0.

Mermaid Code (without markings)

flowchart LR
    0(["`#91;RSymbol#93; x
      (0)
      *1.1*`"])

Describes symbol/variable references

3) Function Call Vertex

Type: function-call

flowchart LR
    1[["`#91;RFunctionCall#93; foo
      (1)
      *1.1-5*`"]]
    style 1 stroke:black,stroke-width:7px;

R Code of the Dataflow Graph

The analysis required 1.49 ms (including parsing and normalization) within the generation environment.
The following marks are used in the graph to highlight sub-parts (uses ids): 1.

foo()

Mermaid Code (without markings)

flowchart LR
    1[["`#91;RFunctionCall#93; foo
      (1)
      *1.1-5*`"]]

Describes any kind of function call, these can happen implicitly as well! (see the notable cases)

Interesting Case

Built-In Function Call

flowchart LR
    0{{"`#91;RLogical#93; TRUE
      (0)
      *1.4-7*`"}}
    1{{"`#91;RNumber#93; 1
      (1)
      *1.10*`"}}
    3[["`#91;RIfThenElse#93; if
      (3)
      *1.1-10*
    (0, 1, [empty])`"]]
    style 3 stroke:black,stroke-width:7px; 
    3 -->|"returns, argument"| 1
    3 -->|"reads, argument"| 0

R Code of the Dataflow Graph

The analysis required 1.51 ms (including parsing and normalization) within the generation environment.
The following marks are used in the graph to highlight sub-parts (uses ids): 3.

if(TRUE) 1

Mermaid Code (without markings)

flowchart LR
    0{{"`#91;RLogical#93; TRUE
      (0)
      *1.4-7*`"}}
    1{{"`#91;RNumber#93; 1
      (1)
      *1.10*`"}}
    3[["`#91;RIfThenElse#93; if
      (3)
      *1.1-10*
    (0, 1, [empty])`"]]
    3 -->|"returns, argument"| 1
    3 -->|"reads, argument"| 0

Control structures like if are desugared into function calls (we omit the arguments of if(TRUE, 1) for simplicity).

4) Variable Definition Vertex

Type: variable-definition

flowchart LR
    1{{"`#91;RNumber#93; 1
      (1)
      *1.6*`"}}
    0["`#91;RSymbol#93; x
      (0)
      *1.1*`"]
    style 0 stroke:black,stroke-width:7px; 
    2[["`#91;RBinaryOp#93; #60;#45;
      (2)
      *1.1-6*
    (0, 1)`"]]
    0 -->|"defined-by"| 1
    0 -->|"defined-by"| 2
    2 -->|"argument"| 1
    2 -->|"returns, argument"| 0

R Code of the Dataflow Graph

The analysis required 1.40 ms (including parsing and normalization) within the generation environment.
The following marks are used in the graph to highlight sub-parts (uses ids): 0.

x <- 1

Mermaid Code (without markings)

flowchart LR
    1{{"`#91;RNumber#93; 1
      (1)
      *1.6*`"}}
    0["`#91;RSymbol#93; x
      (0)
      *1.1*`"]
    2[["`#91;RBinaryOp#93; #60;#45;
      (2)
      *1.1-6*
    (0, 1)`"]]
    0 -->|"defined-by"| 1
    0 -->|"defined-by"| 2
    2 -->|"argument"| 1
    2 -->|"returns, argument"| 0

Describes a defined variable. Not just <- causes this!

Interesting Case

Globally Defined Variable

flowchart LR
    1{{"`#91;RNumber#93; 1
      (1)
      *1.7*`"}}
    0["`#91;RSymbol#93; x
      (0)
      *1.1*`"]
    style 0 stroke:black,stroke-width:7px; 
    2[["`#91;RBinaryOp#93; #60;#60;#45;
      (2)
      *1.1-7*
    (0, 1)`"]]
    0 -->|"defined-by"| 1
    0 -->|"defined-by"| 2
    2 -->|"argument"| 1
    2 -->|"returns, argument"| 0

R Code of the Dataflow Graph

The analysis required 1.70 ms (including parsing and normalization) within the generation environment.
The following marks are used in the graph to highlight sub-parts (uses ids): 0.

x <<- 1

Mermaid Code (without markings)

flowchart LR
    1{{"`#91;RNumber#93; 1
      (1)
      *1.7*`"}}
    0["`#91;RSymbol#93; x
      (0)
      *1.1*`"]
    2[["`#91;RBinaryOp#93; #60;#60;#45;
      (2)
      *1.1-7*
    (0, 1)`"]]
    0 -->|"defined-by"| 1
    0 -->|"defined-by"| 2
    2 -->|"argument"| 1
    2 -->|"returns, argument"| 0

Are described similar within the dataflow graph, only the active environment differs.

5) Function Definition Vertex

Type: function-definition

flowchart LR
    2["`#91;RFunctionDefinition#93; function
      (2)
      *1.1-12*`"]
    style 2 stroke:black,stroke-width:7px; 

subgraph "flow-2" [function 2]
    0{{"`#91;RNumber#93; 1
      (0)
      *1.12*`"}}
    style 0 stroke:purple,stroke-width:4px; 
end
2 -.-|function| flow-2

R Code of the Dataflow Graph

The analysis required 1.15 ms (including parsing and normalization) within the generation environment.
The following marks are used in the graph to highlight sub-parts (uses ids): 2.

function() 1

Mermaid Code (without markings)

flowchart LR
    2["`#91;RFunctionDefinition#93; function
      (2)
      *1.1-12*`"]

subgraph "flow-2" [function 2]
    0{{"`#91;RNumber#93; 1
      (0)
      *1.12*`"}}
    style 0 stroke:purple,stroke-width:4px; 
end
2 -.-|function| flow-2

Describes a function definition. Are always anonymous at first; although they can be bound to a name, the id 0 refers to the 1 in the body. The presented subgraph refers to the body of the function, marking exit points and open references.

Edges

1) Reads Edge

Type: 1

flowchart LR
    1{{"`#91;RNumber#93; 2
      (1)
      *1.6*`"}}
    0["`#91;RSymbol#93; x
      (0)
      *1.1*`"]
    2[["`#91;RBinaryOp#93; #60;#45;
      (2)
      *1.1-6*
    (0, 1)`"]]
    4(["`#91;RSymbol#93; x
      (4)
      *2.7*`"])
    6[["`#91;RFunctionCall#93; print
      (6)
      *2.1-8*
    (4)`"]]
    0 -->|"defined-by"| 1
    0 -->|"defined-by"| 2
    2 -->|"argument"| 1
    2 -->|"returns, argument"| 0
    4 -->|"reads"| 0
    linkStyle 4 stroke:red,color:red,stroke-width:4px;
    6 -->|"reads, returns, argument"| 4

R Code of the Dataflow Graph

The analysis required 1.46 ms (including parsing and normalization) within the generation environment.
The following marks are used in the graph to highlight sub-parts (uses ids): 4->0.

x <- 2
print(x)

Mermaid Code (without markings)

flowchart LR
    1{{"`#91;RNumber#93; 2
      (1)
      *1.6*`"}}
    0["`#91;RSymbol#93; x
      (0)
      *1.1*`"]
    2[["`#91;RBinaryOp#93; #60;#45;
      (2)
      *1.1-6*
    (0, 1)`"]]
    4(["`#91;RSymbol#93; x
      (4)
      *2.7*`"])
    6[["`#91;RFunctionCall#93; print
      (6)
      *2.1-8*
    (4)`"]]
    0 -->|"defined-by"| 1
    0 -->|"defined-by"| 2
    2 -->|"argument"| 1
    2 -->|"returns, argument"| 0
    4 -->|"reads"| 0
    6 -->|"reads, returns, argument"| 4

The source vertex is usually a use that reads from the respective target definition.

Interesting Cases

Reads Edge (Call)

flowchart LR
    4["`#91;RFunctionDefinition#93; function
      (4)
      *1.8-20*`"]

subgraph "flow-4" [function 4]
    3[["`#91;RExpressionList#93; #123;
      (3)
      *1.19*`"]]
end
    0["`#91;RSymbol#93; foo
      (0)
      *1.1-3*`"]
    5[["`#91;RBinaryOp#93; #60;#45;
      (5)
      *1.1-20*
    (0, 4)`"]]
    %% Environment of 7 [level: 0]:
    %% Built-in
    %% 170----------------------------------------
    %%   foo: {foo (0, function, def. @5)}
    7[["`#91;RFunctionCall#93; foo
      (7)
      *2.1-5*`"]]
4 -.-|function| flow-4

    0 -->|"defined-by"| 4
    0 -->|"defined-by"| 5
    5 -->|"argument"| 4
    5 -->|"returns, argument"| 0
    7 -->|"reads"| 0
    linkStyle 5 stroke:red,color:red,stroke-width:4px;
    7 -->|"returns"| 3
    7 -->|"calls"| 4

R Code of the Dataflow Graph

The analysis required 1.62 ms (including parsing and normalization) within the generation environment.
The following marks are used in the graph to highlight sub-parts (uses ids): 7->0.

foo <- function() {}
foo()

Mermaid Code (without markings)

flowchart LR
    4["`#91;RFunctionDefinition#93; function
      (4)
      *1.8-20*`"]

subgraph "flow-4" [function 4]
    3[["`#91;RExpressionList#93; #123;
      (3)
      *1.19*`"]]
end
    0["`#91;RSymbol#93; foo
      (0)
      *1.1-3*`"]
    5[["`#91;RBinaryOp#93; #60;#45;
      (5)
      *1.1-20*
    (0, 4)`"]]
    %% Environment of 7 [level: 0]:
    %% Built-in
    %% 170----------------------------------------
    %%   foo: {foo (0, function, def. @5)}
    7[["`#91;RFunctionCall#93; foo
      (7)
      *2.1-5*`"]]
4 -.-|function| flow-4

    0 -->|"defined-by"| 4
    0 -->|"defined-by"| 5
    5 -->|"argument"| 4
    5 -->|"returns, argument"| 0
    7 -->|"reads"| 0
    7 -->|"returns"| 3
    7 -->|"calls"| 4

Named calls are resolved too, linking to the symbol that holds the anonymous function definition (indirectly or directly)

Reads Edge (Parameter)

flowchart LR
    9["`#91;RFunctionDefinition#93; function
      (9)
      *1.6-24*`"]

subgraph "flow-9" [function 9]
    1["`#91;RSymbol#93; x
      (1)
      *1.15*`"]
    3["`#91;RSymbol#93; y
      (3)
      *1.18*`"]
    4(["`#91;RSymbol#93; x
      (4)
      *1.20*`"])
    8[["`#91;RExpressionList#93; #123;
      (8)
      *1.23*`"]]
end
    0["`#91;RSymbol#93; f
      (0)
      *1.1*`"]
    10[["`#91;RBinaryOp#93; #60;#45;
      (10)
      *1.1-24*
    (0, 9)`"]]
    3 -->|"defined-by"| 4
    4 -->|"reads"| 1
    linkStyle 1 stroke:red,color:red,stroke-width:4px;
9 -.-|function| flow-9

    0 -->|"defined-by"| 9
    0 -->|"defined-by"| 10
    10 -->|"argument"| 9
    10 -->|"returns, argument"| 0

R Code of the Dataflow Graph

The analysis required 1.45 ms (including parsing and normalization) within the generation environment.
The following marks are used in the graph to highlight sub-parts (uses ids): 4->1.

f <- function(x, y=x) {}

Mermaid Code (without markings)

flowchart LR
    9["`#91;RFunctionDefinition#93; function
      (9)
      *1.6-24*`"]

subgraph "flow-9" [function 9]
    1["`#91;RSymbol#93; x
      (1)
      *1.15*`"]
    3["`#91;RSymbol#93; y
      (3)
      *1.18*`"]
    4(["`#91;RSymbol#93; x
      (4)
      *1.20*`"])
    8[["`#91;RExpressionList#93; #123;
      (8)
      *1.23*`"]]
end
    0["`#91;RSymbol#93; f
      (0)
      *1.1*`"]
    10[["`#91;RBinaryOp#93; #60;#45;
      (10)
      *1.1-24*
    (0, 9)`"]]
    3 -->|"defined-by"| 4
    4 -->|"reads"| 1
9 -.-|function| flow-9

    0 -->|"defined-by"| 9
    0 -->|"defined-by"| 10
    10 -->|"argument"| 9
    10 -->|"returns, argument"| 0

Parameters can read from each other as well.

2) DefinedBy Edge

Type: 2

flowchart LR
    1(["`#91;RSymbol#93; y
      (1)
      *1.6*`"])
    0["`#91;RSymbol#93; x
      (0)
      *1.1*`"]
    2[["`#91;RBinaryOp#93; #60;#45;
      (2)
      *1.1-6*
    (0, 1)`"]]
    0 -->|"defined-by"| 1
    linkStyle 0 stroke:red,color:red,stroke-width:4px;
    0 -->|"defined-by"| 2
    linkStyle 1 stroke:red,color:red,stroke-width:4px;
    2 -->|"argument"| 1
    2 -->|"returns, argument"| 0

R Code of the Dataflow Graph

The analysis required 1.08 ms (including parsing and normalization) within the generation environment.
The following marks are used in the graph to highlight sub-parts (uses ids): 0->1, 0->2.

x <- y

Mermaid Code (without markings)

flowchart LR
    1(["`#91;RSymbol#93; y
      (1)
      *1.6*`"])
    0["`#91;RSymbol#93; x
      (0)
      *1.1*`"]
    2[["`#91;RBinaryOp#93; #60;#45;
      (2)
      *1.1-6*
    (0, 1)`"]]
    0 -->|"defined-by"| 1
    0 -->|"defined-by"| 2
    2 -->|"argument"| 1
    2 -->|"returns, argument"| 0

The source vertex is usually a define variable that is defined by the respective target use. However, nested definitions can carry it (in the nested case, x is defined by the return value of <-(y, z)). Additionally, we link the assignment.

Interesting Cases

DefinedBy Edge (Nested)

flowchart LR
    2(["`#91;RSymbol#93; z
      (2)
      *1.11*`"])
    1["`#91;RSymbol#93; y
      (1)
      *1.6*`"]
    3[["`#91;RBinaryOp#93; #60;#45;
      (3)
      *1.6-11*
    (1, 2)`"]]
    0["`#91;RSymbol#93; x
      (0)
      *1.1*`"]
    4[["`#91;RBinaryOp#93; #60;#45;
      (4)
      *1.1-11*
    (0, 3)`"]]
    1 -->|"defined-by"| 2
    1 -->|"defined-by"| 3
    linkStyle 1 stroke:red,color:red,stroke-width:4px;
    3 -->|"argument"| 2
    3 -->|"returns, argument"| 1
    0 -->|"defined-by"| 3
    linkStyle 4 stroke:red,color:red,stroke-width:4px;
    0 -->|"defined-by"| 4
    linkStyle 5 stroke:red,color:red,stroke-width:4px;
    4 -->|"argument"| 3
    4 -->|"returns, argument"| 0

R Code of the Dataflow Graph

The analysis required 1.33 ms (including parsing and normalization) within the generation environment.
The following marks are used in the graph to highlight sub-parts (uses ids): 0->4, 0->3, 1->3.

x <- y <- z

Mermaid Code (without markings)

flowchart LR
    2(["`#91;RSymbol#93; z
      (2)
      *1.11*`"])
    1["`#91;RSymbol#93; y
      (1)
      *1.6*`"]
    3[["`#91;RBinaryOp#93; #60;#45;
      (3)
      *1.6-11*
    (1, 2)`"]]
    0["`#91;RSymbol#93; x
      (0)
      *1.1*`"]
    4[["`#91;RBinaryOp#93; #60;#45;
      (4)
      *1.1-11*
    (0, 3)`"]]
    1 -->|"defined-by"| 2
    1 -->|"defined-by"| 3
    3 -->|"argument"| 2
    3 -->|"returns, argument"| 1
    0 -->|"defined-by"| 3
    0 -->|"defined-by"| 4
    4 -->|"argument"| 3
    4 -->|"returns, argument"| 0

Nested definitions can carry the defined by edge as well.

DefinedBy Edge (Expression)

flowchart LR
    1(["`#91;RSymbol#93; y
      (1)
      *1.6*`"])
    2(["`#91;RSymbol#93; z
      (2)
      *1.10*`"])
    3[["`#91;RBinaryOp#93; #43;
      (3)
      *1.6-10*
    (1, 2)`"]]
    0["`#91;RSymbol#93; x
      (0)
      *1.1*`"]
    4[["`#91;RBinaryOp#93; #60;#45;
      (4)
      *1.1-10*
    (0, 3)`"]]
    3 -->|"reads, argument"| 1
    3 -->|"reads, argument"| 2
    0 -->|"defined-by"| 3
    linkStyle 2 stroke:red,color:red,stroke-width:4px;
    0 -->|"defined-by"| 4
    4 -->|"argument"| 3
    4 -->|"returns, argument"| 0

R Code of the Dataflow Graph

The analysis required 1.29 ms (including parsing and normalization) within the generation environment.
The following marks are used in the graph to highlight sub-parts (uses ids): 0->3.

x <- y + z

Mermaid Code (without markings)

flowchart LR
    1(["`#91;RSymbol#93; y
      (1)
      *1.6*`"])
    2(["`#91;RSymbol#93; z
      (2)
      *1.10*`"])
    3[["`#91;RBinaryOp#93; #43;
      (3)
      *1.6-10*
    (1, 2)`"]]
    0["`#91;RSymbol#93; x
      (0)
      *1.1*`"]
    4[["`#91;RBinaryOp#93; #60;#45;
      (4)
      *1.1-10*
    (0, 3)`"]]
    3 -->|"reads, argument"| 1
    3 -->|"reads, argument"| 2
    0 -->|"defined-by"| 3
    0 -->|"defined-by"| 4
    4 -->|"argument"| 3
    4 -->|"returns, argument"| 0

Here, we define by the result of the + expression.

3) Calls Edge

Type: 4

flowchart LR
    4["`#91;RFunctionDefinition#93; function
      (4)
      *1.8-20*`"]

subgraph "flow-4" [function 4]
    3[["`#91;RExpressionList#93; #123;
      (3)
      *1.19*`"]]
end
    0["`#91;RSymbol#93; foo
      (0)
      *1.1-3*`"]
    5[["`#91;RBinaryOp#93; #60;#45;
      (5)
      *1.1-20*
    (0, 4)`"]]
    %% Environment of 7 [level: 0]:
    %% Built-in
    %% 343----------------------------------------
    %%   foo: {foo (0, function, def. @5)}
    7[["`#91;RFunctionCall#93; foo
      (7)
      *2.1-5*`"]]
4 -.-|function| flow-4

    0 -->|"defined-by"| 4
    0 -->|"defined-by"| 5
    5 -->|"argument"| 4
    5 -->|"returns, argument"| 0
    7 -->|"reads"| 0
    7 -->|"returns"| 3
    7 -->|"calls"| 4
    linkStyle 7 stroke:red,color:red,stroke-width:4px;

R Code of the Dataflow Graph

The analysis required 1.52 ms (including parsing and normalization) within the generation environment.
The following marks are used in the graph to highlight sub-parts (uses ids): 7->4.

foo <- function() {}
foo()

Mermaid Code (without markings)

flowchart LR
    4["`#91;RFunctionDefinition#93; function
      (4)
      *1.8-20*`"]

subgraph "flow-4" [function 4]
    3[["`#91;RExpressionList#93; #123;
      (3)
      *1.19*`"]]
end
    0["`#91;RSymbol#93; foo
      (0)
      *1.1-3*`"]
    5[["`#91;RBinaryOp#93; #60;#45;
      (5)
      *1.1-20*
    (0, 4)`"]]
    %% Environment of 7 [level: 0]:
    %% Built-in
    %% 343----------------------------------------
    %%   foo: {foo (0, function, def. @5)}
    7[["`#91;RFunctionCall#93; foo
      (7)
      *2.1-5*`"]]
4 -.-|function| flow-4

    0 -->|"defined-by"| 4
    0 -->|"defined-by"| 5
    5 -->|"argument"| 4
    5 -->|"returns, argument"| 0
    7 -->|"reads"| 0
    7 -->|"returns"| 3
    7 -->|"calls"| 4

Link the function call to the (anonymous) function definition.

4) Returns Edge

Type: 8

flowchart LR
    3["`#91;RFunctionDefinition#93; function
      (3)
      *1.8-19*`"]

subgraph "flow-3" [function 3]
    1(["`#91;RSymbol#93; x
      (1)
      *1.19*`"])
    style 1 stroke:purple,stroke-width:4px; 
end
    0["`#91;RSymbol#93; foo
      (0)
      *1.1-3*`"]
    4[["`#91;RBinaryOp#93; #60;#45;
      (4)
      *1.1-19*
    (0, 3)`"]]
    %% Environment of 6 [level: 0]:
    %% Built-in
    %% 388----------------------------------------
    %%   foo: {foo (0, function, def. @4)}
    6[["`#91;RFunctionCall#93; foo
      (6)
      *2.1-5*`"]]
3 -.-|function| flow-3

    0 -->|"defined-by"| 3
    0 -->|"defined-by"| 4
    4 -->|"argument"| 3
    4 -->|"returns, argument"| 0
    6 -->|"reads"| 0
    6 -->|"returns"| 1
    linkStyle 6 stroke:red,color:red,stroke-width:4px;
    6 -->|"calls"| 3

R Code of the Dataflow Graph

The analysis required 1.63 ms (including parsing and normalization) within the generation environment.
The following marks are used in the graph to highlight sub-parts (uses ids): 6->1.

foo <- function() x
foo()

Mermaid Code (without markings)

flowchart LR
    3["`#91;RFunctionDefinition#93; function
      (3)
      *1.8-19*`"]

subgraph "flow-3" [function 3]
    1(["`#91;RSymbol#93; x
      (1)
      *1.19*`"])
    style 1 stroke:purple,stroke-width:4px; 
end
    0["`#91;RSymbol#93; foo
      (0)
      *1.1-3*`"]
    4[["`#91;RBinaryOp#93; #60;#45;
      (4)
      *1.1-19*
    (0, 3)`"]]
    %% Environment of 6 [level: 0]:
    %% Built-in
    %% 388----------------------------------------
    %%   foo: {foo (0, function, def. @4)}
    6[["`#91;RFunctionCall#93; foo
      (6)
      *2.1-5*`"]]
3 -.-|function| flow-3

    0 -->|"defined-by"| 3
    0 -->|"defined-by"| 4
    4 -->|"argument"| 3
    4 -->|"returns, argument"| 0
    6 -->|"reads"| 0
    6 -->|"returns"| 1
    6 -->|"calls"| 3

Link the function call to the exit points of the target definition (this may incorporate the call-context).

5) DefinesOnCall Edge

Type: 16

flowchart LR
    6["`#91;RFunctionDefinition#93; function
      (6)
      *1.6-19*`"]

subgraph "flow-6" [function 6]
    1["`#91;RSymbol#93; x
      (1)
      *1.15*`"]
    5[["`#91;RExpressionList#93; #123;
      (5)
      *1.18*`"]]
end
    0["`#91;RSymbol#93; f
      (0)
      *1.1*`"]
    7[["`#91;RBinaryOp#93; #60;#45;
      (7)
      *1.1-19*
    (0, 6)`"]]
    10{{"`#91;RNumber#93; 1
      (10)
      *2.5*`"}}
    11(["`#91;RArgument#93; x
      (11)
      *2.3*`"])
    %% Environment of 12 [level: 0]:
    %% Built-in
    %% 454----------------------------------------
    %%   f: {f (0, function, def. @7)}
    12[["`#91;RFunctionCall#93; f
      (12)
      *2.1-6*
    (x (11))`"]]
    1 -->|"defined-by-on-call"| 11
    linkStyle 0 stroke:red,color:red,stroke-width:4px;
6 -.-|function| flow-6

    0 -->|"defined-by"| 6
    0 -->|"defined-by"| 7
    7 -->|"argument"| 6
    7 -->|"returns, argument"| 0
    11 -->|"reads"| 10
    11 -->|"defines-on-call"| 1
    linkStyle 7 stroke:red,color:red,stroke-width:4px;
    12 -->|"argument"| 11
    12 -->|"reads"| 0
    12 -->|"returns"| 5
    12 -->|"calls"| 6

R Code of the Dataflow Graph

The analysis required 1.95 ms (including parsing and normalization) within the generation environment.
The following marks are used in the graph to highlight sub-parts (uses ids): 11->1, 1->11.

f <- function(x) {}
f(x=1)

Mermaid Code (without markings)

flowchart LR
    6["`#91;RFunctionDefinition#93; function
      (6)
      *1.6-19*`"]

subgraph "flow-6" [function 6]
    1["`#91;RSymbol#93; x
      (1)
      *1.15*`"]
    5[["`#91;RExpressionList#93; #123;
      (5)
      *1.18*`"]]
end
    0["`#91;RSymbol#93; f
      (0)
      *1.1*`"]
    7[["`#91;RBinaryOp#93; #60;#45;
      (7)
      *1.1-19*
    (0, 6)`"]]
    10{{"`#91;RNumber#93; 1
      (10)
      *2.5*`"}}
    11(["`#91;RArgument#93; x
      (11)
      *2.3*`"])
    %% Environment of 12 [level: 0]:
    %% Built-in
    %% 454----------------------------------------
    %%   f: {f (0, function, def. @7)}
    12[["`#91;RFunctionCall#93; f
      (12)
      *2.1-6*
    (x (11))`"]]
    1 -->|"defined-by-on-call"| 11
6 -.-|function| flow-6

    0 -->|"defined-by"| 6
    0 -->|"defined-by"| 7
    7 -->|"argument"| 6
    7 -->|"returns, argument"| 0
    11 -->|"reads"| 10
    11 -->|"defines-on-call"| 1
    12 -->|"argument"| 11
    12 -->|"reads"| 0
    12 -->|"returns"| 5
    12 -->|"calls"| 6

This edge is automatically joined with defined by on call!

Link an Argument to whichever parameter they cause to be defined if the related function call is invoked.

6) DefinedByOnCall Edge

Type: 32

flowchart LR
    6["`#91;RFunctionDefinition#93; function
      (6)
      *1.6-19*`"]

subgraph "flow-6" [function 6]
    1["`#91;RSymbol#93; x
      (1)
      *1.15*`"]
    5[["`#91;RExpressionList#93; #123;
      (5)
      *1.18*`"]]
end
    0["`#91;RSymbol#93; f
      (0)
      *1.1*`"]
    7[["`#91;RBinaryOp#93; #60;#45;
      (7)
      *1.1-19*
    (0, 6)`"]]
    10{{"`#91;RNumber#93; 1
      (10)
      *2.5*`"}}
    11(["`#91;RArgument#93; x
      (11)
      *2.3*`"])
    %% Environment of 12 [level: 0]:
    %% Built-in
    %% 520----------------------------------------
    %%   f: {f (0, function, def. @7)}
    12[["`#91;RFunctionCall#93; f
      (12)
      *2.1-6*
    (x (11))`"]]
    1 -->|"defined-by-on-call"| 11
    linkStyle 0 stroke:red,color:red,stroke-width:4px;
6 -.-|function| flow-6

    0 -->|"defined-by"| 6
    0 -->|"defined-by"| 7
    7 -->|"argument"| 6
    7 -->|"returns, argument"| 0
    11 -->|"reads"| 10
    11 -->|"defines-on-call"| 1
    linkStyle 7 stroke:red,color:red,stroke-width:4px;
    12 -->|"argument"| 11
    12 -->|"reads"| 0
    12 -->|"returns"| 5
    12 -->|"calls"| 6

R Code of the Dataflow Graph

The analysis required 1.92 ms (including parsing and normalization) within the generation environment.
The following marks are used in the graph to highlight sub-parts (uses ids): 11->1, 1->11.

f <- function(x) {}
f(x=1)

Mermaid Code (without markings)

flowchart LR
    6["`#91;RFunctionDefinition#93; function
      (6)
      *1.6-19*`"]

subgraph "flow-6" [function 6]
    1["`#91;RSymbol#93; x
      (1)
      *1.15*`"]
    5[["`#91;RExpressionList#93; #123;
      (5)
      *1.18*`"]]
end
    0["`#91;RSymbol#93; f
      (0)
      *1.1*`"]
    7[["`#91;RBinaryOp#93; #60;#45;
      (7)
      *1.1-19*
    (0, 6)`"]]
    10{{"`#91;RNumber#93; 1
      (10)
      *2.5*`"}}
    11(["`#91;RArgument#93; x
      (11)
      *2.3*`"])
    %% Environment of 12 [level: 0]:
    %% Built-in
    %% 520----------------------------------------
    %%   f: {f (0, function, def. @7)}
    12[["`#91;RFunctionCall#93; f
      (12)
      *2.1-6*
    (x (11))`"]]
    1 -->|"defined-by-on-call"| 11
6 -.-|function| flow-6

    0 -->|"defined-by"| 6
    0 -->|"defined-by"| 7
    7 -->|"argument"| 6
    7 -->|"returns, argument"| 0
    11 -->|"reads"| 10
    11 -->|"defines-on-call"| 1
    12 -->|"argument"| 11
    12 -->|"reads"| 0
    12 -->|"returns"| 5
    12 -->|"calls"| 6

This edge is automatically joined with defines on call!

This represents the other direction of defines on call (i.e., links the parameter to the argument). This is just for completeness.

7) Argument Edge

Type: 64

flowchart LR
    1(["`#91;RSymbol#93; x
      (1)
      *1.3*`"])
    3(["`#91;RSymbol#93; y
      (3)
      *1.5*`"])
    5[["`#91;RFunctionCall#93; f
      (5)
      *1.1-6*
    (1, 3)`"]]
    5 -->|"reads, argument"| 1
    linkStyle 0 stroke:red,color:red,stroke-width:4px;
    5 -->|"reads, argument"| 3
    linkStyle 1 stroke:red,color:red,stroke-width:4px;

R Code of the Dataflow Graph

The analysis required 1.39 ms (including parsing and normalization) within the generation environment.
The following marks are used in the graph to highlight sub-parts (uses ids): 5->1, 5->3.

f(x,y)

Mermaid Code (without markings)

flowchart LR
    1(["`#91;RSymbol#93; x
      (1)
      *1.3*`"])
    3(["`#91;RSymbol#93; y
      (3)
      *1.5*`"])
    5[["`#91;RFunctionCall#93; f
      (5)
      *1.1-6*
    (1, 3)`"]]
    5 -->|"reads, argument"| 1
    5 -->|"reads, argument"| 3

Links a function call to the entry point of its arguments. If we do not know the target of such a call, we automatically assume that all arguments are read by the call as well!

8) SideEffectOnCall Edge

Type: 128

flowchart LR
    %% Environment of 7 [level: 0]:
    %% Built-in
    %% 623----------------------------------------
    %%   x: {x (3, variable, def. @5)}
    7["`#91;RFunctionDefinition#93; function
      (7)
      *1.6-27*`"]

subgraph "flow-7" [function 7]
    4{{"`#91;RNumber#93; 2
      (4)
      *1.25*`"}}
    3["`#91;RSymbol#93; x
      (3)
      *1.19*`"]
    5[["`#91;RBinaryOp#93; #60;#60;#45;
      (5)
      *1.19-25*
    (3, 4)`"]]
    6[["`#91;RExpressionList#93; #123;
      (6)
      *1.17*
    (5)`"]]
end
    0["`#91;RSymbol#93; f
      (0)
      *1.1*`"]
    8[["`#91;RBinaryOp#93; #60;#45;
      (8)
      *1.1-27*
    (0, 7)`"]]
    %% Environment of 10 [level: 0]:
    %% Built-in
    %% 631----------------------------------------
    %%   f: {f (0, function, def. @8)}
    10[["`#91;RFunctionCall#93; f
      (10)
      *2.1-3*`"]]
    3 -->|"defined-by"| 4
    3 -->|"defined-by"| 5
    3 -->|"side-effect-on-call"| 10
    linkStyle 2 stroke:red,color:red,stroke-width:4px;
    5 -->|"argument"| 4
    5 -->|"returns, argument"| 3
    6 -->|"returns, argument"| 5
7 -.-|function| flow-7

    0 -->|"defined-by"| 7
    0 -->|"defined-by"| 8
    8 -->|"argument"| 7
    8 -->|"returns, argument"| 0
    10 -->|"reads"| 0
    10 -->|"returns"| 6
    10 -->|"calls"| 7

R Code of the Dataflow Graph

The analysis required 1.98 ms (including parsing and normalization) within the generation environment.
The following marks are used in the graph to highlight sub-parts (uses ids): 3->10.

f <- function() { x <<- 2 }
f()

Mermaid Code (without markings)

flowchart LR
    %% Environment of 7 [level: 0]:
    %% Built-in
    %% 623----------------------------------------
    %%   x: {x (3, variable, def. @5)}
    7["`#91;RFunctionDefinition#93; function
      (7)
      *1.6-27*`"]

subgraph "flow-7" [function 7]
    4{{"`#91;RNumber#93; 2
      (4)
      *1.25*`"}}
    3["`#91;RSymbol#93; x
      (3)
      *1.19*`"]
    5[["`#91;RBinaryOp#93; #60;#60;#45;
      (5)
      *1.19-25*
    (3, 4)`"]]
    6[["`#91;RExpressionList#93; #123;
      (6)
      *1.17*
    (5)`"]]
end
    0["`#91;RSymbol#93; f
      (0)
      *1.1*`"]
    8[["`#91;RBinaryOp#93; #60;#45;
      (8)
      *1.1-27*
    (0, 7)`"]]
    %% Environment of 10 [level: 0]:
    %% Built-in
    %% 631----------------------------------------
    %%   f: {f (0, function, def. @8)}
    10[["`#91;RFunctionCall#93; f
      (10)
      *2.1-3*`"]]
    3 -->|"defined-by"| 4
    3 -->|"defined-by"| 5
    3 -->|"side-effect-on-call"| 10
    5 -->|"argument"| 4
    5 -->|"returns, argument"| 3
    6 -->|"returns, argument"| 5
7 -.-|function| flow-7

    0 -->|"defined-by"| 7
    0 -->|"defined-by"| 8
    8 -->|"argument"| 7
    8 -->|"returns, argument"| 0
    10 -->|"reads"| 0
    10 -->|"returns"| 6
    10 -->|"calls"| 7

Links a global side effect to an affected function call (e.g., a super definition within the function body)

9) NonStandardEvaluation Edge

Type: 256

flowchart LR
    1(["`#91;RSymbol#93; x
      (1)
      *1.7*`"])
    3[["`#91;RFunctionCall#93; quote
      (3)
      *1.1-8*
    (1)`"]]
    3 -->|"argument, non-standard-evaluation"| 1
    linkStyle 0 stroke:red,color:red,stroke-width:4px;

R Code of the Dataflow Graph

The analysis required 1.34 ms (including parsing and normalization) within the generation environment.
The following marks are used in the graph to highlight sub-parts (uses ids): 3->1.

quote(x)

Mermaid Code (without markings)

flowchart LR
    1(["`#91;RSymbol#93; x
      (1)
      *1.7*`"])
    3[["`#91;RFunctionCall#93; quote
      (3)
      *1.1-8*
    (1)`"]]
    3 -->|"argument, non-standard-evaluation"| 1

Marks cases in which R's non-standard evaluation mechanisms cause the default semantics to deviate

thanks github

EagleoutIce · 2024-10-04T18:46:04Z

This pull request is included in v2.1.0 (see Release v2.1.0 (Query API, Improved Wiki, Configuration for Built-Ins)).

EagleoutIce added 5 commits September 19, 2024 17:12

wip: test documentation of graph compartments

3f78f75

test: explain df graph edge and vertex types

8192577

doc: refine wiki pages to prepare for dataflow explanation

00b4d80

doc: automated dataflow graph wiki page :D

348e9ff

lint-fix: handle linter issues

2d519f4

EagleoutIce linked an issue Sep 19, 2024 that may be closed by this pull request

Better documentation for edge types #994

Closed

refactor: remove dollar math from generated markdown

06ae3ff

thanks github

EagleoutIce merged commit d1ebd9c into main Sep 19, 2024
14 checks passed

EagleoutIce deleted the 994-better-documentation-for-edge-types branch September 19, 2024 21:04

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

better documentation for edge types #996

better documentation for edge types #996

EagleoutIce commented Sep 19, 2024

EagleoutIce commented Oct 4, 2024

better documentation for edge types #996

better documentation for edge types #996

Conversation

EagleoutIce commented Sep 19, 2024

Vertices

1) Value Vertex

2) Use Vertex

3) Function Call Vertex

Built-In Function Call

4) Variable Definition Vertex

Globally Defined Variable

5) Function Definition Vertex

Edges

1) Reads Edge

Reads Edge (Call)

Reads Edge (Parameter)

2) DefinedBy Edge

DefinedBy Edge (Nested)

DefinedBy Edge (Expression)

3) Calls Edge

4) Returns Edge

5) DefinesOnCall Edge

6) DefinedByOnCall Edge

7) Argument Edge

8) SideEffectOnCall Edge

9) NonStandardEvaluation Edge

EagleoutIce commented Oct 4, 2024