../../Rtrack_website/vignettes/Rtrack_json_schema.Rmd
Rtrack_json_schema.RmdIn 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.
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.
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 JSON schema can be found at https://rupertoverall.net/Rtrack/Rtrack_schema_v1.json. It is also presented below:
{
"definitions": {},
"$schema": "http://json-schema.org/draft-07/schema#",
"$id": "https://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": [
"https://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 https://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
https://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 https://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_]*$"
}
}
}
}
}
}The metrics calculated by Rtrack are also contained in
the rtrack_experiment object, but are not exported to the
JSON file.↩︎
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.↩︎