search

bids-standard / bids-specification

Brain Imaging Data Structure (BIDS) Specification
https://bids-specification.readthedocs.io/
Creative Commons Attribution 4.0 International
264 stars 154 forks source link

Alternative proposal to BEP038 #1856

Open oesteban opened 2 weeks ago

oesteban commented 2 weeks ago

This is a proposal to achieve the aims of BEP 38 as derivative datasets, without the need to introduce a new DatasetType. The structure of derivatives is well-established in BIDS, and this would require the introduction of fewer new concepts and less code complexity in supporting all BIDS DatasetTypes.

To demonstrate, the proposal has several examples with 'classical' templates/atlases. In addition to that, I'm working on uploading PS13 to templateflow (further supporting the practical implementation of the proposal), and, if accepted, I can commit to generating bids-examples following the proposal for PS13.

I incorporate the BEP metadata from this spec, for the moment unchanged as the absence of macros made it really hard to carefully edit (that said, I think that part of the current proposal is okay, and I would possibly suggest some additions only).

This proposal only includes the following new entities:

As I understand it, the atlas BEP has taken the shape it has because it was felt that derivatives datasets would not satisfy the needs. I believe I have shown that it can with only minor modifications.

I include a skeleton of the new terms in this PR. If we agree in principle, we can work on schematizing these changes and tightening up the text.

