Address comments, improve doc

NeurodataWithoutBorders · May 18, 2021 · 13b6c4e · 13b6c4e
1 parent def36e9
commit 13b6c4e
Show file tree

Hide file tree

Showing 4 changed files with 36 additions and 13 deletions.
diff --git a/requirements-doc.txt b/requirements-doc.txt
@@ -2,4 +2,4 @@ sphinx
 matplotlib
 sphinx_rtd_theme
 sphinx-gallery
-allensdk  # ntoe that as of allensdk 2.10.0, python 3.8 is not supported
+allensdk  # note that as of allensdk 2.10.0, python 3.8 is not supported
diff --git a/src/pynwb/file.py b/src/pynwb/file.py
@@ -48,16 +48,29 @@ class Subject(NWBContainer):
         'strain'
     )
 
-    @docval({'name': 'age', 'type': str, 'doc': 'the age of the subject', 'default': None},
-            {'name': 'description', 'type': str, 'doc': 'a description of the subject', 'default': None},
-            {'name': 'genotype', 'type': str, 'doc': 'the genotype of the subject', 'default': None},
-            {'name': 'sex', 'type': str, 'doc': 'the sex of the subject', 'default': None},
-            {'name': 'species', 'type': str, 'doc': 'the species of the subject', 'default': None},
-            {'name': 'subject_id', 'type': str, 'doc': 'a unique identifier for the subject', 'default': None},
-            {'name': 'weight', 'type': str, 'doc': 'the weight of the subject', 'default': None},
+    @docval({'name': 'age', 'type': str,
+             'doc': ('The age of the subject. The ISO 8601 Duration format is recommended, e.g., "P90D" for '
+                     '90 days old.'), 'default': None},
+            {'name': 'description', 'type': str,
+             'doc': 'A description of the subject, e.g., "mouse A10".', 'default': None},
+            {'name': 'genotype', 'type': str,
+             'doc': 'The genotype of the subject, e.g., "Sst-IRES-Cre/wt;Ai32(RCL-ChR2(H134R)_EYFP)/wt".',
+             'default': None},
+            {'name': 'sex', 'type': str,
+             'doc': ('The sex of the subject. Using "F" (female), "M" (male), "U" (unknown), or "O" (other) '
+                     'is recommended.'), 'default': None},
+            {'name': 'species', 'type': str,
+             'doc': ('The species of the subject. The formal latin binomal name is recommended, e.g., "Mus musculus"'),
+             'default': None},
+            {'name': 'subject_id', 'type': str, 'doc': 'A unique identifier for the subject, e.g., "A10"',
+             'default': None},
+            {'name': 'weight', 'type': (float, str),
+             'doc': ('The weight of the subject, including units. Using kilograms is recommended. e.g., "0.02 kg". '
+                     'If a float is provided, then the weight will be stored as "[value] kg".'),
+             'default': None},
             {'name': 'date_of_birth', 'type': datetime, 'default': None,
-             'doc': 'datetime of date of birth. May be supplied instead of age.'},
-            {'name': 'strain', 'type': str, 'doc': 'the strain of the subject', 'default': None})
+             'doc': 'The datetime of the date of birth. May be supplied instead of age.'},
+            {'name': 'strain', 'type': str, 'doc': 'The strain of the subject, e.g., "C57BL/6J"', 'default': None})
     def __init__(self, **kwargs):
         kwargs['name'] = 'subject'
         call_docval_func(super(Subject, self).__init__, kwargs)
@@ -67,7 +80,10 @@ def __init__(self, **kwargs):
         self.sex = getargs('sex', kwargs)
         self.species = getargs('species', kwargs)
         self.subject_id = getargs('subject_id', kwargs)
-        self.weight = getargs('weight', kwargs)
+        weight = getargs('weight', kwargs)
+        if isinstance(weight, float):
+            weight = weight + ' kg'
+        self.weight = weight
         self.strain = getargs('strain', kwargs)
         date_of_birth = getargs('date_of_birth', kwargs)
         if date_of_birth and date_of_birth.tzinfo is None:

diff --git a/src/pynwb/icephys.py b/src/pynwb/icephys.py
@@ -138,7 +138,11 @@ class IZeroClampSeries(CurrentClampSeries):
 
     @docval(*get_docval(CurrentClampSeries.__init__, 'name', 'data', 'electrode'),  # required
             {'name': 'gain', 'type': 'float', 'doc': 'Units: Volt/Volt'},  # required
-            *get_docval(CurrentClampSeries.__init__, 'stimulus_description', 'resolution', 'conversion', 'timestamps',
+            {'name': 'stimulus_description', 'type': str,
+             'doc': ('The stimulus name/protocol. Setting this to a value other than "N/A" is deprecated as of '
+                     'NWB 2.3.0.'),
+             'default': 'N/A'},
+            *get_docval(CurrentClampSeries.__init__, 'resolution', 'conversion', 'timestamps',
                         'starting_time', 'rate', 'comments', 'description', 'control', 'control_description',
                         'sweep_number'),
             {'name': 'unit', 'type': str, 'doc': "The base unit of measurement (must be 'volts')",

diff --git a/src/pynwb/misc.py b/src/pynwb/misc.py
@@ -268,7 +268,10 @@ class DecompositionSeries(TimeSeries):
              'doc': 'a table for describing the frequency bands that the signal was decomposed into', 'default': None},
             {'name': 'source_timeseries', 'type': TimeSeries,
              'doc': 'the input TimeSeries from this analysis', 'default': None},
-            {'name': 'source_channels', 'type': DynamicTableRegion, 'doc': 'the channels that provided the source data',
+            {'name': 'source_channels', 'type': DynamicTableRegion,
+             'doc': ('The channels that provided the source data. In the case of electrical recordings this is '
+                     'typically a DynamicTableRegion pointing to the electrodes table at NWBFile.electrodes, '
+                     'similar to ElectricalSeries.electrodes.'),
              'default': None},
             *get_docval(TimeSeries.__init__, 'resolution', 'conversion', 'timestamps', 'starting_time', 'rate',
                         'comments', 'control', 'control_description'))