Entity¶

Contents

Entity class
Types of entities

Entity class ¶

class Entity¶

The Entity is a class for JSON objects representing physical existences. It has two required properties, type and description.

type¶: a string object representing the type of this Entity instance. normally, here comes the name of the subclass that this entity belongs to.

description¶: a string description of this Entity instance.

In addition to the above required properties, an Entity instance can have the following optional property:

reference¶

an optional property consisting of a string or an array of [ string ], containing the URL(s) related to this Entity instance.

It can start with, for example: - https:// (in case the reference is a web page) - RRID: (in case it is a type of research material) - doi: (in case it is described elsewhere with a DOI)

Types of entities ¶

Depending on what dimension(s) it lives in, entities are categorized differently.

Note that, a class of an entity may be implied from the ontology of the type property.

Spatial entity ¶

The Spatial class is a subclass of Entity, and is used for entities that require some physical space.

You can check representative subclasses of Spatial: see Predefined subclasses for Spatial for details.

class Spatial¶

the root class of all the spatial existence classes.

type¶: a required string property inherited as an Entity instance.

description¶: a required string property inherited as an Entity instance.

parts¶: an optional property holding a Spatial or an array of them. This property is used to represent a “part-of” relationship between Spatial objects.

reference¶: an optional string or [ string ] property inherited as an Entity instance.

The nature of each Spatial entity is represented ontologically.

Temporal entity ¶

The Temporal is a subclass of Entity, and is used to represent a certain temporal event or phase.

You can check representative subclasses of Temporal: see Predefined subclasses for Temporal for details.

class Temporal¶

the root class of all the temporal existence classes.

type¶: a required string property inherited as an Entity instance. This field must hold "Temporal" or the name of one of its subclasses.

description¶: a required string property inherited as an Entity instance.

reference¶: an optional string or [ string ] property inherited as an Entity instance.

The nature of each Temporal entity is represented ontologically.

Signals ¶

The Signal is a subclass of Entity, and is used to represent a certain quality that goes between spatial entities.

An example entry for a Signal entity looks like below:

in: “acquisition.json”¶

{
    "type":          "Sampled",
    "role":          "indicator",
    "quality":       "calcium",
    "size":          {
        "shape":     [1],
    },
    "range":         { "type": "number" },
    "sampling-rate": {
        "type": "number",
        "precision": 3,
        "value":     "100",
        "unit":      "Hz"
    }
    "generated-by":  { "$ref": "setups.json#postdoc-room/components/probe" },
    "monitored-by":  { "$ref": "setups.json#postdoc-room/components/photodiode" },
    "description":   "the calcium signal read from the surface probe of the participant."
}

You can check representative subclasses of Signal: see Predefined subclasses for Signal for details.

class Signal¶

the root class of all the classes related to qualitative existence.

type¶: a required string property inherited as an Entity instance.

description¶: a required string property inherited as an Entity instance.

role¶

a required string property referring to what role it plays in the context of this physiology experiment.

Must be one of: "command", "indicator", "configuration".

quality¶

a required string property describing the physical quality that this signal is supposed to reflect.

The exact vocabulary shall be ontologically defined elsewhere, but possibly includes: "position", "voltage", "weight", "calcium".

generated-by: a required property that holds a Spatial entity, or a reference to it. If there are multiple entities, a list of Spatial entities may be used. This property indicates what spatial existence generates/emits this signal.

monitored-by: a required property that holds a Spatial entity, or a reference to it. If there are multiple entities, a list of Spatial entities may be used. This property indicates what spatial existence monitors/reads this signal.

range¶

a required object property to describe what algebraic values this Signal must hold.

For representing numeric definitions, you can use a JSON Schema-related representation such as { "type": "number", "minimum": 0.0 }.

If this Signal holds an enumerative values, you can give a mapping here e.g.

"range": {
    "high": {
        "description": "TTL-high"
    },
    "low": {
        "description": "TTL-low"
    }
}

reference¶: an optional string or [ string ] property inherited as an Entity instance.

The quality underlying each Signal entity is represented ontologically.

Programs and Routines ¶

A Routine class is capable of reading/holding/writing Signal, and of storing data in a certain format.

A Program controls one Routine or more, and it normally resides in a certain Spatial entity (e.g. a PC or a microcontroller) that in turn reads or writes Signal entities.

The format of data files is described using a DataFile instance.

An example Program entity would look like below:

in: “acquisition.json”¶

{
    "type":        "manual-operation",
    "description": "a post-hoc manual operation of behavioral states",

    "runs-on":  { "$ref": "setups.json#postdoc-room/components/PC" },
    "supplier": { "$ref": "organization.json#people/Keisuke" },
    "routines": {
        "annotation": {
            "reads": { "$ref": "../channels/video" },
            "generates": { "$ref": "../channels/behavioral-states" },
            "stores": {
                "anno": {
                    "data": { "$ref": "../channels/behavioral-states" },
                    "extension": ".csv",
                    "format": "text/csv"
                }
            }
        }
    }
}

class Program¶

The Program is a subclass of Entity, and is used to represent an algorithm for signal I/O and data storage.

type¶: a required string property inherited as an Entity instance. This property must hold "Program", or the name of one of its subclasses.

description¶: a required string property inherited as an Entity instance, describing the function of this program in the experiment.

runs-on

a required property that holds a Spatial entity. This represents the “hardware” part of the program.

For this Program to process a certain Signal, this Signal must be monitored / read by the Spatial entity that runs the Program.

routines¶: a required mapping from names to their corresponding Routine entities.

supplier¶

an optional property that holds an Individual entity, or a reference to it.

This property describes the “software” (algorithm) part of the program. Normally, this is the individual who developed the program. In cases where the program represents a sort of “manual” operations (e.g. manual annotation of behavioral states), the person who did the job will appear here.

If there are multiple suppliers, it can hold a list of them.

reference¶: an optional string or [ string ] property inherited as an Entity instance.

class Routine¶

The Routine is not a subclass of Entity. In fact, this class is rather like a small companion class for the sake of easier description of a Program entity.

Normally a Routine instance is defined inside a Program instance, and is never referred to from outside of it.

reads¶: a required property that holds a reference to a Signal instance this routine uses.

generates¶: a required property that holds a reference to a Signal instance this routine generates.

protocol¶: an optional ProtocolControl property representing, if exists, the protocol for stimulation.

stores¶: an optional mapping that maps the identifiers of the data files to the corresponding DataFile specifications that this routine generates.

class DataFile¶

another companion class for Program and Routine being used to describe a data file.

data¶: a required property that holds a Quality to be saved in this data file. If there are multiple of them, this property can hold all of them as a list.

extension¶: a required string property that holds the extension of the data file.

format¶: a required string representation of the format of the content of this data file. It is recommended that this property follows what is specified in Multipurpose Internet Mail Extension (MIME) types, but in cases where the format is binary and not specified there, you can use application/<your application name> instead.

Entity¶

Entity class¶

Types of entities¶

Spatial entity¶

Temporal entity¶

Signals¶

Programs and Routines¶