Alternative proposal to BEP038

[oesteban]

Rendered proposal: https://bids-specification--1856.org.readthedocs.build/en/1856/derivatives/atlas.html

---

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:

• seg: derived from the original BEP038 proposal
• scale: multi-scale atlases are specified (which is fully lacking in the current draft)

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 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 BEP Proposal: Atlas specification #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]

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]

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

• Don't say atlas-<labelA>..._space-<labelB>..., say tpl-<labelB>/<datatype>/tpl-<labelB>..._atlas-<labelA>....
• Don't create a new atlas DatasetType, use derivative and define four new entities.
• Don't use an atlases/ subdirectory in the dataset root to store atlases.

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>: The name of a template, which has the same status as (and is mutually exclusive with) sub-<label>, to be used when data have been sampled to some space <label> and then combined across subjects.
• atlas-<label>: The name of an atlas, which is simply a name canonically associated with a collection of files.
• seg-<label>: A specific segmentation, if an atlas defines (or is commonly used to define) more than one segmentation.
• scale-<label>: A further specifier, if an atlas defines segmentations at multiple spatial scales.

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]

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]

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]

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:

• Atlas generation
• Atlas application/consumption

(as is the case with many/all derivatives)

And an atlas can be created at either the:

• group level (incorporating multiple participants' data)
• individually (using only a single participant's data)

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]

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]

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:

• Being able to share an atlas as a standalone dataset
• Being able to validate an atlas

Would this proposal be able accommodate that?

[oesteban]

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.

[PeerHerholz]

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?

[oesteban]

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]

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.

[oesteban]

@PeerHerholz this is the mention.

I didn't want to explicitly get down the from- / to- issue because that has great potential to change (or establish some extra rules so that it is unambiguous).

[pwighton]

@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.

[francopestilli]

Thank you for all the proposed changes @oesteban! We have made comments throughout and except for these minor comments we think it is ready for community review by @effigies @PeerHerholz @jdkent @francopestilli @pwighton @bendhouseart

@PeerHerholz, shall we meet and go over this? This might unlock the BEP and wrap up one component of the project. I am excited about this possibility!

[pwighton]

I've reviewed the changes to the proposal. Thank-you to @oesteban for the updates and to everyone else who's worked on this.

My biggest questions relate to the definitions of space, template and atlas. I'd be very happy to make a push or PR to clarify the proposal, but would like to seek alignment first.

I'll start with the definition of space since I'm expecting it to be the easiest to align on.

Space

The proposed definition for space is:

Space (PR1856) - A reference coordinate system of analysis engendered by the spatiotemporal distribution of neuroimaging features such as those given by subjects' and templates' data.

I would suggest changing to:

Space (PR1856-PW) - A coordinate system of analysis given by subjects' data or the aggregation thereof. Every image file defines it's own space, which is commonly referred to as "the native space of xyz". When a new space is deliberately created, it is done by creating a template which serves as the authoritative definition of that space. The template name MUST match the name of the space it is defining.

I think this would clarify the relationship between space and template and formalize it with 'MUST' language.

Template

The proposed definition of template is:

Template (PR1856) - An average feature map obtained by aggregation of subjects and/or sessions that allows the spatial location of brain anatomy and function of the templated cohort. Templates operationalize the concept of standardized spatial frame of analysis, a common Space in which subjects' data can be spatially-normalized into for group inference. Like subjects' feature maps generate a native spatial frame of reference for analyses, templates engender a generic or standard space of analysis were subjects can be spatiotemporally aligned into. In other words, templates (that is, specific feature maps) are authoritative definitions of spaces in that they instantiate the abstract concept of space.

I would suggest changing to:

Template (PR1856-PW) - Imaging data, or the aggregation thereof, that MUST serve as the authoritative definition of a space. The template name MUST match the name of the space it is defining. Templates operationalize the concept of standardized spatial frame of analysis, a common Space in which subjects' data can be spatially-normalized into for group inference. Like subjects' feature maps generate a native spatial frame of reference for analyses, templates engender a generic or standard space of analysis were subjects can be spatiotemporally aligned into. In other words, templates (that is, specific feature maps) are authoritative definitions of spaces in that they instantiate the abstract concept of space.

Here, I'm trying to leave the definition unchanged, but formalize it with MUST language.

Atlas

The proposed definition for atlas is:

