Utilities

pymoc.util.catalog

pymoc.util.catalog.catalog_to_moc(catalog, radius, order, **kwargs)

Convert a catalog to a MOC.

The catalog is given as an Astropy SkyCoord object containing multiple coordinates. The radius of catalog entries can be given as an Astropy Quantity (with units), otherwise it is assumed to be in arcseconds.

Any additional keyword arguments are passed on to catalog_to_cells.

pymoc.util.catalog.catalog_to_cells(catalog, radius, order, include_fallback=True, **kwargs)

Convert a catalog to a set of cells.

This function is intended to be used via catalog_to_moc but is available for separate usage. It takes the same arguments as that function.

This function uses the Healpy query_disc function to get a list of cells for each item in the catalog in turn. Additional keyword arguments, if specified, are passed to query_disc. This can include, for example, inclusive (set to True to include cells overlapping the radius as well as those with centers within it) and fact (to control sampling when inclusive is specified).

If cells at the given order are bigger than the given radius, then query_disc may find none inside the radius. In this case, if include_fallback is True (the default), the cell at each position is included.

If the given radius is zero (or smaller) then Healpy query_disc is not used – instead the fallback position is used automatically.

pymoc.util.catalog.read_ascii_catalog(filename, format_, unit=None)

Read an ASCII catalog file using Astropy.

This routine is used by pymoctool to load coordinates from a catalog file in order to generate a MOC representation.

pymoc.util.plot

pymoc.util.plot.plot_moc(moc, order=None, antialias=0, filename=None, projection='cart', color='blue', title='', coord_sys='C', graticule=True, **kwargs)

Plot a MOC using Healpy.

This generates a plot of the MOC at the specified order, or the MOC’s current order if this is not specified. The MOC is flattened at an order of order + antialias to generate intermediate color levels.

Parameters:
  • order – HEALPix order at which to generate the plot.

  • antialias – number of additional HEALPix orders to use for intermediate color levels. (There can be 4 ** antialias levels.)

  • filename – file in which to save plot. If not specified then the plot is shown with plt.show().

  • projection

    map projection to be used — can be shortened to 4 characters. One of:

    • ’cart[esian]’ (uses healpy.visufunc.cartview)

    • ’moll[weide]’ (uses healpy.visufunc.mollview)

    • ’gnom[onic]’ (uses healpy.visufunc.gnomview)

  • color

    color scheme. One of:

    • ’blue’

    • ’green’

    • ’red’

    • ’black’

  • title – title of the plot.

  • coord_sys

    Healpy coordinate system code for the desired plot coordinates. One of:

    • ’C’ — Celestial (equatorial)

    • ’G’ — Galactic

    • ’E’ — Ecliptic

  • graticule – whether or not to draw a graticule.

  • **kwargs – passed to the selected Healpy plotting function.

pymoc.util.tool

pymoctool - PyMOC utility program

Usage:

pymoctool [INPUT]... [COMMAND [FILE]]... [--output OUTPUT]

This program can be used to manipulate MOC files. All formats handled by PyMOC (FITS, JSON and ASCII) are supported. The program maintains a “running” MOC into which all input files are merged. Each command operates on the “running” MOC. Input files and commands are processed in the order given to the command.

For example, this command:

pymoctool a.fits --output a.json b.fits --output merged.txt

would load a MOC “a.fits”, re-write it as “a.json”, merge (forming the union with) “b.fits” and write the combined MOC to “merged.txt”.

class pymoc.util.tool.CommandDict

Decorator to record commands in a dictionary.

exception pymoc.util.tool.CommandError

Class representing expected errors from PyMOC tool commands.

class pymoc.util.tool.MOCTool

Class implementing a basic tool to manipulate MOC files.

run(params)

Main run method for PyMOC tool.

Takes a list of command line arguments to process.

Each operation is performed on a current “running” MOC object.

read_moc(filename)

Read a file into the current running MOC object.

If the running MOC object has not yet been created, then it is created by reading the file, which will import the MOC metadata. Otherwise the metadata are not imported.

catalog()

Create MOC from catalog of coordinates.

This command requires that the Healpy and Astropy libraries be available. It attempts to load the given catalog, and merges it with the running MOC.

The name of an ASCII catalog file should be given. The file should contain either “RA” and “Dec” columns (for ICRS coordinates) or “Lon” and “Lat” columns (for galactic coordinates). The MOC order and radius (in arcseconds) can be given with additional options.

pymoctool --catalog coords.txt
    [order 12]
    [radius 3600]
    [unit (hour | deg | rad) (deg | rad)]
    [format commented_header]
    [inclusive]

Units (if not specified) are assumed to be hours and degrees for ICRS coordinates and degrees for galactic coordinates. The format, if not specified (as an Astropy ASCII table format name) is assumed to be commented header, e.g.:

# RA Dec
01:30:00 +45:00:00
22:30:00 +45:00:00
help()

Display command usage information.

identifier()

Set the identifier of the current MOC.

The new identifier should be given after this option.

pymoctool ... --id 'New MOC identifier' --output new_moc.fits
display_info()

Display basic information about the running MOC.

intersection()

Compute the intersection with the given MOC.

This command takes the name of a MOC file and forms the intersection of the running MOC with that file.

pymoctool a.fits --intersection b.fits --output intersection.fits
name()

Set the name of the current MOC.

The new name should be given after this option.

pymoctool ... --name 'New MOC name' --output new_moc.fits
normalize()

Normalize the MOC to a given order.

This command takes a MOC order (0-29) and normalizes the MOC so that its maximum order is the given order.

pymoctool a.fits --normalize 10 --output a_10.fits
write_moc()

Write the MOC to a given file.

subtract()

Subtract the given MOC from the running MOC.

This command takes the name of a MOC file to be subtracted from the running MOC.

pymoctool a.fits --subtract b.fits --output difference.fits
plot()

Show the running MOC on an all-sky map.

This command requires that the Healpy and matplotlib libraries be available. It plots the running MOC, which should be normalized to a lower order first if it would generate an excessively large pixel array.

pymoctool a.moc --normalize 8 --plot

It also accepts additional arguments which can be used to control the plot. The ‘order’ option can be used instead of normalizing the MOC before plotting. The ‘antialias’ option specifies an additional number of MOC orders which should be used to smooth the edges as plotted – 1 or 2 is normally sufficient. The ‘file’ option can be given to specify a file to which the plot should be saved.

pymoctool ... --plot [order <order>] [antialias <level>] [file <filename>] ...
version()

Show PyMOC version number.