The Rtrack JSON schema

In order to archive raw tracking data in a way that it can be shared with other researchers and with other software, it is necessary to establish a standardised data format. We have opted to use JSON—a simple and widely-used format suited to the storage of list-type data.

More information about JSON can be found at https://www.json.org/.

This document describes the standardised JSON format and presents the formal schema.

A shareable format for water maze data

The complete raw data describing an experiment is bundled by Rtrack into an rtrack_experiment object1. This object contains all of the raw tracking data, arena descriptions and any user-defined factors. Exporting to a JSON archive file (using the function export_json) will package all of the core information in the rtrack_experiment object into a single JSON file. This file can be archived, submitted as supplementary materials for a publication or shared with colleagues. The function read_experiment will read such files and completely recreate the rtrack_experiment object for further analysis in R. Because the read_experiment function also accepts URLs, an experiment can even be loaded directly from a JSON archive hosted on a remote server.

A standardised format for water maze data

Because the JSON standard is not bound to a particular software or programming language2, it can easily be read by other software and can be readily shared with colleagues who might not (for whatever reason!) use R. In addition, because it is plain text, it is fully compatible with version control platforms and can be searched for metadata keywords if necessary.

The formal schema

The formal JSON schema can be found at http://rupertoverall.net/Rtrack/Rtrack_schema_v1.json. It is also presented below:

