Image

class snappl.image.Image(full_filepath=None, filepath=None, base_path=None, base_dir=None, path=None, no_base_path=False, id=None, provenance_id=None, width=None, height=None, observation_id=None, sca=None, ra=None, dec=None, ra_corner_00=None, ra_corner_01=None, ra_corner_10=None, ra_corner_11=None, dec_corner_00=None, dec_corner_01=None, dec_corner_10=None, dec_corner_11=None, band=None, mjd=None, position_angle=None, exptime=None, sky_level=None, zeropoint=None, format=-1, is_superclass=False, **kwargs)

Bases: PathedObject

Encapsulates a single 2d image.

Properties inclue the following. Some of these properties may not be defined for some subclasses of Image.

If possible, avoid using all “path” properties, and instead use the other properties to get access to image data. Note that “noisepath” and “flagspath” are not defined for all Image subclasses, and will only be defined sometimes for some subclasses (depending on how data is stored).

• filepathpathlib.Path ; path relative to the base path of the image file. This may just

  have the image data itself, or it may be a base filepath, or it may have everything, depending on the subclass. If you can avoid using this property, do so. Use .data, etc, instead.

• filename : string ; just the name part of filepath (so if filepath is Path(“/foo/bar”), name is “bar”)

• full_filepath : pathlib.Path ; absolute path to file on system. (Same as base_path / filepath.)

• base_path : base path for images; usually will be Config value system.paths.images

• base_dir : synonym for base_path

• pathpathlib.Path; absolute path to the image on disk, sort of, in a complicatd way.

  HERE FOR BACKWARDS COMPATIBILITY ONLY

• name : str; synonym for filename. HERE FOR BACKWARDS COMPATIBILITY ONLY.

• observation_id : str; a unique identifier of the exposure associated with the image

• sca : int (str?); the SCA of this image

• ra: float; the nominal RA at the center of the image in decimal degrees, usu. from the header

• dec: float; the nominal RA at the center of the image in decimal degrees, usu. from the header

• ra_corner_00: float; decimal degrees, ra of pixel (0, 0)

• ra_corner_10: float; decimal degrees, ra of pixel (width-1, 0)

• ra_corner_01: float; decimal degrees, ra of pixel (0, height)

• ra_corner_11: float; decimal degrees, ra of pixel (width-1, height-1)

• dec_corner_00: float; decimal degrees, dec of pixel (0, 0)

• dec_corner_10: float; decimal degrees, dec of pixel (width-1, 0)

• dec_corner_01: float; decimal degrees, dec of pixel (0, height)

• dec_corner_11: float; decimal degrees, dec of pixel (width-1, height-1)

• band : str; filter

• mjd : float; mjd of the start of the image

• position_angle : float; position angle in degrees north of east (CHECK THIS)

• exptime : float; exposure time in seconds

• sky_level : float; an estimate of the sky level (in ADU) if known, None otherwise

• zeropoint : float; convert to AB mag with -2.5*log(adu) + zeropoint, where adu is the units of data

• width : the width (xorizontal size as viewed on ds9) of the image in pixels

• height : the height (y/vertical size as viewed on ds9) of the image in pixels

• image_shape : tuple (height, width) of ints; the image size

• coord_center : tuple of (ra, dec) [I THINK] : center of the image calculated from the WCS

• data : 2d numpy array; the data of this image

• noise : 2d numpy array; a 1σ noise image (if defined)

• flags : 2d numpy array of ints; a pixel flags image (if defined)

IMPORTANT NOTE: because of how numpy arrays are indexed, if you want to get value of the pixel at (ix, iy), you would do image.data[iy, ix].

For all implementations, the properties data, noise, and flags are lazy-loaded. That is, they start empty, but when you access them, an internal buffer gets loaded with that data. This means it can be very easy for lots of memory to get used without your realizing it. There are a couple of solutions. The first, is to call Image.free() when you’re sure you don’t need the data any more, or if you know you want to get rid of it for a while and re-read it from disk later. The second is just not to access the data, noise, and flags properties, instead use Image.get_data(), and manage the data object lifetime yourself.

Instantiate an image. You probably don’t want to do that.

This is an abstract base class that has limited functionality. You probably want to instantiate a subclass if you’re creating a new image.

If you’re trying to pull an image out of the database, then probably what you really want is to use the Image.get_image or Image.find_images class methods.

