The DES Module

The galsim.des module contains some functionality specific developed for the use of GalSim in simulations of the Dark Energy Survey. However, both PSFEx and MEDS files are used for other surveys besides DES, so both DES_PSFEx and MEDSBuilder may be relevant to users outside of DES.

Note

To use this module, you must separately import galsim.des. These functions are not automatically imported when you import galsim.

DES PSF models

class galsim.des.DES_PSFEx(file_name, image_file_name=None, wcs=None, dir=None)[source]

Bases: object

Class that handles DES files describing interpolated principal component images of the PSF. These are usually stored as *_psfcat.psf files.

PSFEx is software written by Emmanuel Bertin. If you want more detail about PSFEx, please check out the web site:

http://www.astromatic.net/software/psfex

It builds PSF objects from images of stars in a given exposure, finds a reasonable basis set to describe those images, and then fits the coefficient of these bases as a function of the (x,y) position on the image.

Note that while the interpolation is done in image coordinates, GalSim usually deals with object profiles in world coordinates. However, PSFEx does not consider the WCS of the image when building its bases. The bases are built in image coordinates. So there are two options to get GalSim to handle this difference.

Ignore the WCS of the original image. In this case, the *.psf files have all the information you need:
```
>>> des_psfex = galsim.des.DES_PSFEx(fitpsf_file_name)
>>> image_pos = galsim.PositionD(image_x, image_y)    # position in pixels on the image
>>>                                                   # NOT in arcsec on the sky!
>>> psf = des_psfex.getPSF(image_pos)      # profile is in image coordinates
```
The psf profile that is returned will be in image coordinates. Therefore, it should be drawn onto an image with no wcs. (Or equivalently, one with scale = 1.) If you want to use this to convolve a galaxy profile, you would want to either project the galaxy (typically constructed in world coordinates) to the correct image coordinates or project the PSF up into world coordinates.
Build the PSF in world coordinates directly. The DES_PSFEx constructor can take an extra argument, either image_file_name or wcs, to tell GalSim what WCS to use for the coversion between image and world coordinates. The former option is the name of the file from which to read the WCS, which will often be more convenient, but you can also just pass in a WCS object directly.
```
>>> des_psfex = galsim.des.DES_PSFEx(fitpsf_file_name, image_file_name)
>>> image_pos = galsim.PositionD(image_x, image_y)    # position in pixels on the image
>>>                                                   # NOT in arcsec on the sky!
>>> psf = des_psfex.getPSF(image_pos)      # profile is in world coordinates
```
This time the psf profile that is returned will already be in world coordinates as GalSim normally expects, so you can use it in the normal ways. If you want to draw it (or a convolved object) onto an image with the original WCS at that location, you can use des_psfex.getLocalWCS(image_pos) for the local wcs at the location of the PSF.

Note that the returned psf here already includes the pixel. This is what is sometimes called an “effective PSF”. Thus, you should not convolve by the pixel profile again (nor integrate over the pixel). This would effectively include the pixel twice!

In GalSim, you should always pass method='no_pixel' when drawing images of objects convolved with PSFs produced with this class. Other drawing methods, such as photon shooting (method='phot') or an FFT (method='fft'), will result in convolving the pixel twice.

Parameters:

file_name – The file name to be read in, or a pyfits HDU in which case it is used directly instead of being opened.
image_file_name – The name of the fits file of the original image (needed for the WCS information in the header). If unavailable, you may omit this (or use None), but then the returned profiles will be in image coordinates, not world coordinates. [default: None]
wcs – Optional way to provide the WCS if you already have it loaded from the image file. [default: None]
dir – Optionally a directory name can be provided if the file_name does not already include it. (The image file is assumed to be in the same directory.) [default: None].

getLocalWCS(image_pos)[source]

If the original image was provided to the constructor, this will return the local WCS at a given location in that original image. If not, this will return None.

Parameter:: image_pos (Position): The position in pixels in the image.

Returns:: A LocalWCS or None

getPSF(image_pos, gsparams=None)[source]

Returns the PSF at position image_pos.

Parameters:

image_pos – The position in image coordinates at which to build the PSF.
gsparams – A GSParams instance to pass to the constructed GSObject. [defualt: None]

Returns:

the PSF as a GSObject

getPSFArray(image_pos)[source]: Returns the PSF image as a numpy array at position image_pos in image coordinates.

class galsim.des.DES_Shapelet(file_name, dir=None)[source]

Bases: object

Class that handles DES files describing interpolated polar shapelet decompositions. These are stored as *_fitpsf.fits files. They are not used in DES anymore, so this class is at best of historical interest

The shapelet PSFs measure a shapelet decomposition of each star and interpolate the shapelet coefficients over the image positions.

Unlike PSFEx, these PSF models are built directly in world coordinates. The shapelets know about the WCS, so they are able to fit the shapelet model directly in terms of arcsec. Thus, the getPSF function always returns a profile in world coordinates.

Typical usage:

>>> des_shapelet = galsim.des.DES_Shapelet(fitpsf_file_name)
>>> image_pos = galsim.PositionD(image_x, image_y)    # position in pixels on the image
>>>                                                   # NOT in arcsec on the sky!
>>> psf = des_shapelet.getPSF(image_pos)   # profile is in world coordinates

