hats.inspection.visualize_catalog
=================================

.. py:module:: hats.inspection.visualize_catalog

.. autoapi-nested-parse::

   Generate a molleview map with the pixel densities of the catalog

   NB: Testing validity of generated plots is currently not tested in our unit test suite.

   ..
       !! processed by numpydoc !!


Functions
---------

.. autoapisummary::

   hats.inspection.visualize_catalog.plot_density
   hats.inspection.visualize_catalog.plot_pixels
   hats.inspection.visualize_catalog.plot_pixel_list
   hats.inspection.visualize_catalog.plot_moc
   hats.inspection.visualize_catalog.plot_healpix_map


Module Contents
---------------

.. py:function:: plot_density(catalog: hats.catalog.Catalog, *, plot_title: str | None = None, order=None, unit=None, **kwargs)

   
   Create a visual map of the density of input points of a catalog on-disk.


   :Parameters:

       **catalog: Catalog**
           on-disk catalog object

       **plot_title** : str | None
           Optional title for the plot

       **order** : int
           Optionally reduce the display healpix order, and aggregate smaller tiles. (Default value = None)

       **unit** : astropy.units.Unit
           Unit to show for the angle for angular density. (Default value = None)

       **\*\*kwargs**
           Additional args to pass to `plot_healpix_map`







   :Raises:

       ImportError
           if matplotlib is not installed in the current environment.

       ValueError
           if an in-memory-only catalog is provided.







   ..
       !! processed by numpydoc !!

.. py:function:: plot_pixels(catalog: hats.catalog.healpix_dataset.healpix_dataset.HealpixDataset, plot_title: str | None = None, **kwargs)

   
   Create a visual map of the pixel density of the catalog.


   :Parameters:

       **plot_title** : str | None
           Optional title for the plot

       **catalog: HealpixDataset**
           on-disk or in-memory catalog, with healpix pixels.

       **\*\*kwargs**
           Additional args to pass to `plot_healpix_map`














   ..
       !! processed by numpydoc !!

.. py:function:: plot_pixel_list(pixels: list[hats.pixel_math.HealpixPixel], plot_title: str = '', projection='MOL', color_by_order=True, **kwargs)

   
   Create a visual map of the pixel density of a list of pixels.


   :Parameters:

       **pixels** : list[HealpixPixel]
           healpix pixels (order and pixel number) to visualize

       **plot_title** : str
           (Default value = "") heading for the plot

       **projection** : str
           The projection to use. Available projections listed at
           https://docs.astropy.org/en/stable/wcs/supported_projections.html (Default value = "MOL")

       **color_by_order** : bool
           Whether to color the pixels by their order. True by default.

       **\*\*kwargs**
           Additional args to pass to `plot_healpix_map`







   :Raises:

       ImportError
           if matplotlib is not installed in the current environment.







   ..
       !! processed by numpydoc !!

.. py:function:: plot_moc(moc: mocpy.MOC, *, projection: str = 'MOL', title: str = '', fov: astropy.units.Quantity | tuple[astropy.units.Quantity, astropy.units.Quantity] = None, center: astropy.coordinates.SkyCoord | None = None, wcs: astropy.wcs.WCS = None, frame_class: Type[astropy.visualization.wcsaxes.frame.BaseFrame] | None = None, ax: astropy.visualization.wcsaxes.WCSAxes | None = None, fig: matplotlib.figure.Figure | None = None, **kwargs) -> tuple[matplotlib.figure.Figure, astropy.visualization.wcsaxes.WCSAxes]

   
   Plots a moc

   By default, a new matplotlib figure and axis will be created, and the projection will be a Molleweide
   projection across the whole sky.

   :Parameters:

       **moc** : mocpy.MOC
           MOC to plot

       **projection** : str
           The projection to use in the WCS. Available projections listed at
           https://docs.astropy.org/en/stable/wcs/supported_projections.html
           (Default value = "MOL")

       **title** : str
           The title of the plot (Default value = "")

       **fov** : Quantity | tuple[Quantity, Quantity] = None
           The Field of View of the WCS. Must be an astropy Quantity with an angular unit,
           or a tuple of quantities for different longitude and latitude FOVs (Default covers the full sky)

       **center** : SkyCoord | None
           The center of the projection in the WCS (Default: SkyCoord(0, 0))

       **wcs** : WCS | None
           The WCS to specify the projection of the plot. If used, all other WCS parameters
           are ignored and the parameters from the WCS object is used.

       **frame_class** : Type[BaseFrame] | None
           The class of the frame for the WCSAxes to be initialized with.
           if the `ax` kwarg is used, this value is ignored (By Default uses EllipticalFrame for full
           sky projection. If FOV is set, RectangularFrame is used)

       **ax** : WCSAxes | None
           The matplotlib axes to plot onto. If None, an axes will be created to be used. If
           specified, the axes must be an astropy WCSAxes, and the `wcs` parameter must be set with the WCS
           object used in the axes. (Default: None)

       **fig** : Figure | None
           The matplotlib figure to add the axes to. If None, one will be created, unless
           ax is specified (Default: None)

       **\*\*kwargs**
           Additional kwargs to pass to `mocpy.MOC.fill`



   :Returns:

       Tuple[Figure, WCSAxes]
           The figure and axes used to plot the healpix map




   :Raises:

       ImportError
           if matplotlib is not installed in the current environment.







   ..
       !! processed by numpydoc !!

