hipercam.window¶

CCD windows module

Defines classes to represent sub-windows of a CCD and associated functions. Starts from a class representing just the header and format of a window, adds data to that, and also adds classes that bundle up a CCD’s-worth and multiple-CCD’s-wprth of such headers into single objects.

Classes summary

`Winhead`(llx, lly, nx, ny, xbin, ybin, outamp)	The header parts of a CCD window
`Window`(win[, data, copy])	A CCD window, headers, position and data
`CcdWin`([wins])	All the `Winhead` objects of a single CCD.
`MccdWin`([wins])	All the `Winhead` objects for multiple CCDs.

class hipercam.window.Winhead(llx, lly, nx, ny, xbin, ybin, outamp, head=None, copy=False)¶

Bases: hipercam.header.Header

The header parts of a CCD window

Winhead objects contain everything needed to represent a CCD window other than its data. This represents an arbitrary rectangular region of binned pixels. The lower-left pixel of the CCD is assumed to have coordinates (x,y) = (1,1). Winhead dimensions are in binned pixels.

>>> from hipercam import Winhead
>>> win = Winhead(12, 6, 100, 150, 2, 3)
>>> print(win)

Attributes

llxint

X ordinate lower-left pixel, unbinned pixels

llyint: Y ordinate lower-left pixel, unbinned pixels
xbinint: X-binning factor
ybinint: Y-binning factor
nxint: X-dimension, binned pixels
nyint: Y-dimension, binned pixels
outampstr, {‘’,’LL’,’LR’,’UL’,’UR’}: output amplifier location
urxint: X-ordinate of unbinned pixed at upper right of Winhead (starts from 1 on the left)
uryint: Y-ordinate of unbinned pixed at upper right of Winhead (starts from 1 on the left)
xlofloat: Left-most edge of window. Will be something-point-five as the centre of pixels are integers.
xhifloat: Right-most edge of window.
ylofloat: Lower edge of window
yhifloat: Upper edge of window

clash(win)¶

Raises a ValueError if two :class: Winhead`s are considered to ‘clash’. In this case this means if they have any pixels in common. This method is used in the ‘check’ method of the :class:`Group class to check the mutual validity of a set of Winhead.

Arguments:

win : :class:`Winhead`
   the :class:`Winhead` that we are testing self against.

copy(memo=None)¶

Returns a copy (deepcopy) of the Winhead

copy.copy and copy.deepcopy of a Winhead use this method

distance(x, y)¶: Calculates the minimum distance of a point from the edge of the Winhead. If the point is outside the Winhead the distance will be negative; if inside it will be positive. The edge is defined as the line running around the outside of the outer set of pixels. For a point outside the box in both x and y, the value returned is a lower limit to the distance.

extent()¶: Returns (left,right,bottom,top) boundaries of Winhead i.e. (xlo,xhi,ylo,yhi)

format(nohead=False)¶: Used to ensure that only the Winhead format gets printed which is useful in some instances. Relying on __repr__ carries the risk of being overloaded. Set ‘nohead’ True to suppress the header in addition

inside(win)¶

Returns True if win contains self in such a way that it could be cut down to it. This implies that even if binned, its pixels are “in step”, aka “synchronised”, and that its bin factors are integer divisors of those of self.

Arguments:

win  : :class:Winhead
   the :class:Winhead that we are testing against to see if `self` in
   inside it.

See also inside(), window()

property urx¶: Unbinned X pixel at upper-right of Winhead

property ury¶: Unbinned Y pixel at upper-right of Winhead

window(xlo, xhi, ylo, yhi, copy=False)¶

Generates a new Winhead by windowing it to match the complete pixels visible within the range xlo to xhi, ylo to yhi.

Arguments:

xlo : float
   minimum X, unbinned pixels (extreme left pixels of CCD centred
   on 1). None to ignore.

xhi : float
   maximum X, unbinned pixels. None to ignore.

ylo : float
   minimum Y, unbinned pixels (bottom pixels of CCD centred on 1)
   None to ignore.

yhi : float
   maximum Y, unbinned pixels. None to ignore

copy : bool
   controls whether the header is copied over, or just
   referenced.  The latter is more efficient, but if you later want
   to change the header could propogate those changes to whatever
   you copied.

Returns the windowed Winhead. Raises a ValueError if there are no visible pixels.

x(xpix)¶

Given an X-pixel position, returns the physical X in the CCD.

Arguments:

xpix : (float / ndarray)
  X-pixel position in terms of binned pixels. Centre of left-most
  pixel is 0.

Returns the physical location measured in unbinned pixels, with the centre of left-most pixels of the CCD = 1.0

x_pixel(x)¶

The inverse of x: returns the X-pixel position given a physical X location.

Arguments:

x : (float)
  the physical location measured in unbinned pixels, with the centre
  of left-most pixels of the CCD = 1.0

Returns the X-pixel position in terms of binned pixels. Centre of the left-most pixel is 0.

