ipyaladin.widget

Aladin Lite widget for Jupyter Notebook.

This module provides a Python wrapper around the Aladin Lite JavaScript library. It allows to display astronomical images and catalogs in an interactive way.

Classes

Aladin

Aladin Lite widget.

Functions

widget_should_be_loaded(→ collections.abc.Callable)

Check if the widget is ready to execute a function.

Module Contents

ipyaladin.widget.widget_should_be_loaded(function: collections.abc.Callable) → collections.abc.Callable

Check if the widget is ready to execute a function.

Store the call for a later execution.

Parameters:

functionCallable

The function to decorate.

Returns:

Callable

The decorated function.

class ipyaladin.widget.Aladin(**init_options: object)

Aladin Lite widget.

This widget is a Python wrapper around the Aladin Lite JavaScript library. It allows to display astronomical images and catalogs in an interactive way.

property selected_objects: List[astropy.table.table.Table]

The list of catalogs selected by the user.

Returns:

list[Table]

A list of astropy.table.Table objects representing the selected catalogs.

property height: int

The height of the widget.

Returns:

int

The height of the widget in pixels. Setting the height to -1 will expand the widget at 100% height of its container. This is generally a bad idea in a notebook but can be usefull for dashbord applications. The default height is 400 pixels.

property rotation: float

The center rotation of the widget.

This is the view center to north pole angle in degrees. This is equivalent to getting the 3rd Euler angle. Positive angles rotates the view in the counter clockwise order (or towards the east).

It can be set with either a float number in degrees or an astropy.coordinates.Angle object.

Returns:

astropy.coordinates.Angle

An astropy.coordinates.Angle object representing the center rotation of the widget in degrees. The default rotation is 0 degrees.

property wcs: astropy.wcs.WCS

The world coordinate system corresponding to the current view of ipyaladin.

Returns:

~astropy.wcs.WCS

An astropy WCS object representing the world coordinate system.

property fov_xy: Tuple[astropy.coordinates.Angle, astropy.coordinates.Angle]

The field of view of the Aladin Lite along the two axes.

Returns:

tuple[Angle, Angle]

A tuple of astropy.units.Angle objects representing the field of view.

property fov: astropy.coordinates.Angle

The field of view of the Aladin Lite widget along the horizontal axis.

It can be set with either a float number in degrees or an astropy.coordinates.Angle object.

Returns:

astropy.coordinates.Angle

An astropy.coordinates.Angle object representing the field of view.

See also

fov_xy

property target: astropy.coordinates.SkyCoord | Tuple[float, float]

The target of the Aladin Lite widget.

The target can be provided as coordinates (either ~astropy.coordinates.SkyCoord or (~astropy.coordinates.Longitude, ~astropy.coordinates.Latitude)) or as a name (as a string).

The conversion from a name to coordinates does call different online services depending on the base layer of the widget: - for the sky: it uses CDS’s Sesame name resolver. This looks first in SIMBAD, then in VizieR, and then in NED for the object’s coordinates. - for Earth: it uses Nominatim, OpenStreetMap’s search bar - for other solar system bodies: it calls the Gazetteer of Planetary Nomenclature

Returns:

~astropy.coordinates.SkyCoord or Tuple[Longitude, Latitude]

If ipyaladin has a sky survey, returns a ~astropy.coordinates.SkyCoord object. Otherwise, if ipyaladin is currently on a planetary body, returns a tuple with the Longitude and the Latitude of the current position of the widget.

add_markers(markers: ipyaladin.elements.marker.Marker | List[ipyaladin.elements.marker.Marker], **catalog_options: any) → None

Add markers to the Aladin Lite widget.

Markers have a popup window that appear when they’re clicked on.

Parameters:

markersMarker or list[Marker]

The marker(s) to add to the widget. It can be given as a single Marker object or as a list of Marker objects.

catalog_optionsany

The options for the catalog. See the Aladin Lite catalog options

See also

add_table

also adds points, but without popup window.

save_view_as_image(path: str | pathlib.Path, image_format: str = 'png', with_logo: bool = True) → None

Save the current view of the widget as an image file.

This should be used as quick previews, or illustrations. For scientific-quality pixels, use ‘get_view_as_fits’.

Parameters:

pathUnion[str, Path]

The path where the image will be saved.

image_formatstr

The format of the image. Can be ‘png’, ‘jpeg’ or ‘webp’.

with_logobool

Whether to include the Aladin Lite logo in the image.

See also

get_view_as_fits

conserves the photometry

get_view_as_fits() → astropy.io.fits.HDUList

Get the base layer of the widget as an astropy HDUList object.

The output FITS image will have the same shape as the current view of the widget. This uses astroquery.hips2fits internally. This method currently only exports the bottom/base layer.

Returns:

~astropy.io.fits.HDUList

The FITS object containing the image.

See also

save_view_as_image

get_JPEG_thumbnail() → None

Create a new tab with the current Aladin view.

This method will only work if you are running a notebook in a browser (for example, it won’t do anything in VSCode).

See also

save_view_as_image

will save the image on disk instead

add_catalog_from_URL(votable_URL: str, votable_options: dict | None = None) → None

Load a VOTable table from an url and load its data into the widget.

Parameters:

votable_URLstr

votable_optionsdict

add_fits(fits: str | pathlib.Path | astropy.io.fits.HDUList, **image_options: any) → None

Load a FITS image into the widget.

Parameters:

fitsUnion[str, Path, HDUList]

The FITS image to load in the widget. It can be given as a path (either a string or a pathlib.Path object), or as an astropy.io.fits.HDUList.

image_optionsany

