7  From mrdi Files to Zenodo: Invariants of Phylogenetic Models

Authors
Affiliations

Leopold Mareis

Technical University of Munich

Antony Della Vecchia

TU Berlin

Resource Information
Data algebraicphylogenetics.org (database version 0.3)
Git + DOI Git      DOI
Short Description This notebook demonstrates a reproducible research data workflow with the .mrdi file format: it (i) downloads group-based phylogenetic models from the algebraic phylogenetics database, (ii) computes invariants of their vanishing ideals in OSCAR that the database does not provide, and (iii) saves the results as .mrdi and publishes them on Zenodo.

7.1 Introduction

The .mrdi file format serializes mathematical objects together with their type information, so that a file loads directly into a computer algebra system as a ready-to-use object (Della Vecchia, Joswig, and Lorenz 2024). The algebraic phylogenetics database (The algebraic-phylogenetics collaboration 2026; Bacher et al. 2025) uses this format to distribute phylogenetic models on small trees and networks, including their parametrizations and vanishing ideals, for the Julia package OSCAR (Decker et al. 2025).

Della Vecchia, Antony, Michael Joswig, and Benjamin Lorenz. 2024. “A FAIR File Format for Mathematical Software.” In Mathematical Software – ICMS 2024, 14749:234–44. Lecture Notes in Computer Science. Springer. https://doi.org/10.1007/978-3-031-64529-7_25.
Bacher, Tabea, Marina Garrote-López, Christiane Görgen, and Marius J. Neubert. 2025. “Making Mathematical Online Resources FAIR: At the Example of Small Phylogenetic Trees.” https://arxiv.org/abs/2501.10823.
Decker, Wolfram, Christian Eder, Claus Fieker, Max Horn, and Michael Joswig, eds. 2025. The Computer Algebra System OSCAR: Algorithms and Examples. Vol. 32. Algorithms and Computation in Mathematics. Springer. https://doi.org/10.1007/978-3-031-62127-7.

In this notebook, we use such files as the starting point of a small computational study and close the loop to a published dataset. For every model of the Cavender–Farris–Neyman (CFN) and Jukes–Cantor (JC) type, we

  • load the model from its .mrdi file,
  • compute the degrees of a minimal generating set and the \(h\)-vector of the Hilbert series of its vanishing ideal,
  • save the results again as an .mrdi file, and
  • upload results, notebook and Julia environment to Zenodo, which assigns a DOI.

7.2 Setting up the Julia Environment

The phylogenetic model type SmallGroupBasedModel is not yet part of an OSCAR release. The files Project.toml and Manifest.toml in this repository therefore pin the development branch of OSCAR that can read the database files, together with HTTP and JSON3 for the web requests. The first instantiation downloads and precompiles all packages, which takes several minutes.

import Pkg
Pkg.activate(".")
Pkg.instantiate()

using Oscar # computer algebra and .mrdi (de)serialization
using HTTP  # download from the database, requests to Zenodo
using JSON3 # read and write Zenodo's JSON messages

The following settings collect everything that a reader may want to change. The Zenodo access token is read from a file outside the repository, so it is never committed or uploaded. Without this file, the notebook performs all computations and skips the upload.

const SITE       = "https://algebraicphylogenetics.org"
const MODELS     = ["CFN", "JC"]                    # "K2P" and "K3P" are much slower
const ZENODO     = "https://sandbox.zenodo.org/api" # real Zenodo: https://zenodo.org/api
const TOKEN_FILE = "../all_token.txt"               # needs deposit:write and deposit:actions
const OUTFILE    = "generator_degrees.mrdi"
const CSVFILE    = "generator_degrees.csv"

7.3 Loading the Data

The database lists every model on its landing page and stores the corresponding .mrdi files under a fixed path. We collect all model identifiers of the selected types from the page, download the missing files into the folder data/ and load them with OSCAR’s generic load function.

index = String(HTTP.get(SITE).body)
pattern = r"SmallGroupBasedModel_([\d-]+-([A-Z0-9]+))\.mrdi"
ids = sort(unique(String(m[1]) for m in eachmatch(pattern, index) if m[2] in MODELS))

