User Tools

Site Tools


neuroimagen:xnat_pipelines_registro

This is an old revision of the document!


Pipeline de registro de PET y MRI en Xnat

El objetivo de este pipeline es procesar conjuntamente dos imágenes MRI y PET de un mismo sujeto adquiridas en las fechas más próximas posibles, siempre a menos de 6 meses (dos experimentos Xnat, en el mismo proyecto), registrarlas, calcular algunas estadísticas y someterlas a un proceso de validación manual.

El proceso se ha separado en tres partes que se han integrado, finalmente, en un único pipeline:

  1. preprocesamiento de los experimentos (emparejamiento de imágenes PET con las MRI más próximas del mismo sujeto y conversión de ambas a NIFTI)
  2. ejecución del pipeline de registro y cálculo
  3. generación de una imagen de previsualización del registro y un proceso user friendly de validación del resultado

Ejemplo de uso

El pipeline que se ejecuta automáticamente se halla en:

/nas/data/xnat/pipeline/catalog/RegisterPETwithMRImatch/RegisterPETwithMRImatch.xml

pero conviene definir también los otros pipelines: MatchPETwithMRI, DicomToNifti_Y y RegisterPETwithMRI.

Instalación del pipeline: argumentos de entrada

En el proyecto, se añaden los tres pipelines de registro y el pipeline de conversión a formato NIFTI:

Pero sólo se pide que se arranque automáticamente tras la carga de imágenes RegisterPETwithMRImatch, que es el que llama a los otros en el orden adecuado.

Las opciones dcmT1tag y dcmFBBtag indican, respectivamente, patrones en los atributos SequenceName de la secuencia MRI y ProtocolName de la secuencia PET. Pueden variar de un proyecto a otro.

Nota: Es necesario marcar la opción “Launch pipeline automatically when session is archived?” al añadir el pipeline; esta opción, aunque se editen luego las opciones del pipeline, no se guarda.

Carga de los archivos MRI y PET: ejecución automática del pipeline

Dado que el pipeline RegisterPETwithMRImatch se ejecuta automáticamente al cargar un estudio PET, es imprescindible que antes se haya cargado el estudio MRI correspondiente al mismo sujeto, con el que se quiere emparejar.

Nota: Si se usa la utilidad xnatapic upload_dicom, se debe indicar explícitamente que se ejecuten los pipelines automáticos al completar la carga de los estudios PET. P.ej.

xnatapic upload_dicom --project_id TestMatch1 --subject_id FACEHBI_001 --pipelines facehbi/FACEHBI-F001B

Notificación por e-mail y enlace a la validación

El proceso de cada estudio no es muy largo: unos 20 minutos. Al finalizar (si todo ha transcurrido sin errores), le llegará al usuario un correo electrónico como el que sigue:

El primer enlace sólo es un log de las operaciones. El segundo enlace, abre una ventana donde se muestra el resultado del registro. El usuario debe decidir si es correcto o no, y esa decisión se guardará en Xnat junto con el resto de información de registro y estadísticas.

Recursos generados

Como resultado del pipeline, en cada estudio PET procesado se crea una carpeta de recursos llamada MRI. En ella se guarda la siguiente información:

  • un archivo JSON, llamado mriSessionMatch.json, con resultados del emparejamiento PET-MRI, estadísticas sobre el registro (SURV y CL) y sobre la evaluación de la calidad del mismo (QA)
  • los archivos NIFTI, _fbb y _struc, generados durante el registro
  • un archivo HTML llamado qa.html y una imagen GIF (obtenida superponiendo los bordes del _struc sobre la imagen _fbb) que son con los que se lleva a cabo la evaluación de calidad del apartado anterior

Generación del informe

El script get_registration_report de la xnatapic genera un archivo CSV que resume estos valores para cada PET de cada individuo. Se debe invocar como:

xnatapic get_registration_report --project_id TestMatch1 --output report.csv

El archivo CSV de salida contiene las siguientes columnas:

  • DCM_SUBJECT: código DICOM del paciente en el estudio PET
  • SUBJECT_ID: código Xnat del paciente
  • PET_EXPERIMENT_ID: código Xnat del estudio PET
  • MRI_EXPERIMENT_ID: código Xnat del estudio MRI
  • REGISTRATION_QA: 0 si no se hizo o si no se consideró bueno el registro; 1 si se consideró bueno el registro
  • STATISTICS_SURV: estadístico SURV calculado al comparar el PET con la referencia
  • STATISTICS_CL: estadístico CL calculado al comparar el PET con la referencia

Nota: Cuando un estudio PET no ha podido emparejarse con uno MRI, el usuario recibe un mensaje de error. Entonces, en el archivo CSV la columna de REGISTRATION_QA aparece vacía (y en MRI_EXPERIMENT_ID un valor que no corresponde a ningún experimento).

Detalle de la implementación

La implementación de RegisterPETwithMRImatch se ha hecho como un wrapper que ejecuta en orden tres pipelets independientes (esto es, que también se pueden ejecutar cada uno sobre un estudio PET, si se asume que ya ha sido preprocesado por los anteriores pipelines de la cadena).

RegisterPETwithMRImatch: llamadas a los pipelets

El pipeline distribuye los datos en tres directorios en los que se ejecutarán procesos diferentes: el de datos de PET (pet), el de datos de MRI (anat) y el de registro (reg).

El registro, se ejecutará con el pipeline de emparejamiento MatchPETwithMRI. Éste, generará la primera versión del archivo JSON. Es la llamada al pipelet más sencilla, que tiene este código:

<step id="RUNMATCHPETWITHMRI" description="Finds the MRI matching this PET session" continueOnFailure="false">
	<pipelet location="RegisterPETwithMRImatch" name="MatchPETwithMRI">
		<parameters>
			<name>callerworkdir</name>
			<values><unique>^/Pipeline/parameters/parameter[name='regDir']/values/unique/text()^</unique></values>
			<description>child workdir</description>
		</parameters>
	</pipelet>
</step>

Nota: La forma de declarar un pipelet no está correctamente documentada en el Xnat Pipeline Development Schema, donde parece indicarse que el bloque <parameters> tiene la misma estructura que los otros bloques del mismo tipo en el XML del pipeline; no es así, aquí, cada <parameters> actúa, en realidad, como cada elemento <parameter> de las otras secciones. Es posible que esto sea un error que corrijan en futuras versiones del pipeline engine.

El parámetro callerworkdir es el que se pasa a los pipelets para que construyan con él el directorio de trabajo; si no se les pasa este argumento (p.ej. si son llamados como pipelines independientes), entonces crean su propio directorio de trabajo.

Nota: callerworkdir no es un estándar, sino una decisión de diseño de este conjunto de pipelines.

El resultado del pipeline anterior es un archivo JSON (que también es cargado como recurso de la sesión PET en Xnat) con una la estructura similar a las respuestas de los servicios de Xnat, para poder hacer uso después de este mecanismo de consulta; p.ej.

{ "ResultSet": {
    "Result":[
      { "MRIsession": "XNAT03_E00005",
        "_": ""
      }]
    }
}

La conversión de DICOM a NIFTI se lleva a cabo ejecutando el pipeline DicomToNifti_Y dos veces: una, sobre el estudio PET, y otra sobre el estudio MRI identificado en el pipeline anterior. Al ejecutarse como pipelet, los archivos NIFTI se crean en los subirectorios pet/NIFTI y anat/NIFTI (pet y anat son pasados como callerworkdir).

La llamada a DicomToNifti_Y sobre el estudio MRI se hace pasando un id obtenido mediante una llamada a fileUtils:GetColumn, una utilidad que permite extraer valores de respuestas JSON a consultas hechas a la API de Xnat en tiempo de ejecución del pipeline. De igual modo se pasan los identificadores de las imágenes del estudio, o scanids. En particular, en este segundo pipelet, se pasan los parámetro mediante este código:

<parameters>
	<name>id</name>
	<values><unique>^fileUtils:GetColumn( /Pipeline/parameters/parameter[name='host']/values/unique/text(), /Pipeline/parameters/parameter[name='user']/values/unique/text(), /Pipeline/parameters/parameter[name='pwd']/values/unique/text(), concat('data/experiments/',/Pipeline/parameters/parameter[name='sessionID']/values/unique/text(),'/resources/MRI/files/mriSessionMatch.json'), 'MRIsession')^</unique></values>
	<description>MRI session ID</description>
