Address comments, improve doc

Author: rly

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

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 = str(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:

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')",

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'))

tests/integration/hdf5/test_nwbfile.py

@@ -209,7 +209,7 @@ def setUpContainer(self):
                        sex='M',
                        species='Rattus norvegicus',
                        subject_id='RAT123',
-                       weight='2 lbs',
+                       weight='2 kg',
                        date_of_birth=datetime(1970, 1, 1, 12, tzinfo=tzutc()),
                        strain='my_strain')
 

tests/unit/test_file.py

@@ -423,7 +423,7 @@ def setUp(self):
                                sex='M',
                                species='Rattus norvegicus',
                                subject_id='RAT123',
-                               weight='2 lbs',
+                               weight='2 kg',
                                date_of_birth=datetime(2017, 5, 1, 12, tzinfo=tzlocal()),
                                strain='my_strain')
         self.start = datetime(2017, 5, 1, 12, tzinfo=tzlocal())
@@ -445,13 +445,20 @@ def test_constructor(self):
         self.assertEqual(self.subject.sex, 'M')
         self.assertEqual(self.subject.species, 'Rattus norvegicus')
         self.assertEqual(self.subject.subject_id, 'RAT123')
-        self.assertEqual(self.subject.weight, '2 lbs')
+        self.assertEqual(self.subject.weight, '2 kg')
         self.assertEqual(self.subject.date_of_birth, datetime(2017, 5, 1, 12, tzinfo=tzlocal()))
         self.assertEqual(self.subject.strain, 'my_strain')
 
     def test_nwbfile_constructor(self):
         self.assertIs(self.nwbfile.subject, self.subject)
 
+    def test_weight_float(self):
+        subject = Subject(
+            subject_id='RAT123',
+            weight=2.3,
+        )
+        self.assertEqual(subject.weight, '2.3 kg')
+
 
 class TestCacheSpec(TestCase):