mkpath("data")
models = map(ids) do id
  file = "SmallGroupBasedModel_$id.mrdi"
  path = joinpath("data", file)
  url  = "$SITE/static/data/SmallGroupBasedModels/$file"
  isfile(path) || write(path, HTTP.get(url).body)
  load(path)
end
ids
12-element Vector{String}:
 "3-0-0-0-0-0-0-CFN"
 "3-0-0-0-0-0-0-JC"
 "4-0-0-0-0-0-0-CFN"
 "4-0-0-0-0-0-0-JC"
 "4-0-0-0-0-1-0-CFN"
 "4-0-0-0-0-1-0-JC"
 "5-0-0-0-0-0-0-CFN"
 "5-0-0-0-0-0-0-JC"
 "5-0-0-0-0-1-0-CFN"
 "5-0-0-0-0-1-0-JC"
 "5-0-0-0-0-2-0-CFN"
 "5-0-0-0-0-2-0-JC"

Each identifier encodes the tree, starting with its number of leaves, followed by the model type. The database version 0.3 contains the following six trees:

3 leaves, star (binary)

4 leaves, star

4 leaves, binary

5 leaves, star

5 leaves, non-binary

5 leaves, binary

7.4 Group-Based Models and their Vanishing Ideals

A phylogenetic model describes how a DNA site evolves along the edges of a tree: each edge carries a transition matrix between the states, and the joint distribution of the states at the \(n\) leaves is a polynomial function of the matrix entries. In group-based models, the states are identified with the elements of an abelian group \(G\), which is \(\mathbb{Z}_2\) for the two-state CFN model and \(\mathbb{Z}_2 \times \mathbb{Z}_2\) for the four-state JC model on the nucleotides. After a discrete Fourier transform, the parametrization becomes monomial in the so-called Fourier coordinates \(q_{g_1 \dots g_n}\), indexed by group elements at the leaves. The vanishing ideal \(I\) collects all polynomial relations among the Fourier coordinates that hold for every choice of parameters. Its elements are known as phylogenetic invariants, and since the parametrization is monomial, \(I\) is a toric ideal generated by binomials (Sturmfels and Sullivant 2005).

We inspect the CFN model on the binary tree with four leaves.

model = models[findfirst(==("4-0-0-0-0-1-0-CFN"), ids)]
vanishing_ideal(model)
Ideal generated by
  -q[2,2,2,2]*q[1,1,1,1] + q[2,2,1,1]*q[1,1,2,2]
  -q[2,1,2,1]*q[1,2,1,2] + q[2,1,1,2]*q[1,2,2,1]

Both generators are quadratic binomials in eight Fourier coordinates. The database further records the dimension and the degree of the model.

(model.dimension, model.degree)
(6, 4)

7.5 Computing New Invariants

The database stores a generating set of the vanishing ideal, but this set is in general not minimal and its degrees depend on how it was computed. We compute two invariants of the ideal that do not depend on such choices.

Degrees of minimal generators. Every minimal generating set of a homogeneous ideal has the same number of generators in each degree. The largest such degree tells us which polynomials suffice to describe the model. Sturmfels and Sullivant (2005) proved that the ideals of the CFN model on trees are generated in degree two and conjectured that the degree of a group-based model is at most \(|G|\) in general.

Stanley, Richard P. 1978. “Hilbert Functions of Graded Algebras.” Advances in Mathematics 28 (1): 57–83. https://doi.org/10.1016/0001-8708(78)90045-2.

The \(h\)-vector. The Hilbert series of the coordinate ring \(\mathbb{Q}[q]/I\) counts the linearly independent polynomials of each degree modulo \(I\). It is a rational function \[H(t) = \frac{h_0 + h_1 t + \dots + h_s t^s}{(1-t)^d},\] where \(d\) is the Krull dimension and \(h(1) = h_0 + \dots + h_s\) is the degree of the model. This yields a free consistency check against the database. The \(h\)-vector \((h_0, \dots, h_s)\) carries further structural information: for Cohen–Macaulay domains, it is palindromic if and only if the ring is Gorenstein (Stanley 1978). Buczyńska and Wiśniewski (2007) showed that binary CFN trees give Gorenstein rings.

The function analyse computes both invariants. Since the database stores the ideal in an ungraded polynomial ring, we first pass to the standard grading, in which every Fourier coordinate has degree one.

