convert_bids_to_nnUNetV2.py: Not up-to-date

[jcohenadad]

There is apparently (slack conversation with @naga-karthik @valosekj from 2025-06-23) a more up-do-date version:
https://github.com/ivadomed/model_seg_sci/blob/main/dataset-conversion/convert_bids_to_nnUNetv2_all_sci_data.py

However, I can see a few issues with that new script:

• Can only be used on single contrast (https://github.com/ivadomed/model_seg_sci/blob/e92cfb6ca4bd41e78a2e9f2b5643d9d3aab6342c/dataset-conversion/convert_bids_to_nnUNetv2_all_sci_data.py#L32-L33), which is problematic in my case, as I have two input images
• Reorients to RPI (https://github.com/ivadomed/model_seg_sci/blob/e92cfb6ca4bd41e78a2e9f2b5643d9d3aab6342c/dataset-conversion/convert_bids_to_nnUNetv2_all_sci_data.py#L35), which is problematic in my case, as I don't want any reorientation. And, by the way, it shouldn't be the responsibility of a script called "convert_bids_to_nnUNetV2" to reorient, as the name of the script suggests only a renaming/restructuring of files, rather than actual action on the files themselves.

So, questions for @naga-karthik @valosekj : does this script include all the functionalities of https://github.com/ivadomed/utilities/blob/fa601f3039dd508ea51162906f9c965e94aab86e/dataset_conversion/convert_bids_to_nnUNetV2.py?

• if yes: we should just replace it then
• if no: can you please identify the missing features, and open an issue for each of the missing feature so we can address them in the future

[naga-karthik]

does this script include all the functionalities

No. Accounting for all possible combinations (i.e. multiple inputs contrasts, region-based vs multi-channel, conflicting naming conventions) was making the script too heavy so functionalities of this script are quite basic. For other projects, we just tailored it to the kinds of inputs we had and label combinations we wanted to test.

Will open issues to add more functionalities

[jcohenadad]

Additional insights. A lot of fields in https://github.com/ivadomed/model_seg_sci/blob/main/dataset-conversion/convert_bids_to_nnUNetv2_all_sci_data.py are project-specific. Eg, the region-based approach assumes only 2 classes to segment, and their names as well:

https://github.com/ivadomed/model_seg_sci/blob/e92cfb6ca4bd41e78a2e9f2b5643d9d3aab6342c/dataset-conversion/convert_bids_to_nnUNetv2_all_sci_data.py#L224-L234

I'm reiterating the suggestion that the only purpose of convert_bids_to_nnUNetV2.py should be file organization. The creation of the nnUNet plans file should be the responsibility of another script, unless I am missing something?

[jcohenadad]

Reacting to #57 (comment): if the sole purpose of convert_bids_to_nnUNetV2.py is file organization, wouldn't it facilitate the generalization of the script?

And for the generation of the plans file, that could be the responsibility of another (project-specific or not) script.

By the way: do we really need a script to generate a JSON plans file? Is it that difficult to customize that JSON file based on the project, and then host that file on the repository of that project? People could understand it and copy/paste the bits that matter to them.

[naga-karthik]

The creation of the nnUNet plans file should be the responsibility of another script, unless I am missing something?

Minor nitpick: the convert_bids_to_nnUNetV2.py does NOT create plans file (i.e. the file containing training params for nnunet). What it creates is a "dataset fingerprint", which is dataset.json. To avoid confusion for students reading this -- we refer to plans.json as the one containing nnunet training params and dataset.json as just the dataset fingerprint containing info about region-based labelling order.

do we really need a script to generate a JSON plans file?

nnUNet expects the dataset.json to be present in root of dataset. If not, the nnunet preprocessing fails -- this is why we create the dataset.json with the conversion script.

[jcohenadad]

OK thanks, that makes a lot more sense. So yes, I do see the argument for generating the dataset.json file, but why do we need to, e.g.:

• reorient to RPI
• decide at this step if this is going to be a region-based training or not

[naga-karthik]

but why do we need to, e.g.: reorient to RPI, decide at this step if this is going to be a region-based training or not

Now these are optional, for sure. In the past, we just found it easy to reorient everything in script (when aggregating multi-site data) and there was need for region-based models (starting with SCIseg) -- so included them in teh script

these features should be optional in the script as well

[jcohenadad]

and there was need for region-based models (starting with SCIseg)

but again, couldn't this be handled by another script? In my case, i have more than 2 classes to segment, the region-based follows a certain logic, etc. We don't want to end up with a 10,000 line-of-code script. Again, we should always think 'atomic' when it comes down to scripts.

[jcohenadad]

I also realized that nnUnetv2 expects a single segmentation file as input, integer-coded. This goes against our convention, which suggests one binary file per structure (eg: SC, GM, lesion, etc.).

So, does the convert_bids_to_nnUNetv2_all_sci_data.py script also deal with aggregating various binary segmentation files into a single segmentation file? And how do you deal with segmentation files where the same pixel is present in both classes (in case of overlapping regions, eg: lesion+SC)?

[naga-karthik]

I also realized that nnUnetv2 expects a single segmentation file as input, integer-coded.

Indeed.

does the convert_bids_to_nnUNetv2_all_sci_data.py script also deal with aggregating various binary segmentation files into a single segmentation file?

Yes. Because we only had two classes to segment (SC and lesion), script follows a rigid naming convention to fetch these files and combine them.

And how do you deal with segmentation files where the same pixel is present in both classes (in case of overlapping regions, eg: lesion+SC)?

That's done using this function. We first ensure that lesion is part of SC (i.e. inside it) and then assign different integer values to SC and lesion

[jcohenadad]

We first ensure that lesion is part of SC

where do you do it?

Full code of the function

def create_region_based_label(lesion_label_file, seg_label_file, image_file, sub_ses_name, thr=0.5):
    """
    Creates region-based labels for nnUNet training. The regions are: 
    0: background
    1: spinal cord seg
    2: lesion seg
    """
    # load the labels
    lesion_label_npy = nib.load(lesion_label_file).get_fdata()
    seg_label_npy = nib.load(seg_label_file).get_fdata()

    # binarize the labels
    lesion_label_npy = np.where(lesion_label_npy > thr, 1, 0)
    # add the lesion seg to the spinal cord seg
    seg_label_npy = np.where((seg_label_npy + lesion_label_npy) > thr, 1, 0)

    # check if the shapes of the labels match
    assert lesion_label_npy.shape == seg_label_npy.shape, \
          f'Shape mismatch between lesion label and segmentation label for subject {sub_ses_name}. Check the labels.'

    # create a new label array with the same shape as the original labels
    label_npy = np.zeros(lesion_label_npy.shape, dtype=np.int16)
    # spinal cord
    label_npy[seg_label_npy == 1] = 1
    # lesion seg
    label_npy[lesion_label_npy == 1] = 2
    # TODO: what happens when the subject has no lesion?

    # print unique values in the label array
    # print(f'Unique values in the label array for subject {sub_ses_name}: {np.unique(label_npy)}')
    
    # save the new label file
    ref = nib.load(image_file)
    label_nii = nib.Nifti1Image(label_npy, ref.affine, ref.header)

    return label_nii

[naga-karthik]

In these lines, specifically.

# add the lesion seg to the spinal cord seg
seg_label_npy = np.where((seg_label_npy + lesion_label_npy) > thr, 1, 0)

Note, at the time of creating the script, we were using sct_deepseg_sc which missed segmenting parts of the SC in patients with severe SCI (e.g. if the lesion was in-between metallic implants, deepseg_sc was segmenting the cord above and below the lesion. So, this basic check added lesion seg to the cord seg.

note also that this approach is not a robust way of ensuring lesion is inside the SC.

[jcohenadad]

I'm wondering if it makes sense to try to generalize the convert_bids_to_nnUNetv2_all_sci_data.py code. For example in my situation, for a region-based approach, I would need the following labels:

"labels": {
    "background": 0,
    "white matter without lesion": 1,
    "white matter with lesion": 2,
    "gray matter without lesion": 3,
    "gray matter with lesion": 4,
},

defined as follows for region-based training:

"labels": {
    "background": 0,
    "spinal cord": [1, 2, 3, 4],
    "gray matter": [3, 4],
    "lesion": [2, 4]
},
"regions_class_order": ??? (I'm not sure what makes sense here)