Stars

The Star class is mostly an implementation detail that users won’t need to know, but for more advanced usage, it may be helpful to use the Star objects directly.

class piff.Star(data, fit)[source]

Information about a “star”, which may be either a real star or an interpolated star at some target location.

The Star object is the fundamental way that Piff keeps track of information connected to a particular observation location. This includes both the input data (postage stamp image, position on the detector, position in the field of view, weight image, etc.) and derived information connected to whatever Model is being used

Stars are not normally constructed directly by the user. They are built by various Piff functions such as:

stars = input_handler.makeStars(logger) stars, wcs = piff.Input.process(config[‘input’]) target_star = piff.Star.makeTarget(x=x, y=y, wcs=wcs, …)

However, a star can be constructed directly from a StarData instance and a StarFit instance. The former keeps track of the data about the star (either as observed or the model at a location) and the latter keeps track of fitted parameters related to fitting the data to a model.

star = piff.Star(star_data, star_fit)

Stars have an immutable design, so any functions that change either the data or the fitted parameters return a new object and don’t change the original. e.g.

star = psf.drawStar(star) star = star.reflux() star = star.addPoisson(gain=gain)

Stars have the following attributes:

star.data The component StarData object star.fit The component StarFit object

and the following read-only properties:

star.image The image of the star star.weight The weight map connected to the image data star.image_pos The position of the star in image coordinates, aka (x,y) star.field_pos The position of the star in field coordinates, aka (u,v) star.x The x position of the star in image coordinates star.y The y position of the star in image coordinates star.u The u position of the star in field coordinates star.v The v position of the star in field coordinates star.chipnum The chip number where this star was observed (or would be observed) star.flux The flux of the object star.center The nominal center of the object (not necessarily the centroid) star.is_reserve Whether the star is reserved from being used to fit the PSF star.hsm HSM measurements for this star as a tuple: (flux, cenu, cenv, sigma, g1, g2, flag)

Parameters

  • data – A StarData instance (invariant)

  • fit – A StarFit instance (invariant)

addPoisson(signal=None, gain=None)[source]

Return new Star with the weight values altered to reflect Poisson shot noise from a signal source, e.g. when the weight only contains variance from background and read noise.

Parameters

  • signal – The signal (as a Star instance) from which the Poisson variance is extracted. If None, the data image is used. All signals are clipped from below at zero.

  • gain – The gain, in e per ADU, assumed in calculating new weights. If None is given, then the ‘gain’ property is used, else defaults to not adding any variance.

Returns

a new Star instance with updated weight array.

center_to_offset(center)[source]

A utility routine to convert from a center position in focal plane coordinates to the corresponding offset in image coordinates on the postage stamp image.

Parameters

center – A tuple (u,v) in focal plane coordinates

Returns

The corresponding (dx,dy) in image coordinates.

static load_images(stars, file_name, pointing=None, image_hdu=None, weight_hdu=None, badpix_hdu=None, noise=None, sky=None, logger=None)[source]

Load the image data into a list of Stars.

We don’t store the image data for Stars when we write them to a file, since that would take up a lot of space and is usually not desired. However, we do store the bounds in the original image where the star was cutout, so if you want to load back in the original data from the image file, you can do so with this function.

Parameters

  • stars – A list of Star instances.

  • file_name – The file with the image data for these stars.

  • pointing – The pointing direction to use. [default: None]

  • image_hdu – The hdu to use for the main image. [default: None, which means either 0 or 1 as appropriate according to the compression.]

  • weight_hdu – The hdu to use for the weight image. [default: None]

  • badpix_hdu – The hdu to use for the bad pixel mask. [default: None]

  • noise – A constant noise value to use in lieu of a weight map [default: None]

  • sky – Optional sky image or float value to subtract from the main image. [default: None]

  • logger – A logger object for logging debug info. [default: None]

Returns

a new list of Stars with the images information loaded.

classmethod makeTarget(x=None, y=None, u=None, v=None, properties={}, wcs=None, scale=None, stamp_size=48, image=None, weight=None, pointing=None, flux=1.0, **kwargs)[source]

Make a target Star object with the requested properties.

The image will be blank (all zeros), and the properties field will match the given input properties.

The input properties must have either ‘x’ and ‘y’ or ‘u’ and ‘v’. The other pair will be calculated from the wcs if one is provided, or you may pass in both sets of coordinates and leave out the wcs