.. py:function:: plot_healpix_map(healpix_map: numpy.ndarray, *, projection: str = 'MOL', title: str = '', cmap: str | matplotlib.colors.Colormap = 'viridis', norm: matplotlib.colors.Normalize | None = None, ipix: numpy.ndarray | None = None, depth: numpy.ndarray | None = None, cbar: bool = True, fov: astropy.units.Quantity | tuple[astropy.units.Quantity, astropy.units.Quantity] = None, center: astropy.coordinates.SkyCoord | None = None, wcs: astropy.wcs.WCS = None, frame_class: Type[astropy.visualization.wcsaxes.frame.BaseFrame] | None = None, ax: astropy.visualization.wcsaxes.WCSAxes | None = None, fig: matplotlib.figure.Figure | None = None, **kwargs)

   
   Plot a map of HEALPix pixels to values as a colormap across a projection of the sky

   Plots the given healpix pixels on a spherical projection defined by a WCS. Colors each pixel based on the
   corresponding value in a map. The map can be across all healpix pixels at a given order, or
   specify a subset of healpix pixels with the `ipix` and `depth` parameters.

   By default, a new matplotlib figure and axis will be created, and the projection will be a Molleweide
   projection across the whole sky. Additional kwargs will be passed to the creation of a matplotlib
   ``PathCollection`` object, which is the artist that draws the tiles.

   :Parameters:

       **healpix_map** : np.ndarray
           Array of map values for the healpix tiles. If ipix and depth are not
           specified, the length of this array will be used to determine the healpix order, and will plot
           healpix pixels with pixel index corresponding to the array index in NESTED ordering. If ipix and
           depth are specified, all arrays must be of the same length, and the pixels specified by the
           ipix and depth arrays will be plotted with their values specified in the healpix_map array.

       **projection** : str
           The projection to use in the WCS. Available projections listed at
           https://docs.astropy.org/en/stable/wcs/supported_projections.html

       **title** : str
           The title of the plot

       **cmap** : str | Colormap
           The matplotlib colormap to plot with

       **norm** : Normalize | None
           The matplotlib normalization to plot with

       **ipix** : np.ndarray | None
           Array of HEALPix NESTED pixel indices. Must be used with depth, and arrays
           must be the same length

       **depth** : np.ndarray | None
           Array of HEALPix pixel orders. Must be used with ipix, and arrays
           must be the same length

       **cbar** : bool
           If True, includes a color bar in the plot (Default: True)

       **fov** : Quantity or Quantity | tuple[Quantity, Quantity]
           The Field of View of the WCS. Must be an astropy Quantity with an angular unit,
           or a tuple of quantities for different longitude and latitude FOVs (Default covers the full sky)

       **center** : SkyCoord | None
           The center of the projection in the WCS (Default: SkyCoord(0, 0))

       **wcs** : WCS | None
           The WCS to specify the projection of the plot. If used, all other WCS parameters
           are ignored and the parameters from the WCS object is used.

       **frame_class** : Type[BaseFrame] | None
           The class of the frame for the WCSAxes to be initialized with.
           if the `ax` kwarg is used, this value is ignored (By Default uses EllipticalFrame for full
           sky projection. If FOV is set, RectangularFrame is used)

       **ax** : WCSAxes | None
           The matplotlib axes to plot onto. If None, an axes will be created to be used. If
           specified, the axes must be an astropy WCSAxes, and the `wcs` parameter must be set with the WCS
           object used in the axes. (Default: None)

       **fig** : Figure | None
           The matplotlib figure to add the axes to. If None, one will be created, unless
           ax is specified (Default: None)

       **\*\*kwargs**
           Additional kwargs to pass to creating the matplotlib `PathCollection` artist



   :Returns:

       Tuple[Figure, WCSAxes]
           The figure and axes used to plot the healpix map




   :Raises:

       ImportError
           if matplotlib is not installed in the current environment.







   ..
       !! processed by numpydoc !!