ViSL3D Visual

Created on Fri Mar 22 16:05:52 2024

@author: ixakalabadie

class visl3d.visual.Cube(l_cubes, coords, l_isolevels, cmaps, units, mags, delta, rms=None, name='', resol=1, galaxies=None, image2d=(None, None), lines=None, interface='full')[source]

Bases: object

Class to store relevant data to create the visualisation.

Parameters:

  • l_cubes (list) – List of 3D arrays with the data. Even if it is only one cube it must be a list. For overlay the arrays must have the same shape.

  • coords (array) – Array with the coordinates of the cube. It must be a sorted 3x2 array with the minimum and maximum values of the spatial and spectral axes.

  • l_isolevels (list) – List of arrays with the isosurface levels for each cube.

  • cmaps (list) – Matplotlib colormap to use for each cube. Must have the same length as l_isolevels.

  • units (len 4 array) – Array of strings with the units of the data cube. The first element is the unit of the data.

  • mags (len 4 array) – Array of strings with the magnitudes of the data cube. E.g. [‘I’, ‘RA’, ‘DEC’, ‘V’].

  • rms (float, optional) – RMS of the data cube.

  • name (str, optional) – Name of the object. Default is ‘’.

  • delta (len 3 array, optional) – Array with the pixel size in each axis. Default is None.

  • resol (float, optional) – Step size for the marching cubes algorithm. Higher value means lower resolution. Default is 1.

  • galaxies (dict, optional) – Dictionary with galaxies to include in the model. Keys are names of galaxies and it must have two more dictionaries inside with the keys ‘coords’ and ‘col’. ‘coords’ must have the coordinates of the galaxy (transformed to units of the cube between -1000 and 1000) and ‘col’ the color of each galaxy as a string. E.g. {‘NGC 1234’: {‘coords’: [-560, 790, 134], ‘col’: ‘255 0 0’}}. ‘coord’ is calculated with ‘[RA - mean(cubeRA)]/abs(deltaRA)*2000/nPixRA’. The whole dictionary can be obtained with misc.get_galaxies().

  • image2d (tuple, optional) – Tuple with the name of the survey and the data to plot a 2D image (str, (hex, shape)). The data is the image in hexadecimal format and the shape of the image. It can be calculated with the function misc.get_imcol. If (‘blank’, (None,None)) a blank plane will be created. If (‘’, None) no image will be created.

  • lines (dict, optional) – Dictionary with the names of spectral lines as keys and a tuple with the centre and the full width of the line as value. The centre must be an astropy quantity and the width can be a quantity or an integer representing the number of pixels. E.g. {‘NII’: (6583*u.Angstrom, 50 [pixels])), ‘Halpha’: (6562*u.Angstrom, 10*u.Angstrom)}.

  • interface (str, optional) – Format of the web interface. ‘full’ gives a fully interactive web page and ‘minimal’ just the 3D model. Default is ‘full’.

class visl3d.visual.X3DomWidget(**kwargs: Any)[source]

Bases: AnyWidget

Class to display ViSL3D visualisation in a jupyter notebook.

Attributes:
comm
cross_validation_lock

A contextmanager for running a block with our cross validation lock set to True.

html
keys

The traits which are synced.

layout
log
model_id

Gets the model id of this widget.

tabbable

Is widget tabbable?

tooltip

A tooltip caption.

Methods

add_class(className)

Adds a class to the top level element of the widget.

add_traits(**traits)

Dynamically add trait attributes to the Widget.

blur()

Blur the widget.

class_own_trait_events(name)

Get a dict of all event handlers defined on this class, not a parent.

class_own_traits(**metadata)

Get a dict of all the traitlets defined on this class, not a parent.

class_trait_names(**metadata)

Get a list of all the names of this class' traits.

class_traits(**metadata)

Get a dict of all the traits of this class.

close()

Close method.

focus()

Focus on the widget.

get_manager_state([drop_defaults, widgets])

Returns the full state for a widget manager for embedding

get_state([key, drop_defaults])

Gets the widget state, or a piece of it.

handle_comm_opened(comm, msg)

Static method, called when a widget is constructed.

handle_control_comm_opened(comm, msg)

Class method, called when the comm-open message on the "jupyter.widget.control" comm channel is received

has_trait(name)

Returns True if the object has a trait with the specified name.

hold_sync()

Hold syncing any state until the outermost context manager exits

hold_trait_notifications()

Context manager for bundling trait change notifications and cross validation.

notify_change(change)

Called when a property has changed.

observe(handler[, names, type])

Setup a handler to be called when a trait changes.

on_msg(callback[, remove])

(Un)Register a custom msg receive callback.

on_trait_change([handler, name, remove])

DEPRECATED: Setup a handler to be called when a trait changes.

on_widget_constructed(callback)

Registers a callback to be called when a widget is constructed.

open()

