Merge pull request #138 from NeurodataWithoutBorders/check_session_start_time

[Add Check]: attempt to check for 'default' start times

Author: CodyCBakerPhD

docs/best_practices/nwbfile_metadata.rst

@@ -11,18 +11,25 @@ File Organization
 
 .. _best_practice_global_time_reference:
 
-Global Time Reference
-~~~~~~~~~~~~~~~~~~~~~
+Global Date and Time Reference
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-An :nwb-schema:ref:`sec-NWBFile` can have two primary time references. The global time reference for all objects in the
-:nwb-schema:ref:`sec-NWBFile` is the ``timestamps_reference_time``. By default, this is also set to the
-``session_start_time``, but when writing multiple NWBFiles that are all designed to align
-to the same time reference, the ``session_start_time`` may be set separately from the explicitly specified common
-``timestamps_reference_time`` used across all of the NWBFiles.
+An :nwb-schema:ref:`sec-NWBFile` can have two primary time references. The global date and time reference for all
+objects in the :nwb-schema:ref:`sec-NWBFile` is the ``timestamps_reference_time``. By default, this is set to the
+``session_start_time``, but when writing multiple NWBFiles that are all designed to align to the same time reference,
+the ``timestamp_reference_time`` used across all of the NWBFiles may be set separately from the ``session_start_time``.
 
 All time-related data in the NWBFile should be synchronized to the ``timestamps_reference_time`` so that future users
 are able to understand the timing of all events contained within the NWBFile.
 
+Given the importance of this field within an :nwb-schema:ref:`sec-NWBFile`, is it critical that it be set to a proper
+value. Default values should generally not be used for this field. If the true date is unknown, use your
+best guess. If the exact start time is unknown, then it is fine to simply set it to midnight on that date.
+
+
+Check functions: :py:meth:`~nwbinspector.checks.nwbfile_metadata.check_session_start_time_old_date`,
+:py:meth:`~nwbinspector.checks.nwbfile_metadata.check_session_start_time_future_date`,
+
 
 
 .. _best_practice_acquisition_and_processing:

nwbinspector/checks/nwbfile_metadata.py

@@ -1,5 +1,6 @@
 """Check functions that examine general NWBFile metadata."""
 import re
+from datetime import datetime
 
 from pynwb import NWBFile, ProcessingModule
 from pynwb.file import Subject
@@ -15,6 +16,27 @@
 PROCESSING_MODULE_CONFIG = ["ophys", "ecephys", "icephys", "behavior", "misc", "ogen", "retinotopy"]
 
 
+@register_check(importance=Importance.BEST_PRACTICE_SUGGESTION, neurodata_type=NWBFile)
+def check_session_start_time_old_date(nwbfile: NWBFile):
+    """Check if the session_start_time was set to an appropriate value."""
+    if nwbfile.session_start_time <= datetime(1980, 1, 1).astimezone():
+        return InspectorMessage(
+            message=(
+                f"The session_start_time ({nwbfile.session_start_time}) may not be set to the true date of the "
+                "recording."
+            )
+        )
+
+
+@register_check(importance=Importance.CRITICAL, neurodata_type=NWBFile)
+def check_session_start_time_future_date(nwbfile: NWBFile):
+    """Check if the session_start_time was set to an appropriate value."""
+    if nwbfile.session_start_time >= datetime.now().astimezone():
+        return InspectorMessage(
+            message=f"The session_start_time ({nwbfile.session_start_time}) is set to a future date and time."
+        )
+
+
 @register_check(importance=Importance.BEST_PRACTICE_SUGGESTION, neurodata_type=NWBFile)
 def check_experimenter(nwbfile: NWBFile):
     """Check if an experimenter has been added for the session."""

tests/unit_tests/test_nwbfile_metadata.py

@@ -1,5 +1,5 @@
 from uuid import uuid4
-from datetime import datetime
+from datetime import datetime, timezone
 
 from pynwb import NWBFile, ProcessingModule
 from pynwb.file import Subject
@@ -18,6 +18,8 @@
     check_subject_age,
     check_subject_species,
     check_processing_module_name,
+    check_session_start_time_old_date,
+    check_session_start_time_future_date,
     PROCESSING_MODULE_CONFIG,
 )
 from nwbinspector.tools import make_minimal_nwbfile
@@ -26,6 +28,47 @@
 minimal_nwbfile = make_minimal_nwbfile()
 
 
+def test_check_session_start_time_old_date_pass():
+    assert check_session_start_time_old_date(minimal_nwbfile) is None
+
+
+def test_check_session_start_time_old_date_fail():
+    nwbfile = NWBFile(
+        session_description="",
+        identifier=str(uuid4()),
+        session_start_time=datetime(1970, 1, 1, 0, 0, 0, 0, timezone.utc),
+    )
+    assert check_session_start_time_old_date(nwbfile) == InspectorMessage(
+        message="The session_start_time (1970-01-01 00:00:00+00:00) may not be set to the true date of the recording.",
+        importance=Importance.BEST_PRACTICE_SUGGESTION,
+        check_function_name="check_session_start_time_old_date",
+        object_type="NWBFile",
+        object_name="root",
+        location="/",
+    )
+
+
+def test_check_session_start_time_future_date_pass():
+    nwbfile = NWBFile(session_description="", identifier=str(uuid4()), session_start_time=datetime(2010, 1, 1))
+    assert check_session_start_time_future_date(nwbfile) is None
+
+
+def test_check_session_start_time_future_date_fail():
+    nwbfile = NWBFile(
+        session_description="",
+        identifier=str(uuid4()),
+        session_start_time=datetime(2030, 1, 1, 0, 0, 0, 0, timezone.utc),
+    )
+    assert check_session_start_time_future_date(nwbfile) == InspectorMessage(
+        message="The session_start_time (2030-01-01 00:00:00+00:00) is set to a future date and time.",
+        importance=Importance.CRITICAL,
+        check_function_name="check_session_start_time_future_date",
+        object_type="NWBFile",
+        object_name="root",
+        location="/",
+    )
+
+
 def test_check_experimenter():
     assert check_experimenter(minimal_nwbfile) == InspectorMessage(
         message="Experimenter is missing.",