Atlas (PR1856) - Knowledge about the brain, generally formalized with reference to a standard space (see the Template definition above) by means of spatiotemporal annotations such as landmarks, segmentations, parcellations, or probability maps. One prominent manuscript regarding the specific aspects of atlases, such as their regional resolution, is Bijsterbosch et al. (2020). To further differentiate the concept of atlas and template throughout the specification, template will designate a standardized stereotaxy frame where some feature or features are mapped through spatial normalization and then possibly averaged. Conversely, atlas will designate a specific methodology or algorithm to create meaningful knowledge annotations about the brain such as landmarks or segmentations.

I'm tying to work through the implications this definition has on the PS13 use case. Would a neuronal density map, or say a quantitative T1 map, be considered an atlas? If 'yes', then I think the language from the original BEP-038 proposal makes that more clear.

The original BEP-038 proposed definition for atlas:

Atlas (PR1714) - 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.

If a neuronal density map or quantitative t1 map would be considered an atlas, then a minimal change to 'Atlas (PR1856)' that would clarify that would be:

Atlas (PR1856-PW) - Knowledge about the brain, generally formalized with reference to a standard space (see the Template definition above) by means of spatiotemporal annotations such as landmarks, segmentations, parcellations, probability maps, density maps or other quantitative maps. One prominent manuscript regarding the specific aspects of atlases, such as their regional resolution, is Bijsterbosch et al. (2020). Atlases are the result of a specific methodology or algorithm to create meaningful knowledge about the brain.

If a neuronal density map or quantitative t1 map would not be considered an atlas, then I think some other term would be required since it's not a template (it doesn't define a space; it uses a pre-existing space) nor an atlas.

[pwighton]

@oesteban, @mnoergaard and I met last week to discuss this proposal. I've proposed some revisions based off of that discussion which are here

[PeerHerholz]

Hey everyone,

thanks @pwighton, @mnoergaard and @oesteban for your continued work on this.

Would the idea be that the proposed changes are merged into @oesteban's fork and branch to update this PR respectively?

Thanks again.

Best, Peer

[pwighton]

Would the idea be that the proposed changes are merged into @oesteban's fork and branch to update this PR respectively?

Yes @PeerHerholz, that was my intention.

[PeerHerholz]

Hey @pwighton,

awesome, thanks so much!

Best, Peer

[PeerHerholz]

Hey everyone,

just wanted to ask re the current status of this and if I could be of any help?

Best, Peer

[oesteban]

I've been away this week, I'll try to allocate time next week asap. Thanks @pwighton and @bendhouseart for the time you took in revising this :)

[pwighton]

I've updated the PR based on feedback by @bendhouseart and @mnoergaard.

Once everyone has had a chance to review it, should we try to setup a zoom meeting with @PeerHerholz, @oesteban, @mnoergaard, @bendhouseart and any other interested parties? I think we could align and iterate much faster with periodic zoom calls.

[PeerHerholz]

Hey everyone,

sounds great. Thanks so much for your continued work and effort!
Do you think it would be possible to have a meeting before the holiday season?

Thanks again.

Best, Peer

[pwighton]

That would be great! I'm available up to Tues Dec 17th.

[oesteban]

For those parties interested, please fill your availability at http://whenisgood.net/rrnttg4

[oesteban]

@pwighton @mnoergaard @effigies let's meet on Friday (details for your timezone here)

everyone is welcome to join :)

[PeerHerholz]

Hey folks,

I won't be able to make the meeting due to childcare.
However, please let me know if I can be of any help.

Best, Peer

[PeerHerholz]

Hey everyone,

I just wanted to ask how the meeting went and if it would be possible to get a brief summary, as well as if there are any tasks I could/should work on?

Best, Peer

[oesteban]

@PeerHerholz we had a productive meeting. We discussed the main sticking points and found clearer ways of describing the two contended entities (tpl- and atlas-). Based on those discussions, @pwighton will create a new PR as soon as time and workload permit. We also thought that having more regular meetings (perhaps bi-weekly) starting in January will help push this forward. The feeling is that we are very close to wrapping up and final submission.

EDIT: we had also a very productive exchange regarding when a new tpl- should be issued, in the case data are aligned into a pre-existing template space (e.g., fsaverage). We will also work making this clearer in the spec.

Am I missing something? @effigies @mnoergaard

[pwighton]

Yes, I've just closed my PR and will pefrom another review and open a new PR after the holidays. I'm still a bit unclear on what the formal definition of an atlas and template will be. My understanding right now is:

• template: An aggregation of continuous- or discreet- valued data that MAY serve as the authoritative definition of a space
• atlas: A collection of related templates

@oesteban, let me know if those definitions seem like a good starting point for the review.

I agree that regular meetings will be very helpful in finalizing this BEP and I'm looking forward to discussing this with you all in the new year.