Reference¶

The ALPS-CCD package¶

This package contains tools to load *.SPE CCD frames saved by WinView (ccd.io subpackage) and analyse CCD frames (ccd.analysis subpackage)

`ccd.io` CCD Frame I/O¶

This package contains tools to read e.g. *.spe files. Important helper functions to load single and multiple files are:

get_frame()
frame_iter()

CCD frames are stored as Frame objects. Multi-frame files are stored as FrameSet. Meta-information of such FrameInfo and FrameSetInfo containers.

ccd.io.tools.frame_iter(paths)¶

Loop over all frames in the files in paths regardless of single-/multiple-frame files.

Parameters:

paths : iterable of str

The file names.

ccd.io.tools.get_frame(framepath)¶

Get a frame from a single or multi-frame file.

If a frame from a multi-frame file is requested, the frame number must be appended to the file path deliminated by ccd.io.FrameSetInfo.framenumsep (default: ‘##’), e.g. some/deep/directory/name.spe##3. Frame numbers are 0-indexed.

class ccd.io.frameset.FrameSet(frames=None)¶

Container for a set of frames taken under the same conditions (e.g. camera, temperature, exposure time).

add_frames(*frames)¶: Add all arguments to the frame list.

frame_shape¶

frames¶

classmethod from_dir(path, pattern='*', info_extract=None)¶

Load images from one directory.

Only images that match the glob-pattern pattern are included.

get_frame(i, retplain=None)¶

Retrieve a stored frame. No copy is performed!

Parameters:

i : int

Return the i-th index.

retplain : {True, False, None}, optional

If True return a plain np.ndarray frame, if False return a Frame object with appropriate info dictionary. If None (default) use the value of self.ret_plain_frame. If masked data is stored, the returned frame is always a masked frame.

classmethod load_file(path)¶: Load a frame set from a tar archive or FITS or SPE file.

mean_frame(retuncert=False, confidence=0.68, retframe=False)¶

Calculate the mean of each pixel, optionally the corresponding uncertainty.

The uncertainty is calculated assuming the pixel-values are Gaussian distributed, thus their mean values are Student-t distributed. The uncertainty for a pixel is then calculated from the ISF of the t-distribution t.isf, the number of samples n_meas and the empirical standard deviation of the pixel values, stdev:

ndf = n_meas - 1
a_half = 0.5 * ( 1.0 - confidence)
uncert = t.isf(a_half, ndf) * stdev / sqrt(n_meas)

Parameters:

retuncert : bool, optional

Calculate the uncertainties. Default is not to calculate these.

confidence : float, optional

The confidence level for uncertainties. I.e. the _true_ pixel mean is with probability confidence within:
mean - uncert < true < mean + uncert

Returns:

mean : 2D array

The mean pixel values.

uncert : 2D array, optional

The uncertainty of the mean values with confidence overlapping probability.

num_frames¶

pixel_correlation_rms_frame(prnt=True)¶

stddev_frame(ddof=1, **kwargs)¶

Calculate the empirical standard deviation in each pixel.

Parameters:

ddof : int, optional

The ddof parameter for np.std. For an unbiased estimator: ddof=1 (default), for a maximum likelihood estimator: ddof=0.

subset(indices, comment='')¶: Return a frame set containing only the frames indices.

var_frame(retuncert=False, confidence=0.68, ddof=1, **kwargs)¶

Calculate the variance estimate in every pixel and optionally the associated uncertainties.

The uncertainties are calculated based on the assumption that the variance is chi^2 distributed with \(N_{dof} = num_frames - 1\). The lower and upper chi2 quantilles are calculated and a symmetricized error estimate is returned.

Parameters:

ddof : int, optional

The ddof parameter for np.std. For a unbiased estimator: ddof=1 (default), for a maximum likelihood estimator: ddof=0.

retuncert : bool, optional

Return the estimate uncertainty is True. By default, the uncertainty is not returned.

confidence : float, optional

The confidence of the uncertainty estimation.

Returns:

var : 2D array

The estimated pixel variances.

uncert : 2D array, optional

The uncertainty of the estimated variances.

write_to_fits(f, overwrite=False)¶: Write to open file-object f.

zoom_in(*args)¶

Return a frame set for the given pixel ranges.

Accepted calling signatures::: zoom_in(pixel_range) zoom_in(xmin, ymin, xmax, ymax)

pixel_range must be an object with xmin, ymin, xmax, ymax attributes.

class ccd.io.info.FrameInfo(*args, **kwargs)¶

Container for CCD frame meta information

Stored data (if available) are:

temperature

The device temperature during exposure in Kelvin.

exposure

The exposure time in seconds.

gain

The read-out ADC gain identifier as str.

datetime

The date and time when the exposure was taken as datetime.datetime.

ro_mode

The read-out mode as str.

camera

The camera type as str.

comment

A comment containing e.g. notes about performed corrections.

path

The path of the file as str.

classmethod from_fits_header(header)¶

set(key, new)¶

update(*args, **kwargs)¶

update_fits_header(header)¶

update_from_fits_header(header)¶

class ccd.io.info.FrameSetInfo(*args, **kwargs)¶

framenumsep = '##'¶: Separator between frame-set filename and frame number

update_fits_header(header, image=-1)¶

Update given FITS header.

If image is given, assume to update the header data for image image. Otherwise (default) the primary header data is updated.

exception ccd.io.info.InfoError¶

ccd.io.info.QE_measurement_XEVA(abspath)¶: Format .../YYYY-MM-DD .../Filter ExpostimeUnit TempUnit/frame#.png

class ccd.io.info.TarFile(tarpath, filepath=None)¶

frameinfo¶

setinfo¶

ccd.io.info.get_date(part)¶

ccd.io.info.mk_key_function(*keys)¶

Make a key-function to sort/group lists of frames (or other objects).

Supported keys ar:

all allowed keys of FrameInfo
“dir”: The sub-directory of the frame file.
Callables accepting a Frame object.

Examples

>>> # Sort frames by exposure
>>> frames = sorted(frames, key=mk_key_function("exposure"))

>>> # Sort frames by containing directory (i.e. the data set)
>>> frames = sorted(frames, key=mk_key_function("dir"))

>>> # Group frames by exposure
>>> key_fn = mk_key_function("exposure")
>>> frames = sorted(frames, key=key_fn)
>>> grouped = itertools.groupby(frames, key_fn)

>>> # Sort frames by their mean value and exposure
>>> frames = sorted(frames,
...                 key=mk_key_function(lambda f: f.mean(),
...                                     "exposure"))

ccd.io.info.tokenize_basename(path)¶

class ccd.io.spe.SPEReader(path=None, file=None)¶

Reader for WinView/32 .spe files.

Attributes read:

datetime : `datetime.datetime`
    The local time at which the frame was taken.

exposure : `float`
    The exposure time in seconds.

dtype : numpy data type
    The data type stored in the frame, e.g. `numpy.int16` or
    `numpy.float`.

readoutrate : `str`
    The read-out rate used ("2MHz" or "100kHz").

adcoffset¶

as_TH2I(name='image', title='converted SPE frame')¶

as_primary_hdu()¶

data¶

datetime¶

dtype¶

exposure¶

num_frames¶

readoutrate¶

shape¶: The (y, x) shape of one frame.

shutter_compensation¶

shutter_control¶

temp¶: The detector temperature in degree Celsius.

`ccd.analysis` package¶

This package contains tools to analyze CCD frames.

class ccd.analysis.normalize.FrameNormalizer(valid_shape, data_rows, data_cols, offset_estimator, get_fpn=None)¶

A little helper to correct PIXIS frames using the overscan columns.

correct_offset(frame)¶

data_region(frame)¶

subtract_fpn(frame, *args, **kwargs)¶

class ccd.analysis.normalize.plain_offset(offset_rows, offset_cols)¶

Estimate the offset from averaging over all pixel in offset_rows and offset_cols.

Parameters:

offset_rows, offset_cols: valid ndarray index object, e.g. slice or None

The rows and columns where the offset will be estimated. If None, all rows or columns are used for estimation, respectively.

frame : 2dim ndarray, Frame, optional

The frame to estimate from. If None (default) a callable object is returned.

class ccd.analysis.normalize.rowwise_offset(offset_cols)¶

Estimate the row-wise offset from averaging over a given range of columns.

If this correction is performed the plain_offset correction is redundant.

Parameters:

offset_cols: valid ndarray index object, e.g. slice or None

The columns where the per-row offset will be estimated.

frame : 2dim ndarray, Frame, optional

The frame to estimate from. If None (default) a callable object is returned.

ccd.analysis.normalize.safe_slice(a)¶

If possible convert a into a slice object.

Returns:

ret : slice, other

If possible, a slice object, or a.

issclice : bool

True if ret is a slice.

Tools to fit 2-dim data¶

class ccd.analysis.spotfitting.GaussContExpo(*args, **kwargs)¶

Fit a 2-dim Gaussian with exponential tail to data.

Before fitting 2-dim data, one has to initialise the parameters of the fit-function. Parameters can be set using update_params(), during object creation or with initial_guess().

The current parameter values are accessible through param_values and param_dict.

evaluate(X0, X1)¶

Evaluate the fit function at position (X0, X1) using the current parameter values.

Parameters:

X0, X1 : float, ndarray

The locations where the fit-funtion is evaluated. Using matplotlib.matshow() convention means y, x = X0, X1.

fit(data, n_fit)¶

initial_guess(data)¶

integral()¶: Calculate the integral under the spot ignoring the offset.

param_dict¶

param_names = ('A', 'mu0', 'mu1', 'sigma0', 'sigma1', 'xi', 'offset')¶

update_params(*args, **kwargs)¶

Update fit-function parameters.

This method accepts either the numerical values of all parameters as arguments:

>>> fitter.update_params(1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0)

or keyword arguments (not necessarily all parameters):

>>> fitter.update_params(mu0=2.0, mu1=3.0)

class ccd.analysis.spotfitting.Gauss2D(*args, **kwargs)¶

Fit a 2-dim gaussian to data.

A Collection of Patterns and ROIs¶

class ccd.analysis.roi.BoundaryROI(central_roi, withdiag=True, width=1)¶

fmt = '<{self.__class__.__name__}[withdiag={self.withdiag} width={self.width}] of {self._central_roi} object>'¶

class ccd.analysis.roi.BoxROI(shape, inner_width, outer_width, inner_height, outer_height)¶

class ccd.analysis.roi.CircleROI(shape, radius)¶

dr2¶

fmt = '<{self.__class__.__name__}[radius:{self.radius}] object of shape:{self.shape} at [x:{self.x} y:{self.y}]>'¶

class ccd.analysis.roi.IrregularROI(mask)¶

class ccd.analysis.roi.MovableROI(shape)¶

fmt = '<{self.__class__.__name__} object of shape:{self.shape} at [x:{self.x} y:{self.y}]>'¶

move(i0, i1, xfirst=False)¶

Move the ROI to a new position on the frame.

Parameters:

i0, i1 : float

The new position.

xfirst : bool, optional

If True interprete arguments as x, y = i0, i1. By default, the ordering y, x = i0, i1 is assumed.

class ccd.analysis.roi.ROI(shape)¶

fmt = '<{self.__class__.__name__} object of shape:{self.shape}>'¶

inner_idx(idx, which='ravelled')¶

Convert whole-frame indices to indices valid in the ROI.

Whole-frame indices that are not in the ROI are silently discarded.

Calculate indices indexing pixels in the ROI from indices indexing the whole frame.

I.e. indices starting with 0 in the ROI.

Parameters:

idx : array_like of ints

The indices to convert.

which : string

Format of idx. At the moment only “ravelled” is accepted.

Returns:

inner : array of ints

The corresponding indices of the ROI area.

Examples

>>> roi = ROI(asarray([[0, 0, 0, 0],
...                    [0, 1, 1, 0],
...                    [0, 1, 0, 0],
...                    [0, 0, 0, 0]]), dtype=bool)
>>> roi.inner_idx(6)
array([1])
>>> roi.inner_idx(4)
array([], dtype=int32)

inverted¶

mask¶

n_px¶

outer_idx(idx, which='ravelled')¶: Convert inner indices to indices valid in the whole frame.

ravelled¶

xy¶

yx¶

class ccd.analysis.roi.RectangleROI(shape, width, height)¶

fmt = '<{self.__class__.__name__}[width:{self.width} height:{self.height}] object of shape:{self.shape} at [x:{self.x} y:{self.y}]>'¶

class ccd.analysis.roi.RingROI(shape, r_in, r_out)¶

fmt = '<{self.__class__.__name__}[inner:{self.r_in} outer:{self.r_out}] object of shape={self.shape} at [x:{self.x} y:{self.y}]>'¶

class ccd.analysis.roi.SliceROI(shape, sl0, sl1)¶

Construct a ROI from slices.

Parameters:

shape : (int, int)

The shape of the target mask.

sl0, sl1: slice or (int, int)

The slices of the ROI.

class ccd.analysis.roi.SquareROI(shape, size)¶

Square-shaped ROI.

To center the pattern on a pixel use:

>>> pattern.move(x + 0.5, y + 0.5)

Parameters:

shape : pair of int

The shape of the 2-dim data (y-len, x-len).

size : int

Size of the square.

fmt = '<{self.__class__.__name__}[size:{self.width}] object of shape:{self.shape} at [x:{self.x} y:{self.y}]>'¶

ccd.analysis.roi.get_boundary_mask(spot, withdiag=False, width=1, out=None, where=None)¶

Get the boundary of a single, connected spot.

If the spot is not singular, the behaviour is untested.

Parameters:

spot : 2-dim bool array

withdiag : bool, optional

If True include diag. neighbors in the boundary map.

width : int, optional

The width of the neighborhood in pixels. For width > 1 the result differs strongly depending the value of withdiag.

out : 2-dim array, optional

If not None the result is prepared in out and a reference to out is returned.

where : (y-indices, x-indices), optional

If given, the lists of y- and x-indices of the spots pixels. If None the indices are computed using np.where, which can be time-consuming.

ccd.analysis.roi.get_boundary_mask_pure_python(spot, withdiag=False, width=1, out=None, where=None)¶

Get the boundary of a single, connected spot.

If the spot is not singular, the behaviour is untested.

Parameters:

spot : 2-dim bool array

withdiag : bool, optional

If True include diag. neighbors in the boundary map.

width : int, optional

The width of the neighborhood in pixels. For width > 1 the result differs strongly depending the value of withdiag.

out : 2-dim array, optional

If not None the result is prepared in out and a reference to out is returned.

where : (y-indices, x-indices), optional

If given, the lists of y- and x-indices of the spots pixels. If None the indices are computed using np.where, which can be time-consuming.

ccd.analysis.roi.get_boundary_mask_weave(spot, withdiag=False, width=1, out=None, where=None)¶

Get the boundary of a single, connected spot.

If the spot is not singular, the behaviour is untested.

Parameters:

spot : 2-dim bool array

withdiag : bool, optional

If True include diag. neighbors in the boundary map.

width : int, optional

The width of the neighborhood in pixels. For width > 1 the result differs strongly depending the value of withdiag.

out : 2-dim array, optional

If not None the result is prepared in out and a reference to out is returned.

where : (y-indices, x-indices), optional

If given, the lists of y- and x-indices of the spots pixels. If None the indices are computed using np.where, which can be time-consuming.

ccd.analysis.roi.round_afz(x)¶

Replicate Python2’s “away from zero” round() function.

Parameters:

x : float

Returns:

rounded : int

Rounded number. At ties, e.g. 2.5 or -1.5, the result is rounded away from zero resulting in 3 or -1, respectively.

Reference¶

The ALPS-CCD package¶

ccd.io CCD Frame I/O¶

ccd.analysis package¶

Tools to fit 2-dim data¶

A Collection of Patterns and ROIs¶

`ccd.io` CCD Frame I/O¶

`ccd.analysis` package¶