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)

/ 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 two optional arguments to set the type used for the attributes, and 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

The type used for the attributes should be a NamedTuple-alike or a Dict-alike type. Here is a more in-depth recommendation, use:

NamedTuple if you don't plan to modify the attributes of the MTG, e.g. to use them for plotting or computing statistics...
MutableNamedTuple if you plan to modify the attributes values but not adding new attributes very often, e.g. recompute an attribute value...
Dict or similar (e.g. OrderedDict) if you plan to heavily modify the attributes, e.g. adding/removing attributes a lot

Note

If you don't know what to use, just 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_uxOPqXIfyb

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.