property xhi¶: Right-hand edge of window (urx+0.5)

property xlo¶: Left-hand edge of window (llx-0.5)

xy()¶: Returns two 2D arrays containing the x and y values at the centre of each pixel defined by the Winhead. See numpy.meshgrid to see what this means.

y(ypix)¶

Given a Y-pixel position, returns the physical Y in the CCD.

Arguments:

ypix : (float / ndarray)
  Y-pixel position in terms of binned pixels. Centre of lowest
  pixel is 0.

Returns the physical location measured in unbinned pixels, with the centre of lowest pixels of the CCD = 1.0

y_pixel(y)¶

The inverse of y: returns the Y-pixel position given a physical Y location.

Arguments:

Y : (float)
  the physical location measured in unbinned pixels, with the centre
  of lowest pixels of the CCD = 1.0

Returns the Y-pixel position in terms of binned pixels. Centre of the lowest pixel is 0.

property yhi¶: Top edge of window (ury+0.5)

property ylo¶: Bottom edge of window (lly-0.5)

class hipercam.window.Window(win, data=None, copy=False)¶

Bases: hipercam.window.Winhead

A CCD window, headers, position and data

Constructed from a Winhead and a numpy.ndarray which is stored in an attribute called data.

>>> import numpy as np
>>> from hipercam import Winhead, Window
>>> win = Winhead(12, 6, 100, 150, 2, 3, 'LL')
>>> data = np.ones((150,100))
>>> wind = Window(win,data)
>>> wind += 0.5
>>> wind *= 2

You cannot directly change the nx, ny values of a Window; you have to change its data array attribute and nx and ny will be taken from it.

Window objects support various arithematical operations such as subtraction or addition of constants. The end result of these always has a float type for safety to avoid problems with e.g. trying to make the result of adding a float to an integer an integer or with the range of integers.

Parameters

winWinhead: the Winhead defining the position and, optionally, headers
data2D numpy.ndarray: the data (2D). The dimensions must match those in win unless data is None in which case a zero array of the correct size will be created. A ValueError will be raised if not. Standard C-type ordering, y-then-x assumed.
copybool: flag sent to Winhead controlling whether the header is copied by value or reference. ‘False’ is lightweight and faster but when building up CCDs from multiple Windows, you should probably use ‘True’ unless you are careful to make ‘win’ a different object every time.

add_fxy(funcs, ndiv=0)¶

Routine to add in the results of evaluating a function or a list of functions of x & y to the Window. Each function must take 2D arrays of x and y values for each pixel of the Window and return an array of values for each point. If you have lots of things to add, this routine saves some overhead by only generating the x,y pixel arrays once at the start. Pixels can be subdivided ndiv per unbinned pixel (ndiv == 0 simply computes the result at pixel centre)

Arguments:

funcs : (a callable or a list of callables)
    the callable(s) must have signature::

       arr = func(x,y)

    where x and y are 2D arrays containing the x and y values at the
    centre of each pixel in the :class:`Window`. Each func must have
    a method 'offset(self, dx, dy)' which returns a copy of the
    function displaced in centre by dx, dy unbinned pixels.

ndiv : (int)

    a sub-division factor used to improve the photometric accuracy
    when pixellation matters. The funcs are computed over a grid of
    ndiv*ndiv points per unbinned pixel.

add_noise(readout, gain)¶

Adds noise to a Window according to a variance calculated from V = readout**2 + counts/gain. Arguments:

readout : (float)
    RMS readout noise in counts

gain : (float)
    Gain in electrons per count.

copy(memo=None)¶

Returns a copy (deepcopy) of the Window

copy.copy and copy.deepcopy of a Window use this method

crop(win)¶

Creates a new :class:Window by cropping the current :class:Window to the format defined by :class:Winhead win. Will throw a ValueError if the operation is impossible or results in no overlap. The current :class:Window must lie outside win and must be synchronised (in step) if any binning is used. If binning is used then the binning factors of the :class:Window must be divisors of the binning factors of those of win. If binning takes place it will be carried out by averaging, as appropriate for cropping flat-field frames (but not star fields).

Arguments:

win : (:class:Winhead)
   the new format to apply.

flatten()¶: Return data of the Window as a 1D array

float32()¶: Converts the data type of the array to float32.

float64()¶: Converts the data type of the array to float64.

max()¶: Returns the maximum value of the Window.

mean()¶: Returns the mean value of the Window.

median()¶: Returns the median value of the Window.

min()¶: Returns the minimum value of the Window.

property nx¶: Returns binned X-dimension of the Window.

property ny¶: Returns binned Y-dimension of the Window.

percentile(q)¶

Computes percentile(s) of a Window.

Arguments:

q : float or sequence of floats
  Percentile(s) to use, in range [0,100]

