Merge remote-tracking branch 'origin/order_of_images' into order_of_images

Author: bendichter

docs/best_practices/nwbfile_metadata.rst

@@ -202,13 +202,19 @@ Species
 ~~~~~~~
 
 The ``species`` of a :nwb-schema:ref:`sec-Subject` should be set to the proper
-:wikipedia:`Latin binomial <Binomial_nomenclature>`. *E.g.*, a rat would be "Rattus norvegicus". Specific subspecies
-may be further specified by a dash, *e.g.*, "Rattus norvegicus - Long Evans".
+:wikipedia:`Latin binomial <Binomial_nomenclature>`. *E.g.*, a rat would be "Rattus norvegicus".
 
 Check function: :py:meth:`~nwbinspector.checks.nwbfile_metadata.check_subject_species`
 
 
 
+Strain
+~~~~~~~
+
+The ``strain`` of a :nwb-schema:ref:`sec-Subject` should be set to further indicate the subspecies or breed or common genetic modification. *E.g.*, common strains for species "Rattus norvegicus" might include "Long Evans", "Sprague-Dawley", "Wistar", or "C57BL/6". If no specific strain is used, then simply indicate "Wild Type".
+
+
+
 .. _best_practice_subject_age:
 
 Age

docs/user_guide/command_line_usage.rst

@@ -17,34 +17,106 @@ You may then run the NWBInspector via the command line via the following usages
 which should quickly display a basic report to your console window.
 
 
-Common Flags
-------------
+All available options for the CLI may be viewed by calling :code:`nwbinspector --help`. We will now highlight some of
+the most useful of these options.
+
+
+
+Formatting the Report
+---------------------
+
+The basic report layout organizes by :py:attr:`~nwbinspector.register_check.InspectorMessage.importance` first and
+:py:attr:`~nwbinspector.register_check.InspectorMessage.file_path` last.
+
+For example,
+
+::
+
+    insert example
+
+however, the NWBInspector supports more general organization as defined by the `--levels` flag. To use this flag,
+you must pass a series a comma-separated words that correspond to any attributes of the
+:py:class:`~nwbinspector.register_check.InspectorMessage` in any order.
+
+For example,
+
+::
+
+    nwbinspector path/to/my/data/dir/ --levels check_function_name,object_type,file_path
+
+.. note::
+
+    The :py:attr:`~nwbinspector.register_check.InspectorMessage.message` itself cannot be used in organization.
+
+The ascending or descending order of each of these levels may be additionally controlled with the `--reverse` flag,
+which is likewise a comma-separated series of boolean words.
+
+For example,
+
+::
+
+    nwbinspector path/to/my/data/dir/ --levels check_function_name,object_type,file_path --reverse false,true,false
+
+.. note::
+
+    Valid 'boolean words' are any capitalizations of the words ``"false", "true"`` or characters ``"F", "T"``, and even
+    numbers like ``"0, 1"``.
+
+
+The defalt report also aggregates identical outputs into a summary over multiple files;
+
+::
+
+    insert example
+
+and it will do this any time the last value of the ``--levels`` list is ``file_path``. To see the full report of every
+issue over all files, use the ``--detailed`` flag.
+
+
+
+Saving the Report
+-----------------
 
 There are many common options you can specify with flags, such as saving the report for future reference...
 
 ::
 
-    nwbinspector path/to/my/data.nwb --log-file path/to/my/nwbinspector_report.txt
+    nwbinspector path/to/my/data.nwb --report-file-path path/to/my/nwbinspector_report.txt
 
-    # if a report file from a previous run of the inspector is already present at the location
-    # it can be overwritten with '-o'
-    nwbinspector path/to/my/data.nwb -o --log-file path/to/my/nwbinspector_report.txt
 
+If a report file from a previous run of the inspector is already present at the location, it can be overwritten with
+the ``-o`` or ``--overwrite`` flag...
+
+::
 
-Or enabling parallelization over a directory to allow the NWBInspector to run many times faster...
+    nwbinspector path/to/my/data.nwb --report-file-path path/to/my/nwbinspector_report.txt -o
+
+
+
+Faster Inspection
+-----------------
+
+The NWBInspector supports parallelization over a directory to allow the NWBInspector to run many times faster. To use
+this feature, simply set the ``--n-jobs`` flag to either a positive integer corresponding to the number of CPUs you
+wish to use, or set to ``-1`` to use all available system resources.
+
+For example,
 
 ::
 
-    # '--n-jobs -1' will automatically use as many resources as are available on your system
     nwbinspector path/to/my/data/dir/ --n-jobs -1
 
 
-And if your file was written using NWB extensions (link to extensions) that may possess their own specific
-checks, those checks can be added ...
 
-::
+External Modules
+----------------
 
-    nwbinspector path/to/my/data.nwb -m my_extension_module1 my_extension_module2
+If the NWBFiles being inspected require an external module to parse, or have externally defined check registries (such
+as those specific to an :nwb-schema:ref:`NWB Extension<extending-the-format>`), these can be specified with the ``-m``
+or ``--modules`` flag.
 
+For example,
 
-Other flags may be viewed in the command line by calling :code:`nwbinspector --help`.
+::
+
+    nwbinspector path/to/my/data.nwb -m my_extension_module1 my_extension_module2

nwbinspector/checks/nwbfile_metadata.py

@@ -6,6 +6,7 @@
 from pynwb.file import Subject
 
 from ..register_checks import register_check, InspectorMessage, Importance