function analyse(model)
  I = vanishing_ideal(model)
  S, _ = grade(base_ring(I))
  J = ideal(S, S.(gens(I)))

  # the Hilbert series has to be computed before the minimal generators,
  # the reverse order fails in the current development version of OSCAR
  A, _ = quo(S, J)
  h = Int.(collect(coefficients(hilbert_series_reduced(A)[1])))
  @assert (dim(A), sum(h)) == (model.dimension, model.degree) "mismatch with the database"
  degs = degree.(Int, minimal_generating_set(J))

  return Dict{String, Any}(
    "dimension"             => model.dimension,
    "degree"                => model.degree,
    "n_stored_generators"   => ngens(I),
    "n_min_generators"      => length(degs),
    "max_generator_degree"  => maximum(degs; init = 0),
    "generators_per_degree" => [count(==(k), degs) for k in 1:maximum(degs; init = 0)],
    "h_vector"              => h,
    "h_vector_palindromic"  => h == reverse(h))
end
analyse(model)
Dict{String, Any} with 8 entries:
  "h_vector"              => [1, 2, 1]
  "n_stored_generators"   => 2
  "h_vector_palindromic"  => true
  "dimension"             => 6
  "degree"                => 4
  "n_min_generators"      => 2
  "max_generator_degree"  => 2
  "generators_per_degree" => [0, 2]

The two stored generators are already minimal. The \(h\)-vector \((1, 2, 1)\) is palindromic and sums to the degree four of the model. We now analyse all models.

results = @time Dict(id => analyse(m) for (id, m) in zip(ids, models));
  0.799629 seconds (3.77 M allocations: 77.202 MiB, 10.38% compilation time)
Invariants of the vanishing ideals; dimension and degree agree with the database.
tree model dim. deg. stored gens. minimal gens. minimal gens. per degree h-vector palindromic
3 leaves, star (binary) CFN 4 1 1 0 () (1) yes
3 leaves, star (binary) JC 4 3 1 1 (0, 0, 1) (1, 1, 1) yes
4 leaves, star CFN 5 8 3 3 (0, 3) (1, 3, 3, 1) yes
4 leaves, star JC 5 20 28 21 (0, 17, 4) (1, 7, 11, 1) no
4 leaves, binary CFN 6 4 2 2 (0, 2) (1, 2, 1) yes
4 leaves, binary JC 6 34 35 33 (0, 10, 23) (1, 7, 18, 7, 1) yes
5 leaves, star CFN 6 52 37 30 (0, 30) (1, 10, 25, 16) no
5 leaves, star JC 6 115 235 175 (0, 165, 10) (1, 21, 66, 26, 1) no
5 leaves, non-binary CFN 7 44 28 24 (0, 24) (1, 9, 21, 13) no
5 leaves, non-binary JC 7 315 360 272 (0, 175, 97) (1, 24, 125, 131, 33, 1) no
5 leaves, binary CFN 8 34 20 20 (0, 20) (1, 8, 16, 8, 1) yes
5 leaves, binary JC 8 813 589 512 (0, 154, 358) (1, 26, 197, 365, 197, 26, 1) yes

The table reveals three observations. First, the stored generating sets are frequently far from minimal: for the JC model on the non-binary tree with five leaves, 272 of 360 stored generators suffice, and the stored set contains polynomials up to degree five although degree three is enough. Second, all CFN ideals are generated in degree two, in line with Sturmfels and Sullivant (2005), and all JC ideals in degree at most three, below the conjectured bound \(|\mathbb{Z}_2 \times \mathbb{Z}_2| = 4\). Third, the \(h\)-vector is palindromic for every binary tree, in line with Buczyńska and Wiśniewski (2007) for the CFN model, while among the non-binary trees only the CFN model on the star tree with four leaves has a palindromic \(h\)-vector.

Sturmfels, Bernd, and Seth Sullivant. 2005. “Toric Ideals of Phylogenetic Invariants.” Journal of Computational Biology 12 (2): 204–28. https://doi.org/10.1089/cmb.2005.12.204.
Buczyńska, Weronika, and Jarosław A. Wiśniewski. 2007. “On the Geometry of Binary Symmetric Models of Phylogenetic Trees.” Journal of the European Mathematical Society 9 (3): 609–35. https://doi.org/10.4171/JEMS/90.

7.6 Saving the Results as mrdi

