Ir al contenido
DevLab

Protocolos y su jerarquía

Qué publica Neurologyca para tu organización, qué ocurre por persona y dónde encajan las microintervenciones.

En esta página
  1. La jerarquía
  2. Si ningún contexto encaja
  3. Catálogo y por persona
  4. Un protocolo de un vistazo
  5. Measurement, tal como lo devuelve Engine
  6. Qué ves en la API
  7. Leer el catálogo
  8. Las posiciones y sus relojes
  9. Steps, media e instrucciones
  10. Microintervenciones
  11. Versiones

Todo lo que capturas cuelga de un contexto que Neurologyca asigna a tu organización. Dentro de él, un protocolo dice qué se mide y cuándo: una lista ordenada de posiciones, y cada una ejecuta una mecánica (el guion de una captura) hecha de steps.

La jerarquía en dos columnas: el catálogo que publica Neurologyca y tus datos por persona.

El catálogo

Lo publica Neurologyca. Inmutable una vez publicado.

  1. Tu organización

    Tu organización en Engine.

    tiene asignado
  2. Contexto context

    Un caso de uso. Decide en qué protocolos puedes inscribir.

    • no públicas Sus reglas pueden ofrecer una mecánica como microintervención tras una captura.
    comparte
  3. Grupo de protocolos protocol_group

    Una familia de protocolos. Puede estar en varios contextos.

    agrupa
  4. Protocolo protocol

    Qué se mide y con qué frecuencia.

    en orden
  5. Posición protocol_mechanic

    Un hueco del protocolo: su orden y sus relojes (cuándo se puede capturar).

    ejecuta
  6. Mecánica mechanic

    El guion de una captura.

    hecha de
  7. Steps step

    Cada uno con su step_type, media y fases, más las instrucciones.

Tus datos

Por persona. Lo creas tú con la API.

  1. Usuario

    Una persona de tu aplicación.

    • uno por persona Su baseline, común a todos los protocolos.
  2. Inscripción userProtocolId es de un protocolo

    Una persona en un protocolo. La inscripción es de un protocolo del catálogo.

  3. Captura de una posición es de una posición
    userProtocolId + protocolMechanicId

    Lo que la persona hace en una posición. La captura es de una posición del protocolo.

    • opcional Al completarse, Engine puede lanzar: Interrupción interruptionIdcaptura de la microintervención
  4. Resultados por step uno por step

    Los indicadores de cada step capturado. Hay un resultado por cada step.

Nivel (nombre en la API) Qué es Qué decide
context Un caso de uso asignado a tu organización En qué protocolos puedes inscribir a las personas, y si las capturas se pueden interpretar
protocol_group Una familia de protocolos; puede estar en más de un contexto En qué se fija la interpretación
protocol Qué se mide y con qué frecuencia Sus posiciones, en orden
protocol_mechanic (una posición) Un hueco del protocolo Cuándo se puede capturar: fecha, franja horaria y separación
mechanic El guion de una captura Sus steps, fijos o libres, y las pantallas que se muestran entre ellos
step (step_type) Un estímulo o una tarea Su tipo, la duración sugerida y lo que se muestra

El whitepaper llama a la mecánica mechanism; la API dice mechanic. Ves un protocolo si alguno de los contextos de su grupo está asignado a tu organización. Un protocolo hecho para una sola organización solo lo ve e inscribe esa: para cualquier otra no existe (404).

Tu organización ve los contextos que Neurologyca le asigna, y el catálogo crece. Si ninguno encaja con tu caso, puedes encargar uno; para medir sin contexto, usa Measurement.

Encarga un contexto

Si ninguno encaja, Neurologyca puede crear uno para tu caso. Cuéntanos qué quieres entender, en qué situación y para quién es la lectura. A partir de ahí:

  1. Partimos de la literatura publicada sobre el tema y de lo que la captura puede medir de verdad.
  2. Diseñamos el protocolo y decidimos a quién va dirigida la lectura, y lo revisamos todo contigo.
  3. Lo asignamos a tu organización y lo integras como cualquier otro.

Siempre dentro del uso responsable: la lectura está pensada para acompañar a la persona y nunca debe usarse por sí sola para decidir sobre ella.

Pedir un contexto a support@neurologyca.com, o habla con tu contacto en Neurologyca.

Context Maker En desarrollo

Una herramienta que estamos desarrollando para crear un contexto a partir de tu caso. Contarás tu caso con tus palabras y te propondrá un contexto: qué medir, cómo pedírselo a la persona y para quién escribir la lectura, partiendo de la literatura publicada sobre el tema y de lo que la captura puede medir.

Si algo de lo que buscas todavía no se puede medir, te lo dirá y te propondrá qué puedes medir en su lugar.

También podrás pedir a Neurologyca que repase la propuesta contigo. Una propuesta no crea un contexto por sí sola: Neurologyca lo asigna, como cualquier otro.

Lo publica Neurologyca (catálogo) Ocurre por persona (ejecución)
Contexto, grupo de protocolos, protocolo, posición, mecánica, step, media, instrucción Usuario, baseline, inscripción, la captura de una posición, sus resultados
Las mecánicas que un contexto puede ofrecer como microintervenciones (las reglas que las ofrecen no son públicas) Una interrupción (una oferta que ocurrió, anclada a la captura que la disparó) y la captura de su microintervención

