API reference#

Plotting#

Public plotting API for SkyPlot.

Implementation details live in skyplot.plotlib; this module keeps the stable, user-facing plotting surface in one small place.

skyplot.plotting.add_gridlines(ax, *, color='black', linestyle='-', linewidth=0.2, lon_gridline_spacing_deg=30.0, lat_gridline_spacing_deg=30.0, alpha=1.0)[source]#

Add Cartopy gridlines to an existing GeoAxes.

Parameters:

  • ax (cartopy.mpl.geoaxes.GeoAxes) – Axes receiving the gridlines; required.

  • color (str, default="black") – Gridline color.

  • linestyle (str, default="-") – Matplotlib gridline style.

  • linewidth (float, default=0.2) – Positive gridline width in points.

  • lon_gridline_spacing_deg (float, default=30.0) – Positive longitude separation in degrees.

  • lat_gridline_spacing_deg (float, default=30.0) – Positive latitude separation in degrees.

  • alpha (float, default=1.0) – Gridline opacity.

Return type:

Any

skyplot.plotting.equidistantconic(map_data, *, projection_kwargs=None, extent=None, coordinate_frame=None, coordinate_transform=None, wcs=None, world_axis_mapping=None, ax=None, n_theta=720, n_phi=1440, resolution=None, nest=False, interpolate=False, cmap='roma_r', badvalue=-1.6375e+30, badcolor=None, vmin=None, vmax=None, norm=None, colorbar_title='Map value', title=None, show_gridlines=True, plot_mode='map', overlay_color='k', alpha=None, zorder=None, gridline_kwargs=None, pcolormesh_kwargs=None, vector_kwargs=None, add_colorbar=True, figsize=(8.0, 5.0), dpi=300)[source]#

Plot a sky map using a Cartopy EquidistantConic projection.

Parameters:

  • map_data (numpy.ndarray or sequence) – Required 1D HEALPix map or 2D WCS-backed image. In vector mode, a two-element (U, V) sequence of matching component maps.

  • projection_kwargs (dict or None, default=None) – Cartopy EquidistantConic options; cutoff is unsupported.

  • extent (sequence[float] or {"auto"} or None, default=None) – Geographic bounds for new axes and default projection-center inference. extent="auto" infers the WCS image footprint for WCS-backed maps and selects the global extent for HEALPix maps. None keeps the default global view. Regional extents also define the sampling domain.

  • coordinate_frame (str or None, default=None) – Source-frame metadata label.

  • coordinate_transform (sequence[str] or None, default=None) – (source_frame, display_frame) Astropy sampling transform. Common frame names are "icrs" (equatorial), "galactic", and "geocentrictrueecliptic" (ecliptic).

  • wcs (object or None, default=None) – WCS for 2D input.

  • world_axis_mapping (sequence[int] or None, default=None) – Explicit longitude/latitude WCS world-axis mapping.

  • ax (GeoAxes or None, default=None) – Existing overlay axes; None creates axes.

  • n_theta (int, defaults=720, 1440) – Sampling-grid dimensions.

  • n_phi (int, defaults=720, 1440) – Sampling-grid dimensions.

  • resolution ({"low", "medium", "high"} or None, default=None) – Sampling-grid preset and 14, 16, or 18 point base font for low, medium, or high, respectively; also selects 120, 200, or 300 DPI.

  • nest (bool, default=False) – Use HEALPix NEST ordering.

  • interpolate (bool, default=False) – Interpolate samples instead of using nearest-pixel lookup.

  • cmap (str or sequence, default="roma_r") – Colormap specification.

  • badvalue (float or None, default=healpy.UNSEEN) – Missing-data sentinel; None disables it.

  • badcolor (color or None, default=None) – Missing-data color. None makes missing samples transparent.

  • vmin (float or None, defaults=None, None) – Color-scale limits.

  • vmax (float or None, defaults=None, None) – Color-scale limits.

  • norm (str or Normalize or None, default=None) – Mesh color normalization.

  • colorbar_title (str, default="Map value") – Colorbar label.

  • title (str or None, default=None) – Axes title.

  • show_gridlines (bool, default=True) – Draw gridlines.

  • plot_mode ({"map", "overlay_mask", "vector_field"}, default="map") – Render a scalar map, a binary-mask overlay, or a transparent vector overlay. Vector mode requires a two-element (U, V) map sequence and ax= from a previously rendered magnitude map.

  • overlay_color (color, default="k") – Invalid-pixel overlay color. cmap is ignored for mask overlays.

  • alpha (float or None, default=None) – Layer opacity. Mask overlays default to 0.25 when omitted; an explicitly supplied value is used unchanged.

  • zorder (float or None, default=None) – Artist drawing order. Scalar maps default to 1, vector fields to 2, and mask overlays to 3.

  • gridline_kwargs (dict or None, defaults=None, None) – Extra gridline and mesh options.

  • pcolormesh_kwargs (dict or None, defaults=None, None) – Extra gridline and mesh options.

  • vector_kwargs (dict or None, default=None) – Options for the vector artist in vector mode. Set method to "streamplot" (default) or "quiver". Scalar color arguments are ignored in vector mode.

  • add_colorbar (bool, default=True) – Add a horizontal colorbar.

  • figsize (tuple[float, float], default=(8.0, 5.0)) – New-figure size.

  • dpi (int, default=300) – New-figure resolution.

