[JOSS] code and docstrings

[AJQuinn]

Hello - overall I'm impressed with the code quality and writing of this package. Its clear that care has been taken and it appears that the functions and objects handle complicated analyses relatively clearly. The tests are thorough and cover a range of sensible checks. Well done!

My comments are limited to some aspects of code organisation and documentation.

- Code formatting/linting

The code doesn't appear to use a formal style checker or linter, running flake8 spectral_connectivity/*py from the route dir gives quite a lot of suggestions - some more reasonable than others.... You may or may not want to adopt formal code-checking as part of the test suite. I find flake8 useful (ignoring some error codes) but this is up to you.

Flake does highlight the following points that I think are work checking out.

• some docstrings are missing, or applied inconsistently. flake8 spectral_connectivity/*py | grep Missing

  spectral_connectivity/connectivity.py:1:1: D100 Missing docstring in public module
  spectral_connectivity/connectivity.py:119:1: D107 Missing docstring in __init__
  spectral_connectivity/connectivity.py:159:1: D102 Missing docstring in public method
  spectral_connectivity/connectivity.py:165:1: D102 Missing docstring in public method
  spectral_connectivity/connectivity.py:263:1: D102 Missing docstring in public method
  spectral_connectivity/connectivity.py:272:1: D102 Missing docstring in public method
  spectral_connectivity/connectivity.py:520:1: D102 Missing docstring in public method
  spectral_connectivity/connectivity.py:735:1: D102 Missing docstring in public method
  spectral_connectivity/connectivity.py:738:1: D102 Missing docstring in public method
  spectral_connectivity/connectivity.py:1271:1: D413 Missing blank line after last section
  spectral_connectivity/connectivity.py:1271:1: D413 Missing blank line after last section
  spectral_connectivity/minimum_phase_decomposition.py:1:1: D100 Missing docstring in public module
  spectral_connectivity/minimum_phase_decomposition.py:27:1: D413 Missing blank line after last section
  spectral_connectivity/minimum_phase_decomposition.py:27:1: D413 Missing blank line after last section
  spectral_connectivity/minimum_phase_decomposition.py:100:1: D413 Missing blank line after last section
  spectral_connectivity/minimum_phase_decomposition.py:100:1: D413 Missing blank line after last section
  spectral_connectivity/statistics.py:1:1: D100 Missing docstring in public module
  spectral_connectivity/statistics.py:8:1: D413 Missing blank line after last section
  spectral_connectivity/statistics.py:8:1: D413 Missing blank line after last section
  spectral_connectivity/statistics.py:35:1: D103 Missing docstring in public function
  spectral_connectivity/transforms.py:1:1: D100 Missing docstring in public module
  spectral_connectivity/transforms.py:72:1: D107 Missing docstring in __init__
  spectral_connectivity/transforms.py:103:1: D105 Missing docstring in magic method
  spectral_connectivity/transforms.py:136:1: D102 Missing docstring in public method
  spectral_connectivity/transforms.py:144:1: D102 Missing docstring in public method
  spectral_connectivity/transforms.py:164:1: D102 Missing docstring in public method
  spectral_connectivity/transforms.py:177:1: D102 Missing docstring in public method
  spectral_connectivity/transforms.py:183:1: D102 Missing docstring in public method
  spectral_connectivity/transforms.py:202:1: D102 Missing docstring in public method
  spectral_connectivity/transforms.py:212:1: D102 Missing docstring in public method
  spectral_connectivity/transforms.py:216:1: D102 Missing docstring in public method
  spectral_connectivity/transforms.py:220:1: D102 Missing docstring in public method
  spectral_connectivity/transforms.py:224:1: D102 Missing docstring in public method
  spectral_connectivity/transforms.py:384:1: D413 Missing blank line after last section
  spectral_connectivity/transforms.py:384:1: D413 Missing blank line after last section
  spectral_connectivity/transforms.py:425:1: D413 Missing blank line after last section
  spectral_connectivity/transforms.py:425:1: D413 Missing blank line after last section
  spectral_connectivity/transforms.py:626:1: D413 Missing blank line after last section
  spectral_connectivity/transforms.py:626:1: D413 Missing blank line after last section
  spectral_connectivity/transforms.py:695:1: D413 Missing blank line after last section
  spectral_connectivity/transforms.py:695:1: D413 Missing blank line after last section
  spectral_connectivity/wrapper.py:1:1: D100 Missing docstring in public module

  These are mainly on properties and methods of objects but are worth completing, a single line of context would do in most cases. Multitaper.tapers seems to be partially documented.

- Simulations and plotting functions

The simulation functions and plotting utilities in the notebooks are very useful and, I think, deserve to be included in the package as their own submodules. This could really simplify your documentation and be a big help going forward - this one is up to you though, you may not want to maintain this longer term.

I've done something similar in a package based on autoregressive modelling and find it really helpful to be able to quickly generate a known system from within the package.

Maintaining high-quality plotting functions can be a pain, but I think some simple options to help get people started would be great.

- Requirements and versions

The versions of required packages in setup.py and environment.yml seemt to be mismatched. Makes sense that setup has the basics and the conda env would have a more complete list.

numpy, pandas and pytest have version limits in setup but not in the conda env. I guess conda will resolve this during install but it would certainly be simpler if they matched.

- Makefile

Your Makefile seems to be broken. Calling Make gives a Makefile:3: *** missing separator. Stop. error.

It seems like the makefile might not be used much from the limited options in it, but I'd recommend either fixing it up or removing it.

xref: https://github.com/openjournals/joss-reviews/issues/4840

[AJQuinn]

Perhaps thats too much for a single comment..! Please let me know if that all makes sense, happy to chat more if anything is worth clarifying or discussing.

[edeno]

Hi @AJQuinn , I believe I have addressed everything in this issue, so I will close it. Please let me know if I haven't addressed anything sufficiently. I am working on updating the documentation for the other issue currently.