first draft of general conventions page #26

PeerHerholz · 2023-10-19T14:18:49Z

This PR and the respective commits aim to introduce a first draft of a new page/section concerning general conventions for BEP development. This was discussed here and addresses this issue.

To this end, a new page called "General conventions" is introduced within/from which specific conventions are included/linked. In the current form, parts of the original discussion/proposal were copy-pasted and adapted within a section called "general conventions for spatial derivatives".

Adding @dlevitas to this endeavor.

This PR and the respective commits aim to introduce a first draft of a new page/section concerning general conventions for BEP development. This was discussed [here](bids-standard/bids-specification#1602) and addresses [this issue](bids-standard#24). To this end, a new page called "General conventions" is introduced within/from which specific conventions are included/linked. In the current form, parts of the original discussion/proposal were copy-pasted and adapted within a section called "general conventions for spatial derivatives".

PeerHerholz · 2023-11-02T09:15:08Z

Hi folks,

I just wanted to ask if someone had any thoughts re this (@bids-standard/steering, @bids-standard/maintainers)?

Thanks again.

Cheers, Peer

yarikoptic

I think it is worth

unify to "guidelines" (renaming of the file is due to then)
separate out "general" from "BEP specific" (or come up with some other term) guidelines. I gave examples of a few generic guidelines, we could add more.

docs/general_conventions.md

yarikoptic · 2023-11-02T14:39:36Z

docs/general_conventions.md

+
+Based on the evergrowing set of `BEP`s and the respective work and efforts conducted to develop them, the community has identified a set of general conventions that can be used to guide the corresponding processes. These conventions are not part of the [BIDS specification](https://bids-specification.readthedocs.io/en/stable/index.html), but rather a set of guidelines that are recommended to be followed when developing a `BEP`. These conventions are not set in stone and can be modified as needed. However, we recommend that any changes to these conventions be discussed with the `BIDS community` before being implemented. The guidelines are thus RECOMMENDED, not REQUIRED, in that `BEP`s would be allowed to deviate when deemed necessary. The goal is to establish consensus so that parts of `BEP`s that propose terms in line with guidelines will be considered accepted in principle. 
+
+## General conventions for spatial derivatives


By General conventions I envision conventions General to all BEPs, and that is what suggested in opening paragraph. Here it seems that conventions are already more specific, and thus not General. Let's place them into a separate section?

Suggested change

## General conventions for spatial derivatives

# BEP specific guidelines

Sometimes multiple BEPs touch upon an aspect which is relevant to all of them.

## Guidelines for spatial derivatives

IIRC the idea was to work on and formalize conventions that would apply across multiple BEPs based on their respective modality and/or included analyses. Thus, the structure would be: general conventions independent of modality/analyses -> modality/analyses-specific conventions and therefore, there wouldn't be a BEP specific section. However, I could of course be wrong re this.

They're not exactly BEP-specific, but they are decisions that were triggered by the needs specific BEPs. Possibly there's a better heading, but I'm okay with separating out universal and more narrowly targeted guidelines.

docs/general_conventions.md

PeerHerholz · 2023-11-06T10:29:50Z

Hi everyone,

thx @yarikoptic for the feedback and input, that's highly appreciated!

@francopestilli, @arokem, @effigies, @oesteban: as the other authors of the initial proposal, what do you think about the proposed changes?

Cheers, Peer

sappelhoff · 2023-11-06T10:39:27Z

docs/general_conventions.md

@@ -0,0 +1,52 @@
+# BEP general conventions
+
+Based on the evergrowing set of `BEP`s and the respective work and efforts conducted to develop them, the community has identified a set of general conventions that can be used to guide the corresponding processes. These conventions are not part of the [BIDS specification](https://bids-specification.readthedocs.io/en/stable/index.html), but rather a set of guidelines that are recommended to be followed when developing a `BEP`. These conventions are not set in stone and can be modified as needed. However, we recommend that any changes to these conventions be discussed with the `BIDS community` before being implemented. The guidelines are thus RECOMMENDED, not REQUIRED, in that `BEP`s would be allowed to deviate when deemed necessary. The goal is to establish consensus so that parts of `BEP`s that propose terms in line with guidelines will be considered accepted in principle. 


this should be reformatted to start a new line after each sentence (~semantic line breaks https://sembr.org/)

also below and throughout this document --> it will result in a cleaner git diff in the future :-)

sappelhoff

Thanks Peer, I agree with the proposed additions in general, but cannot really make a statement about the spatial derivatives in particular, because I lack expertise in that domain.

effigies · 2023-11-06T14:13:08Z

I'm okay with the text in general, and I don't think we need to be overly fussy about wording in this repo so long as there are not glaring inconsistencies with what was decided. We can always propose clarifying updates.

I think it would be easier for me to make concrete suggestions if you accept (with modifications, if you like) Yarik's changes and add line breaks. Right now it's hard not to conflict.

PeerHerholz · 2023-11-06T14:38:24Z

Thx @sappelhoff and @effigies,

I will accept the changes to streamline further feedback.

@yarikoptic

Simplify intro and add line breaks as suggested by @yarikoptic. Co-authored-by: Yaroslav Halchenko <[email protected]>

@yarikoptic

Change wording from "conventions" to "guideline" as suggest by @yarikoptic. Co-authored-by: Yaroslav Halchenko <[email protected]>

@yarikoptic

Add section re general guidelines/recommendations as suggested by @yarikoptic. Co-authored-by: Yaroslav Halchenko <[email protected]>

mkdocs.yml

rename general_conventions.md to general_guidelines.md Co-authored-by: Yaroslav Halchenko <[email protected]>

@yarikoptic

rename general_conventions.md to general_guidelines.md as suggested by @yarikoptic.

oesteban

A fast first pass addressing some stylistic issues (e.g. start new sentences with new line) and minor comments here and there.

I find the use of backticks to emphasize acronyms and words distracting.

oesteban · 2023-11-07T10:26:41Z

docs/general_guidelines.md

@@ -0,0 +1,67 @@
+# BEP general guidelines
+
+Based on the evergrowing set of `BEP`s and the respective work and efforts conducted to develop them, the community has identified a set of general guidelines that can be used to guide the corresponding processes.


Does the mkdocs accept abbreviations? Because the backticks use here feels annoying to me.

(it's a nitpick anyways)

oesteban · 2023-11-07T10:28:09Z

docs/general_guidelines.md

+
+Based on the evergrowing set of `BEP`s and the respective work and efforts conducted to develop them, the community has identified a set of general guidelines that can be used to guide the corresponding processes.
+These guidelines are not part of the [BIDS specification](https://bids-specification.readthedocs.io/en/stable/index.html), but rather are recommended to be followed when developing a `BEP`.
+These guidelines are not set in stone and can be modified as needed.


This comment would need further elaboration w.r.t. stated rules and guidelines policing the process of modification. Otherwise, remove.

Did we have some additional information re this? Also asking @yarikoptic, @arokem and @francopestilli?

I agree that this is not necessary unless we have something more explicit to say here (I don't think we do)

docs/general_guidelines.md

oesteban · 2023-11-07T10:32:19Z

docs/general_guidelines.md

+## Facilitate atomic changes
+
+See [issue #371](https://github.com/bids-standard/bids-specification/issues/371) for motivation and discussion.
+It is recommended to identify perspective entities and metadata fields to be added, and research if they, or their synonyms, are  already considered in submitted PRs or other BEPs.


Perhaps who or how to keep track of other PRs and BEPs would be necessary.

How about the BEP leads are responsible for this and the maintainers verify?

docs/general_guidelines.md

CPernet · 2023-11-08T07:28:15Z

sorry to jump in late but if 'These guidelines are not part of the [BIDS specification](https://bids-specification.readthedocs.io/en/stable/index.html), but rather are recommended to be followed when developing a BEP. why is it to be merged in the BIDS specification, i.e. /docs? and not merged to /bids-extensions (IMO this either goes into spec derivatives and it is part of the spec or goes to extension -- please no new section)

Add line breaks and rephrasing. Co-authored-by: Oscar Esteban <[email protected]>

Add line breaks. Co-authored-by: Oscar Esteban <[email protected]>

PeerHerholz · 2023-11-08T10:48:27Z

Hi @CPernet,

sorry if I did something wrong but this should merge into /bids-extensions, ie here as indicated above.

Co-authored-by: Oscar Esteban <[email protected]>

This commit adds line breaks in the introduction and removes a sentence regarding diverging from the guidelines (as no respective process was discussed/provided).

PeerHerholz · 2023-11-20T10:27:28Z

Hi everyone,

would the current status be ok re merging?

Cheers, Peer

effigies

Apologies for the slow response. I think this is overall good. A small comment on an evolution of BEP 23 that I wasn't aware of when we wrote up the initial draft.

docs/general_guidelines.md

@effigies

Update to latest status of BEP23, ie `mimap`s and `stat-`mean/`std` maps as suggested by @effigies. Co-authored-by: Chris Markiewicz <[email protected]>

Based on recent additions to the BIDS extensions principles in bids-standard/bids-extensions#26. Along the way, we follow the inheritance principle by reducing the number of metadata files in each directory to one per model, across all of the model parameters, and eliminating the distinction between model fit and model derived parameters.

PeerHerholz mentioned this pull request Oct 19, 2023

Incorporate general conventions for spatial derivatives #24

Closed

yarikoptic requested changes Nov 2, 2023

View reviewed changes

sappelhoff reviewed Nov 6, 2023

View reviewed changes

PeerHerholz and others added 3 commits November 6, 2023 15:39

Update docs/general_conventions.md

005d4de

Simplify intro and add line breaks as suggested by @yarikoptic. Co-authored-by: Yaroslav Halchenko <[email protected]>

Update docs/general_conventions.md

9866692

Change wording from "conventions" to "guideline" as suggest by @yarikoptic. Co-authored-by: Yaroslav Halchenko <[email protected]>

Update docs/general_conventions.md

1eb757f

Add section re general guidelines/recommendations as suggested by @yarikoptic. Co-authored-by: Yaroslav Halchenko <[email protected]>

yarikoptic reviewed Nov 6, 2023

View reviewed changes

mkdocs.yml Outdated Show resolved Hide resolved

PeerHerholz and others added 2 commits November 7, 2023 11:07

Update mkdocs.yml

4f5b373

rename general_conventions.md to general_guidelines.md Co-authored-by: Yaroslav Halchenko <[email protected]>

Rename general_conventions.md to general_guidelines.md

fe3de8c

rename general_conventions.md to general_guidelines.md as suggested by @yarikoptic.

oesteban reviewed Nov 7, 2023

View reviewed changes

PeerHerholz and others added 8 commits November 8, 2023 11:42

Update docs/general_guidelines.md

88fe9d4

Add line breaks and rephrasing. Co-authored-by: Oscar Esteban <[email protected]>

Update docs/general_guidelines.md

c8d7e26

Add line breaks and rephrasing. Co-authored-by: Oscar Esteban <[email protected]>

Update docs/general_guidelines.md

965a9cc

Add line breaks. Co-authored-by: Oscar Esteban <[email protected]>

Update docs/general_guidelines.md

d287cc5

Add line breaks. Co-authored-by: Oscar Esteban <[email protected]>

Update docs/general_guidelines.md

e1ef67e

Add line breaks. Co-authored-by: Oscar Esteban <[email protected]>

Update docs/general_guidelines.md

e810d4a

Add line breaks. Co-authored-by: Oscar Esteban <[email protected]>

Update docs/general_guidelines.md

8b85b15

Add line breaks. Co-authored-by: Oscar Esteban <[email protected]>

Update docs/general_guidelines.md

7d27b36

Add line breaks. Co-authored-by: Oscar Esteban <[email protected]>

PeerHerholz and others added 3 commits November 16, 2023 10:46

Merge branch 'main' into general_conventions

834a291

Update docs/general_guidelines.md

64202c3

Co-authored-by: Oscar Esteban <[email protected]>

update general_guidelines.md

2dd9a79

This commit adds line breaks in the introduction and removes a sentence regarding diverging from the guidelines (as no respective process was discussed/provided).

effigies approved these changes Nov 22, 2023

View reviewed changes

docs/general_guidelines.md Outdated Show resolved Hide resolved

Update docs/general_guidelines.md

894e46b

Update to latest status of BEP23, ie `mimap`s and `stat-`mean/`std` maps as suggested by @effigies. Co-authored-by: Chris Markiewicz <[email protected]>

effigies merged commit 6c4c65c into bids-standard:main Nov 27, 2023

PeerHerholz mentioned this pull request Dec 19, 2023

BEP016 finalization bids-standard/bids-bep016#89

Open

4 tasks

arokem mentioned this pull request Mar 12, 2024

[DWI] How to encode ADC/TRACE volumes? bids-standard/bids-specification#1723

Closed

arokem mentioned this pull request Mar 29, 2024

WIP: Propose new mechanism to record metadata across separate data files, incorporate use of dwimap bids-standard/bids-bep016#90

Closed

yarikoptic mentioned this pull request Mar 30, 2024

[ENH] Add explicit wording on DICOM terms correspondence bids-standard/bids-specification#1450

Merged

2 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

first draft of general conventions page #26

first draft of general conventions page #26

PeerHerholz commented Oct 19, 2023 •

edited

Loading

PeerHerholz commented Nov 2, 2023

yarikoptic left a comment

yarikoptic Nov 2, 2023

PeerHerholz Nov 6, 2023

effigies Nov 6, 2023

PeerHerholz commented Nov 6, 2023

sappelhoff Nov 6, 2023

sappelhoff Nov 6, 2023

sappelhoff left a comment

effigies commented Nov 6, 2023 •

edited

Loading

PeerHerholz commented Nov 6, 2023

oesteban left a comment

oesteban Nov 7, 2023

oesteban Nov 7, 2023

oesteban Nov 7, 2023

PeerHerholz Nov 8, 2023

arokem Nov 8, 2023

oesteban Nov 7, 2023

PeerHerholz Nov 8, 2023

CPernet commented Nov 8, 2023 •

edited

Loading

PeerHerholz commented Nov 8, 2023

PeerHerholz commented Nov 20, 2023

effigies left a comment


		Based on the evergrowing set of `BEP`s and the respective work and efforts conducted to develop them, the community has identified a set of general conventions that can be used to guide the corresponding processes. These conventions are not part of the [BIDS specification](https://bids-specification.readthedocs.io/en/stable/index.html), but rather a set of guidelines that are recommended to be followed when developing a `BEP`. These conventions are not set in stone and can be modified as needed. However, we recommend that any changes to these conventions be discussed with the `BIDS community` before being implemented. The guidelines are thus RECOMMENDED, not REQUIRED, in that `BEP`s would be allowed to deviate when deemed necessary. The goal is to establish consensus so that parts of `BEP`s that propose terms in line with guidelines will be considered accepted in principle.

		## General conventions for spatial derivatives

-## General conventions for spatial derivatives
+# BEP specific guidelines
+Sometimes multiple BEPs touch upon an aspect which is relevant to all of them.
+## Guidelines for spatial derivatives

		@@ -0,0 +1,52 @@
		# BEP general conventions

		Based on the evergrowing set of `BEP`s and the respective work and efforts conducted to develop them, the community has identified a set of general conventions that can be used to guide the corresponding processes. These conventions are not part of the [BIDS specification](https://bids-specification.readthedocs.io/en/stable/index.html), but rather a set of guidelines that are recommended to be followed when developing a `BEP`. These conventions are not set in stone and can be modified as needed. However, we recommend that any changes to these conventions be discussed with the `BIDS community` before being implemented. The guidelines are thus RECOMMENDED, not REQUIRED, in that `BEP`s would be allowed to deviate when deemed necessary. The goal is to establish consensus so that parts of `BEP`s that propose terms in line with guidelines will be considered accepted in principle.

		@@ -0,0 +1,67 @@
		# BEP general guidelines

		Based on the evergrowing set of `BEP`s and the respective work and efforts conducted to develop them, the community has identified a set of general guidelines that can be used to guide the corresponding processes.

first draft of general conventions page #26

first draft of general conventions page #26

Conversation

PeerHerholz commented Oct 19, 2023 • edited Loading

PeerHerholz commented Nov 2, 2023

yarikoptic left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

PeerHerholz commented Nov 6, 2023

Choose a reason for hiding this comment

Choose a reason for hiding this comment

sappelhoff left a comment

Choose a reason for hiding this comment

effigies commented Nov 6, 2023 • edited Loading

PeerHerholz commented Nov 6, 2023

oesteban left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

CPernet commented Nov 8, 2023 • edited Loading

PeerHerholz commented Nov 8, 2023

PeerHerholz commented Nov 20, 2023

effigies left a comment

Choose a reason for hiding this comment

PeerHerholz commented Oct 19, 2023 •

edited

Loading

effigies commented Nov 6, 2023 •

edited

Loading

CPernet commented Nov 8, 2023 •

edited

Loading