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 | Path | 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.

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.

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 | Path | 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¶

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.

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.