If you’re working with non-database images and are trying to get a pre-existing image, then probably what you really want to do is call the get_image() method of an ImageCollection object.

Parameters:

• filepath (str or Path, default None) – Path of the image relative to the base path for images, unless less no_base_path is True, in which case this is the full absolute path to the image. For datbase images, you do not want to create a path yourself, but leave it at None and let the class create the filepath. See PathedObject.

• full_filepath (str or Path, default None) – The full path to the image. If you’re using an Image subclass to deal with an image that’s not in the database, you probably want to set this to the absolute path of the image, and you probably want to set no_base_path to True, but you might also set base_path yourself and leave no_base_path at False.

• base_path (str or Path, default None) – Always leave this at None for images associated with database, and the default will be used. Otherwise, the absolute path of the image is base_path / filepath (which should be exactly the same as full_filepath). Must be None if no_base_path is True.

• base_dir (str or Path, default None) – Synonym for base_path

• no_base_path (bool, default False) – For images associated with the database, leave this at False, and make filepath relative to the base path (which may be system dependent). For images that aren’t associated with the database, you can make this True and set filepath to be just the path to the image.

• id (UUID or str that can be converted to UUID, default None) – Database ID of the image. This is only relevant if the image is in the l2image table of the Roman SNPIT internal database (but is required in that case).

• provenance_id (UUID or str that can be converted to UUID, default NOne) – The id of the provenance of the image. Only relevant if the image is in the l2image table of the Roman SNPIT internal database (but is required in that case).

• width (int, default None) – The width and height of the image in pixels if known.

• height (int, default None) – The width and height of the image in pixels if known.

• format (int, default -1) – Index into the table Image._format_def at the bottom of this file.

• observation_id (str)

• sca (int, default None)

• ra (float, default None)

• dec (float, default None)

• (ra|dec)_corner_(00|01|10|11) (float, default None)

• band (str, default None)

• mjd (float, default None)

• position_angle (float, default None)

• exptime (float, default None)

• sky_level (float, default None)

• zeropoint (float, default None) – All of these are the values that should be set for these properties (see Image class docstring). If they are None, how they get populated depends on the image subclass. In many cases, they will be lazy-loaded from the header.

Attributes Summary

band	Band (str)
coord_center	[RA, DEC] (both floats) in degrees at the center of the image
data	The image data, a 2d numpy array.
data_array_list
dec	Float; decimal degrees; nominal dec of the image (probably from the header)
dec_corner_00	Float; decimal degrees; the dec of pixel (x=0, y=0)
dec_corner_01	Float; decimal degrees; the dec of pixel (x=0, y=height-1)
dec_corner_10	Float; decimal degrees; the dec of pixel (x=width-1, y=0)
dec_corner_11	Float; decimal degrees; the dec of pixel (x=width-1, y=height-1)
exptime	Exposure time in seconds.
flags	An integer 2d numpy array of pixel masks / flags TBD
height	height (y-size, first index in numpy arrays) of the image
id	The database image uuid in the l2image table.
image_shape	(ny, nx) pixel size of image.
mjd	MJD of the start of the image (defined how? TAI?)
name
noise	The 1σ pixel noise, a 2d numpy array.
observation_id	Str; unique identifier of one exposure combining all SCAs.
path
position_angle	Position angle in degrees north of east (CHECK THIS)
provenance_id	The database provenance uuid of the image in the l2image table.
ra	Float; decimal degrees; nominal RA of the image (probably from the header)
ra_corner_00	Float; decimal degrees; tha RA of pixel (x=0, y=0)
ra_corner_01	Float; decimal degrees; the RA of pixel (x=0, y=height-1)
ra_corner_10	Float; decimal degrees; the RA of pixel (x=width-1, height=0)
ra_corner_11	Float; decimal degrees; the RA of pixel (x=width-1, y=height=1)
sca	Int; the chip of the image
sky_level	Estimate of the sky level in ADU.
width	the width (x-size, second index in numpy arrays) of the image
zeropoint	Image zeropoint for AB magnitudes.

Methods Summary