My proposal is issued to address three central issues and other relevant problems. For the interested, I include arguments against specific choices in the BEP as-is, but I hope my arguments for this proposal stand on their own. To see these arguments, please unfold this paragraph by clicking the initial arrow. ## Issue 1: Opening `DatasetType` to values other than `raw` and `derivatives` should have its own BEP. Adding values to `DatasetType` is a major change to the specification that should be broadly discussed by the community, with a preliminary analysis of potential side-effects by the SG and/or Maintainers. It took a long while before `derivatives` became a relevant part of BIDS and many years of discussion about them. I contend that `DatasetType` should keep its special status and be discussed separately. After `DatasetType` is agreed as the appropriate mechanism, the BEP leads intending to add values should state it when presenting the BEP draft to the SG before it becomes listed as an active BEP. For instance, it would not be crazy to contemplate the possibility of having a `DatasetType` such as `freesurfer`, which has a very stable and standardized data structure, to allow it as a standalone dataset. Opening `DatasetType` means opening BIDS to the creation of standards within the standard. Where to draw the line between `raw` and `derivative` has traditionally be a contention point, so enabling more options should be considered very carefully, and provided with prescriptions of how to do it and how to decide beforehand. Otherwise, BEPs proposing new dataset types will creep up as we all tend to think that our area of specialization is special. Please note that this issue does not enter into the actual value of `atlas` proposed by the BEP. That is reviewed next. **Proposed solution**: (1) drop this part of the proposal; (2) discuss the issue as BIDS prescribes; (3) establish whether the intent of `DatasetType` may be open to other dataset types. ## Issue 2: The new value `atlas` for `DatasetType` evades the actual problem. **Evading \*the\* problem that exists**. By creating the new `DatasetType` metadata, the overarching problem is escaped: the fact that **BIDS-Derivatives has not been developed far enough to represent "second-level" analyses**, as in, analyses where data from several subjects, or sessions, or runs, are pooled together. Instead, the current BEP proposal cordons off the problem by creating its own little island. **Solving a problem that does not exist**. The use of the new `DatasetType` is justified to *enable* the sharing of "atlas", as stated in the initial paragraph, and later: > *This will allow sharing existing atlases as stand-alone datasets, validating them via the [BIDS validator](https://github.com/bids-standard/bids-validator) and enabling their integration as sub-datasets of other BIDS datasets.* which suggests that, if a dataset is of `derivative` type then the following is not supported: - The sharing of the dataset stand-alone (which is factually false, derivative datasets are already standalone) - The validation of a derivative dataset (which is circumstancial because the vision is that derivatives are validated as raw one day) - The `derivative` dataset cannot be integrated as a sub-dataset of another BIDS dataset (which is factually false). Therefore, this approach seems to indicate that atlases are somewhere in between "raw" and "derivative" and hence they require their own `DatasetType`. **Proposed solution**: My proposal encodes atlas-derived results and atlas-generating pipelines results within current BIDS-derivatives specifications. If I'm reviewing a paper corresponding to a new template and/or atlas, I would feel better equipped to understand the pipeline and the results if delivered as BIDS-Derivatives, with the most salient intermediate steps there (or transformations so that I can replicate them) instead of a final structure that looks like templateflow's resources putting `atlas-` first. The first reports the atlas creation process, while the second is a fast-track mechanism to emancipate the blobs a researcher wants be reused from the outputs and reporting of the generating pipeline. My understanding of BIDS is that it wants to achieve the first. The act of sharing data and ensuring FAIRness in the delivery of the service is more of a responsibility of other players such as OpenNeuro or TemplateFlow. ## Issue 3: the folder structure is inconsistent with current BIDS raw and derivatives This PR proposes an alternative that is consistent with current BIDS. While for raw and first-level analyses derivatives the spatial reference is established by that of individual subjects, for higher-than-first-level analyses this PR proposes the concept of template, which is the aggregation of feature maps that serve for reference at the individual level (e.g., aggregation of runs, sessions or sets of subjects). That allows for a more consistent organization, which has been already tested in the wild with TemplateFlow. In addition, there are several aspects of atlases (and templates) that this BEP did not cover: ### Problem 1: longitudinal templates (and atlases) The cohort entity of templateflow could resolve this. I can update my PR if it is accepted to contemplate this. ### Problem 2: multi-scale atlases My proposal includes a new scale- entity. ### Problem 3: probabilistic surface parcellations. This would require finding a GIFTI encoding of FreeSurfer's GCS format. This is not really a problem of atlas, but BIDS-Derivatives in general. **Proposed solution**: Implemented by this PR against BEP038. ## Other issues **Downstream problems of the proposed `DatasetType`**. It seems the intent is to have these datasets uploaded to BIDS-compatible platforms such as OpenNeuro as a new means of disseminating and distributing atlases. OpenNeuro does implement FAIR pretty comprehensively, which is fundamental for this intent not to become extremely dangerous, but at the outskirt, the BIDS specifications should refrain from suggesting OpenNeuro should be used for sharing. These atlases will likely be shared through other venues where data versioning, accessibility, etc. are not as transparent or available and that will have the opposite effect that is intended in this BEP (undermined reproducibility and limited reusability of the atlas). But even assuming OpenNeuro as the mechanism for redistribution, there are other issues that are covered in our TemplateFlow paper, which will be problematic if not exacerbated: - Lack of a controled vocabulary for templates' and atlases' names: no one can avoid that two templates are given the same label to the `atlas` entity, and I don't think it would be good for BIDS to attempt to control that. The experience would revive the issues hit with template specifications (https://bids-specification.readthedocs.io/en/stable/appendices/coordinate-systems.html). I also provided an example of this problem within #1281. - Existing templates and atlases will not adopt this. The main way of disseminating templates and atlases remains software packages. It is highly unlikely that software packages will adopt this standard because it adds insecurity (what if BIDS changes the standard? what if my atlases cannot be represented with this specification?) at a very low turnover (because here the sharing is with yourself as a developer, you organize the data as it is most convenient for your application). - Upcoming atlases will not adopt this. If an atlas creator wants their template be reused, they either distribute it with the format of a popular tool (e.g., FreeSurfer or AFNI) or it is unlikely to be adopted (except for applications that can query TemplateFlow). - Unfortunately, many template/atlas generators set copyleft and (worse) no-derivs restrictions on the license, which conflict with the purpose of sharing the resource (since these resources are meant to create derived works). That defeats the noble purpose of "sharing" standalone (even if that were a problem). If a derivative is protected with no-derivs (or the raw, like the HCP data), that is within the scope of possibilities. However, `DatasetType` `atlas` allows people to mark a resource as atlas and confusingly set no-derivs (and maybe request royalties after use?). For `derivative` it is not assumed that you can create further derivatives and the license is checked. **Intro of the proposal misses the point**. The introduction of the current proposal is largely devoted to explain what an atlas is. BIDS should not be a neuroimaging handbook, and therefore, BEPs should not require such justifications. I believe this is a consequence of issue 2 to justify the choice.
oesteban commented 2 weeks ago