Parameters

  • x – The image x position. [optional, see above; may also be given as part of the :properties: dict.]

  • y – The image y position. [optional, see above; may also be given as part of the :properties: dict.]

  • u – The image u position. [optional, see above; may also be given as part of the :properties: dict.]

  • v – The image v position. [optional, see above; may also be given as part of the :properties: dict.]

  • properties – The requested properties for the target star, including any other requested properties besides x,y,u,v. You may also provide x,y,u,v in this dict rather than explicitly as kwargs. [default: None]

  • wcs – The requested WCS. [optional]

  • scale – If wcs is None, you may instead provide a pixel scale. [default: None]

  • stamp_size – The size in each direction of the (blank) image. [default: 48]

  • image – An existing image to use instead of making a new one, if desired. [default: None; this overrides stamp_size]

  • weight – An existing image to use for the weight. [default: None]

  • pointing – The pointing direction to use. [default: None]

  • flux – The flux of the target star. [default: 1]

  • **kwargs – Additional properties can also be given as keyword arguments if that is more convenient than populating the properties dict.

Returns

A Star instance

offset_to_center(offset)[source]

A utility routine to convert from an offset in image coordinates to the corresponding center position in focal plane coordinates on the postage stamp image.

Parameters

offset – A tuple (dx,dy) in image coordinates

Returns

The corresponding (du,dv) in focal plane coordinates.

classmethod read(fits, extname)[source]

Read stars from a FITS file.

Parameters

  • fits – An open fitsio.FITS object

  • extname – The name of the extension to read from

Returns

a list of Star instances

classmethod read_coords_params(fits, extname)[source]

Read only star fit parameters and coordinates from a FITS file.

Parameters

  • fits – An open fitsio.FITS object

  • extname – The name of the extension to read from

Returns

the arrays coords and params

run_hsm()[source]

Use HSM to measure moments of star image.

This usually isn’t called directly. The results are accessible as star.hsm, which caches the results, so repeated access is efficient.

Returns

(flux, cenu, cenv, sigma, g1, g2, flag)

withFlux(flux=None, center=None)[source]

Update the flux and/or center values

Parameters

  • flux – The new flux. [default: None, which means keep the existing value.]

  • center – The new center. [default: None, which means keep the existing value.]

withProperties(**kwargs)[source]

Set or change any properties in the star.

Parameters

**kwargs – Each named kwarg is taken to be a property to set in the returned star.

Returns

a new Star with the given properties, but is otherwise the same as self.

classmethod write(stars, fits, extname)[source]

Write a list of stars to a FITS file.

Parameters

  • stars – A list of stars to write

  • fits – An open fitsio.FITS object

  • extname – The name of the extension to write to

class piff.StarData(image, image_pos, weight=None, pointing=None, field_pos=None, properties=None, property_types=None, orig_weight=None, logger=None, _xyuv_set=False)[source]

A class that encapsulates all the relevant information about an observed star.

Class intended to be immutable once returned from the method that creates it.

This includes:

  • a postage stamp of the imaging data

  • the weight map for these pixels (zero weight means the pixel is masked or otherwise bad)

  • whether the pixel values represent flux or surface brightness

  • the pixel area on the sky

  • the position of the star on the image

  • the position of the star in the full field-of-view (local tangent plane projection)

  • possibly extra information, such as colors

A StarData object can render the pixel data in one of two ways:

  • getImage() returns the pixels as a galsim.Image.

  • getDataVector() returns the pixels as a numpy array.

Different use cases may prefer the data in one of these forms or the other.

A StarData object also has this property:
property pixel_area

Solid angle on sky subtended by each pixel, in units of the uv system.

The other information is stored in a dict. This dict will include at least the following items:

  • x

  • y

  • u

  • v

And anything else you want to store. e.g.

  • chipnum

  • ra

  • dec

  • color_ri

  • color_iz

  • gain

Any of these values may be used for interpolation. The most typical choices would be either (x,y) or (u,v). The choice of what values to use is made by the interpolator. All such values should be either int or float values.

Note that the position given for the star does not have to be a proper centroid. It is rather just some position in image coordinates to use as the origin of the model.