ap_phot(coords[, ap_r, method, subpixels, ...])	Do aperture photometry on the image at the specified coordinates.
bulk_save_to_db(images[, dbclient])	Don't use this if you don't really know what you're doing.
find_images([provenance, provenance_tag, ...])	Search the database for images.
fraction_masked()	Fraction of pixels that are masked.
free()	Try to free memory.
get_cutout(ra, dec, xsize[, ysize, mode, ...])	Make a cutout of the image at the given RA and DEC.
get_data([which, always_reload, cache])	Read the data from disk and return one or more 2d numpy arrays of data.
get_image(image_id[, dbclient])	Get an Image from the database based on its image id.
get_ra_dec_cutout(ra, dec, xsize[, ysize, ...])	Creates a new snappl image object that is a cutout of the original image, at a location in pixel-space.
get_wcs([wcsclass])	Get image WCS.
includes_radec(ra, dec)	Check to see if (ra, dec) is included within the image borders.
psf_phot(init_params, psf[, forced_phot, ...])	Do psf photometry.
save([which, path, imagepath, noisepath, ...])	Save the image to its path(s).
save_data([which, path, imagepath, ...])	Same as save; here for backwards compatibility.
save_to_db([dbclient])	Write this image record to the database.

Attributes Documentation

band

Band (str)

coord_center

[RA, DEC] (both floats) in degrees at the center of the image

data

The image data, a 2d numpy array.

data_array_list = ['all', 'data', 'noise', 'flags']

dec

Float; decimal degrees; nominal dec of the image (probably from the header)

dec_corner_00

Float; decimal degrees; the dec of pixel (x=0, y=0)

dec_corner_01

Float; decimal degrees; the dec of pixel (x=0, y=height-1)

dec_corner_10

Float; decimal degrees; the dec of pixel (x=width-1, y=0)

dec_corner_11

Float; decimal degrees; the dec of pixel (x=width-1, y=height-1)

exptime

Exposure time in seconds.

flags

An integer 2d numpy array of pixel masks / flags TBD

TODO : think about what we mean by this. Right now it’s subclass-dependent. But, for usage, we need a way of making this more general. Issue #45.

height

height (y-size, first index in numpy arrays) of the image

Type:

Int

id

The database image uuid in the l2image table.

image_shape

(ny, nx) pixel size of image.

Type:

Tuple

mjd

MJD of the start of the image (defined how? TAI?)

name

noise

The 1σ pixel noise, a 2d numpy array.

observation_id

Str; unique identifier of one exposure combining all SCAs.

path

position_angle

Position angle in degrees north of east (CHECK THIS)

provenance_id

The database provenance uuid of the image in the l2image table.

ra

Float; decimal degrees; nominal RA of the image (probably from the header)

ra_corner_00

Float; decimal degrees; tha RA of pixel (x=0, y=0)

ra_corner_01

Float; decimal degrees; the RA of pixel (x=0, y=height-1)

ra_corner_10

Float; decimal degrees; the RA of pixel (x=width-1, height=0)

ra_corner_11

Float; decimal degrees; the RA of pixel (x=width-1, y=height=1)

sca

Int; the chip of the image

sky_level

Estimate of the sky level in ADU.

width

the width (x-size, second index in numpy arrays) of the image

Type:

Int

zeropoint

Image zeropoint for AB magnitudes.

The zeropoint zp is defined so that an object with total counts c (in whatever units data is in) has AB magnitude m:

m = -2.5 * log(10) + zp

Methods Documentation

ap_phot(coords, ap_r=9, method='subpixel', subpixels=5, bgsize=511, **kwargs)

Do aperture photometry on the image at the specified coordinates.

Does background subtraction using photutils.background.Background2D with box size bgsize.

Parameters:

• coords (astropy.table.Table) – Must have (at least) columns ‘x’ and ‘y’ representing 0-origin pixel coordinates. (CHECK THIS)

• ap_r (float, default 9) – Aperture radius in pixels

• method (str, default 'subpixel') – Passed to the “method” parmeter of photutils.photometry.aperture_photometry

• subpixels (int, default 5) – Number of subpixels to use for the ‘subpixel’ method.

• bgsize (int, default 511) – Box size for photutils Background2D background subtraction. Set to <=0 to not do background subtraction.

• **kwargs (further arguments are passed directly to photutils.photometry.aperture_photometry)

Returns:

results – Results of photutils.aperture.aperture_photometry

Return type:

astropy.table.Table

classmethod bulk_save_to_db(images, dbclient=None)

Don’t use this if you don’t really know what you’re doing.

classmethod find_images(provenance=None, provenance_tag=None, process=None, dbclient=None, **kwargs)

Search the database for images.

Parameters:

• provenance (Provenance or UUID, default None) – Either provenance, or both of provenacne_tag and process, are required. provenacne is the provenance of images to search.

