Getting started

Introduction

This page let's you take a peek at what the package is capable of. If you want a better, more in-depth introduction to the package, take a look at the tutorials, starting from Read and Write MTGs. If you don't know what an MTG is, you can read more about starting from The MTG concept.

If your main goal is to query trees (children, descendants, ancestors, filters), go directly to Traversal, descendants, ancestors and filters.

Installation

You must have a working Julia installation on your computer. The version of Julia should be greater than 1.3.

If you want to install Julia for the first time, you can download it frome julialang.org. If you want a little introduction on Julia + VSCode, you can check out this video.

You can install the latest stable version of MultiScaleTreeGraph.jl using this command:

]add MultiScaleTreeGraph

Note

The ] is used to enter the package mode in the REPL.

Example

Read a simple MTG file:

using MultiScaleTreeGraph

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

Then you can compute new variables in the MTG using transform!:

transform!(mtg, :Length => (x -> isnothing(x) ? nothing : x * 1000.) => :length_mm)

The design of transform! is heavily inspired from the eponym function from tabular workflows (notably DataFrames.jl), with little tweaks for MTGs.

You can see the newly-computed attributes using descendants like so:

descendants(mtg, :length_mm)

6-element Vector{Any}:
    nothing
    nothing
 100.0
 200.0
 100.0
 200.0

Or by getting a tabular view of your MTG:

to_table(mtg)

Symbols: Scene  Individual  Axis  Internode  Leaf
Scales:  0      1           2     3          3   
                           Attributes Table (7 x 12)
╭───┬─────────┬────────────┬───────┬───────┬────────┬───────────┬───────────┬───
│   │ node_id │     symbol │ scale │ index │   link │ parent_id │ length_mm │  ⋯
│   │   Int64 │     Symbol │ Int64 │ Int64 │ Symbol │    Int64? │       Any │  ⋯
├───┼─────────┼────────────┼───────┼───────┼────────┼───────────┼───────────┼───
│ 1 │       1 │      Scene │     0 │     0 │      / │   missing │   missing │  ⋯
│ 2 │       2 │ Individual │     1 │     0 │      / │         1 │   missing │  ⋯
│ 3 │       3 │       Axis │     2 │     0 │      / │         2 │   missing │  ⋯
│ 4 │       4 │  Internode │     3 │     0 │      / │         3 │     100.0 │  ⋯
│ 5 │       5 │       Leaf │     3 │     0 │      + │         4 │     200.0 │  ⋯
│ 6 │       6 │  Internode │     3 │     1 │      < │         4 │     100.0 │  ⋯
│ 7 │       7 │       Leaf │     3 │     0 │      + │         6 │     200.0 │  ⋯
╰───┴─────────┴────────────┴───────┴───────┴────────┴───────────┴───────────┴───
                                                               5 columns omitted

You can also select only a subset of attributes:

to_table(mtg, vars=[:Length, :Width])

Symbols: Scene  Individual  Axis  Internode  Leaf
Scales:  0      1           2     3          3   
                            Attributes Table (7 x 8)
╭───┬─────────┬────────────┬───────┬───────┬────────┬───────────┬──────────┬────
│   │ node_id │     symbol │ scale │ index │   link │ parent_id │   Length │   ⋯
│   │   Int64 │     Symbol │ Int64 │ Int64 │ Symbol │    Int64? │ Float64? │ F ⋯
├───┼─────────┼────────────┼───────┼───────┼────────┼───────────┼──────────┼────
│ 1 │       1 │      Scene │     0 │     0 │      / │   missing │  missing │   ⋯
│ 2 │       2 │ Individual │     1 │     0 │      / │         1 │  missing │   ⋯
│ 3 │       3 │       Axis │     2 │     0 │      / │         2 │  missing │   ⋯
│ 4 │       4 │  Internode │     3 │     0 │      / │         3 │      0.1 │   ⋯
│ 5 │       5 │       Leaf │     3 │     0 │      + │         4 │      0.2 │   ⋯
│ 6 │       6 │  Internode │     3 │     1 │      < │         4 │      0.1 │   ⋯
│ 7 │       7 │       Leaf │     3 │     0 │      + │         6 │      0.2 │   ⋯
╰───┴─────────┴────────────┴───────┴───────┴────────┴───────────┴──────────┴────
                                                                1 column omitted

Or directly transforming the MTG into a DataFrame:

using DataFrames
DataFrame(mtg)

Then you can write the MTG back to disk like so:

write_mtg("test.mtg",mtg)

You can also convert your MTG to a MetaGraph:

MetaGraph(mtg)

Meta graph based on a Graphs.SimpleGraphs.SimpleDiGraph{Int64} with vertex labels of type Int64, vertex metadata of type MultiScaleTreeGraph.ColumnarAttrs, edge metadata of type Symbol, graph metadata given by "MTG", and default weight 1.0

Next step: traversal tutorial

If you are new to MTGs or graph vocabulary, this is usually the best next page:

Traversal, descendants, ancestors and filters

It explains these words in plain language and gives practical query recipes.