render_ipyaladin

render_ipyaladin class

Reactively render an ipyaladin sky viewer (Aladin Lite).

Usage Source

render_ipyaladin(
    _fn: Optional[ValueFn[ValueT]] = None,
    *,
    width: Optional[str] = None,
    height: Optional[str] = None,
    fill: Optional[bool] = None,
    fillable: Optional[bool] = None,
    rate_policy: Optional[RatePolicy] = None,
    rate_delay: Optional[float] = None,
)

@render_ipyaladin is a decorator that creates a render function – a function that returns the viewer to display and re-runs when the reactive values it reads change:

from ipyaladin import Aladin

from shinywidgets import render_ipyaladin


@render_ipyaladin
def sky():
    return Aladin(target="M31", fov=5)

The render function should return an ipyaladin.Aladin widget (requires pip install 'shinywidgets[ipyaladin]'). In a filling layout, the viewer fills its container unless the Aladin has an explicit height (or its layout has an explicit height).

Note

Accessing the rendered widget: the render function gains two read-only attributes: .value, the value it most recently returned, and .widget, the rendered Aladin instance. Viewer state can also be read reactively with reactive_read().

Responding to user interaction: the output has methods that read what the user does in the viewer, much like input.my_slider() reads an input. Call them in a reactive function (a @render.* function, @reactive.calc, or @reactive.effect), which then re-runs whenever the interaction changes:

• clicked_object(): the catalog source most recently clicked.
• selected(): the catalog sources inside the current box selection (needs selection mode armed, e.g. .widget.selection("rectangle")).
• target(): the sky position at the center of the view.
• fov(): the view’s field of view.

clicked_object() returns None until a source is clicked. All four are seeded from the viewer’s state at render (so an interaction made before the accessor’s first read is reflected in that read) and follow every click, pan, zoom, or selection – and Python-side .widget.target = ... assignments too. A re-render builds a new viewer, so clicked_object() starts over at None and the others follow the new viewer’s state.

Mutating the widget: use .widget to update the rendered viewer in place (e.g., .widget.target = "M31" or .widget.fov = 5); trait changes on the widget are synced to the browser. ipyaladin queues method calls (e.g., .widget.add_table()) until the viewer has loaded in the browser, but property assignments (e.g., .widget.fov = 5) are not queued, so gate effects that set them on sky.read("_is_loaded"). Don’t gate on the _ready trait instead: ipyaladin does not reliably set it.

Interacting with catalogs: clicked_object() and selected() (above) cover the common cases; the trait-level equivalents (clicked_object and _selected_objects) also work with sky.read(). Prefer any of these over .widget.set_listener(): in ipyaladin 0.8.x listener callbacks are shared across all Aladin instances, so they are not session-safe in a multi-user Shiny app. When setting .widget.target in place, use a "ra dec" string or an astropy SkyCoord (a plain float tuple raises in ipyaladin’s setter).

Network access: the viewer loads its JavaScript from a CDN and its sky imagery (HiPS tiles) from CDS servers at render time, so it requires an internet connection. A constructor target= given as an object name (Aladin(target="M31")) resolves the name to coordinates with a blocking call to CDS’s Sesame service while the render function runs; an unresolvable name (or an unreachable service) raises (NameResolveError, or a misleading WidgetNotReadyError in ipyaladin 0.8.x, whose _ready trait is never set) and fails the render outright. Prefer coordinate strings ("83.63 22.01", parsed locally) or a SkyCoord for anything set programmatically.

Parameters

width : Optional[str] = None

A CSS length unit (e.g., "400px" or "100%") for the output’s width.

height : Optional[str] = None

A CSS length unit for the output’s height. When None (the default), the output is designed to fill the height of its parent container (see fill and fillable).

fill : Optional[bool] = None

Whether the output should grow or shrink to fit its parent container. When None (the default), this is True if height is not specified.

fillable : Optional[bool] = None

Whether the output container should fill available space (scrolling its contents on overflow). When None (the default), this is True if height is not specified.

rate_policy : Optional[RatePolicy] = None

How to rate-limit reactive_read() on the widget: "debounce" or "throttle". None (the default) debounces reactive_read() only if rate_delay is given; no accessor on this renderer declares a default.

rate_delay : Optional[float] = None

The rate-limit window in seconds (default 0.25). 0 disables rate limiting.

Each :

which :

See also

output_widget(): in Shiny Core, the UI needs this to hold the output (Shiny Express displays it where the render function is defined).

Methods

clicked_object()	The catalog source the user most recently clicked, as a dict with ra, dec, and data (the source’s catalog row).
fov()	The view’s field of view, as an astropy Angle.
selected()	The catalog sources inside the current selection, as a list of astropy Tables (one per catalog).
target()	The sky position at the center of the view, as an astropy SkyCoord (a (Longitude, Latitude) tuple for planetary surveys).

clicked_object()

render_ipyaladin.clicked_object()

The catalog source the user most recently clicked, as a dict with ra, dec, and data (the source’s catalog row).

Returns None until the user clicks a source (the synced clicked_object trait defaults to {}, which reads as None), so use req(sky.clicked_object()) to wait for a click. Seeded at render and per instance, so a click made before the first read is reflected in it; a re-render builds a new viewer with no click yet, so it starts over at None. Clicking the same source twice doesn’t fire twice. Not rate-limited.

fov()

render_ipyaladin.fov()

The view’s field of view, as an astropy Angle.

Seeded at render and follows every zoom (and Python-side .widget.fov = ... assignments); reading before the first render cancels silently (like req(False)). Not rate-limited. With two or more ipyaladin viewers on the same page, this follows only the last-rendered one (an ipyaladin limitation: its frontend syncs the field of view from one viewer per page).

selected()

render_ipyaladin.selected()

The catalog sources inside the current selection, as a list of astropy Tables (one per catalog).

[] from mount until the user selects, which needs selection mode armed first (e.g., .widget.selection("rectangle")). Seeded at render, so it never returns None; reading before the first render cancels silently (like req(False)). Not rate-limited.

target()

render_ipyaladin.target()

The sky position at the center of the view, as an astropy SkyCoord (a (Longitude, Latitude) tuple for planetary surveys).

Seeded at render and follows every pan (and Python-side .widget.target = ... assignments); reading before the first render cancels silently (like req(False)). Not rate-limited.