API Reference

You can find automatically generated documentation for each module in the zCluster package below. Note that some functions listed here may not be used by any of the scripts found in the bin/ directory.

catalogs

This module contains tools for handling catalogs.

catalog2DS9(catalog, outFileName, constraintsList=[], addInfo=[], idKeyToUse='name', RAKeyToUse='RADeg', decKeyToUse='decDeg', color='cyan')

Converts a catalog containing object dictionaries into a ds9 region file. Objects will be labelled in the .reg file according to the idKeyToUse.

If color == ‘key’, then use ‘color’ key in object dictionary to set color.

constraintsList works the same way as selectFromCatalog function

getNEDInfo(obj, nedDir='NEDResults', radiusDeg=0.08333333333333333, crossMatchRadiusDeg=0.041666666666666664, refetch=True): Queries NED for matches near each obj (must have keys name, RADeg, decDeg) and returns the nearest cluster match and its distance in arcmin. We search a box of radiusDeg around the object.

makeRADecString(RADeg, decDeg): Switched to using %.5f_%.5f as part of image file names.

parseNEDResult(inFileName, onlyObjTypes=None)

Parses NED tab-delimited text file query result, returns dictionary.

onlyObjTypes can be a string indicating types of objects only to include e.g. GClstr

selectFromCatalog(catalog, constraintsList)

Given a catalog (list of dictionaries representing objects), return a list of objects matching the given constraintsList. Each item in constraintsList is a string in the form:

“key < value”, “key > value”, etc.

Note that the spaces between key, operator (e.g. ‘<’) and value are essential!

writeCatalog(catalog, outFileName, keysToWrite, keyFormats, constraintsList, headings=True, extraHeaderText=None)

Dumps the catalog to a .csv.

constraintsList works as in the selectFromCatalog function.

writeRedshiftsCatalog(catalog, outFileName): Writes a .fits table with cluster photo-zs in it

clusters

This module contains routines for estimating galaxy cluster photometric redshifts.

applyUniformPrior(pz, zArray, zPriorMin=None, zPriorMax=None): Applies uniform redshift prior to pz between zPriorMin and zPriorMax.

calculateRedshiftAndOdds(pz, zArray, dzOdds=0.2, method='max', zPriorMax=None, zPriorMin=None)

Calculates z and BPZ/EAZY style odds for given pz, zArray

Method == ‘max’ finds z based on max peak in pz Method == ‘odds’ finds z based on z at which odds is maximised

estimateAreaMask(RADeg, decDeg, catalog)

Using the objects in the catalog, estimate the area covered - to take care of e.g. survey boundaries without needing to get masks for every survey. This works by estimating the average angular separation between sources in the catalog, and using that to draw a circle of that radius around every object. This is then used as the mask in area calculations.

Parameters:

RADeg (float) – Cluster RA position in decimal degrees.
decDeg (float) – Cluster dec position in decimal degrees.
catalog (list) – List of dictionaries, where each dictionary defines an object in the catalog.

Returns:

Mask of area covered. wcs (astWCS.WCS object): WCS corresponding to areaMask.

Return type:

areaMask (2d array)

estimateClusterRedshift(RADeg, decDeg, catalog, zPriorMin, zPriorMax, weightsType, maxRMpc, zMethod, maskMap=None, maskWCS=None, sanityCheckRadiusArcmin=1.0, bckCatalog=[], bckAreaDeg2=None, filterDeltaValues=True, minBackgroundAreaMpc2=11.0)

This does the actual work of estimating cluster photo-z from catalog.