{
  "definitions": {},
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "http://rupertoverall.net/Rtrack/Rtrack_schema_v1.json",
  "type": "object",
  "title": "Rtrack",
  "required": [
    "schema",
    "info",
    "data"
  ],
  "properties": {
    "schema": {
      "$id": "#/properties/schema",
      "description": "This is the schema against which the current document should be 
            validated.",
      "type": "string",
      "title": "Rtrack schema version",
      "default": "",
      "examples": [
        "http://rupertoverall.net/Rtrack/Rtrack_schema_v1.json"
      ],
      "pattern": "^(.*)$"
    },
    "info": {
      "$id": "#/properties/info",
      "type": "object",
      "title": "Experiment information",
      "default": null,
      "properties": {
        "author.note": {
          "$id": "#/properties/info/properties/author.note",
          "description": "Authors can add experiment information and accreditation in 
                this field.",
          "type": "string",
          "title": "Optional note from data authors.",
          "default": "",
          "pattern": "^(.*)$"
        },
        "processing.note": {
          "$id": "#/properties/info/properties/processing.note",
          "description": "This field should include date, software, version and other 
                information about the processing and can be populated by the processing 
                software.",
          "type": "string",
          "title": "Note generated at processing.",
          "default": "",
          "pattern": "^(.*)$"
        },
        "export.note": {
          "$id": "#/properties/info/properties/export.note",
          "description": "This field should include date, software, version and other 
                information about the export to JSON and can be populated by the exporting 
                software.",
          "type": "string",
          "title": "Note generated on export",
          "default": "",
          "pattern": "^(.*)$"
        }
      }
    },
    "data": {
      "$id": "#/properties/data",
      "type": "array",
      "title": "Track data",
      "default": null,
      "items": {
        "$id": "#/properties/data/items",
        "type": "object",
        "title": "",
        "default": null,
        "required": [
          "id",
          "target",
          "day",
          "trial",
          "arena_name",
          "raw.t",
          "raw.x",
          "raw.y",
          "t",
          "x",
          "y",
          "arena"
        ],
        "properties": {
          "id": {
            "$id": "#/properties/data/items/properties/id",
            "description": "A unique identifier for each track. Note the restrictions on 
                the characters allowed (must start with a letter, only alphanumeric and 
                underscore allowed for the remainder).",
            "type": "string",
            "title": "Track identifier",
            "default": "",
            "examples": [
              "Track_1"
            ],
            "pattern": "^[a-zA-Z][a-zA-Z0-9_]*$"
          },
          "target": {
            "$id": "#/properties/data/items/properties/target",
            "description": "",
            "type": "string",
            "title": "Target identifier",
            "default": "",
            "pattern": "^(.*)$"
          },
          "day": {
            "$id": "#/properties/data/items/properties/day",
            "description": "The day of the trial as ordinal numbers starting from 1 
                (e.g. the first day is 1, second is 2 etc.). If all trials are done on 
                the same day, then this field is still required (all values can just be 
                set to 1).",
            "type": "string",
            "title": "Day number",
            "default": "",
            "examples": [
              "1"
            ],
            "pattern": "^([1-9]([0-9])*)$"
          },
          "trial": {
            "$id": "#/properties/data/items/properties/trial",
            "description": "The trial number. Starting at 1 (first trial), this can be 
                numbered consecutively, or start at 1 again each day.",
            "type": "string",
            "title": "Trial number",
            "default": null,
            "examples": [
              "1"
            ],
            "pattern": "^([1-9]([0-9])*)$"
          },
          "arena_name": {
            "$id": "#/properties/data/items/properties/arena_name",
            "description": "",
            "type": "string",
            "title": "Arena identifier",
            "default": "",
            "examples": [
              "Arena_SW.txt"
            ],
            "pattern": "^(.*)$"
          },
          "raw.t": {
            "$id": "#/properties/data/items/properties/raw.t",
            "description": "",
            "type": "string",
            "title": "Original timestamps",
            "default": "",
            "examples": [
              "0,0.08,0.16"
            ],
            "pattern": "^([0-9\\.,\\-]*)$"
          },
          "raw.x": {
            "$id": "#/properties/data/items/properties/raw.x",
            "description": "",
            "type": "string",
            "title": "Original x coordinates",
            "default": "",
            "examples": [
              "220.9763,220.2634,219.907"
            ],
            "pattern": "^([0-9\\.,\\-]*)$"
          },
          "raw.y": {
            "$id": "#/properties/data/items/properties/raw.y",
            "description": "",
            "type": "string",
            "title": "Original y coordinates",
            "default": "",
            "examples": [
              "140.4269,141.4961,142.2089"
            ],
            "pattern": "^([0-9\\.,\\-]*)$"
          },
          "t": {
            "$id": "#/properties/data/items/properties/t",
            "description": "",
            "type": "string",
            "title": "Normalised and interpolated timestamp",
            "default": "",
            "examples": [
              "0,0.0006667,0.001333"
            ],
            "pattern": "^([0-9\\.,\\-]*)$"
          },
          "x": {
            "$id": "#/properties/data/items/properties/x",
            "description": "",
            "type": "string",
            "title": "Normalised and interpolated x coordinates",
            "default": "",
            "examples": [
              "0.9192,0.9117,0.9079"
            ],
            "pattern": "^([0-9\\.,\\-]*)$"
          },
          "y": {
            "$id": "#/properties/data/items/properties/y",
            "description": "",
            "type": "string",
            "title": "Normalised and interpolated y coordinates",
            "default": "",
            "examples": [
              "0.3883,0.3996,0.4071"
            ],
            "pattern": "^([0-9\\.,\\-]*)$"
          },
          "arena": {
            "$id": "#/properties/data/items/properties/arena",
            "type": "object",
            "title": "Arena description",
            "required": [
              "type",
              "trial.length",
              "arena.bounds"
            ],
            "properties": {
              "type": {
                "$id": "#/properties/data/items/properties/arena/properties/type",
                "description": "",
                "type": "string",
                "title": "Arena type",
                "default": "",
                "examples": [
                  "mwm"
                ],
                "pattern": "^(.*)$"
              },
              "trial.length": {
                "$id": "#/properties/data/items/properties/arena/properties/trial.length",
                "description": "",
                "type": "string",
                "title": "Trial length",
                "default": "",
                "examples": [
                  "120"
                ],
                "pattern": "^([0-9]*)$"
              },
              "pool": {
                "$id": "#/properties/data/items/properties/arena/properties/arena.bounds",
                "description": "A description of the bounds of the arena. See the 
                    documentation at http://rupertoverall.net/Rtrack for details on how 
                    these strings are constructed.",
                "type": "string",
                "title": "Arena bounds description",
                "default": "",
                "examples": [
                  "circle 133.655 103.5381 95"
                ],
                "pattern": "^(.*)$"
              },
              "goal": {
                "$id": "#/properties/data/items/properties/arena/properties/goal",
                "description": "A description of the goal. See the documentation at
                    http://rupertoverall.net/Rtrack for details on how these strings are 
                    constructed.",
                "type": "string",
                "title": "Goal description",
                "default": "",
                "examples": [
                  "circle 121.8934 154.6834 10"
                ],
                "pattern": "^(.*)$"
              },
              "old.goal": {
                "$id": "#/properties/data/items/properties/arena/properties/old.goal",
                "description": "A description of the old (previous) goal. See the 
                    documentation at http://rupertoverall.net/Rtrack for details on how 
                    these strings are constructed.",
                "type": "string",
                "title": "Old goal description",
                "default": "",
                "examples": [
                  "circle 121.8934 154.6834 10"
                ],
                "pattern": "^(.*)$"
              }
            }
          },
          "factor": {
            "$id": "#/properties/data/items/properties/factor",
            "description": "An optional factor associated with the track. As many 
                'factor' elements as desired may be added, but all factors must be 
                associated with all tracks. Factor names must start with 'factor_' and 
                only alphanumeric and underscore are allowed for the remainder.",
            "type": "string",
            "title": "Optional additional factor",
            "default": "",
            "examples": [
              "factor_Sex"
            ],
            "pattern": "^(factor_)[a-zA-Z0-9_]*$"
          }
        }
      }
    }
  }
}

  1. The metrics calculated by Rtrack are also contained in the rtrack_experiment object, but are not exported to the JSON file.

  2. Don’t let the name fool you; although the ‘JavaScript Object Notation’ was indeed originally designed to be a part of JavaScript, it has been widely adopted since the early 2000s and is supported by most software environments. See https://en.wikipedia.org/wiki/JSON for some background information.