[ENH] BEP036 - Phenotypic Data Guidelines

[ericearl]

The BEP leads can meet as-needed to discuss this BEP PR

Coordinate a meeting by emailing Eric Earl: eric.earl.nih@gmail.com.

Communicate on this PR to provide feedback otherwise.

HTML preview of this BEP

BEP036 brings guidelines for best tabular phenotypic data to the BIDS specification.

• Includes an appendix called phenotype.md
• Includes a new AdditionalValidation key for the dataset_description.json, for which the usage is described in the modality agnostic files sections
• Includes the new option to store session_id as the second column in the participants.tsv

Additional Links

1. Original Google Doc
2. Draft BIDS Validator errors and warnings
3. BIDS Examples PR

---

Co-authored-by: Eric Earl eric.earl@nih.gov @ericearl
Co-authored-by: Samuel Guay samuel.guay@umontreal.ca @SamGuay
Co-authored-by: Sebastian Urchs sebastian.urchs@mcgill.ca @surchs
Co-authored-by: Arshitha Basavaraj arshitha.basavaraj@iiitb.ac.in @Arshitha

[surchs]

Copying from https://github.com/surchs/bids-specification/pull/1/files#r2103117486

For this section, would it make sense to suggest that demo-like information be prioritized in this file rather than participants.tsv, making the latter primarily a list of subject IDs? I haven't seen this explicitly addressed anywhere, though I'm unsure if it's something we want to formalize 😬
Something like this could follow the paragraph?:

When all demographic data is stored in phenotype/demographics.tsv, participants.tsv may serve primarily as a minimal listing of subject identifiers with only the participant_id column.

[Arshitha]

I agree. It'd be good to mention this.

[timdressler]

Hi, I am new to commenting a PR and also relatively new to BIDS - so my comment might be stupid.

