Read and Write MTGs

Read

Reading a file

Reading an MTG is done using the read_mtg function:

file = joinpath(dirname(dirname(pathof(MultiScaleTreeGraph))),"test","files","simple_plant.mtg")

mtg = read_mtg(file)

Symbols: Scene  Individual  Axis  Internode  Leaf
Scales:  0      1           2     3          3   
/ 1: Scene
└─ / 2: Individual
   └─ / 3: Axis
      └─ / 4: Internode
         ├─ + 5: Leaf
         └─ < 6: Internode
            └─ + 7: Leaf

The file given in input can be either a .mtg, .csv, .xlsx or .xlsm file.

The function has one optional argument to set the type used for the MTG field (see next section for more details). It also has a keyword argument to choose the sheet name in case you're reading an xlsx or xlsm file.

Attributes type

Attributes are stored using the columnar backend (ColumnarAttrs) by default.

This backend keeps one typed table per symbol and is optimized for repeated traversal and attribute retrieval. In practice:

users can still create nodes with Dict/NamedTuple-like attribute inputs;
those inputs are converted to the columnar representation when nodes are attached to an MTG.

So for most workflows, there is no extra option to choose here: use the default.

MTG encoding type

The MTG encoding type can be either immutable or mutable. By default we use a mutable one (MutableNodeMTG), but you can use the immutable one by setting the mtg_type argument of the function to NodeMTG. If you're planning on modifying the MTG encoding of some of your nodes, you should use MutableNodeMTG, and if you don't want to modify anything, use NodeMTG instead as it should be faster.

Note

Again, if you don't know what to use, use the default.

Sheet name

If you're reading your MTG from a .xlsx or .xlsm file, you can choose the sheet you want to read by using the keyword argument sheet_name.

If you don't provide anything for the sheet name, it will read the first one by default.

Note

Keyword arguments must be explicitly named in the function call. In this case it would be:

file = joinpath(dirname(dirname(pathof(MultiScaleTreeGraph))),"test","files","tree3h.xlsx")
mtg = read_mtg(file, sheet_name = "A3H")

Write

Writing an MTG back to disk is as simple as this:

temporary_file = tempname() # using a temporary file here, but you should put the path to the file you want to write

write_mtg(temporary_file, mtg)

[ Info: Writing mtg to /tmp/jl_8PG5S781gP

Build manually

It is also possible to build an MTG from scratch using MultiScaleTreeGraph.jl. It is explained in a further tutorial Make an MTG manually.