classmethod rhdu(hdu)¶: Constructs a Window from an ImageHdu. Requires header parameters ‘LLX’, ‘LLY’, ‘XBIN’ and ‘YBIN’ to be defined. This converts the data to float32 internally, unless it is read in as float64 in the first place conversion which would lose precision.

search(fwhm, x0, y0, thresh, fft, max=False, percent=50.0)¶

Search for a target in a :class:Window. Works by convolving the image with a gaussian of FWHM = fwhm, and returns the location of the maximum in the smoothed image which exceeds a level thresh and lies closest to the expected position. The convolution improves the reliability of the identification of the object position and reduces the chance of problems being caused by cosmic rays, although if there is more overall flux in a cosmic ray than the star, it could go wrong.

This routine is intended to provide a first cut in position for more precise methods to polish.

Arguments:

 fwhm : float
   Gaussian FWHM in pixels. If <= 0, there will be no convolution,
   although this is not advisable as a useful strategy.

 x0 : float
   x-position to judge position from (CCD-coordinates). The closest
   sufficiently high maximum will be taken.

 y0 : float
   y-position to judge position from (CCD-coordinates). The closest
   sufficiently high maximum will be taken.

 thresh : float
   The peak counts above background in the maximum of the *smoothed*
   image must exceed this value for a maximum to count. Use this to
   filter out noise.

 fft : bool
   The astropy.convolution routines are used. By default FFT-based
   convolution is applied as it scales better with fwhm, especially
   for fwhm >> 1, however the direct method (fft=False) may be faster
   for small fwhm values and images and has a better behaviour at the
   edges where it extends value with the nearest pixel while the FFT
   wraps values.

max : bool
   If True, just go for the highest peak, i.e. ignore x0, y0. The peak
   should still exceed the background by `thresh`

percent : float
   percentile to use to compute the background value. < 0 and it will
   be set to the minimum. 50% = median by default.

Returns:

a tuple of (x,y,peak): x,y is the location of the
brightest pixel measured in terms of CCD coordinates
(i.e. lower-left pixel is at (1,1)) and `peak` is the image value
at the peak pixel, in the *unconvolved* image. It might be useful
for initial estimates of peak height. If no peak is found, a
HipercamError will be raised.

set_const(val)¶: Sets the data array to a constant

property size¶: Number of pixels

std()¶: Returns the standard deviation of the Window.

sum()¶: Returns the sum of the Window.

uint16()¶: Converts the data type of the array to uint16. A warning will be issued if there will be loss of precision. A ValueError is thrown if any data are outside the range 0 to 65535 This is to save space on output.

whdu(head=None, xoff=0, yoff=0, extnam=None)¶

Writes the Window to an astropy.io.fits.ImageHDU

Arguments:

head : astropy.io.fits.Header
    Extra header items to add at the start of header in addition to
    those already contained in the :class:`Window`.

xoff : int
    Offset in X-direction to use for mosaicing.

yoff : int
    Offset in Y-direction to use for mosaicing.

extnam : None | string
    Extension name, useful in 'fv'

Returns:

hdu    : astropy.io.fits.ImageHDU
   The HDU containing the data and the header.

window(xlo, xhi, ylo, yhi, copy=False)¶

Creates a new Window by windowing it down to whatever complete pixels are visible in the region xlo to xhi, ylo to yhi. ValueError raised if no Window left.

Arguments:

xlo : float
   minimum X, unbinned pixels (extreme left pixels of CCD
   centred on 1)

xhi : float
   maximum X, unbinned pixels

ylo : float
   minimum Y, unbinned pixels (bottom pixels of CCD centred on 1)

yhi : float
   maximum Y, unbinned pixels

copy : bool
   controls whether the headers in the Winhead associated
   with this are copied by value or reference. True=copy by
   value which can carry significant overheads, but has the
   virtue of creating an independent object.

Returns the windowed Window.

property winhead¶: A copy of the Winhead underlying the Window This is to allow simpler reporting of problems with the format without the data as well

class hipercam.window.CcdWin(wins={})¶

Bases: hipercam.group.Group

All the Winhead objects of a single CCD.

Acts as a container for all of the window formats of a CCD.

Parameters

winsGroup(Winhead): All of the Winhead objects

classmethod fromJson(fname)¶

Read from JSON-format file fname

Returns a CcdWin object.

toJson(fname)¶

Dumps ccdWin in JSON format to a file

Arguments:

fname : (string)
   name of file to dump to

class hipercam.window.MccdWin(wins={})¶

Bases: hipercam.group.Group

All the Winhead objects for multiple CCDs.

Parameters

winsGroup(CcdWin): All of the CcdWin objects

classmethod fromJson(fname)¶

Read from JSON-format file fname

Returns an MccdWin object.

toJson(fname)¶

Dumps MccdWin in JSON format to a file

Arguments:

fname : (string)
   file to dump to

hipercam.window¶

Table of Contents

Previous topic

Next topic

This Page

Navigation

hipercam.window¶