bids.ext.reports package#

Module contents#

pybids-reports: A tool for building methods sections for BIDS datasets.

class bids.ext.reports.BIDSReport(layout: BIDSLayout, config: None | str | dict[str, dict[str, str]] = None)[source]#

Bases: object

Generate publication-quality data acquisition section from BIDS dataset.

Parameters#

layoutbids.layout.BIDSLayout

Layout object for a BIDS dataset.

configstr or dict, optional

Configuration info for methods generation. Can be a path to a file (str), a dictionary, or None. If None, loads and uses default configuration information. Keys in the dictionary include:

‘dir’: a dictionary for converting encoding direction strings

(e.g., j-) to descriptions (e.g., anterior to posterior)

‘seq’: a dictionary of sequence abbreviations (e.g., EP) and

corresponding names (e.g., echo planar)

‘seqvar’: a dictionary of sequence variant abbreviations

(e.g., SP) and corresponding names (e.g., spoiled)

Warning#

pybids’ automatic report generation is experimental and currently under active development, and as such should be used with caution. Please remember to verify any generated report before putting it to use.

Additionally, only MRI datatypes (func, anat, fmap, and dwi) are currently supported.

generate(**kwargs: Any) → Counter[str][source]#

Generate the methods section.

Parameters#

kwargsdict

Keyword arguments passed to BIDSLayout to select subsets of the dataset.

Returns#

countercollections.Counter

A dictionary of unique descriptions across subjects in the dataset, along with the number of times each pattern occurred. In cases where all subjects underwent the same protocol, the most common pattern is most likely the most complete. In cases where the dataset contains multiple protocols, each pattern will need to be inspected manually.

Examples#

>>> from os.path import join
>>> from bids.layout import BIDSLayout
>>> from bids.reports import BIDSReport
>>> from bids.tests import get_test_data_path
>>> layout = BIDSLayout(join(get_test_data_path(), 'synthetic'))
>>> report = BIDSReport(layout)
>>> counter = report.generate(session='01')
Number of patterns detected: 1
Remember to double-check everything and to replace <deg> with a degree symbol.

>>> counter.most_common()[0][0]  
'In session 01, MR data were...'
generate_from_files(files: list[BIDSFile]) → Counter[str][source]#

Generate a methods section from a list of files.

Parameters#

fileslist of BIDSImageFile objects

List of files from which to generate methods description.

Returns#

countercollections.Counter

A dictionary of unique descriptions across subjects in the file list, along with the number of times each pattern occurred. In cases where all subjects underwent the same protocol, the most common pattern is most likely the most complete. In cases where the file list contains multiple protocols, each pattern will need to be inspected manually.

Examples#

>>> from os.path import join
>>> from bids.layout import BIDSLayout
>>> from bids.reports import BIDSReport
>>> from bids.tests import get_test_data_path
>>> layout = BIDSLayout(join(get_test_data_path(), 'synthetic'))
>>> report = BIDSReport(layout)
>>> files = layout.get(session='01', extension=['.nii.gz', '.nii'])
>>> counter = report.generate_from_files(files)
Number of patterns detected: 1
Remember to double-check everything and to replace <deg> with a degree symbol.

>>> counter.most_common()[0][0]  
'In session 01, MR data were...'

Submodules#

bids.ext.reports.parameters module#

Functions for building strings for individual parameters.

bids.ext.reports.parameters.bvals(bval_file: str | Path) → str[source]#

Generate description of dMRI b-values.

bids.ext.reports.parameters.duration(all_imgs: list[Nifti1Image], metadata: dict[str, Any]) → str[source]#

Generate general description of scan length from files.

bids.ext.reports.parameters.echo_time_ms(files: list[BIDSFile]) → str[source]#

Generate description of echo times from metadata field.

Parameters#

fileslist of bids.layout.models.BIDSFile

List of nifti files in layout corresponding to file collection.

Returns#