Return type:

Figure

skyplot.plotting.gnomonic(map_data, *, center=(0.0, 0.0), xsize=500, ysize=500, n_theta=None, n_phi=None, pixel_size_arcmin=5.0, wcs=None, world_axis_mapping=None, ax=None, nest=False, interpolate=False, cmap='roma_r', badvalue=-1.6375e+30, badcolor=None, vmin=None, vmax=None, norm=None, colorbar_title='Map value', title=None, show_gridlines=False, gridline_kwargs=None, add_colorbar=True, plot_mode='map', overlay_color='k', alpha=None, zorder=None, astro_orientation=True, figsize=(5.5, 6.5), dpi=300, imshow_kwargs=None, vector_kwargs=None)[source]#

Plot a local gnomonic view using Matplotlib.

Parameters:

  • map_data (numpy.ndarray or sequence) – Required 1D HEALPix map or 2D WCS-backed image. In vector mode, a two-element (U, V) sequence of matching component maps.

  • center (sequence[float], default=(0.0, 0.0)) – Tangent point as (longitude_deg, latitude_deg).

  • xsize (int, defaults=500, 500) – Output width and height in pixels.

  • ysize (int, defaults=500, 500) – Output width and height in pixels.

  • n_theta (int or None, defaults=None, None) – Optional ysize and xsize overrides, respectively.

  • n_phi (int or None, defaults=None, None) – Optional ysize and xsize overrides, respectively.

  • pixel_size_arcmin (float, default=5.0) – Tangent-point pixel scale in arcminutes.

  • wcs (object or None, default=None) – WCS for 2D input.

  • world_axis_mapping (sequence[int] or None, default=None) – Explicit longitude/latitude WCS world-axis mapping.

  • ax (matplotlib.axes.Axes or None, default=None) – Existing axes for an overlay; None creates axes. Vector mode requires axes from a prior magnitude-map rendering.

  • nest (bool, default=False) – Use HEALPix NEST ordering.

  • interpolate (bool, default=False) – Interpolate sampled values instead of using nearest-pixel lookup.

  • cmap (str or sequence, default="roma_r") – Colormap specification.

  • badvalue (float or None, default=healpy.UNSEEN) – Missing-data sentinel; None disables it.

  • badcolor (color or None, default=None) – Missing-data color. None makes missing samples transparent.

  • vmin (float or None, defaults=None, None) – Color-scale limits.

  • vmax (float or None, defaults=None, None) – Color-scale limits.

  • norm (str or Normalize or None, default=None) – Image color normalization.

  • colorbar_title (str, default="Map value") – Colorbar label.

  • title (str or None, default=None) – Axes title.

  • show_gridlines (bool, default=False) – Draw unlabeled curved longitude and latitude graticules in the tangent plane. The axes otherwise display the center, patch size, and pixel size rather than coordinate ticks.

  • gridline_kwargs (dict or None, default=None) – Matplotlib contour-style overrides for gnomonic gridlines, such as color, linestyle, linewidth, or alpha.

  • plot_mode ({"map", "overlay_mask", "vector_field"}, default="map") – Render a scalar map, a binary-mask overlay, or a transparent vector overlay. Use a separate scalar-map call to render vector magnitude.

  • vector_kwargs (dict or None, default=None) – Options for the vector artist in vector mode. Set method to "streamplot" (default) or "quiver". Scalar color arguments are ignored in vector mode.

  • add_colorbar (bool, default=True) – Add a horizontal colorbar.

  • alpha (float or None, default=None) – Image opacity. Mask overlays default to 0.25 when omitted; an explicitly supplied value is used unchanged.

  • zorder (float or None, default=None) – Artist drawing order. Scalar maps default to 1, vector fields to 2, and mask overlays to 3.

  • astro_orientation (bool, default=True) – Display increasing longitude to the left.

  • figsize (tuple[float, float], default=(5.5, 5.5)) – New-figure size in inches.

  • dpi (int, default=300) – New-figure resolution.

  • imshow_kwargs (dict or None, default=None) – Extra keyword arguments forwarded to Axes.imshow.

  • overlay_color (Any)

Return type:

Figure

skyplot.plotting.mollweide(map_data, *, projection_kwargs=None, coordinate_frame=None, coordinate_transform=None, wcs=None, world_axis_mapping=None, ax=None, n_theta=720, n_phi=1440, resolution=None, nest=False, interpolate=False, cmap='roma_r', badvalue=-1.6375e+30, badcolor=None, vmin=None, vmax=None, norm=None, colorbar_title='Map value', title=None, show_gridlines=True, plot_mode='map', overlay_color='k', alpha=None, zorder=None, gridline_kwargs=None, pcolormesh_kwargs=None, vector_kwargs=None, add_colorbar=True, figsize=(8.0, 5.0), dpi=300)[source]#

Plot a sky map using a Cartopy Mollweide projection.

Parameters:

  • map_data (numpy.ndarray or sequence) – Required 1D HEALPix map or 2D WCS-backed image. In vector mode, a two-element (U, V) sequence of matching component maps.

  • projection_kwargs (dict or None, default=None) – Keyword arguments passed to Cartopy’s Mollweide CRS.

  • coordinate_frame (str or None, default=None) – Metadata label for the source coordinate frame.

  • coordinate_transform (sequence[str] or None, default=None) – (source_frame, display_frame) Astropy sampling transform. Common frame names are "icrs" (equatorial), "galactic", and "geocentrictrueecliptic" (ecliptic); for example, ("galactic", "icrs") displays a Galactic map in equatorial coordinates.

  • wcs (object or None, default=None) – WCS for a 2D input; its all_world2pix method is required.

  • world_axis_mapping (sequence[int] or None, default=None) – Explicit (longitude_axis, latitude_axis) WCS world-axis mapping.

  • ax (GeoAxes or None, default=None) – Existing axes for an overlay; None creates an axes.

  • n_theta (int, defaults=720, 1440) – Colatitude and longitude sampling-grid sizes.

  • n_phi (int, defaults=720, 1440) – Colatitude and longitude sampling-grid sizes.

  • resolution ({"low", "medium", "high"} or None, default=None) – Preset that overrides n_theta and n_phi and selects a larger readable font size (14, 16, or 18 points) and a 120, 200, or 300 DPI new figure for low, medium, or high.

  • nest (bool, default=False) – Treat a 1D HEALPix map as NEST ordered.

  • interpolate (bool, default=False) – Interpolate sampled values instead of using nearest-pixel lookup.

  • cmap (str or sequence, default="roma_r") – Matplotlib or colormaps colormap specification.

  • badvalue (float or None, default=healpy.UNSEEN) – Input sentinel converted to missing data; None disables sentinel matching.

  • badcolor (color or None, default=None) – Color for missing, non-finite, or sentinel samples. None makes missing samples transparent.

  • vmin (float or None, defaults=None, None) – Optional lower and upper color-scale limits.

  • vmax (float or None, defaults=None, None) – Optional lower and upper color-scale limits.

  • norm (str or matplotlib.colors.Normalize or None, default=None) – Matplotlib normalization forwarded to pcolormesh.

  • colorbar_title (str, default="Map value") – Label for the optional colorbar.

  • title (str or None, default=None) – Axes title.

  • show_gridlines (bool, default=True) – Draw Cartopy gridlines.

  • plot_mode ({"map", "overlay_mask", "vector_field"}, default="map") – Render a scalar map, a binary-mask overlay, or a transparent vector overlay. Vector mode requires a two-element (U, V) map sequence and ax= from a previously rendered magnitude map.

  • overlay_color (color, default="k") – Invalid-pixel overlay color. cmap is ignored for mask overlays.

  • alpha (float or None, default=None) – Layer opacity. Mask overlays default to 0.25 when omitted; an explicitly supplied value is used unchanged.

  • zorder (float or None, default=None) – Artist drawing order. Scalar maps default to 1, vector fields to 2, and mask overlays to 3.

  • gridline_kwargs (dict or None, default=None) – Overrides for gridline color, style, width, spacing, or opacity.

  • pcolormesh_kwargs (dict or None, default=None) – Extra keyword arguments passed to GeoAxes.pcolormesh.

  • vector_kwargs (dict or None, default=None) – Options for the vector artist in vector mode. Set method to "streamplot" (default) or "quiver". cmap, vmin, vmax, and norm are ignored in vector mode.

  • add_colorbar (bool, default=True) – Add a horizontal colorbar.

  • figsize (tuple[float, float], default=(8.0, 5.0)) – Figure size in inches when creating axes.

  • dpi (int, default=300) – Figure resolution when creating axes.

Return type:

Figure

skyplot.plotting.orthographic(map_data, *, projection_kwargs=None, coordinate_frame=None, coordinate_transform=None, wcs=None, world_axis_mapping=None, ax=None, n_theta=720, n_phi=1440, resolution=None, nest=False, interpolate=False, cmap='roma_r', badvalue=-1.6375e+30, badcolor=None, vmin=None, vmax=None, norm=None, colorbar_title='Map value', title=None, show_gridlines=True, plot_mode='map', overlay_color='k', alpha=None, zorder=None, gridline_kwargs=None, pcolormesh_kwargs=None, vector_kwargs=None, add_colorbar=True, figsize=(5.5, 6.5), dpi=300)[source]#

Plot a sky map using a Cartopy Orthographic projection.

Parameters:

  • map_data (numpy.ndarray or sequence) – Required 1D HEALPix map or 2D WCS-backed image. In vector mode, a two-element (U, V) sequence of matching component maps.

  • projection_kwargs (dict or None, default=None) – Keyword arguments passed to Cartopy’s Orthographic CRS.

  • coordinate_frame (str or None, default=None) – Metadata label for the source coordinate frame.

  • coordinate_transform (sequence[str] or None, default=None) – (source_frame, display_frame) Astropy sampling transform. Common frame names are "icrs" (equatorial), "galactic", and "geocentrictrueecliptic" (ecliptic).

  • wcs (object or None, default=None) – WCS for a 2D map input.

  • world_axis_mapping (sequence[int] or None, default=None) – Explicit longitude/latitude WCS world-axis indices.

  • ax (GeoAxes or None, default=None) – Existing axes for an overlay; None creates axes.

  • n_theta (int, defaults=720, 1440) – Colatitude and longitude sampling-grid sizes.

  • n_phi (int, defaults=720, 1440) – Colatitude and longitude sampling-grid sizes.

  • resolution ({"low", "medium", "high"} or None, default=None) – Preset overriding both sampling-grid sizes and selecting a 14, 16, or 18 point base font and 120, 200, or 300 DPI new figure for low, medium, or high, respectively.

  • nest (bool, default=False) – Use HEALPix NEST ordering for a 1D map.

  • interpolate (bool, default=False) – Interpolate sampled map values instead of using nearest-pixel lookup.

  • cmap (str or sequence, default="roma_r") – Colormap specification.

  • badvalue (float or None, default=healpy.UNSEEN) – Missing-data sentinel; None disables sentinel matching.

  • badcolor (color or None, default=None) – Missing-data color. None makes missing samples transparent.

  • vmin (float or None, defaults=None, None) – Optional color-scale limits.

  • vmax (float or None, defaults=None, None) – Optional color-scale limits.

  • norm (str or Normalize or None, default=None) – Color normalization passed to pcolormesh.

  • colorbar_title (str, default="Map value") – Optional colorbar label.

  • title (str or None, default=None) – Optional axes title.

  • show_gridlines (bool, default=True) – Draw geographic gridlines.

  • plot_mode ({"map", "overlay_mask", "vector_field"}, default="map") – Render a scalar map, a binary-mask overlay, or a transparent vector overlay. Vector mode requires a two-element (U, V) map sequence and ax= from a previously rendered magnitude map.

  • overlay_color (color, default="k") – Invalid-pixel overlay color. cmap is ignored for mask overlays.

  • alpha (float or None, default=None) – Layer opacity. Mask overlays default to 0.25 when omitted; an explicitly supplied value is used unchanged.

  • zorder (float or None, default=None) – Artist drawing order. Scalar maps default to 1, vector fields to 2, and mask overlays to 3.

  • gridline_kwargs (dict or None, defaults=None, None) – Extra gridline and mesh keyword arguments.

  • pcolormesh_kwargs (dict or None, defaults=None, None) – Extra gridline and mesh keyword arguments.

  • vector_kwargs (dict or None, default=None) – Options for the vector artist in vector mode. Set method to "streamplot" (default) or "quiver". Scalar color arguments are ignored in vector mode.

  • add_colorbar (bool, default=True) – Add a horizontal colorbar.

  • figsize (tuple[float, float], default=(5.5, 6.5)) – New-figure size in inches.

  • dpi (int, default=300) – New-figure resolution.

