MiRA/data-format.html at main · Ecological-Complexity-Lab/MiRA · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Multilayer network JSON and CSV format | MiRA Multilayer Network Visualization</title>
  <meta name="description"
    content="The multilayer network data format MiRA reads: the JSON schema (layers, nodes, extended edge list, state nodes) and the CSV import layout, with worked examples for bipartite, spatial, and temporal networks.">
  <link rel="canonical" href="https://mira.ecomplab.com/data-format.html">
  <link rel="icon" type="image/svg+xml" href="assets/favicon.svg">
  <meta property="og:type" content="article">
  <meta property="og:site_name" content="MiRA — Multilayer Network Visualization">
  <meta property="og:title" content="Multilayer network JSON and CSV format">
  <meta property="og:description" content="The JSON schema and CSV import layout MiRA uses for multilayer networks.">
  <meta property="og:url" content="https://mira.ecomplab.com/data-format.html">
  <meta property="og:image" content="https://mira.ecomplab.com/assets/social-card.png">
  <meta name="twitter:card" content="summary_large_image">
  <meta name="twitter:title" content="Multilayer network JSON and CSV format">
  <meta name="twitter:description" content="The JSON schema and CSV import layout MiRA uses for multilayer networks.">
  <meta name="twitter:image" content="https://mira.ecomplab.com/assets/social-card.png">
  <link rel="stylesheet" href="css/content.css">