cc @jdkent @melanieganz @CPernet @dorahermes @Remi-Gau @effigies @ericearl @francopestilli

There are some wrinkles to iron out (e.g., missing glossary definitions breaking documentation building), but this is a general summary of how I see this. Happy to discuss use cases that are not immediately clear how they would be encoded under this proposal.

Thank you all for your patience, this PR was long overdue.

effigies commented 2 weeks ago

Oscar, do you mind if I do minor cleanups to get the doc builds working? I think this will be easier to review with a rendered spec in front of us. (Thumbs up is fine, no need to clutter the comments more than they already will be.)

effigies commented 2 weeks ago

To ignore the arguments and boil this down to the practical difference between BEP38 and this counter-proposal, it seems to be:

As far as I can tell, anything that could be named under the existing BEP38 could be named under this (notwithstanding some comments on things that need clearing up below) proposal, so that's a good start.

The last point I'm inferring just by its absence. Any recommendation on what people who saw value in this construct do? My personal inclination would be to use sourcedata/atlases/, but BIDS has not defined the structure of sourcedata/. It could be a matter of convention, and the specific locations could be tracked in DatasetLinks.

Some questions on your entities. I'll start with my understanding of how they seem to be used:

tpl-<label> is not defined in your proposal so far. Is it required to be a controlled vocabulary, such as in https://bids-specification.rtfd.io/en/stable/appendices/coordinate-systems.html#image-based-coordinate-systems? Can it, like space, be uncontrolled, provided there is a link within the metadata somewhere? Are you considering study-derived templates at this point, or leaving that to another effort?

My understanding is that the 4-tuple (atlas, seg, scale, suffix) is intended to be unique such that any two files containing the same set of path components have comparable values (e.g., an integer label in a dseg means the same thing in two files where these entities match). How global is this? For example, is there supposed to be a registry that controls this vocabulary, similar to space-<label>, or would I need to verify with the atlas metadata when I receive two datasets with an overlapping atlas label?

I don't really understand scale-. At first I thought it overlaps with res- or den-, but it seems to be something else. Is it "degree of subdivision of segmentation" or "number of subjects used to derive"? Or is seg-<> for qualitative differences (different types of quantities mapped) while scale- is for quantitative differences, and the meaning of each is atlas-specific?

I've only had a quick read-through and so I might have more thoughts later. I don't see any show-stopping problems, but I would like to hear from others who've been more in-the-weeds. Might be good to get people together in Seoul to discuss?

effigies commented 2 weeks ago

One question regarding datatype under tpl: Is that required, optional, or what? You can derive segmentations from any of a number of modalities (or multiple modalities at once) and use them in others; does it make sense to drop datatype altogether under tpl-, or leave it optional? I think required is not tenable.

oesteban commented 2 weeks ago

Any recommendation on what people who saw value in this construct do? My personal inclination would be to use sourcedata/atlases/, but BIDS has not defined the structure of sourcedata/. It could be a matter of convention, and the specific locations could be tracked in DatasetLinks.

I think recommending sourcedata/atlases is a good starting point.

tpl-<label> is not defined in your proposal so far. Is it required to be a controlled vocabulary, such as in https://bids-specification.rtfd.io/en/stable/appendices/coordinate-systems.html#image-based-coordinate-systems? Can it, like space, be uncontrolled, provided there is a link within the metadata somewhere? Are you considering study-derived templates at this point, or leaving that to another effort?