Assumes each object has keys ‘pz’ (p(z), probability distribution), ‘pz_z’ (corresponding redshifts at each point in p(z)

If bckCatalog and bckAreaDeg2 are given, then these are used for the background estimation. If not, then a projected 3-4 Mpc annulus is used.

If zDebias is not None, the final output redshift (‘z’) will be:

z_final = z_initial + zDebias*(1+z_initial)

This is obviously a fudge, so use with caution (only used for some surveys - see bin/zCluster).

extractArraysFromGalaxyCatalog(catalog, RADeg, decDeg): For convenience: pulls out arrays needed for NGal measurement from galaxy catalog. Needs RADeg, decDeg to calculate angular distances from cluster (or random) position.

getPixelAreaDeg2Map(mapData, wcs): Returns a map of pixel area in square degrees.

makeBlankMap(RADeg, decDeg, sizePix, sizeDeg)

Makes a square blank map with a WCS.

Returns:

mapData (2d array)
wcs (astWCS.WCS object)

makeDegreesDistanceMap(degreesMap, wcs, RADeg, decDeg, maxDistDegrees)

Fills (in place) the 2d array degreesMap with distance in degrees from the given position, out to some user-specified maximum distance.

Parameters:

degreesMap (np.ndarray) – Map (2d array) that will be filled with angular distance from the given coordinates. Probably you should feed in an array set to some extreme initial value (e.g., 1e6 everywhere) to make it easy to filter for pixels near the object coords afterwards.
wcs (astWCS.WCS) – WCS corresponding to degreesMap.
RADeg (float) – RA in decimal degrees of position of interest (e.g., object location).
decDeg (float) – Declination in decimal degrees of position of interest (e.g., object location).
maxDistDegrees – The maximum radius out to which distance will be calculated.

Returns:

A map (2d array) of distance in degrees from the given position, (min x, max x) pixel coords corresponding to maxDistDegrees box, (min y, max y) pixel coords corresponding to maxDistDegrees box

Note

This routine measures the pixel scale local to the given position, then assumes that it does not change. So, this routine may only be accurate close to the given position, depending upon the WCS projection used.

makeDensityMap(RADeg, decDeg, catalog, z, dz=0.1, rMaxMpc=1.5, sizeMpc=8.0, MpcPerPix=0.1, gaussSmoothPix=2, outFITSFileName=None, outPlotFileName=None)

Makes a projected density map within +/- dz of the given redshift, smoothed using a Gaussian kernel, then calculates the centroid location, centroid shift (with respect to the original position), and an asymmetry statistic.

Parameters:

RADeg (float) – RA coordinate (decimal degrees) of the center of the output map.
decDeg (float) – dec coordinate (decimal degrees) of the center of the output map.
z (float) – Central redshift at which the projected density will be calculated.
dz (float, optional) – Sets the integration range z +/- dz over which the projected density is calculated.
rMaxMpc (float, optional) – The maximum radial distance in Mpc (from RADeg, decDeg) in which the centroid search is performed.
sizeMpc (float, optional) – The size of the density map (which is square) in projected Mpc.
MpcPerPix (float, optional) – The pixel size, in projected Mpc, for the output density map.
gaussSmoothPix (int, optional) – The size of the Gaussian smoothing kernel applied to the output projected density map, in pixels.
outFITSFileName (str, optional) – If given, write the density map as a FITS file to the given location.
makePlot (str, optional) – If given, write a plot of the density map to the given location (the file format is determined by the extension, and supported formats depend on the matplotlib backend used).

Returns:

‘map’: the output projected density map (2d array)
’wcs’: the output WCS
’cRADeg’: the RA of the centroid (peak) in the density map
’cDecDeg’: the dec of the centroid (peak) in the density map
’offsetArcmin’: size of the offset of the centroid (arcmin) from the original RA, dec
coords
’offsetMpc’: size of the offset of the centroid (projected Mpc) from the original RA,
dec coordinates
’CS’: centroid shift parameter (Mpc)
’A’: asymmetry parameter

Return type:

A dictionary with keys

makeWeightedNz(RADeg, decDeg, catalog, zPriorMax, weightsType, minDistanceMpc=0.0, maxDistanceMpc=1.0, applySanityCheckRadius=True, sanityCheckRadiusArcmin=1.0, areaMask=None, wcs=None)

Make a N(z) distribution in the direction of the postion (usually of a cluster) given by RADeg, decDeg. This is constructed from the p(z) distributions of all galaxies in the catalog, with radial weights applied as per weightsType. So, for ‘flat1Mpc’, the radial weight is 1 if within a projected distance of 1 Mpc of RADeg, decDeg, and 0 otherwise.

zPriorMax can be used to reign in any spuriously high redshifts given our prior knowledge of the depth of a given photometric survey. However, this is now largely redundant as the mag-based prior does most of the work (see PhotoRedshiftEngine.py).

NOTE: minDistanceMpc only applies to ‘flat’ weightsType (for local background estimate)

PhotoRedshiftEngine

This module contains a class for estimating galaxy photometric redshifts using a template fitting method.

class PhotoRedshiftEngine(absMagCut, passbandSet='SDSS+Ks', zMin=0.01, zMax=3.0, zStep=0.01, ZPError=0.0, ZPOffsets=None, templatesDir=None, EBMinusVList=[0.0], emLinesScaleList=[0.0])

A class that calculates galaxy photo-zs, adding photo-z info to a catalog (list of dictionaries) in place.

Sets up the stuff we would otherwise calculate every time, i.e., the templates.

calcPhotoRedshifts(galaxyCatalog, calcMLRedshiftAndOdds=False, returnPZ=True, storeBestFitSEDModels=False)

Calculates photometric redshifts and adds to the galaxy catalog in place.

NOTE: since normally we’re normally only interested in p(z), this only returns the maximum likelihood z and BPZ-style odds parameter if calcMLRedshiftAndOdds = True.

calcZeroPointOffsets(galaxyCatalog, zSpecColumn='z_spec'): If the galaxyCatalog contains zSpecColumn, fit SEDs at given spec-zs to determine zero point offsets. After this is done, they will automatically be applied by calcPhotoRedshifts.

calculateMLRedshiftAndOdds(pz, dzOdds=0.2, method='max')

Calculates maximum likelihood z and BPZ/EAZY style odds for given pz, zArray

Method == ‘max’ finds z based on max peak in pz Method == ‘odds’ finds z based on z at which odds is maximised

estimateStellarMasses(galaxyCatalog, stellarMassModelDir, z=None)

Given a directory containing BC03-format stellar population models, estimate the stellar mass of galaxies in the given catalog.

Parameters:

galaxyCatalog (list) – Galaxy catalog as a list of dictionaries, i.e., in the format returned by self.calcPhotoRedshifts().
stellarMassModelDir (str) – Path to a directory containing the stellar population models (BC03 format for now).
z (float, optional) – If given, the redshift will be fixed to this value and applied to all the galaxies in the catalog (this is what you want for galaxy clusters, and is quicker). If None, then the maximum likelihood redshift of each individual galaxy will be used (this will be very slow, but actually isn’t implemented yet…).

Returns:

None [‘log10StellarMass’ key is added in-place to each galaxy in galaxyCatalog]

retrievers

This module contains routines for retrieving galaxy catalogs from various photometric surveys.

ATLASDR4Retriever(RADeg, decDeg, halfBoxSizeDeg=0.3, optionsDict={}): Retrieves VST ATLAS DR4 photometry via ESO.

CFHTLenSRetriever(RADeg, decDeg, halfBoxSizeDeg=0.6, optionsDict={})

Retrieves CFHTLenS photometry, which works differently to other CFHT catalogues.

halfBoxSizeDeg is actually a radius in this case.

NOTE: optionsDict must include ‘maxMagError’ key.

DECaLSDR10Retriever(RADeg, decDeg, halfBoxSizeDeg=0.6, DR=None, optionsDict={}): Retrieves DECaLS DR10 tractor catalogs (if they exist) at the given position. Cuts the catalog to the radius specified by halfBoxSizeDeg.

DECaLSDR8Retriever(RADeg, decDeg, halfBoxSizeDeg=0.6, DR=None, optionsDict={}): Retrieves DECaLS DR8 tractor catalogs (if they exist) at the given position. Cuts the catalog to the radius specified by halfBoxSizeDeg.

DECaLSDR9Retriever(RADeg, decDeg, halfBoxSizeDeg=0.6, DR=None, optionsDict={}): Retrieves DECaLS DR9 tractor catalogs (if they exist) at the given position. Cuts the catalog to the radius specified by halfBoxSizeDeg.

DECaLSRetriever(RADeg, decDeg, halfBoxSizeDeg=0.6, DR=None, optionsDict={}): Retrieves DECaLS DRx tractor catalogs (if they exist) at the given position. Cuts the catalog to the radius specified by halfBoxSizeDeg.

DELVEDR2Retriever(RADeg, decDeg, halfBoxSizeDeg=0.6, DR=None, optionsDict={}): DELVE DR2 retriever, using NOAO datalab.

DESDR1Retriever(RADeg, decDeg, halfBoxSizeDeg=0.6, optionsDict={}): Retrieves DES DR1 photometry at the given position. This assumes you have easyaccess installed (https://pypi.python.org/pypi/easyaccess/1.0.7) and have registered for a login to access the DES Oracle database

DESDR2Retriever(RADeg, decDeg, halfBoxSizeDeg=0.6, optionsDict={}): Retrieves DES DR2 photometry at the given position. This assumes you have easyaccess installed (https://pypi.python.org/pypi/easyaccess/1.0.7) and have registered for a login to access the DES Oracle database

DESRetriever(RADeg, decDeg, DR='DR1', halfBoxSizeDeg=0.6, optionsDict={})

Retrieves DES photometry. Assumes you have easyaccess installed (https://pypi.python.org/pypi/easyaccess/1.0.7) and the necessary login to access either public or proprietary tables in the DES Oracle database.

Use DR = ‘DR1’ or ‘DR2’ to access the public photometry, DR = ‘Y3’ to access the current ‘Gold’ photometry

DESY3Retriever(RADeg, decDeg, halfBoxSizeDeg=0.6, optionsDict={}): Retrieves DES Y3 photometry at the given position. This assumes you have easyaccess installed (https://pypi.python.org/pypi/easyaccess/1.0.7) and access rights for the non-public tables in the DES Oracle database.

DESY3WISERetriever(RADeg, decDeg, halfBoxSizeDeg=0.6, optionsDict={}): Retrieves DES Y3 photometry joined to AllWISE at the given position. This assumes you have easyaccess installed (https://pypi.python.org/pypi/easyaccess/1.0.7) and access rights for the non-public tables in the DES Oracle database.

DL_DECaLSDR10Retriever(RADeg, decDeg, halfBoxSizeDeg=0.6, DR=None, optionsDict={}): DECaLS DR10 retriever, using NOAO datalab.

FITSRetriever(RADeg, decDeg, halfBoxSizeDeg=0.6, optionsDict={})

Parses a FITS catalog made by e.g., soi_makecatalogs.py.

NOTE: No star-galaxy separation is applied in this currently.

Here optionsDict needs to include ‘fileName’ key.

If ‘addSDSS’: True in optionsDict, then we fetch an SDSS catalog at the location, cross match it against the FITS catalog, and add in info for bands we can’t find (e.g., g-band). We don’t add SDSS objects which aren’t detected in the FITS catalog.

KiDSDR4Retriever(RADeg, decDeg, halfBoxSizeDeg=0.3, optionsDict={}): Retrieves KiDS DR4 photometry (which includes VIKING IR bands).

PS1Retriever(RADeg, decDeg, halfBoxSizeDeg=0.3, optionsDict={}): Retrieves PS1 photometry at the given position.

S82Retriever(RADeg, decDeg, halfBoxSizeDeg=0.33666666666666667, optionsDict={}): Retrieves SDSS Stripe 82 photometry at the given position.

SDSSDR10Retriever(RADeg, decDeg, halfBoxSizeDeg=0.15, optionsDict={}): Retrieves SDSS DR10 photometry at the given position.

SDSSDR12Retriever(RADeg, decDeg, halfBoxSizeDeg=0.6, optionsDict={}): Retrieves SDSS DR12 photometry at the given position.

SDSSDR7Retriever(RADeg, decDeg, halfBoxSizeDeg=0.15, optionsDict={}): Retrieves SDSS DR7 main photometry at the given position.

SDSSDR8Retriever(RADeg, decDeg, halfBoxSizeDeg=0.15, optionsDict={}): Retrieves SDSS DR8 photometry at the given position.

SDSSRetriever(RADeg, decDeg, halfBoxSizeDeg=0.3, DR=7, optionsDict={}): Retrieves SDSS main photometry at the given position.

addExtraPhoto(RADeg, decDeg, catalog, halfBoxSizeDeg=0.15, optionsDict={}): Add extra photometry from another retriever, as specified in optionsDict using the ‘extraRetriever’ and ‘extraOptions’ keys. Used to supplement e.g. single band (Ks) catalogs from APO.

addWISEPhotometry(RADeg, decDeg, catalog, halfBoxSizeDeg=0.6): This is an option that can be enabled in other retriever functions by adding ‘addWISE’: True in optionsDict. For this to work, the passbandSet used by PhotoRedshiftEngine must also have the WISE bands defined. We can probably tidy this up a bit…

checkMagErrors(photDict, maxMagError, minBands=3, bands=['u', 'g', 'r', 'i', 'z'])

Checks if the magnitudes in photDict are less than maxMagError, for a minimum number of minBands photometric bands.

Returns True if the photDict passes the test, False if not

fixcolnames(tab)

Fix column names returned by the casjobs query. Needed by PS1Retriever.

Parameters:

(astropy.table.Table) (tab) –
modified (Returns reference to original table with column names) –

getEBMinusV(RADeg, decDeg, optionsDict={}): Get E(B-V) due to Galactic dust from Schlegel maps, using IRSA web service

getRetriever(database, maxMagError=0.2)

Given the name of a survey database, return a function that can retrieve a galaxy catalog, and an associated options dictionary.

Parameters:

database (str) – Name of the survey database - relatively well-tested options are: SDSSDR12, S82, DESY3, DESDR1, KiDSDR4, DECaLS (and similar variants).
maxMagError (float, optional) – Objects with magnitude uncertainties greater than this value will be cut from retrieved catalogs, subject to the minimum number of bands used by checkMagErrors().

Returns:

Retriever function, a dictionary containing additional parameters that the function needs to be given, and the name of the PhotoRedshiftEngine passband set to use.

Returns None if there is no match to database.

makeCacheDir(): Makes the cache directory where catalogs (and sometimes other survey-specific data) are stored.

parseFITSPhotoTable(tab, fieldIDKey=None, optionsDict={})

Parse .fits table into catalog list of dictionaries format. Extinction correction due to Galactic dust will be applied, using IRSA web service. If fieldIDKey == None (the default), this is done at the mean RA, dec coords. Otherwise, sources are grouped by fieldID and the mean correction for each field is applied.

Returns catalog (list of dictionaries)