Repository: NeurodataWithoutBorders/nwbinspector (language: python)

Issue:
[Bug]: Unclear Recommendation for Experimenter Name Formatting
### What happened?

If there is a formatting issue with the experimenter names, the following warning is raised:
"Message: The name of experimenter 'Donoghue T' does not match the DANDI form (Last, First Middle or Last, First M.)."

This comes from here:
https://github.com/NeurodataWithoutBorders/nwbinspector/blob/f9b58ebff25f8a05a1a1e1ba6823e29a06acc6ff/nwbinspector/checks/nwbfile_metadata.py#L64

I find the description of the format that is supposed to be followed quite confusing. 

From what I can tell there was some discussion of the format [here](https://github.com/NeurodataWithoutBorders/nwbinspector/issues/33), which I think concluded that "LastName, FirstName MiddleInitial" is what DANDI expects. Following this, if I update names to follow this (ex: "Donoghue, Thomas") nwbinspector no longer throws the warning. 

I'm not sure if I'm missing something broader here, but in terms of interpretability of the warning message, could it read:
```
f"The name of experimenter '{experimenter}' does not match the DANDI form "
"(LastName, FirstName MiddleInitial)."
```
^This seems to work, and matches the notes in the prior issue - I'm just not sure if it's maybe too restrictive (and perhaps doesn't cover other accepted inputs). Either way, I find that the current message isn't really interpretable. 

SideNote: I didn't spend any time parsing the regex or checking the details of the DANDI format, so maybe the general accepted pattern is more obvious from there. 

### Steps to Reproduce

```shell
The warning gets thrown with a wrong author format, for example "LastName Initial".
```


### Traceback

_No response_

### Operating System

macOS

### Python Executable

Conda

### Python Version

3.8

### Usage

Command Line Interface

### Were you streaming with ROS3?

No

### Package Versions

_No response_

### Code of Conduct

- [X] I agree to follow this project's [Code of Conduct](https://github.com/NeurodataWithoutBorders/nwbinspector/blob/dev/.github/CODE_OF_CONDUCT.rst)
- [X] Have you ensured this bug was not already [reported](https://github.com/neurodatawithoutborders/nwbinspector/issues)?
- [X] To the best of your ability, have you ensured this is a bug within the code that checks the NWBFile, rather than a bug in the NWBFile reader (e.g., [PyNWB](https://github.com/NeurodataWithoutBorders/pynwb) or [MatNWB](https://github.com/NeurodataWithoutBorders/matnwb))?


Discussion / hints:
Thanks for the feedback - this name convention topic has been rather extensive, and the response from that DANDI team is that "names are complicated", which is absolutely true in this day and age. The regex is indeed a bit restrictive IMO however, it is largely up to DANDI for what they want to accept.

As for improving the communicated message, let's discuss this and try to reach an improvement.

For your suggestions of utilizing parentheses,

```
Message = f"The name of experimenter '{experimenter}' does not match the DANDI form (LastName, FirstName MiddleInitial)."
```

I just worry that that makes people think they need to wrap their string in parentheses as well, such as

```python
nwbfile = pynwb.NWBFile(
    ...
    experimenters=["(Baker, Cody C.)"]
)
```

or even worse try something weird with tuples (specific to people using PyNWB, admitedly)

```python
nwbfile = pynwb.NWBFile(
    ...
    experimenters=("Baker", "Cody C.")
)
```


As for the message as it is right now, it is to indicate that the 'middle name' part of it can be either an initial, or a full middle name. *E.g.*, both of these are accepted

```python
nwbfile = pynwb.NWBFile(
    ...
    experimenters=["Baker, Cody C"]
)
```

and

```python
nwbfile = pynwb.NWBFile(
    ...
    experimenters=["Baker, Cody Carrington"]
)
```

How can I better communicate those two accepted cases in a non-confusing way?

EDIT:

Oh, also a third case of optional accepted period applied to the initial

```python
nwbfile = pynwb.NWBFile(
    ...
    experimenters=["Baker, Cody C."]
)
```
@CodyCBakerPhD 

oh, you are trying to communicate:

Last, First Middle
    or
Last, First M.

Yes, I also find this confusing. 

How about:

"The name of experimenter '{experimenter}' does not match the DANDI form: 'LastName, FirstName MiddleInitial.' or 'LastName, FirstName MiddleName'."



> "The name of experimenter '{experimenter}' does not match the DANDI form: 'LastName, FirstName MiddleInitial.' or 'LastName, FirstName, MiddleName'."

That reads fine to me, what do you think @TomDonoghue 
OH! My main misinterpretation here is that I wasn't parsing the original message into two separate layouts, reading it all as one designation rather than two (basically, reading "First Middle or Last" as a description of the 2nd element of the overall name, rather than the `or` indicating two valid name layouts). Something about having the whole thing in a () threw me off I think.  Now that's it's clicked I see what's going on. That's partly my bad on getting confused hahaha. 

I like @bendichter's suggestion. If I'm now understanding, then writing it as
`"LastName, FirstName MiddleInitial" or "LastName, FirstName MiddleName"`
more clearly (to me) parses out the two slightly different acceptable conventions. 

To Cody's list above: I believe this covers the acceptable cases, other than it doesn't explicitly describe whether the initial should have a period, but since `Donoghue, Thomas R.` or `Donoghue, Thomas R` are both accepted, not specifying this separately seems fine I think?
As long as we are being exhaustive, maybe we could do:

"The name of experimenter '{experimenter}' does not match the DANDI form: 'LastName, Firstname', 'LastName, FirstName MiddleInitial.' or 'LastName, FirstName, MiddleName'."
I think listing all is fine - though I think setting it up as _the_ DANDI form is partly what made me think it was all one description, so maybe:
```
"The name of experimenter '{experimenter}' does not match any of the accepted DANDI forms, which are: 'LastName, Firstname', 'LastName, FirstName MiddleInitial.' or 'LastName, FirstName, MiddleName'."
```
(or similar, with updated phrasing that clearly notes there is more than one acceptable layout here)

Fix patch:
diff --git a/CHANGELOG.md b/CHANGELOG.md
new file mode 100644
index 000000000..6dcdd8c85
--- /dev/null
+++ b/CHANGELOG.md
@@ -0,0 +1,4 @@
+# Upcoming
+
+### Improvements
+* Enhanced human-readability of the return message from `check_experimenter_form`. [PR #254](https://github.com/NeurodataWithoutBorders/nwbinspector/pull/254)
diff --git a/nwbinspector/checks/nwbfile_metadata.py b/nwbinspector/checks/nwbfile_metadata.py
index bf8e80872..f900557a1 100644
--- a/nwbinspector/checks/nwbfile_metadata.py
+++ b/nwbinspector/checks/nwbfile_metadata.py
@@ -60,8 +60,8 @@ def check_experimenter_form(nwbfile: NWBFile):
         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.)."
+                    f"The name of experimenter '{experimenter}' does not match any of the accepted DANDI forms: "
+                    "'LastName, Firstname', 'LastName, FirstName MiddleInitial.' or 'LastName, FirstName, MiddleName'."
                 )
             )
 


Test patch:
diff --git a/tests/unit_tests/test_nwbfile_metadata.py b/tests/unit_tests/test_nwbfile_metadata.py
index 7b9acdc17..ae9c7eff6 100644
--- a/tests/unit_tests/test_nwbfile_metadata.py
+++ b/tests/unit_tests/test_nwbfile_metadata.py
@@ -132,8 +132,8 @@ def test_check_experimenter_form_fail():
     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.)."
+                "The name of experimenter 'First Middle Last' does not match any of the accepted DANDI forms: "
+                "'LastName, Firstname', 'LastName, FirstName MiddleInitial.' or 'LastName, FirstName, MiddleName'."
             ),
             importance=Importance.BEST_PRACTICE_SUGGESTION,
             check_function_name="check_experimenter_form",