[FIX] clarify participants tsv+json with examples and recommendations #459

sappelhoff · 2020-04-29T09:16:17Z

first step towards #458

This PR is intended as a fast intervention to improve the documentation about our participants.tsv.

It's my intention that all changes made here merely clarify and do not prevent us from taking one of the other actions discussed in #458. Yet, I think it's good to make some immediate small improvements and simultaneously think about and discuss long-term higher impact improvements.

This PR is implementing a mix of the suggestions I made in these comments:

In particular, I:

say that age, sex, handedness are often used and we thus recommend (!) some values for them
stress that a participants.json is highly RECOMMENDED
add examples and link to other existing sections

these changes combined with reverting the validator change in bids-standard/bids-validator#905 that @rwblair said he will do in #458 (comment) will hopefully lead to more sane BIDS participants.tsv and json files. --> this will lead to validator WARNINGS when participant.json files are missing.

I agree that there remains much to do, let's keep discussing the general issue in #458 and use this PR to discuss how to make a pragmatic fast-but-small improvement.

Rendered draft

https://2338-150465237-gh.circle-artifacts.com/0/site/03-modality-agnostic-files.html#participants-file

src/03-modality-agnostic-files.md

nicholst · 2020-04-29T10:38:57Z

New thought: Age in perinatal populations.

Having just examined a dissertation on imaging of neonates, I learned that there are no less than 4 notions of age used: Gestational age, postmenstrual age, chronological age & corrected age. These are defined in a Policy Statement from the American Academy of Pediatrics (Blackmon et al. (2004)).

According to Table 1 of the policy, typical time units vary for each (weeks is used by all measures, months or years is used mainly with chronological and postmenstrual age).

I was about to suggest an edit but I'm not sure where to put it.

Do we say

For perinatal subjects, please do not use age, but instead define a variable, one of gestational_age, postmenstrual_age, chronological_age or corrected_age, but with time units of years.

Or do we just add to the current age guidelines:

age: numeric value in years (float or integer value). For perinatal subjects, age must still be in years, and the type of age stored in the JSON file, one of gestational age, postmenstrual age, chronological age or corrected age, as per Blackmon et al. (2004).

Reference

Blackmon, L. R., Batton, D. G., Bell, E. F., Denson, S. E., Engle, W. A., Kanto, W. P., … Stark, A. (2004). Age terminology during the perinatal period. Pediatrics, 114(5), 1362–1364. https://doi.org/10.1542/peds.2004-1915

src/03-modality-agnostic-files.md

satra · 2020-04-29T11:01:49Z

@nicholst - this came up in the main discussion. i have added some wording to this change at least to enumerate that issue.

jasmainak · 2020-04-29T14:58:21Z

src/03-modality-agnostic-files.md

-compulsory column `participant_id` that consists of `sub-<label>`,
-followed by a list of optional columns describing participants. Each participant
-needs to be described by one and only one row.
+    -   for "female", use one of these values: `female`, `f`, `F`, `FEMALE`,


do we need to use the keyword MUST here?

see some lines above We RECOMMEND to use the following values

src/03-modality-agnostic-files.md

jasmainak · 2020-04-29T15:05:15Z

src/03-modality-agnostic-files.md

+optional columns are defined beyond `age`, `sex`, and `handedness`, such as
+`group` in this example.
+
+`participants.json` example:


is the rationale for having this sidecar file described elsewhere in the document? In the example below, it's not clear to me how one would write the "Levels". Also, why is this even needed when you already have a restricted set of values or age and sex?

