Automatically generate a "Data" (image acquisition) boilerplate

[oesteban]

This can be easily done just mapping the JSON sidecar files to text.

(Suggested by Sam Nastase in his open review to the preprint)

[chrisgorgo]

See https://github.com/INCF/pybids/pull/100

[tsalo]

Regarding this issue, I'd be happy to open a PR to add the acquisition boilerplate into fmriprep. There are going to be some bugs in the pybids BIDSReport module in 0.6.5, which is what fMRIPrep requires. Should I hold off on this until pybids 0.7 is supported?

[effigies]

@tsalo Now that 0.7 is out, I think it's worth upgrading before we depend on any more functionality.

[tsalo]

That makes sense. If the acquisition report generation is going to be integrated, then it's probably worth it to move to 0.7.1 (or whatever comes next) directly, since 0.7 missed a couple of compatibility updates in the reports module.

In the meantime, I can just hold off on this until 0.7 is supported.

[tsalo]

I think I'm ready to open a PR, but the BIDSReport write-ups are still pretty ugly. Here is an example writeup for ds000254 (just what I had on hand):

For session None: MR data were acquired using a UNKNOWN-Tesla GE 3 Tesla MR750 MODEL MRI scanner. T1-weighted structural MRI data were collected (256 slices; repetition time, TR=7.33ms; echo time, TE=3ms; flip angle, FA=8; field of view, FOV=190x256mm; matrix size=190x256; voxel size=1x1x1mm). One run of bilateralfingertapping multi-echo fMRI data were collected (44 slices in interleaved ascending order; repetition time, TR=4000ms; echo time, TE=9.1, 25, 39.6, and 54.3ms; flip angle, FA=90; field of view, FOV=240x240mm; matrix size=80x80; voxel size=3x3x3mm; in-plane acceleration factor=2). Each run was 6:00 minutes in length, during which 90 functional volumes were acquired.

Dicoms were converted to NIfTI-1 format. This section was (in part) generated automatically using pybids (0.7.1+2.gbad18f9.dirty).

Before I open a PR here, I wanted to see if there are any changes that anyone would like to see implemented over in pybids to the reporting module.

[tsalo]

I just wanted to ping this issue. Should I open a pull request or wait on further improvements to pybids' BIDSReport?

[tsalo]

I believe that a relatively simple solution would be to build the BIDSReport in fmriprep.workflows.base.init_fmriprep_wf(), like this.

That said, I think it should also be pretty easy to add a generate_from_files() method to BIDSReport that would build the boilerplate from some set of files rather than collecting the files from a BIDSLayout.get() call. This would allow fMRIPrep or a niworkflow to build the report after calling collect_data().

EDIT: I've opened https://github.com/bids-standard/pybids/issues/599 to implement the generate_from_files() method.

[oesteban]

Hey @tsalo, how familiar you are with the reportlet system that generates the visual reports of fMRIPrep?

The problem of filtering metadata from a specified set of files seems pretty close. We should try to identify functionality patterns and minimize niworkflows if possible, removing duplicates.

(just thinking out loud here, not meaning anything concrete)

[tsalo]

@oesteban I'm not really familiar with the reportlets. However, my assumption was that the image acquisition section would end up within the preprocessing section of the report, but before the description of the preprocessing. I.e., it would be added to LiterateWorkflow.__desc__ at the very beginning of the top-level workflow and would go into the standard CITATION file.

If, instead, you'd prefer to have a separate boilerplate and reportlet, then I'm sure that's possible, but I don't think I know enough about the reportlet system to help just yet.

That said, I think no matter which way it's set up within niworkflows, the report generator will probably need to take in the dictionary generated by any BIDS App's collect_data function, as well as a BIDSLayout for the dataset, then convert the dictionary to a list of BIDSImageFile objects, and finally call BIDSReport.generate_from_files() to get the description. I can at least help with that part.

[oesteban]

Oh, sorry I confused you. I wasn't referring to the literate description of workflows in building the boilerplate. I was meaning the actual report builder, which uses PyBIDS to query against a BIDS-like structure of reportlets: https://github.com/nipreps/niworkflows/blob/736306b40e14b4866166c6877fbf598ef6436c6b/niworkflows/reports/core.py#L146

Basically, fMRIPrep drops the reportlets (either .svg or .html files) under a folder that is used as layout.root by PyBIDS. This is the potential commonality (if any exist)

[tsalo]

Oh okay. So would the goal be to index the reportlets as is done there and then to use those to build image-specific acquisition boilerplates that describe the original file? Or would the boilerplate already exist as a series of image-specific reportlets that would be indexed with the above line?