• provenance_tag (string, default None) – The provenance tag to search. Required if provenance is None.

• process (string, deafault None) – The process, used with provenance_tag, to find the provenance. Required if provenacne_tag is not None.

• dbclient (SNPITDBClient, default None) – The connection to the database. If None, a new connection will be created based on what’s it the config.

• filepath (pathlib.Path or str, default None) – Path of the image (relative to the base path for all images) of the image to search for. Usually if you feed it this, you don’t want to feed it nay other parameters.

• mjd_min (float, default None) – Only return images at this mjd or later

• mjd_max (float, default None) – Only return images at this mjd or earlier.

• ra (float, default None) – Only return images that contain this ra

• dec (float, default None) – Only return images that containe this dec

• ra_min (float, default None) – Only return images whose nominal central RA/dec are greater/lesser than the specified limits.

• ra_max (float, default None) – Only return images whose nominal central RA/dec are greater/lesser than the specified limits.

• dec_min (float, default None) – Only return images whose nominal central RA/dec are greater/lesser than the specified limits.

• dec_max (float, default None) – Only return images whose nominal central RA/dec are greater/lesser than the specified limits.

• band (str, default None) – Only include images from this band

• exptime_min (float, default None) – Only include images with at least this exptime in seconds.

• exptime_max (float, default None) – Only include images with at most this exptime in seconds.

• sca (int) – Only include images from this sca.

• order_by (str or list, default None) – By default, the returned images are not sorted in any particular way. Put a keyword here to sort by that value (or by those values). Options include ‘id’, ‘provenance_id’, ‘observation_id’, ‘sca’, ‘ra’, ‘dec’, ‘filepath’, ‘width’, ‘height’, ‘mjd’, ‘exptime’. Not all of these are necessarily useful, and some of them may be null for many objects in the database.

• limit (int, default None) – Only return this many objects at most.

• offset (int, default None) – Useful with limit and order_by ; offset the returned value by this many entries. You can make repeated calls to find_objects to get subsets of objects by passing the same order_by and limit, but different offsets each time, to slowly build up a list.

Returns:

imagelist – Really it will be list of objects of a subclass of snappl.image.Image, but you shouldn’t need to know that.

Return type:

list of snappl.image.Image

fraction_masked()

Fraction of pixels that are masked.

free()

Try to free memory.

get_cutout(ra, dec, xsize, ysize=None, mode='strict', fill_value=nan)

Make a cutout of the image at the given RA and DEC. This implementation assumes that the image WCS is an AstropyWCS.

Parameters:

• x (int) – x pixel coordinate of the center of the cutout.

• y (int) – y pixel coordinate of the center of the cutout.

• xsize (int) – Width of the cutout in pixels.

• ysize (int) – Height of the cutout in pixels. If None, set to xsize.

• mode (str, default 'strict') – “strict” does not allow for partial overlap between the cutout and the original image, “partial” will fill in non-overlapping pixels with fill_value. This is identical to the mode parameter of astropy.nddata.Cutout2D.

• fill_value (float, default np.nan) – Fill value for pixels that are outside the original image when mode=’partial’. This is identical to the fill_value parameter of astropy.nddata.Cutout2D.

Returns:

cutout – A new snappl image object that is a cutout of the original image.

Return type:

snappl.image.Image

get_data(which='all', always_reload=False, cache=False)

Read the data from disk and return one or more 2d numpy arrays of data.

Parameters:

• which (str) –

  What to read:

  ’data’ : just the image data ‘noise’ : just the noise data ‘flags’ : just the flags data ‘all’ : data, noise, and flags

• always_reload (bool, default False) – Whether this is supported depends on the subclass. If this is false, then get_data() has the option of returning the values of self.data, self.noise, and/or self.flags instead of always loading the data. If this is True, then get_data() will ignore the self._data et al. properties.

• cache (bool, default False) – Normally, get_data() just reads the data and does not do any internal caching. If this is True, and the subclass supports it, then the object will cache the loaded data so that future calls with always_reload will not need to reread the data, nor will accessing the data, noise, and flags properties.

