SubsetTools

class jdaviz.configs.default.plugins.subset_tools.subset_tools.SubsetTools(*args, **kwargs)

Bases: PluginTemplateMixin, LoadersMixin

See the Subset Tools for more details.

Only the following attributes and methods are available through the public plugin API:

• show()

• open_in_tray()

• close_in_tray()

• subset (SubsetSelect): Manages subset selection and creation

• combination_mode (SelectPluginComponent): Allows selection of combination modes for subsets

• recenter_dataset (DatasetSelect): Data used for recentering.

• recenter()

• get_center()

• set_center()

• import_region()

• get_regions()

• rename_selected()

• rename_subset()

• update_subset()

• simplify_subset()

Public constructor

Attributes Summary

can_freeze	A boolean (True, False) trait.
can_simplify	A boolean (True, False) trait.
combination_mode_items	An instance of a Python list.
combination_mode_selected	A trait which allows any value.
glue_state_types	An instance of a Python list.
has_subset_details	A boolean (True, False) trait.
icon_and	A trait for unicode strings.
icon_andnot	A trait for unicode strings.
icon_checktoradial	A trait for unicode strings.
icon_or	A trait for unicode strings.
icon_radialtocheck	A trait for unicode strings.
icon_replace	A trait for unicode strings.
icon_xor	A trait for unicode strings.
is_centerable	A boolean (True, False) trait.
mode_selected	A trait for unicode strings.
multiselect	A boolean (True, False) trait.
recenter_dataset_items	An instance of a Python list.
recenter_dataset_selected	A trait for unicode strings.
select	An instance of a Python list.
selected_subset_group
show_region_info	A boolean (True, False) trait.
subplugins_opened	A trait which allows any value.
subset_definitions	An instance of a Python list.
subset_items	An instance of a Python list.
subset_selected	A trait which allows any value.
subset_types	An instance of a Python list.
template_file
user_api

Methods Summary

get_center([subset_name])	Return the center of the Subset.
get_regions([region_type, ...])	Return spatial and/or spectral subsets of region_type (spatial or spectral, default both) as regions or SpectralRegions objects, respectively.
import_region(region[, edit_subset, ...])	Method for creating subsets from regions or region files.
recenter()	Recenter the selected subset on the centroid of the region of the current subset in the selected data layer.
rename_selected(new_label)	Method to rename the subset currently selected in the Subset Tools plugin.
rename_subset(old_label, new_label)	Method to rename an existing subset
set_center(new_cen[, subset_name, update])	Set the desired center for the selected Subset, if applicable.
simplify_subset()	Simplify the selected spectral subset by combining all subregions into a single spectral region.
update_subset([subset_label, subregion])	Method to update the attributes of an existing subset.
vue_freeze_subset(*args)
vue_recenter_subset(*args)
vue_rename_subset(msg)
vue_simplify_subset(*args)
vue_update_subset(*args)

Attributes Documentation

can_freeze

A boolean (True, False) trait.

can_simplify

A boolean (True, False) trait.

combination_mode_items

An instance of a Python list.

combination_mode_selected

A trait which allows any value.

glue_state_types

An instance of a Python list.

has_subset_details

A boolean (True, False) trait.

icon_and

A trait for unicode strings.

icon_andnot

A trait for unicode strings.

icon_checktoradial

A trait for unicode strings.

icon_or

A trait for unicode strings.

icon_radialtocheck

A trait for unicode strings.

icon_replace

A trait for unicode strings.

icon_xor

A trait for unicode strings.

is_centerable

A boolean (True, False) trait.

mode_selected

A trait for unicode strings.

multiselect

A boolean (True, False) trait.

recenter_dataset_items

An instance of a Python list.

recenter_dataset_selected

A trait for unicode strings.

select

An instance of a Python list.

selected_subset_group

show_region_info

A boolean (True, False) trait.

subplugins_opened

A trait which allows any value.

subset_definitions

An instance of a Python list.

subset_items

An instance of a Python list.

subset_selected

A trait which allows any value.

subset_types

An instance of a Python list.