Del catálogo no defines nada: lo lees con GET /catalog/* e inscribes a las personas en él.

Un ejemplo sintético con tres posiciones y una microintervención. Abre una posición para ver sus steps. Si has iniciado sesión con un equipo, puedes cambiarlo por uno de los protocolos de tu organización: DevLab lo lee de tu catálogo, sin crear usuarios.

El protocolo Measurement, desde GET /user-protocols/{userProtocolId}/schema: una posición, un step, en cualquier momento.

Quieres saber Llamada
Tus contextos y protocolos GET /catalog/contexts, GET /catalog/protocols
Las posiciones de una inscripción y cuál toca GET /user-protocols/{userProtocolId}
El protocolo entero, con relojes y guiones GET /user-protocols/{userProtocolId}/schema
El guion de una posición GET /user-protocols/{userProtocolId}/mechanics/{protocolMechanicId}
JSON
{
"order": 1,
"mechanic": {
"name": "Measurement",
"flowMode": "fixed",
"steps": [
{
"order": 1,
"type": "measurement_free",
"minTimeSeconds": 6,
"maxTimeSeconds": null,
"optional": false
}
]
}
}

Tu backend lee el catálogo con tu key (el SDK de navegador nunca llama a estas rutas). Cada una devuelve solo lo asignado a tu organización, ordenado por id.

Ruta Devuelve
GET /catalog/contexts Los contextos asignados a tu organización: los temas que agrupan tus protocolos
GET /catalog/protocol_group Los grupos de protocolos de tus contextos, más el grupo del protocolo de baseline, que tienen todos. Ese grupo llega hoy con interpreted: true, pero no inscribes a nadie en él y no se interpreta por sí solo (ver Baseline)
GET /catalog/protocols Los protocolos en los que puedes inscribir personas; hasSchedule: true quiere decir que solo puede empezar por su primera posición, e interpreted: false, que POST /analyze responde 409 PROTOCOL_NOT_ANALYSED (como con Measurement). Baseline también aparece, con interpreted: true, pero no inscribes personas en él
GET /catalog/protocol_mechanic Las posiciones de cada protocolo (qué mecánica, en qué orden) con sus tres relojes
GET /catalog/mechanics Las mecánicas de tus protocolos y las microintervenciones que pueden ofrecer tus contextos, cada una con constellationSubcontextId (su subcontexto de análisis, o null)
GET /catalog/mechanics/{pid} Una mecánica con su guion completo, para una microintervención que tu propia app decide ofrecer
GET /catalog/mechanic_step Qué tipo de step, en qué orden, forma cada mecánica
GET /catalog/step_types Los tipos de step, con minTimeSeconds y maxTimeSeconds: los dos extremos de cada ventana de respuesta. Varios pueden compartir type: current: true marca el que está en uso
GET /catalog/media Los textos, imágenes y vídeos de esos tipos de step
GET /catalog/step_type_media Qué media va con cada tipo de step

@neurologyca/capture-server lee seis de ellas a la vez con listProtocolLibrary().

Una posición puede declarar tres relojes independientes; está disponible donde se solapan:

  • Fecha: un día contado desde la primera captura completada del protocolo (o un día de la semana), con una tolerancia antes y después. Cuando esa ventana se cierra, la posición se pierde.
  • Franja horaria: ventanas en el huso horario local de la persona (el timezone del usuario; si no tiene, uno por defecto del entorno).
  • Separación (timeBetweenSessionsSeconds): un tiempo mínimo desde la captura anterior. Cuando los relojes se aplican, Engine mantiene además una separación mínima entre dos capturas del mismo protocolo, aunque la posición no declare ninguna; ese mínimo es un ajuste del entorno.

Un protocolo con hasSchedule: true declara una fecha o una franja horaria en al menos una posición, y hay que empezarlo por la posición 1. La separación no activa hasSchedule ni obliga al orden. Engine declara estos relojes y los comprueba al abrir una captura; que un fallo rechace la captura o solo quede registrado depende del entorno. Sesiones, inscripciones e interrupciones muestra las respuestas.

  • minTimeSeconds y maxTimeSeconds son una guía para tu interfaz: Engine no los aplica, y a menudo vienen null.
  • presentationSeconds, cuando viene, dice cuánto está pensada para mostrarse la pregunta del step; el visualizador lo pinta como «se muestra N s». También es una guía: el SDK te lo da (PlanStep.presentationSeconds) y no lo aplica.
  • media[] lista lo que se puede mostrar en un step. Cuando muestras uno, envía su pid como mediaId con los lotes de ese step.
  • instructions[] son pantallas que se muestran pero no se miden: beforeStep (con step) o atEnd.
  • Un step optional se puede saltar. Un step cíclico (rounds, phases) sigue siendo una sola captura.
  • targetConstellationHciId nombra en qué se fija la interpretación en ese step. El SDK lo llama igual, PlanStep.targetConstellationHciId.

Un contexto también puede definir mecánicas cortas que Engine puede ofrecer tras una captura completada, como un ejercicio de respiración. No son posiciones de tu protocolo: la oferta llega como una interrupción de la captura que la disparó. Ver Sesiones, inscripciones e interrupciones.

Los protocolos publicados nunca cambian: una edición crea una versión nueva. Un protocolo archivado se puede seguir inscribiendo, con un protocolNotice que apunta a su sustituto; uno obsoleto no admite inscripciones ni capturas nuevas.