FITS I/O

Note

The FITS functionality in JAX-GalSim is just a light wrapper around the GalSim FITS functionality that attempts to convert Image objects.

jax_galsim.fits.read(*args, **kwargs)

Construct an Image from a FITS file or HDUList.

LAX-backend implementation of galsim.fits.read().

Parameters:

• file_name – The name of the file to read in. [Either file_name or hdu_list is required.]

• dir – Optionally a directory name can be provided if file_name does not already include it. [default: None]

• hdu_list – Either an astropy.io.fits.HDUList, astropy.io.fits.PrimaryHDU, or astropy.io.fits..ImageHDU. In the former case, the hdu in the list will be selected. In the latter two cases, the hdu parameter is ignored. [Either file_name or hdu_list is required.]

• hdu – The number of the HDU to return. [default: None, which means to return either the primary or first extension as appropriate for the given compression. (e.g. for ‘rice’, the first extension is the one you normally want.)]

• compression – Which decompression scheme to use (if any). Options are: - None or ‘none’ = no decompression - ‘rice’ = use rice decompression in tiles - ‘gzip’ = use gzip to decompress the full file - ‘bzip2’ = use bzip2 to decompress the full file - ‘gzip_tile’ = use gzip decompression in tiles - ‘hcompress’ = use hcompress decompression in tiles - ‘plio’ = use plio decompression in tiles - ‘auto’ = determine the decompression from the extension of the file name (requires file_name to be given). - ‘.fz’ => ‘rice’ - ‘.gz’ => ‘gzip’ - ‘.bz2’ => ‘bzip2’ - otherwise None [default: ‘auto’]

• read_header – Whether to read the header and store it as image.header.[default: False]

• suppress_warning – Whether to suppress a warning that the WCS could not be read from the FITS header, so the WCS defaulted to either a PixelScale or AffineTransform. [default: True]

Original GalSim Documentation

The normal usage for this function is to read a fits file and return the image contained therein, automatically decompressing it if necessary. However, you may also pass it an HDUList, in which case it will select the indicated hdu (with the hdu parameter) from that.

Not all FITS pixel types are supported – only short, int, unsigned short, unsigned int, float, and double.

If the FITS header has keywords that start with GS_, these will be used to initialize the bounding box and WCS. If these are absent, the code will try to read whatever WCS is given in the FITS header. cf. galsim.wcs.readFromFitsHeader. The default bounding box will have (xmin,ymin) at (1,1). The default WCS, if there is no WCS information in the FITS file, will be PixelScale(1.0).

This function is called as im = galsim.fits.read(...)

Returns:

the image as an Image instance.

jax_galsim.fits.readMulti(*args, **kwargs)

Construct a list of Image instances from a FITS file or HDUList.

LAX-backend implementation of galsim.fits.readMulti().

Parameters:

• file_name – The name of the file to read in. [Either file_name or hdu_list is required.]

• dir – Optionally a directory name can be provided if file_name does not already include it. [default: None]

• hdu_list – An astropy.io.fits.HDUList from which to read the images. [Either file_name or hdu_list is required.]

• compression – Which decompression scheme to use (if any). Options are: - None or ‘none’ = no decompression - ‘rice’ = use rice decompression in tiles - ‘gzip’ = use gzip to decompress the full file - ‘bzip2’ = use bzip2 to decompress the full file - ‘gzip_tile’ = use gzip decompression in tiles - ‘hcompress’ = use hcompress decompression in tiles - ‘plio’ = use plio decompression in tiles - ‘auto’ = determine the decompression from the extension of the file name (requires file_name to be given). - ‘.fz’ => ‘rice’ - ‘.gz’ => ‘gzip’ - ‘.bz2’ => ‘bzip2’ - otherwise None [default: ‘auto’]

• read_headers – Whether to read the headers and store them as image.header.[default: False]

• suppress_warning – Whether to suppress a warning that the WCS could not be read from the FITS header, so the WCS defaulted to either a PixelScale or AffineTransform. [default: True]

Original GalSim Documentation

The normal usage for this function is to read a fits file and return a list of all the images contained therein, automatically decompressing them if necessary. However, you may also pass it an HDUList, in which case it will build the images from these directly.

Not all FITS pixel types are supported – only short, int, unsigned short, unsigned int, float, and double.

If the FITS header has keywords that start with GS_, these will be used to initialize the bounding box and WCS. If these are absent, the code will try to read whatever WCS is given in the FITS header. cf. galsim.wcs.readFromFitsHeader. The default bounding box will have (xmin,ymin) at (1,1). The default WCS, if there is no WCS information in the FITS file, will be PixelScale(1.0).