The function save serializes the results, here a dictionary of dictionaries, into an .mrdi file. Loading the file returns an equal object, which any OSCAR user can process further without parsing. A CSV file offers the same table for other software.

save(OUTFILE, results)
load(OUTFILE) == results
true
cols = ["dimension", "degree", "n_stored_generators", "n_min_generators",
        "max_generator_degree", "generators_per_degree", "h_vector", "h_vector_palindromic"]
open(CSVFILE, "w") do io
  println(io, join(["model"; cols], ";"))
  foreach(id -> println(io, join([id; [string(results[id][c]) for c in cols]], ";")), ids)
end

7.7 Publishing on Zenodo

Zenodo’s REST API publishes a record in four steps: we create an empty deposition, upload the files into its storage bucket, attach the metadata and publish. Next to the results, we upload this notebook and the Julia environment so that the computation can be reproduced exactly. The metadata reference the database as the source of the data.

metadata = Dict(
  "title"       => "Generator degrees and h-vectors of small group-based phylogenetic models",
  "upload_type" => "dataset",
  "description" => """
    <p>Degrees of minimal generators and h-vectors of the vanishing ideals
    (in Fourier coordinates) of the $(join(MODELS, " and ")) models on all trees of the algebraic phylogenetics database
    (algebraicphylogenetics.org, version 0.3).</p>
    <p>The results are stored in <code>$OUTFILE</code> (load with <code>Oscar.load</code>) and
    <code>$CSVFILE</code>. They were computed with OSCAR $(pkgversion(Oscar))
    and Julia $(VERSION) by the attached notebook.</p>""",
  "creators"    => [Dict("name" => "Mareis, Leopold", "orcid" => "0000-0002-2624-6522"),
                    Dict("name" => "Della Vecchia, Antony", "orcid" => "0009-0008-1179-9862")],
  "license"     => "cc-by-4.0",
  "keywords"    => ["algebraic phylogenetics", "toric ideals", "group-based models",
                    "OSCAR", "mrdi"],
  "related_identifiers" => [Dict("identifier" => SITE, "relation" => "isDerivedFrom",
                                 "resource_type" => "dataset")])
if isfile(TOKEN_FILE)
  auth = ["Authorization" => "Bearer " * strip(read(TOKEN_FILE, String))]
  json = [auth; "Content-Type" => "application/json"]
  bin  = [auth; "Content-Type" => "application/octet-stream"]

  dep = JSON3.read(HTTP.post("$ZENODO/deposit/depositions", json, "{}").body)
  for file in [OUTFILE, CSVFILE, "notebook.qmd", "Project.toml", "Manifest.toml"]
    HTTP.put("$(dep.links.bucket)/$file", bin, read(file))
  end
  HTTP.put(dep.links.self, json, JSON3.write(Dict("metadata" => metadata)))
  record = JSON3.read(HTTP.post(dep.links.publish, auth).body)

  println("Published ", replace(ZENODO, "/api" => ""), "/records/", record.id,
          " with DOI ", record.doi)
else
  println("No token found at $TOKEN_FILE, the upload is skipped.")
end
Published https://sandbox.zenodo.org/records/637359 with DOI 10.5072/zenodo.637359

On the sandbox, records are only for testing and their DOIs do not resolve. Once the workflow is final, setting ZENODO to the real Zenodo API and using a token from zenodo.org publishes a permanent record. Publishing is irreversible; later corrections become new versions of the record under a common concept DOI.

Citing this Notebook

Please cite our community with the following bib item.

@article{Mareis_Haug_Drton_2025,
title={MaRDI's Zenodo Community for Graphical Modeling and Causal Inference},
volume={2},
journal={Proceedings of the Conference on Research Data Infrastructure},
author={Mareis, Leopold and Haug, Stephan and Drton, Mathias},
year={2025},
month={Sep.}
}

When using the phylogenetic models, please give credit to the algebraic phylogenetics database: The algebraic-phylogenetics collaboration (2026).

The algebraic-phylogenetics collaboration. 2026. “A Database of Small Trees and Networks in Algebraic Phylogenetics.” 2026. https://www.algebraicphylogenetics.org.

Additional Information

License Information: Please follow the above links for license information of data and code.

Contact: If you have suggestions, feel free to create an issue or contact the authors.