Parameters

  • image – A postage stamp image that includes the star

  • image_pos – The position in image coordinates to use as the “center” of the star. Note: this does not have to be the centroid or anything specific about the star. It is merely the image position of the (0,0) coordinate for the model’s internal coordinate system.

  • weight – The corresponding weight map for that image. [default: None]

  • pointing – A galsim.CelestialCoord representing the pointing coordinate of the exposure. It does not have to be the exact center of the field of view. But it should be the same for all StarData objects in the exposure. This is required if image.wcs is a CelestialWCS, but should be None if image.wcs is a EuclideanWCS. [default: None]

  • field_pos – Optionally provide the field_pos directly, rather than calculating it from the wcs and a pointing. [default: None]

  • properties – A dict containing other properties about the star that might be of interest. [default: None]

  • property_types – A dict containing the types to use for properties if we are eventually going to output them to a file. (Only really necessary for any that aren’t float.) [default: None]

  • orig_weight – The original weight map prior to any additional Poisson variance being added. [default: None, which means use orig_weight=weight]

  • logger – A logger object for logging debug info. [default: None]

addPoisson(signal=None, gain=None)[source]

Return new StarData with the weight values altered to reflect Poisson shot noise from a signal source, e.g. when the weight only contains variance from background and read noise.

Parameters

  • signal – The signal (as a Star instance) from which the Poisson variance is extracted. If None, the data image is used. All signals are clipped from below at zero.

  • gain – The gain, in e per ADU, assumed in calculating new weights. If None is given, then the ‘gain’ property is used, else defaults to not adding any variance.

Returns

a new StarData instance with updated weight array.

static calculateFieldPos(image_pos, wcs, pointing, properties=None)[source]

Convert from image coordinates to field coordinates.

Parameters

  • image_pos – The position in image coordinates, as a galsim.PositionD instance.

  • wcs – The wcs to use to connect image coordinates with sky coordinates:

  • pointing – A galsim.CelestialCoord representing the pointing coordinate of the exposure. This is required if image.wcs is a CelestialWCS, but should be None if image.wcs is a EuclideanWCS. [default: None]

  • properties – If properties is provided, and the wcs is a CelestialWCS, then add ‘ra’, ‘dec’ properties (in hours, degrees respectively) based on the sky coordinates. [default: None]

Returns

a galsim.PositionD instance representing the position in field coordinates.

getDataVector()[source]

Get the pixel data as a numpy array.

Also returns the weight values and the local u,v coordinates of the pixels. Any pixels with zero weight (e.g. from masking in the original image) will not be included in the returned arrays.

Returns

data_vector, weight_vector, u_vector, v_vector

getImage()[source]

Get the pixel data as a galsim.Image.

Also returns the weight image and the origin position (the position in x,y coordinates to use as the origin of the PSF model).

Returns

image, weight, image_pos

class piff.StarFit(params, flux=1.0, center=(0.0, 0.0), params_var=None, A=None, b=None, chisq=None, dof=None)[source]

Class to hold the results of fitting a Model to some StarData, or specify the PSF interpolated to an unmeasured location.

Class is intended to be invariant once created.

This class can be extended to carry information of use to a given Model instance (such as intermediate results), but interpolators will be looking for some subset of these properties:

Params

numpy vector of parameters of the PSF that apply to this star

Params_var

numpy array of variance error parameters of the PSF

Flux

flux of the star

Center

(u,v) tuple giving position of stellar center (relative to data.image_pos)

Chisq

Chi-squared of fit to the data (if any) with current params

Dof

Degrees of freedom in the fit (will depend on whether last fit had parameters free or just the flux/center).

A, b

matrix, vector, giving design matrix equation for the Taylor expansion of chisq wrt params about their current values. The alpha matrix, AT A, is also the inverse covariance matrix of the params.

Parameters

  • params – A 1d numpy array holding estimated PSF parameters

  • params_var – A 1d numpy array holding estimates PSF variance error parameters

  • flux – Estimated flux for this star

  • center – Estimated or fixed center position (u,v) of this star relative to the StarData.image_pos reference point.

  • A – Design matrix for the quadratic dependence of chi-squared on params about current values. Quatratic terms is dpT AT A dp.

  • b – Vector portion of design equation. Linear term of chi-squared dependence on params about current values is -2 AT b.

  • chisq – chi-squared value at current parameters.

newParams(params, **kwargs)[source]

Return new StarFit that has the array params installed as new parameters.

Parameters

  • params – A 1d array holding new parameters; must match size of current ones

  • **kwargs – Any other additional properties for the star. Takes current flux and center if not provided, and otherwise puts in None

Returns

New StarFit object with altered parameters. All chisq-related parameters are set to None since they are no longer valid.