template_file = ('/home/docs/checkouts/readthedocs.org/user_builds/jdaviz/envs/latest/lib/python3.11/site-packages/jdaviz/configs/default/plugins/subset_tools/subset_tools.py', 'subset_tools.vue')

user_api

Methods Documentation

get_center(subset_name=None)

Return the center of the Subset. This may or may not be the centroid obtain from data.

Parameters:

subset_namestr

The name of the subset that is being updated.

Returns:

cennumber, tuple of numbers, or None

The center of the Subset in x or (x, y), depending on the Subset type, if applicable. If Subset is not centerable, this returns None.

get_regions(region_type=None, list_of_subset_labels=None, use_display_units=False, return_sky_region=None, wrt_data=None)

Return spatial and/or spectral subsets of region_type (spatial or spectral, default both) as regions or SpectralRegions objects, respectively.

Parameters:

region_typestr or None, optional

Specifies the type of subsets to retrieve. Options are spatial to retrieve only spatial subsets, spectral to retrieve only spectral subsets or None (default) to retrieve both spatial and spectral subsets, when relevant to the current configuration.

list_of_subset_labelslist of str or None, optional

If specified, only subsets matching these labels will be included. If not specified, all subsets matching the region_type will be returned.

use_display_unitsbool, optional

(For spectral subsets) If False (default), subsets are returned in the native data unit. If True, subsets are returned in the spectral axis display unit set in the Unit Conversion plugin.

wrt_datastr or None

Only applicable for spatial subsets, an error will be raised when ‘’region_type’’ equals ‘spectral’. Otherwise, spectral subsets will not be impacted when called. Controls return type of PixelRegion / SkyRegion. To return a spatial subset in opposition with the current link type (e.g return PixelRegion when WCS linked, SkyRegion when pixel linked), wrt_data can be set to the data label of the dataset whose WCS should be used for this transformation. The default behavior (None) will return Pixel/Sky region based on app link type (Sky for Cubeviz), using the WCS of the subset’s parent dataset (i.e the data layer the subset was created on).

Returns:

regionsdict

A dictionary mapping subset labels to their respective regions objects (for spatial regions) or SpectralRegions objects (for spectral regions).

Examples

>>> from jdaviz import Imviz, Cubeviz
>>> from regions import PixCoord, CirclePixelRegion, CircleSkyRegion
>>> from astropy.nddata import NDData
>>> import numpy as np
>>> import astropy.units as u
>>> imviz = Imviz()
>>> imviz.link_data(align_by='pixels')
>>> data = NDData(np.ones((128, 128)) * u.nJy, wcs=getfixture('image_2d_wcs'))
>>> imviz.load_data(data)
>>> plg = imviz.plugins['Subset Tools']
>>> plg.import_region(CirclePixelRegion(center=PixCoord(x=1163.618408203125, y=1433.47998046875), radius=141.28575134277344))  # noqa E501
>>> type(plg.get_regions()['Subset 1'])
<class 'regions.shapes.circle.CirclePixelRegion'>
>>> type(plg.get_regions(wrt_data='NDData[DATA]')['Subset 1'])
<class 'regions.shapes.circle.CircleSkyRegion'>
>>> imviz.app.delete_subsets()
>>> imviz.link_data(align_by='wcs')
>>> plg.import_region(CirclePixelRegion(center=PixCoord(x=1163.618408203125, y=1433.47998046875), radius=141.28575134277344))  # noqa E501
>>> type(plg.get_regions()['Subset 2'])
<class 'regions.shapes.circle.CircleSkyRegion'>
>>> type(plg.get_regions(wrt_data='NDData[DATA]')['Subset 2'])
<class 'regions.shapes.circle.CirclePixelRegion'>

>>> cubeviz = Cubeviz()
>>> cubeviz.load_data(getfixture('spectrum1d_cube'))
>>> plg = cubeviz.plugins['Subset Tools']
>>> plg.import_region(CirclePixelRegion(center=PixCoord(x=24.27156066879736, y=22.183517455582475), radius=4.7523674964904785))  # noqa E501
>>> type(plg.get_regions()['Subset 1'])
<class 'regions.shapes.circle.CircleSkyRegion'>
>>> type(plg.get_regions(wrt_data='Unknown spectrum object[FLUX]')['Subset 1'])
<class 'regions.shapes.circle.CirclePixelRegion'>