The options for the image. See the Aladin Lite image options

add_moc(moc: any, **moc_options: any) → None

Add a MOC to the Aladin-Lite widget.

Parameters:

moc~mocpy.MOC or str or dict

The MOC can be provided as a mocpy.MOC object, as a string containing an URL where the MOC can be retrieved, or as a dictionary where the keys are the HEALPix orders and the values are the pixel indices (ex: {“1”:[1,2,4], “2”:[12,13,14,21,23,25]}).

moc_options

Keyword arguments. The possible values are documented in Aladin Lite’s MOC options

add_moc_from_URL(moc_URL: str, moc_options: dict | None = None) → None

Load a MOC from a URL and display it in Aladin Lite widget.

Parameters:

moc_URL: str

An URL to retrieve the MOC from

moc_options

Keyword arguments. The possible values are documented in Aladin Lite’s MOC options

add_moc_from_dict(moc_dict: dict, moc_options: dict | None = None) → None

Load a MOC from a dict object and display it in Aladin Lite widget.

Parameters:

moc_dict: dict

It contains the MOC cells. Key are the HEALPix orders, values are the pixel indexes, eg: {“1”:[1,2,4], “2”:[12,13,14,21,23,25]}

moc_options

Keyword arguments. The possible values are documented in Aladin Lite’s MOC options

add_table(table: astropy.table.table.QTable | astropy.table.table.Table, *, shape: str | ipyaladin.elements.error_shape.CircleError | ipyaladin.elements.error_shape.EllipseError = 'cross', **table_options: any) → None

Load a table into the widget.

The extra parameters allow to draw either circles which radii correspond to the error estimation, or ellipses which major axis, minor axis, and angles correspond to the coordinates error.

Parameters:

table~astropy.table.table.QTable or ~astropy.table.table.Table

table that must contain coordinates information

shapestr | ~ipyaladin.CircleError | ~ipyaladin.EllipseError

The shape to draw for each source. It accepts the strings “square”, “circle”, “plus”, “cross”, “rhomb”, and “triangle” as well as the two specific classes ipyaladin.CircleError and ipyaladin.EllipseError that adapt the size of the drawn shapes (circles or ellipses) to error columns. See example notebook 04_Importing_Tables.

**table_options

Keyword arguments. They mostly give control on the visual aspects of the table. If the coordinates cannot be detected automatically, then you can give the appropriate column names in the ‘ra_field’ and ‘dec_field’ arguments. The possible values are documented in Aladin Lite’s table options

See also

add_markers

adds markers with a popup window when clicked

add_graphic_overlay_from_region(region: SupportedRegion, **graphic_options: any) → None

Add an overlay graphic layer to the Aladin Lite widget.

Parameters:

region: `~regions.CircleSkyRegion`, `~regions.EllipseSkyRegion`,

`~regions.LineSkyRegion`,`~regions.PolygonSkyRegion`,

`~regions.RectangleSkyRegion`, `~regions.Regions`, or a list of these.

The region(s) to add in Aladin Lite. It can be given as a supported region or a list of regions from the regions package.

graphic_options: keyword arguments

The options for the graphic overlay. Use Region visual for region options. See Aladin Lite’s graphic overlay options

See also

add_graphic_overlay_from_stcs

for shapes described as STC-S strings.

Notes

The possible ~regions.RegionVisual options correspond to the Aladin Lite / ipyaladin parameters:

Correspondence between options

RegionVisual	AladinLite	ipyaladin
edgecolor	color	color
facecolor	fillColor	fill_color
color	color and fillColor	color and fill_color
alpha	opacity	opacity
linewidth	lineWidth	line_width

add_overlay_from_stcs(stc_string: collections.abc.Iterable[str] | str, **overlay_options: any) → None

Add an overlay layer defined by an STC-S string.

Parameters:

stc_stringstr, Iterable[str]

The STC-S string or an iterable of STC-S strings.

overlay_optionskeyword arguments

The overlay options for all the STC-S strings See Aladin Lite’s graphic overlay options

add_graphic_overlay_from_stcs(stc_string: collections.abc.Iterable[str] | str, **overlay_options: any) → None

Add an overlay layer defined by an STC-S string.

Parameters:

stc_stringstr, Iterable[str]

The STC-S string or an iterable of STC-S strings.

overlay_optionskeyword arguments

The overlay options for all the STC-S strings. See Aladin Lite’s graphic overlay options

See also

add_graphic_overlay_from_region

if the shape is in an astropy ~regions

object.

set_color_map(color_map_name: str) → None

Change the color map of the Aladin Lite widget.

Parameters:

color_map_name: str

The name of the color map to use.

selection(selection_type: str = 'rectangle') → None

Trigger the selection tool.

Parameters:

selection_type: str

The type of selection tool to trigger. Can be ‘circle’ or ‘rectangle’. Default is ‘rect’.

rectangular_selection() → None

Trigger the rectangular selection tool.

Notes

This method is deprecated, use selection instead

set_listener(listener_type: str, callback: collections.abc.Callable) → None

Set a listener for an event to the widget.

Parameters:

listener_typestr

Can either be ‘object_hovered’, ‘object_clicked’, ‘click’ or ‘select’

callbackCallable

A python function to be called when the event corresponding to the listener_type is detected

add_listener(listener_type: str, callback: collections.abc.Callable) → None

Add a listener to the widget. Use set_listener instead.

Parameters:

listener_type: str

Can either be ‘object_hovered’, ‘object_clicked’, ‘click’ or ‘select’

callback: Callable

A python function to be called when the event corresponding to the listener_type is detected

Notes

This method is deprecated, use set_listener instead