-
Notifications
You must be signed in to change notification settings - Fork 63
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
API Proposal: Importing/loading spatial and spectral regions #2871
Comments
Of all of these options, I prefer API 1. Although, I think with version 4.0 we have an opportunity to make setting and retrieving subsets more straightforward. As a fresh user, I would assume the API for creating and retrieving subsets would look like I would propose moving that functionality into one method for creating subsets, one for creating them from a file, and one for retrieving them for version 4.0. It looks like So the two different methods for creating subsets would look like:
and
I know I took Proposal 1 and turned it into 10 sentences instead of 1 but I think renaming the method is an important part of clarifying the API for a user. Happy to hear your thoughts on this! |
@javerbukh , would an API called |
I know we do not support that currently but I do think it is possible to do programmatically. Should that be a blocker for this effort? |
🤷♀️ I am not sure if it is possible until we have a way to serialize the operators into something Maybe @camipacifici can chime in here. Also, regular users not familiar with glue internals might find "regions" more intuitive than "subsets". |
Thoughts on proposed API:
I like the idea of a method called It would be ideal to have the possibility of combining regions to create composite regions. It doesn't have to be MVP, but definitely something to plan. Maybe it could be a separate method. The user could load individual regions and then combine them according to the usual arithmetic we have in the UI. Just an idea. |
Just to make sure I understand, is this what you all are counter-proposing?
|
And just to be clear, I am not touching any export functions/methods. So design of |
It makes sense to have a separate method for loading with a file since the code will pretty different. My main point is that the naming convention should be consistent for all things that touch subsets/regions. I think using |
In that case, are we converging on Proposed API 1 as-is, @javerbukh and @camipacifici ? |
If the In any case, I think we are settling on the |
The ticket only asked to ponder about loading, not |
I didn't ask to ponder about how to refactor |
OK thanks for the clarification. Two 👍 so far from devs to refactor |
Re: #2871 (comment) @camipacifici , still just the 2 👍 and no 👎 . So does this mean we go with Proposed API 1? |
Update: I added Proposed API 3 based on discussions this morning. |
Thank you for this other proposal. Will there be similar calls for The UI functionality of the subset plugin should be improved regardless, so I do not see this as a problem among your cons. For the other cons, I rely on you all. Both API1 and API3 look ok to me from a user stand point. Please advise on what would be best technically. |
Good question and probably @kecnry can chime in here. A little weird for plugin API to export to object too when it can already export to files (standalone app users get no benefit from this) but it does put all the related functionality in one place. I don't see the |
If we go with API3, yes, I think it would make sense to have an We could also consider accessing these through the export plugin so that you can access any object directly from the export API instead of or in addition to writing to the file... we already have the logic there to determine the format). |
I was thinking |
When it comes the time people can add/remove plugins at will, does that mean they can no longer do these things unless those plugins are enabled (as opposed to attaching the API to helper/viewer)? |
I would not put any regions/subset-specific API into the export plugin, but we can use the general export method to also expose the underlying objects instead of only supporting writing to files.
Yes, but I don't see any issue with that myself 🤷♂️ |
Sure, but as far as the user is concerned, then exporting region API would be in the Export plugin. Unless you are saying we do that in addition to also putting export regions API in Subset Tools plugin? |
I think both is probably fine (subset plugin for now for the basic functionality, and export plugin down the road for translating to different formats, bulk retrieval, etc). |
Looks like API3 is good. I re-send my question about the |
Since I was the one that wrote this one, I am okay to deprecate it in favor of the new API. "interactive" is kinda meaningless now that we don't advertise loading static masks.
I cannot speak for this one. @kecnry last touched it in #2127 . I am thinking we can also deprecate it unless other people object. |
But this also means with Option 3, we also have to deprecate |
Right, those too. |
OK I updated pros and cons of Option 3 to include deprecation of all those APIs. Seems pretty disruptive but if people really like the plugin API idea, we have little choice. |
This does worry me a bit. I still like option 1, but can see the arguments for 3 as well. So I guess don't count me as a strong vote either way 😬. (so helpful) |
I think at tag-up today, we chose Proposed API 3, so here is the plan. We can choose to implement new things first and deprecated later for smaller pointed tickets. We can also choose to split import and export work into different tickets. Though doing them all at once might be cleaner. Proposed new API signatures are negotiable.
The plan:
|
Scope: Propose API to import/load spatial and spectral regions.
Out of scope:
🐱
Accepted plan
See #2871 (comment)
Spatial Regions
Existing API
These work in Cubeviz and Imviz.
viz_helper.load_regions_from_file()
jdaviz/jdaviz/core/helpers.py
Lines 643 to 644 in 069834a
viz_helper.load_regions()
jdaviz/jdaviz/core/helpers.py
Lines 675 to 676 in 069834a
To export
viz.app.get_subsets()
jdaviz/jdaviz/app.py
Lines 949 to 952 in 069834a
viz.get_interactive_regions()
jdaviz/jdaviz/core/helpers.py
Line 861 in f985a7f
Proposed API
No change; same as Existing API. One could argue to absorb
load_regions_from_file
intoload_regions
but both have existed for a while now and no one complained about it, so no motivation for extra churn.Spectral Regions
Existing API
This theoretically works on any viz with a spectrum viewer.
To export
viz.app.get_subsets()
jdaviz/jdaviz/app.py
Lines 949 to 952 in 069834a
Proposed API 1
Same as spatial regions:
viz_helper.load_regions_from_file()
viz_helper.load_regions()
Pros: Less API for user to remember.
Cons: Possibility of over-complicating the logic in those methods due to different usages and file formats between spatial and spectral regions. Might also have to rename
get_*
methods.Proposed API 2
Similar to spatial regions but not identical:
viz_helper.load_spectral_regions_from_file()
viz_helper.load_spectral_regions()
Pros: Cleanly separating out logic for spatial and spectral. User's intention is clear.
Cons: Possibility of code duplication where logic is shared between spatial and spectral regions. User has to remember to use different APIs for spatial vs spectral. Might have to rename spatial region methods by adding
spatial
to them.Proposed API 3
The concept was originally suggested by @kecnry: The idea is we use plugin API directly. Example usage would be something like this (such functionality currently does not exist):
Pros: "import" might be okay instead of "load" for plugin method since we also have "export" plugin. The API is controlled by plugin, so no need to choose between attaching it to helper or viewer.
Not-a-con-but-also-not-a-pro: We have to implement the functionality in the plugin first to support the API and possible new GUI elements to go with it.
Cons: Unclear what the behavior should be when a region file has multiple regions to be loaded via this plugin API, since the regions package does not understand glue Subset operations. For Imviz, behavior can be confusing when user changes Orientation between importing regions via this API. We have to deprecate
load_*
andget_*
methods in helpers.The text was updated successfully, but these errors were encountered: