hpmoc.plotters module

More complex plotting commands for joint events in more human-readable formats, e.g. the GW skymap plots from O2 with their overlaid crosses marking neutrino positions.

hpmoc.plotters.add_disks(disks, rgba, ax=None, sigma=1, degrees=True, zorder=1, shape=None, θφm=None)

disksIterable[Tuple[float, float, float]]: A list of (ra, dec, σ) tuples where ra is the right ascension, dec the declination, and σ the radius of the disk to be plotted.
rgbaTuple[float, float, float, float]: A tuple of red, green, blue, and alpha values between 0 and 1 to use for the disk color. If the disks overlap, the alpha value will gradually increase to reflect their overlap.
axhealpy.projaxes.SphericalProjAxes, optional: The healpy axes instance on which to plot s⃗. Uses current axes if not provided, i.e. plt.gca().
sigmafloat, optional: The size of the error region in terms of disk σ.
degreesbool, optional: Whether the disks angles are defined in degrees. If False, radians are assumed instead.
zorderfloat, optional: The z-order of the image. Make it higher to place it over previously-plotted images.
shapeTuple[int, int], optional: The shape of the projected image returned by one of the healpy.visufunc plotters when return_projected_map=True, i.e. the result of a call to ax.projmap. This determines the pixel locations.
θϕmTuple[array, array, array]: The return result of get_ax_angles. If you are making multiple plots, it might be slightly faster to reuse this value.

hpmoc.plotters.add_scatterplot(ax, right_ascensions, declinations, marker='$\\bigodot$', color='green', pt_labels=None, zorder=1000, **kwargs): Add a scatterplot to the current HEALpy axis. Useful for plotting neutrinos etc.; remaining kwargs are passed to healpy.projscatter. Returns the current figure.

hpmoc.plotters.azeqview(s⃗, *scatter, unit=None, cmap=None, rot=(180, 0, 0), **kwargs)

Make a healpy.visufunc.azeqview plot using LLAMA default styling with point sources optionally plotted on the sky.

Parameters

s⃗ (array-like or astropy.units.Quantity) – The full HEALPix skymap in NEST or RING ordering to plot.
*scatter (PointsTuple) – Point-sources to add as a scatterplot over s⃗. Each collection of points consists of a tuple of the form (points, rgba, marker, name), where each tuple is meant to represent a specific type of point-source; for example, if plotting both neutrino and catalog point sources, you’d provide a tuple for each. points is a list of point source tuples of the form (ra, dec) or (ra, dec, σ), where ra is right ascension, dec declination, and σ, optionally, the radial size of the point-source, all expressed in degrees. For each point where σ is specified, a translucent disk of radius sigma in the color specified by RGBA tuple rgba, where each value is in the range [0, 1], will be plotted over the skymap. The central location of each point source will be indicated by a marker, specified (optionally using LaTeX) for a collection of points as the string marker. The name of this collection of sources is given as the string name.
unit (str or astropy.units.Unit, optional) – The unit of the skymap values. If s⃗ is an astropy.units.Quantity instance and unit is not provided, it will be read from s⃗.
cmap (matplotlib.colors.Colormap) – The colormap for the plotted skymap. If not defined, the default LLAMA colormap returned by default_cmap is used.
rot (Tuple[float, float, float], optional) – The rotation to apply to the skymap; define the central longitude, central latitude, and rotation about center. The default LIGO skymap orientation is used by default, unless a single point is specified in *scatter; in this case, the plot is centered at that point by default.
sigmas (Union[float, List[float]]) – Plot error region disks for point sources of size sigmas. Provide a single sigma or a list of sigmas for multiple layers of disks, or omit error region disks from the plot by setting to an empty list.
graticule (Callable, optional) – A function called on a figure for rendering a graticule on the given figures.
**kwargs – Keyword args to pass to healpy.visufunc.azeqview.

Returns

fig – The axes instance that was plotted to.

Return type

matplotlib.axes.Axes

See also

healpy.visufunc.azeqview

hpmoc.plotters.cartview(s⃗, *scatter, unit=None, cmap=None, rot=(180, 0, 0), **kwargs)

Make a healpy.visufunc.cartview plot using LLAMA default styling with point sources optionally plotted on the sky.

Parameters

s⃗ (array-like or astropy.units.Quantity) – The full HEALPix skymap in NEST or RING ordering to plot.
*scatter (PointsTuple) – Point-sources to add as a scatterplot over s⃗. Each collection of points consists of a tuple of the form (points, rgba, marker, name), where each tuple is meant to represent a specific type of point-source; for example, if plotting both neutrino and catalog point sources, you’d provide a tuple for each. points is a list of point source tuples of the form (ra, dec) or (ra, dec, σ), where ra is right ascension, dec declination, and σ, optionally, the radial size of the point-source, all expressed in degrees. For each point where σ is specified, a translucent disk of radius sigma in the color specified by RGBA tuple rgba, where each value is in the range [0, 1], will be plotted over the skymap. The central location of each point source will be indicated by a marker, specified (optionally using LaTeX) for a collection of points as the string marker. The name of this collection of sources is given as the string name.
unit (str or astropy.units.Unit, optional) – The unit of the skymap values. If s⃗ is an astropy.units.Quantity instance and unit is not provided, it will be read from s⃗.
cmap (matplotlib.colors.Colormap) – The colormap for the plotted skymap. If not defined, the default LLAMA colormap returned by default_cmap is used.
rot (Tuple[float, float, float], optional) – The rotation to apply to the skymap; define the central longitude, central latitude, and rotation about center. The default LIGO skymap orientation is used by default, unless a single point is specified in *scatter; in this case, the plot is centered at that point by default.
sigmas (Union[float, List[float]]) – Plot error region disks for point sources of size sigmas. Provide a single sigma or a list of sigmas for multiple layers of disks, or omit error region disks from the plot by setting to an empty list.
graticule (Callable, optional) – A function called on a figure for rendering a graticule on the given figures.
**kwargs – Keyword args to pass to healpy.visufunc.cartview.

Returns

fig – The axes instance that was plotted to.

Return type

matplotlib.axes.Axes

See also

healpy.visufunc.cartview

hpmoc.plotters.default_cmap(): Get the matplotlib colormap.

hpmoc.plotters.get_ax_angles(ax, shape=None, lonlat=False)

hpmoc.plotters.get_ax_nside(ax, shape=None)

hpmoc.plotters.get_hp_ax_img_shape(ax): Get the shape of a healpy.projaxes.SphericalProjAxes instance’s plotted images.

hpmoc.plotters.gnomview(s⃗, *scatter, unit=None, cmap=None, rot=(180, 0, 0), **kwargs)

Make a healpy.visufunc.gnomview plot using LLAMA default styling with point sources optionally plotted on the sky.

Parameters

s⃗ (array-like or astropy.units.Quantity) – The full HEALPix skymap in NEST or RING ordering to plot.
*scatter (PointsTuple) – Point-sources to add as a scatterplot over s⃗. Each collection of points consists of a tuple of the form (points, rgba, marker, name), where each tuple is meant to represent a specific type of point-source; for example, if plotting both neutrino and catalog point sources, you’d provide a tuple for each. points is a list of point source tuples of the form (ra, dec) or (ra, dec, σ), where ra is right ascension, dec declination, and σ, optionally, the radial size of the point-source, all expressed in degrees. For each point where σ is specified, a translucent disk of radius sigma in the color specified by RGBA tuple rgba, where each value is in the range [0, 1], will be plotted over the skymap. The central location of each point source will be indicated by a marker, specified (optionally using LaTeX) for a collection of points as the string marker. The name of this collection of sources is given as the string name.
unit (str or astropy.units.Unit, optional) – The unit of the skymap values. If s⃗ is an astropy.units.Quantity instance and unit is not provided, it will be read from s⃗.
cmap (matplotlib.colors.Colormap) – The colormap for the plotted skymap. If not defined, the default LLAMA colormap returned by default_cmap is used.
rot (Tuple[float, float, float], optional) – The rotation to apply to the skymap; define the central longitude, central latitude, and rotation about center. The default LIGO skymap orientation is used by default, unless a single point is specified in *scatter; in this case, the plot is centered at that point by default.
sigmas (Union[float, List[float]]) – Plot error region disks for point sources of size sigmas. Provide a single sigma or a list of sigmas for multiple layers of disks, or omit error region disks from the plot by setting to an empty list.
graticule (Callable, optional) – A function called on a figure for rendering a graticule on the given figures.
**kwargs – Keyword args to pass to healpy.visufunc.gnomview.

Returns

fig – The axes instance that was plotted to.

Return type

matplotlib.axes.Axes

See also

healpy.visufunc.gnomview

hpmoc.plotters.graticule(ax, **kwargs): Add labels and a graticule to the given axes ax (with placement tailored to the plot type and window). Pass this to visufunc plotter functions.

hpmoc.plotters.label_graticule(ax, ras, decs, δr, δd, rot, ra_window=None, dec_window=None, **kwargs): Add text labels to a graticule.

hpmoc.plotters.layer_plot(s⃗, ax=None, vmin=None, vmax=None, cmap=None, zorder=0, shape=None, nest=True, θφm=None)

Show a new plot on top of an existing healpy axes instance.

Parameters

s⃗ (PartialUniqSkymap or array) – The skymap to plot. If a np.ndarray is given, assume it is a full skymap.
ax (healpy.projaxes.SphericalProjAxes, optional) – The healpy axes instance on which to plot s⃗. Uses current axes if not provided, i.e. plt.gca().
vmin (float, optional) – Minimum value of the colormap.
vmax (float, optional) – Maximum value of the colormap.
cmap (str, optional) – matplotlib colormap to use.
zorder (float, optional) – The z-order of the image. Make it higher to place it over previously-plotted images.
shape (Tuple[int, int], optional) – The shape of the projected image returned by one of the healpy.visufunc plotters when return_projected_map=True, i.e. the result of a call to ax.projmap. This determines the pixel locations.
nest (bool, optional) – Whether s⃗ has NEST HEALPix pixel ordering. This argument is ignored if s⃗ is a PartialUniqSkymap (implied UNIQ ordering).
θϕm (Tuple[array, array, array]) – The return result of get_ax_angles. If you are making multiple plots, it might be slightly faster to reuse this value.

hpmoc.plotters.mollview(s⃗, *scatter, unit=None, cmap=None, rot=(180, 0, 0), **kwargs)

Make a healpy.visufunc.mollview plot using LLAMA default styling with point sources optionally plotted on the sky.

Parameters

s⃗ (array-like or astropy.units.Quantity) – The full HEALPix skymap in NEST or RING ordering to plot.
*scatter (PointsTuple) – Point-sources to add as a scatterplot over s⃗. Each collection of points consists of a tuple of the form (points, rgba, marker, name), where each tuple is meant to represent a specific type of point-source; for example, if plotting both neutrino and catalog point sources, you’d provide a tuple for each. points is a list of point source tuples of the form (ra, dec) or (ra, dec, σ), where ra is right ascension, dec declination, and σ, optionally, the radial size of the point-source, all expressed in degrees. For each point where σ is specified, a translucent disk of radius sigma in the color specified by RGBA tuple rgba, where each value is in the range [0, 1], will be plotted over the skymap. The central location of each point source will be indicated by a marker, specified (optionally using LaTeX) for a collection of points as the string marker. The name of this collection of sources is given as the string name.
unit (str or astropy.units.Unit, optional) – The unit of the skymap values. If s⃗ is an astropy.units.Quantity instance and unit is not provided, it will be read from s⃗.
cmap (matplotlib.colors.Colormap) – The colormap for the plotted skymap. If not defined, the default LLAMA colormap returned by default_cmap is used.
rot (Tuple[float, float, float], optional) – The rotation to apply to the skymap; define the central longitude, central latitude, and rotation about center. The default LIGO skymap orientation is used by default, unless a single point is specified in *scatter; in this case, the plot is centered at that point by default.
sigmas (Union[float, List[float]]) – Plot error region disks for point sources of size sigmas. Provide a single sigma or a list of sigmas for multiple layers of disks, or omit error region disks from the plot by setting to an empty list.
graticule (Callable, optional) – A function called on a figure for rendering a graticule on the given figures.
**kwargs – Keyword args to pass to healpy.visufunc.mollview.

Returns

fig – The axes instance that was plotted to.

Return type

matplotlib.axes.Axes

See also

healpy.visufunc.mollview

hpmoc.plotters.multiplot(*s⃗l, transform: Optional[Callable] = None, plotters: List[Union[Callable, str]] = (<function mollview>, ), scatters: Optional[List[List[hpmoc.points.PointsTuple]]] = None, subplot_height: float = 4, suptitle: Optional[str] = None, dpi: float = 200, ncols: int = 2, widths: Optional[List[float]] = None, hspace: float = 0.2, wspace: float = 0.04, subplot_kwargs: Optional[List[Optional[List[dict]]]] = None, **kwargs)

Make a grid plot of multiple skymaps (optionally with scatterplots for each).

Parameters

*s⃗ₗ (List[np.ndarray]) – A list of skymaps to plot. Can either be a single-resolution full-sky HEALPix array or another format, though in the latter case a suitable transform function must be provided.
transform (Callable, optional) – A function taking a single element of s⃗ₗ and transforming it into a single-resolution full-sky HEALPix array. Only necessary if the elements of s⃗ₗ are not already in such a format. transform is called on each skymap directly before plotting, making it an effective way to manage memory usage when plotting compressed skymap formats.
plotters (List[Union[Callable, str]], optional) – A list of plotters from this module to use for each plot. If multiple plotters are specified, they will be plotted alongside each other; if this makes the figure too wide, change the number of columns in the grid with ncols. Plotters contained in this module can also be specified using their function names.
scatters (List[List[PointsTuple]], optional) – Scatterplots to use, one list for each skymap containing the sets of points to plot for that skymap. See plotter dosctrings for scatter, e.g. the mollview docstring for the format of each scatterplot specifier. Scatterplots for a given skymap will be added to each plotter.
subplot_height (float, optional) – The height of each subplot (in inches). Width is automatically determined. Overall figure height will be this times ncols.
suptitle (str, optional) – If provided, add a title for the entire multiplot at the top. You can manually call suptitle on the returned figure if you need to customize beyond the default title styling.
dpi (float, optional) – DPI of the output figure. Modify this to change the figure’s resolution.
ncols (int, optional) – How many columns of skymaps to include in the grid. NB: All subplots for a single skymap are counted as a single column (in contrast to matplotlib.gridspec.GridSpec, which counts each subplot in a single column). The number of rows is determined automatically from the number of skymaps provided combined with ncols.
widths (List[float], optional) – Ratios of widths of the plots in plotters as a multiple of subplot_height. Must have the same length as plotters.
hspace (float, optional) – How much vertical space (height) to reserve between subplots.
wspace (float, optional) – How much horizontal space (width) to reserve between subplots.
subplot_kwargs (List[Optional[List[dict]]], optional) – Lists of keyword argument dictionaries that will be used for each subplot. The first index specifies the plotter, and the second index specifies the skymap from s⃗ₗ. This behavior allows you to easily specify lists of keyword arguments for specific plotters (since often) only one of the plotters requires skymap-specific parameters). NB: These subplot-specific keyword arguments take precedence over **kwargs for their respective subplots.
**kwargs – Keyword arguments applied to all plotters. NB: hold=True is set for all subplots by default since a new figure is always created.

