From ea022bf5b783d81a393a44e4e3af81d664f27ffe Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fran=C3=A7ois=20Laurent?= <francois.laurent@posteo.net> Date: Mon, 6 Feb 2023 23:50:34 +0100 Subject: [PATCH] clearer doc about labels arrays --- README.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 4c42527..f574a8c 100644 --- a/README.md +++ b/README.md @@ -194,13 +194,14 @@ Time series of behavior tags are stored in *json* files as in the following exam The `metadata`->`id` element gives a text identifier for the run/assay. Appart from this `id` element, none of the above-mentioned elements in object `metadata` is standard. -The `data` array lists the different moving objects (larvae) with their `id` (as a string) and time series of timestamps (float array `t`) and associated label specifications (object `labels`). +The `data` array lists the different moving objects (larvae) with their `id` (as a string) and time series of timestamps (float array `t`) and associated label specifications (array `labels`). -The top-level `labels` element can an object, with label names listed in child element `names`, or an array that lists names just like `names` does in the above example. +The top-level `labels` element can be an object, with the different label names listed in child element `names`. Alternatively, the top-level `labels` element can be an array that lists label names just like `labels`->`names` does in the above example. +The simpler array form is preferred for element `labels` when no additional information (such as `colors`) needs to be stored. -The `labels` elements in `data` are arrays with as many elements as in sibling `t`. Each element in `labels` can be a name (string), a list of names (possibly empty array of strings) or encoded as an index (integer) or indices (array of integers) in the top-level `labels` or `labels`->`names` array. +The `labels` elements in `data` are arrays with as many elements as in sibling `t`. Each element in `labels` can be a name (string) or a list of names (possibly empty array of strings). -Encoded labels start from index `1`. In the above example, `1` refers to `"run"`, `2` to `"bend"`, etc. +Alternatively, labels can be integer-encoded so that each element in `labels` is either an index (integer) or indices (possibly empty array of integers). Indices point to array elements in the top-level `labels` or `labels`->`names` array. Encoded labels start from index `1`. In the above example, `1` refers to `"run"`, `2` to `"bend"`, etc. This format is inspired by the [WCON](https://github.com/openworm/tracker-commons/blob/master/discuss/Formats.md#json-as-a-candidate-format=) proposal. Such a file can be made WCON-compliant prefixing occurences of `labels`, `secondarylabels` and `dependencies` by `@`. In addition, `x` and `y` should be added to `units` (with associated text units) and to every objects in `data` (with associated numeric data). -- GitLab