search

brainglobe / brainglobe-meta

(Meta-)package repository for BrainGlobe's Python tools for computational neuroanatomy.
BSD 3-Clause "New" or "Revised" License
10 stars 0 forks source link

[Feature] Decide how to expose tools to users #5

Open willGraham01 opened 1 year ago

willGraham01 commented 1 year ago

Is your feature request related to a problem? Please describe. We should decide which, and how, to expose the various BrainGlobe tools included in the meta-package to users.

We should also document the new names/aliases of the tools.

Describe the solution you'd like Users should be able to select the tool they wish to use from methods within the brainglobe namespace, which we can achieve in the manner described in Adam's comment here.

Describe alternatives you've considered We could also expose all the (user-facing) sub-packages in __init__.py which has the advantage of not making the sub-package documentation redundant (until it relocates to the new website of course, when we can update our pointers accordingly).

brainglobe/__init__.py

import cellfinder-core as cellfinder
import brainreg

Then users would still have access to every public-facing tool, but the under-the-hood packages can remain hidden and we can reorganise them as we see fit.

import bg.cellfinder

# Do cellfinder things with bg.cellfinder, without ever worrying about cellfinder-core being there under-the-hood.
adamltyson commented 1 year ago

We should probably decide if we're going to keep the tool names (e.g. bg.cellfinder) or focus on application bg.cell_detector_3d), or both? I think I'm leaning towards application, because then this makes it easier to slowly build up a comprehensive toolbox of functionality, and organise repos as we see fit. Any thoughts @alessandrofelder?

adamltyson commented 1 year ago

With the above, all the individual packages would be available anyway, so we wouldn't break any existing functionality.

alessandrofelder commented 1 year ago

I think I'm leaning towards application

If we go down this route, how would we organise the user documentation? Would it be confusing for users familiarising themselves with BG that what they know as bg.cell_detector_3d is actually cellfinder in disguise? For this, having a 1:1 correspondence between python package and naming in metapackage would be good?

adamltyson commented 1 year ago

If we go down this route, how would we organise the user documentation? Would it be confusing for users familiarising themselves with BG that what they know as bg.cell_detector_3d is actually cellfinder in disguise? For this, having a 1:1 correspondence between python package and naming in metapackage would be good?

One idea would be to keep the docs as they are for a while while we build the metapackage (and a napari meta-plugin?). Then one day we release "BrainGlobe 2", which includes the introduction of the new structure. In most cases it would just be a case of bulk renaming of docs and UI elements.

We could make the naming in the metapackage match the napari plugin fairly easily. not sure if we'd want to rename the packages though.

Not sure if this is a good idea, just putting it out there because once we make a decision, we should stick to it.

alessandrofelder commented 1 year ago

Think I'm leaning towards keeping the original names (but consolidating cellfinder-napari and cellfinder-core into one repo etc.) because I expect our users recognise them already and so will have a smoother switch to the metapackage, and things only ever have one name?

adamltyson commented 1 year ago

Think I'm leaning towards keeping the original names (but consolidating cellfinder-napari and cellfinder-core into one) because I expect our users recognise them already and so will have a smoother switch to the metapackage, and things only ever have one name?

Sounds good to me. I think I'm convinced. No reason why we can't have bg.cellfinder and bg.some_new_thing_that_doesnt_need_its_own_name coexisting too.