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
andsession
matches between the data and the target. This is indicated by the empty value indata_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.