Open a comm to the frontend if one isn't already open.

remove_class(className)

Removes a class from the top level element of the widget.

send(content[, buffers])

Sends a custom msg to the widget model in the front-end.

send_state([key])

Sends the widget state, or a piece of it, to the front-end, if it exists.

set_state(sync_data)

Called when a state is received from the front-end.

set_trait(name, value)

Forcibly sets trait attribute, including read-only attributes.

setup_instance(**kwargs)

This is called before self.__init__ is called.

trait_defaults(*names, **metadata)

Return a trait's default value or a dictionary of them

trait_events([name])

Get a dict of all the event handlers of this class.

trait_has_value(name)

Returns True if the specified trait has a value.

trait_metadata(traitname, key[, default])

Get metadata values for trait by key.

trait_names(**metadata)

Get a list of all the names of this class' traits.

trait_values(**metadata)

A dict of trait names and their values.

traits(**metadata)

Get a dict of all the traits of this class.

unobserve(handler[, names, type])

Remove a trait change handler.

unobserve_all([name])

Remove trait change handlers of any type for the specified name.

close_all

get_view_spec
html

A trait for unicode strings.

visl3d.visual.createHTML(cube, filename, description=None, pagetitle=None)[source]

Create HTML file from a Cube object.

Parameters:

  • cube (Cube) – Object of the Cube class.

  • filename (str) – Name of the HTML file including the extension (.html).

  • description (str, optional) – A description for the web page.

  • pagetitle (str, optional) – The title of the web page.

visl3d.visual.createVis(cube, filename=None, description=None, pagetitle=None, shifts=None, notebook=False)[source]

Create an HTML file with a 3D visualisation of a datacube (without an X3D file).

Parameters:

  • cube (Cube) – Object of the Cube class.

  • filename (str, optional) – Name of the HTML file including the extension (.html). Optional is notebook=True.

  • description (str, optional) – A description for the web page.

  • pagetitle (str, optional) – The title of the web page.

  • notebook (bool) – Display the visualisation in the jupyter notebook. If True, the file will not be saved. Default is False.

visl3d.visual.createX3D(cube, filename, shifts=None)[source]

Create X3D file from a Cube object.

Parameters:

  • cube (Cube) – Object of the Cube class.

  • filename (str) – Name of the X3D file including the extension (.x3d).

  • shift (list, optional) – A list with a arrays of 3D vectors giving the shift in RA, DEC and spectral axis in the same units given to the cube. Similar to l_cube or l_isolevels.

visl3d.visual.displayVis(filename)[source]

Disply a ViSL3D visualisation in a jupyter notebook.

Parameters:

filename (str) – Name of the file to visualise, including the ‘.html’ extension.

visl3d.visual.prep_mult(cube, spectral_lims, header=None, spatial_lims=None, l_isolevels=None, unit=None, colormap=None, image2d=None, im2dcolor='Greys', lines=None)[source]

Prepare the Cube class for a cube with multiple spectral lines. Makes a subcube for each spectral line.

Parameters:

  • cube (str or np.ndarray) – Path to the FITS file or the data cube. If data it must be in the form [spectral axis, DEC, RA].

  • spectral_lims (list) – List of lists with the limits (minimum and maximum) of the spectral axis. Can be quatities or pixels. E.g. [[vmin1, vmax1], [vmin2, vmax2]].

  • header (astropy.io.fits.header.Header, optional) – Header of the FITS file.

  • spatial_lims (list, optional) – List of lists with the limits (minimum and maximum) of the spatial axes. E.g. [[[ramin1, ramax1], [decmin1, decmax1]], [[ramin2, ramax2], [decmin2, decmax2]]]. Each list will correspond to the subcubes defined in spectral_lims in the same order. If only one set of limits is provided it will be used for all the subcubes. If None the whole cube is used. Default is None.

  • l_isolevels (list, optional) – List of arrays with the isosurface levels for each cube. If None it is calculated automatically.

  • unit (str, optional) – Unit to convert the data cube. If None the original unit is used. If ‘rms’ data is divided by the RMS of the cube. If ‘percent’ data is divided by the maximum value.

  • colormap (str, optional) – Name of the colormaps to use. Must be the same length as the number of spectral lines to model. If None and the number of lines is <7 they are be chosen automatically. Default is None.

  • image2d (str or 2D or 3D array, optional) – Name of the survey to query a 2D image. See survey options in https://astroquery.readthedocs.io/en/latest/skyview/skyview.html. If ‘blank’ a blank plane is used. If None no image is created. If 2D or 3D array, the mage data in RGB format between 0 and 1 (3D). The RGB column must be last. If 2D, the image will be converted automatically. The image will cover the full FoV of the created cube model (after applying limits).

  • im2dcolor (str, optional) – Name of the colormap to use for the 2D image. Default is ‘Greys’.

  • lines (array-like, optional) – List with the names of each subcube to use as labels in the web page. Must have same length as spectral_lims. Default is None.

