Closed yarikoptic closed 4 years ago
I think the rationale was that for most metadata the values are too far ranging to be included in the file name, so it makes sense to only have it in the json file.
BUT - I have a light memory that you can choose whatever index you want in the filename.... So you could - if you wanted to have _fa-25
and _fa-45
which I think is what you're looking for, right? You'd still need the FlipAngle
metadata field in your json and that's where the value would actually come from.... you can name the file whatever you'd like.
I agree that the current specification isn't clear on this src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md#indexable_metadata-index-key-value-pair and its also wildly possible that I'm misremembering a conversation.
Tagging @agahkarakuzu who might have more thoughts than me.....
_fa-25
and _fa-45
are valid only if you have 45 FA values in the list. Please, remember that the value in the filename is an index rather than the actual value.
So what you need to do is
_fa-1
and _fa-2
in the filenamesFlipAngle : [25, 45]
in the JSONI agree with @tiborauer that the filename should only contain index(es) of some metadata like FA. Quick follow up question on this: in the accompanying JSON file must there a vector of values, i.e. one value per index, as you suggest? Or could I store a single value per JSON file, i.e. only the value for that index?
@yarikoptic if you have multiple sessions, couldn't you label the sessions/runs (_run-1_
, _run-2_
,...) to avoid confusion? And if you want to quickly check the actual FA values, maybe have that information saved in another JSON file, associated with each of the sessions/runs?
I see no reason why you could not. You need a list only, if you use a single JSON for multiple images.
I would prefer using the corresponding keys rather than just having runs. Although, run
is not specified for structural data, yet; but for fMRI runs have the same acquisition parameters.
As for index
vs actual parameter value
discussion, I think one of the core principles of the BIDS specification is not to store parameter values in file names. So I agree with @tiborauer and @ChristophePhillips Also note that _fa-<index>
is an indexable_metadata
.
@KirstieJane this is from one of my previous commits, I though that it would be redundant and omitted this from the specification. I think we should put it back, what do you think?
@ChristophePhillips @tiborauer I have added bunch of details regarding JSON files on this branch. These are not final of course, needs discussion before merging, but should be helpful. For the JSON files of the grouping suffixes
, single value per JSON. For the JSON file of the resultant maps, using vectorized form makes more sense. You can see this simple VFA
dataset on OSF repo, I followed this convention there.
Note that run
entity assumes that all the parameters remain the same across multiple runs.
I'm confused about the list thing after our conversation on the call yesterday - seems like we need to clarify that.... I had taken away from the conversation yesterday that we can't have lists. Are there any metadata fields in the main specification that are lists? Are we inventing something new here? Seems big....
If we didn't allow lists, would we then allow any value? I feel like this conversation has been had elsewhere in the specification. @yarikoptic - are you aware of other metadata fields that are stored in the filename?
I agree that fa
is preferred, and run
is for identical acquisitions.
VolumeTiming
and SliceTiming
, for example, are lists.
The confusion comes for the fieldmaps. I proposed, back then, using list to store TE for dual-echo fieldmaps; however, the proposal using EchoTime1
and EchoTime2
has been accepted for a reason I cannot recall now.
VolumeTiming
andSliceTiming
, for example, are lists.
These wouldn't use the index from the filename though, right? I think this is a first use of using the index to grab information from a list.....and I guess having us just insert the FlipAngle
as a single float in the json would fit better with the EchoTime1
example?
@tiborauer
You need a list only, if you use a single JSON for multiple images.
I think that there is 1 <--> 1 mapping between a JSON file and an image, this is why we had inheritance principle discussion.
Given that there'll be a JSON for each image with a different fa
, each JSON should better contain only the corresponding value instead of a list that contains parameters for every other image of the same group.
@KirstieJane, For MEG, they already have a very similar concept:
"Some software reader may skip important metadata that is specific to MEG system manufacturers. It is therefore RECOMMENDED that users provide additional meta information extracted from the manufacturer raw data files in a sidecar JSON file. This allows for easy searching and indexing of key metadata elements without the need to parse files in proprietary data format. Other relevant files MAY be included alongside the MEG data; examples are provided below."
I agree it may be vague; however, I am not sure why it may not work.
However, there is a clear statement in the current spec against using actual values (for ME data):
"Please note that the <index>
denotes the number/index (in a form of an integer) of the echo not the echo time value which needs to be stored in the field EchoTime of the separate JSON file."
Coolio! Thanks @tiborauer - that makes sense to me to conform with the suggestion already in the spec to have the index be the index not the real value.
(I've remembered by the way the conversation that I couldn't properly bring to mind earlier. Your indices don't have to correspond to any order of the metadata. So index 1 can be flip angle 45, index 2 can be 65 and index 3 can be 25. No problem. 😸)
@yarikoptic - does all this make sense? Probably different json files for the two different scans with different flip angles and use the indexes rather than the values. Is there a different angle (lolz) that we haven't considered?
Thank you everyone for this lively discussion. Sorry for me being a slow one ;)
TL;DR: Overall, I think that <index>
should in general be avoided unless it is the most semantically descriptive way (e.g. in case of _run
) or lookup into an ordered list is necessary (nowhere in BIDS atm AFAIK). With grouped scan collections
it might be the case. I will try to digest it and followup later. Current bids-specification or master of this BEP do not warrant use of <index>
for _fa
really. If you could clarify the "inheritance principle" for me - I would appreciate.
And now the longer version: ;-)
I think I will need to spend some more time to grasp grouped scan collections
which are introduced in the indexable_metadata
branch of this BEP (and thus not a part of the BEP001 master). As far as I see it (indexable_metadata
) would be the only good reason for using <index>
here instead of a <label>
which would allow for an arbitrary literal (and thus could be actual value) to be used to make dataset more human "readable".
Meanwhile, let me dump here some notes/arguments which could, once again, be irrelevant in the realm of indexable_metadata
:
I think that there is 1 <--> 1 mapping between a JSON file and an image, this is why we had inheritance principle discussion.
IMHO (see https://github.com/bids-standard/bids-specification/issues/102) inheritance principle ATM is quite a weak point within BIDS. Although pybids and probably other tools have their own way to treat it, I am afraid it is not yet formalized well enough and thus I would not rely on it heavily just yet. If I am wrong, please follow up on that issue and clarify.
_run-<index>
@KirstieJane, For MEG, they already have a very similar concept:
unfortunately there is no L34-L39
id in that page for me... The only <index>
in that page I find, is the _run-<index>
. For the run
it makes perfect sense to distinguish between scans which are otherwise exactly the same (thus all other possibly informative fields being the same), and _run-<index>
describing the repetition and (likely) the order of those.
If the reference was for the quote ("Some software reader may skip important metadata...") about usefulness of sidecar JSON files - I agree that there should be sidecar files which provide as much of information as possible. But either the filename has <index>
or <label>
is somewhat orthogonal to it (again disgregarding "grouping" effort/branch).
_echo-<index>
which seems was there since the markdown inception of bids-specification, and thus IMHO needs TLC due to all the "EchoTime[12]", and that is why great to see you are working on straightening it up
BIDS ATM is not entirely clear on either index for echo
should anyhow imply any ordering or lookup in some list:
$> grep -A2 '[^-]<index' src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md
Please note that the `<index>` denotes the number/index (in a form of an
integer) of the echo not the echo time value which needs to be stored in the
field EchoTime of the separate JSON file.
_fa-<index>
vs _fa-<label>
?If we disregard "grouped scans" for now, with <index>
so I see no benefit as of the master
version of this BEP.
_fa-<label>
:_task
, _acq
and even _desc
in derived data, while relying on JSON side car to provide further information. Even subject and session "ids" are just <label>
s which often make datasets more reusable (reuse of ids across studies at the center) and "robust" (removing an entry in the middle of the list of items doesn't require renaming the others after it!)_fa-
has a sidecar with actual value in `FlipAngle' so dataset remains machine friendly@yarikoptic going back to the very first comment you made
Moreover it is not immediately clear from the filename how any two files (e.g. _fa-1 and _fa-2) are different, and would require lookups into .json files, decreasing the usefulness from BIDS convention.
As you also noted in your latest comment, it makes sense within the context of grouped scan collections
, because if a filename has a grouping suffix
and _fa-<index>
, it becomes immediately clear that the application which collects those files hinges on varying flip angles. Most importantly, when people go ahead and read the table for grouping suffixes
, they can find out why <fa>
was changed for that group of images. If someone is using a label from the specification that corresponds to an acquisition parameter, I think it is critical to have an explicit description for the cases where <fa>
can be varied.
This is why we suggest the use of <indexable_metadata>
with a grouping suffix
.
For example:
sub-01_fa-1_VFA.nii.gz
sub-01_fa-2_VFA.nii.gz
sub-01_fa-3_VFA.nii.gz
The use of <index>
comes in handy here because total number of varying flip angles may show differences for the same grouped scan collections
between different datasets . For example, I can collect my dataset with 10 different flip angles to be more accurate with my VFA
estimation, whereas 3 is enough in general. Having information on how many different flip angles are collected is easier with <index>
for human readers and semantically relevant if you know what VFA
is.
When people go ahead and read the table for grouping suffixes, it is clear why <fa>
was changed for a group of images attaining VFA
suffix. However, the purpose of why flip angle was changed becomes questionable if the suffix
was T1w
, because its function here rather remains esoteric and there is no explanation about it in the specification that people can refer to:
sub-01_fa-1_T1w.nii.gz
sub-01_fa-2_T1w.nii.gz
Therefore, it does not make much sense to use <fa>
with conventional anatomical images
. It goes more like "if you have two GRE images with different flip angles, you should better call one of them PDw
and the other one T1w
, next to each other". This makes more sense if those files will be processed individually, and knowing the name of their contrast is going to determine the course of the process (e.g. PDw contrast can be better for segmenting a specific structure).
The problem here is that you can draw the line anywhere you like for the amount of flip angle difference that separates PDw
s from T1w
s. So what option do I have if I still want to call both those images T1w
using different flip angles? Because I am just trying out some parameters. I would do the following:
sub-01_acq-fa30_T1w.nii.gz
sub-01_acq-fa35_T1w.nii.gz
This gives a better feeling that someone was just experimenting with different flip angles. Whereas the use of <fa>
in the filename (with indexes) implies a well-defined use case, given that people can find explanations about it in the spec.
Lastly, the benefit brought by <index>
does not change from master
to indexable_metadata
branch of the BEP001. IMHO, if we disregard grouped scans
for BEP001, we'd be disregarding one of the main additions it brings.
The inheritance principle in its current form is a concern for BEP001, because we were planning to keep all the constant parameters in one (top) JSON file and put only varying parameters in lower JSON files such as:
sub-01_VFA.json (constant parameters shared between sub-01_fa-1_VFA.nii.gz and sub-02_fa-1_VFA.nii.gz )
sub-01_fa-1_VFA.json (values of the varying parameters for sub-01_fa-1_VFA.nii.gz )
sub-01_fa-1_VFA.nii.gz
sub-01_fa-2_VFA.json (values of the varying parameters for sub-01_fa-2_VFA.nii.gz )
sub-01_fa-2_VFA.nii.gz
According to the inheritance principle this is not valid, because the structure above makes one JSON file apply to more than one images. This is why we diverged from this approach, which was the only case we interfaced with the inheritance principle.
This is why we suggest the use of
<indexable_metadata>
with agrouping suffix
.
Was this suggestion discussed within the "BIDS core"?
IMHO it might even be worth a dedicated BEP since it is not merely adding new data types etc, but introduces changes into how sidecar files relate to data files etc. So it would be very worth having a more targeted discussion (of cause might have examples from this BEP as motivation)
The use of
<index>
comes in handy here because total number of varying flip angles may show differences for the samegrouped scan collections
between different datasets . For example, I can collect my dataset with 10 different flip angles to be more accurate with myVFA
estimation, whereas 3 is enough in general. Having information on how many different flip angles are collected is easier with<index>
for human readers and semantically relevant if you know whatVFA
is.When people go ahead and read the table for grouping suffixes, it is clear why
<fa>
was changed for a group of images attainingVFA
suffix.
Hm... I do not think anything in BIDS is intended to answer why (why do we collect any anat/ -- for registration? for diagnosis? for deriving surfaces? for both?), but rather what.
That is why I actually quite dislike having _T1w
being replaced with some non-informative _VFA
, but I see the point that with different fa
values you could obtain files with different suffixes... I would have suggested to come up with a dedicated _grp-<label>
field for such grouppings, while retaining suffix to describe what image it is (_grp-vfa1_T1w
, _grp-vfa1_PD
) thus staying more consistent with BIDS "core". Then folks who do not care about having multi flip angle images, could just happily use _T1w
in their pipelines, because they would know what it is. Those who do care about VFA - could just group those images, get FlipAngle from sidecar .json, and we all are happy family again making such datasets useful not only for VFA interested folks.
once again -- sounds like a good discussion to bring up with other BIDS fellas community members.
I think what we're trying to do in BEP001 is have a smaller group work through the (many) complexities of extending the specification before opening up the discussion. Although - to be clear - everyone is welcome to join in! Conversations like this make it much easier to see where the challenges are and how we should be capturing the many discussions we've had about this over the years.
We'll absolutely take your considerations into our extension of the specification - particuarly capturing more of the motivation for why we've chosen to go down this path which is - at the moment - not clearly enough explained.
One last point - I'm not a fella. Please don't generalise the BIDS community as all male.
One last point - I'm not a fella. Please don't generalise the BIDS community as all male.
No (over)generalization was intended, sorry. I used fella
as a colloquial form of fellow
with the connection to fellowship
as we are all aiming for the same common good. But English is not my native language, I guess I have made a mistake.
I will change it, and not to "comrade" (which in my view/history is gender neutral) which would be the closest, but to a longer "community members". I hope that suffice. Sorry for my bad English.
I would argue against BIDS ignoring why. Modality-specific suffixes answer why rather than what, and we already have some discussions on the inaccuracies of the what.
There are two main motivations behind using grouping suffixes.
_T1w
or _PDw
. For that reason, we consider grouping suffix more appropriate and accurate.Although related to the original issue, I think it is worth a separate discussion, thus moving into a new https://github.com/bids-standard/bep001/issues/72
Our use case: We are doing period QA (data is available from http://datasets.datalad.org/?dir=/dbic/QA), and in the past had some scans with standard flip angles with no indication of flip angle in the file name. Now we (in particular @kodiweera) experimenting with different flip angles. If we resort to
_fa-<index>
, we could potentially have confusingly identical filenames across sessions when actual flip angle would be different. Moreover it is not immediately clear from the filename how any two files (e.g._fa-1
and_fa-2
) are different, and would require lookups into .json files, decreasing the usefulness from BIDS convention.I wondered what was the rationale (besides may be inability/difficulty of reflecting floating point values? did you see any of those in over 10% (100-90% of the use cases? ;)) for storing indexes and not the actual values?