However, I want to draw attention to a potential issue with the handling repeated usage of a phenotype/ measurement. Currently, if a measurement is conducted more than once, a run_id column MUST be added that "corresponds to an existing run- entity used in a filename(s)" (https://bids-specification--2123.org.readthedocs.build/en/2123/modality-agnostic-files/phenotypic-and-assessment-data.html).

However, in my case (and I guess many others), a phenotype measurement tool might be conducted independently of a run in an experimental task. For example, I conduct a mood questionnaire 7 times over the course of one session in which multiple tasks (with multiple runs) are conducted. Thus, I think it is not reasonable that the run_id column in the phenotype file corresponds to an existing run_ in a (task) filename. Instead, something like a measurement_timepoint_id (or similar) that is not related to the run_ in other files might be a good idea. Again, I am sorry if my comment is stupid or I misunderstood something.

[VisLab]

Along this line: The current proposal states:

A participant identifier of the form sub-, matching a participant entity found in the dataset. Note that data for one participant MAY be represented across multiple rows in case of multiple sessions or runs, and therefore the entry in the participant_id column will be repeated. The combination of participant_id, session_id and run_id MUST be unique.

The problem with this is that it doesn't cover the following cases which are in many datasets that I am familiar with:

Example 1: A dataset in which there are multiple training sessions on some equipment or on some test procedure on multiple different days before any imaging or any data that would have a run occurs.

Example 2: Sleep questionnaires and other questionnaires that administered multiple times un-associated with any imaging sessions.

Both of these require another column identifier (not associated with the run).

[ericearl]

@VisLab Great to hear from you! Thanks for reading the BEP. Now to your comments...

Example 1: A dataset in which there are multiple training sessions on some equipment or on some test procedure on multiple different days before any imaging or any data that would have a run occurs.

We may not have made it explicit, but here is this example in the HTML preview of the appendix. It covers what to do when there's "1 participant with 2 sessions, where 1 session is only tabular phenotype and the other is only imaging". The same idea extends to more than 2 sessions of some combination of acquired data and tabular phenotypic data. For instance, in your Example 1, we could say:

Define many phenotypic session names

• ses-day1equipmenttraining1
• ses-day1equipmenttraining2
• ses-day1equipmenttraining3
• ses-day2equipmenttraining1
• ses-day2equipmenttraining2
• ses-preproceduretraining
• ses-procedure
• ses-postprocedure
• ...

Store most, if not all, in one aggregated file

• phenotype/equipment_training.tsv
  • Where participant_id, session_id, run_id, and day are joint indexes.
  • Yes, day is not a a validate-able column, but you could alternatively create a phenotype/day#_equipment_training.tsv if you want stricter validation support.
  • Remember that run_id is not about tying the data to a particular task's run, but instead to differentiate multiple runs of the same tabular phenotypic test, survey, assessment, questionnaire, or lab result within the same participant_id's session_id.

Example 2: Sleep questionnaires and other questionnaires that administered multiple times un-associated with any imaging sessions.

The answer to example 2 is the appendix example I linked above, and now here.

I hope this helps and let me know if you don't think this resolves your comment. Or if perhaps there's something else we should consider which you can propose?

[ericearl]

@timdressler

I want to draw attention to a potential issue with the handling repeated usage of a phenotype/ measurement. Currently, if a measurement is conducted more than once, a run_id column MUST be added that "corresponds to an existing run- entity used in a filename(s)" (https://bids-specification--2123.org.readthedocs.build/en/2123/modality-agnostic-files/phenotypic-and-assessment-data.html).

Wowza, good catch! I didn't notice that incorrect set of words there. It currently says:

(run_id is) A run identifier that corresponds to an existing run- entity used in a filename(s). A chronological run number is used when a measurement tool or assessment described by a tabular file was repeated within a session.

What it should say:

(run_id is) A run identifier to differentiate multiple runs of the same measurement tool. A chronological run number is used when a measurement tool or assessment described by a tabular file is repeated within a session.

Thanks! I'll edit that.

For example, I conduct a mood questionnaire 7 times over the course of one session in which multiple tasks (with multiple runs) are conducted.

Does the text edit above of "what it should say" make better sense and resolve the run_id labeling issue?

[SamGuay]

There you go @ericearl !
(Do we need to wait for #2273 to have this one merge-able?)

[SamGuay]

Suggested change

	To read more about the guidelines for tabular phenotypic data and examples,
	see the [tabular phenotypic data guidelines appendix](../appendices/phenotype.md).

I don't think we need to repeat it one more time considering the last 3 paragraphs mention the same URL.

[ericearl]

@rwblair or @effigies: The check_links step failed on a link I don't think I put in there. What would you recommend to get past this error in CI?

URL        `https://www.encodeproject.org/profiles/biosample_type'
Name       `ENCODE Biosample Type'
Parent URL file:///home/circleci/project/site/modality-agnostic-files/data-summary-files.html, line 2318, col 31
Real URL   https://www.encodeproject.org/profiles/biosample_type
Check time 0.516 seconds
Size       2KB
Result     Error: 405 Not Allowed
 1 thread active,    32 links queued, 1229 links in 1262 URLs checked, runtime 46 seconds
 1 thread active,    25 links queued, 1236 links in 1262 URLs checked, runtime 51 seconds
 1 thread active,    14 links queued, 1247 links in 1264 URLs checked, runtime 56 seconds
 1 thread active,     7 links queued, 1254 links in 1264 URLs checked, runtime 1 minute, 1 seconds

Thanks!

[mih]

Thank you for working on this BEP!

I want to put a use case on record that I do not find to be fitting smoothly into the current BIDS spec or the current BEP draft. Maybe it can inform further development.

I am structuring a longitudinal cohort dataset, multi-site, multi-modal with deep phenotyping, >30+ questionaires, genetics, hormones, imaging, ... Currently ~300 subjects aiming for 1k, with repeated assessments and afterwards another 8 years of data acquisition and further growth -- a dynamic resource.

Moreover, the project employs a decentralized governance model, where a site that acquired data retains the ultimate decision who get's access to which data types and subjects -- for their respective portion of the dataset.

Lastly, the dataset comprises numerous meaningful subpopulations. It can be assumed that a subselection of particular subjects will be a standard data access approach.

From my POV, an optimal representation of phenotypic data would be individual files per-subject, per-session, per-instrument, ideally underneath the respective subject directories. This would enable:

• low churn: once an assessment time point is complete for a subject, the respective directory can be frozen/archived, and files remain static "forever", and can be hosted on "dumb" systems with read-only access
• per-file access model: technical solutions like datalad allow for hosting file content "on premise" at the respective governing site

It is my understanding that in the current BIDS spec and the BEP draft it is only possible to represent data in an aggregated fashion (across participants, across sessions). This means that data from multiple subjects, and multiple sites needs to be concatenated into a single file. This creates a churn issue (each incoming data point requires an update of such a file, creating hundreds of versions that are strict increments). More importantly, this creates a governance issue, because that file content now requires the joint decision of all contributing entities re data access granting, and the copy needs to live somewhere (new).

It is appears to be possible (or at least not explicitly forbidden) to have more than one file under /phenotype/ corresponding to a single instrument. For example

• LHA_site1.tsv, where "LHA_site1" is considered the instrument name, read as "LHA as used at site 1"

By extension, a more extreme interpretation would be to consider the following as compliant

• LHA_sub-001.tsv, where ""LHA_sub-001" reads "the LHA instrument as given to subject 001".

Or even

• LHA_sub-001_ses-001.tsv for "the LHA instrument as given to subject 001 in sesssion 001".

In all cases, the corresponding metadata files would identify that LHA_site1, LHA_sub-001, and LHA_sub-001_ses-001 are actually all the same instrument -- even if the necessary inference may be (needlessly) complex.

If we consider this line of arguments valid, the enforced placement of these files under /phenotype/ appears to be disproportionately strict.

Have you considered a more encapsulated, less aggregated representation of such information? I feel that it would help support the expression of developing resources in BIDS.

Thanks for your consideration!

[karl-koschutnig]

@mih
This is exactly the kind of case that shows why I'm not keen on the phenotype approach — it breaks with how BIDS handles everything else (subject/session/run-resolved, not a flat aggregate table).

Instead of aggregating into phenotype/, I've proposed an "on-top" survey modality that keeps instrument-based data (surveys, but potentially other assessment types too) inside the normal subject/session/run structure, with sidecar metadata living next to the data the way it does for every other modality. Aggregated phenotype tables can still be generated downstream — they just aren't the only canonical form.

I've built a reference implementation of this, PRISM Studio: it handles subject/session/run-resolved survey data, template-based instrument authoring, and dataset validation against that structure — so the proposal isn't just abstract, there's working tooling behind it.

• Docs: https://prism-studio.readthedocs.io/en/latest/
• Full proposal: [SCHEMA] Support structured survey data as a BIDS modality #2404

[ericearl]

@mih Thanks for continuing the PR discussion! I'm also glad @karl-koschutnig already commented back, because that is exactly what I was going to recommend for your use case. This PR/BEP is a set of guidelines that users can opt-in for additional BIDS validation support of good practices (aggregating because that is what most end-users want to interpret or use). It is not strictly enforced unless a user opts in, so in a way this BEP changes very little about BIDS overall.

The way you are proposing to store phenotype data is supported by PRISM Studio now, I believe, and in fact was an original alternative to our "aggregated" recommendation. We called that alternative the "segregated" approach. One of the reasons we stopped pushing on segregation is because we wanted to satisfy the use cases of most users, with the intent to come back to the segregated approach when time allowed for us. But PRISM Studio already did it, which is great!

Of course, tables are built from rows and columns and you can either segregate or aggregate them (in various wide or narrow shapes). However, most end-users want to ingest tabular data in an aggregated table.

P.S. We can all technically achieve the segregated approach in BIDS right now by integrating every piece of tabular phenotypic data into sessions files, but then it is a vast sea of tiny files which needs something like PRISM Studio anyway to carefully construct aggregated files as-needed.