This function is called as im = galsim.fits.readMulti(...)

Note

This function along with writeMulti can be used to effect the equivalent of a simple version of fpack or funpack. To Rice compress a fits file, you can call:

fname = 'some_image_file.fits'
galsim.fits.writeMulti(galsim.fits.readMulti(fname, read_headers=True), fname+'.fz')

To uncompress:

fname = 'some_image_file.fits.fz'
galsim.fits.writeMulti(galsim.fits.readMulti(fname, read_headers=True), fname[:-3])

Returns:

a Python list of Image instances.

jax_galsim.fits.readCube(*args, **kwargs)

Construct a Python list of Image instances from a FITS data cube.

LAX-backend implementation of galsim.fits.readCube().

Parameters:

• file_name – The name of the file to read in. [Either file_name or hdu_list is required.]

• dir – Optionally a directory name can be provided if file_name does not already include it. [default: None]

• hdu_list – Either an astropy.io.fits.HDUList, an astropy.io.fits.PrimaryHDU, or astropy.io.fits.ImageHDU. In the former case, the hdu in the list will be selected. In the latter two cases, the hdu parameter is ignored. [Either file_name or hdu_list is required.]

• hdu – The number of the HDU to return. [default: None, which means to return either the primary or first extension as appropriate for the given compression. (e.g. for rice, the first extension is the one you normally want.)]

• compression – Which decompression scheme to use (if any). Options are: - None or ‘none’ = no decompression - ‘rice’ = use rice decompression in tiles - ‘gzip’ = use gzip to decompress the full file - ‘bzip2’ = use bzip2 to decompress the full file - ‘gzip_tile’ = use gzip decompression in tiles - ‘hcompress’ = use hcompress decompression in tiles - ‘plio’ = use plio decompression in tiles - ‘auto’ = determine the decompression from the extension of the file name (requires file_name to be given). - ‘.fz’ => ‘rice’ - ‘.gz’ => ‘gzip’ - ‘.bz2’ => ‘bzip2’ - otherwise None [default: ‘auto’]

• suppress_warning – Whether to suppress a warning that the WCS could not be read from the FITS header, so the WCS defaulted to either a PixelScale or AffineTransform. [default: True]

Original GalSim Documentation

Not all FITS pixel types are supported – only short, int, unsigned short, unsigned int, float, and double.

If the FITS header has keywords that start with GS_, these will be used to initialize the bounding box and WCS. If these are absent, the code will try to read whatever WCS is given in the FITS header. cf. galsim.wcs.readFromFitsHeader. The default bounding box will have (xmin,ymin) at (1,1). The default WCS, if there is no WCS information in the FITS file, will be PixelScale(1.0).

This function is called as image_list = galsim.fits.readCube(...)

Returns:

a Python list of Image instances.

jax_galsim.fits.write(*args, **kwargs)

Write a single image to a FITS file.

LAX-backend implementation of galsim.fits.write().

Parameters:

• image – The Image to write to file. Per the description of this method, it may be given explicitly via galsim.fits.write(image, ...) or the method may be called directly as an image method, image.write(...). Note that if the image has a ‘header’ attribute containing a FitsHeader, then the FitsHeader is written to the header in the PrimaryHDU, followed by the WCS as usual.

• file_name – The name of the file to write to. [Either file_name or hdu_list is required.]

• dir – Optionally a directory name can be provided if file_name does not already include it. [default: None]

• hdu_list – An astropy.io.fits.HDUList. If this is provided instead of file_name, then the Image is appended to the end of the HDUList as a new HDU. In that case, the user is responsible for calling either hdu_list.writeto(...) or galsim.fits.writeFile(...) afterwards. [Either file_name or hdu_list is required.]

• clobber – Setting clobber=True will silently overwrite existing files. [default: True]

• compression – Which compression scheme to use (if any). Options are: - None or ‘none’ = no compression - ‘rice’ = use rice compression in tiles (preserves header readability) - ‘gzip’ = use gzip to compress the full file - ‘bzip2’ = use bzip2 to compress the full file - ‘gzip_tile’ = use gzip in tiles (preserves header readability) - ‘hcompress’ = use hcompress in tiles (only valid for 2-d images) - ‘plio’ = use plio compression in tiles (only valid for pos integer data) - ‘auto’ = determine the compression from the extension of the file name (requires file_name to be given): - ‘.fz’ => ‘rice’ - ‘.gz’ => ‘gzip’ - ‘.bz2’ => ‘bzip2’ - otherwise None [default: ‘auto’]

Original GalSim Documentation

