Implement associations between Data layers

[bmorris3]

Description

This PR adds a dictionary _data_associations to the Application class, and methods for finding associations between glue Data entries in the DataCollection.

Suppose you have two layers A and B which are associated with one another, e.g., layer B is the DQ array for the science data in layer A. You could load these layers and specify their association like so:

imviz_helper = Imviz()

shape = (10, 10)
data_parent = np.ones(shape, dtype=float)
data_child = np.zeros(shape, dtype=int)

imviz_helper.load_data(data_parent, data_label='A')

# specify this data layer as the child of the  
# previous data layer with the `parent` arg:
imviz_helper.load_data(data_child, data_label='B', parent='A')

which gets represented as a dictionary:

>>> imviz_helper.app._data_associations
{
    "A": {
        "parent": None,
        "children": [
            "B"
        ]
    },
    "B": {
        "parent": "A",
        "children": []
    }
}

Four simple, private helper methods are added to Application to make this easy to use:

• _add_assoc_data_as_parent: create an entry in the association dict with this layer as parent (called by default on add_data)
• _set_assoc_data_as_child: specify that this layer is the child of another
• _get_assoc_data_parent/_get_assoc_data_children: find the parent/children of this layer

For now, I'm assuming:

• we will only create hierarchical associations when one Data layer is the DQ layer for a science layer already in the viewer
• we do not want the DQ/child layers in Plot Options

It follows that we need to filter out children Data entries from DatasetSelect and LayerSelect. This prevents the DQ layers from appearing in Plot Options or plugin data dropdown menus so they are not options in, e.g., Aperture Photometry.

We could choose to expose the child layers in the data menu and/or legend, or hide them in either or both places. For now, I updated the layer icon logic to provide a special icon for child layers. In the above example, the layer labeled "B" will appear in the legend in Imviz as "A1" (for now).

Other uses to investigate in the future

• Could/should we load all extensions other than the science data as children of the science data?
• Since Add "Random" colormap for visualizing image segmentation maps #2671, we provide super-basic support for image segmentation maps, which are generated with respect to one science data, and can be generated multiple times with different segmentation settings. We could load segmentation maps with their source data as "parent," so their visibilities are synced.
• Resampled (L3+) JWST products have extensions for context images (ext='CON'), which are represented as integer arrays with the same shape as the science data.

Example

Here's an example using glue dev, since merge of glue-viz/glue#2468. It loads two JWST Level 2 images from the FRESCO program and their data quality extensions.

imviz = Imviz()

data_dir = "../example_files/"

uris = [
    'mast:JWST/product/jw01895001004_07101_00001_nrca3_cal.fits',

    # # Bonus: try with a second science data+DQ pair:
    'mast:JWST/product/jw01895001004_04101_00001_nrca3_cal.fits'
]

for uri in uris:
    fn = uri.split('/')[-1]
    path = f'{data_dir}/{fn}'
    result = Observations.download_file(uri, local_path=path)
    with warnings.catch_warnings():
        warnings.simplefilter('ignore')
        imviz.load_data(path, ext='SCI')

        # specify parent/child relationship explicitly for this demo,
        # in the future this can be the parser default behavior when ext=DQ
        parent = imviz.app.data_collection[-1].label
        imviz.load_data(path, ext='DQ', parent=parent)

# choose colormap for DQ array:
cmap = plt.cm.prism
cmap.set_bad(color='k', alpha=0)

# set the colormap/stretch/opacity options, without using Plot Options.
# this will be moved to internal DQ-specific methods:
layer = imviz.default_viewer._obj.layers[-1]
layer.composite._allow_bad_alpha = True
layer.state.cmap = cmap
layer.state.v_min = 0
layer.state.v_min = 1000
layer.state.alpha = 0.8

imviz.show()

imviz-data-assoc.mov

Change log entry

• Is a change log needed? If yes, is it added to CHANGES.rst? If you want to avoid merge conflicts,
  list the proposed change log here for review and add to CHANGES.rst before merge. If no, maintainer
  should add a no-changelog-entry-needed label.

Checklist for package maintainer(s)

This checklist is meant to remind the package maintainer(s) who will review this pull request of some common things to look for. This list is not exhaustive.

• Are two approvals required? Branch protection rule does not check for the second approval. If a second approval is not necessary, please apply the trivial label.
• Do the proposed changes actually accomplish desired goals? Also manually run the affected example notebooks, if necessary.
• Do the proposed changes follow the STScI Style Guides?
• Are tests added/updated as required? If so, do they follow the STScI Style Guides?
• Are docs added/updated as required? If so, do they follow the STScI Style Guides?
• Did the CI pass? If not, are the failures related?
• Is a milestone set? Set this to bugfix milestone if this is a bug fix and needs to be released ASAP; otherwise, set this to the next major release milestone. Bugfix milestone also needs an accompanying backport label.
• After merge, any internal documentations need updating (e.g., JIRA, Innerspace)? 🐱

[codecov]

Codecov Report

Attention: Patch coverage is 82.25806% with 11 lines in your changes are missing coverage. Please review.

Project coverage is 88.67%. Comparing base (9515b7a) to head (5afa49f).
Report is 5 commits behind head on main.

❗ Current head 5afa49f differs from pull request most recent head 00785d7. Consider uploading reports for the commit 00785d7 to get more accurate results

Files	Patch %	Lines
jdaviz/configs/imviz/plugins/parsers.py	53.84%	6 Missing ⚠️
jdaviz/app.py	86.48%	5 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #2761      +/-   ##
==========================================
- Coverage   88.68%   88.67%   -0.01%     
==========================================
  Files         108      108              
  Lines       16214    16266      +52     
==========================================
+ Hits        14379    14424      +45     
- Misses       1835     1842       +7     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[bmorris3]

@kecnry Suggested that we prevent assigning children of children for now. This has been added in
5afa49f, and tested on the example above. When you load a DQ array and set it as a child of another DQ array, add_data now raises this error:

NotImplementedError: Data associations are currently supported 
between root layers (without parents) and their children, but 
the proposed parent "jw01895001004_04101_00001_nrca3_cal[DQ]" 
has parent "jw01895001004_04101_00001_nrca3_cal[DATA]".

[kecnry]

There are some future decisions about whether these layers remain in the data-menu/legend/mouseover or just appear as part of the parent layer to the user, but since this isn't being advertised to the user yet as an option to load_data, we can defer those decisions until the rest of the effort converges.

I do wonder whether we're building this with more flexibility than we'll ever need, but there are safeguards now to prevent nesting, etc, and at least if we want the flexibility later we won't have to redesign the whole infrastructure.

I just have a few minor comments on the implementation, otherwise am ok with this going in and iterating as needed for the follow-up efforts.

[kecnry]

this will update the state a bunch of times. Can we instead either build this logic into above or use a dictionary-comprehension to build all the new entries and then just apply to the state once?

[bmorris3]

Good idea. In 00785d7, I instead gather the child layer icon updates in a different dict, and update self.state.layer_icons once at the end.

[kecnry]

do we also need to validate that parent exists in the data-collection?

[bmorris3]

Sure thing, done in 55d2e68.

[bmorris3]

Adding a note for posterity: the above example calls

        imviz.load_data(path, ext='DQ', parent=parent)

so it might look like the new keyword argument parent is public. But the Imviz.load_data call signature accepts **kwargs, so I didn't have to add a parent kwarg to that public method. I did add parent to the call signature of Application.add_data, but we consider Application private.

[gibsongreen]

The demo was exciting, can't wait to see how DQ progresses forward!

[bmorris3]

Thanks all!