</parameters>
<parameters>
	<name>scanids</name>
	<values><list>^fileUtils:GetColumnList( /Pipeline/parameters/parameter[name='host']/values/unique/text(), /Pipeline/parameters/parameter[name='user']/values/unique/text(), /Pipeline/parameters/parameter[name='pwd']/values/unique/text(), concat('data/experiments/', fileUtils:GetColumn(/Pipeline/parameters/parameter[name='host']/values/unique/text(), /Pipeline/parameters/parameter[name='user']/values/unique/text(), /Pipeline/parameters/parameter[name='pwd']/values/unique/text(), concat('data/experiments/',/Pipeline/parameters/parameter[name='sessionID']/values/unique/text(),'/resources/MRI/files/mriSessionMatch.json'), 'MRIsession'), '/scans?format=JSON'), 'ID')^</list></values>
	<description>MRI scan IDs</description>
</parameters>

Nota: Los pipelines de Xnat pueden usar llamadas a funciones Java del /pipeline engine/ para evaluar variables y expresiones y asignar valores a parámetros. En particular, fileUtils:getColumn y fileUtils:GetColumnList, permiten obtener valores de un campo o de una lista de valores de un /ResultSet/ como el de arriba:

''fileUtils:GetColumn(HOST, USER, PASSWORD, PATH, COLUMN)''
''fileUtils:GetColumnList(HOST, USER, PASSWORD, PATH, COLUMN)''

Más detalles en el código fuente de FileUtils.

Nota: La diferencia entre fileUtils::GetColumn y fileUtils::GetColumnList es que la primera devuelve un valor único (de ahí <unique>) y la segunda devuelve una lista (<list>). Estas listas, como las <csv> (valores separados por comas incluidos en el propio XML), se manejan en los pipelines mediante iteradores <loop>.

El último pipeline llamado es RegisterPETwithMRI. Se trata de una llamada semejante a la de MatchPETwithMRI, pasando el callerworkdir que, en este caso, es el mismo directorio de trabajo del pipeline RegisterPETwithMRImatch.

MatchPETwithMRI: emparejado PET-MRI

El pipeline usa el script matchPETwithMRI.sh (representado mediante el resource matchPETwithMRI.xml).

Primero, hace la consulta a Xnat sobre los experimentos de modalidad (xsiType) xnat:mrSessionData que se encuentran del mismo sujeto dentro del proyecto. Esto se guarda como un archivo CSV (mriSessions.csv).

Después, ejecuta el script matchPETwithMRI.sh (representado por el recurso del mismo nombre), llamándolo como

matchPETwithMRI.sh --PETdate $DATE --MRIrecords mriSessions.csv --outputMatch mriSessionMatch.json

donde $DATE es sustituida por el valor de la fecha de la sesión de PET (dato que Xnat guarda como xnat:imageSessionData/date).

El código de este script se puede ver a continuación.

El archivo JSON generado, mriSessionMatch.json, es después cargado dentro del recurso MRI (que es creado, si no existía previamente) de la sesión PET, p.ej. en

http://localhost/data/experiments/XNAT03_E00008/resources/MRI/files/mriSessionMatch.json

DicomToNifti_Y: conversión con dcm2niix

Este pipeline es una adaptación del DicomToNifti_X que se encuentra en dcm2niix. La adaptación consiste en:

* usar un formato de salida en los nombres de los ficheros NII distinto del formato por defecto (en particular, se usa: %n_%s_%d). * usar el argumento /ignore derived/ (-i) [para esto se modificó el resource dcm2niix] * recibir como parámetro el directorio de trabajo (callerworkdir), cuando es llamado como pipelet.

Nota: previamente, ya se había modificado el recurso que llama a dcm2niix para incluir la opción -i.

RegisterPETwithMRI: registro

Si este pipeline no recibe el parámetro callerworkdir, crea los tres directorios, pet, anat y reg, y descarga en los dos primeros las correspondientes series de imágenes de las sesiones, en formato NIFTI, y en el segundo directorio descarga el archivo mriSessionMatch.json de los recursos de la sesión PET. En caso de recibir el callerworkdir, es que esos datos ya existían en esos directorios y no hace falta volver a descargarlos.

El pipeline ejecuta tres scripts: linkNIIwithTagValue.sh, registerPETwithMRI.sh y mkSlicesQAhtm.sh.

linkNIIwithTagValue.sh

