Repository: bids-standard/pybids

Issue:
Add method to build BIDSReport from list of files
It would be nice to be able to build reports from lists of files, for tools that collect their inputs using custom functions, like fMRIPrep. In these cases, BIDSLayout filters are insufficient to collect the exact files required by the tools.

EDIT: I should also note that I've got working code for this and would be happy to open a PR if others think it would be useful.

Discussion:

Patch:
diff --git a/bids/layout/models.py b/bids/layout/models.py
index 766edd14..9b1e0893 100644
--- a/bids/layout/models.py
+++ b/bids/layout/models.py
@@ -377,17 +377,15 @@ class BIDSImageFile(BIDSFile):
         'polymorphic_identity': 'image_file'
     }
 
-    def get_image(self, **kwargs):
+    def get_image(self):
         """Return the associated image file (if it exists) as a NiBabel object
-
-        Any keyword arguments are passed to ``nibabel.load``.
         """
         try:
             import nibabel as nb
-            return nb.load(self.path, **kwargs)
-        except Exception as e:
+            return nb.load(self.path)
+        except Exception:
             raise ValueError("'{}' does not appear to be an image format "
-                             "NiBabel can read.".format(self.path)) from e
+                             "NiBabel can read.".format(self.path))
 
 
 class BIDSJSONFile(BIDSFile):
diff --git a/bids/reports/parsing.py b/bids/reports/parsing.py
index ef16eabb..80219315 100644
--- a/bids/reports/parsing.py
+++ b/bids/reports/parsing.py
@@ -456,6 +456,7 @@ def parse_niftis(layout, niftis, subj, config, **kwargs):
                     n_runs = len(layout.get_runs(subject=subj,
                                                  task=nifti_struct.entities['task'],
                                                  **kwargs))
+                    n_runs = max(n_runs, 1)
                     description_list.append(func_info(nifti_struct.entities['task'],
                                                       n_runs, metadata, img,
                                                       config))
diff --git a/bids/reports/report.py b/bids/reports/report.py
index 78f19c9e..e23f4e16 100644
--- a/bids/reports/report.py
+++ b/bids/reports/report.py
@@ -49,6 +49,74 @@ class BIDSReport(object):
 
         self.config = config
 
+    def generate_from_files(self, files):
+        r"""Generate a methods section from a list of files.
+
+        Parameters
+        ----------
+        files : list of BIDSImageFile objects
+            List of files from which to generate methods description.
+
+        Returns
+        -------
+        counter : :obj:`collections.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]  # doctest: +ELLIPSIS
+        'For session 01:\n\tMR data were...'
+        """
+        descriptions = []
+
+        subjs = sorted(list(set([f.get_entities().get('subject') for f in files])))
+        sessions = sorted(list(set([f.get_entities().get('session') for f in files])))
+        for sid in subjs:
+            subject_files = [f for f in files if f.get_entities().get('subject') == sid]
+            description_list = []
+            for ses in sessions:
+                niftis = [f for f in subject_files if f.get_entities().get('session') == ses]
+
+                if niftis:
+                    description_list.append('For session {0}:'.format(ses))
+                    description_list += parsing.parse_niftis(self.layout, niftis,
+                                                             sid, self.config,
+                                                             session=ses)
+                    metadata = self.layout.get_metadata(niftis[0].path)
+                else:
+                    raise Exception('No niftis for subject {0}'.format(subject))
+
+            # Assume all data were converted the same way and use the last nifti
+            # file's json for conversion information.
+            if 'metadata' not in vars():
+                raise Exception('No valid jsons found. Cannot generate final '
+                                'paragraph.')
+
+            description = '\n\t'.join(description_list)
+            description = description.replace('\tFor session', '\nFor session')
+            description += '\n\n{0}'.format(parsing.final_paragraph(metadata))
+            descriptions.append(description)
+        counter = Counter(descriptions)
+        print('Number of patterns detected: {0}'.format(len(counter.keys())))
+        print(utils.reminder())
+        return counter
+
     def generate(self, **kwargs):
         r"""Generate the methods section.
 
diff --git a/doc/conf.py b/doc/conf.py
index d5feaf6a..c96e36a6 100755
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -19,7 +19,7 @@ sys.path.insert(0, os.path.abspath('../'))
 # -- Project information -----------------------------------------------------
 
 project = 'PyBIDS'
-copyright = '2020, Developers of PyBIDS'
+copyright = '2019, Developers of PyBIDS'
 author = 'Developers of PyBIDS'
 
 currentdir = os.path.abspath(os.path.dirname(__file__))
@@ -124,4 +124,4 @@ texinfo_documents = [
 ]
 
 # If false, no module index is generated.
-texinfo_domain_indices = False
+texinfo_domain_indices = False
\ No newline at end of file


Test patch:
diff --git a/bids/analysis/tests/test_analysis.py b/bids/analysis/tests/test_analysis.py
index e2971bfb..0b893a0c 100644
--- a/bids/analysis/tests/test_analysis.py
+++ b/bids/analysis/tests/test_analysis.py
@@ -27,8 +27,8 @@ def test_first_level_sparse_design_matrix(analysis):
     assert df.shape == (172, 9)
     assert df['condition'].nunique() == 2
     assert set(df.columns) == {'amplitude', 'onset', 'duration',
-                               'condition', 'subject', 'run',
-                               'task', 'datatype', 'suffix'}
+                                         'condition', 'subject', 'run',
+                                         'task', 'datatype', 'suffix'}
 
 
 def test_post_first_level_sparse_design_matrix(analysis):
@@ -40,15 +40,12 @@ def test_post_first_level_sparse_design_matrix(analysis):
     result = collections[0].to_df(format='long', entities=False)
     assert result.shape == (9, 2)
     entities = {
-        # 'subject': '01',  # PY35
+        'subject': '01',
         'task': 'mixedgamblestask',
         'datatype': 'func',
         'suffix': 'bold'}
     assert not set(entities.keys()) - set(collections[0].entities.keys())
     assert not set(entities.values()) - set(collections[0].entities.values())
-    # PY35
-    assert 'subject' in collections[0].entities
-    assert collections[0].entities['subject'] in ('01', '02')
 
     # Participant level and also check integer-based indexing
     collections = analysis['participant'].get_collections()
diff --git a/bids/reports/tests/test_report.py b/bids/reports/tests/test_report.py
index 5921a77b..798eafad 100644
--- a/bids/reports/tests/test_report.py
+++ b/bids/reports/tests/test_report.py
@@ -34,6 +34,16 @@ def test_report_gen(testlayout):
     assert isinstance(descriptions, Counter)
 
 
+def test_report_gen_from_files(testlayout):
+    """Report generation from file list should return a counter of unique
+    descriptions in the dataset.
+    """
+    report = BIDSReport(testlayout)
+    files = testlayout.get(extension=['nii.gz', 'nii'])
+    descriptions = report.generate_from_files(files)
+    assert isinstance(descriptions, Counter)
+
+
 def test_report_subject(testlayout):
     """Generating a report for one subject should only return one subject's
     description (i.e., one pattern with a count of one).