JOSS review: repo comments

[kbonney]

Hi @jranalli, I was able to install the package and execute all of the tests and notebooks without major issue. Below are a few comments regarding the repository:

• [x] Does installation proceed as outlined in the documentation? The package matplotlib is used in notebooks and by the visualization module, so it should be added to dependencies in setup.py.
• [x] Automated tests: Are there automated tests or manual steps described so that the functionality of the software can be verified? While tests are present and automated, they generate over 65 thousand warnings. I am not suggesting you resolve all of these for the review, but this does cause concern for the sustainability of the package going forward and should be investigated at some point. I would also recommend running the tests in the GH action by simply running pytest once rather than for each file. That will make it easier if and when you expand the test suite to more files.
• [x] Example usage: Do the authors include examples of how to use the software (ideally to solve real-world analysis problems). The suite of examples are great and cover a lot of the functionality, but I have a slight concern about field_demo.ipynb. In the notebook it is suggested that a user could use the cmv package to generate CMV data to validate the component locations following the field analysis methodology. My understanding is that the cmv package uses the same component locations which you would be validating to generate the CMV data. For demonstration purposes this is fine, but it should be clarified in the text that in practical use cases the CMV data should be independent of the locations being validated.
• [x] Functionality documentation: Is the core functionality of the software documented to a satisfactory level (e.g., API method documentation)? I saw in #7 that an RTD page was made for the package, however it doesn't look like a link can be easily found by a potential user. I recommend adding the link to somewhere in the REAMDE.md, to the package metadata in setup.py, and the GitHub "About" metadata in the top right widget on the repo homepage. Also, it looks like the demos folder was moved deep into the docs folder so that you can display them on a page in the documentation. This makes it difficult for users to find the examples in the code, so I recommend moving the folder back to the top level and using nblink to reference their location in the docs.

Happy to clarify/assist with any of these items.

[jranalli]

Since these changes weren't that big structurally, I made them in the same pull request as responding to Issue #11 (pull request #13). I took care of the easy ones, and have one minor point left.

1) Added, along with instructions to install jupyter for the demos in the README 2) Modified the action to run them all at once. 3) You're correct, they should be independent. The assumption to do this is that the plant has only isolated mislabeling and that has been consistent with the operational data experience of using the method. In such a case, we've found that "good enough" CMVs can be identified even when keeping the scrambled data, because the errors introduced by false positions end up averaging out as you incorporate the large plant. But it is in principle a limitation of the method. I guess you could add the CMV calculation to the iterative loop of correcting the positions, but we haven't had data that would require that to really test out whether it would work. Nonetheless, I've added a little more notation there to clarify. 4) I added links to the Readme and the github About box, but am not done here. I still need to look into how to use nblink to modify the demo locations.

[jranalli]

OK, got nblink figured out and moved the demos back to the parent directory in the latest push to the PR. Demos appear to build correctly in the PR-level readthedocs build. So I would propose that PR #13 addresses all these concerns per your approval.

[kbonney]

@jranalli, thanks for addressing these comments. #13 looks good to me.