Este script busca dentro del directorio de trabajo los archivos JSON asociados a archivos NIFTI que contienen un valor particular de un tag DICOM (es decir, un par clave-valor en el JSON).

El código del script se puede ver a continuación.

El script se llamaría desde la línea de comandos de esta forma:

linkNIIwithTagValue.sh --tag SequenceName --value _tfl3d1_16ns --link sub-XNAT5_S00037_T1w

El argumento –link indica el nombre de los enlaces suaves que se crearán en el directorio de trabajo apuntando a los archivos correspondientes (uno con extensión nii.gz y otro con extensión .json).

registerPETwithMRI.sh

Este script usa las herramientas de la FSL y de ANTS para registrar las imágenes cuyos enlaces se crearon en el script anterior. Después, calcula dos valores estadísticos (usando la utilidad fslstats) comparando la imagen PET-MRI registrada con los atlas de referencia Centiloid_Std_VOI/nifti/2mm/voi_ctx_2mm.nii y Centiloid_Std_VOI/nifti/2mm/voi_WhlCbl_2mm.nii. Estos valores estadísticos los añade a un archivo JSON con la estructura del mriSessionMatch.json (si no existe, lo crea).

El código del script se puede ver a continuación.

El script se llamaría desde la línea de comandos como sigue:

registerPETwithMRI.sh --sid  XNAT5_S00037 --wdir ./reg/ --pet ./pet/sub-XNAT5_S00037_single_fbb.nii.gz --mri ./anat/sub-XNAT5_S00037_T1w.nii.gz --out ./reg/mriSessionMatch.json

Nota: Para que se pueda ejecutar el script, además de ser visibles las bibliotecas de Freesurfer y de ANT, debe estar instalado en todos los nodos del cluster el programa jq [yum install jq].

Nota: para que el script pueda acceder a las imágenes de referencia en /nas/software/neuro.dev, el usuario xnat debe tener permisos de lectura en él.

mkSlicesQAhtm.sh

Este script genera una página HTML interactiva con la que hacer la comprobación visual del registro. Utiliza la herramienta slices de la FSL que crea un archivo GIF con diferentes vistas del registro. La página HTML muestra esa imagen y, mediante llamadas AJAX a la API de Xnat, modifica el valor del parámetro qa en el archivo mriSessionMatch.json del recurso MRI del estudio PET. En particular, el código Javascript para hacer esta modificación es:

//update registration status
regStatus.ResultSet.Result[0].qa=( $("input#QAssessOk").checked )?1:0;
fetch("mriSessionMatch.json?XNAT_CSRF="+csrfToken+"&overwrite=true&inbody=true&format=json&content=MRImatch", {
	"method": "PUT",
	"mode": "same-origin",
	"credentials": "same-origin",
	"headers": { 'Content-type': 'application/json; charset=UTF-8' },
	"body": JSON.stringify(regStatus) }
).then( ... );

Nota: Para interactuar con Xnat a través de una página web, se debe obtener un token CSRF (Cross-Site Request Forgery), que es un mecanismo de seguridad para detectar ataques. Este token se encuentra fácilmente en el código HTML de las páginas devueltas por el servidor Xnat (siempre que el usuario se haya identificado previamente en él) y hay que obtenerlo previamente; p.ej. descargando y reconociendo su patrón (csrfToken=) en la página de entrada del servidor Xnat.

El código completo del script se puede ver a continuación.

La llamada al script desde la línea de comandos se haría como sigue:

mkSlicesQAhtm.sh --sid XNAT5_S00037 --wdir ./reg/

Como se ve, no necesita más información que el id del sujeto, porque el acceso al resto de la información se hará con rutas relativas a la carpeta de recursos MRI.

Script para generación de informe final

Para facilitar el acceso a la información, se ha añadido a la xnatapic una herramienta de consulta get_registration_report, que genera un archivo CSV con los valores relevantes de los archivos mriSessionMatch.json de todas las sesiones PET de un proyecto.

El código completo de este script (que se debe copiar o bien en el directorio share/xnatapic de la instalación de xnatapic, o bien en el directorio .xnatapic del usuario), se puede ver a continuación.

La llamada y el formato del resultado se pueden ver más arriba.

neuroimagen/xnat_pipelines_registro.1607699933.txt.gz · Last modified: 2020/12/11 15:18 by daniel