This is an old revision of the document!
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:
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
.
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.
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
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.
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:
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)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
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:
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).
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).
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.
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: 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
.