Note that the returned psf here already includes the pixel. This is what is sometimes called an “effective PSF”. Thus, you should not convolve by the pixel profile again (nor integrate over the pixel). This would effectively include the pixel twice!

This class will only interpolate within the defining bounds. It won’t extrapolate beyond the bounding box of where the stars defined the interpolation. If you try to use it with an invalid position, it will throw an IndexError. You can check whether a position is valid with

>>> if des_shapelet.bounds.includes(pos):
>>>     psf = des_shapelet.getPSF(pos)
>>> else:
>>>     [...skip this object...]

Parameters:

file_name – The name of the file to be read in.
dir – Optionally a directory name can be provided if the file names do not already include it. [default: None]

getB(pos)[source]: Get the B vector as a numpy array at position pos

getPSF(image_pos, gsparams=None)[source]

Returns the PSF at position image_pos

Parameters:

image_pos – The position in pixel units for which to build the PSF.
gsparams – An optional GSParams instance to pass to the constructed GSObject. [default: None]

Returns:

the PSF as a galsim.Shapelet instance

read_fits()[source]: Read in a DES_Shapelet stored in FITS file.

Writing to MEDS Files

This module defines the MultiExposureObject class for representing multiple exposure data for a single object. The WriteMEDS function can be used to write a list of MultiExposureObject instances to a single MEDS file.

Importing this module also adds these data structures to the config framework, so that MEDS file output can subsequently be simulated directly using a config file.

class galsim.des.MultiExposureObject(images, weight=None, badpix=None, seg=None, psf=None, wcs=None, id=0, cutout_row=None, cutout_col=None)[source]

A class containing exposures for single object, along with other information.

The MultiExposureObject class represents multiple exposure data for a single object for the purpose of writing the images to a MEDS file.

The WriteMEDS function can be used to write a list of MultiExposureObjects to a MEDS file.

Parameters:

images – List of images of the object.
weight – List of weight images. [default: None]
badpix – List of bad pixel masks. [default: None]
seg – List of segmentation maps. [default: None]
psf – List of psf images. [default: None]
wcs – List of WCS transformations. [default: None]
id – Galaxy id. [default: 0]

Attributes:

self.images – List of images of the object.
self.weight – List of weight maps.
self.seg – List of segmentation maps.
self.psf – List of psf images.
self.wcs – List of WCS transformations.
self.n_cutouts – Number of exposures.
self.box_size – Size of each exposure image.

class galsim.des.MEDSBuilder[source]

Bases: OutputBuilder

This class lets you use the MultiExposureObject very simply as a special output type when using config processing.

It requires the use of galsim.des in the config files modules section.

buildImages(config, base, file_num, image_num, obj_num, ignore, logger)[source]

Build a meds file as specified in config.

Parameters:

config – The configuration dict for the output field.
base – The base configuration dict.
file_num – The current file_num.
image_num – The current image_num.
obj_num – The current obj_num.
ignore – A list of parameters that are allowed to be in config that we can ignore here.
logger – If given, a logger object to log progress.

Returns:

A list of MultiExposureObjects.

getNImages(config, base, file_num, logger=None)[source]

Returns the number of images to be built for a given file_num.

In the base class, we only build a single image, so it returns 1.

Parameters:

config – The configuration dict for the output field.
base – The base configuration dict.
file_num – The current file number.
logger – If given, a logger object to log progress.

Returns:

the number of images to build.

writeFile(data, file_name, config, base, logger)[source]

Write the data to a file. In this case a MEDS file.

Parameters:

data – The data to write. Here, this is a list of MultiExposureObject.
file_name – The file_name to write to.
config – The configuration dict for the output field.
base – The base configuration dict.
logger – If given, a logger object to log progress.

class galsim.des.OffsetBuilder[source]

Bases: ExtraOutputBuilder

This “extra” output builder saves the stamp offset values for later use.

It is used as a meds_get_offset field in the output section.

finalize(config, base, main_data, logger)[source]

Perform any final processing at the end of all the image processing.

This function will be called after all images have been built.

It returns some sort of final version of the object. In the base class, it just returns self.data, but depending on the meaning of the output object, something else might be more appropriate.

Parameters:

config – The configuration field for this output object.
base – The base configuration dict.
main_data – The main file data in case it is needed.
logger – If given, a logger object to log progress. [default: None]

Returns:

The final version of the object.

processStamp(obj_num, config, base, logger)[source]

Perform any necessary processing at the end of each stamp construction.

This function will be called after each stamp is built, but before the noise is added, so the existing stamp image has the true surface brightness profile (unless photon shooting was used, in which case there will necessarily be noise from that process).

Remember, these stamps may be processed out of order. Saving data to the scratch dict is safe, even if multiprocessing is being used.

Parameters:

obj_num – The object number
config – The configuration field for this output object.
base – The base configuration dict.
logger – If given, a logger object to log progress. [default: None]

galsim.des.WriteMEDS(obj_list, file_name, clobber=True)[source]

Writes a MEDS file from a list of MultiExposureObject instances.

Parameters:

obj_list – List of MultiExposureObject instances
file_name – Name of meds file to be written
clobber – Setting clobber=True when file_name is given will silently overwrite existing files. [default True]