Write the Image instance image to a FITS file, with details depending on the arguments. This function can be called directly as galsim.fits.write(image, ...), with the image as the first argument, or as an Image method: image.write(...).

jax_galsim.fits.writeMulti(*args, **kwargs)

Write a Python list of images to a multi-extension FITS file.

LAX-backend implementation of galsim.fits.writeMulti().

Parameters:

• image_list – A Python list of Image instances. (For convenience, some items in this list may be HDUs already. Any Image will be converted into an astropy.io.fits.HDU.)

• file_name – The name of the file to write to. [Either file_name or hdu_list is required.]

• dir – Optionally a directory name can be provided if file_name does not already include it. [default: None]

• hdu_list – An astropy.io.fits.HDUList. If this is provided instead of file_name, then the Image is appended to the end of the HDUList as a new HDU. In that case, the user is responsible for calling either hdu_list.writeto(...) or galsim.fits.writeFile(...) afterwards. [Either file_name or hdu_list is required.]

• clobber – Setting clobber=True will silently overwrite existing files. [default: True]

• compression – Which compression scheme to use (if any). Options are: - None or ‘none’ = no compression - ‘rice’ = use rice compression in tiles (preserves header readability) - ‘gzip’ = use gzip to compress the full file - ‘bzip2’ = use bzip2 to compress the full file - ‘gzip_tile’ = use gzip in tiles (preserves header readability) - ‘hcompress’ = use hcompress in tiles (only valid for 2-d images) - ‘plio’ = use plio compression in tiles (only valid for pos integer data) - ‘auto’ = determine the compression from the extension of the file name (requires file_name to be given): - ‘.fz’ => ‘rice’ - ‘.gz’ => ‘gzip’ - ‘.bz2’ => ‘bzip2’ - otherwise None [default: ‘auto’]

Original GalSim Documentation

The details of how the images are written to file depends on the arguments.

Note

This function along with readMulti can be used to effect the equivalent of a simple version of fpack or funpack. To Rice compress a fits file, you can call:

fname = 'some_image_file.fits'
galsim.fits.writeMulti(galsim.fits.readMulti(fname, read_headers=True), fname+'.fz')

To uncompress:

fname = 'some_image_file.fits.fz'
galsim.fits.writeMulti(galsim.fits.readMulti(fname, read_headers=True), fname[:-3])

jax_galsim.fits.writeCube(*args, **kwargs)

Write a Python list of images to a FITS file as a data cube.

LAX-backend implementation of galsim.fits.writeCube().

Parameters:

• image_list – The image_list can also be either an array of NumPy arrays or a 3d NumPy array, in which case this is written to the fits file directly. In the former case, no explicit check is made that the NumPy arrays are all the same shape, but a NumPy exception will be raised which we let pass upstream unmolested.

• file_name – The name of the file to write to. [Either file_name or hdu_list is required.]

• dir – Optionally a directory name can be provided if file_name does not already include it. [default: None]

• hdu_list – An astropy.io.fits.HDUList. If this is provided instead of file_name, then the cube is appended to the end of the HDUList as a new HDU. In that case, the user is responsible for calling either hdu_list.writeto(...) or galsim.fits.writeFile(...) afterwards. [Either file_name or hdu_list is required.]

• clobber – Setting clobber=True will silently overwrite existing files. [default: True]

• compression – Which compression scheme to use (if any). Options are: - None or ‘none’ = no compression - ‘rice’ = use rice compression in tiles (preserves header readability) - ‘gzip’ = use gzip to compress the full file - ‘bzip2’ = use bzip2 to compress the full file - ‘gzip_tile’ = use gzip in tiles (preserves header readability) - ‘hcompress’ = use hcompress in tiles (only valid for 2-d images) - ‘plio’ = use plio compression in tiles (only valid for pos integer data) - ‘auto’ = determine the compression from the extension of the file name (requires file_name to be given): - ‘.fz’ => ‘rice’ - ‘.gz’ => ‘gzip’ - ‘.bz2’ => ‘bzip2’ - otherwise None [default: ‘auto’]

Original GalSim Documentation

The details of how the images are written to file depends on the arguments. Unlike for writeMulti, when writing a data cube it is necessary that each Image in image_list has the same size (nx, ny). No check is made to confirm that all images have the same origin and pixel scale (or WCS).

In fact, the WCS of the first image is the one that gets put into the FITS header (since only one WCS can be put into a FITS header). Thus, if the images have different WCS functions, only the first one will be rendered correctly by plotting programs such as ds9. The FITS standard does not support any way to have the various images in a data cube to have different WCS solutions.