import_region(region, edit_subset=None, combination_mode=None, max_num_regions=20, refdata_label=None, return_bad_regions=False, region_format=None)

Method for creating subsets from regions or region files.

Parameters:

regionregion, list of region objects, or str

A region object can be one of the following:

• Astropy regions object

• photutils apertures (limited support until photutils fully supports regions)

• specutils SpectralRegion object

A string which represents a regions or SpectralRegion file. If given as a list, it can only contain spectral or non-spectral regions, not both.

edit_subsetstr or None

Subset to have region applied to it using combination_mode

combination_modelist, str, or None

The way that regions are created or combined. If a list, then it must be the same length as regions. If None, then a new subset will be created. Options are [‘new’, ‘replace’, ‘or’, ‘and’, ‘xor’, ‘andnot’]

max_num_regionsint or None

Maximum number of regions to load, starting from top of the list. Default is 20. If you want to load everything, set it to None. Loading a large number of regions is not recommended due to performance impact.

refdata_labelstr or None

This is only applicable to non-spectral regions. Label of data to use for sky-to-pixel conversion for a region, or mask creation. Data must already be loaded into Jdaviz. If None, defaults to the reference data in the default viewer. Choice of this data is particularly important when sky region is involved.

return_bad_regionsbool

If True, return the regions that failed to load (see bad_regions); This is useful for debugging. If False, do not return anything (None).

region_formatstr or None

Passed to Regions.read(format=region_format). Only applicable if region is a string pointing to a valid file that Regions can read.

Returns:

bad_regionslist of (obj, str) or None

If requested (see return_bad_regions option), return a list of (region, reason) tuples for region objects that failed to load. If all the regions loaded successfully, this list will be empty. If not requested, return None.

recenter()

Recenter the selected subset on the centroid of the region of the current subset in the selected data layer.

rename_selected(new_label)

Method to rename the subset currently selected in the Subset Tools plugin.

Parameters:

new_labelstr

The new label to apply to the selected subset.

rename_subset(old_label, new_label)

Method to rename an existing subset

Parameters:

old_labelstr

The current label of the subset to be renamed.

new_labelstr

The new label to apply to the selected subset.

set_center(new_cen, subset_name=None, update=False)

Set the desired center for the selected Subset, if applicable. If Subset is not centerable, nothing is done.

Parameters:

new_cennumber or tuple of numbers

The new center defined either as x or (x, y), depending on the Subset type.

subset_namestr

The name of the subset that is being updated.

updatebool

If True, the Subset is also moved to the new center. Otherwise, only the relevant editable fields are updated but the Subset is not moved.

Raises:

NotImplementedError

Subset type is not supported.

simplify_subset()

Simplify the selected spectral subset by combining all subregions into a single spectral region. This is only available for spectral subsets with more than one subregion.

update_subset(subset_label=None, subregion=None, **kwargs)

Method to update the attributes of an existing subset. The attributes of a subset and their current values can be retrieved with the ‘get_subset_definition` method.

Parameters:

subset_labelstr

The name of the subset to update. If this is not the currently selected subset in the UI, it will be selected.

subregionint, optional

The integer subregion index (in the subset_definitions dictionary) for which to modify the specified attributes.

The attributes to update and their new values are passed as keyword arguments to this

function, for example:

plg = imviz.plugins[‘Subset Tools’] plg.update_subset(‘Subset 1’, xmax = 9.522, xmin = 9.452)

If no values to update are specified, this function will return the current definition of

the specified subset. The “att” keys in the returned dictionaries are the attributes that

can be updated with this method.

vue_freeze_subset(*args)

vue_recenter_subset(*args)

vue_rename_subset(msg)

vue_simplify_subset(*args)

vue_update_subset(*args)