Yes, you're right -- tpl should be defined and it's not, I will address that ASAP. Controlled language - I see it as space in that it is semi-controlled. I would recommend using template space names from https://bids-specification.readthedocs.io/en/stable/appendices/coordinate-systems.html#standard-template-identifiers but allow any label if those standard names do not represent the data.

For example, is there supposed to be a registry that controls this vocabulary, similar to space-<label>, or would I need to verify with the atlas metadata when I receive two datasets with an overlapping atlas label?

I don't know whether there's interest in maintaining another informal 'registry' like https://bids-specification.rtfd.io/en/stable/appendices/coordinate-systems.html#image-based-coordinate-systems? for spaces. My impression is that the spaces list has been pretty stable because the effect of adding new items is minimal.

Perhaps this proposal should also have some sort of atlas-<label>_description.json file given at the root of the structure which is inherited by all files containing atlas-<label>.

Otherwise, if there's a single file (e.g., a single atlas-<label>_dseg file; https://github.com/bids-standard/bids-specification/pull/1856/files#diff-930106228fdeff531c65486378dd4138c6f27c38cbce3bd7621743e4a42453e0R79), that could alternatively serve the purpose.

Another interesting route would be to allow YAML to facilitate a natural language description of the methods of the atlas (i.e., embed a README into the metadata file). Some sort of atlas-<label>_description.yml.

Finally, it may be useful to have an atlases.tsv and atlases.json.

I'm open to any suggestion to resolve this issue.

I don't really understand scale-. At first I thought it overlaps with res- or den-, but it seems to be something else.

It is something else. It is common for atlases to define several levels (scales) of granularity of the defined ROIs. They are typically related hierarchically. E.g., say we have a parcellation that has 7 regions for each hemisphere at the lowest scale. Those regions are then divided in a number of regions at the next level, and so on up to dividing the hemisphere into 1000 ROIs in the highest scale. I think a very interesting paper that describes this as the choice of 'brain unit' is https://www.nature.com/articles/s41593-020-00726-z

One question regarding datatype under tpl: Is that required, optional, or what? You can derive segmentations from any of a number of modalities (or multiple modalities at once) and use them in others; does it make sense to drop datatype altogether under tpl-, or leave it optional? I think required is not tenable.

I think this is a general question for BIDS Derivatives—by not saying anything explicit, we leave it open, and one day, BIDS Derivatives will address this issue. Validator-wise, I'd make it optional.

jdkent commented 2 weeks ago

Thanks for your work on this @oesteban! I largely agree with your approach.

Scope of BEP

As a grounding for me (and hopefully for others), the Atlas BEP scope is to cover:

(as is the case with many/all derivatives)

And an atlas can be created at either the:

But the atlas will always be applied to individual participant data.

seg- entity consensus

I believe one point to find consensus on is how to apply/define the entity seg-

In previous discussions about atlas application/consumption, seg- was understood to be an application of an atlas to a particular participant, with the same label (e.g., atlas-AAL becomes seg-AAL within the participant directory). Thus atlas->seg mirrored the relationship between tpl->space

In a discussion of atlas generation, the entity seg is more about differentiating the same atlas by differing criteria for parcel/segmentation creation.

moving forward we could: 1) use the atlas- entity consistently for the application of the atlas on individual data. 2) create another term to differentiate the conflicting definitions of seg-

General Comments

I have a couple agreements/comments/clarifications

Issue 1: Opening DatasetType to values other than raw and derivatives should have its own BEP.

Agree, I never felt comfortable adding a new datatype, I also think atlases are derivatives.

Issue 2: The new value atlas for DatasetType evades the actual problem.

Agree, I think the issue is more of a technical one of openneuro not supporting uploading of standalone derivative datasets than anything the standard specifies.

Issue 3: the folder structure is inconsistent with current BIDS raw and derivatives Problem 1: longitudinal templates (and atlases) The cohort entity of templateflow could resolve this. I can update my PR if it is accepted to contemplate this.

