Protocols and their hierarchy
What Neurologyca publishes for your organization, what happens per person, and where microinterventions fit.
The hierarchy
Section titled “The hierarchy”Everything you capture hangs from a context that Neurologyca assigns to your organization. Inside it, a protocol says what is measured and when: an ordered list of positions, each one running a mechanic (the script of one capture) made of steps.
The catalogue
Published by Neurologyca. Immutable once published.
- Your organization
Your organization in Engine.
is assigned - Context
contextA use case. It decides which protocols you can enrol people in.
- not public Its rules may offer a mechanic as a microintervention after a capture.
- Protocol group
protocol_groupA family of protocols. It can be in several contexts.
groups - Protocol
protocolWhat is measured, and how often.
in order - Position
protocol_mechanicOne slot of the protocol: its order and its schedule (when it can be captured).
runs - Mechanic
mechanicThe script of one capture.
made of - Steps
stepEach with its
step_type, media and phases, plus the instructions.
Your data
Per person. You create it with the API.
- User
A person in your application.
- one per person Their baseline, shared by every protocol.
- Enrolment
userProtocolIdbelongs to a protocolA person in a protocol. The enrolment belongs to a protocol in the catalogue.
- Capture of a position belongs to a position
userProtocolId+protocolMechanicIdWhat the person does in a position. The capture belongs to a position of the protocol.
- optional Once it completes, Engine may raise: Interruption
interruptionIdmicrointervention capture
- optional Once it completes, Engine may raise: Interruption
- Results per step one per step
The indicators of each captured step. There is one result per step.
| Level (API name) | What it is | What it decides |
|---|---|---|
context |
A use case your organization has been given | Which protocols you can enrol people in, and whether captures can be interpreted |
protocol_group |
A family of protocols; it can belong to more than one context | What the interpretation focuses on |
protocol |
What is measured, and how often | Its positions, in order |
protocol_mechanic (a position) |
One slot of the protocol | When it can be captured: date, time of day and spacing |
mechanic |
The script of one capture | Its steps, fixed or free, and the screens shown between them |
step (step_type) |
One stimulus or task | Its type, suggested duration and what is shown |
The whitepaper calls the mechanic a mechanism; the API says mechanic. You see a protocol if any of the contexts of its group is assigned to your organization. A protocol made for a single organization is seen and enrolled only by that one: for any other, it does not exist (404).
If no context fits
Section titled “If no context fits”Your organization sees the contexts Neurologyca assigns to it, and the catalogue keeps growing. If none fits your case, you can commission one; to measure without a context, use Measurement.
Commission a context
If none fits, Neurologyca can build one for your case. Tell us what you want to understand, in which situation, and who the reading is for. Then:
- We start from the published literature on the topic and from what the capture can actually measure.
- We design the protocol and decide who the reading is for, and review it all with you.
- We assign it to your organization, and you integrate it like any other.
Always within responsible use: the reading is meant to support the person and must never be used on its own to decide about them.
Request a context at support@neurologyca.com, or talk to your Neurologyca contact.
Context Maker In development
A tool we are developing to create a context from your case. You will describe your case in your own words and it will propose a context: what to measure, how to ask the person and who to write the reading for, starting from the published literature on the topic and from what the capture can measure.
If part of what you are after cannot be measured yet, it will tell you so and suggest what you can measure instead.
You will also be able to ask Neurologyca to go over the proposal with you. A proposal does not create a context by itself: Neurologyca assigns it, like any other.
Catalogue and per person
Section titled “Catalogue and per person”| Neurologyca publishes it (catalogue) | Happens per person (execution) |
|---|---|
| Context, protocol group, protocol, position, mechanic, step, media, instruction | User, baseline, enrolment, the capture of a position, its results |
| The mechanics a context may offer as microinterventions (the rules that offer them are not public) | An interruption (an offer that happened, anchored to the capture that triggered it) and its microintervention capture |
You define nothing in the catalogue: you read it with GET /catalog/* and enrol people in it.
A protocol at a glance
Section titled “A protocol at a glance”A synthetic example with three positions and one microintervention. Open a position to see its steps. Signed in with a team, you can switch it to one of your organization’s protocols: DevLab reads it from your catalogue, without creating users.
Measurement, as Engine returns it
Section titled “Measurement, as Engine returns it”The Measurement protocol, from GET /user-protocols/{userProtocolId}/schema: one position, one step, any time.
What you see in the API
Section titled “What you see in the API”| You want to know | Call |
|---|---|
| Your contexts and protocols | GET /catalog/contexts, GET /catalog/protocols |
| The positions of an enrolment and which one is next | GET /user-protocols/{userProtocolId} |
| The whole protocol, with schedules and scripts | GET /user-protocols/{userProtocolId}/schema |
| The script of one position | GET /user-protocols/{userProtocolId}/mechanics/{protocolMechanicId} |
{ "order": 1, "mechanic": { "name": "Measurement", "flowMode": "fixed", "steps": [ { "order": 1, "type": "measurement_free", "minTimeSeconds": 6, "maxTimeSeconds": null, "optional": false } ] }}Reading the catalogue
Section titled “Reading the catalogue”Your backend reads the catalogue with your key (the browser SDK never calls these routes). Each one returns only what is assigned to your organization, ordered by id.
| Route | Returns |
|---|---|
GET /catalog/contexts |
The contexts assigned to your organization: the themes that group your protocols |
GET /catalog/protocol_group |
The protocol groups of your contexts, plus the group of the baseline protocol, which everyone has. That group arrives with interpreted: true today, but you enrol nobody in it and it is not interpreted by itself (see Baseline) |
GET /catalog/protocols |
The protocols you can enrol people in; hasSchedule: true means it can only start at its first position, and interpreted: false that POST /analyze answers 409 PROTOCOL_NOT_ANALYSED (as with Measurement). Baseline is listed too, with interpreted: true, but you do not enrol people in it |
GET /catalog/protocol_mechanic |
The positions of each protocol (which mechanic, in which order) with their three clocks |
GET /catalog/mechanics |
The mechanics of your protocols and the microinterventions your contexts can offer, each with constellationSubcontextId (its analysis subcontext, or null) |
GET /catalog/mechanics/{pid} |
One mechanic with its full script, for a microintervention your own app decides to offer |
GET /catalog/mechanic_step |
Which step type, in which order, makes up each mechanic |
GET /catalog/step_types |
The step types, with minTimeSeconds and maxTimeSeconds: the two ends of each response window. Several can share a type: current: true marks the one in use |
GET /catalog/media |
The texts, images and videos of those step types |
GET /catalog/step_type_media |
Which media goes with each step type |
@neurologyca/capture-server reads six of them at once with listProtocolLibrary().
Positions and their clocks
Section titled “Positions and their clocks”A position can declare three independent clocks; it is available where they overlap:
- Date: a day counted from the first completed capture of the protocol (or a weekday), with a tolerance before and after. Once that window closes, the position is lost.
- Time of day: windows in the person’s local time zone (the user’s
timezone; without one, a default of the environment). - Spacing (
timeBetweenSessionsSeconds): a minimum time since the previous capture. When clocks are enforced, Engine also keeps a minimum spacing between two captures of the same protocol, even when a position declares none; that minimum is a setting of the environment.
A protocol with hasSchedule: true declares a date or a time-of-day window for at least one position, and must be started at position 1. Spacing does not set hasSchedule and does not force the order. Engine declares these clocks and checks them when a capture is opened; whether a failed check rejects the capture or is only logged depends on the environment. Sessions, enrolments and interruptions shows the answers.
Steps, media and instructions
Section titled “Steps, media and instructions”minTimeSecondsandmaxTimeSecondsare guidance for your interface: Engine does not enforce them, and they are oftennull.presentationSeconds, when present, says how long the step’s question is meant to be shown; the visualizer prints it as «shown N s». It is guidance too: the SDK gives it to you (PlanStep.presentationSeconds) and does not apply it.media[]lists what can be shown in a step. When you show one, send itspidasmediaIdwith that step’s batches.instructions[]are screens that are shown but not measured:beforeStep(withstep) oratEnd.- An
optionalstep may be skipped. A cyclic step (rounds,phases) is still one capture. targetConstellationHciIdnames what the interpretation looks at in that step. The SDK gives it the same name,PlanStep.targetConstellationHciId.
Microinterventions
Section titled “Microinterventions”A context may also define short mechanics that Engine can offer after a completed capture, such as a breathing exercise. They are not positions of your protocol: the offer arrives as an interruption of the capture that triggered it. See Sessions, enrolments and interruptions.
Versions
Section titled “Versions”Published protocols never change: an edit creates a new version. An archived protocol can still be enrolled, with a protocolNotice that points to its replacement; a deprecated one accepts no new enrolments or captures.