Merge pull request #54 from nipreps/add_seg_entity

ENH:  Add seg entity to segmentations and time activity curves

Author: mnoergaard

docs/outputs.rst

@@ -336,7 +336,10 @@ from an anatomical segmentation. The resulting table has ``FrameTimesStart`` and
 
   sub-<subject_label>/
     pet/
-      sub-<subject_label>_[specifiers]_desc-preproc_timeseries.tsv
+      sub-<subject_label>_[specifiers]_seg-<seg>_desc-preproc_timeseries.tsv
+
+The ``desc-preproc`` entity indicates that the curves were derived from the
+preprocessed PET series.
 
 If partial volume correction is applied, the filenames also include the
 ``_pvc-<method>`` entity, indicating the algorithm used.
@@ -347,10 +350,12 @@ table containing the mean uptake within that region::
 
   sub-<subject_label>/
     pet/
-      sub-<subject_label>_[specifiers]_desc-<seg>_ref-<ref>_timeseries.tsv
+      sub-<subject_label>_[specifiers]_seg-<seg>_ref-<ref>_desc-preproc_timeseries.tsv
 
 The ``ref`` entity captures the reference region identifier provided via the
 :ref:`CLI options <cli_refmask>` ``--ref-mask-name`` and ``--ref-mask-index``.
+As with the primary TACs, ``desc-preproc`` reflects use of the preprocessed PET
+series.
 When partial volume correction is performed, the ``_pvc-<method>`` entity is
 also included.
 

docs/workflows.rst

@@ -573,8 +573,8 @@ These workflows rely on pretrained segmentation models distributed with
 ``petprep.data.segmentation``. The first time a particular model is requested it
 will be automatically downloaded to the *PETPrep* cache directory, so ensure
 sufficient disk space is available. Each segmentation produces a labeled NIfTI
-image ``desc-<seg>_dseg.nii.gz`` and a TSV table of region volumes
-``desc-<seg>_morph.tsv`` saved under the ``anat/`` derivatives folder.
+image ``seg-<seg>_dseg.nii.gz`` and a TSV table of region volumes
+``seg-<seg>_morph.tsv`` saved under the ``anat/`` derivatives folder.
 
 For example, the raphe segmentation can be enabled with::
 

petprep/workflows/pet/base.py

@@ -700,7 +700,9 @@ def init_pet_wf(
         DerivativesDataSink(
             base_directory=petprep_dir,
             suffix='timeseries',
-            desc=config.workflow.seg,
+            seg=config.workflow.seg,
+            desc='preproc',
+            allowed_entities=('seg',),
             TaskName=all_metadata[0].get('TaskName'),
             **prepare_timing_parameters(all_metadata[0]),
         ),
@@ -732,9 +734,10 @@ def init_pet_wf(
             DerivativesDataSink(
                 base_directory=petprep_dir,
                 suffix='timeseries',
-                desc=config.workflow.seg,
+                seg=config.workflow.seg,
+                desc='preproc',
                 ref=config.workflow.ref_mask_name,
-                allowed_entities=('ref',),
+                allowed_entities=('seg', 'ref'),
                 TaskName=all_metadata[0].get('TaskName'),
                 **prepare_timing_parameters(all_metadata[0]),
             ),

petprep/workflows/pet/fit.py

@@ -462,9 +462,10 @@ def init_pet_fit_wf(
             DerivativesDataSink(
                 base_directory=config.execution.petprep_dir,
                 suffix='timeseries',
-                desc=config.workflow.seg,
+                seg=config.workflow.seg,
+                desc='preproc',
                 ref=config.workflow.ref_mask_name,
-                allowed_entities=('ref',),
+                allowed_entities=('seg', 'ref'),
                 TaskName=metadata.get('TaskName'),
                 **timing_parameters,
             ),

petprep/workflows/pet/segmentation.py

@@ -167,7 +167,8 @@ def _build_nodes(
     nodes['ds_seg'] = pe.Node(
         DerivativesDataSink(
             base_directory=config.execution.petprep_dir,
-            desc=desc,
+            seg=seg,
+            allowed_entities=('seg',),
             suffix='dseg',
             extension='.nii.gz',
             compress=True,
@@ -217,7 +218,8 @@ def _build_nodes(
     nodes['ds_dseg_tsv'] = pe.Node(
         DerivativesDataSink(
             base_directory=config.execution.petprep_dir,
-            desc=desc,
+            seg=seg,
+            allowed_entities=('seg',),
             suffix='dseg',
             extension='.tsv',
             datatype='anat',
@@ -230,7 +232,8 @@ def _build_nodes(
     nodes['ds_morph_tsv'] = pe.Node(
         DerivativesDataSink(
             base_directory=config.execution.petprep_dir,
-            desc=desc,
+            seg=seg,
+            allowed_entities=('seg',),
             suffix='morph',
             extension='.tsv',
             datatype='anat',

petprep/workflows/pet/tests/test_fit.py

@@ -243,7 +243,8 @@ def test_refmask_report_connections(bids_root: Path, tmp_path: Path):
     assert 'ds_ref_tacs' in wf.list_node_names()
     ds_tacs = wf.get_node('ds_ref_tacs')
     assert ds_tacs.inputs.ref == 'cerebellum'
-    assert ds_tacs.inputs.desc == config.workflow.seg
+    assert ds_tacs.inputs.seg == config.workflow.seg
+    assert ds_tacs.inputs.desc == 'preproc'
     edge_tacs = wf._graph.get_edge_data(wf.get_node('pet_ref_tacs_wf'), ds_tacs)
     assert ('outputnode.timeseries', 'in_file') in edge_tacs['connect']