</head>
<body>
  <header class="topbar">
    <div class="inner">
      <a href="index.html"><img src="assets/MiRA_logo.svg" alt="MiRA — Multilayer Interactive Rendering Application"></a>
      <nav>
        <a href="index.html">App</a>
        <a href="docs/manual.html">Manual</a>
        <a href="data-format.html">Data format</a>
        <a href="about.html">About</a>
        <a href="https://github.com/Ecological-Complexity-Lab/MiRA">GitHub</a>
        <a href="https://arxiv.org/abs/2605.09597">Preprint</a>
      </nav>
    </div>
  </header>

  <div class="wrap">
    <p class="crumbs"><a href="index.html">MiRA</a> › Data format</p>

    <h1>The multilayer network data format MiRA reads</h1>
    <p class="lead">
      MiRA reads a multilayer network as either a single <strong>JSON</strong> file or a set of
      <strong>CSV</strong> files. Both describe the same thing: layers, nodes, an edge list that
      holds intralayer and interlayer links together, and the (layer, node) pairs that make up the
      network. This page is the quick reference; the <a href="docs/manual.html#data-import">manual</a>
      has the exhaustive version.
    </p>

    <h2>How do I format a multilayer network as JSON for MiRA?</h2>
    <p>
      A MiRA JSON file has four arrays — <code>layers</code>, <code>nodes</code>,
      <code>extended</code> (the edge list), and <code>state_nodes</code> — plus global flags.
      An edge is classified as intralayer when <code>layer_from</code> equals <code>layer_to</code>,
      and interlayer otherwise.
    </p>
    <pre><code>{
  "directed": false,
  "directed_interlayer": false,
  "layers": [
    { "layer_id": 1, "layer_name": "Forest",
      "latitude": 42.3, "longitude": 3.1,
      "bipartite": true, "setA_type": "pollinator" }
  ],
  "nodes": [
    { "node_id": "sp_1", "node_name": "Bee", "node_type": "pollinator" }
  ],
  "extended": [
    { "layer_from": "Forest", "node_from": "Bee",
      "layer_to": "Forest", "node_to": "Flower", "weight": 1.5 }
  ],
  "state_nodes": [
    { "layer_name": "Forest", "node_name": "Bee" }
  ]
}</code></pre>

    <h3>Field reference</h3>
    <ul>
      <li><code>directed</code> <em>(Boolean)</em> — marks intralayer edges as directed (draws
        arrowheads). Setting it <code>true</code> also forces <code>directed_interlayer</code> true.
        Default <code>false</code>.</li>
      <li><code>directed_interlayer</code> <em>(Boolean, optional)</em> — treats interlayer edges as
        directed even when the network is otherwise undirected (useful for temporal networks where
        direction encodes time, e.g. year <em>t</em> → <em>t</em>+1).</li>
      <li><code>layers[]</code> — <code>layer_id</code>, <code>layer_name</code>; optional
        <code>latitude</code>/<code>longitude</code> (unlock <a href="tutorial-spatial-map.html">Map
        Mode</a>); optional <code>bipartite</code> and <code>setA_type</code> (see below). Extra
        fields become color/size attributes.</li>
      <li><code>nodes[]</code> — <code>node_id</code>, <code>node_name</code>; <code>node_type</code>
        is required for bipartite layers. Extra fields become <em>physical</em> attributes (constant
        across layers).</li>
      <li><code>extended[]</code> — <code>layer_from</code>, <code>node_from</code>,
        <code>layer_to</code>, <code>node_to</code> (required); optional <code>weight</code> (line
        width + threshold filter) and per-edge <code>directed</code>.</li>
      <li><code>state_nodes[]</code> — <code>layer_name</code>, <code>node_name</code> for every
        (layer, node) pair present. Extra fields become <em>per-layer</em> (state) attributes that
        can differ for the same node across layers (e.g. <code>abundance</code>,
        <code>module</code>).</li>
    </ul>

    <div class="callout">
      <strong>Bipartite is never auto-detected.</strong> Mark a layer with
      <code>"bipartite": true</code> and give its nodes a <code>node_type</code> with exactly two
      distinct values <em>within that layer</em>. Use <code>setA_type</code> to pin which type is
      drawn on top (by ecological convention the higher trophic level — pollinator, parasite,
      disperser). Different layers may pair different node types (diagonal coupling), so more than
      two <code>node_type</code> values globally is fine.
    </div>

    <h2>How do I import a multilayer network from CSV into MiRA?</h2>
    <p>
      The CSV importer accepts up to four files. Only the edge list is required; the other three add
      attributes. Comma, tab, and semicolon delimiters are auto-detected.
    </p>
    <ul>
      <li><strong>Extended edge list</strong> (required) — <code>layer_from</code>,
        <code>node_from</code>, <code>layer_to</code>, <code>node_to</code>, optional
        <code>weight</code>. Intralayer and interlayer links share this one file.</li>
      <li><strong>Layer attributes</strong> (optional) — <code>layer_id</code>,
        <code>layer_name</code>, <code>latitude</code>, <code>longitude</code>,
        <code>bipartite</code> (TRUE/FALSE), <code>setA_type</code>, plus any extra layer columns.</li>
      <li><strong>Node attributes</strong> (optional) — <code>node_name</code> (required),
        <code>node_type</code> (required when any layer is bipartite), plus physical attributes
        constant across layers (e.g. <code>body_mass</code>, <code>guild</code>).</li>
      <li><strong>State-node attributes</strong> (optional) — <code>layer_name</code>,
        <code>node_name</code>, plus per-layer attributes that vary across layers (e.g.
        <code>abundance</code>, <code>module</code>).</li>
    </ul>

    <h3>Worked example — edge list</h3>
    <pre><code>layer_from,node_from,layer_to,node_to,weight
1982,Apodemus_agrarius,1982,Ixodes_ricinus,1
1982,Apodemus_peninsulae,1982,Ixodes_ricinus,1
1983,Apodemus_agrarius,1983,Ixodes_ricinus,1</code></pre>
    <p>
      The (layer, node) pairs are derived automatically from the edge list — you never list them by
      hand. See the <a href="docs/manual.html#import-csv">manual</a> for the full four-file example
      with per-layer abundance.
    </p>

    <div class="callout">
      <strong>From R:</strong> the <a href="https://emln.ecomplab.com">emln</a>
      package writes both formats directly — <code>multilayer_to_json(net, bipartite = TRUE)</code>
      and <code>multilayer_to_csv(net, path = "my_network/")</code> — or plots straight into MiRA
      with <code>plot_multilayer()</code>.
    </div>

    <footer class="site">
      MiRA (Multilayer Interactive Rendering Application) —
      <a href="index.html">app</a> ·
      <a href="docs/manual.html">manual</a> ·
      <a href="about.html">tool comparison</a> ·
      <a href="https://arxiv.org/abs/2605.09597">preprint</a>
    </footer>
  </div>
</body>
</html>