Graphs and Diagrams
Sage supports graphs and diagrams using
Mermaid,
a popular JavaScript-based diagramming and charting tool.
In Sage, the [diagram] and [mermaid]
tags are used to create Mermaid diagrams.
The [diagram] tag uses
MiniCalc
to build a diagram using one of the Mermaid
fluent APIs.
For example…
[diagram]
@NewDSFlowchart()
.LeftToRight
.SetCurveShape(@TDSFlowchartCurveShape.Linear)
.Node(n1, 'Apple').Hexagon
.Node(n2, 'Banana').Circle
.Node(n3, 'Cherry').Oval
.Link(n1, n2).Arrow
.Link(n2, n3).DoubleArrow
[end]
The above produces…
One significant advantage is that the [diagram] tag
is theme-aware, using the StyleDark and StyleLight methods.
For example…
[diagram]
@NewDSFlowchart()
.LeftToRight
.SetCurveShape(@TDSFlowchartCurveShape.Linear)
.Node(n1, 'Apple').Hexagon
.Node(n2, 'Banana').Circle
.Node(n3, 'Cherry').Oval
.StyleDark('fill:red,color:yellow')
.StyleLight('fill:yellow,color:black')
.Link(n1, n2).Arrow
.StyleDark('stroke:cyan')
.StyleLight('stroke:blue')
.Link(n2, n3).DoubleArrow.Dotted
[end]
The above produces this…
Toggle the Sage theme to see the full effect.
---
config:
flowchart:
curve: linear
---
flowchart LR
direction LR
n0{{"Apple"}} --> n1(("Banana"))
n1 <--> n2(["Cherry"])
---
config:
flowchart:
curve: linear
---
flowchart LR
direction LR
n0{{"Apple"}} --> n1(("Banana"))
n1 <-.-> n2(["Cherry"])
style n2 fill:red,color:yellow
linkStyle 0 stroke:cyan;
The [mermaid] tag uses raw Mermaid to build a
Mermaid diagram.
Below are several different kinds of examples.
A flow chart…
[mermaid]
flowchart LR
A[Start] --> B{Error?};
B -->|Yes| C[Hmm...];
C --> D[Debug];
D --> B;
B ---->|No| E[Yay!];
[end]
The above produces this chart…
The same chart, but this time, in a box:
flowchart LR
A[Start] --> B{Error?};
B -->|Yes| C[Hmm...];
C --> D[Debug];
D --> B;
B ---->|No| E[Yay!];
flowchart LR
A[Start] --> B{Error?};
B -->|Yes| C[Hmm...];
C --> D[Debug];
D --> B;
B ---->|No| E[Yay!];
A flowchart with sub-graphs…
[mermaid]
flowchart LR
subgraph Client
A(("Client<br>[GUI]")) --> B[Client<br>Proxy]
B --> C[TCP<br>Client]
end
C -. "~Network~" .-> E
subgraph Server
E[TCP<br>Server] --> F[Server<br>Skeleton]
F --> G((Impl.<br>Object))
end
[end]
The above produces this graph…
flowchart LR
subgraph Client
A(("Client<br>[GUI]")) --> B[Client<br>Proxy]
B --> C[TCP<br>Client]
end
C -. "~Network~" .-> E
subgraph Server
E[TCP<br>Server] --> F[Server<br>Skeleton]
F --> G((Impl.<br>Object))
end
A sequence diagram…
[mermaid]
sequenceDiagram
Alice->>John: Hello John, how are you?
loop Healthcheck
John->>John: Fight against hypochondria
end
Note right of John: Rational thoughts!
John-->>Alice: Great!
John->>Bob: How about you?
Bob-->>John: Jolly good!
[end]
The above produces this diagram…
sequenceDiagram
Alice->>John: Hello John, how are you?
loop Healthcheck
John->>John: Fight against hypochondria
end
Note right of John: Rational thoughts!
John-->>Alice: Great!
John->>Bob: How about you?
Bob-->>John: Jolly good!
A state diagram…
[mermaid]
stateDiagram-v2
state fork_state <<fork>>
[*] --> fork_state
fork_state --> State2
fork_state --> State3
state join_state <<join>>
State2 --> join_state
State3 --> join_state
join_state --> State4
State4 --> [*]
[end]
The above produces this diagram…
stateDiagram-v2
state fork_state <<fork>>
[*] --> fork_state
fork_state --> State2
fork_state --> State3
state join_state <<join>>
State2 --> join_state
State3 --> join_state
join_state --> State4
State4 --> [*]
A class diagram…
[mermaid]
classDiagram
Person <|-- Student
Person <|-- Professor
Person : +String name
Person : +String phoneNumber
Person : +String emailAddress
Person: +purchaseParkingPass()
Address "1" <-- "0..1" Person:lives at
class Student{
+int studentNumber
+int averageMark
+isEligibleToEnrol()
+getSeminarsTaken()
}
class Professor{
+int salary
}
class Address{
+String street
+String city
+String state
+int postalCode
+String country
-validate()
+outputAsLabel()
}
[end]
The above produces this diagram…
classDiagram
Person <|-- Student
Person <|-- Professor
Person : +String name
Person : +String phoneNumber
Person : +String emailAddress
Person: +purchaseParkingPass()
Address "1" <-- "0..1" Person:lives at
class Student{
+int studentNumber
+int averageMark
+isEligibleToEnrol()
+getSeminarsTaken()
}
class Professor{
+int salary
}
class Address{
+String street
+String city
+String state
+int postalCode
+String country
-validate()
+outputAsLabel()
}
An ER diagram…
[mermaid]
erDiagram
CUSTOMER ||--o{ ORDER : places
CUSTOMER {
string name
string custNumber
string sector
}
ORDER ||--|{ LINE-ITEM : contains
ORDER {
int orderNumber
string deliveryAddress
}
LINE-ITEM {
string productCode
int quantity
float pricePerUnit
}
[end]
The above produces this diagram…
erDiagram
CUSTOMER ||--o{ ORDER : places
CUSTOMER {
string name
string custNumber
string sector
}
ORDER ||--|{ LINE-ITEM : contains
ORDER {
int orderNumber
string deliveryAddress
}
LINE-ITEM {
string productCode
int quantity
float pricePerUnit
}
A Gantt diagram…
[mermaid]
gantt
title A Gantt Diagram
dateFormat YYYY-MM-DD
section Section
A task :a1, 2014-01-01, 30d
Another task :after a1 , 20d
section Another
Task in sec :active, 2014-01-12 , 12d
another task :crit, 24d
[end]
The above produces this diagram…
gantt
title A Gantt Diagram
dateFormat YYYY-MM-DD
section Section
A task :a1, 2014-01-01, 30d
Another task :after a1 , 20d
section Another
Task in sec :active, 2014-01-12 , 12d
another task :crit, 24d
A user journey diagram…
[mermaid]
journey
title My working day
section Go to work
Make tea: 5: Me
Go upstairs: 3: Me
Do work: 1: Me, Cat
section Go home
Go downstairs: 5: Me
Sit down: 3: Me
[end]
The above produces this diagram…
journey
title My working day
section Go to work
Make tea: 5: Me
Go upstairs: 3: Me
Do work: 1: Me, Cat
section Go home
Go downstairs: 5: Me
Sit down: 3: Me
A requirement diagram…
[mermaid]
requirementDiagram
requirement test_req {
id: 1
text: the test text.
risk: high
verifymethod: test
}
element test_entity {
type: simulation
}
test_entity - satisfies -> test_req
[end]
The above produces this chart…
requirementDiagram
requirement test_req {
id: 1
text: the test text.
risk: high
verifymethod: test
}
element test_entity {
type: simulation
}
test_entity - satisfies -> test_req
A pie chart…
[mermaid]
pie title Pets adopted by volunteers
"Dogs" : 386
"Cats" : 85
"Rats" : 15
"Birds": 10
"Goats": 10
[end]
The above produces this chart…
pie title Pets Adopted by Volunteers "Dogs" : 386 "Cats" : 622 "Rats" : 218 "Birds": 343
A mind map…
[mermaid]
mindmap
root((mindmap))
Origins
Long history
::icon(fa fa-book)
Popularisation
British popular psychology author Tony Buzan
Research
On effectivness<br/>and features
On Automatic creation
Uses
Creative techniques
Strategic planning
Argument mapping
Tools
Pen and paper
Mermaid
[end]
The above produces this diagram…
mindmap
root((mindmap))
Origins
Long history
::icon(fa fa-book)
Popularisation
British popular psychology author Tony Buzan
Research
On effectivness<br/>and features
On Automatic creation
Uses
Creative techniques
Strategic planning
Argument mapping
Tools
Pen and paper
Mermaid
A quadrant chart…
[mermaid]
quadrantChart
title Reach and engagement of campaigns
x-axis Low Reach --> High Reach
y-axis Low Engagement --> High Engagement
quadrant-1 We should expand
quadrant-2 Need to promote
quadrant-3 Re-evaluate
quadrant-4 May be improved
Campaign A: [0.3, 0.6]
Campaign B: [0.45, 0.23]
Campaign C: [0.57, 0.69]
Campaign D: [0.78, 0.34]
Campaign E: [0.40, 0.34]
Campaign F: [0.35, 0.78]
[end]
The above produces this chart…
quadrantChart title Reach and engagement of campaigns x-axis Low Reach --> High Reach y-axis Low Engagement --> High Engagement quadrant-1 We should expand quadrant-2 Need to promote quadrant-3 Re-evaluate quadrant-4 May be improved Campaign A: [0.3, 0.6] Campaign B: [0.45, 0.23] Campaign C: [0.57, 0.69] Campaign D: [0.78, 0.34] Campaign E: [0.40, 0.34] Campaign F: [0.35, 0.78]
A timeline…
[mermaid]
timeline
title History of Social Media Platform
2002 : LinkedIn
2004 : Facebook
: Google
2005 : Youtube
2006 : Twitter
[end]
The above produces this diagram…
timeline
title History of Social Media Platform
2002 : LinkedIn
2004 : Facebook
: Google
2005 : Youtube
2006 : Twitter
A sankey diagram…
[mermaid]
sankey-beta
Agricultural 'waste',Bio-conversion,124.729
Bio-conversion,Liquid,0.597
Bio-conversion,Losses,26.862
Bio-conversion,Solid,280.322
Bio-conversion,Gas,81.144
Biofuel imports,Liquid,35
Biomass imports,Solid,35
Coal imports,Coal,11.606
Coal reserves,Coal,63.965
Coal,Solid,75.571
[end]
The above produces this diagram…
sankey-beta Agricultural 'waste',Bio-conversion,124.729 Bio-conversion,Liquid,0.597 Bio-conversion,Losses,26.862 Bio-conversion,Solid,280.322 Bio-conversion,Gas,81.144 Biofuel imports,Liquid,35 Biomass imports,Solid,35 Coal imports,Coal,11.606 Coal reserves,Coal,63.965 Coal,Solid,75.571
An X-Y chart…
[mermaid]
xychart-beta
title "Sales Revenue"
x-axis [jan, feb, mar, apr, may, jun, jul, aug, sep, oct, nov, dec]
y-axis "Revenue (in $)" 4000 --> 11000
bar [5000, 6000, 7500, 8200, 9500, 10500, 11000, 10200, 9200, 8500, 7000, 6000]
line [5000, 6000, 7500, 8200, 9500, 10500, 11000, 10200, 9200, 8500, 7000, 6000]
[end]
The above produces this chart…
xychart-beta title "Sales Revenue" x-axis [jan, feb, mar, apr, may, jun, jul, aug, sep, oct, nov, dec] y-axis "Revenue (in $)" 4000 --> 11000 bar [5000, 6000, 7500, 8200, 9500, 10500, 11000, 10200, 9200, 8500, 7000, 6000] line [5000, 6000, 7500, 8200, 9500, 10500, 11000, 10200, 9200, 8500, 7000, 6000]
A block diagram…
[mermaid]
block-beta
columns 1
db(("DB"))
blockArrowId6<[" "]>(down)
block:ID
A
B["A wide one in the middle"]
C
end
space
D
ID --> D
C --> D
style B fill:#969,stroke:#333,stroke-width:4px
[end]
The above produces this diagram…
block-beta
columns 1
db(("DB"))
blockArrowId6<[" "]>(down)
block:ID
A
B["A wide one in the middle"]
C
end
space
D
ID --> D
C --> D
style B fill:#969,stroke:#333,stroke-width:4px
In the upper-right corner of the chart,
you will see a magnifying glass icon.
Clicking on this icon will open a copy of the chart
in a new browser tab.
Try it now, using any of the charts above.
You can include links to Sage content
in Mermaid diagrams.
This can be useful to break a large diagram into
smaller pieces (which link to one another),
or to make a diagram that has links to other articles.
In a [mermaid] or [diagram] tag,
Sage links use the <<Sage:…>> syntax…
[mermaid]
flowchart LR
A(<<Sage:/DSUtilOverview|Utility>>) --> B(<<Sage:/VDB>>);
B --> C(<<Sage:/Ginkgo>>)
C --> D(<<Sage:/InstallDelphi|Delphi>>);
[end]
Above, there are four links, producing this diagram…
As this example shows, the optional link caption comes
after the link URL, separated by a pipe character.
Implicitly, these links correspond to the [link]
and [link/] tags.
To use [mlink], [ref],
and [mref] tags,
specify the tag name before the link itself, as follows…
[mermaid]
flowchart LR
A(<<Sage:/DSUtilOverview|Utility>>) --> B(<<Sage:/VDB>>);
B --> C(<<Sage:mlink:/Ginkgo>>)
C --> D(<<Sage:/InstallDelphi|Delphi>>);
[end]
The above produces this diagram…
Above, the link to Ginkgo uses [mlink] instead of
[link].
The full set of choices is: link, mlink, ref, and mref
(link is the default).
To summarize, the syntax is as follows…
Above, the optional <verb> is one of these:
link, mlink, ref, and mref;
the required <link> is the Sage link;
and the optional <caption> is the link caption.
flowchart LR A(<a href="../DSUtilOverview/">Utility</a>) --> B(<a href="../VDB/">VDB</a>); B --> C(<a href="../Ginkgo/">Ginkgo</a>) C --> D(<a href="../InstallDelphi/">Delphi</a>);
flowchart LR A(<a href="../DSUtilOverview/">Utility</a>) --> B(<a href="../VDB/">VDB</a>); B --> C(<tt><a href="../Ginkgo/" class="mlb">Ginkgo</a></tt>) C --> D(<a href="../InstallDelphi/">Delphi</a>);
<<Sage:[<verb>:]<link>[<caption>]>>
⏱ Last Modified: 1/6 11:08:10 am