testr

Description of echo times.

bids.ext.reports.parameters.echo_times_fmap(files: list[BIDSFile]) → tuple[float, float][source]#

Generate description of echo times from metadata field for fmaps

Parameters#

fileslist of bids.layout.models.BIDSFile

List of nifti files in layout corresponding to file collection.

Returns#

te_str :

Description of echo times.

bids.ext.reports.parameters.field_of_view(img: None | Nifti1Image) → str[source]#

Extract and reformat FOV.

Parameters#

imgnibabel.Nifti1Image

Image from scan from which to derive parameters.

Returns#

fovstr

Field of view string (e.g., ‘256x256’)

bids.ext.reports.parameters.func_duration(nb_vols: int, tr: float) → str[source]#

Generate description of functional run length from repetition time and number of volumes.

bids.ext.reports.parameters.get_nb_vols(all_imgs: list[Nifti1Image | None]) → list[int] | None[source]#

Get number of volumes from list of files.

If all files have the same nb of vols it will return the number of volumes, otherwise it will return the minimum and maximum number of volumes.

bids.ext.reports.parameters.get_slice_info(slice_times: list[Any]) → str | list[str][source]#

Extract slice order from slice timing info.

TODO: Be more specific with slice orders. Currently anything where there’s some kind of skipping is interpreted as interleaved of some kind.

Parameters#

slice_timesarray-like

A list of slice times in seconds or milliseconds or whatever.

Returns#

slice_order_namestr

The name of the slice order sequence.

bids.ext.reports.parameters.intendedfor_targets(metadata: dict[str, Any], layout: BIDSLayout) → str[source]#

Generate description of intended for targets.

bids.ext.reports.parameters.matrix_size(img: None | Nifti1Image) → str[source]#

Extract and reformat voxel size, matrix size, FOV, and number of slices into strings.

Parameters#

imgnibabel.Nifti1Image

Image from scan from which to derive parameters.

Returns#

matrix_sizestr

Matrix size string (e.g., ‘128x128’)

bids.ext.reports.parameters.multi_echo(files: list[BIDSFile]) → str[source]#

Generate description of echo times from metadata field.

Parameters#

fileslist of bids.layout.models.BIDSFile

List of nifti files in layout corresponding to file collection.

Returns#

multi_echostr

Whether the data are multi-echo or single-echo.

bids.ext.reports.parameters.nb_runs(run_list: list[str]) → str[source]#

Generate description of number of runs from list of files.

bids.ext.reports.parameters.nb_vols(all_imgs: list[Nifti1Image]) → str[source]#

Generate description of number of volumes from files.

bids.ext.reports.parameters.sequence(metadata: dict[str, Any], config: dict[str, dict[str, str]]) → str | list[str][source]#

Extract and reformat imaging sequence(s) and variant(s) into pretty strings.

Parameters#

metadatadict

The metadata for the scan.

configdict

A dictionary with relevant information regarding sequences, sequence variants, phase encoding directions, and task names.

Returns#

seqsstr

Sequence names.

bids.ext.reports.parameters.slice_order(metadata: dict[str, Any]) → str[source]#

Generate description of slice timing from metadata.

bids.ext.reports.parameters.variants(metadata: dict[str, Any], config: dict[str, dict[str, str]]) → str[source]#

Extract and reformat imaging variant(s).

Parameters#

metadatadict

The metadata for the scan.

configdict

A dictionary with relevant information regarding sequences, sequence variants, phase encoding directions, and task names.

Returns#

variantsstr

Sequence variant names.

bids.ext.reports.parameters.voxel_size(img: None | Nifti1Image) → str[source]#

Extract and reformat voxel size.

Parameters#

imgnibabel.Nifti1Image

Image from scan from which to derive parameters.

Returns#

voxel_sizestr

Voxel size string (e.g., ‘2x2x2’)

bids.ext.reports.parsing module#

