DistanceMatrix

https://schemas.wur.nl/betula/distance-matrix/0.6.0/schema.json

A pairwise distance matrix, shared by react-bio-viz and acacia (via @holmrenser/nj’s DistanceResult). Squareness, symmetry, and a zero diagonal are semantic constraints, not checked structurally by this schema.

Field	Type	Required	Description
`type`	`"distance-matrix"`	optional	Wire-format object-kind discriminator (see betula’s versioning policy). Optional.
`labels`	array of Identifier	required
`matrix`	array of array of `number` (≥ 0)	required
`labelNames`	object of `string`	optional	Optional display-name lookup from label to a longer/human-readable name.

No properties beyond those listed are allowed.

Valid examples¶

simple.json

{
  "type": "distance-matrix",
  "labels": ["A", "B", "C"],
  "matrix": [
    [0, 0.1, 0.3],
    [0.1, 0, 0.25],
    [0.3, 0.25, 0]
  ]
}

Invalid examples¶

missing-matrix.json

{
  "labels": ["A", "B", "C"]
}

negative-value.json

{
  "labels": ["A", "B"],
  "matrix": [
    [0, -0.1],
    [-0.1, 0]
  ]
}

wrong-type-const.json

{
  "type": "tree",
  "labels": ["A", "B"],
  "matrix": [
    [0, 0.1],
    [0.1, 0]
  ]
}

distance-matrix.schema.json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://schemas.wur.nl/betula/distance-matrix/0.6.0/schema.json",
  "title": "DistanceMatrix",
  "description": "A pairwise distance matrix, shared by react-bio-viz and acacia (via @holmrenser/nj's DistanceResult). Squareness, symmetry, and a zero diagonal are semantic constraints, not checked structurally by this schema.",
  "type": "object",
  "properties": {
    "type": {
      "const": "distance-matrix",
      "description": "Wire-format object-kind discriminator (see betula's versioning policy). Optional."
    },
    "labels": {
      "type": "array",
      "items": { "$ref": "https://schemas.wur.nl/betula/core/identifier/0.6.0/schema.json" },
      "minItems": 1
    },
    "matrix": {
      "type": "array",
      "items": {
        "type": "array",
        "items": { "type": "number", "minimum": 0 }
      }
    },
    "labelNames": {
      "type": "object",
      "description": "Optional display-name lookup from label to a longer/human-readable name.",
      "additionalProperties": { "type": "string" }
    }
  },
  "required": ["labels", "matrix"],
  "additionalProperties": false
}

Usage¶

Read a JSON document and parse it as a DistanceMatrix. CI runs this exact code against the first valid example above; see Getting started to install the bindings.

Python

TypeScript

Rust

distance-matrix.py

from betula_schema import DistanceMatrix, parse_json

with open("distance-matrix.json") as f:
    distance_matrix = parse_json(DistanceMatrix, f.read())
print(distance_matrix)

distance-matrix.ts

import { readFileSync } from "node:fs";
import { parseJson, type DistanceMatrix } from "betula-schema";

const distanceMatrix: DistanceMatrix = parseJson("DistanceMatrix", readFileSync("distance-matrix.json", "utf8"));
console.log(distanceMatrix);

distance-matrix.rs

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let text = std::fs::read_to_string("distance-matrix.json")?;
    let distance_matrix: betula_schema::DistanceMatrix = betula_schema::parse_str(&text)?;
    println!("{distance_matrix:?}");
    Ok(())
}