Return type:

Figure

skyplot.plotting.platecarree(map_data, *, projection_kwargs=None, extent=None, coordinate_frame=None, coordinate_transform=None, wcs=None, world_axis_mapping=None, ax=None, n_theta=720, n_phi=1440, resolution=None, nest=False, interpolate=False, cmap='roma_r', badvalue=-1.6375e+30, badcolor=None, vmin=None, vmax=None, norm=None, colorbar_title='Map value', title=None, show_gridlines=True, plot_mode='map', overlay_color='k', alpha=None, zorder=None, gridline_kwargs=None, pcolormesh_kwargs=None, vector_kwargs=None, add_colorbar=True, figsize=(8.0, 5.0), dpi=300)[source]#

Plot a sky map using a Cartopy PlateCarree projection.

Parameters:

  • map_data (numpy.ndarray or sequence) – Required 1D HEALPix map or 2D WCS-backed image. In vector mode, a two-element (U, V) sequence of matching component maps.

  • projection_kwargs (dict or None, default=None) – Keyword arguments for Cartopy’s PlateCarree CRS.

  • extent (sequence[float] or {"auto"} or None, default=None) – (lon_min, lon_max, lat_min, lat_max) in degrees for new axes; extent="auto" infers the WCS image footprint for WCS-backed maps and selects the global extent for HEALPix maps. None keeps the default global view. Regional extents also define the sampling domain; an existing ax retains its own extent.

  • coordinate_frame (str or None, default=None) – Source-frame metadata label.

  • coordinate_transform (sequence[str] or None, default=None) – (source_frame, display_frame) Astropy sampling transform. Common frame names are "icrs" (equatorial), "galactic", and "geocentrictrueecliptic" (ecliptic).

  • wcs (object or None, default=None) – WCS for 2D input.

  • world_axis_mapping (sequence[int] or None, default=None) – Explicit longitude/latitude WCS axes.

  • ax (GeoAxes or None, default=None) – Existing overlay axes; None creates axes.

  • n_theta (int, defaults=720, 1440) – Sampling-grid dimensions.

  • n_phi (int, defaults=720, 1440) – Sampling-grid dimensions.

  • resolution ({"low", "medium", "high"} or None, default=None) – Sampling-grid preset and 14, 16, or 18 point base font for low, medium, or high, respectively; also selects 120, 200, or 300 DPI.

  • nest (bool, default=False) – Use HEALPix NEST ordering.

  • interpolate (bool, default=False) – Interpolate samples instead of using nearest-pixel lookup.

  • cmap (str or sequence, default="roma_r") – Colormap specification.

  • badvalue (float or None, default=healpy.UNSEEN) – Missing-data sentinel; None disables it.

  • badcolor (color or None, default=None) – Missing-data color. None makes missing samples transparent.

  • vmin (float or None, defaults=None, None) – Color-scale limits.

  • vmax (float or None, defaults=None, None) – Color-scale limits.

  • norm (str or Normalize or None, default=None) – Mesh color normalization.

  • colorbar_title (str, default="Map value") – Colorbar label.

  • title (str or None, default=None) – Axes title.

  • show_gridlines (bool, default=True) – Draw gridlines.

  • plot_mode ({"map", "overlay_mask", "vector_field"}, default="map") – Render a scalar map, a binary-mask overlay, or a transparent vector overlay. Vector mode requires a two-element (U, V) map sequence and ax= from a previously rendered magnitude map.

  • overlay_color (color, default="k") – Invalid-pixel overlay color. cmap is ignored for mask overlays.

  • alpha (float or None, default=None) – Layer opacity. Mask overlays default to 0.25 when omitted; an explicitly supplied value is used unchanged.

  • zorder (float or None, default=None) – Artist drawing order. Scalar maps default to 1, vector fields to 2, and mask overlays to 3.

  • gridline_kwargs (dict or None, defaults=None, None) – Extra gridline and mesh options.

  • pcolormesh_kwargs (dict or None, defaults=None, None) – Extra gridline and mesh options.

  • vector_kwargs (dict or None, default=None) – Options for the vector artist in vector mode. Set method to "streamplot" (default) or "quiver". Scalar color arguments are ignored in vector mode.

  • add_colorbar (bool, default=True) – Add a horizontal colorbar.

  • figsize (tuple[float, float], default=(8.0, 5.0)) – New-figure size.

  • dpi (int, default=300) – New-figure resolution.