+from ..utils import is_module_installed
 
 duration_regex = (
     r"^P(?!$)(\d+(?:\.\d+)?Y)?(\d+(?:\.\d+)?M)?(\d+(?:\.\d+)?W)?(\d+(?:\.\d+)?D)?(T(?=\d)(\d+(?:\.\d+)?H)?(\d+(?:\.\d+)"
@@ -38,12 +39,31 @@ def check_session_start_time_future_date(nwbfile: NWBFile):
 
 
 @register_check(importance=Importance.BEST_PRACTICE_SUGGESTION, neurodata_type=NWBFile)
-def check_experimenter(nwbfile: NWBFile):
+def check_experimenter_exists(nwbfile: NWBFile):
     """Check if an experimenter has been added for the session."""
     if not nwbfile.experimenter:
         return InspectorMessage(message="Experimenter is missing.")
 
 
+@register_check(importance=Importance.BEST_PRACTICE_SUGGESTION, neurodata_type=NWBFile)
+def check_experimenter_form(nwbfile: NWBFile):
+    """Check the text form of each experimenter to see if it matches the DANDI regex pattern."""
+    if is_module_installed(module_name="dandi"):
+        from dandischema.models import NAME_PATTERN  # for most up to date version of the regex
+    else:
+        NAME_PATTERN = r"^([\w\s\-\.']+),\s+([\w\s\-\.']+)$"  # copied on 7/12/22
+
+    for experimenter in nwbfile.experimenter:
+        experimenter = experimenter.decode() if isinstance(experimenter, bytes) else experimenter
+        if re.match(string=experimenter, pattern=NAME_PATTERN) is None:
+            yield InspectorMessage(
+                message=(
+                    f"The name of experimenter '{experimenter}' does not match the DANDI form "
+                    "(Last, First Middle or Last, First M.)."
+                )
+            )
+
+
 @register_check(importance=Importance.BEST_PRACTICE_SUGGESTION, neurodata_type=NWBFile)
 def check_experiment_description(nwbfile: NWBFile):
     """Check if a description has been added for the session."""

setup.py

@@ -5,7 +5,7 @@
     long_description = f.read()
 setup(
     name="nwbinspector",
-    version="0.4.7",
+    version="0.4.9",
     description="Tool to inspect NWB files for best practices compliance.",
     long_description=long_description,
     long_description_content_type="text/markdown",

tests/unit_tests/test_nwbfile_metadata.py

@@ -7,7 +7,8 @@
 from nwbinspector import (
     InspectorMessage,
     Importance,
-    check_experimenter,
+    check_experimenter_exists,
+    check_experimenter_form,
     check_experiment_description,
     check_institution,
     check_keywords,
@@ -70,37 +71,79 @@ def test_check_session_start_time_future_date_fail():
     )
 
 
-def test_check_experimenter_pass():
+def test_check_experimenter_exists_pass():
     nwbfile = NWBFile(
         session_description="",
         identifier=str(uuid4()),
         session_start_time=datetime.now().astimezone(),
         experimenter=["Last, First"],
     )
-    assert check_experimenter(nwbfile) is None
+    assert check_experimenter_exists(nwbfile) is None
 
 
-def test_check_experimenter_bytestring_pass():
+def test_check_experimenter_exists_bytestring_pass():
     nwbfile = NWBFile(
         session_description="",
         identifier=str(uuid4()),
         session_start_time=datetime.now().astimezone(),
         experimenter=[b"Last, First"],
     )
-    assert check_experimenter(nwbfile) is None
+    assert check_experimenter_exists(nwbfile) is None
 
 
-def test_check_experimenter_fail():
-    assert check_experimenter(minimal_nwbfile) == InspectorMessage(
+def test_check_experimenter_exists_fail():
+    assert check_experimenter_exists(minimal_nwbfile) == InspectorMessage(
         message="Experimenter is missing.",
         importance=Importance.BEST_PRACTICE_SUGGESTION,
-        check_function_name="check_experimenter",
+        check_function_name="check_experimenter_exists",
         object_type="NWBFile",
         object_name="root",
         location="/",
     )
 
 
+def test_check_experimenter_form_pass():
+    nwbfile = NWBFile(
+        session_description="",
+        identifier=str(uuid4()),
+        session_start_time=datetime.now().astimezone(),
+        experimenter=["Last, First"],
+    )
+    assert check_experimenter_form(nwbfile=nwbfile) is None
+
+
+def test_check_experimenter_form_bytestring_pass():
+    nwbfile = NWBFile(
+        session_description="",
+        identifier=str(uuid4()),
+        session_start_time=datetime.now().astimezone(),
+        experimenter=[b"Last, First"],
+    )
+    assert check_experimenter_form(nwbfile=nwbfile) is None
+
+
+def test_check_experimenter_form_fail():
+    nwbfile = NWBFile(
+        session_description="",
+        identifier=str(uuid4()),
+        session_start_time=datetime.now().astimezone(),
+        experimenter=["First Middle Last"],
+    )
+    assert check_experimenter_form(nwbfile=nwbfile) == [
+        InspectorMessage(
+            message=(
+                "The name of experimenter 'First Middle Last' does not match the DANDI form "
+                "(Last, First Middle or Last, First M.)."
+            ),
+            importance=Importance.BEST_PRACTICE_SUGGESTION,
+            check_function_name="check_experimenter_form",
+            object_type="NWBFile",
+            object_name="root",
+            location="/",
+        )
+    ]
+
+
 def test_check_experiment_description():
     assert check_experiment_description(minimal_nwbfile) == InspectorMessage(
         message="Experiment description is missing.",