I am open to a cohort entity, could potentially also be absorbed by the seg- entity, the criteria being the timepoint/age-range for the data selected as input.

Problem 2: multi-scale atlases My proposal includes a new scale- entity.

I can see how scale and seg are being used in the examples, but in my mind there is still a decent amount of overlap between the entities.

seg- is REQUIRED when a single atlas has several different realizations (for instance, segmentations and parcellations created with different criteria) that need disambiguation. scale- is REQUIRED to disambiguate different atlas 'scales', when the atlas has more than one 'brain unit' resolutions, typically relating to the area covered by regions.

In my mind, I could describe that a different number of parcels is a different criteria and would fit under the definition of seg-.

I have a request for the examples:

MIAL67ThalamicNuclei-pipeline/
├─ tpl-MNI152NLin2009cAsym/
│  └─ anat/
│     ├─ tpl-MNI152NLin2009cAsym_atlas-MIAL67ThalamicNuclei_dseg.json
│     ├─ tpl-MNI152NLin2009cAsym_atlas-MIAL67ThalamicNuclei_dseg.tsv
│     ├─ tpl-MNI152NLin2009cAsym_atlas-MIAL67ThalamicNuclei_res-1_dseg.nii.gz
│     └─ tpl-MNI152NLin2009cAsym_atlas-MIAL67ThalamicNuclei_res-1_probseg.nii.gz
├─ sub-01
│  └─ anat/
│     ├─ sub-01_label-ThalamicNuclei_dseg.json
│     ├─ sub-01_label-ThalamicNuclei_dseg.tsv
│     ├─ sub-01_label-ThalamicNuclei_dseg.nii.gz
│     ├─ sub-01_space-MNI152NLin2009cAsym_T1w.nii.gz
│     └─ sub-01_T1w.nii.gz
┇
└─ sub-67
   └─ anat/
      ├─ sub-67_label-ThalamicNuclei_dseg.json
      ├─ sub-67_label-ThalamicNuclei_dseg.tsv
      ├─ sub-67_label-ThalamicNuclei_dseg.nii.gz
      ├─ sub-67_space-MNI152NLin2009cAsym_T1w.nii.gz
      └─ sub-67_T1w.nii.gz

In these examples, I would prefer if tpl-MNI152NLin2009cAsym_atlas-MIAL67ThalamicNuclei_dseg.json and tpl-MNI152NLin2009cAsym_atlas-MIAL67ThalamicNuclei_dseg.tsv be represented at the top level if possible (as atlas-MIAL67ThalamicNuclei_dseg.[json|tsv]) so that the atlas information is more findable, also could reduce repetition if the atlas was generated in multiple template spaces.

PeerHerholz commented 2 weeks ago

Hi everyone,

thanks for all your work on this @oesteban!

As mentioned by @effigies, it would be great to also discuss this during the upcoming Brainhack if possible.

@jdkent: how would @oesteban's proposal relate to the updates and examples you've worked on? It seems that both are more aligned than the previous BEP038 versions we had, no?

Thanks again.

Best, Peer

pwighton commented 2 weeks ago

Thanks for this proposal, @oesteban.

I haven't had a chance to review it in detail yet, but will set aside some time next week to do so.

For the PS-13 use case, at a high level, we are interested in 2 things:

Would this proposal be able accommodate that?

oesteban commented 2 weeks ago

In these examples, I would prefer if tpl-MNI152NLin2009cAsym_atlas-MIAL67ThalamicNuclei_dseg.json and tpl-MNI152NLin2009cAsym_atlas-MIAL67ThalamicNuclei_dseg.tsv be represented at the top level if possible (as atlas-MIAL67ThalamicNuclei_dseg.[json|tsv]) so that the atlas information is more findable, also could reduce repetition if the atlas was generated in multiple template spaces.