Returns:

An object of the Cube class for a model with multiple spectral lines.

Return type:

Cube

visl3d.visual.prep_one(cube, header=None, lims=None, unit=None, isolevels=None, colormap='CMRmap_r', image2d=None, im2dcolor='Greys', galaxies=None)[source]

Prepare the Cube class for a cube with a single spectral line.

Parameters:

  • cube (str or np.ndarray) – Path to the FITS file or to the data cube.

  • header (astropy.io.fits.header.Header, optional) – Header of the FITS file.

  • lims (array-like, optional) – 3x2 array with the minimum and maximum limits of the cube. If None the whole cube is used. It can contain limits in astropy quantities or in pixels. E.g. [[ramin, ramax], [decmin, decmax], [vmin, vmax]]. Default is None.

  • unit (str, optional) – Unit to convert the data cube. If None the original unit is used. If ‘rms’ data is divided by the RMS of the cube. If ‘percent’ data is divided by the maximum value.

  • isolevels (array-like, optional) – Array with the isosurface levels in the given units. If None it is calculated automatically.

  • colormap (str, optional) – Name of the colormap to use. Default is ‘CMRmap_r’.

  • image2d (str or tuple or 2D or 3D array, optional) –

    • If None, no image is created.

    • If ‘blank’, a blank plane is used.

    • Name of the survey (str) to query a 2D image. See survey options in https://astroquery.readthedocs.io/en/latest/skyview/skyview.html.

    • Tuple with the name of the survey (str) and the number of pixels (int) to set the resolution of the image (default is 1000).

    • Tuple can be given with a name for the image (str) and the image data (2D or 3D array).

      If 3D array, the image data in RGB format between 0 and 1 (3D). The RGB column must be last. If 2D, the image will be converted automatically.

    The image will cover the full FoV of the created cube model (after applying limits).

  • im2dcolor (str, optional) – Name of the colormap to use for the 2D image. Default is ‘Greys’.

  • galaxies (list or str, optional) – List with the names of galaxies to include in the model. If ‘query’ a NED query is made within the limits of the cube. If None no galaxies are included.

Returns:

An object of the Cube class for a single spectral line model.

Return type:

Cube

visl3d.visual.prep_overlay(cube, header=None, spectral_lims=None, lines=None, spatial_lims=None, l_isolevels=None, unit=None, colormap=None, image2d=None, im2dcolor='Greys')[source]

Prepare the Cube class for an overlay of spectral lines. Makes a subcube for each spectral line and overlays the centre of each line in the same point.

Parameters:

  • cube (str or np.ndarray) – Path to the FITS file or the data cube.

  • header (astropy.io.fits.header.Header, optional) – Header of the FITS file.

  • spectral_lims (list, optional) – List of lists with the limits (minimum and maximum) of the spectral axis. E.g. [[vmin1, vmax1], [vmin2, vmax2]].

  • lines (dict, optional) – Dictionary with the names of spectral lines as keys and a tuple with the centre and the full width of the line as value. The centre must be an astropy quantity and the width can be a quantity or an integer representing the number of the pixel. E.g. {‘NII’: (6583*u.Angstrom, 50 [pixels])), ‘Halpha’: (6562*u.Angstrom, 10*u.Angstrom)}. If None the centres will be the centres of the subcubes.

  • spatial_lims (list, optional) – List of lists with the limits (minimum and maximum) of the spatial axes. E.g. [[[ramin1, ramax1], [decmin1, decmax1]], [[ramin2, ramax2], [decmin2, decmax2]]]. Each list will correspond to the subcubes defined in spectral_lims in the same order. If only one set of limits is provided it will be used for all the subcubes. If None the whole cube is used. Default is None.

  • l_isolevels (list, optional) – List of arrays with the isosurface levels for each cube. If None it is calculated automatically.

  • unit (str, optional) – Unit to convert the data cube. If None the original unit is used. If ‘rms’ data is divided by the RMS of the cube. If ‘percent’ data is divided by the maximum value.

  • colormap (str, optional) – Name of the colormaps to use. Must be the same length as the number of spectral lines to model. If None and the number of lines is <7 they are be chosen automatically. Default is None.

  • image2d (str or 2D or 3D array, optional) – Name of the survey to query a 2D image. See survey options in https://astroquery.readthedocs.io/en/latest/skyview/skyview.html. If ‘blank’ a blank plane is used. If None no image is created. If 2D or 3D array, the mage data in RGB format between 0 and 1 (3D). The RGB column must be last. If 2D, the image will be converted automatically. The image will cover the full FoV of the created cube model (after applying limits).

  • im2dcolor (str, optional) – Name of the colormap to use for the 2D image. Default is ‘Greys’.

Returns:

An object of the Cube class for an overlay of spectral lines.

Return type:

Cube