yes I link to a section where this is described in the sentence above [section on tabular files](02-common-principles.md#tabular-files))

Also, why is this even needed when you already have a restricted set of values or age and sex

with this PR, we only RECOMMEND, not REQUIRE --> as I say in the PR intro, the changes here are a first step that should be ok with both sides of the discussion (those that want to have it strict, and those who want to have it lenient or relating to other standards/ontologies)

we need to discuss in the related issue on how to improve things further.

okay fair enough. Let's continue the discussion in another issue/PR!

jasmainak · 2020-04-29T15:06:00Z

Thanks a lot @sappelhoff for taking a stab at this

nicholst

Looks good, especially with @satra's edit to clarify age as chronological age.

src/03-modality-agnostic-files.md

Co-Authored-By: Richard Höchenberger <richard.hoechenberger@gmail.com> Co-Authored-By: Satrajit Ghosh <satrajit.ghosh@gmail.com>

dorahermes · 2020-04-30T13:46:29Z

Will there be a standard option in handedness for ambidexter?

sappelhoff · 2020-04-30T14:26:50Z

Will there be a standard option in handedness for ambidexter?

If this PR were to be merged, we would RECOMMEND one of a, A, ambidextrous, Ambidextrous, or AMBIDEXTROUS

dorahermes · 2020-04-30T14:35:57Z

Thanks for clarifying!

sappelhoff · 2020-05-06T13:49:22Z

@nicholst @satra @dorahermes @hoechenberger if you approve of this "first step PR" in its current state, we can merge it.

overall discussion will continue in #458

nicholst

Looks good!

* origin/master: (404 commits) [DOC] Auto-generate changelog entry for PR bids-standard#460 Apply suggestions from code review label -> index drop _part-, introduce _split- [DOC] Auto-generate changelog entry for PR bids-standard#459 [DOC] Auto-generate changelog entry for PR bids-standard#465 fix table Update src/99-appendices/06-meg-file-formats.md [DOC] Auto-generate changelog entry for PR bids-standard#441 inject _part into MEG spec update entity table FIX: clarify _part Apply suggestions from code review FIX: clarify participants tsv [DOC] Auto-generate changelog entry for PR bids-standard#457 Update Release_Protocol.md add pdf steps for release protocol FIX: remove BESA from list of restricted keywords Remove trailing space Add reference to PDF on front page of specification ... Conflicts: src/02-common-principles.md - had to meld with my previous wording etc.

* upstream/master: (113 commits) [DOC] Auto-generate changelog entry for PR bids-standard#152 [DOC] Auto-generate changelog entry for PR bids-standard#467 Specify that suffix must be alphanumeric ENH: make NOT RECOMMENDED stronger (SHOULD NOT) for zero padding for uniqueness ENH: Include leading . within definition of the file extension ENH: provide an example for a suffix based on an _eeg.vhdr filename [DOC] Auto-generate changelog entry for PR bids-standard#477 [DOC] Auto-generate changelog entry for PR bids-standard#460 Also ignore users urls on github Quote regexp in command line [INFRA] linkchecker - ignore github pull and tree URLs Apply suggestions from code review replace purview with scope label -> index Apply suggestions from code review drop _part-, introduce _split- Apply SA feedback and amended to purview [DOC] Auto-generate changelog entry for PR bids-standard#459 Add Domain Expert to Maintainers Group [DOC] Auto-generate changelog entry for PR bids-standard#465 ...

sappelhoff force-pushed the agesex branch from 6ed4550 to 9353ce9 Compare April 29, 2020 09:23

hoechenberger reviewed Apr 29, 2020

View reviewed changes

src/03-modality-agnostic-files.md Outdated Show resolved Hide resolved

FIX: clarify participants tsv

9eac317

sappelhoff force-pushed the agesex branch from 9353ce9 to 9eac317 Compare April 29, 2020 09:34

sappelhoff changed the title ~~FIX: clarify participants tsv~~ [FIX] clarify participants tsv Apr 29, 2020

sappelhoff requested review from effigies, franklin-feingold, jasmainak, nicholst, rwblair and satra April 29, 2020 09:39

satra reviewed Apr 29, 2020

View reviewed changes

src/03-modality-agnostic-files.md Outdated Show resolved Hide resolved

satra reviewed Apr 29, 2020

View reviewed changes

src/03-modality-agnostic-files.md Outdated Show resolved Hide resolved

jasmainak reviewed Apr 29, 2020

View reviewed changes

src/03-modality-agnostic-files.md Show resolved Hide resolved

jasmainak reviewed Apr 29, 2020

View reviewed changes

nicholst previously approved these changes Apr 29, 2020

View reviewed changes

rwblair mentioned this pull request Apr 29, 2020

remove age sex from non custom columns list for participants tsv. bids-standard/bids-validator#949

Merged

sappelhoff commented Apr 30, 2020

View reviewed changes

src/03-modality-agnostic-files.md Outdated Show resolved Hide resolved

Apply suggestions from code review

8a2dc1d

Co-Authored-By: Richard Höchenberger <richard.hoechenberger@gmail.com> Co-Authored-By: Satrajit Ghosh <satrajit.ghosh@gmail.com>

sappelhoff dismissed nicholst’s stale review via 8a2dc1d April 30, 2020 08:01

jasmainak approved these changes Apr 30, 2020

View reviewed changes

sappelhoff changed the title ~~[FIX] clarify participants tsv~~ [FIX] clarify participants tsv+json with examples and recommendations May 4, 2020

satra approved these changes May 6, 2020

View reviewed changes

nicholst approved these changes May 6, 2020

View reviewed changes

sappelhoff merged commit 41e2214 into bids-standard:master May 12, 2020

sappelhoff deleted the agesex branch May 12, 2020 17:34

bids-maintenance added a commit that referenced this pull request May 12, 2020

[DOC] Auto-generate changelog entry for PR #459

8a17471

yarikoptic mentioned this pull request Oct 18, 2023

Formalize participants' age to actually allow for other than year units/durations #1633

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[FIX] clarify participants tsv+json with examples and recommendations #459

[FIX] clarify participants tsv+json with examples and recommendations #459

sappelhoff commented Apr 29, 2020 •

edited

Loading

nicholst commented Apr 29, 2020

satra commented Apr 29, 2020

jasmainak Apr 29, 2020

sappelhoff Apr 30, 2020

jasmainak Apr 29, 2020

sappelhoff Apr 30, 2020

jasmainak Apr 30, 2020

jasmainak commented Apr 29, 2020

nicholst left a comment

dorahermes commented Apr 30, 2020

sappelhoff commented Apr 30, 2020

dorahermes commented Apr 30, 2020

sappelhoff commented May 6, 2020

nicholst left a comment

[FIX] clarify participants tsv+json with examples and recommendations #459

[FIX] clarify participants tsv+json with examples and recommendations #459

Conversation

sappelhoff commented Apr 29, 2020 • edited Loading

Rendered draft

nicholst commented Apr 29, 2020

satra commented Apr 29, 2020

jasmainak Apr 29, 2020

Choose a reason for hiding this comment

sappelhoff Apr 30, 2020

Choose a reason for hiding this comment

jasmainak Apr 29, 2020

Choose a reason for hiding this comment

sappelhoff Apr 30, 2020

Choose a reason for hiding this comment

jasmainak Apr 30, 2020

Choose a reason for hiding this comment

jasmainak commented Apr 29, 2020

nicholst left a comment

Choose a reason for hiding this comment

dorahermes commented Apr 30, 2020

sappelhoff commented Apr 30, 2020

dorahermes commented Apr 30, 2020

sappelhoff commented May 6, 2020

nicholst left a comment

Choose a reason for hiding this comment

sappelhoff commented Apr 29, 2020 •

edited

Loading