Thanks for your feedback @jdkent. I think the above is the only caveat you found, so I'll go ahead and address your request with 'a little twist'. In the example, as it stands, the only metadata that can be generalized across items is label-ThalamicNuclei_dseg.tsv, shared by the 67 subjects that were segmented to build the atlas. Since we only have one template space, then the atlas metadata does not need to be generalized (could be done, without issues, if you want to see the metadata at the top level).

However, generalization would be expected if two different template spaces are created (this is the twist). I've updated accordingly (see f159e61)

As mentioned by @effigies, it would be great to also discuss this during the upcoming Brainhack if possible.

@PeerHerholz definitely :)

Would this proposal be able accommodate that?

@pwighton —that's exactly the purpose. Yes, both are requirements of any BEP, and the proposal must abide by them.

@effigies - I've tried to address some of your questions in 905160d. I'm afraid I'll need to keep working to make the specs render again.

oesteban commented 2 weeks ago

Thanks @oesteban! I think this looks great.

I was wondering if we should add a little bit of information concerning the different naming conventions, ie

tpl-MNI152NLin2009cAsym_from-MNI152NLin6Asym_mode-image_xfm.h5

vs.

sub-01_from-T1w_to-MNI152NLin2009cAsym_mode-image_xfm.h5

to prevent confusion in users (and other stakeholders). That's somewhat outside the scope of BEP038 but as BEP014 is still in development, a little explanation as to how certain transforms are named might be beneficial. WDYT?

I added a little mention to BEP014 in that commit: https://github.com/bids-standard/bids-specification/pull/1856/files#diff-930106228fdeff531c65486378dd4138c6f27c38cbce3bd7621743e4a42453e0R177-R179 I believe we should not attempt to get very deep into transforms here and let it happen within BEP14.

PeerHerholz commented 2 weeks ago

I added a little mention to BEP014 in that commit: https://github.com/bids-standard/bids-specification/pull/1856/files#diff-930106228fdeff531c65486378dd4138c6f27c38cbce3bd7621743e4a42453e0R177-R179 I believe we should not attempt to get very deep into transforms here and let it happen within BEP14.

Definitely! Sorry, I didn't mean to say that we should explain why there are different naming patterns for transform, just that they exist and refer to transforms between template spaces in one case and transforms between subject and template spaces in the other. Simply to avoid confusion. However, maybe that's just me, haha.

pwighton commented 2 weeks ago

@pwighton —that's exactly the purpose. Yes, both are requirements of any BEP, and the proposal must abide by them.

Thanks @oesteban! With that out of the way, I have a few minor comments:

1) I'm glad to see the cohort entity, but cohort is currently defined as: "A subset of a defined template space". Seems like an odd definition, so I'm wondering if I'm missing something? I'd suggest changing the definition to something like "a sub-population over which an atlas or template was computed"

2) The suggested directory structure looks like:

mni152nlin2009casym-pipeline/
├─ tpl-MNI152NLin2009cAsym/
│  └─ anat/

Just curious what the role of the anat directory is here. Is it required? What do you think this would look like for the PS13 example? There, we have PET data mapped to an anatomical template so would we use anat to signify it is in an anatomical space or pet to signify it is derived from PET data?

3) I think the altas metadata should include Units as a RECOMMENDED feild. I understand metadata came from the previous proposal, so this comment applies to both proposals.

codecov[bot] commented 2 weeks ago

Codecov Report

All modified and coverable lines are covered by tests :white_check_mark:

Project coverage is 87.93%. Comparing base (9baaeec) to head (d15677a).

:exclamation: Current head d15677a differs from pull request most recent head b275ca3

Please upload reports for the commit b275ca3 to get more accurate results.

Additional details and impacted files ```diff @@ Coverage Diff @@ ## bep038 #1856 +/- ## ======================================= Coverage 87.93% 87.93% ======================================= Files 16 16 Lines 1351 1351 ======================================= Hits 1188 1188 Misses 163 163 ```

:umbrella: View full report in Codecov by Sentry.
:loudspeaker: Have feedback on the report? Share it here.

