Tools for Creating Source Catalogs¶

To help users create source catalogs in the proper format, Mirage contains the catalog generator and create catalog modules. catalog_generator.py contains classes for each of the types of catalogs accepted by Mirage. The create_catalog.py module contains functions that will query several astronomical databases and attempt to construct realistic point source and extragalactic catalogs for a given pointing. There is also a function for automated catalog creation from an input APT file. See the Catalog Generation Tools notebook in the Mirage repository for examples of all of this functionality.

Catalog_generator - Create catalogs from a list of sources¶

The classes in this module can be used to simplify Mirage catalog creation from lists of source coordinates and magnitudes. Generally the user instantiates the class for the desired type of catalog with a list of RA and Dec or detector x, y source positions. Magnitude columns can then be added to the catalog by providing a list of magnitudes as well as the instrument and filter name associated with the magnitudes. Catalogs may contain multiple magnitude columns covering multiple instruments and filters. Examples of how to use the catalog generator functionality are given in the Catalog Generation Tools notebook notebook. Below, we show examples for the most common catalogs: point sources and galaxies.

Point Source Catalog¶

The examples below create point source catalogs containing 10 sources. By supplying source locations via the ra and dec keywords, Mirage assumes that the locations are Right Ascention and Declination values given in decimal degrees. If you wish to specify source locations in units of row and column indexes on the detector, then the x and y keywords should be used, as seen in the second example below.

Columns containing AB magnitudes in the NIRCam F200W and F212N filters, as well as the NIRISS F090W filter are added to the catalog using the add_magnitude_column method. Note that the instrument and filter names associated with the magnitude values must be supplied in these calls. The mag_sys keyword is optional and allows uses to specify the magnitude system. Allowed values are “abmag”, “stmag”, and “vegamag”. The default is “abmag”. Note that all magnitude columns in a given catalog MUST be in the same magnitude system.

Once the catalog has been created and at least one magnitude column has been added, the table can be printed to the screen using the table method.

The save method will save the table in an ascii file in the appropriate format for Mirage to use.

import numpy as np
from mirage.catalogs import catalog_generator

ra_list = np.random.random(10) + 53.5
dec_list = np.random.random(10) - 67.2

nrc_f200w_mag = np.random.random(10) + 16.
nrc_f212n_mag = np.random.random(10) + 19.
nis_f090w_mag = np.random.random(10) + 15.5

ptsrc = catalog_generator.PointSourceCatalog(ra=ra_list, dec=dec_list)
ptsrc.add_magnitude_column(nrc_f200w_mag, instrument='nircam', filter='F200W', mag_sys='abmag')
ptsrc.add_magnitude_column(nrc_f212n_mag, instrument='nircam', filter='F212N', mag_sys='abmag')
ptsrc.add_magnitude_column(nis_f090w_mag, instrument='niriss', filter='F090W', mag_sys='abmag')
ptsrc.save('point_sources.cat')
ptsrc.table()

x_list = np.random.random(10) * 2048
y_list = np.random.random(10) * 2048

ptsrc = catalog_generator.PointSourceCatalog(x=x_list, y=y_list)
ptsrc.add_magnitude_column(nrc_f200w_mag, instrument='nircam', filter='F200W', mag_sys='abmag')
ptsrc.add_magnitude_column(nrc_f212n_mag, instrument='nircam', filter='F212N', mag_sys='abmag')
ptsrc.add_magnitude_column(nis_f090w_mag, instrument='niriss', filter='F090W', mag_sys='abmag')
ptsrc.save('point_sources_xy.cat')

Galaxy Catalog¶

The example below creates a galaxy catalog. The main difference compared to the point source catalog is that the user must provide values for the ellipticity, sersic index, and position angle when instantiating the class.

import numpy as np
from mirage.catalogs import catalog_generator

ra_list = np.random.random(10) + 53.5
dec_list = np.random.random(10) - 67.2
ellipticity = np.random.random(10) * 0.75
sersic_index = np.random.random(10) * 4.
position_angle = np.random.random(10) * 359.

nrc_f200w_mag = np.random.random(10) + 16.
nrc_f212n_mag = np.random.random(10) + 19.
nis_f090w_mag = np.random.random(10) + 15.5

gal = catalog_generator.GalaxyCatalog(ra=ra_list, dec=dec_list, ellipticity=ellipticity,
                                      sersic_index=sersic_index, position_angle=position_angle)
gal.add_magnitude_column(nrc_f200w_mag, instrument='nircam', filter='F200W', mag_sys='abmag')
gal.add_magnitude_column(nrc_f212n_mag, instrument='nircam', filter='F212N', mag_sys='abmag')
gal.add_magnitude_column(nis_f090w_mag, instrument='niriss', filter='F090W', mag_sys='abmag')
gal.save('galaxies.cat')
gal.table()

Create_catalogs - create catalogs using online astronomical databases¶

The functions in this module use astroquery to search astronomical databases and retrieve source lists for a given pointing. In this way, a user can quickly generate reasonably realistic catalogs of point sources and galaxies for a given pointing.

The get_all_catalogs function takes the RA and Dec of a particular pointing along with the width in arcseconds of the area for which to produce the catalog, and queries multiple databases to produce a point source catalog. An example call to create a 120 x 120 arcsecond catalog is shown below. The resulting point source catalog can then be placed in the pointSource entry of the yaml input file. Note that an email address is required input for the Besancon model query.

from mirage.catalogs import create_catalogs

ra = 80.4  # degrees
dec = -69.8  # degrees
box_width = 120  # arcseconds
filter_list = ['F444W', 'F480M']
cat, mag_column_names = create_catalog.get_all_catalogs(ra, dec, box_width, kmag_limits=(13, 29),
                                                        instrument='NIRCAM', filters=filter_list,
                                                        email='someone@somewhere.edu')

Foreground Stars¶

A realistic list of foreground stars is compiled by querying the 2MASS, WISE, and GAIA catalogs using the given pointing. Using the retrieved magnitudes in the various bands associated with these surveys, Mirage converts these to magnitude values in the requested NIRCam or NIRISS filters. Note that these queries return stars only down to about V=16. For dimmer stars, Mirage queries the Besancon model. This process is described in the Background Stars section below. The code needed to produce the foreground and background star lists, and combine the two into a single catalog is also shown in the Bakcground Stars section below.

Background Stars¶

To obtain a list of stars dimmer than those returned in the Foreground Stars search, Mirage uses astroquery to query the Besancon model of stars in the Milky Way. This query returns a representative sample (in terms of luminosity distribution) of stars for a given pointing, including a realistic stellar density and realistic luminosity distribution. Note that these stars are not actual stars in the sky.

Background Galaxies¶

For a given pointing, Mirage can also generate a catalog containing a representative sample of background galaxies. Similar to the Besancon query described above, Mirage will generate a catalog containing a realistic density of galaxies across the field at reasonable magnitudes. To accomplish this, Mirage queries the GOODS-S catalog from 3DHST and extracts an appropriate number of galaxies to populate the catalog at a reasonable density. Currently this function will fail if the user requests a catalog with an area larger than the GOODS-S field: 606,909 arcsec ². An example is shown below. The resulting file can then be placed in the galaxyListFile entry of the yaml input file.