BIDSIO

BIDSIO is a project for simplifying tasks associated with using multiple BIDS datasets, and writing out to new BIDS sets. It is structured to facillitate ML code dealing with BIDS directories, hence the use of data and target.

Installation

You can install BIDSIO using pip:
pip install -U git+https://github.com/AlexandreHutton/bidsio

Note that the package is in early development and is likely to change significantly.

Usage

The section gives example uses of the package.

Loading image sets

Loading image sets is done via the BIDSLoader class.

Loading pairs from a single BIDS dataset

In the following example, we create a BIDSLoader that will return a tuple of the form (data, target) with the following properties:

subject and session matches between the data and the target. This is indicated by the empty value in data_entities.
The data image has the T1w suffix (i.e., is a T1-weighted image).
The target image has the FLAIR suffix (i.e., is a T2-weighted FLAIR image).

from bidsio.bidsloader import BIDSLoader
bload = BIDSLoader(data_entities = [{'subject': '',
                                     'session': '',
                                     'suffix': 'T1w'}],
                   target_entities = [{'suffix': 'FLAIR'}],
                   root_dir = 'example_bids/'
                   )

Loading pairs from different BIDS datasets

We are not restricted to using a single BIDS dataset. If the images are split across different BIDS datasets, we can still pair them via the root_list argument. Instead of using a single BIDS root directory, root_list will be used to fetch images.

from bidsio.bidsloader import BIDSLoader
bload = BIDSLoader(data_entities = [{'subject': '',
                                     'session': '',
                                     'suffix': 'T1w'}],
                   target_entities = [{'suffix': 'FLAIR'}],
                   root_list = ['example_bids/', 'example_bids_flair/']
                   )

Loading multiple data / target

In cases where you have multiple inputs (e.g. T1w + T2w images) and have multiple outputs (e.g. white matter masks, lesion masks), we simply need to specify the BIDS entities. In the next example, the T1w and T2w images are in the same directory (raw data), and the target images are in the derivatives/ directory.

from bidsio.bidsloader import BIDSLoader
bload = BIDSLoader(data_entities = [{'subject': '',
                                     'session': '',
                                     'suffix': 'T1w'},
                                    {'suffix': 'T2w'}],
                   target_entities = [{'label': 'WM'},
                                      {'label': 'L'}],
                   root_dir = 'example_bids/'
                   target_derivatives_names = ['wm_seg', 'lesion_seg']
                   )

Saving an image

Once you're making predictions, you may need to save your predictions. You can do so using the write_image_like method of BIDSLoader. Since your prediction will probably be a different type of data than your input (e.g. predicting masks based on T1w images), you can modify the BIDS entities. Unmodified entities will be taken from the image_to_imitate input.

from bidsio.bidsloader import BIDSLoader
data = bids_image.get_fdata()
prediction = model.predict(data)  # Prediction we generated and would like to save.
BIDSLoader.write_image_like(data_to_write = prediction,
                            image_to_imitate = bids_image,
                            new_bids_root = 'prediction_bids/',
                            new_entities = {'suffix': 'mask',
                                            'label', 'L'}
                            )

Reporting Issues

Please report issues via GitHub's issue tracker and include the code required to reproduce the issue and how it differs from the expected behaviour.