Describing processed/derivative data using HED

[neuromechanist]

The BIDS Derivative provides the descriptions.tsv mechanism to provide a more detailed explanation of the changes in the derivative data. However, the description is in freeform, and would not likely be as helpful for large-scale analyses.

@VisLab and I were thinking about the possibility of a schema library to describe processing steps systematically. Each modality (eeg, mri, ieeg, meg, pet, etc) has its own (as well as some common) processes. I wonder if that would be a worthwhile effort and who would be willing to contribute.

@dorahermes, @yarikoptic, @arnodelorme, @robertoostenveld, @smakeig, I appreciate your thoughts on the potential merit/relevance of such a schema library.

[robertoostenveld]

... the description is in freeform, and would not likely be as helpful for large-scale analyses.

Can you point to any BIDS derivatives examples online for which you consider the freeform format not to as helpful? Or is this just a theoretical consideration?

[yarikoptic]

would be indeed interesting to see how HED would apply there, where it seems more about PROV description.

[neuromechanist]

Can you point to any BIDS derivatives examples online for which you consider the freeform format not to as helpful? Or is this just a theoretical consideration?

Freeform text may not be machine-readable. In the BIDS-Derivative example, the lack of structures and reserved vocabulary renders the table not machine-readable. This is particularly cumbersome for systematic comparison of (or building inference from) different processing pipelines:

desc_id	description
Filt	low-pass filtered at 30Hz
FiltDs	low-pass filtered at 30Hz, downsampled to 250Hz
preproc	low-pass filtered at 30Hz, downsampled to 250Hz, and rereferenced to a common average reference

would be indeed interesting to see how HED would apply there, where it seems more about PROV description.

Yes, this could be seen as providing a schema to describe the provenance (for example, providing a common vocabulary for the labels in BIDS-Prov).

AFAIK, there are only a handful of derivative datasets on OpenNeuro, one on EEG is ds005907. The dataset_description fields that indicate this is a derivative dataset are:

    "DatasetType": "derivative",
    "GeneratedBy": [
        {
            "Name": "NEMAR-pipeline",
            "Description": "A validated EEG pipeline",
            "Version": "bcb79cb",
            "CodeURL": "https://github.com/sccn/NEMAR-pipeline/blob/main/eeg_nemar_preprocess.m"
        }

Ideally, the individual data files should also have a _desc-<label> tag to indicate they are not raw data.
Then based on the BIDS Derivative spec, we can have a descriptions.tsv (and hopefully a descriptions.json) to provide more detail on the processes performed using the code under CodeURL. This would require HED tags such as Filter, Remove-channel, ICA, etc for this example.

I understand that this is essentially an approach to the Provenance description, with several missing parts compared to the BIDS-Prov proposal. Hopefully, the same schema can carry over there too.

[robertoostenveld]

The optional desc-<label> entity can be part of the filename to make filenames non-overlapping with the BIDS source data from which it is derived (since "Any modification of raw files must use a modified filename that does not conflict with the raw filename"). See here.

The descriptions.tsv MAY be included and the "description" column is to make the desc-<label> entity human readable.

If you would want, you could put machine readable details in the additional columns which are allowed in the descriptions.tsv file, but a columnar format is not so suited for that if you ask me. Machine readable details of the pipeline can go in the GeneratedBy object in the dataset_description.json. However, I think that the prov files would be the most appropriate, see BEP28.

Given lack of a concrete example or case, I do consider this merely a theoretical discussion. Don't you have datasets on NEMAR where this applies?

[smakeig]

There is also the old question of defining events that occurred during the recording - of particular importance when dealing with an epoched dataset - or its processing step precursors. In this case, of real (but often ignored) importance of saving the complete events record for the recording -- even when only a subset of epochs has been saved as a derivative dataset. Ibn EEGLAB the solution was to retain a complete EEG.urevent record in epoched data files, along with pointers from their own event markers (in EEG.events) to their corresponding entry in the EEG.urevent event list. However, I am not sure whether data authors will be saving epoched data files as derivatives -- as this could be naturally tempting to many of them...

[yarikoptic]

. However, I think that the prov files would be the most appropriate, see BEP28.

yeap, I think this would be the "closest" issue (attn @cmaumet on this discussion)

• "Integrate" with already defined in BIDS descriptions and _desc entities bids-standard/BEP028_BIDSprov#151

Note that GeneratedBy might need to "migrate" to point to activity (associated with entity e.g. container) instead of an entity itself:

• "Absorb"/migrate already defined in BIDS dataset_description.json GeneratedBy bids-standard/BEP028_BIDSprov#148

and there on. But indeed, independently of that, may be there was a reason to formalize adding HED column to descriptions.tsv to provide even higher level if there were appropriate HED tags?

[neuromechanist]

I do consider this merely a theoretical discussion

Thanks @robertoostenveld for the feedback. You are right, derivative datasets are more or less theoretical in the sense that it is not being used as much, or at all for now. The BIDS validator just got updated (not sure if deployed to production yet) to accept _desc-<label> on channels.tsv, etc. So, I don't think there would be any dataset on NEMAR or OpenNeuro with proper _desc labels.

FWIW, I will push all processed HBN datasets (3k+ subjs) to OpenNeuro/NEMAR as soon as the validator comes into production.

may be there was a reason to formalize adding HED column to descriptions.tsv to provide even higher level if there were appropriate HED tags

Yes, that is a cool idea, This is exactly the point of this Issue:

1. Should we work on a HED schema library to annotate processes?
2. If yes, what hierarchy would you all think makes sense (considering extensibility to different modalities, processes, etc)?
3. If no, what would be a (theoretical) alternative to describe the Prov steps (or here, the processes for desc-ids) in a machine-readable way?
4. Have you recorded any list of "standard" processes (or Prov steps) that could be translated into a HED schema library?

[robertoostenveld]

I think the biggest hurdle on elaborating the BEP021 derivatives for human electrophysiology is not the various ideas how it could in principle be implemented by data producers (i.e., people that compute and share the derivatives), but more that those ideas are not sufficiently "bounded" by the requirements and expectations of "data consumers" (people that would download the derivatives to continue working on them).

Without stakeholders on both sides (both producers and consumers) getting involved, I see it as primarily a technology push without any market pull. Development of BIDS for raw data was successful because of the balanced involvement of both types of stakeholders.

[neuromechanist]

The relevance of this issue with BEP028 came up in HED Working Group discussion on March 17. BIDS-PROV accommodates a Label for Activities which is now a freeform text field but would benefit from a controlled list to indicate what this activity is doing. Otherwise, it would be very hard to systematically follow the processes.

We discussed with @christinerogers to identify top-level potential labels, such as Filters, Feature Extraction, Classifiers, and Regressors as top-level categories as a starting point that could be expanded using HED or any other mechanism.

[cmaumet]

Hi everyone (thanks for the ping @yarikoptic). As part of BEP028, you can store a more specific type (than Activity) by using the Type attribute in any activity: https://docs.google.com/document/d/1vw3VNDof5cecv2PkFp7Lw_pNUTUo8-m8V4SIdtGJVKs/edit?tab=t.0#heading=h.67arjmklnbek