Return type:

Figure

Plotting implementation#

The lower-level Matplotlib and Cartopy rendering functions are available for applications that need custom projection factories or rendering integration. Most users should prefer skyplot.plotting.

Matplotlib + Cartopy visualization routines for HEALPix sky maps.

skyplot.plotlib.plot_with_projection(map_data, *, projection_name, projection_factory, projection_kwargs=None, extent=None, coordinate_frame=None, coordinate_transform=None, wcs=None, world_axis_mapping=None, ax=None, n_theta=720, n_phi=1440, resolution=None, nest=False, interpolate=False, cmap='roma_r', badvalue=-1.6375e+30, badcolor=None, vmin=None, vmax=None, norm=None, colorbar_title='Map value', title=None, show_gridlines=True, plot_mode='map', gridline_adder=None, overlay_color='k', alpha=None, zorder=None, gridline_kwargs=None, pcolormesh_kwargs=None, vector_kwargs=None, add_colorbar=True, figsize=(8.0, 5.0), dpi=300)[source]#

Render a sampled sky map on a supplied Cartopy projection.

This is the implementation primitive behind the named projection renderers. Most callers should use skyplot.plotting; this function is useful when an application supplies its own Cartopy CRS factory.

Parameters:

  • map_data (numpy.ndarray or sequence) – Required 1D HEALPix map or 2D WCS-backed image. For plot_mode="vector_field", provide a two-element (U, V) sequence of matching component maps.

  • projection_name (str) – Required metadata name for the projection.

  • projection_factory (callable) – Required callable that constructs the Cartopy CRS.

  • projection_kwargs (dict or None, default=None) – CRS-constructor keyword arguments.

  • extent (sequence[float] or {"auto"} or None, default=None) – New-axes geographic extent as (lon_min, lon_max, lat_min, lat_max). extent="auto" infers the WCS image footprint for a WCS-backed 2D map and selects the global extent for a HEALPix map. None keeps the default global view. For regional Plate Carrée and Equidistant Conic views, the configured sampling grid is generated within the selected extent.

  • coordinate_frame (str or None, default=None) – Source-frame metadata label.

  • coordinate_transform (sequence[str] or None, default=None) – (source_frame, display_frame) Astropy sampling transform. Common frame names are "icrs" (equatorial), "galactic", and "geocentrictrueecliptic" (ecliptic). For example, ("galactic", "icrs") displays a Galactic map in equatorial coordinates.

  • wcs (object or None, default=None) – WCS used for a 2D input.

  • world_axis_mapping (sequence[int] or None, default=None) – Explicit (longitude_axis, latitude_axis) WCS world-axis mapping. This permits a 2D image to retain WCS metadata with additional world axes when its shape matches the WCS spatial pixel axes. Non-spatial axes are evaluated at their WCS reference values; slice coupled WCS and data cubes to the intended plane before plotting.

  • ax (GeoAxes or None, default=None) – Existing axes for an overlay; None creates axes. Vector mode requires axes from a previously rendered magnitude map.

  • n_theta (int, default=720) – Colatitude sampling-grid size.

  • n_phi (int, default=1440) – Longitude sampling-grid size.

  • resolution ({"low", "medium", "high"} or None, default=None) – Preset overriding n_theta and n_phi. It also uses a 14, 16, or 18 point base font and a 120, 200, or 300 DPI new figure for low, medium, or high, respectively.

  • nest (bool, default=False) – Use HEALPix NEST ordering.

  • interpolate (bool, default=False) – Interpolate samples instead of using nearest-pixel lookup.

  • cmap (str or sequence, default="roma_r") – Colormap specification.

  • badvalue (float or None, default=healpy.UNSEEN) – Missing-data sentinel; None disables it.

  • badcolor (color or None, default=None) – Missing-data color. None makes missing samples transparent.

  • vmin (float or None, default=None) – Lower color-scale limit.

  • vmax (float or None, default=None) – Upper color-scale limit.

  • norm (str or Normalize or None, default=None) – Mesh color normalization.

  • colorbar_title (str, default="Map value") – Colorbar label.

  • title (str or None, default=None) – Axes title.

  • show_gridlines (bool, default=True) – Draw gridlines.

  • gridline_adder (callable or None, default=None) – Function that adds Cartopy gridlines. Required when show_gridlines=True for direct low-level use.

  • plot_mode ({"map", "overlay_mask", "vector_field"}, default="map") – Rendering mode. "vector_field" accepts a (U, V) pair of HEALPix maps or WCS-backed arrays and draws only a transparent vector overlay. Draw its magnitude in a separate plot_mode="map" call before passing that figure’s axes here. Scalar color-scale arguments are ignored.

  • overlay_color (color, default="k") – Invalid-pixel overlay color. cmap is ignored for mask overlays.

  • alpha (float or None, default=None) – Opacity of the plotted layer. Mask overlays default to 0.25 when omitted; an explicitly supplied value is used unchanged.

  • zorder (float or None, default=None) – Artist drawing order. Scalar maps default to 1, vector fields to 2, and mask overlays to 3. An explicit value is used unchanged.

  • gridline_kwargs (dict or None, default=None) – Gridline option overrides.

  • pcolormesh_kwargs (dict or None, default=None) – Extra mesh keyword arguments.

  • vector_kwargs (dict or None, default=None) – Options passed to the vector artist when plot_mode="vector_field". method selects "streamplot" (default) or "quiver".

  • add_colorbar (bool, default=True) – Add a horizontal colorbar.

  • figsize (tuple[float, float], default=(8.0, 5.0)) – New-figure size in inches.

  • dpi (int, default=300) – New-figure resolution.

  • is (The projection_factory creates a Cartopy CRS. When ax)

  • provided

  • rendering. (its projection and viewport are retained for overlay)

