add get_dataset_description method

Author: tyarkoni

bids/layout/layout.py

@@ -417,8 +417,8 @@ def get_entities(self, scope='all', metadata=None):
 
         Args:
             scope (str): The scope of the search space. Indicates which
-                BIDSLayouts' entities to extract. See BIDSLayout docstring
-                for valid values.
+                BIDSLayouts' entities to extract. See BIDSLayout.get()
+                docstring for valid values.
             metadata (bool, None): By default (None), all available entities
                 are returned. If True, only entities found in metadata files
                 (and not defined for filenames) are returned. If False, only
@@ -444,8 +444,8 @@ def get_files(self, scope='all'):
 
         Args:
             scope (str): The scope of the search space. Indicates which
-                BIDSLayouts' entities to extract. See BIDSLayout docstring
-                for valid values.
+                BIDSLayouts' entities to extract. See BIDSLayout.get()
+                docstring for valid values.
 
         Returns: A dict, where keys are file paths and values are BIDSFile
             instances.
@@ -469,8 +469,8 @@ def parse_file_entities(self, filename, scope='all', entities=None,
         Args:
             filename (str): The filename to parse for entity values
             scope (str, list): The scope of the search space. Indicates which
-                BIDSLayouts' entities to extract. See BIDSLayout docstring
-                for valid values. By default, extracts all entities.
+                BIDSLayouts' entities to extract. See BIDSLayout.get()
+                docstring for valid values. By default, extracts all entities.
             entities (list): An optional list of Entity instances to use in
                 extraction. If passed, the scope and config arguments are
                 ignored, and only the Entities in this list are used.
@@ -763,7 +763,7 @@ def get_file(self, filename, scope='all'):
                 an absolute path, or relative to the root of this BIDSLayout.
             scope (str, list): Scope of the search space. If passed, only
                 BIDSLayouts that match the specified scope will be
-                searched. See BIDSLayout docstring for valid values.
+                searched. See BIDSLayout.get() docstring for valid values.
 
         Returns: A BIDSFile, or None if no match was found.
         '''
@@ -877,6 +877,27 @@ def get_metadata(self, path, include_entities=False, scope='all'):
 
         return {}
 
+    def get_dataset_description(self, scope='self', all_=False):
+        ''' Return contents of dataset_description.json.
+
+        Args:
+            scope (str): The scope of the search space. Only descriptions of
+                BIDSLayouts that match the specified scope will be returned.
+                See BIDSLayout.get() docstring for valid values. Defaults to
+                'self'--i.e., returns the dataset_description.json file for
+                only the directly-called BIDSLayout.
+            all_ (bool): If True, returns a list containing descriptions for
+                all matching layouts. If False (default), returns for only the
+                first matching layout.
+
+        Returns: a dictionary or list of dictionaries (depending on all_).
+        '''
+        layouts = self._get_layouts_in_scope(scope)
+        if not all_:
+            return layouts[0].get_file('dataset_description.json').get_dict()
+        return [l.get_file('dataset_description.json').get_dict()
+              for l in layouts]
+
     def get_nearest(self, path, return_type='filename', strict=True,
                     all_=False, ignore_strict_entities='extension',
                     full_search=False, **filters):

bids/layout/tests/test_layout.py

@@ -495,6 +495,18 @@ def test_get_layouts_in_scope(layout_ds005_multi_derivs):
     assert self_scope == [l]
 
 
+def test_get_dataset_description(layout_ds005_multi_derivs):
+    l = layout_ds005_multi_derivs
+    dd = l.get_dataset_description()
+    assert isinstance(dd, dict)
+    assert dd['Name'] == 'Mixed-gambles task'
+    dd = l.get_dataset_description('all', True)
+    assert isinstance(dd, list)
+    assert len(dd) == 3
+    names = {'Mixed-gambles task', 'Mixed-gambles task -- dummy derivative'}
+    assert set([d['Name'] for d in dd]) == names
+
+
 def test_indexed_file_associations(layout_7t_trt):
     img = layout_7t_trt.get(subject='01', run=1, suffix='bold', session='1',
                             acquisition='fullbrain', extension='nii.gz')[0]