.. DO NOT EDIT. .. THIS FILE WAS AUTOMATICALLY GENERATED BY SPHINX-GALLERY. .. TO MAKE CHANGES, EDIT THE SOURCE PYTHON FILE: .. "tutorials/tutorial_examples/plot_002_bids_layout.py" .. LINE NUMBERS ARE GIVEN BELOW. .. only:: html .. note:: :class: sphx-glr-download-link-note :ref:`Go to the end ` to download the full example code .. rst-class:: sphx-glr-example-title .. _sphx_glr_tutorials_tutorial_examples_plot_002_bids_layout.py: ==================== How pyAFQ uses BIDS ==================== The pyAFQ API relies heavily on the `Brain Imaging Data Standard (BIDS) `_, a widely used standard for organizing and describing neuroimaging data. This means that the software assumes that its inputs are organized according to the BIDS specification and its outputs conform where possible with BIDS. .. note:: Derivatives of processing diffusion MRI are not currently fully described in the existing BIDS specification, but describing these is part of an ongoing effort. Wherever possible, we conform with the draft implementation of the BIDS DWI derivatives available `here `_ In this example, we will explore the use of BIDS in pyAFQ and see how BIDS allows us to extend and provide flexibility to the users of the software. .. GENERATED FROM PYTHON SOURCE LINES 24-33 .. code-block:: Python import os import os.path as op import AFQ.api.bundle_dict as abd from AFQ.api.group import GroupAFQ, get_afq_bids_entities_fname import AFQ.data.fetch as afd .. GENERATED FROM PYTHON SOURCE LINES 34-36 To interact with and query BIDS datasets, we use `pyBIDS `_, which we import here: .. GENERATED FROM PYTHON SOURCE LINES 36-40 .. code-block:: Python import bids from bids.layout import BIDSLayout .. GENERATED FROM PYTHON SOURCE LINES 41-47 We start with some example data. The data we will use here is generated from the `Stanford HARDI dataset `_. The call below fetches this dataset and organized it within the `~/AFQ_data` folder in the BIDS format. .. GENERATED FROM PYTHON SOURCE LINES 47-50 .. code-block:: Python afd.organize_stanford_data(clear_previous_afq="all") .. GENERATED FROM PYTHON SOURCE LINES 51-93 After doing that, we should have a folder that looks like this: | stanford_hardi | ├── dataset_description.json | └── derivatives | ├── freesurfer | │   ├── dataset_description.json | │   └── sub-01 | │   └── ses-01 | │   └── anat | │   ├── sub-01_ses-01_T1w.nii.gz | │   └── sub-01_ses-01_seg.nii.gz | └── vistasoft | ├── dataset_description.json | └── sub-01 | └── ses-01 | └── dwi | ├── sub-01_ses-01_dwi.bvals | ├── sub-01_ses-01_dwi.bvecs | └── sub-01_ses-01_dwi.nii.gz The top level directory (`stanford_hardi`) is our overall BIDS dataset folder. In many cases, this folder will include folders with raw data for each subject in the dataset. In this case, we do not include the raw data folders and only have the outputs of pipelines that were used to preprocess the data (e.g., correct the data for subject motion, eddy currents, and so forth). In general, only the preprocessed diffusion data is required for pyAFQ to run. See the :doc:`"Organizing your data" ` section of the documentation for more details. In this case, one folder contains derivative of the Freesurfer software and another folder contains the DWI data that has been preprocessed with the Vistasoft software. pyAFQ provides facilities to segment tractography results obtained using other software as well. For example, we often use `qsiprep `_ to preprocess our data and reconstruct tractographies with software such as `MRTRIX `_. Here, we will demonstrate how to use these reconstructions in the pyAFQ segmentation and tractometry pipeline We fetch this data and add it as a separate pipeline The following code will download a previously-created tractography and organize it by adding it to the BIDS dataset folder and renaming them to be BIDS-compliant (e.g., `sub-01_ses_01_dwi_tractography.trk`). .. GENERATED FROM PYTHON SOURCE LINES 93-118 .. code-block:: Python afd.fetch_stanford_hardi_tractography() bids_path = op.join(op.expanduser('~'), 'AFQ_data', 'stanford_hardi') tractography_path = op.join(bids_path, 'derivatives', 'my_tractography') sub_path = op.join(tractography_path, 'sub-01', 'ses-01', 'dwi') os.makedirs(sub_path, exist_ok=True) os.rename( op.join( op.expanduser('~'), 'AFQ_data', 'stanford_hardi_tractography', 'full_segmented_cleaned_tractography.trk'), op.join( sub_path, 'sub-01_ses-01-dwi_tractography.trk')) afd.to_bids_description( tractography_path, **{"Name": "my_tractography", "PipelineDescription": {"Name": "my_tractography"}, "GeneratedBy": [{"Name": "my_tractography"}]}) .. rst-class:: sphx-glr-script-out .. code-block:: none 0%| | 0/11337 [00:00 .. GENERATED FROM PYTHON SOURCE LINES 190-191 We can also get some more structured information about this file: .. GENERATED FROM PYTHON SOURCE LINES 191-195 .. code-block:: Python print(tractography_file.get_entities()) .. rst-class:: sphx-glr-script-out .. code-block:: none {'datatype': 'dwi', 'extension': '.trk', 'session': '01', 'subject': '01', 'suffix': 'tractography'} .. GENERATED FROM PYTHON SOURCE LINES 196-202 We can use a :class:`bids.BIDSValidator` class instance to validate that this file is compliant with the specification. Note that the validator requires that the filename be provided relative to the root of the BIDS dataset, so we have to split the string that contains the full path of the tractography to extract only the part that is relative to the root of the entire BIDS ``layout`` object: .. GENERATED FROM PYTHON SOURCE LINES 202-209 .. code-block:: Python tractography_full_path = tractography_file.path tractography_relative_path = tractography_full_path.split(layout.root)[-1] validator = bids.BIDSValidator() print(validator.is_bids(tractography_relative_path)) .. rst-class:: sphx-glr-script-out .. code-block:: none True .. GENERATED FROM PYTHON SOURCE LINES 210-217 Next, we specify the information we need to define the bundles that we are interested in segmenting. In this case, we are going to use a list of bundle names for the bundle info. These names refer to bundles for which we already have clear definitions of the information needed to segment them (e.g., waypoint ROIs and probability maps). For an example that includes custom definition of bundle info, see the `plot_callosal_tract_profile example `_. .. GENERATED FROM PYTHON SOURCE LINES 217-227 .. code-block:: Python bundle_info = abd.default18_bd()[ "Left Superior Longitudinal", "Right Superior Longitudinal", "Left Arcuate", "Right Arcuate", "Left Corticospinal", "Right Corticospinal", "Forceps Minor"] .. GENERATED FROM PYTHON SOURCE LINES 228-244 Now, we can define our GroupAFQ object, pointing to the derivatives of the `'my_tractography'` pipeline as inputs. This is done by setting the `import_tract` key-word argument. We pass the `bundle_info` defined above. We also point to the preprocessed data that is in a `'dmriprep'` pipeline. Note that the pipeline name is not necessarily the name of the folder it is in; the pipeline name is defined in each pipeline's `dataset_description.json`. These data were preprocessed with 'vistasoft', so this is the pipeline we'll point to If we were using `'qsiprep'`, this is where we would pass that string instead. If we did that, AFQ would look for a derivatives folder called `'stanford_hardi/derivatives/qsiprep'` and find the preprocessed DWI data within it. Finally, to speed things up a bit, we also sub-sample the provided tractography. This is done by defining the segmentation_params dictionary input. To sub-sample to 10,000 streamlines, we define `'nb_streamlines' = 10000`. .. GENERATED FROM PYTHON SOURCE LINES 244-255 .. code-block:: Python my_afq = GroupAFQ( bids_path, preproc_pipeline='vistasoft', bundle_info=bundle_info, import_tract={ "suffix": "tractography", "scope": "my_tractography" }, segmentation_params={'nb_streamlines': 10000}) .. GENERATED FROM PYTHON SOURCE LINES 256-259 Finally, to run the segmentation and extract tract profiles, we call The `export_all` method. This creates all of the derivative outputs of AFQ within the 'stanford_hardi/derivatives/afq' folder. .. GENERATED FROM PYTHON SOURCE LINES 259-263 .. code-block:: Python my_afq.export_all() .. rst-class:: sphx-glr-script-out .. code-block:: none 0%| | 0/179864.0 [00:00` .. container:: sphx-glr-download sphx-glr-download-python :download:`Download Python source code: plot_002_bids_layout.py ` .. only:: html .. rst-class:: sphx-glr-signature `Gallery generated by Sphinx-Gallery `_