The data read not stored in the class, so when the caller goes out of scope, the data will be freed (unless the caller saved it somewhere. This does mean it’s read from disk every time.

Return type:

list (length 1 or 3 ) of 2d numpy arrays

classmethod get_image(image_id, dbclient=None)

Get an Image from the database based on its image id.

Parmameters

image_idUUID or str that can be converted to UUID

The ID of the image to get.

dbclientSNPITDBClient, default None

The connection to the database. If None, a new connection will be created based on what’s it the config.

get_ra_dec_cutout(ra, dec, xsize, ysize=None, mode='strict', fill_value=nan)

Creates a new snappl image object that is a cutout of the original image, at a location in pixel-space.

Parameters:

• ra (float) – RA coordinate of the center of the cutout, in degrees.

• dec (float) – DEC coordinate of the center of the cutout, in degrees.

• xsize (int) – Width of the cutout in pixels.

• ysize (int) – Height of the cutout in pixels. If None, set to xsize.

• mode (str, default 'strict') – “strict” does not allow for partial overlap between the cutout and the original image, “partial” will fill in non-overlapping pixels with fill_value. This is identical to the mode parameter of astropy.nddata.Cutout2D.

• fill_value (float, default np.nan) – Fill value for pixels that are outside the original image when mode=’partial’. This is identical to the fill_value parameter of astropy.nddata.Cutout2D.

Returns:

cutout – A new snappl image object that is a cutout of the original image.

Return type:

snappl.image.Image

get_wcs(wcsclass=None)

Get image WCS. Will be an object of type BaseWCS (from wcs.py) (really likely a subclass).

Parameters:

wcsclass (str or None) – By default, the subclass of BaseWCS you get back will be defined by the Image subclass of the object you call this on. If you want a specific subclass of BaseWCS, you can put the name of that class here. It may not always work; not all types of images are able to return all types of wcses.

Return type:

object of a subclass of snappl.wcs.BaseWCS

includes_radec(ra, dec)

Check to see if (ra, dec) is included within the image borders.

Parameters:

• ra (float) – The coordinate in decimal degrees to check.

• dec (float) – The coordinate in decimal degrees to check.

Return type:

True if (ra, dec) is within the image borders, False otherwise.

psf_phot(init_params, psf, forced_phot=True, fit_shape=(5, 5), bginner=15, bgouter=25, return_resid_image=False)

Do psf photometry.

Does local background subtraction.

Parameters:

• init_params (something) – passed to the init_params of a call to a photutils.psf.PSFPHotometry object.

• psf (snappl.psf.PSF) – The PSF profile to fit to the image.

• forced_phot (bool, default True) – If True, then the x and y positions are fixed. If False, then they will be fit along with the flux.

• fit_shape (tuple of (int, int), default (5, 5)) – Shape of the stamp around the positions in which to do the fit.

• bginner (float, default 15) – Radius of inner boundry of annulus in which to measure background.

• bouter (float, default 25) – Radius of outer boundry of annulus in which to measure background.

• return_resid_image (bool, default False) – If True, returns photutils.psf.PSFPhotometry.make_residual_image along with the photometry results.

Return type:

TODO

save(which='all', path=None, imagepath=None, noisepath=None, flagspath=None, overwrite=False)

Save the image to its path(s).

May have side-effects on the internal data structure (e.g. FITS subclasses modify the internally stored header).

Paramters

whichstr, default “all”

One of ‘data’, ‘noise’, ‘flags’, or ‘all’

imagepathstr, default None

Full Path to write the image to. If not specified, will use use self.full_filepath. Does NOT update any of the path properties of the image. You can leave this at None, and the path that the Image figured out when it was constructed will be used. Usually, that’s what you should do.

pathstr, default None

A synonym for imagepath. Do not use. Here for backwards compatibility.

noisepathstr, default None

Path to write the noise image to, if the noise image is stored as a separate image. (It isn’t always; some subclasses have it as a separate part of the data structure that also has the image.) If None, use an internally stored noisepath. If that is not set, and noisepath is None, and this isn’t a subclass that combines all the data planes into one file, then any noise data array will not be written. Usually, you don’t want to have to specify this.

flagspathstr, default None

Path to write the flags image to, similar to noisepath.

overwritebool, default False

Clobber existing images?

Not implemented for all subclasses.

save_data(which='all', path=None, imagepath=None, noisepath=None, flagspath=None, overwrite=False)

Same as save; here for backwards compatibility. Use save.

save_to_db(dbclient=None)

Write this image record to the database.

USE THIS WITH CARE. All fields must be properly set. In particular, the filepath and provenance_id must both be right for the database. Don’t use this if you don’t really know what you’re doing.

This does not actually write any files; it just writes a database row. Make sure files are where they need to be before calling this.