Skip to content

Commit e7d9761

Browse files
authored
Merge pull request #16 from gdalle/gdalle
Restructure package and documentation to make it more user- and developer-friendly
2 parents 9aeca07 + 917dc57 commit e7d9761

14 files changed

+733
-682
lines changed

README.md

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,4 +3,8 @@
33
[![Dev](https://img.shields.io/badge/docs-dev-blue.svg)](https://JuliaGraphs.github.io/MetaGraphsNext.jl/dev)
44
[![CodeCov](https://codecov.io/gh/JuliaGraphs/MetaGraphsNext.jl/branch/master/graph/badge.svg)](https://codecov.io/gh/JuliaGraphs/MetaGraphsNext.jl)
55

6-
This is an experimental, type-stable replacement for [MetaGraphs](https://github.com/JuliaGraphs/MetaGraphs.jl)
6+
Welcome to `MetaGraphsNext.jl`, an experimental, type-stable replacement for [MetaGraphs](https://github.com/JuliaGraphs/MetaGraphs.jl).
7+
8+
## Getting started
9+
10+
To see how the package works, take a look at the tutorial in the [documentation](https://juliagraphs.org/MetaGraphsNext.jl/dev/). We first explain [the basics](tutorial_basics.md) of the `MetaGraph` structure, before moving on to its [integration](tutorial_lightgraphs.md) with `LightGraphs.jl`.

docs/make.jl

Lines changed: 21 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,24 @@
1-
using MetaGraphsNext
21
using Documenter: deploydocs, makedocs
2+
using MetaGraphsNext
3+
4+
makedocs(
5+
sitename = "MetaGraphsNext.jl",
6+
modules = [MetaGraphsNext],
7+
doctest = true,
8+
format = Documenter.HTML(;
9+
prettyurls = get(ENV, "CI", "false") == "true",
10+
canonical = "https://juliagraphs.org/MetaGraphsNext.jl/dev/",
11+
assets = String[],
12+
),
13+
pages = [
14+
"Home" => "index.md",
15+
"Tutorial" => [
16+
"Basics" => "tutorial_basics.md",
17+
"LightGraphs.jl interface" => "tutorial_lightgraphs.md",
18+
"Reading / writing" => "tutorial_files.md",
19+
],
20+
"API reference" => "api.md",
21+
]
22+
)
323

4-
makedocs(sitename = "MetaGraphsNext.jl", modules = [MetaGraphsNext], doctest = false)
524
deploydocs(repo = "github.com/JuliaGraphs/MetaGraphsNext.jl.git")

docs/src/api.md

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
# API reference
2+
3+
## Basics
4+
5+
```@autodocs
6+
Modules = [MetaGraphsNext]
7+
Pages = ["metagraph.jl"]
8+
```
9+
10+
```@autodocs
11+
Modules = [MetaGraphsNext]
12+
Pages = ["metaundigraph.jl", "metadigraph.jl"]
13+
```
14+
15+
```@autodocs
16+
Modules = [MetaGraphsNext]
17+
Pages = ["dict_utils.jl"]
18+
```
19+
20+
```@autodocs
21+
Modules = [MetaGraphsNext]
22+
Pages = ["weights.jl"]
23+
```
24+
25+
## LightGraphs.jl interface
26+
27+
```@autodocs
28+
Modules = [MetaGraphsNext]
29+
Pages = ["lightgraphs.jl"]
30+
```
31+
32+
```@autodocs
33+
Modules = [MetaGraphsNext]
34+
Pages = ["overrides.jl"]
35+
```
36+
37+
## Reading / writing
38+
39+
```@autodocs
40+
Modules = [MetaGraphsNext]
41+
Pages = ["persistence.jl"]
42+
```

docs/src/index.md

Lines changed: 8 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,13 @@
11
# MetaGraphsNext.jl
22

3-
```@index
4-
Modules = [MetaGraphsNext]
5-
```
3+
Welcome to `MetaGraphsNext.jl`, an experimental, type-stable replacement for [MetaGraphs](https://github.com/JuliaGraphs/MetaGraphs.jl).
4+
5+
## Getting started
66

7-
```@autodocs
7+
To see how the package works, take a look at the tutorial. We first explain [the basics](tutorial_basics.md) of the `MetaGraph` structure, before moving on to its [integration](tutorial_lightgraphs.md) with `LightGraphs.jl`.
8+
9+
## Index
10+
11+
```@index
812
Modules = [MetaGraphsNext]
913
```

docs/src/tutorial_basics.md

Lines changed: 137 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,137 @@
1+
# Working with metagraphs
2+
3+
```jldoctest example
4+
julia> using LightGraphs
5+
6+
julia> using MetaGraphsNext
7+
```
8+
9+
## Creating a `MetaGraph`
10+
11+
We provide a default constructor in which you only need to specify types:
12+
13+
```jldoctest example
14+
julia> colors = MetaGraph(Graph(), VertexMeta = String, EdgeMeta = Symbol, gprops = "special")
15+
Meta graph based on a {0, 0} undirected simple Int64 graph with vertices indexed by Symbol(s), String(s) vertex metadata, Symbol(s) edge metadata, "special" as graph metadata, and default weight 1.0
16+
```
17+
18+
## Adding and modifying vertices
19+
20+
Use `setindex!` (as you would do with a dictionary) to add a new vertex with the given metadata. If a vertex with the given label does not exist, it will be created automatically. Otherwise, `setindex!` will modify the metadata for the existing vertex.
21+
22+
```jldoctest example
23+
julia> colors[:red] = "warm";
24+
25+
julia> colors[:yellow] = "warm";
26+
27+
julia> colors[:blue] = "cool";
28+
```
29+
30+
## Using vertex codes
31+
32+
In the absence of removal, vertex codes correspond to order of insertion in the underlying graph:
33+
34+
```jldoctest example
35+
julia> code_for(colors, :red)
36+
1
37+
38+
julia> code_for(colors, :blue)
39+
3
40+
```
41+
42+
You can retrieve the associated labels as follows:
43+
44+
```jldoctest example
45+
julia> label_for(colors, 1)
46+
:red
47+
48+
julia> label_for(colors, 3)
49+
:blue
50+
```
51+
52+
## Accessing metadata
53+
54+
You can access and change the metadata using indexing: zero arguments for graph metadata, one label for vertex metadata, and two labels for edge metadata.
55+
56+
```jldoctest example
57+
julia> colors[]
58+
"special"
59+
60+
julia> colors[:blue] = "very cool";
61+
62+
julia> colors[:blue]
63+
"very cool"
64+
65+
julia> colors[:red, :yellow] = :orange;
66+
67+
julia> colors[:red, :yellow]
68+
:orange
69+
```
70+
71+
Checking the presence of a vertex or edge can be done with `haskey`:
72+
73+
```jldoctest example
74+
julia> haskey(colors, :red)
75+
true
76+
77+
julia> haskey(colors, :green)
78+
false
79+
80+
julia> haskey(colors, :red, :yellow)
81+
true
82+
83+
julia> haskey(colors, :yellow, :red) # undirected graph, so vertex order doesn't matter
84+
true
85+
86+
julia> haskey(colors, :red, :green)
87+
false
88+
```
89+
90+
## Deleting vertices and edges
91+
92+
You can delete vertices and edges with `delete!`.
93+
94+
```jldoctest example
95+
julia> delete!(colors, :red, :yellow);
96+
97+
julia> delete!(colors, :blue);
98+
```
99+
100+
## Adding weights
101+
102+
The most simple way to add edge weights is to speficy a default weight for all of them.
103+
104+
```jldoctest example
105+
julia> defaultweight(MetaGraph(Graph(), defaultweight = 2))
106+
2
107+
108+
julia> weighttype(MetaGraph(Graph(), defaultweight = 2))
109+
Int64
110+
```
111+
112+
You can use the `weightfunction` keyword to specify a function which will
113+
transform edge metadata into a weight. This weight must always be the same
114+
type as the `defaultweight`.
115+
116+
```jldoctest example
117+
julia> weighted = MetaGraph(Graph(), EdgeMeta = Float64, weightfunction = identity);
118+
119+
julia> weighted[:red] = nothing; weighted[:blue] = nothing; weighted[:yellow] = nothing;
120+
121+
julia> weighted[:red, :blue] = 1.0; weighted[:blue, :yellow] = 2.0;
122+
123+
julia> the_weights = LightGraphs.weights(weighted)
124+
metaweights
125+
126+
julia> size(the_weights)
127+
(3, 3)
128+
129+
julia> the_weights[1, 3]
130+
1.0
131+
132+
julia> diameter(weighted)
133+
3.0
134+
135+
julia> weightfunction(weighted)(0)
136+
0
137+
```

docs/src/tutorial_files.md

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
# Read / write
2+
3+
```jldoctest readwrite
4+
julia> using LightGraphs
5+
6+
julia> using MetaGraphsNext
7+
```
8+
9+
## DOTFormat
10+
11+
```jldoctest readwrite
12+
julia> simple = MetaGraph(Graph());
13+
14+
julia> simple[:a] = nothing; simple[:b] = nothing; simple[:a, :b] = nothing;
15+
16+
julia> mktemp() do file, io
17+
savegraph(file, simple, DOTFormat())
18+
print(read(file, String))
19+
end
20+
graph T {
21+
a
22+
b
23+
a -- b
24+
}
25+
26+
julia> complicated = MetaGraph(DiGraph(),
27+
VertexMeta = Dict{Symbol, Int},
28+
EdgeMeta = Dict{Symbol, Int},
29+
gprops = (tagged = true,)
30+
);
31+
32+
julia> complicated[:a] = Dict(:code_1 => 1, :code_2 => 2);
33+
34+
julia> complicated[:b] = Dict(:code => 2);
35+
36+
julia> complicated[:a, :b] = Dict(:code => 12);
37+
38+
julia> mktemp() do file, io
39+
savegraph(file, complicated, DOTFormat())
40+
print(read(file, String))
41+
end
42+
digraph G {
43+
tagged = true
44+
a [code_1 = 1, code_2 = 2]
45+
b [code = 2]
46+
a -> b [code = 12]
47+
}
48+
```
49+
50+
## MGFormat
51+
52+
```jldoctest readwrite
53+
julia> example = MetaGraph(Graph());
54+
55+
julia> mktemp() do file, io
56+
savegraph(file, example)
57+
loadgraph(file, "something", MGFormat()) == example
58+
end
59+
true
60+
```

0 commit comments

Comments
 (0)