Returns:

The figure containing the rendered map.

Return type:

matplotlib.figure.Figure

Normalization#

Matplotlib normalizations provided by SkyPlot.

skyplot.normalization.PlanckLogNorm(vmin=None, vmax=None, linthresh=10.0)[source]#

Return the Planck-style symmetric logarithmic normalization.

The forward transform is arcsinh(0.5 * value / linthresh) / ln(10) and its analytic inverse. It is linear close to zero and becomes logarithmic at larger absolute values. When either limit is omitted, Matplotlib derives it from the first plotted map, as for its built-in normalizations.

Parameters:

  • vmin (float or None, defaults=None, None) – Optional data limits passed to matplotlib.colors.FuncNorm. An omitted limit is derived from the plotted map.

  • vmax (float or None, defaults=None, None) – Optional data limits passed to matplotlib.colors.FuncNorm. An omitted limit is derived from the plotted map.

  • linthresh (float, default=10.0) – Scale of the linear region around zero. It must be finite and positive.

Returns:

A Matplotlib normalization suitable for a plotting function’s norm= argument.

Return type:

matplotlib.colors.FuncNorm

Sampling#

Sampling helpers for HEALPix sky maps.

skyplot.sampling.make_theta_phi_grid(n_theta, n_phi, *, theta_min=0.0001, theta_max=None, phi_min=0.0, phi_max=6.283185307179586)[source]#