bendhouseart commented 1 week ago

Looking at the example provided for the PS13 Atlas below, I'm wondering if there is anything precluding one from optionally applyingatlas-<label> in the case where there exists only 1 atlas per template space.

First example

``` "ps13-pipeline": { "tpl-fsaverage": { "pet": { "tpl-fsaverage_atlas-ps13_desc-nopvc_dseg.nii.gz": "", "tpl-fsaverage_atlas-ps13_desc-pvc_dseg.nii.gz": "", "tpl-fsaverage_atlas-ps13_dseg.json": "", "tpl-fsaverage_atlas-ps13_dseg.tsv": "", "tpl-fsaverage_desc-nopvc_mimap.json": "", "tpl-fsaverage_desc-nopvc_mimap.nii.gz": "", "tpl-fsaverage_desc-pvc_mimap.json": "", "tpl-fsaverage_desc-pvc_mimap.nii.gz": "", "tpl-fsaverage_hemi-L_den-164k_desc-nopvc_mimap.json": "", "tpl-fsaverage_hemi-L_den-164k_desc-nopvc_mimap.shape.gii": "", "tpl-fsaverage_hemi-L_den-164k_desc-pvc_mimap.json": "", "tpl-fsaverage_hemi-L_den-164k_desc-pvc_mimap.shape.gii": "", "tpl-fsaverage_hemi-L_den-164k_stat-std_desc-nopvc_mimap.json": "", "tpl-fsaverage_hemi-L_den-164k_stat-std_desc-nopvc_mimap.shape.gii": "", "tpl-fsaverage_hemi-L_den-164k_stat-std_desc-pvc_mimap.json": "", "tpl-fsaverage_hemi-L_den-164k_stat-std_desc-pvc_mimap.shape.gii": "", "tpl-fsaverage_hemi-R_den-164k_desc-nopvc_mimap.json": "", "tpl-fsaverage_hemi-R_den-164k_desc-nopvc_mimap.shape.gii": "", "tpl-fsaverage_hemi-R_den-164k_desc-pvc_mimap.json": "", "tpl-fsaverage_hemi-R_den-164k_desc-pvc_mimap.shape.gii": "", "tpl-fsaverage_hemi-R_den-164k_stat-std_desc-nopvc_mimap.json": "", "tpl-fsaverage_hemi-R_den-164k_stat-std_desc-nopvc_mimap.shape.gii": "", "tpl-fsaverage_hemi-R_den-164k_stat-std_desc-pvc_mimap.json": "", "tpl-fsaverage_hemi-R_den-164k_stat-std_desc-pvc_mimap.shape.gii": "", "tpl-fsaverage_stat-std_desc-nopvc_mimap.json": "", "tpl-fsaverage_stat-std_desc-nopvc_mimap.nii.gz": "", "tpl-fsaverage_stat-std_desc-pvc_mimap.json": "", "tpl-fsaverage_stat-std_desc-pvc_mimap.nii.gz": "", }, }, ```

It's not clear to me when the atlas-<label> entity should be applied as is the case in the following example:

Second example

