Improving Software Sustainability of `brainglobe-utils`

[willGraham01]

brainglobe-utils was designed to be our package that contains a wide range of general-purpose functionality that can be re-used across all brainglobe tools. However, it currently suffers from a number of problems from a software sustainability standpoint that we should address.

Preliminaries for new developers

A new developer tackling this issue should first head over to our developer documentation (site, repo) and familiarise themselves with the content.

The content itself is fairly new - if during tackling this issue, or even after reading through it, there are clarifications that need to be made, please raise issues on the documentation site and propose solutions! :slightly_smiling_face:

Improving brainglobe-utils

Once familiar with our developer docs; the following topics need to be addressed in brainglobe-utils.

Where there's already an issue tracking one of these tasks, it's linked to below. However feel free to edit the content of these issues with updated task lists etc.

Documentation

• [ ] A lack of docstrings https://github.com/brainglobe/brainglobe-utils/issues/19. If we don't have proper docstrings, it is not clear to us as developers what functionality has actually been pulled into this repository.
• [x] The imio package was recently merged into brainglobe_utils as the image_io submodule. However, imio itself was never properly documented, and so we should make amends and document image_io: https://github.com/brainglobe/brainglobe-utils/issues/34

Testing

• [x] We also want to improve our test coverage to ~90% on brainglobe-utils. There is currently no issue to track this, but it might be worth opening them on a per-submodule basis.
• [ ] Improve napari-related test infrastructure and share it across BrainGlobe
  • [ ] #68
  • [ ] https://github.com/brainglobe/BrainGlobe/issues/69
• [ ] https://github.com/brainglobe/BrainGlobe/issues/63

Refactoring

• [ ] There are several refactor-ings that can be done to bring additional functionality across the brainglobe tool-suite into utils. Some that spring to mind:
  • [ ] https://github.com/brainglobe/brainglobe-utils/issues/3
  • [x] https://github.com/brainglobe/brainreg/issues/180
  • [ ] https://github.com/brainglobe/BrainGlobe/issues/5

[alessandrofelder]

Re-using utils code elsewhere

• [x] https://github.com/brainglobe/cellfinder/issues/327#issuecomment-1883323757

[adamltyson]

I think this high-level issue can be closed now, the remaining individual issues are still open.

Thanks again @K-Meech!