Returns

fig – A new matplotlib figure containing the specified subplots.

Return type

matplotlib.figure.Figure

Raises

ValueError – If scatters is provided and is ill-formatted or not of the same length as s⃗ₗ; if widths is included and is not of the same length as plotters; if subplot_kwargs is included and is not of the same length as plotters, or if its elements are neither None nor lists of the same length as s⃗ₗ; or if one of the plotters is specified as a string but cannot be found in this module.

hpmoc.plotters.orthview(s⃗, *scatter, unit=None, cmap=None, rot=(180, 0, 0), **kwargs)

Make a healpy.visufunc.orthview plot using LLAMA default styling with point sources optionally plotted on the sky.

Parameters

s⃗ (array-like or astropy.units.Quantity) – The full HEALPix skymap in NEST or RING ordering to plot.
*scatter (PointsTuple) – Point-sources to add as a scatterplot over s⃗. Each collection of points consists of a tuple of the form (points, rgba, marker, name), where each tuple is meant to represent a specific type of point-source; for example, if plotting both neutrino and catalog point sources, you’d provide a tuple for each. points is a list of point source tuples of the form (ra, dec) or (ra, dec, σ), where ra is right ascension, dec declination, and σ, optionally, the radial size of the point-source, all expressed in degrees. For each point where σ is specified, a translucent disk of radius sigma in the color specified by RGBA tuple rgba, where each value is in the range [0, 1], will be plotted over the skymap. The central location of each point source will be indicated by a marker, specified (optionally using LaTeX) for a collection of points as the string marker. The name of this collection of sources is given as the string name.
unit (str or astropy.units.Unit, optional) – The unit of the skymap values. If s⃗ is an astropy.units.Quantity instance and unit is not provided, it will be read from s⃗.
cmap (matplotlib.colors.Colormap) – The colormap for the plotted skymap. If not defined, the default LLAMA colormap returned by default_cmap is used.
rot (Tuple[float, float, float], optional) – The rotation to apply to the skymap; define the central longitude, central latitude, and rotation about center. The default LIGO skymap orientation is used by default, unless a single point is specified in *scatter; in this case, the plot is centered at that point by default.
sigmas (Union[float, List[float]]) – Plot error region disks for point sources of size sigmas. Provide a single sigma or a list of sigmas for multiple layers of disks, or omit error region disks from the plot by setting to an empty list.
graticule (Callable, optional) – A function called on a figure for rendering a graticule on the given figures.
**kwargs – Keyword args to pass to healpy.visufunc.orthview.

Returns

fig – The axes instance that was plotted to.

Return type

matplotlib.axes.Axes

See also

healpy.visufunc.orthview

hpmoc.plotters.unmask_partial_image(partial_image, mask, shape)

hpmoc.plotters.visufunc(**default_kwargs)

A decorator that adds LLAMA styling and overlaid scatterplots to healpy.visufunc plotting functions. Automatically calls the hp.visufunc function of the same name as func, leaving the wrapped function body to do apply post-plot styling defaults specific to that plotter. The current figure is passed to the wrapped function as the keyword argument fig.

If only a single point source is specified in *scatter, then the wrapped plotter will use the location of that point as the default rot value. If xsize is also provided to the decorator, then reso will also take a default value that fits the sky area contained in 2*max(sigmas).

Provide additional **default_kwargs to add to the wrapper if needed.

hpmoc.plotters.visufunc_defaults(s⃗, default_kwargs, *scatter, sigmas=1, graticule=<function graticule>, **kwargs)

Get default arguments for visufunc wrapped functions.

Parameters

s⃗ – Skymap to plot.
default_kwargs – Default keyword arguments from @visufunc wrapper.
sigmas – Error regions of point sources to plot.
*scatter – Scatterplot points.
**kwargs – Keyword arguments.

Returns

Input arguments updated to defaults. All keyword arguments are folded into kwargs.

Return type

s⃗, scatter, kwargs