``` "ps13rev2034-pipeline": { "tpl-fsaverage": { "pet": { "tpl-fsaverage_atlas-ps13_desc-nopvc_dseg.nii.gz": "", "tpl-fsaverage_atlas-ps13_desc-pvc_dseg.nii.gz": "", "tpl-fsaverage_atlas-ps13_dseg.json": "", "tpl-fsaverage_atlas-ps13_dseg.tsv": "", "tpl-fsaverage_atlas-ps13_hemi-L_den-164k_desc-nopvc_mimap.json": "", "...": "", "tpl-fsaverage_atlas-ps13_stat-std_desc-pvc_mimap.nii.gz": "", }, }, "tpl-MNI152Lin": { "pet": { "tpl-MNI152Lin_atlas-ps13_desc-nopvc_dseg.nii.gz": "", "tpl-MNI152Lin_atlas-ps13_desc-pvc_dseg.nii.gz": "", "tpl-MNI152Lin_atlas-ps13_dseg.json": "", "tpl-MNI152Lin_atlas-ps13_dseg.tsv": "", "tpl-MNI152Lin_atlas-ps13_res-1p5_desc-spmvbmNopvc_mimap.json": "", "...": "", "tpl-MNI152Lin_atlas-ps13_res-2_stat-std_desc-pvc_mimap.nii.gz": "", "tpl-MNI152Lin_atlas-ps13rev2034_desc-nopvc_dseg.nii.gz": "", "tpl-MNI152Lin_atlas-ps13rev2034_desc-pvc_dseg.nii.gz": "", "tpl-MNI152Lin_atlas-ps13rev2034_dseg.json": "", "tpl-MNI152Lin_atlas-ps13rev2034_dseg.tsv": "", }, } } ```

While I can walk up the file tree to determine that each file in the first example is a part of the PS13 pipeline, I feel that without ps13 being present in the filename it could get a bit confusing as to what tpl-fsaverage*_mimap* is on about.

And, to me, it feels a bit unsatisfying not to have PS13 there as that's the important bit.

Thanks

CPernet commented 1 week ago

Thanks Anthony for catching this. As people develop Atlases they need to be able to name them indeed. If atlas-PS13_mimap works that would be good.

oesteban commented 1 week ago

@bendhouseart As it is written up right now, there's nothing preventing the addition of atlas-ps13 as you indicate. IMHO it is more appropriate not having it because this is the output of a pipeline that clearly has for objective generating template maps and standard deviation maps of the radiotracer uptake - it's not an "atlas" as I understand that.\

I'm happy to add an example remarking that the atlas-ps13 entity can be present in this case if the authors prefer it there.

CPernet commented 1 week ago

@oesteban if you agree I think one should define the entities and the full corresponding namestemplate andatlas in the glossary, this follows on your comment above

has for objective generating template maps and standard deviation maps of the radiotracer uptake - it's not an "atlas" as I understand that

IMO, agreeing on the semantic matters -- for people doing quantitative imaging (R1map, R2map, PET tracers, etc) those averages are called atlases. For instance @jdkent and @melanieganz defined those in the original proposal for instance here https://github.com/jdkent/bids-specification/blob/bep038_jk_edits/src/schema/objects/entities.yaml#atlas

 description: |
    The definition of atlas per Merriam-Webster is ‘a bound collection of maps (i.e. labeled brain regions
    or quantitative aspects) and metadata (tables, or textual matter). Within BIDS, atlases are broadly
    defined as a mapping between locations in a spatial coordinate systems and descriptions associated with
    those locations. Atlases are often build from registering many subjects or maps to a template. By analogy
    with geographical atlases, brain atlases can map brain locations to either discrete labels like a map
    of countries does, or to continuous quantities like a topographic map does.

    This comprises all possible types of atlases, specifically deterministic, probabilistic, and mask/voxel-based
    ones, and quantitative maps from various modalities including but not limited to structural features (e.g.
    myelination, cytoarchitecture), functional features (e.g. resting-state networks, localizers) and such based on
    multimodal data integration (e.g. gene expression, receptors). Furthermore, it covers both volume/voxel and
    surface/vertex data, as well as gray and white matter atlases.

thx - cyril (PS: arrived at COEX so we need to have that beer)

oesteban commented 1 week ago

@oesteban if you agree I think one should define the entities and the full corresponding namestemplate andatlas in the glossary, this follows on your comment above

This came up yesterday when discussing during the BrainHack (cc/ @effigies, @PeerHerholz, @francopestilli and @jdkent to correct me if I say something inaccurate) and it seemed everyone agreed these concepts are best defined in the common principles (as this PR proposes, see 11, 12, and 13 in https://bids-specification--1856.org.readthedocs.build/en/1856/common-principles.html#definitions).

CPernet commented 1 week ago

nice one! thx