Parsing functions for generating BIDSReports.

bids.ext.reports.parsing.anat_info(files: list[BIDSFile], config: dict[str, dict[str, str]], layout: BIDSLayout) → str[source]#

Generate a paragraph describing T1- and T2-weighted structural scans.

Parameters#

fileslist of bids.layout.models.BIDSFile

List of nifti files in layout corresponding to DWI scan.

configdict

A dictionary with relevant information regarding sequences, sequence variants, phase encoding directions, and task names.

layoutbids.layout.BIDSLayout

Layout object for a BIDS dataset.

Returns#

descstr

A description of the scan’s acquisition information.

bids.ext.reports.parsing.common_mri_desc(img: None | Nifti1Image, metadata: dict[str, Any], config: dict[str, dict[str, str]]) → dict[str, Any][source]#

Extract common MRI parameters from metadata.

bids.ext.reports.parsing.dwi_info(files: list[BIDSFile], config: dict[str, dict[str, str]], layout: BIDSLayout) → str[source]#

Generate a paragraph describing DWI scan acquisition information.

Parameters#

fileslist of bids.layout.models.BIDSFile

List of nifti files in layout corresponding to DWI scan.

configdict

A dictionary with relevant information regarding sequences, sequence variants, phase encoding directions, and task names.

layoutbids.layout.BIDSLayout

Layout object for a BIDS dataset.

Returns#

descstr

A description of the DWI scan’s acquisition information.

bids.ext.reports.parsing.files_not_found_warning(files: list[BIDSFile] | BIDSFile) → None[source]#

Warn user that files were not found or empty.

bids.ext.reports.parsing.final_paragraph(metadata: dict[str, Any]) → str[source]#

Describe dicom-to-nifti conversion process and methods generation.

Parameters#

metadatadict

The metadata for the scan.

Returns#

descstr

Output string with scanner information.

bids.ext.reports.parsing.fmap_info(files: list[BIDSFile], config: dict[str, dict[str, str]], layout: BIDSLayout) → str[source]#

Generate a paragraph describing field map acquisition information.

Parameters#

fileslist of bids.layout.models.BIDSFile

List of nifti files in layout corresponding to field map scan.

configdict

A dictionary with relevant information regarding sequences, sequence variants, phase encoding directions, and task names.

layoutbids.layout.BIDSLayout

Layout object for a BIDS dataset.

Returns#

descstr

A description of the field map’s acquisition information.

bids.ext.reports.parsing.func_info(files: list[BIDSFile], config: dict[str, dict[str, str]], layout: BIDSLayout) → str[source]#

Generate a paragraph describing T2*-weighted functional scans.

Parameters#

fileslist of bids.layout.models.BIDSFile

List of nifti files in layout corresponding to DWI scan.

configdict

A dictionary with relevant information regarding sequences, sequence variants, phase encoding directions, and task names.

layoutbids.layout.BIDSLayout

Layout object for a BIDS dataset.

Returns#

descstr

A description of the scan’s acquisition information.

bids.ext.reports.parsing.institution_info(files: list[BIDSFile])[source]#
bids.ext.reports.parsing.meg_info(files: list[BIDSFile]) → str[source]#

Generate a paragraph describing meg acquisition information.

Parameters#

fileslist of bids.layout.models.BIDSFile

List of nifti files in layout corresponding to meg scan.

configdict

A dictionary with relevant information regarding sequences, sequence variants, phase encoding directions, and task names.

Returns#

descstr

A description of the field map’s acquisition information.

bids.ext.reports.parsing.mri_scanner_info(files: list[BIDSFile])[source]#
bids.ext.reports.parsing.parse_files(layout: BIDSLayout, data_files: list[BIDSFile], config: dict[str, dict[str, str]]) → list[str][source]#

Loop through files in a BIDSLayout and generate appropriate descriptions.

Then, compile all of the descriptions into a list.

Parameters#