Build a regular full-sky angular grid in radians.

Parameters:

  • n_theta (int) – Number of samples in colatitude direction.

  • n_phi (int) – Number of samples in longitude direction.

  • theta_min (float, optional) – Minimum colatitude in radians. Small positive defaults avoid exact pole singularities in some workflows.

  • theta_max (float or None, optional) – Maximum colatitude in radians. If None, uses pi - theta_min.

  • phi_min (float, optional) – Inclusive and exclusive longitude bounds in radians, respectively. They must lie within [0, 2*pi] with phi_min < phi_max.

  • phi_max (float, optional) – Inclusive and exclusive longitude bounds in radians, respectively. They must lie within [0, 2*pi] with phi_min < phi_max.

Returns:

(theta_grid, phi_grid) each with shape (n_theta, n_phi).

Return type:

tuple[numpy.ndarray, numpy.ndarray]

Raises:

ValueError – If grid sizes are not integers of at least 2, or angular bounds are non-finite, outside their physical ranges, or not increasing.

skyplot.sampling.sample_at_angles(hp_map, theta, phi, *, nest=False, lonlat=False, interpolate=False, badvalue=-1.6375e+30)[source]#

Sample a HEALPix map at supplied angular coordinates.

Parameters:

  • hp_map (numpy.ndarray) – Input HEALPix map, shape (npix,).

  • theta (numpy.ndarray) – Polar angle(s). If lonlat=False, this is colatitude in radians. If lonlat=True, this is longitude in degrees.

  • phi (numpy.ndarray) – Azimuth angle(s). If lonlat=False, this is longitude in radians. If lonlat=True, this is latitude in degrees.

  • nest (bool, optional) – Whether input map uses NEST ordering. Default is False for RING.

  • lonlat (bool, optional) – Interpret theta and phi as longitude/latitude in degrees when True. Default is False.

  • interpolate (bool, optional) – Use bilinear interpolation when True. Use nearest-pixel sampling when False. Default is False.

  • badvalue (float or None, optional) – Input sentinel value treated as missing data. Defaults to healpy.UNSEEN. NaN values are always treated as missing.

Returns:

Sampled map values with broadcasted shape of theta and phi.

Return type:

numpy.ndarray

Raises:

ValueError – If input map is invalid or angle arrays have incompatible shapes.

skyplot.sampling.sample_full_sky(hp_map, *, n_theta=240, n_phi=480, nest=False, interpolate=False, badvalue=-1.6375e+30)[source]#

Sample an input HEALPix map on a regular full-sky grid.

Parameters:

  • hp_map (numpy.ndarray) – Input HEALPix map, shape (npix,).

  • n_theta (int, optional) – Number of colatitude samples in output grid. Default is 240.

  • n_phi (int, optional) – Number of longitude samples in output grid. Default is 480.

  • nest (bool, optional) – Whether input map uses NEST ordering. Default is False.

  • interpolate (bool, optional) – Use interpolation when True, nearest-pixel lookup otherwise.

  • badvalue (float or None, optional) – Input sentinel value treated as missing data. Defaults to healpy.UNSEEN. NaN values are always treated as missing.

Returns:

(lon_deg, lat_deg, values) arrays, all with shape (n_theta, n_phi).

Return type:

tuple[numpy.ndarray, numpy.ndarray, numpy.ndarray]

Notes

Longitudes are wrapped to [-180, 180) degrees to align with Plotly geo projections.

Saving#

Figure export utilities for skyplot (Matplotlib backend).

skyplot.saving.save_figure(fig=None, output_path=None, *, width=None, height=None, figsize=(8.0, 5.0), dpi=300, scale=1.0)[source]#

Save a Matplotlib figure to a static image format selected by suffix.

If fig is omitted, the most recently created skyplot figure is used. A path without a suffix is saved as PNG with .png appended.

Parameters:

  • fig (Figure | None)

  • output_path (str | Path | None)

  • width (int | None)

  • height (int | None)

  • figsize (tuple[float, float])

  • dpi (int)

  • scale (float)

Return type:

Path