layoutbids.layout.BIDSLayout

Layout object for a BIDS dataset.

data_fileslist of bids.layout.models.BIDSFile

List of nifti files in layout corresponding to subject/session combo.

configdict

Configuration info for methods generation.

bids.ext.reports.parsing.perf_info(files: list[BIDSFile], config: dict[str, dict[str, str]], layout: BIDSLayout) → str[source]#
bids.ext.reports.parsing.pet_info(files: list[BIDSFile], layout: BIDSLayout) → str[source]#
bids.ext.reports.parsing.try_load_nii(file: BIDSFile) → None | Nifti1Image[source]#

Try to load a nifti file, return None if it fails.

bids.ext.reports.report module#

Generate publication-quality data acquisition methods section from BIDS dataset.

class bids.ext.reports.report.BIDSReport(layout: BIDSLayout, config: None | str | dict[str, dict[str, str]] = None)[source]#

Bases: object

Generate publication-quality data acquisition section from BIDS dataset.

Parameters#

layoutbids.layout.BIDSLayout

Layout object for a BIDS dataset.

configstr or dict, optional

Configuration info for methods generation. Can be a path to a file (str), a dictionary, or None. If None, loads and uses default configuration information. Keys in the dictionary include:

‘dir’: a dictionary for converting encoding direction strings

(e.g., j-) to descriptions (e.g., anterior to posterior)

‘seq’: a dictionary of sequence abbreviations (e.g., EP) and

corresponding names (e.g., echo planar)

‘seqvar’: a dictionary of sequence variant abbreviations

(e.g., SP) and corresponding names (e.g., spoiled)

Warning#

pybids’ automatic report generation is experimental and currently under active development, and as such should be used with caution. Please remember to verify any generated report before putting it to use.

Additionally, only MRI datatypes (func, anat, fmap, and dwi) are currently supported.

generate(**kwargs: Any) → Counter[str][source]#

Generate the methods section.

Parameters#

kwargsdict

Keyword arguments passed to BIDSLayout to select subsets of the dataset.

Returns#

countercollections.Counter

A dictionary of unique descriptions across subjects in the dataset, along with the number of times each pattern occurred. In cases where all subjects underwent the same protocol, the most common pattern is most likely the most complete. In cases where the dataset contains multiple protocols, each pattern will need to be inspected manually.

Examples#

>>> from os.path import join
>>> from bids.layout import BIDSLayout
>>> from bids.reports import BIDSReport
>>> from bids.tests import get_test_data_path
>>> layout = BIDSLayout(join(get_test_data_path(), 'synthetic'))
>>> report = BIDSReport(layout)
>>> counter = report.generate(session='01')
Number of patterns detected: 1
Remember to double-check everything and to replace <deg> with a degree symbol.

>>> counter.most_common()[0][0]  
'In session 01, MR data were...'
generate_from_files(files: list[BIDSFile]) → Counter[str][source]#

Generate a methods section from a list of files.

Parameters#

fileslist of BIDSImageFile objects

List of files from which to generate methods description.

Returns#

countercollections.Counter

A dictionary of unique descriptions across subjects in the file list, along with the number of times each pattern occurred. In cases where all subjects underwent the same protocol, the most common pattern is most likely the most complete. In cases where the file list contains multiple protocols, each pattern will need to be inspected manually.

Examples#

>>> from os.path import join
>>> from bids.layout import BIDSLayout
>>> from bids.reports import BIDSReport
>>> from bids.tests import get_test_data_path
>>> layout = BIDSLayout(join(get_test_data_path(), 'synthetic'))
>>> report = BIDSReport(layout)
>>> files = layout.get(session='01', extension=['.nii.gz', '.nii'])
>>> counter = report.generate_from_files(files)
Number of patterns detected: 1
Remember to double-check everything and to replace <deg> with a degree symbol.

>>> counter.most_common()[0][0]  
'In session 01, MR data were...'