cpl.core ¶

Raises:

cpl.core.IllegalInputError – If the passed type is invalid
cpl.core.TypeMismatchError – If the image type is complex and requested casting type is non-complex.

See also

cpl.core.Image.to_type: Converts an image to a given type. Modified in place.

conjugate(self: cpl.core.Image) → None¶

Complex conjugate the pixels in a complex image. Modified in place.

Raises:: cpl.core.InvalidTypeError – If the image is not of a complex type

copy_into(self: cpl.core.Image, other: cpl.core.Image, ypos: int, xpos: int) → None¶

Copy one image into another

(ypos, xpos) must be a valid position in self. If other is bigger than the place left in self, the part that falls outside of self is simply ignored, an no error is raised. The bad pixels are inherited from other in the concerned self zone.

The two input images must be of the same type, namely one of cpl.core.Type.INT, cpl.core.Type.FLOAT, cpl.core.Type.DOUBLE.

Parameters:

other (cpl.core.Image) – the inserted image
ypos (int) – the y pixel position in self where the lower left pixel of other should go (from 0 to the y-1 size of self)
xpos (int) – the x pixel position in self where the lower left pixel of other should go (from 0 to the x-1 size of self)

Raises:

cpl.core.TypeMismatchError – if the input images are of different types
cpl.core.InvalidTypeError – if the image type is not supported
cpl.core.AccessOutOfRangeError – if xpos or ypos are outside the specified range

Notes

The two pixel buffers may not overlap

count_rejected(self: cpl.core.Image) → int¶

Count the number of bad pixels declared in an image

Returns:: the number of bad pixels
Return type:: int

static create_gaussian(width: int, height: int, dtype: cpl.core.Type, xcen: float, ycen: float, norm: float, sig_x: float, sig_y: float) → cpl.core.Image¶

Generate an image from a 2d gaussian function.

This function generates an image of a 2d gaussian. The gaussian is defined by the position of its centre, given in pixel coordinates inside the image with the FITS convention (x from 0 to nx-1, y from 0 to ny-1), its norm and the value of sigma in x and y.

\[f(x, y) = (norm/(2*pi*sig_x*sig_y)) * exp(-(x-xcen)^2/(2*sig_x^2)) * exp(-(y-ycen)^2/(2*sig_y^2))\]

Parameters:

width (int) – width of the new image
height (int) – height of the new image
dtype (cpl.core.Type) – type of the new image, must be cpl.core.Type.FLOAT or cpl.core.Type.DOUBLE
xcen (int, float) – x position of the center
ycen (int, float) – y position of the center
norm (int, float) – norm of the gaussian.
sig_x (int, float) – sigma in x for the gaussian distribution.
sig_y (int, float) – sigma in y for the gaussian distribution.

Returns:

New Image containing the gaussian function.

Return type:

Raises:

cpl.core.InvalidTypeError – If self is not of a supported image type.

See also

cpl.core.Image.create_gaussian_like: Generate an image from a 2d gaussian function with width, height and type matching another image.

static create_gaussian_like(other: cpl.core.Image, xcen: float, ycen: float, norm: float, sig_x: float, sig_y: float) → cpl.core.Image¶

Generate an image from a 2d gaussian function with width, height and type matching another image.

This function generates an image of a 2d gaussian. The gaussian is defined by the position of its centre, given in pixel coordinates inside the image with the FITS convention (x from 0 to nx-1, y from 0 to ny-1), its norm and the value of sigma in x and y.

\[f(x, y) = (norm/(2*pi*sig_x*sig_y)) * exp(-(x-xcen)^2/(2*sig_x^2)) * exp(-(y-ycen)^2/(2*sig_y^2))\]

Parameters:

other (cpl.core.Image) – Other Image with the desired width, height and data type.
xcen (int, float) – x position of the center
ycen (int, float) – y position of the center
norm (int, float) – norm of the gaussian.
sig_x (int, float) – sigma in x for the gaussian distribution.
sig_y (int, float) – sigma in y for the gaussian distribution.

Returns:

New Image containing the gaussian function.

Return type:

See also

cpl.core.Image.create_gaussian: Generate an image from a 2d gaussian function.

static create_jacobian(deltax: cpl.core.Image, deltay: cpl.core.Image) → cpl.core.Image¶

Compute area change ratio for a transformation map.

Parameters:

deltax (cpl.core.Image) – x shift of each pixel
deltay (cpl.core.Image) – y shift of each pixel

Returns:

New Image containing the are change ratios

Return type:

Notes

The shifts Images deltax and deltay, describing the transformation, must be of type cpl.core.Type.DOUBLE. For each pixel (u, v) of the output image, the deltax and deltay code the following transformation:

u - deltax(u,v) = x v - deltay(u,v) = y

This function writes the density of the (u, v) coordinate system relative to the (x, y) coordinates for each (u, v) pixel of image out.

This is trivially obtained by computing the absolute value of the determinant of the Jacobian of the transformation for each pixel of the (u, v) image self.

The partial derivatives are estimated at the position (u, v) in the following way:

dx/du = 1 + 1/2 ( deltax(u-1, v) - deltax(u+1, v) ) dx/dv = 1/2 ( deltax(u, v-1) - deltax(u, v+1) ) dy/du = 1/2 ( deltay(u-1, v) - deltay(u+1, v) ) dy/dv = 1 + 1/2 ( deltay(u, v-1) - deltay(u, v+1) )

Typically this function would be used to determine a flux-conservation factor map for the target image specified in function warp().

The map produced by this function is not applicable for flux conservation in case the transformation implies severe undersampling of the original signal.

Raises:

cpl.core.IllegalInputError – if the shift Images are not 2 dimensional
cpl.core.InvalidTypeError – if the shift Images are not cpl.core.Type.DOUBLE type.

static create_jacobian_polynomial(width: int, height: int, dtype: cpl.core.Type, poly_x: cpl::core::Polynomial, poly_y: cpl::core::Polynomial) → cpl.core.Image¶

Compute area change ratio for a 2D polynomial transformation.

Parameters:

width (int) – width of the new image
height (int) – height of the new image
dtype (cpl.core.Type) – type of the new image, must be cpl.core.Type.FLOAT or cpl.core.Type.DOUBLE
poly_x (cpl.core.Polynomial) – defines source x-pos corresponding to destination (u,v).
poly_y (cpl.core.Polynomial) – defines source y-pos corresponding to destination (u,v).

Returns:

New Image containing the computed area change ratios.

Return type:

Notes

For an image with pixel coordinates (x, y) which is mapped into an output image with pixel coordinates (u, v), and the polynomial inverse transformation (u, v) to (x, y) as in warp_polynomial(), this function writes the density of the (u, v) coordinate system relative to the (x, y) coordinates for each (u, v) pixel of the output image.

This is trivially obtained by computing the absolute value of the determinant of the Jacobian of the transformation for each pixel of the (u, v) self.

Typically this function would be used to determine a flux-conservation factor map for the target image specified in function warp_polynomial().

The map produced by this function is not applicable for flux conservation in case the transformation implies severe undersampling of the original signal.

Raises:

cpl.core.IllegalInputError – if the polynomial dimensions are not 2
cpl.core.InvalidTypeError – if the image type is not supported

See also

cpl.core.Image.create_jacobian_polynomial_like: Compute area change ratio for a 2D polynomial transformation with width, height and type matching another image.

static create_jacobian_polynomial_like(other: cpl.core.Image, poly_x: cpl::core::Polynomial, poly_y: cpl::core::Polynomial) → cpl.core.Image¶

Compute area change ratio for a 2D polynomial transformation with width, height and type matching another image.

Parameters:

other (cpl.core.Image) – other Image with the desired width, height and data type. The type of other must be cpl.core.Type.FLOAT or cpl.core.Type.DOUBLE
poly_x (cpl.core.Polynomial) – defines source x-pos corresponding to destination (u,v).
poly_y (cpl.core.Polynomial) – defines source y-pos corresponding to destination (u,v).

Returns:

New Image containing the computed area change ratios.

Return type:

Notes

For an image with pixel coordinates (x, y) which is mapped into an output image with pixel coordinates (u, v), and the polynomial inverse transformation (u, v) to (x, y) as in warp_polynomial(), this function writes the density of the (u, v) coordinate system relative to the (x, y) coordinates for each (u, v) pixel of the output image.

This is trivially obtained by computing the absolute value of the determinant of the Jacobian of the transformation for each pixel of the (u, v) self.

Typically this function would be used to determine a flux-conservation factor map for the target image specified in function warp_polynomial().

The map produced by this function is not applicable for flux conservation in case the transformation implies severe undersampling of the original signal.

Raises:

cpl.core.IllegalInputError – if the polynomial dimensions are not 2
cpl.core.InvalidTypeError – if the image type is not supported

See also

cpl.core.image.create_jacobian_polynomial: Compute area change ratio for a 2D polynomial transformation.

static create_noise_uniform(width: int, height: int, type: cpl.core.Type, min_pix: float, max_pix: float) → cpl.core.Image¶

Create an image with uniform random noise distribution.

Pixel values are within the provided bounds.

Parameters:

width (int) – width of the new image
height (int) – height of the new image
dtype (cpl.core.Type) – type of the new image, must be cpl.core.Type.INT, cpl.core.Type.FLOAT or cpl.core.Type.DOUBLE
min_pix (float) – minimum output pixel value.
max_pix (float) – maximum output pixel value.

Returns:

New image containing random noise.

Return type:

Raises:

cpl.core.IllegalInputError – If min_pix > max_pix
cpl.core.InvalidTypeError – If the image is not of a supported image type.

See also

cpl.core.Image.create_noise_uniform_like: Create an image with uniform random noise distribution with width, height and type matching another image.

static create_noise_uniform_like(other: cpl.core.Image, min_pix: float, max_pix: float) → cpl.core.Image¶

Create an image with uniform random noise distribution with width, height and type matching another image.

Pixel values are within the provided bounds.

Parameters:

other (cpl.core.Image) – other Image with the desired width, height and data type. The type of other must be cpl.core.Type.INT, cpl.core.Type.FLOAT or cpl.core.Type.DOUBLE
min_pix (float) – minimum output pixel value.
max_pix (float) – maximum output pixel value.

Returns:

New image containing random noise.

Return type:

Raises:

cpl.core.IllegalInputError – If min_pix > max_pix
cpl.core.InvalidTypeError – If the image is not of a supported image type.

See also

cpl.core.Image.create_noise_uniform: Create an image with uniform random noise distribution.

divide(self: cpl.core.Image, other: cpl.core.Image) → None¶

Divide self by another image

Parameters:

other (cpl.core.Image) – image to divide with

Raises:

cpl.core.IncompatibleInputError – if the input images have different sizes
cpl.core.TypeMismatchError – if the second input image has complex type

Notes

The result of division with a zero-valued pixel is marked as a bad pixel.

divide_scalar(self: cpl.core.Image, scalar: float) → None¶

Elementwise division of an image with a scalar

Modifies the image by dividing each of its pixels with a number.

Parameters:: scalar (float) – Non-zero number to divide with
Raises:: cpl.core.DivsionByZeroError – scalar is 0.0

dump(self: cpl.core.Image, filename: str | None = '', mode: str | None = 'w', window: tuple | None = None, show: bool | None = True) → str¶

Dump the image contents to a file, stdout or a string.

This function is intended just for debugging. It prints the contents of an image to the file path specified by filename. If a filename is not specified, output goes to stdout (unless show is False). In both cases the contents are also returned as a string.

Parameters:

filename (str, optional) – File to dump image contents to
mode (str, optional) – Mode to open the file with. Defaults to “w” (write, overwriting the contents of the file if it already exists), but can also be set to “a” (append, creating the file if it does not already exist or appending to the end of it if it does).
window (tuple(int,int,int,int), optional) – Window to dump with value in the format (llx, lly, urx, ury) where: - llx Lower left X coordinate - lly Lower left Y coordinate - urx Upper right X coordinate - ury Upper right Y coordinate
show (bool, optional) – Send image contents to stdout. Defaults to True.

Returns:

Multiline string containing the dump of the image contents.

Return type:

str

duplicate(self: cpl.core.Image) → cpl.core.Image¶

Copy the image.

Copy the image into a new image object. The pixels and the bad pixel map are also copied.

This method is also used when performing a deepcopy on an image.

Returns:: New image object that is a copy of the original image.
Return type:: cpl.core.Image

equals(self: cpl.core.Image, other: cpl.core.Image) → bool¶

Check if one image is equivalent to another.

Two images are considered equal if they share the same dimensions, type, and values (in the same positions as each other).

Can also be called using the equality operator i.e. self`==`other

Parameters:: other (-) – Image to compare to self.
Returns:: True if self is equal to other. False otherwise.
Return type:: bool

Notes

In comparison to numpy array equality, this function is more strict in that the properties of the array (type and dimensions) need to be equal, contrary to numpy which does elementwise comparisons and does not require the arrays to be of the same data type. Numpy functions are still however compatible with images as input arguments for numpy and thus equality functions can be used with the images (e.g. np.array_equals(im1, im2))

exponential(self: cpl.core.Image, base: float) → None¶

Compute the elementwise exponential of the image.

Modifies the image by computing the base-scalar exponential of each of its pixels.

Images can be of type cpl.core.Type.INT, cpl.core.Type.FLOAT or cpl.core.Type.DOUBLE.

Pixels for which the power of the given base is not defined are rejected and set to zero.

Parameters:: base (float) – Base of the exponential.

extract(self: cpl.core.Image, window: tuple) → cpl.core.Image¶

Extract a rectangular zone from an image into another image.

The input coordinates define the extracted region by giving the coordinates of the lower left and upper right corners (inclusive).

Coordinates must be provided in the FITS convention: lower left corner of the image is at (1,1), x increasing from left to right, y increasing from bottom to top. Images can be of type cpl.core.Type.INT, cpl.core.Type.FLOAT or cpl.core.Type.DOUBLE.

If the input image has a bad pixel map and if the extracted rectangle has bad pixel(s), then the extracted image will have a bad pixel map, otherwise it will not.

Parameters:: window (tuple(int,int,int,int)) – Window in the format (llx, lly, urx, ury) where: - llx Lower left X coordinate - lly Lower left Y coordinate - urx Upper right X coordinate - ury Upper right Y coordinate
Returns:: New image instance of the extracted area.
Return type:: cpl.core.Image
Raises:: cpl.core.IllegalInputError – if the window coordinates are not valid

extract_subsample(self: cpl.core.Image, xstep: int, ystep: int) → cpl.core.Image¶

Sub-sample an image

step represents the sampling step in x and y: both steps = 2 will create an image with a quarter of the pixels of the input image.

image type can be cpl.core.Type.INT, cpl.core.Type.FLOAT and cpl.core.Type.DOUBLE. If the image has bad pixels, they will be resampled in the same way.

The flux of the sampled pixels will be preserved, while the flux of the pixels not sampled will be lost. Using steps = 2 in each direction on a uniform image will thus create an image with a quarter of the flux.

Parameters:

ystep (int) – Take every xstep pixel in y
xstep (int) – Take every ystep pixel in x

Returns:

New sub-sampled image

Return type:

Raises:

cpl.core.IllegalInputError – if xstep, ystep are not positive
cpl.core.InvalidTypeError – if the image type is not supported

fft(self: cpl.core.Image, imag: cpl.core.Image | None = None, inverse: bool = False, unnormalized: bool = False, swap_halves: bool = False) → cpl.core.Image¶

Fast Fourier Transform a square, power-of-two sized image. Modified in place.

self must be either of type cpl.core.Type.DOUBLE_COMPLEX or cpl.core.Type.DOUBLE. If self is passed as cpl.core.Type.DOUBLE, the imaginary component can be passed via imag, which must also be cpl.core.Type.DOUBLE. imag is unused otherwise.

Any rejected pixel is used as if it were a good pixel.

The image must be square with a size that is a power of two.

Different FFT options can be set via the kwargs (see Parameters).

Parameters:

imag (cpl.core.Image, optional) – The imaginary part of the image. Only used when the image’s type is cpl.core.Type.DOUBLE If not given, a 0 value image will be set in its place.
inverse (bool, optional) – True to perform Inverse FFT transform
unnormalized (bool, optional) – True to not normalize (with N*N for N-by-N image) on inverse = False. Has no effect on forward transform (inverse = True).
swap_halves (bool, optional) – Swap the four quadrants of the result image.

Raises:

cpl.core.IllegalInputError – if the image is not square or if the image size is not a power of 2.
cpl.core.UnsupportedModeError – if mode is otherwise different from the allowed FFT options.
cpl.core.InvalidTypeError – if the passed image type is not supported.

Warning

When comparing to cpl.drs.fft.fft_image and numpy’s fft, with any image dimensions greater than or equal to 4x4 the values of the imaginary component of the resulting image is sign flipped. This is due to the differing implementation of the fft algorithm which is being looked into.

If possible is recommended to use cpl.drs.fft.fft_image as its a more up to date and well more maintained implementation of fft using fftw.

fill_rejected(self: cpl.core.Image, value: float) → None¶

Set the bad pixels in an image to a fixed value.

Images can be of type cpl.core.Type.FLOAT, cpl.core.Type.INT or cpl.core.Type.DOUBLE

Parameters:: value (int, float) – Value to replace bad pixels
Raises:: cpl.core.InvalidTypeError – If the image’s type is not supported, i.e. cpl.core.Type.FLOAT_COMPLEX or cpl.core.Type.DOUBLE_COMPLEX

fill_window(self: cpl.core.Image, window: tuple, value: float) → None¶

Fill an image window with a constant

Any bad pixels in the window are accepted.

Upper boundaries are inclusive and will also be filled with value.

Images can be of type cpl.core.Type.FLOAT, cpl.core.Type.INT or cpl.core.Type.DOUBLE

Parameters:

window (tuple(int,int,int,int)) – Window to fill with value in the format (llx, lly, urx, ury) where: - llx Lower left X coordinate - lly Lower left Y coordinate - urx Upper right X coordinate (inclusive) - ury Upper right Y coordinate (inclusive)
value (float) – Value to fill with

Raises:

cpl.core.IllegalInputError – The specified window is not valid

filter(self: cpl.core.Image, kernel: cpl::core::Matrix, filter: cpl.core.Filter, border: cpl.core.Border = <Border.FILTER: 0>, dtype: cpl.core.Type) → cpl.core.Image¶

Filter the image using a floating-point kernel

The kernel must have an odd number of rows and an odd number of columns and at least one non-zero element.

For scaling filters (cpl.core.Filter.LINEAR_SCALE and cpl.core.Filter.MORPHO_SCALE) the flux of the filtered image will be scaled with the sum of the weights of the kernel. If for a given input pixel location the kernel covers only bad pixels, the filtered pixel value is flagged as bad and set to zero.

For flux-preserving filters (cpl.core.Filter.LINEAR and cpl.core.Filter.MORPHO) the filtered pixel must have at least one input pixel with a non-zero weight available. Output pixels where this is not the case are set to zero and flagged as bad.

Supported pixel types are: cpl.core.Type.INT, cpl.core.Type.FLOAT and cpl.core.Type.DOUBLE.

Supported filters: cpl.core.Filter.LINEAR, cpl.core.Filter.MORPHO, cpl.core.Filter.LINEAR_SCALE and cpl.core.Filter.MORPHO_SCALE

The result is returned in a new Image.

Parameters:

kernel (cpl.core.Matrix) – Pixel weights
filter (cpl.core.Filter) – cpl.core.Filter.LINEAR or cpl.core.Filter.MORPHO, cpl.core.Filter.LINEAR_SCALE and cpl.core.Filter.MORPHO_SCALE
border (cpl.core.Border, optional) – Filtering border mode. Currently only supports cpl.core.Border.FILTER and thus is set to that by default
dtype (cpl.core.Type) – Data type to use for the output image, can be cpl.core.Type.INT, cpl.core.Type.FLOAT or cpl.core.Type.DOUBLE.

Returns:

The filtered image.

Return type:

Raises:

cpl.core.IllegalInputError – if the kernel has a side of even length.
cpl.core.DivisionByZeroError – If the kernel is a zero-matrix.
cpl.core.AccessOutOfRangeError – If the kernel has a side longer than the input image.
cpl.core.InvalidTypeError – if the image type is not supported.
cpl.core.TypeMismatchError – if in median filtering the input and output pixel types differ.
cpl.core.UnsupportedModeError – If the output pixel buffer overlaps the input one (or the kernel), or the border/filter mode is unsupported.

See also

cpl.core.Image.filter_mask: For filtering using a binary kernel (cpl.core.Mask)

filter_mask(self: cpl.core.Image, kernel: object, filter: cpl.core.Filter, border: cpl.core.Border, dtype: cpl.core.Type) → cpl.core.Image¶

Filter an image using a binary kernel

Parameters:

kernel (cpl.core.Mask) – Mask of Pixels to use
filter (cpl.core.Filter) – Filter to use, can be: cpl.core.Filter.MEDIAN, cpl.core.Filter.AVERAGE and more, see notes
border – border to use, can be cpl.core.Border.FILTER and more, see Notes
dtype (cpl.core.Type) – Data type to use for the output image. Can be cpl.core.Type.INT, cpl.core.Type.FLOAT or cpl.core.Type.DOUBLE but see Notes for restrictions.

Returns:

The filtered image.

Return type:

Notes

The kernel must have an odd number of rows and an odd number of columns.

The output image will have equal dimensions to the original image, except for the border mode CPL_BORDER_CROP, where the output image must have 2 * hx columns fewer and 2 * hy rows fewer than the original image, where the kernel has size (1 + 2 * hx, 1 + 2 * hy).

In standard deviation filtering the kernel must have at least two elements set to True, for others at least one element must be set to True.

Supported pixel types are: cpl.core.Type.INT, cpl.core.Type.FLOAT and cpl.core.Type.DOUBLE.

In median filtering the two images must have the same pixel type.

In standard deviation filtering a filtered pixel must be computed from at least two input pixels, for other filters at least one input pixel must be available. Output pixels where this is not the case are set to zero and flagged as rejected.

In-place filtering is not supported.

Supported modes:

cpl.core.Filter.MEDIAN: cpl.core.Border.FILTER, cpl.core.Border.ZERO, cpl.core.Border.COPY, cpl.core.Border.CROP.

cpl.core.Filter.AVERAGE: cpl.core.Border.FILTER

cpl.core.Filter.AVERAGE_FAST: cpl.core.Border.FILTER

cpl.core.Filter.STDEV: cpl.core.Border.FILTER

cpl.core.Filter.STDEV_FAST: cpl.core.Border.FILTER

Note that in PyCPL the supported border modes for median filtering includes ZERO but not NOP as in CPL’s cpl_image_filter_mask. This is because the NOP mode preserves pixel values from the border regions of a pre-allocated results Image, but this method uses a new Image to store the results so there are no pre-existing pixel values to preserve. See PIPE-11042 for more details.

To shift an image 1 pixel up and 1 pixel right with the cpl.core.Filter.MEDIAN filter and a 3 by 3 kernel, one should set to CPL_BINARY_1 the bottom leftmost kernel element - at row 3, column 1, i.e.

kernel=cpl.core.Mask(3,3)
kernel[0][0] = True

The kernel required to do a 5 x 5 median filtering is created like this:

kernel=~cpl.core.Mask(5,5)

Raises:

cpl.core.IllegalInputError – if the kernel has a side of even length.
cpl.core.DataNotFoundError – If the kernel is empty, or in case of cpl.core.Filter.STDEV if the kernel has only one element set to True.
cpl.core.AccessOutOfRangeError – If the kernel has a side longer than the input image.
cpl.core.InvalidTypeError – if the image type is not supported.
cpl.core.TypeMismatchError – if in median filtering the input and output pixel types differ.
cpl.core.UnsupportedModeError – If the output pixel buffer overlaps the input one (or the kernel), or the border/filter mode is unsupported.

flip(self: cpl.core.Image, angle: int) → None¶

Flip an image on a given mirror line.

This function operates locally on the pixel buffer.

angle can take one of the following values: - 0 (theta=0) to flip the image around the horizontal - 1 (theta=pi/4) to flip the image around y=x - 2 (theta=pi/2) to flip the image around the vertical - 3 (theta=3pi/4) to flip the image around y=-x

Images can be of type cpl.core.Type.INT, cpl.core.Type.FLOAT or cpl.core.Type.DOUBLE.

Parameters:

angle (int) – mirror line in polar coord. is theta = (PI/4) * angle

Raises:

cpl.core.IllegalInputError – if the angle is different from the allowed values
cpl.core.InvalidTypeError – if the image type is not supported

static from_accepted(image_list: cpl::core::ImageList) → cpl.core.Image¶

Create a contribution map from the bad pixel maps of the images.

The returned map counts for each pixel the number of good pixels in the list.

Parameters:: imlist (cpl.core.ImageList) – Images to generate a contribution map from.
Returns:: Output contribution map with the pixel type cpl.core.Type.INT
Return type:: cpl.core.Image
Raises:: cpl.core.IllegalInputError – If the input image list is not valid

get_absflux(self: cpl.core.Image, window: tuple | None = None) → float¶

Computes the sum of absolute values over an entire image or sub window.

Images can be cpl.core.Type.FLOAT, cpl.core.Type.INT or cpl.core.Type.DOUBLE.

Parameters:

window (tuple(int,int,int,int), optional) – Window to operate on in the format (llx, lly, urx, ury) where: - llx Lower left X coordinate (0 for leftmost) - lly Lower left Y coordinate (0 for lowest) - urx Upper right X coordinate - ury Upper right Y coordinate

Returns:

the absolute flux (sum of pixels) value

Return type:

float

Raises:

cpl.core.IllegalInputError – If the specified window is illegal
cpl.core.InvalidTypeError – If the image they are called on has complex data type.

get_centroid_x(self: cpl.core.Image, window: tuple | None = None) → float¶

Computes the x centroid value over the whole image or sub-window.

Images can be cpl.core.Type.FLOAT, cpl.core.Type.INT or cpl.core.Type.DOUBLE.

Parameters:

window (tuple(int,int,int,int), optional) – Window to operate on in the format (llx, lly, urx, ury) where: - llx Lower left X coordinate (0 for leftmost) - lly Lower left Y coordinate (0 for lowest) - urx Upper right X coordinate - ury Upper right Y coordinate

Returns:

the x centroid value

Return type:

float

Raises:

cpl.core.IllegalInputError – If the specified window is illegal
cpl.core.InvalidTypeError – If the image they are called on has complex data type.

See also

cpl.core.Image.get_centroid_y: Compute the y centroid value over the whole image or sub-window.

get_centroid_y(self: cpl.core.Image, window: tuple | None = None) → float¶

Computes the y centroid value over the whole image or sub-window.

Images can be cpl.core.Type.FLOAT, cpl.core.Type.INT or cpl.core.Type.DOUBLE.

Parameters:

window (tuple(int,int,int,int), optional) – Window to operate on in the format (llx, lly, urx, ury) where: - llx Lower left X coordinate (0 for leftmost) - lly Lower left Y coordinate (0 for lowest) - urx Upper right X coordinate - ury Upper right Y coordinate

Returns:

the y centroid value

Return type:

float

Raises:

cpl.core.IllegalInputError – If the specified window is illegal
cpl.core.InvalidTypeError – If the image they are called on has complex data type.

See also

cpl.core.Image.get_centroid_x: Compute the x centroid value over the whole image or sub-window.

get_flux(self: cpl.core.Image, window: tuple | None = None) → float¶

Computes the sum of pixel values over an entire image or sub window

Images can be cpl.core.Type.FLOAT, cpl.core.Type.INT or cpl.core.Type.DOUBLE.

Parameters:: window (tuple(int,int,int,int), optional) – Window to operate on in the format (llx, lly, urx, ury) where: - llx Lower left X coordinate (0 for leftmost) - lly Lower left Y coordinate (0 for lowest) - urx Upper right X coordinate - ury Upper right Y coordinate
Returns:: the flux (sum of pixels) value
Return type:: float
Raises:: cpl.core.IllegalInputError – If the specified window is illegal

Notes

Does not work on complex images.

get_fwhm(self: cpl.core.Image, ypos: int, xpos: int) → tuple¶

Compute the FWHM of an object in a cpl.core.Vector

For the FWHM in x (resp. y) to be computed, the image size in the x (resp. y) direction should be at least of 5 pixels.

If for any reason, one of the FHWMs cannot be computed, its returned value is None with no exception raised. For example, if a 4 column image is passed, the x component of the return tuple would be None, while the y component would be correctly computed, and no exception would be raised.

Parameters:

ypos (int) – the y position of the object (0 for the first pixel)
xpos (int) – the x position of the object (0 for the first pixel)

Returns:

fwhm y, x, which are the computed FWHM in y or x directions

Return type:

tuple(float, float)

Raises:

cpl.core.DataNotFoundError – if (ypos, xpos) specifies a rejected pixel or a pixel with a non-positive value
cpl.core.AccessOutOfRangeError – if (ypos or xpos) is outside the image size range

Notes

The return value may be None with no error condition

This function uses a basic method: start from the center of the object and go away until the half maximum value is reached in x and y.

get_interpolated(self: cpl.core.Image, ypos: float, xpos: float, yprofile: cpl::core::Vector, yradius: float, xprofile: cpl::core::Vector, xradius: float) → Tuple[float, float]¶

Interpolate a pixel

Parameters:

ypos (int) – Pixel y floating-point position (FITS convention)
xpos (int) – Pixel x floating-point position (FITS convention)
yprofile (cpl.core.Vector) – Interpolation weight vector as a function of the distance in Y
yradius (float) – Positive inclusion radius in the Y-dimension
xprofile (cpl.core.Vector) – Interpolation weight as a function of the distance in X
xradius (float) – Positive inclusion radius in the X-dimension

Returns:

Tuple of (interpolated, confidence), where interpolated represents the interpolated pixel value and confidence represents the confidence level of the interpolated value (range 0 to 1)

Return type:

tuple(float, float)

Raises:

cpl.core.IllegalInputError – If xradius, xprofile, yprofile and yradius are not as requested
cpl.core.InvalidTypeError – If the image type is not supported

Notes

If the X- and Y-radii are identical the area of inclusion is a circle, otherwise it is an ellipse, with the larger of the two radii as the semimajor axis and the other as the semiminor axis.

A good profile length is 2001, using radius 2.0.

The radii are only required to be positive. However, for small radii, especially radii less than 1/sqrt(2), (xpos, ypos) may be located such that no source pixels are included in the interpolation, causing the interpolated pixel value to be undefined.

The X- and Y-profiles can be generated with cpl.core.Vector.fill_kernel_profile(profile, radius). For profiles generated with cpl_vector_fill_kernel_profile() it is important to use the same radius both there and in cpl.core.Image.get_interpolated().

On error pconfid is negative (unless pconfid is NULL). Otherwise, if pconfid is zero, the interpolated pixel-value is undefined. Otherwise, if pconfid is less than 1, the area of inclusion is close to the image border or contains rejected pixels.

The input image type can be cpl.core.Type.INT, cpl.core.Type.FLOAT and cpl.core.Type.DOUBLE.

get_mad(self: cpl.core.Image, window: tuple | None = None) → Tuple[float, float]¶

Computes median and median absolute deviation (MAD) on an image or sub-window.

Images can be cpl.core.Type.FLOAT, cpl.core.Type.INT or cpl.core.Type.DOUBLE.

Parameters:

window (tuple(int,int,int,int), optional) – Window to operate on in the format (llx, lly, urx, ury) where: - llx Lower left X coordinate (0 for leftmost) - lly Lower left Y coordinate (0 for lowest) - urx Upper right X coordinate - ury Upper right Y coordinate

Returns:

The median of the non-bad pixels and the median absolute deviation of the good pixels in the format (median, MAD)

Return type:

tuple(float,float)

Raises:

cpl.core.InvalidTypeError – if the image type is not supported
cpl.core.DataNotFoundError – If all pixels in the image are bad

See also

cpl.core.Image.get_median_dev: for calculating median and mean absolute median deviation on an image or sub-window.
cpl.core.Image.get_median: for calculating median on all pixels or sub-window.

get_max(self: cpl.core.Image, window: tuple | None = None) → float¶

Computes the maximum pixel value over an entire image or image sub window

Images can be cpl.core.Type.FLOAT, cpl.core.Type.INT or cpl.core.Type.DOUBLE.

Parameters:: window (tuple(int,int,int,int), optional) – Window to operate on in the format (llx, lly, urx, ury) where: - llx Lower left X coordinate (0 for leftmost) - lly Lower left Y coordinate (0 for lowest) - urx Upper right X coordinate (inclusive) - ury Upper right Y coordinate (inclusive)
Returns:: the maximum value
Return type:: float

Notes

Does not work on complex images.

Raises:: cpl.core.IllegalInputError – If the specified window is illegal

See also

cpl.core.Image.get_min: Get the minimum pixel value over the entire image or image sub window.

get_maxpos(self: cpl.core.Image, window: tuple | None = None) → Tuple[int, int]¶

Computes maximum pixel value and position over an image or sub-window.

Images can be cpl.core.Type.FLOAT, cpl.core.Type.INT or cpl.core.Type.DOUBLE.

Parameters:

window (tuple(int,int,int,int), optional) – Window to operate on in the format (llx, lly, urx, ury) where: - llx Lower left X coordinate (0 for leftmost) - lly Lower left Y coordinate (0 for lowest) - urx Upper right X coordinate - ury Upper right Y coordinate

Returns:

the x coordinate and y coordinate of the maximum position in the format (x,y)

Return type:

tuple(int, int)

Raises:

cpl.core.IllegalInputError – If the specified window is illegal
cpl.core.InvalidTypeError – If self’s pixel type is invalid

See also

cpl.core.Image.get_minpos: get the position of the minimum value in the image

get_mean(self: cpl.core.Image, window: tuple | None = None) → float¶

Computes the mean pixel value over an entire image or sub-window.

Images can be cpl.core.Type.FLOAT, cpl.core.Type.INT or cpl.core.Type.DOUBLE.

Parameters:: window (tuple(int,int,int,int), optional) – Window to operate on in the format (llx, lly, urx, ury) where: - llx Lower left X coordinate (0 for leftmost) - lly Lower left Y coordinate (0 for lowest) - urx Upper right X coordinate - ury Upper right Y coordinate
Returns:: the mean value
Return type:: float

Notes

Does not work on complex images.

Raises:: cpl.core.IllegalInputError – If the specified window is illegal

get_median(self: cpl.core.Image, window: tuple | None = None) → float¶

Computes the median pixel value over an entire image or sub-window.

Images can be cpl.core.Type.FLOAT, cpl.core.Type.INT or cpl.core.Type.DOUBLE.

Parameters:: window (tuple(int,int,int,int), optional) – Window to operate on in the format (llx, lly, urx, ury) where: - llx Lower left X coordinate (0 for leftmost) - lly Lower left Y coordinate (0 for lowest) - urx Upper right X coordinate - ury Upper right Y coordinate
Returns:: the median value
Return type:: float
Raises:: cpl.core.IllegalInputError – If the specified window is illegal

Notes

The median value is calculated using integer arithmetic if the image has integer data type, in which case the median value may differ from some other Python libraries such as numpy. For integer images the behaviour of get_median is equivalent to np.floor(np.median(int_image)).

get_median_dev(self: cpl.core.Image, window: tuple | None = None) → Tuple[float, float]¶

Computes median and mean absolute median deviation on an image or sub-window.

For each non-bad pixel in the window the absolute deviation from the median is computed. The mean absolute median deviation is however still sensitive to outliers. Images can be cpl.core.Type.FLOAT, cpl.core.Type.INT or cpl.core.Type.DOUBLE.

Parameters:

window (tuple(int,int,int,int), optional) – Window to operate on in the format (llx, lly, urx, ury) where: - llx Lower left X coordinate (0 for leftmost) - lly Lower left Y coordinate (0 for lowest) - urx Upper right X coordinate - ury Upper right Y coordinate

Returns:

The median of the non-bad pixels and the mean absolute median deviation

Return type:

tuple(float,float)

Raises:

cpl.core.IllegalInputError – If the specified window is illegal
cpl.core.DataNotFoundError – If all pixels in the specified window are bad

See also

cpl.core.Image.get_mad: for calculating median and median absolute median deviation (MAD) on the image
cpl.core.Image.get_median: for calculating median on all pixels

get_min(self: cpl.core.Image, window: tuple | None = None) → float¶

Computes the minimum pixel value over an entire image or image sub window.

Images can be cpl.core.Type.FLOAT, cpl.core.Type.INT or cpl.core.Type.DOUBLE.

Parameters:: window (tuple(int,int,int,int), optional) – Window to operate on in the format (llx, lly, urx, ury) where: - llx Lower left X coordinate (0 for leftmost) - lly Lower left Y coordinate (0 for lowest) - urx Upper right X coordinate (inclusive) - ury Upper right Y coordinate (inclusive)
Returns:: the minimum value
Return type:: float

Notes

Does not work on complex images.

Raises:: cpl.core.IllegalInputError – If the specified window is illegal

See also

cpl.core.Image.get_max: Get the maximum pixel value over an image or image sub window.

get_minpos(self: cpl.core.Image, window: tuple | None = None) → Tuple[int, int]¶

Computes minimum pixel value position over an image or sub-window.

Images can be cpl.core.Type.FLOAT, cpl.core.Type.INT or cpl.core.Type.DOUBLE.

Parameters:

window (tuple(int,int,int,int), optional) – Window to operate on in the format (llx, lly, urx, ury) where: - llx Lower left X coordinate (0 for leftmost) - lly Lower left Y coordinate (0 for lowest) - urx Upper right X coordinate - ury Upper right Y coordinate

Returns:

the x coordinate and y coordinate of the minimum position in the format (x,y)

Return type:

tuple(int, int)

Raises:

cpl.core.IllegalInputError – If the specified window is illegal
cpl.core.InvalidTypeError – If self’s pixel type is invalid

See also

cpl.core.Image.get_maxpos: get the position of the maximum value in the image

Get a pixel at the specified coordinates.

This is equivalent to getting the pixel via image index using im[y][x]

Parameters:

y (int) – Row to extract value, 0 being the BOTTOMmost row of the image
x (int) – Column to extract value. 0 being the leftmost column of image

Returns:

Value at the specified index. - None if the value is invalid. - float if the image if the image is of a numerical type (cpl.core.Type.INT, cpl.core.Type.FLOAT or cpl.core.Type.DOUBLE). - complex if the image is of a complex type (cpl.core.Type.FLOAT_COMPLEX or cpl.core.Type.DOUBLE_COMPLEX)

Return type:

None, float, or complex

Raises:

cpl.core.IllegalInputError – Coordinates are invalid

Get a list of pixel data from the image from a given index along the image.

Indices are in reference to a 1D representation of the image starting from 0. When converting from 2D coordinates this is equal to (row*width+column)

Parameters:

index (int) – Zero-based index along the Image data to begin extracting pixel data. When converting from 2D coordinates this is equal to (row*width+column)
length (int) – Number of values to extract starting from index

Returns:

length number of values in the image starting from pixel index

Return type:

list

Raises:

cpl.core.AccessOutOfRangeError – If the range specified using index and length is outside of the image.

get_sqflux(self: cpl.core.Image, window: tuple | None = None) → float¶

Computes the sum of squared values over an entire image or sub-window

Images can be cpl.core.Type.FLOAT, cpl.core.Type.INT or cpl.core.Type.DOUBLE.

Parameters:

window (tuple(int,int,int,int), optional) – Window to operate on in the format (llx, lly, urx, ury) where: - llx Lower left X coordinate (0 for leftmost) - lly Lower left Y coordinate (0 for lowest) - urx Upper right X coordinate - ury Upper right Y coordinate

Returns:

the square flux

Return type:

float

Raises:

cpl.core.IllegalInputError – If the specified window is illegal
cpl.core.InvalidTypeError – If the image they are called on has complex data type.

get_stdev(self: cpl.core.Image, window: tuple | None = None) → float¶

Computes the pixel standard deviation over an image or sub window.

Images can be cpl.core.Type.FLOAT, cpl.core.Type.INT or cpl.core.Type.DOUBLE.

Parameters:: window (tuple(int,int,int,int), optional) – Window to operate on in the format (llx, lly, urx, ury) where: - llx Lower left X coordinate (0 for leftmost) - lly Lower left Y coordinate (0 for lowest) - urx Upper right X coordinate - ury Upper right Y coordinate
Returns:: the standard deviation value
Return type:: float
Raises:: cpl.core.IllegalInputError – If the specified window is illegal

Notes

get_stdev calculates the “sample standard deviation” rather than the “ensemble standard deviation”, i.e. the divisor in calculations is N - 1, where N is the number of pixels. This is equivalent to np.std(image, ddof=1) in numpy.

static hypot(first: cpl.core.Image, second: cpl.core.Image) → cpl.core.Image¶

The pixel-wise Euclidean distance between two images.

The Euclidean distance function is useful for gaussian error propagation on addition/subtraction operations.

For pixel values a and b the Euclidean distance c is defined as: :math:’c = sqrt{a^2 + b^2}’

If both input operands are of type cpl.core.Type.FLOAT the distance is computed in single precision, otherwise in double precision.

Parameters:

first (cpl.core.Image) – First input image. Must be type cpl.core.Type.CPL_TYPE_FLOAT or cpl.core.Type.CPL_TYPE_DOUBLE.
second (cpl.core.Image) – Second input image. Must be type cpl.core.Type.CPL_TYPE_FLOAT or cpl.core.Type.CPL_TYPE_DOUBLE.

Returns:

A new Image containing the Euclidean distance between first and second.

Return type:

Raises:

cpl.core.IncompatibleInputError – if the images have different sizes
cpl.core.InvalidType – if the images are not both CPL_TYPE_FLOAT or CPL_TYPE_DOUBLE type.

image_quality_est(self: cpl.core.Image, window: tuple) → cpl::core::Bivector¶

Compute an image quality estimation for an object

Parameters:

window (tuple(int, int, int, int)) – The zone window in the format (x1, y1, x2, y2)

Returns:

The IQE result, which contains in the first vector (x) the computed values, and in the second one (y), the associated errors.

The computed values are: - x position of the object - y position of the object - FWHM along the major axis - FWHM along the minor axis - the angle of the major axis with the horizontal in degrees - the peak value of the object - the background computed

Return type:

cpl.core.BiVector

Raises:

cpl.core.IllegalInputError – if the input zone is not valid or if the computation fails on the zone
cpl.core.InvalidTypeError – if the input image has the wrong type

Notes

This function makes internal use of the iqe() MIDAS function (called here cpl_iqe()) written by P. Grosbol. Refer to the MIDAS documentation for more details. This function has proven to give good results over the years when called from RTD. The goal is to provide the exact same functionality in CPL as the one provided in RTD. The code is simply copied from the MIDAS package, it is not maintained by the CPL team.

The bad pixels map of the image is not taken into account. The input image must be of type float.

is_rejected(self: cpl.core.Image, y: int, x: int) → bool¶

Test if a pixel is good or bad

Parameters:

y (int) – the y pixel position in the image (first pixel is 0)
x (int) – the x pixel position in the image (first pixel is 0)

Returns:

True if the pixel is bad, False if the pixel is good

Return type:

bool

Raises:

cpl.core.AccessOutOfRangeError – if the specified position is outside of image self

static labelise_create(mask: object) → Tuple[cpl.core.Image, int]¶

Labelise a mask to differentiate different objects

Separate the given mask into contiguous regions, labelling each region a different number. 0 Doesn’t count as a region.

Labelises all blobs: 4-neighbor connected zones set to 1 in this mask will end up in the image as zones where all pixels are the same, unique integer.

Parameters:: mask (cpl.core.Mask) – mask to labelise
Returns:: The image making up the labelled regions, and the amount of regions.
Return type:: tuple(cpl.core.Image, int)

Notes

Non-recursive flood-fill is applied to label the zones, dimensioned by the number of lines in the image, and the maximal number of lines possibly covered by a blob.

static load(filename: str, dtype: cpl.core.Type = <Type.DOUBLE: 131072>, extension: int = 0, plane: int = 0, area: tuple = None) → cpl.core.Image¶

Load an image from a file.

Load image data from the extension extension of the FITS file filename. The FITS extenstion may be an image (NAXIS = 2) or a data cube (NAXIS = 3). By default the image is read from the primary HDU of the FITS file.

When the specified extension is a data cube, the slice of the data cube to load may be given by plane. By default the first plane is loaded.

By default the whole image is loaded. If a particular region of an image should be loaded, the region to load may be provided by the argument area.

The argument dtype specifies the pixel data type of the result image. When the image is loaded the pixel data type in the input FITS file is converted into dtype. By default the image data of the input file is converted to cpl.core.Type.DOUBLE. To load the image without converting the pixel data type use cpl.core.Type.UNSPECIFIED.

Valid pixel data types which may be used for dtype are:

cpl.core.Type.INT (32-bit integer)
cpl.core.Type.FLOAT
cpl.core.Type.DOUBLE

Parameters:

filename (str) – Name of the input file
dtype (cpl.core.Type, default=cpl.core.Type.DOUBLE) – Data type of the pixels of the returned image
extension (int, default=0) – Index of the FITS extension to load (the primary data unit has index 0)
plane (int, default=0) – Index of the plane of a data cube to load (counting starts from 0)
area (Tuple, default=None) – Region of interest to load given as a tuple specifying the lower left x, the lower left y, the upper right x (inclusive) and the upper right y coordinate (inclusive) in this order. Numbering of the pixel x and y positions starts at 0 (pycpl convention). If None then the entire image will be loaded.

Returns:

New image instance of loaded data

Return type:

Raises:

cpl.core.FileIOError – If the file cannot be opened, or does not exist.
cpl.core.BadFileFormatError – If the data cannot be loaded from the file.
cpl.core.InvalidTypeError – If the requested pixel data type is not supported.
cpl.core.IllegalInputError – If the requested extension number is invalid (negative), the plane number is out of range, or if the given image region is invalid.
cpl.core.DataNotFoundError – If the specified extension has no image data.

logarithm(self: cpl.core.Image, base: float) → None¶

Compute the elementwise logarithm of the image. Modified in place.

Modifies the image by computing the base-scalar logarithm of each of its pixels.

Images can be of type cpl.core.Type.INT, cpl.core.Type.FLOAT or cpl.core.Type.DOUBLE.

Pixels for which the logarithm is not defined are rejected and set to zero.

Parameters:

base (float) – Base of the logarithm.

Raises:

cpl.core.InvalidTypeError – if the image type is not supported
cpl.core.IllegalInputError – if base is non-positive

move(self: cpl.core.Image, nb_cut: int, new_pos: List[int]) → None¶

Permute tiles in an image

nb_cut^2 defines in how many tiles the images will be permuted. Each tile will then be moved to another place defined in new_pos. nb_cut equal 1 will leave the image unchanged, 2 is used to permute the four image quadrants, etc.. new_pos contains nb_cut^2 values between 1 and nb_cut^2, i.e. a permutation of the values from 1 to nb_cut^2. The zone positions are counted from the lower left part of the image. It is not allowed to move two tiles to the same position (the relation between th new tiles positions and the initial position is bijective !). The array with the permuted positions must contain nb_cut^2 values, the function is unable to verify this.

The image x and y sizes have to be multiples of nb_cut.

16 17 18 6 5 4 13 14 15 3 2 1

10 11 12 —-> 12 11 10 7 8 9 9 8 7

4 5 6 18 17 16 1 2 3 15 14 13

image 3x6 image.move(3, new_pos); with new_pos = [9,8,7,6,5,4,3,2,1];

The bad pixels are moved in the same way.

Parameters:

nb_cut (int) – The number of cuts in x and y
new_pos (list of ints) – Array with the nb_cut^2 permuted positions

Raises:

cpl.core.IllegalInputError – if nb_cut is not strictly positive or cannot divide one of the image sizes or if the new_pos array specifies to move two tiles to the same position.
cpl.core.InvalidTypeError – if the image type is not supported

Notes

The permutation array _must_ contain nb_cut-squared elements

multiply(self: cpl.core.Image, other: cpl.core.Image) → None¶

Multiply self by another image

Parameters:

other (cpl.core.Image) – Image to multiply with self

Raises:

cpl.core.IncompatibleInputError – if the input images have different sizes
cpl.core.TypeMismatchError – if the other has complex type

multiply_scalar(self: cpl.core.Image, scalar: float) → None¶

Elementwise multiplication of an image with a scalar. Modified in place.

Parameters:: scalar (float) – Number to multiply with

negate(self: cpl.core.Image) → None¶

Takes the bit-wise complement (NOT) of the image, pixel by pixel.

The image must be integer type. The NOT is doen in place, overwriting the original image.

Raises:: cpl.core.InvalidTypeError – If the image’s type is not cpl.core.Type.INT

normalise(self: cpl.core.Image, mode: cpl.core.Image.Normalise) → None¶

Normalise pixels in an image. Modified in place.

Normalises an image according to a given criterion.

Possible normalisations are: - cpl.core.Image.Normalise.SCALE sets the pixel interval to [0,1]. - cpl.core.Image.Normalise.MEAN sets the mean value to 1. - cpl.core.Image.Normalise.FLUX sets the flux to 1. - cpl.core.Image.Normalise.ABSFLUX sets the absolute flux to 1.

Parameters:: mode (cpl.core.Image.Normalise) – Normalisation mode.

or_scalar(self: cpl.core.Image, value: int) → None¶

The bit-wise OR of a scalar and an image with integer pixels. Modified in place.

Parameters:: value (int) – scalar value to bit-wise OR with the pixels

Notes

cpl.core.Type.INT is required

or_with(self: cpl.core.Image, other: cpl.core.Image) → None¶

Takes the bit-wise OR of the image with another image, pixel by pixel.

Both images must be integer type. The OR is done in place, overwriting the original image.

Parameters:

other (cpl.core.Image) – Second operand

Raises:

cpl.core.IncompatibleInputError – if the images have different sizes
cpl.core.InvalidTypeError – If either image type is not cpl.core.Type.INT

power(self: cpl.core.Image, exponent: float) → None¶

Compute the elementwise power of the image.

Modifies the image by lifting each of its pixels to exponent.

Images can be of type cpl.core.Type.INT, cpl.core.Type.FLOAT or cpl.core.Type.DOUBLE.

Pixels for which the power to the given exponent is not defined are rejected and set to zero.

Parameters:: exponent (float) – Scalar exponent.

rebin(self: cpl.core.Image, ystart: int, xstart: int, ystep: int, xstep: int) → cpl.core.Image¶

Rebin an image

If both bin sizes in x and y are = 2, an image with (about) a quarter of the pixels of the input image will be created. Each new pixel will be the sum of the values of all contributing input pixels. If a bin is incomplete (i.e., the input image size is not a multiple of the bin sizes), it is not computed.

xstep and ystep must not be greater than the sizes of the rebinned region.

The input image type can be cpl.core.Type.INT, cpl.core.Type.FLOAT and cpl.core.Type.DOUBLE. If the image has bad pixels, they will be propagated to the rebinned image “pessimistically”, i.e., if at least one of the contributing input pixels is bad, then the corresponding output pixel will also be flagged “bad”. If you need an image of “weights” for each rebinned pixel, just cast the input image bpm into a cpl.core.Type.INT image, and apply cpl.core.Image.rebin() to it too.

Parameters:

ystart (int) – start y position of binning (starting from 0…)
xstart (int) – start x position of binning (starting from 0…)
ystep (int) – Bin size in y.
xstep (int) – Bin size in x.

Returns:

New rebinned image

Return type:

Raises:

cpl.core.IllegalInputError – if xstep, ystep, xstart, ystart are not positive
cpl.core.InvalidTypeError – if the image type is not supported

reject(self: cpl.core.Image, y: int, x: int) → None¶

Set a pixel as bad in an image

Parameters:

y (int) – the y pixel position in the image (first pixel is 0)
x (int) – the x pixel position in the image (first pixel is 0)

Raises:

cpl.core.AccessOutOfRangeError – if the specified position is outside of the image

reject_from_mask(self: cpl.core.Image, map: object) → None¶

Set the bad pixels in an image as defined in a mask

If the input image has a bad pixel map prior to the call, it is overwritten.

Parameters:: map (cpl.core.Mask) – the mask defining the bad pixels
Raises:: cpl.core.IncompatibleInputError – if the image and the map have different sizes

reject_value(self: cpl.core.Image, values: set) → None¶

Reject pixels with the specified special value(s)

Parameters:

values (set) – The set of special values that should be marked as rejected pixels. The supported special values are 0, math.inf, -math.inf, math.nan and their numpy equivalents, and any combination is allowed.

Raises:

cpl.core.UnsupportedModeError – If something other than one of the supported special values is in the values parameter.
cpl.core.InvalidTypeError – If the image is a complex type.

save(self: cpl.core.Image, filename: str, pl: cpl::core::PropertyList, mode: int, dtype: cpl.core.Type = <Type.UNSPECIFIED: 1048576>) → None¶

Save an image to a FITS file

This function saves an image to a FITS file. If a property list is provided, it is written to the header where the image is written.

Supported image types are cpl.core.Type.DOUBLE, cpl.core.Type.FLOAT, cpl.core.Type.INT.

The type used in the file can be one of: cpl.core.Type.UCHAR (8 bit unsigned), cpl.core.Type.SHORT (16 bit signed), cpl.core.Type.USHORT (16 bit unsigned), cpl.core.Type.INT (32 bit signed), cpl.core.Type.FLOAT (32 bit floating point), or cpl.core.Type.DOUBLE (64 bit floating point). By default the saved type is cpl.core.Type.UNSPECIFIED. This value means that the type used for saving is the pixel type of the input image. Using the image pixel type as saving type ensures that the saving incurs no loss of information.

Supported output modes are cpl.core.io.CREATE (create a new file) and cpl.core.io.EXTEND (append a new extension to an existing file)

Note that in append mode the file must be writable (and do not take for granted that a file is writable just because it was created by the same application, as this depends from the system umask).

The output mode cpl.core.io.EXTEND can be combined (via bit-wise OR) with an option for tile-compression. This compression is lossless. The options are: cpl.core.io.COMPRESS_GZIP, cpl.core.io.COMPRESS_RICE, cpl.core.io.COMPRESS_HCOMPRESS, cpl.core.io.COMPRESS_PLIO.

Upon success the image will reside in a FITS data unit with NAXIS = 2. Is it possible to save a single image in a FITS data unit with NAXIS = 3

Parameters:

filename (str) – Name of the file to write
pl (cpl.core.PropertyList, optional) – Property list for the output header. None by default.
mode (unsigned int) – Desired output options, determined by bit-wise OR of cpl.core.io enums
dtype (cpl.core.Type, optional) – The type used to represent the data in the file. By default it saves using the image’s current dtype

Raises:

cpl.core.IllegalInputError – if the type or the mode is not supported
cpl.core.InvalidTypeError – if the passed pixel type is not supported
cpl.core.FileNotCreatedError – If the output file cannot be created
cpl.core.FileIOError – if the data cannot be written to the file

See also

cpl.core.ImageList.save: for saving imagelists to a fits file

set_pixel(self: cpl.core.Image, y: int, x: int, value: float | int | float | complex | complex) → None¶

Set a pixel at the specified coordinates.

This is equivalent to setting the pixel via image index using im[y][x] = value

Parameters:

y (int) – Row to extract value, 0 being the BOTTOMmost row of the image
x (int) – Column to extract value. 0 being the leftmost column of image
value (int, float, complex) – Value to set. Must be compatible with the image type (int, float for numerical, complex for complex)

Raises:

cpl.core.AccessOutOfRangeError – if the passed position is not within the image.
cpl.core.InvalidTypeError – If the type value is not compatible with the image type of self

Set a list of pixel data from the image from a given index along the image.

Indices are in reference to a 1D representation of the image starting from 0. When converting from 2D coordinates this is equal to (row*width+column)

Some input pixels can be set to None to set as bad instead of setting a value. This will be reflected in the corresponding location in the bad pixel map.

Parameters:

pixels (int) – length number of values to set in the image starting from pixel index
index (int) – Zero-based index along the Image data to begin setting pixel data. When converting from 2D coordinates this is equal to (row*width+column)

Raises:

cpl.core.AccessOutOfRangeError – If the range specified using index and length is outside of the image.

shift(self: cpl.core.Image, dy: int, dx: int) → None¶

Shift an image by integer offsets

The new zones (in the result image) where no new value is computed are set to 0 and flagged as bad pixels. The shift values have to be valid: -nx < dx < nx and -ny < dy < ny

Parameters:

dy (int) – The shift in Y
dx (int) – The shift in X

Raises:

cpl.core.IllegalInputError – if the requested shift is bigger than the

split_abs_arg(self: cpl.core.Image) → Tuple[cpl.core.Image, cpl.core.Image]¶

Split this complex image into its absolute and argument part(s)

Any bad pixels are also processed.

The split creates new image instances and will not modify the original image

Returns:: absolute and argument parts of the image in the format (absolute, argument)
Return type:: tuple(cpl.core.Image, cpl.core.Image)
Raises:: cpl.core.InvalidTypeError – If the image is not of a complex type

Notes

This corresponds to the cpl_image_fill_abs_arg function in the CPL C API

split_real_imag(self: cpl.core.Image) → Tuple[cpl.core.Image, cpl.core.Image]¶

Split this complex image into its real and/or imaginary part(s)

Any bad pixels are also processed.

The split creates new image instances and will not modify the original image

Returns:: Real and Imaginary parts of the image in the format (real, imaginary). Images will be of type cpl.core.Type.DOUBLE if self is of type cpl.core.Type.DOUBLE_COMPLEX. Likewise images will be of type cpl.core.Type.FLOAT if self is of type cpl.core.Type.FLOAT_COMPLEX.
Return type:: tuple(cpl.core.Image, cpl.core.Image)
Raises:: cpl.core.InvalidTypeError – If the image is not of a complex type

Notes

This corresponds to the cpl_image_fill_re_im function in the CPL C API

subtract(self: cpl.core.Image, other: cpl.core.Image) → None¶

Subtract image values from self

Parameters:

other (cpl.core.Image) – Image to subtract from self

Raises:

cpl.core.IncompatibleInputError – if the input images have different sizes
cpl.core.TypeMismatchError – if the other has complex type

subtract_scalar(self: cpl.core.Image, scalar: float) → None¶

Elementwise subtraction of a scalar from an image. Modified in place.

Parameters:: scalar (float) – Number to subtract

threshold(self: cpl.core.Image, assign_lo_cut: float, assign_hi_cut: float, lo_cut: float | None = None, hi_cut: float | None = None) → None¶

Threshold an image to a given interval. Thresholding is performed inplace.

Pixels outside of the provided interval are assigned the given values.

By default lo_cut and hi_cut are set to the minimum and maximum value of the image data type. Therefore assign_lo_cut will not be applied to any pixels if lo_cut is also not set, and assign_hi_cut will not be applied to any pixels if hi_cut is also not set.

Images can be of type cpl.core.Type.INT, cpl.core.Type.FLOAT or cpl.core.Type.DOUBLE. lo_cut must be smaller than or equal to hi_cut.

Parameters:

assign_lo_cut (float) – Value to assign to pixels below low bound.
assign_hi_cut (float) – Value to assign to pixels above high bound.
lo_cut (float, optional) – Lower bound.
hi_cut (float, optional) – Higher bound.

Raises:

cpl.core.InvalidTypeError – if the image type is not supported

to_type(self: cpl.core.Image, dtype: cpl.core.Type) → cpl.core.Image¶

Convert an image to a given type. Modified in place.

Casting to non-complex types is only supported for non-complex types.

Parameters:

dtype (cpl.core.Type) – The destination type

Returns:

New image that is a copy of the original image converted to the given dtype

Return type:

Raises:

cpl.core.IllegalInputError – If the passed type is invalid
cpl.core.TypeMismatchError – If the image type is complex and requested casting type is non-complex.

See also

cpl.core.Image.cast: Get the minimum pixel value over the entire image

turn(self: cpl.core.Image, rot: int) → None¶

Rotate an image by a multiple of 90 degrees clockwise.

Images can be of type cpl.core.Type.INT, cpl.core.Type.FLOAT or cpl.core.Type.DOUBLE.

The definition of the rotation relies on the PyCPL convention: The lower left corner of the image is at (0,0), x increasing from left to right, y increasing from bottom to top.

For rotations of +90 or -90 degrees on rectangular non-1D-images, the pixel buffer is temporarily duplicated.

rot may be any integer value, its modulo 4 determines the rotation:

-3 to turn 270 degrees counterclockwise. -2 to turn 180 degrees counterclockwise. -1 to turn 90 degrees counterclockwise. 0 to not turn +1 to turn 90 degrees clockwise (same as -3) +2 to turn 180 degrees clockwise (same as -2). +3 to turn 270 degrees clockwise (same as -1).

Parameters:: rot (int) – Number of clockwise rotations. -1 is a rotation of 90 deg counterclockwise.
Raises:: cpl.core.InvalidTypeError – if the image type is not supported e

vector_from_column(self: cpl.core.Image, pos: int) → cpl::core::Vector¶

Extract a column from an image.

Images can be of type cpl.core.Type.INT, cpl.core.Type.FLOAT or cpl.core.Type.DOUBLE.

The bad pixels map is not taken into account in this function.

Parameters:

pos (int) – Position of the column (0 for leftmost column)

Returns:

Vector of values from column pos of the image

Return type:

Raises:

cpl.core.IllegalInputError – pos is not valid
cpl.core.IllegalTypeError – If the image is a type that is not supported

vector_from_row(self: cpl.core.Image, pos: int) → cpl::core::Vector¶

Extract a row from an image.

Images can be of type cpl.core.Type.INT, cpl.core.Type.FLOAT or cpl.core.Type.DOUBLE.

The bad pixels map is not taken into account in this function.

Parameters:

pos (int) – Position of the row (0 for bottom row)

Returns:

Vector of values from row pos of the image

Return type:

Raises:

cpl.core.IllegalInputError – pos is not valid
cpl.core.IllegalTypeError – If the image is a type that is not supported

warp(self: cpl.core.Image, deltay: cpl.core.Image, deltax: cpl.core.Image, yprofile: cpl::core::Vector, yradius: float, xprofile: cpl::core::Vector, xradius: float) → cpl.core.Image¶

Generate a warped version of this image

Parameters:

deltax (int) – The x shift of each pixel, must be same size as deltay and type cplcore.Type.DOUBLE
deltay (int) – The y shift of each pixel, must be same size as deltax and type cplcore.Type.DOUBLE
xprofile (cpl.core.Vector) – Interpolation weight as a function of the distance in Y
xradius (float) – Positive inclusion radius in the X-dimension
yprofile (cpl.core.Vector) – Interpolation weight as a function of the distance in Y
yradius (float) – Positive inclusion radius in the Y-dimension
xprofile – Interpolation weight as a function of the in X
xradius – Positive inclusion radius in the X-dimension

Returns:

new warped image, same size as deltax and deltay and same type as self

Return type:

Raises:

cpl.core.IllegalInputError – if the input images sizes are incompatible or if the delta images are not of type cplcore.Type.DOUBLE
cpl.core.InvalidTypeError – if the image type is not supported

See also

cpl.core.Image.create_jacobian: Compute area change ratio for a transformation map.

Notes

The pixel value at the (integer) position (u, v) in the destination image is interpolated from the (typically non-integer) pixel position (x, y) in the source image, where:

x = u - deltax(u, v), y = v - deltay(u, v).

The identity transform is thus given by deltax and deltay filled with zeros.

deltax and deltay may be a different size than self, but must be the same size as each other.

self may be of the type cplcore.Type.INT, cplcore.Type.FLOAT or cplcore.Type.DOUBLE

If case a correction for flux conservation is required please create a correction map using the function cpl.core.Image.create_jacobian().

warp_polynomial(self: cpl.core.Image, poly_y: cpl::core::Polynomial, poly_x: cpl::core::Polynomial, yprofile: cpl::core::Vector, yradius: float, xprofile: cpl::core::Vector, xradius: float, out_dim: Optional[Tuple[int, int]] = None, out_type: Optional[cpl.core.Type] = None) → cpl.core.Image¶

Warp an image according to a 2D polynomial transformation.

Parameters:

poly_y (cpl.dfs.Polynomial) – Polynomial defining source y-pos corresponding to destination (u,v).
poly_x (cpl.dfs.Polynomial) – Polynomial defining source x-pos corresponding to destination (u,v).
yprofile (cpl.dfs.Vector) – Interpolation weight vector as a function of the distance in Y
yradius (float) – Positive inclusion radius in the Y-dimension
xprofile (cpl.dfs.Vector) – Interpolation weight as a function of the distance in X
xradius (float) – Positive inclusion radius in the X-dimension
out_dim ((size, size)) – output dimensions. If not given then will default to the same dimensions of self
out_type (cpl.core.Type) – Output type. If not given then will default to the same type of self. Will cause errors if output type is not compatible with input

Returns:

New warped image

Return type:

Notes

‘out’ and ‘in’ may have different dimensions and types.

The pair of 2D polynomials are used internally like this:

x = poly_x.eval(cpl.core.Vector([u,v]))
y = poly_y.eval(cpl.core.Vector([u,v]))

where (u,v) are (integer) pixel positions in the destination image and (x,y) are the corresponding pixel positions (typically non-integer) in the source image.

The identity transform (poly_x(u,v) = u, poly_y(u,v) = v) would thus overwrite the ‘out’ image with the ‘in’ image, starting from the lower left if the two images are of different sizes.

Beware that extreme transformations may lead to blank images.

The input image type can be cpl.core.Type.INT, cpl.core.Type.FLOAT and cpl.core.Type.DOUBLE.

In case a correction for flux conservation were required, please create a correction map using the function cpl.core.Image.create_jacobian_polynomial().

Raises:

cpl.core.IllegalInputError – if the polynomial dimensions are not 2
cpl.core.InvalidTypeError – if the output image type is incompatible with the input image

xor_scalar(self: cpl.core.Image, value: int) → None¶

The bit-wise XOR of a scalar and an image with integer pixels. Modified in place.

Parameters:: value (int) – scalar value to bit-wise XOR with the pixels

Notes

cpl.core.Type.INT is required

xor_with(self: cpl.core.Image, other: cpl.core.Image) → None¶

Takes the bit-wise XOR of the image with another image, pixel by pixel.

Both images must be integer type. The XOR is done in place, overwriting the original image.

Parameters:

other (cpl.core.Image) – Second operand

Raises:

cpl.core.IncompatibleInputError – if the images have different sizes
cpl.core.InvalidTypeError – If either image type is not cpl.core.Type.INT

static zeros(width: int, height: int, dtype: cpl.core.Type) → cpl.core.Image¶

Create an image of width × height dimensions, all 0’s, as type dtype

Parameters:

width (int) – width of the new image
height (int) – height of the new image
dtype (cpl.core.Type) – Type of the new image (see supported cpl.core.Types in class summary)

Returns:

New width x height image of dtype initialised with all 0’s

Return type:

Raises:

cpl.core.InvalidTypeError – dtype is not a supported image type.

static zeros_like(other: cpl.core.Image) → cpl.core.Image¶

Create an image filled with 0’s with width, height and type matching another image.

Parameters:: other (cpl.core.Image) – Other Image with the desired width, height and data type.
Returns:: New Image initialised with all 0’s
Return type:: cpl.core.Image

property bpm¶

Bad Pixel Mask of this image to mark locations of bad pixels often used during filtering

Type:: cpl.core.Mask

property height¶

height of the image

Type:: int

property is_complex¶

True if the image is of type cpl.core.Type.FLOAT_COMPLEX or cpl.core.Type.DOUBLE_COMPLEX

Type:: bool

property shape¶

tuple detailing the shape of the image in the format (height, width)

Type:: tuple(int, int)

property size¶

Total number of pixels in the image (width*height)

Type:: int

property type¶

Pixel type of the image

Type:: cpl.core.Type

property width¶

width of the image

Type:: int

class cpl.core.ImageList¶

This module provides functions to create and use a cpl_imagelist.

A CPL ImageList is an ordered list of CPL Images. All images in a list must have the same pixel-type and the same dimensions.

It is allowed to insert the same image into different positions in the list. Different images in the list are allowed to share the same bad pixel map.

Parameters:

from (iterable of cpl.core.Image, optional) – Images to store in self on init. If not given the ImageList is initialised withou any images.

Raises:

cpl.core.TypeMismatchError – images in from are of varying types
cpl.core.IncompatibleInputError – images in from are of varying sizes

class Collapse¶

Members:

MEAN

MEDIAN

MEDIAN_MEAN

property name¶

class SwapAxis¶

Members:

XZ

YZ

property name¶

add(self: cpl.core.ImageList, other: cpl.core.ImageList) → None¶

Add this ImageList with another. Modified in place.

The two input lists must have the same size, the image number n in the list other is added to the image number n in this list.

Parameters:: other (cpl.core.ImageList) – ImageList to add

add_image(self: cpl.core.ImageList, img: cpl.core.Image) → None¶

Add an image list by an image.

Parameters:: img (cpl.core.Image) – image to add

add_scalar(self: cpl.core.ImageList, value: float) → None¶

Elementwise addition of a scalar to each image in the imlist. Modified in place

Parameters:: value (float) – Number to add
Return type:: None

append(self: cpl.core.ImageList, to_append: cpl.core.Image) → None¶

Append an image to the end of self

It is allowed to insert the same image into two different positions in a list.

To insert an image a specific position then set via index (e.g. self[i] = new_image)

It is not allowed to insert images of different sizes or types into a list.

Parameters:

to_append (cpl.core.Image) – The image to append

Raises:

cpl.core.TypeMismatchError – if to_append and self are of different types
cpl.core.IncompatibleInputError – if to_append and self have different sizes

astype(self: cpl.core.ImageList, dtype: cpl.core.Type) → cpl.core.ImageList¶

Cast an imagelist to a different CPL type

Parameters:: dtype (cpl.core.Type) – Type to cast the imagelist to
Return type:: New ImageList, containing images cast to the specified type

collapse_create(self: cpl.core.ImageList) → cpl.core.Image¶

Average an imagelist to a single image.

The bad pixel maps of the images in the input list are taken into account, the result image pixels are flagged as rejected for those where there were no good pixel at the same position in the input image list.

For integer pixel types, the averaging is performed using integer division.

Returns:: The average Image
Return type:: cpl.core.Image

collapse_median_create(self: cpl.core.ImageList) → cpl.core.Image¶

Create a median image from the Imagelist

The image list can be of type cpl.core.Type.INT, cpl.core.Type.FLOAT and cpl.core.Type.DOUBLE.

On success each pixel in the created image is the median of the values on the same pixel position in the images in the list. If for a given pixel all values in the input image list are rejected the resulting pixel is set to zero and flagged as rejected.

The median is defined here as the middle value of an odd number of sorted samples and for an even number of samples as the mean of the two central values. Note that with an even number of samples the median may not be among the input samples.

Also note that in the case of an even number of integer images the mean value will be computed using integer arithmetic. Cast your integer data to a floating point pixel type if that is not the desired behavior.

Returns:: The median image of the input pixel type
Return type:: cpl.core.Image
Raises:: cpl.core.IllegalInputError – if the image list is not valid

collapse_minmax_create(self: cpl.core.ImageList, nlow: int, nhigh: int) → cpl.core.Image¶

Average with rejection an imagelist to a single image

The input images are averaged, for each pixel position the nlow lowest pixels and the nhigh highest pixels are discarded for the average computation.

The input image list can be of type cpl.core.Type.INT, cpl.core.Type.FLOAT and cpl.core.Type.DOUBLE. The created image will be of the same type.

On success each pixel in the created image is the mean of the non-rejected values on the pixel position in the input image list.

For a given pixel position any bad pixels (i.e. values) are handled as follows: Given n bad values on a given pixel position, n/2 of those values are assumed to be low outliers and n/2 of those values are assumed to be high outliers. Any low or high rejection will first reject up to n/2 bad values and if more values need to be rejected that rejection will take place on the good values. This rationale behind this is to allow the rejection of outliers to include bad pixels without introducing a bias. If for a given pixel all values in the input image list are rejected, the resulting pixel is set to zero and flagged as rejected.

Parameters:

nlow (int) – Number of low rejected values
nhigh (int) – Number of high rejected values

Returns:

The average image

Return type:

Raises:

cpl.core.IllegalInputError – if the input image list is not valid or if the sum of the rejections is not lower than the number of images or if nlow or nhigh is negative
cpl.core.InvalidTypeError – if the passed image list type is not supported

collapse_sigclip_create(self: cpl.core.ImageList, kappalow: float, kappahigh: float, keepfrac: float, mode: cpl.core.ImageList.Collapse) → Tuple[cpl.core.Image, cpl.core.Image]¶

Collapse an imagelist with kappa-sigma-clipping rejection

The collapsing is an iterative process which will stop when it converges (i.e. an iteration did not reject any values for a given pixel) or when the next iteration would reduce the fraction of values to keep to less than or equal to keepfrac.

A call with keepfrac == 1.0 will thus perform no clipping.

Supported modes: cpl.core.ImageList.Collapse.MEAN: The center value of the acceptance range will be the mean. cpl.core.ImageList.Collapse.MEDIAN: The center value of the acceptance range will be the median. cpl.core.ImageList.Collapse.MEDIAN_MEAN: The center value of the acceptance range will be the median in the first iteration and in subsequent iterations it will be the mean.

For each pixel position the pixels whose value is higher than center + kappahigh * stdev or lower than center - kappalow * stdev are discarded for the subsequent center and stdev computation, where center is defined according to the clipping mode, and stdev is the standard deviation of the values at that pixel position. Since the acceptance interval must be non-empty, the sum of kappalow and kappahigh must be positive. A typical call has both kappalow and kappahigh positive.

The minimum number of values that the clipping can select is 2. This is because the clipping criterion is based on the sample standard deviation, which needs at least two values to be defined. This means that all calls with (positive) values of keepfrac less than 2/n will behave the same. To ensure that the values in (at least) i planes out of n are kept, keepfrac can be set to (i - 0.5) / n, e.g. to keep at least 50 out of 100 values, keepfrac can be set to 0.495.

The output pixel is set to the mean of the non-clipped values, regardless of which clipping mode is used. Regardless of the input pixel type, the mean is computed in double precision. The result is then cast to the output-pixel type, which is identical to the input pixel type.

Bad pixels are ignored from the start. This means that with a sufficient number of bad pixels, the fraction of good values will be less than keepfrac. In this case no iteration is performed at all. If there is at least one good value available, then the mean will be based on the good value(s). If for a given pixel position there are no good values, then that pixel is set to zero, rejected as bad and if available the value in the contribution map is set to zero.

The input imagelist can be of type cpl.core.Type.INT, cpl.core.Type.FLOAT and cpl.core.Type.DOUBLE.

Parameters:

kappalow (float) – kappa-factor for lower clipping threshold
kappahigh (float) – kappa-factor for upper clipping threshold
keepfrac (float) – The fraction of values to keep (0.0 < keepfrac <= 1.0)
mode (cpl.core.ImageList.Collapse) – Clipping mode, cpl.core.ImageList.Collapse.MEAN or cpl.core.ImageList.Collapse.MEDIAN

Returns:

The collapsed image and the contribution map as an integer image, i.e. the number of kept (non-clipped) values after the iterative process on every pixel. In the format (collapsed, contribution)

Return type:

tuple(cpl.core.Image, cpl.core.Image)

Raises:

cpl.core.DataNotFoundError – if there are less than 2 images in the list
cpl.core.IllegalInputError – if the sum of kappalow and kappahigh is non-positive,
cpl.core.AccessOutOfRangeError – if keepfrac is outside the required interval which is 0.0 < keepfrac <= 1.0
cpl.core.InvalidTypeError – if the type of the input imagelist is unsupported
cpl.core.UnsupportedModeError – if the passed mode is none of the above listed

divide(self: cpl.core.ImageList, other: cpl.core.ImageList) → None¶

Divide this ImageList with another. Modified in place.

The two input lists must have the same size, the image number n in the list other is divides the image number n in this list.

Parameters:: other (cpl.core.ImageList) – ImageList to divide with

divide_image(self: cpl.core.ImageList, img: cpl.core.Image) → None¶

Divide an image list by an image.

Parameters:: img (cpl.core.Image) – image to divide

divide_scalar(self: cpl.core.ImageList, value: float) → None¶

Elementwise division of each image in the imlist with a scalar.

Parameters:: value (float) – Non-zero number to divide with

dump(self: cpl.core.ImageList, filename: str | None = '', mode: str | None = 'w', window: tuple | None = None, show: bool | None = True) → str¶

Dump the contents of each image in the ImageList to a file, stdout or a string.

This function is intended just for debugging. It prints the contents of an image to the file path specified by filename. If a filename is not specified, output goes to stdout (unless show is False). In both cases the contents are also returned as a string.

Parameters:

filename (str, optional) – File to dump file image contents to
mode (str, optional) – Mode to open the file with. Defaults to “w” (write, overwriting the contents of the file if it already exists), but can also be set to “a” (append, creating the file if it does not already exist or appending to the end of it if it does).
window (tuple(int,int,int,int), optional) – Window to dump with value in the format (llx, lly, urx, ury) where: - llx Lower left X coordinate - lly Lower left Y coordinate - urx Upper right X coordinate - ury Upper right Y coordinate
show (bool, optional) – Send image contents to stdout. Defaults to True.

Returns:

Multiline string containing the dump of the image contents in the ImageList.

Return type:

str

empty(self: cpl.core.ImageList) → None¶

Empty an imagelist and deallocate all its images

After the call the image list can be populated again.

exponential(self: cpl.core.ImageList, base: float) → None¶

Compute the elementwise exponential of each image in self. Modified in place.

Parameters:: base (float) – Base of the exponential.

insert(self: cpl.core.ImageList, position: int, item: cpl.core.Image) → None¶

Insert an image into the index position. This will increase the imagelist size by 1

Parameters:

position (int) – index to insert Image
item (cpl.core.Image) – Image to insert

is_uniform(self: cpl.core.ImageList) → bool¶

Determine if an imagelist contains images of equal size and type

The function raises an error if the imagelist is empty (see Raises)

Returns:: True if uniform, otherwise false
Return type:: bool
Raises:: cpl.core.IllegalInputError – If the imagelist is empty

static load(filename: str, dtype: cpl.core.Type = <Type.DOUBLE: 131072>, extension: int = 0, area: tuple = None) → cpl.core.ImageList¶

Load an image list from a file.

Load data from the extension extension of the FITS file filename into a list of images. The FITS extension may be an image (NAXIS = 2) or a data cube (NAXIS = 3). Each image plane in the input data is loaded as a separate image. By default the data is read from the primary HDU of the FITS file.

By default the full area (extent in x and y) of the data is loaded. This may be restricted to a particular region of the data by providing an appropriate argument area.

The argument dtype specifies the pixel data type of the result image list. When the data is loaded the pixel data type in the input FITS file is converted into dtype. By default the data in the input extension is converted to cpl.core.Type.DOUBLE. To load the data without converting the pixel data type use cpl.core.Type.UNSPECIFIED.

Valid pixel data types which may be used for dtype are:

cpl.core.Type.INT (32-bit integer)
cpl.core.Type.FLOAT
cpl.core.Type.DOUBLE

Parameters:

filename (str) – Name of the input file
dtype (cpl.core.Type, optional) – Data type of the pixels in the returend list of images. Is cpl.core.Type.DOUBLE by default.
extension (int, default=0) – Index of the FITS extension to load (the primary data unit has index 0)
Area (Tuple, default=(-1891, -1891, -9012, -9012)) – Region of interest to load given as a tuple specifying the lower left x, the lower left y, the upper right x (inclusive) and the upper right y coordinate (inclusive) in this order. Numbering of the pixel x and y positions starts at 1 (FITS convention)

Returns:

New image list instance of loaded data

Return type:

cpl.core.ImageList

Raises:

cpl.core.FileIOError – If the file cannot be opened, or does not exist.
cpl.core.BadFileFormatError – If the data cannot be loaded from the file.
cpl.core.InvalidTypeError – If the requested pixel data type is not supported.
cpl.core.IllegalInputError – If the requested extension number is invalid (negative), the plane number is out of range, or if the given image region is invalid.
cpl.core.DataNotFoundError – If the specified extension has no image data.

multiply(self: cpl.core.ImageList, other: cpl.core.ImageList) → None¶

Elementwise multiply this ImageList with another. Modified in place.

The two input lists must have the same size, the image number n in the list other is multiplyed with the image number n in this list.

Parameters:: other (cpl.core.ImageList) – ImageList to multiply

multiply_image(self: cpl.core.ImageList, img: cpl.core.Image) → None¶

Multiply an image list by an image.

Parameters:: img (cpl.core.Image) – image to multiply

multiply_scalar(self: cpl.core.ImageList, value: float) → None¶

Elementwise multiplication of a scalar to each image in the imlist.

Parameters:: value (float) – Number to multiply with
Return type:: None

normalise(self: cpl.core.ImageList, mode: cpl.core.Image.Normalise) → None¶

Normalize each image in the list. Modified in place.

The list may be partly modified if an error occurs.

Possible normalisations are: - cpl.core.Image.Normalise.SCALE sets the pixel interval to [0,1]. - cpl.core.Image.Normalise.MEAN sets the mean value to 1. - cpl.core.Image.Normalise.FLUX sets the flux to 1. - cpl.core.Image.Normalise.ABSFLUX sets the absolute flux to 1.

Parameters:: mode (cpl.core.Image.Normalise) – Normalization mode.

pop(self: cpl.core.ImageList, position: int | None = None) → cpl.core.Image¶

Remove and return the image at position

Parameters:: position (int, optional) – Index to pop image from the image list. Defaults to the last image.
Raises:: IndexError – If position is out of range

power(self: cpl.core.ImageList, exponent: float) → None¶

Compute the elementwise power of each image in the imlist.

Parameters:: exponent (float) – Scalar exponent

save(self: cpl.core.ImageList, filename: str, pl: cpl::core::PropertyList, mode: int, dtype: cpl.core.Type = <Type.UNSPECIFIED: 1048576>) → None¶

Save an imagelist to a FITS file

This function saves an image list to a FITS file. If a property list is provided, it is written to the named file before the pixels are written.

Image lists are saved as a 3 dimensional data cube.

Supported image types are cpl.core.Type.DOUBLE, cpl.core.Type.FLOAT, cpl.core.Type.INT.

The type used in the file can be one of: cpl.core.Type.UCHAR (8 bit unsigned), cpl.core.Type.SHORT (16 bit signed), cpl.core.Type.USHORT (16 bit unsigned), cpl.core.Type.INT (32 bit signed), cpl.core.Type.FLOAT (32 bit floating point), or cpl.core.Type.DOUBLE (64 bit floating point). By default the saved type is cpl.core.Type.UNSPECIFIED. This value means that the type used for saving is the pixel type of the input image. Using the image pixel type as saving type ensures that the saving incurs no loss of information.

Supported output modes are cpl.core.io.CREATE (create a new file) and cpl.core.io.EXTEND (append a new extension to an existing file)

Note that in append mode the file must be writable (and do not take for granted that a file is writable just because it was created by the same application, as this depends from the system umask).

The output mode cpl.core.io.EXTEND can be combined (via bit-wise OR) with an option for tile-compression. This compression is lossless. The options are: cpl.core.io.COMPRESS_GZIP, cpl.core.io.COMPRESS_RICE, cpl.core.io.COMPRESS_HCOMPRESS, cpl.core.io.COMPRESS_PLIO. With compression the type must be cpl.core.Type.UNSPECIFIED or cpl.core.Type.INT.

In extend and append mode, make sure that the file has write permissions. You may have problems if you create a file in your application and append something to it with the umask set to 222. In this case, the file created by your application would not be writable, and the append would fail.

Parameters:

filename (str) – Name of the file to write
pl (cpl.core.PropertyList, optional) – Property list for the output header. None by default.
mode (unsigned int) – Desired output options, determined by bit-wise OR of cpl.core.io enums
dtype (cpl.core.Type, optional) – The type used to represent the data in the file. By default it saves using the image’s current dtype

Raises:

cpl.core.IllegalInputError – if the type or the mode is not supported
cpl.core.InvalidTypeError – if the passed pixel type is not supported
cpl.core.FileNotCreatedError – If the output file cannot be created
cpl.core.FileIOError – if the data cannot be written to the file

See also

cpl.core.Image.save: for saving individual images to a fits file

subtract(self: cpl.core.ImageList, other: cpl.core.ImageList) → None¶

Elementwise subtract this ImageList with another. Modified in place.

The two input lists must have the same size, the image number n in the list other is subtracted from the image number n in this list.

Parameters:: other (cpl.core.ImageList) – ImageList to subtract with

subtract_image(self: cpl.core.ImageList, img: cpl.core.Image) → None¶

Subtract an image list by an image.

Parameters:: img (cpl.core.Image) – image to subtract

subtract_scalar(self: cpl.core.ImageList, value: float) → None¶

Elementwise subtraction of a scalar to each image in the imlist. Modified in place.

Parameters:: value (float) – Number to subtract

swap_axis_create(self: cpl.core.ImageList, mode: cpl.core.ImageList.SwapAxis) → cpl.core.ImageList¶

This function is intended for users that want to use the ImageList object as a cube.

Swapping the axis would give them access to the usual functions in the 3 dimensions. This has the cost that it duplicates the memory consumption, which can be a problem for big amounts of data.

Image list can be cpl.core.Type.INT, cpl.core.Type.FLOAT or cpl.core.Type.DOUBLE

Parameters:: mode (cpl.core.ImageList.SwapAxis) – The swapping mode. The mode can be either cpl.core.ImageList.SwapAxis.XZ or cpl.core.ImageList.SwapAxis.YZ
Return type:: New image list of the given axis

threshold(self: cpl.core.ImageList, lo_cut: float, hi_cut: float, assign_lo_cut: float, assign_hi_cut: float) → None¶

Threshold all pixel values to an interval.

Threshold the images of the list using cpl_image_threshold() The input image list is modified.

Pixels outside of the provided interval are assigned the given values.

Parameters:

lo_cut (float) – Lower bound.
hi_cut (float) – Higher bound.
assign_lo_cut (float) – Value to assign to pixels below low bound.
assign_hi_cut (float) – Value to assign to pixels above high bound.

class cpl.core.ImageRow¶

Returned from a Image’s __getitem__ method or iterator. Used to access specific rows of the image.

Not instantiatable on its own.

class cpl.core.Kernel¶

Members:

DEFAULT : default kernel, currently cpl.core.Kernel.TANH

TANH : Hyperbolic tangent

SINC : Sinus cardinal

SINC2 : Square sinus cardinal

LANCZOS : Lanczos2 kernel

HAMMING : Hamming kernel

HANN : Hann kernel

NEAREST : Nearest neighbor kernel (1 when dist < 0.5, else 0)

property name¶

class cpl.core.Mask(*args)¶

These masks are useful for object detection routines or bad pixel map handling.

Morphological routines (erosion, dilation, closing and opening) and logical operations are provided.

CPL masks are like a 2d binary array, with each pixel representing True or False, and can be set as such:

m = cpl.core.Mask(3,3)
m[0][0] = True

PyCPL uses 0 indexing, in the sense that the lower left element in a CPL mask has index (0, 0).

collapse_cols()¶: Create a 1-column mask, all elements are the logical AND of each cell in its corresponding column. Height is kept the same.

collapse_rows()¶: Create a 1-row mask, all elements are the logical AND of each cell in its corresponding column. Width is kept the same

copy()¶: Duplicate the mask

count(window=None)¶

Determines number of occurrences of ‘1’ bit in the given window of this bitmask

Parameters:: window (int) – Rectangle to count bits in the format (x1,y1,x2,y2)

dump(filename='', mode='w', window=None, show=True)¶

Dump the mask contents to a file, stdout or a string.

This function is intended just for debugging. It prints the contents of a mask to the file path specified by filename. If a filename is not specified, output goes to stdout (unless show is False). In both cases the contents are also returned as a string.

Parameters:

filename (str, optional) – File to dump mask contents to
mode (str, optional) – Mode to open the file with. Defaults to “w” (write, overwriting the contents of the file if it already exists), but can also be set to “a” (append, creating the file if it does not already exist or appending to the end of it if it does).
window (tuple(int,int,int,int), optional) – Window to dump with value in the format (llx, lly, urx, ury) where: - llx Lower left X coordinate - lly Lower left Y coordinate - urx Upper right X coordinate - ury Upper right Y coordinate Defaults to entire image.
show (bool, optional) – Send mask contents to stdout. Defaults to True.

Returns:

Multiline string containing the dump of the mask contents.

Return type:

str

extract(window)¶

Copies out a window of this mask to a new mask.

Parameters:: window (tuple(int, int, int, int)) – rectangle to extract from this mask in the format (x1,y1, x2, y2)
Raises:: cpl.core.IllegalInputError – if the zone falls outside the mask

filter(kernel, filter, border)¶

Filter the mask using a binary kernel.

The kernel must have an odd number of rows and an odd number of columns, with at least one pixel set to 1

Parameters:

kernel (cpl.core.Mask) – Mask of elements to use (for each pixel set to 1)
filter (cpl.core.Filter) – cpl.core.Filter.EROSION, cpl.core.Filter.DILATION, cpl.core.Filter.OPENING, cpl.core.Filter.CLOSING
border (cpl.core.Border) – cpl.core.Border.NOP, cpl.core.Border.ZERO or cpl.core.Border.COPY

Raises:

cpl.core.DataNotFoundError – If the kernel is empty.
cpl.core.AccessOutOfRangeError – If the kernel has a side longer than the input mask.
cpl.core.UnsupportedModeError – if the border/filter mode is unsupported.

Returns:

filter_output mask same size as input

Return type:

Mask(self._mask.filter(kernel._mask, filter, border))

Notes

For erosion and dilation: In-place filtering is not supported, but the input buffer may overlap all but the 1+h first rows of the output buffer, where 1+2*h is the number of rows in the kernel.

For opening and closing: Opening is implemented as an erosion followed by a dilation, and closing is implemented as a dilation followed by an erosion. As such a temporary, internal buffer the size of self is allocated and used. Consequently, in-place opening and closing is supported with no additional overhead, it is achieved by passing the same mask as both self and other.

Duality and idempotency: Erosion and Dilation have the duality relations: not(dil(A,B)) = er(not(A), B) and not(er(A,B)) = dil(not(A), B).

Opening and closing have similar duality relations: not(open(A,B)) = close(not(A), B) and not(close(A,B)) = open(not(A), B).

Opening and closing are both idempotent, i.e. open(A,B) = open(open(A,B),B) and close(A,B) = close(close(A,B),B).

The above duality and idempotency relations do not hold on the mask border (with the currently supported border modes).

Unnecessary large kernels: Adding an empty border to a given kernel should not change the outcome of the filtering. However doing so widens the border of the mask to be filtered and therefore has an effect on the filtering of the mask border. Since an unnecessary large kernel is also more costly to apply, such kernels should be avoided.

1x3 erosion example:

kernel = ~cpl.core.Mask(1,3)
filtered.filter(kernel,cpl.core.Filter.EROSION,cpl.core.Border.NOP)

flip(axis)¶

Flip a mask on a given mirror line.

Parameters:: axis (int) – angle to mirror line in polar coord. is theta = (PI/4) * angle - 0 (ϑ=0) to flip the image around the horizontal - 1 (ϑ=π∕4) to flip the image around y=x - 2 (ϑ=π∕2) to flip the image around the vertical - 3 (ϑ=3π∕4) to flip the image around y=-x
Raises:: cpl.core.IllegalInputError – if angle is not as specified

insert(to_insert, ypos, xpos)¶

insert a mask into self

Parameters:

to_insert (cpl.core.Mask) – mask to insert into self
ypos (int) – the y pixel position in self where the lower left pixel of to_insert should go (from 0 to the y size of self)
xpos (int) – the x pixel position in self where the lower left pixel of to_insert should go (from 0 to the x size of in self)

Raises:

cpl.core.IllegalInputError – if xpos or ypos is outside self

classmethod load(fitsfile, extension=0, plane=0, window=None)¶

Loads an bitmask from an INTEGER FITS file

Parameters:

fitsfile (str) – filename of fits file
extension (int) – Specifies the extension from which the image should be loaded (Default) 0 is for the main data section (Files without extension)
plane (int) – Specifies the plane to request from the data section. Default 0.
window (tuple(int, int, int, int)) – The rectangle in the format (x1,y1, x2, y2) specifying the subset of the image to load. If None, load the entire window

Raises:

cpl.core.FileIOError – if the file cannot be opened or does not exist
cpl.core.BadFileFormatError – if the data cannot be loaded from the file
cpl.core.IllegalInputError – if the pased extension number is negative
cpl.core.DataNotFoundError – if the specified extension has no mask data

move(nb_cut, positions)¶

Reorganize the pixels in a mask.

nb_cut must be positive and divide the size of the input mask in x and y.

Parameters:

nb_cut (int) – the number of cut in x and y
new_pos (list of integers) – array with the nb_cut^2 new positions

Raises:

cpl.core.IllegalInputError – if nb_cut is not as requested.

rotate(turns)¶

Rotate this mask by a multiple of 90 degrees clockwise

Parameters:: turns (int) – Integral amount of 90 degree turns to execute.

Notes

turns can be any value, its modulo 4 determines rotation:

-3 to turn 270 degrees counterclockwise.
-2 to turn 180 degrees counterclockwise.
-1 to turn 90 degrees counterclockwise.
0 to not turn
+1 to turn 90 degrees clockwise (same as -3)
+2 to turn 180 degrees clockwise (same as -2).
+3 to turn 270 degrees clockwise (same as -1).

The lower left corner of the image is at (0,0), x increasing from left to right, y increasing from bottom to top.

save(filename, pl, mode)¶

Save a mask to a FITS file.

Parameters:

filename (str) – Name of the file to write
pl (cpl.core.PropertyList) – Property list for the output header (Default None)
mode (unsigned int) – Desired output options, determined by bitwise or of cpl.core.io enums

Raises:

cpl.core.IllegalInputError – if the mode is unsupported
cpl.core.NotCreatedError – if the output file cannot be created
cpl.core.FileIOError – if the data cannot be written to the file

Notes

This function saves a mask to a FITS file. If a property list is provided, it is written to the header where the mask is written.

The type used in the file is cpl.core.Type.UCHAR (8 bit unsigned).

Supported output modes are cpl.core.io.CREATE (create a new file) and cpl.core.io.EXTEND (append a new extension to an existing file)

The output mode cpl.core.io.EXTEND can be combined (via bit-wise or) with an option for tile-compression. This compression is lossless. The options are: cpl.core.io.COMPRESS_GZIP, cpl.core.io.COMPRESS_RICE, cpl.core.io.COMPRESS_HCOMPRESS, cpl.core.io.COMPRESS_PLIO.

Note that in append mode the file must be writable (and do not take for granted that a file is writable just because it was created by the same application, as this depends from the system umask)

shift(yshift, xshift)¶

shift a mask

The ‘empty zone’ in the shifted mask is set to True.

The shift values have to be valid: -nx < dx < nx and -ny < dy < ny

Parameters:

yshift (int) – shift in y
xshift (int) – shift in x

Raises:

cpl.core.IllegalInputError – if the offsets are too big

subsample(ystep, xstep)¶

Subsample a mask.

Parameters:

ystep (int) – Take every ystep pixel in y
xstep (int) – Take every xstep pixel in x

Raises:

cpl.core.IllegalInputError – if xstep and ystep are not greater than zero

classmethod threshold_image(image, lo_cut, hi_cut, inval)¶

Create a new Mask by applying the given thresholds to a cpl.core.Image.

Parameters:

image (cpl.core.Image) – Image to threshold
lo_cut (float) – Lower bound for threshold
hi_cut (float) – Uppper bound for threshold
inval (bool) – This value (0 or 1, False or True) is assigned where the pixel value is not marked as rejected and is strictly inside the provided interval. The other positions are assigned the other value.

Raises:

cpl.core.UnsupportedModeError – if the image data type is unsupported
cpl.core.IllegalInputError – if inval is not binary

Notes

The input image type can be cpl.core.Type.DOUBLE, cpl.core.Type.FLOAT or cpl.core.Type.INT.

If lo_cut is greater than or equal to hi_cut, then the mask is filled with outval (opposite of inval).

property height¶: Number of rows high this mask is

property width¶: Number of columns wide this mask is

class cpl.core.Matrix¶

This class provides the ability to create and interface with cpl_matrix. The elements of a cpl_matrix with M rows and N columns are counted from 0,0 to M-1,N-1. The matrix element 0,0 is the one at the upper left corner of a matrix.

The CPL matrix functions work properly only in the case the matrices elements do not contain garbage (such as NaN or infinity).

Parameters:

data (iterable of floats) – A 1d or 2d iterable containing matrix data to copy from. Any iterable should be compatible as long as it implements python’s buffer protocol and only contains values of type float If a 1d iterable is given, rows must also be given to properly split the data into matrix rows.
rows (int, optional) – Width of the new matrix. This will split data into rows number of rows to initialise the the new matrix. Should only be given if data is 1d, otherwise a ValueError exception is thrown.

class ThresholdMode¶

Members:

EPSILON : use machine DBL_EPSILON as the cutoff factor

SIZE : compute the cutoff factor as 10*DBL_EPSILON*max(N, M)

USER : use user-defined value as the cutoff factor

property name¶

add(self: cpl.core.Matrix, other: cpl.core.Matrix) → None¶

Perform matrix addition with other and self

Add matrices self and other element by element. The two matrices must have identical sizes. The result is written to the self.

Parameters:: other (cpl.core.Matrix) – matrix to add with
Raises:: cpl.core.IncompatibleInputError – if other does not have the same size as self

add_scalar(self: cpl.core.Matrix, value: float) → None¶

Add a scalar to self.

Add the same value to each matrix element.

Parameters:: value (float) – Value to add.

append(self: cpl.core.Matrix, other: cpl.core.Matrix, mode: int) → None¶

Append a matrix to another.

If mode is set to 0, the matrices must have the same number of rows, and are connected horizontally with the self on the left. If mode is set to 1, the matrices must have the same number of columns, and are connected vertically with self on top. The self is expanded to include the values from the other, while other is left untouched.

Parameters:

other (cpl.core.Matrix) – matrix to append to self
mode (int) – Matrices connected horizontally (0) or vertically (1).

Raises:

cpl.core.IllegalInputError – mode is neither 0 nor 1
cpl.core.IncompatibleInputError – Matrices cannot be joined as indicated by mode.

copy_values_from(self: cpl.core.Matrix, submatrix: cpl.core.Matrix, row: int, col: int) → None¶

Copy the values from another matrix into self

The values of submatrix are written to self starting at the indicated row and column. There are no restrictions on the sizes of submatrix: just the parts of submatrix overlapping matrix are copied. There are no restrictions on row and col either, that can also be negative. If the two matrices do not overlap, nothing is done, but an error is raised.

Parameters:

submatrix (cpl.core.Matrix) – Pointer to matrix to get the values from.
row (int) – Position of row 0 of submatrix in self.
col (int) – Position of column 0 of submatrix in self.

Raises:

cpl.core.AccessOutOfRangeError – No overlap exists between the two matrices.

decomp_chol(self: cpl.core.Matrix) → None¶

Replace a matrix by its Cholesky-decomposition, L * transpose(L) = A

Notes

Only the upper triangle of self is read, L is written in the lower triangle If the matrix is singular the elements of self become undefined

decomp_lu(self: cpl.core.Matrix) → Tuple[List[int], bool]¶

Replace a matrix by its LU-decomposition

self must be a n X n non-singular matrix to decompose. self will be modified inplace in which its values will be replaced with it’s LU-decomposed values.

The resulting LU decomposition can be solved with cpl.core.Matrix.solve_lu.

Returns:

The pair of n-integer list filled with row permutations (perm) and True/False for even number of permutations (psig). In the format (perm, psig).

Return type:

tuple(List[int], bool)

Raises:

cpl.core.IllegalInputError – self is not an n by n matrix.
cpl.core.SingularMatrixError – self is singular.
cpl.core.IncompatibleInputError – self and perm have incompatible sizes.
cpl.core.TypeMismatchError – perm is not a list of ints

Notes

Algorithm reference: Golub & Van Loan, Matrix Computations, Algorithms 3.2.1 (Outer Product Gaussian Elimination) and 3.4.1 (Gauss Elimination with Partial Pivoting).

See also

cpl.core.Matrix.solve_lu: Used to solve the LU-decomposition

determinant(self: cpl.core.Matrix) → float¶

Compute the determinant of a matrix.

self must be a square matrix. In case of a 1x1 matrix, the matrix single element value is returned.

Returns:

Matrix determinant

Return type:

float

Raises:

cpl.core.IllegalInputError – self is not square.
cpl.core.UnspecifiedError – self is near-singular with a determinant so close to zero that it cannot be represented by a double.

divide(self: cpl.core.Matrix, other: cpl.core.Matrix) → None¶

Divide self by other, element by element.

Divide each element of self by the corresponding element of the second one. The two matrices must have the same number of rows and columns. The result is written to the first matrix. No check is made against a division by zero.

Parameters:: other (cpl.core.Matrix) – matrix to divide with
Raises:: cpl.core.IncompatibleInputError – if other does not have the same size as self

divide_scalar(self: cpl.core.Matrix, value: float) → None¶

Divide self by a scalar.

Divide each matrix element by the same value.

Parameters:: value (float) – Divisor.
Raises:: cpl.core.DivisionByZeroError – value is 0.0

dump(self: cpl.core.Matrix, filename: str | None = '', mode: str | None = 'w', show: bool | None = True) → str¶

Dump the matrix contents to a file, stdout or a string.

This function is intended just for debugging. It just prints the elements of a matrix, ordered in rows and columns to the file path specified by filename. If a filename is not specified, output goes to stdout (unless show is False).

Parameters:

filename (str, optional) – File to dump matrix contents to
mode (str, optional) – Mode to open the file with. Defaults to “w” (write, overwriting the contents of the file if it already exists), but can also be set to “a” (append, creating the file if it does not already exist or appending to the end of it if it does).
show (bool, optional) – Send matrix contents to stdout. Defaults to True.

Returns:

Multiline string containing the dump of the matrix contents.

Return type:

str

erase_columns(self: cpl.core.Matrix, start: int, count: int) → None¶

Delete columns from a matrix.

A portion of the matrix data is removed. The specified segment can extend beyond the end of the matrix, but an attempt to remove all matrix columns will raise an exception because zero length matrices are illegal. Columns are counted starting from 0.

Parameters:

start (int) – First column to delete.
count (int) – Number of columns to delete.

Raises:

cpl.core.AccessOutOfRangeError – The specified start is outside the matrix boundaries.
cpl.core.IllegalInputError – count is not positive.
cpl.core.IllegalOutputError – Attempt to delete all the columns of matrix.

erase_rows(self: cpl.core.Matrix, start: int, count: int) → None¶

Delete rows from a matrix.

A select number of rows will be completely removed from the object, reducing the total number of rows by 1. The specified segment can extend beyond the end of the matrix, but an attempt to remove all matrix rows will raise an exception because zero length matrices are illegal. Rows are counted starting from 0.

Parameters:

start (int) – First row to delete.
count (int) – Number of rows to delete.

Raises:

cpl.core.AccessOutOfRangeError – The specified start is outside the matrix boundaries.
cpl.core.IllegalInputError – count is not positive.
cpl.core.IllegalOutputError – Attempt to delete all the rows of matrix.

exponential(self: cpl.core.Matrix, base: float) → None¶

Compute the exponential of matrix elements.

Each matrix element is replaced by its exponential in the specified base. The base must be positive.

Parameters:: base (float) – Exponential base.
Raises:: cpl.core.IllegalInputError – base is not positive

extract_column(self: cpl.core.Matrix, column: int) → cpl.core.Matrix¶

Copy a matrix column.

If a MxN matrix is given in input, the extracted row is a new Mx1 matrix. The column number is counted from 0.

Parameters:: column (int) – Sequence number of column to copy.
Returns:: Mx1 Matrix containing the extracted column values.
Return type:: cpl.core.Matrix
Raises:: cpl.core.AccessOutOfRangeError – The column is outside the matrix boundaries.

extract_diagonal(self: cpl.core.Matrix, diagonal: int) → cpl.core.Matrix¶

Extract a matrix diagonal.

If a MxN matrix is given in input, the extracted diagonal is a Mx1 matrix if \(N >= M\), or a 1xN matrix if \(N < M\). The diagonal number is counted from 0, corresponding to the matrix diagonal starting at element (0,0). A square matrix has just one diagonal; if M != N, the number of diagonals in the matrix is \(|M - N|\) + 1. To specify a diagonal sequence number outside this range raises a cpl.core.AccessOutOfRangeError

Parameters:: diagonal (int) – Sequence number of the diagonal to copy.
Returns:: matrix with either 1xN or Mx1 dimensions containing the extracted diagonal.
Return type:: cpl.core.Matrix
Raises:: cpl.core.AccessOutOfRangeError: – If the diagonal is outside the matrix boundaries

extract_row(self: cpl.core.Matrix, row: int) → cpl.core.Matrix¶

Extract a matrix row.

If a MxN matrix is given in input, the extracted row is a new 1xN matrix. The row number is counted from 0.

Parameters:: row (int) – Sequence number of row to copy.
Returns:: New matrix representing the row.
Return type:: cpl.core.Matrix
Raises:: cpl.core.AccessOutOfRangeError – The row is outside the matrix boundaries.

fill(self: cpl.core.Matrix, value: float) → None¶

Write the same value to all matrix elements.

Parameters:: value (float) – Value to write

fill_column(self: cpl.core.Matrix, value: float, column: int) → None¶

Write the same value to a matrix column.

Write the same value to a matrix column. Columns are counted starting from 0.

Parameters:

value (float) – Value to write
column (int) – Sequence number of column to overwrite

Raises:

cpl.core.AccessOutOfRangeError – The specified column is outside the matrix boundaries.

fill_diagonal(self: cpl.core.Matrix, value: float, diagonal: int) → None¶

Write a given value to all elements of a given matrix diagonal.

Parameters:

value (float) – Value to write to diagonal
diagonal (int) – Number of diagonal to overwrite, 0 for main, positive for above main, negative for below main. main is the diagonal starting from (0, 0) on the matrix.

Raises:

cpl.core.AccessOutOfRangeError – The specified diagonal is outside the matrix boundaries.

fill_row(self: cpl.core.Matrix, value: float, row: int) → None¶

Write the same value to a matrix row.

Write the same value to a matrix row. Rows are counted starting from 0.

Parameters:

value (float) – Value to write
row (int) – Sequence number of row to overwrite.

Raises:

cpl.core.AccessOutOfRangeError – The specified row is outside the matrix boundaries.

fill_window(self: cpl.core.Matrix, value: float, row: int, col: int, nrow: int, ncol: int) → None¶

Write the same value into a submatrix of a matrix.

The specified value is written to self starting at the indicated row and column; nrow and ncol can exceed self boundaries, just the range overlapping the self is used in that case.

Parameters:

value (float) – Value to write.
row (int) – Start row of matrix submatrix.
col (int) – Start column of matrix submatrix.
nrow (int) – Number of rows of matrix submatrix.
ncol (int) – Number of columns of matrix submatrix.

Raises:

cpl.core.AccessOutOfRangeError – The specified start position is outside the matrix boundaries.
cpl.core.IllegalInputError – nrow or ncol are not positive.

flip_columns(self: cpl.core.Matrix) → None¶

Reverse order of columns in matrix.

The order of the columns in the matrix is reversed in place.

flip_rows(self: cpl.core.Matrix) → None¶

Reverse order of rows in matrix.

The order of the rows in the matrix is reversed in place.

invert_create(self: cpl.core.Matrix) → cpl.core.Matrix¶

Find a matrix inverse of self

self must be a square matrix.

Returns:: Inverse matrix.
Return type:: cpl.core.Matrix

Notes

When calling invert_create() with a nearly singular matrix, it is possible to get a result containin NaN values without any error code being set.

is_diagonal(self: cpl.core.Matrix, tolerance: float | None = None) → None¶

Check if a matrix is diagonal.

A threshold may be specified to consider zero any number that is close enough to zero. If the specified tolerance is negative (default), the default value is used, equal to the machine double epsilon. A zero tolerance may also be specified.

No error is raised if the self is not square.

Parameters:: tolerance (float) – Max tolerated rounding to zero. If not given the machine double epsilon is used.
Returns:: True if self is a diagonal matrix. False otherwise
Return type:: bool
Raises:: cpl.core.IllegalInputError – if the matrix is not square

Notes

If tolerance is given a negative value, the default value for tolerance will be used (machine double epsilon).

is_identity(self: cpl.core.Matrix, tolerance: float | None = None) → None¶

Check for identity matrix.

A threshold may be specified to consider zero any number that is close enough to zero, and 1 any number that is close enough to 1. If tolerance is not given, the default value is used, equal to the machine double epsilon. A zero tolerance may also be specified.

No error is raised if the self is not square.

Parameters:: tolerance (float, optional) – Max tolerated rounding to zero, or to one. If not given the machine double epsilon is used.
Returns:: True if self is a identity matrix. False otherwise
Return type:: bool
Raises:: cpl.core.IllegalInputError – if the matrix is not square

Notes

If tolerance is given a negative value, the default value for tolerance will be used (machine double epsilon).

is_zero(self: cpl.core.Matrix, tolerance: float | None = None) → None¶

Check for zero matrix.

After specific manipulations of a matrix some of its elements may theoretically be expected to be zero. However, because of numerical noise, such elements may turn out not to be exactly zero. In this specific case, if any of the matrix element is not exactly zero, the matrix would not be classified as a null matrix. A threshold may be specified to consider zero any number that is close enough to zero.

If no tolerance is given then the default value is used, equal to the machine double epsilon.

Parameters:: tolerance (float) – Max tolerated rounding to zero. If not given the machine double epsilon is used.
Returns:: True if self is a zero matrix. False otherwise
Return type:: bool

Notes

If tolerance is given a negative value, the default value for tolerance will be used (machine double epsilon).

logarithm(self: cpl.core.Matrix, base: float) → None¶

Compute the logarithm of matrix elements.

Each matrix element is replaced by its logarithm in the specified base. The base and all matrix elements must be positive.

Parameters:: base (float) – Logarithm base.
Raises:: cpl.core.IllegalInputError – base or any element of self is not positive

max(self: cpl.core.Matrix) → float¶

Find the maximum value of all matrix elements.

The maximum value of matrix elements is found.

Returns:: Maximum value in the matrix
Return type:: float

maxpos(self: cpl.core.Matrix) → Tuple[int, int]¶

Find position of maximum value of matrix elements.

The position of the maximum value of all matrix elements is found. If more than one matrix element have a value corresponding to the maximum, the lowest element row number is returned in row. If more than one maximum matrix elements have the same row number, the lowest element column number is returned in column.

Returns:: tuple in the format (row, column), where: - row is the returned row position of maximum. - column is the returned column position of maximum
Return type:: tuple(int, int)

mean(self: cpl.core.Matrix) → float¶

Find the mean of all matrix elements.

The mean of all matrix elements is calculated

Returns:: Mean of all matrix elements
Return type:: float

Notes

This function works properly only if all elements of the matrix have finite values (not NaN or Infinity).

median(self: cpl.core.Matrix) → float¶

Find the median of all matrix elements.

The median of all matrix elements is calculated

Returns:: Median of all matrix elements
Return type:: float

min(self: cpl.core.Matrix) → float¶

Find the minimum value of all matrix elements.

The minimum value of matrix elements is found.

Returns:: Minimum value in the matrix
Return type:: float

minpos(self: cpl.core.Matrix) → Tuple[int, int]¶

Find position of minimum value of matrix elements.

The position of the minimum value of all matrix elements is found. If more than one matrix element have a value corresponding to the minimum, the lowest element row number is returned in row. If more than one minimum matrix elements have the same row number, the lowest element column number is returned in column.

Returns:: tuple in the format (row, column), where: - row is the returned row position of minimum. - column is the returned column position of minimum
Return type:: tuple(int, int)

multiply(self: cpl.core.Matrix, other: cpl.core.Matrix) → None¶

Multiply self by other, element by element. The two matrices must have identical sizes. The result is written to self.

Parameters:: other (cpl.core.Matrix) – matrix to multiply with
Raises:: cpl.core.IncompatibleInputError – if other does not have the same size as self

Notes

To obtain the rows-by-columns product between two matrices, use product_create()

See also

cpl.core.matrix.product_create: Rows-by-columns product of two matrices
cpl.core.matrix.multiply_scalar: Multiply self by a scalar.

multiply_scalar(self: cpl.core.Matrix, value: float) → None¶

Multiply self by a scalar.

Multiply each matrix element by the same factor.

Parameters:: value (float) – Multiplication factor.

See also

cpl.core.matrix.multiply: Multiply self by other, element by element.
cpl.core.matrix.product_create: Rows-by-columns product of two matrices.

power(self: cpl.core.Matrix, exponent: float) → None¶

Compute a power of matrix elements.

Each matrix element is replaced by its power to the specified exponent. If the specified exponent is not negative, all matrix elements must be not negative; if the specified exponent is negative, all matrix elements must be positive; otherwise, an error condition is set and the matrix will be left unchanged. If the exponent is exactly 0.5 the (faster) sqrt() will be applied instead of pow(). If the exponent is zero, then any (non negative) matrix element would be assigned the value 1.0.

Parameters:: exponent (float) – Constant exponent.
Raises:: cpl.core.IllegalInputError – Any element of self is not compatible with exponent (see extended summary)

product_create(self: cpl.core.Matrix, rhs: cpl.core.Matrix) → cpl.core.Matrix¶

Rows-by-columns product of two matrices.

The number of columns of the first matrix must be equal to the number of rows of the second matrix.

Can also use the @ operator to call this function for example with lhs as the calling object:

product = lhs @ rhs

Parameters:: rhs (cpl.core.Matrix) – Right side matrix to get the product with the calling object
Returns:: The rows-by-columns product of calling matrix and rhs matrix
Return type:: cpl.core.Matrix
Raises:: cpl.core.IncompatibleInputError – The number of columns of the calling matrix is not equal to the number of rows of the rhs matrix.

See also

cpl.core.matrix.multiply: Multiply self by other, element by element.
cpl.core.matrix.multiply_scalar: Multiply self by a scalar.
cpl.core.matrix.product_normal: Compute A = B * transpose(B)

product_normal(self: cpl.core.Matrix) → cpl.core.Matrix¶

Compute A = B * transpose(B)

self * transpose(self) Matrix multiplication results in a matrix of the size [rows of left] * [columns of right] Here, left = self, right = transpose(self) and the rows/columns of a transpose(self) are flipped from a self so the result of the multiplication is [rows of self] * [columns of transpose(self)], simplifies into [rows of self] * [rows of self]

Parameters:: other (cpl.core.Matrix) – M x N Matrix to multiply with its transpose
Returns:: Resulting matrix
Return type:: cpl.core.Matrix

Notes

Only the upper triangle of A is computed, while the elements below the main diagonal have undefined values.

See also

cpl.core.product_create: Rows-by-columns product of two matrices.
cpl.core.multiply: Multiply self by other, element by element.
cpl.core.matrix.multiply_scalar: Multiply self by a scalar.

product_transpose(self: cpl.core.Matrix, ma: cpl.core.Matrix, mb: cpl.core.Matrix) → None¶

Fill a matrix with the product of A * B’

Parameters:

ma (cpl.core.Matrix) – The matrix A, of size M x K
mb (cpl.core.Matrix) – The matrix B, of size N x K

Notes

The use of the transpose of B causes a more efficient memory access Changing the order of A and B is allowed, it transposes the result

resize(self: cpl.core.Matrix, top: int, bottom: int, left: int, right: int) → None¶

Resize a matrix by adding or removing rows and/or columns from the edges.

self is reframed according to specifications. Extra rows and column on the sides might also be negative, as long as they are compatible with the matrix sizes: self would be reduced in size accordingly, but an attempt to remove all matrix columns and/or rows raises an exception because zero length matrices are illegal. The old matrix elements contained in the new shape are left unchanged, and new matrix elements added by the reshaping are initialised to zero. No reshaping (i.e., all the extra rows set to zero) would not raise an exception.

Parameters:

top (int) – Extra rows on top.
bottom (int) – Extra rows on bottom.
left (int) – Extra columns on left.
right (int) – Extra columns on right.

Raises:

cpl.core.IllegalOutputError – Attempt to shrink self to zero size (or less).

set_size(self: cpl.core.Matrix, rows: int, columns: int) → None¶

Resize a matrix.

self is resized according to specifications. The old matrix elements contained in the resized matrix are left unchanged, and new matrix elements will be added by an increase of the matrix number of rows and/or columns are initialised to zero. New rows and/or columns will be added to the right/bottom of self. Likewise when shrinking the matrix by one of the dimensions, the rows/columns will be removed from the right/bottom of self.

Parameters:

rows (int) – New number of rows.
columns (int) – New number of columns.

Raises:

cpl.core.IllegalOutputError – Attempt to shrink matrix to zero size (or less).

shift(self: cpl.core.Matrix, rshift: int, cshift: int) → None¶

Shift matrix elements.

The performed shift operation is cyclical (toroidal), i.e., matrix elements shifted out of one side of the matrix get shifted in from its opposite side. There are no restrictions on the values of the shift. Positive shifts are always in the direction of increasing row/column indexes.

Parameters:

rshift (int) – Shift in the vertical direction.
cshift (int) – Shift in the horizontal direction.

static solve(coefficients: cpl.core.Matrix, rhs: cpl.core.Matrix) → cpl.core.Matrix¶

Solution of a linear system.

Compute the solution of a system of N equations with N unknowns:

coefficients * X = rhs

coefficients must be an NxN matrix, and rhs a NxM matrix. M greater than 1 means that multiple independent right-hand-sides are solved for.

rhs must have N rows and may contain more than one column, which each represent an independent right-hand-side.

Parameters:

coefficients (cpl.core.Matrix) – The N x N matrix of coefficients
rhs (cpl.core.Matrix) – An N by M matrix containing one or more right-hand sides

Returns:

New solution cpl.core.Matrix with the same size as rhs

Return type:

Raises:

cpl.core.IllegalInputError – if coefficients is not a square matrix
cpl.core.IncompatibleInputError – if coefficients and rhs do not have the same number of rows
cpl.core.SingularMatrixError – if coefficients is singular (to working precision)

solve_chol(self: cpl.core.Matrix, rhs: cpl.core.Matrix) → None¶

Solve a L*transpose(L)-system

Parameters:: rhs (cpl.core.Matrix) – M right-hand-sides to be replaced by their solution

Notes

Only the lower triangle of self is accessed

solve_lu(self: cpl.core.Matrix, rhs: cpl.core.Matrix, perm: List[int] | None = None) → cpl.core.Matrix¶

Solve a LU-system

self should be a n x n LU-matrix that has been decomposed using self.decomp_lu()

Parameters:

rhs (cpl.core.Matrix) – m right-hand-sides. This is duplicated and replaced by the solution of self to generate the return matrix.
perm (list of ints) – n-integer array filled with the row permutations

Returns:

The solution of self as applied to rhs

Return type:

Raises:

cpl.core.IllegalInputError – self is not an n by n matrix
cpl.core.IncompatibleInputError – The array or matrices not have the same number of rows.
cpl.core.DivisionByZeroError – The main diagonal of U contains a zero. This error can only occur if the LU-matrix does not come from a successful call to cpl.core.Matrix.decomp_lu.

See also

cpl.core.Matrix.decomp_lu: Used to generate an LU-system which can then be solved using this method.

static solve_normal(coefficients: cpl.core.Matrix, rhs: cpl.core.Matrix) → cpl.core.Matrix¶

Solution of overdetermined linear equations in a least squares sense.

rhs may contain more than one column, which each represent an independent right-hand-side.

Parameters:

coefficients (cpl.core.Matrix) – The N by M matrix of coefficients, where N >= M.
rhs (cpl.core.Matrix) – An N by K matrix containing K right-hand-sides.

Returns:

A newly allocated M by K solution matrix

Return type:

Raises:

cpl.core.IllegalInputError – if coefficients is not a square matrix
cpl.core.IncompatibleInputError – if coefficients and rhs do not have the same number of rows
cpl.core.SingularMatrixError – if coeff is singular (to working precision)

Notes

The following linear system of N equations and M unknowns is given:

coeff * X = rhs

where coeff is the NxM matrix of the coefficients, X is the MxK matrix of the unknowns, and rhs the NxK matrix containing the K right hand side(s).

The solution to the normal equations is known to be a least-squares solution, i.e. the 2-norm of coeff * X - rhs is minimized by the solution to transpose(coeff) * coeff * X = transpose(coeff) * rhs.

In the case that coeff is square (N is equal to M) it gives a faster and more accurate result to use cpl.core.Matrix.solve().

static solve_svd(coefficients: cpl.core.Matrix, rhs: cpl.core.Matrix, threshold_mode: int | None = None, threshold_tol: float = 0) → cpl.core.Matrix¶

Solve a linear system in a least square sense using an SVD factorization, optionally discarding singular values below a given threshold.

The function solves a linear system of the form Ax = b for the solution vector x, where A is represented by the argument coefficients and b by the argument rhs.

If threshold_mode and threshold_tol are passed, singular values which are less or equal than a given cutoff value are treated as zero. Otherwise all singular values are taken into account, regardless of their magnitude. This latter case is equivalent to setting threshold_mode to cpl.core.Matrix.ThresholdMode.USER and threshold_tol to 0.

The argument threshold_mode is used to select the computation of the cutoff value for small singular values. If threshold_mode is set to cpl.core.Matrix.ThresholdMode.EPSILON the machine precision DBL_EPSILON is used as the cutoff factor. If threshold_mode is cpl.core.Matrix.ThresholdMode.SIZE, the cutoff factor is computed as 10*DBL_EPSILON*max(N, M), and if threshold_mode is cpl.core.Matrix.ThresholdMode.USER the argument threshold_tol, a value in the range [0,1] is used as the cutoff factor. The actual cutoff value, is then given by the cutoff factor times the biggest singular value obtained from the SVD of the matrix coefficients of`self`.

Parameters:

coefficients (cpl.core.Matrix) – An N by M matrix of linear system coefficients, where N >= M
rhs (cpl.core.Matrix) – An N by 1 matrix with the right hand side of the system
threshold_mode (cpl.core.Matrix.ThresholdMode, optional) – Optional cutoff mode selector. used to select the computation of the cutoff value for small singular values. Options: - cpl.core.Matrix.ThresholdMode.EPSILON to use machine DBL_EPSILON as the cutoff factor - cpl.core.Matrix.ThresholdMode.SIZE, where the cutoff factor is computed as 10*DBL_EPSILON*max(N, M) - cpl.core.Matrix.ThresholdMode.USER, where the cutoff factor is set as the value passed to threshold_tol For consistency with CPL, the integer values 0, 1 or 2 can also be passed instead of the symbolic contants.
threshold_tol (float, optional) – Factor used to compute the cutoff value if threshold_mode is set to cpl.core.Matrix.ThresholdMode.USER. Must be a value between 0. and 1. Defaults to 0. if not set, but is not used unless threshold_mode is set to cpl.core.Matrix.ThresholdMode.USER. See Notes for more details.

Returns:

A newly allocated M by 1 solution matrix

Return type:

Raises:

cpl.core.IncompatibleInputError – if coefficients and rhs do not have the same number of rows
cpl.core.IllegalInputError – if matrix rhs has more than one column, an illegal mode (not one of cpl.core.Matrix.ThresholdMode.EPSILON, cpl.core.Matrix.ThresholdMode.SIZE or cpl.core.Matrix.ThresholdMode.USER, or their integer equivalents 0, 1, or 2), or an illegal tolerance (not between 0. and 1.) was given.

Notes

The linear system is solved using the singular value decomposition (SVD) of the coefficient matrix, based on a one-sided Jacobi orthogonalization.

sort_columns(self: cpl.core.Matrix, by_absolute: bool = False) → None¶

Sort matrix by columns.

The matrix elements of the top row are used as reference for the column sorting, if there are identical the values of the second row are considered, etc. Columns with the greater values go to left.

Parameters:: by_absolute (bool, optional) – True to sort by absolute value. Default False.

sort_rows(self: cpl.core.Matrix, by_absolute: bool = False) → None¶

Sort matrix by rows.

The matrix elements of the leftmost column are used as reference for the row sorting, if there are identical the values of the second column are considered, etc. Rows with the greater values go on top.

Parameters:: by_absolute (bool, optional) – True to sort by absolute value. Default False.

stdev(self: cpl.core.Matrix) → float¶

Find the standard deviation of all matrix elements.

The standard deviation of all matrix elements is calculated

Returns:: Standard deviation of all matrix elements
Return type:: float

Notes

This function works properly only if all elements of the matrix have finite values (not NaN or Infinity).

subtract(self: cpl.core.Matrix, other: cpl.core.Matrix) → None¶

Subtract matrix other from self

Subtract other from self element by element. The two matrices must have identical sizes. The result is written to self.

Parameters:: other (cpl.core.Matrix) – matrix to subtract with
Raises:: cpl.core.IncompatibleInputError – if other does not have the same size as self

subtract_scalar(self: cpl.core.Matrix, value: float) → None¶

Subtract a scalar to self.

Subtract the same value to each matrix element.

Parameters:: value (float) – Value to subtract.

swap_columns(self: cpl.core.Matrix, column1: int, column2: int) → None¶

Swap two matrix columns.

The values of two given matrix columns are exchanged. Columns are counted starting from 0. If the same column number is given twice, nothing is done and no exception is raised.

Parameters:

column1 (int) – One matrix column.
column2 (int) – Another matrix column.

Raises:

cpl.core.AccessOutOfRangeError – Either of the specified columns is outside the matrix boundaries.

swap_rowcolumn(self: cpl.core.Matrix, row: int) → None¶

Swap a matrix column with a matrix row.

The values of the indicated row are exchanged with the column having the same sequence number. Rows and columns are counted starting from 0.

Parameters:

row (int) – Matrix row.

Raises:

cpl.core.AccessOutOfRangeError – The specified row is outside the matrix boundaries.
cpl.core.IllegalInputError – self is not square.

swap_rows(self: cpl.core.Matrix, row1: int, row2: int) → None¶

Swap two matrix rows.

The values of two given matrix rows are exchanged. Rows are counted starting from 0. If the same row number is given twice, nothing is done and no exception is raised.

Parameters:

row1 (int) – One matrix row.
row2 (int) – Another matrix row.

Raises:

cpl.core.AccessOutOfRangeError – Either of the specified rows is outside the matrix boundaries.

threshold_small(self: cpl.core.Matrix, tolerance: float | None = None) → None¶

Rounding to zero very small numbers in matrix.

After specific manipulations of a matrix some of its elements may theoretically be expected to be zero (for instance, as a result of multiplying a matrix by its inverse). However, because of numerical noise, such elements may turn out not to be exactly zero. With this function any very small number in the matrix is turned to exactly zero.

If no tolerance is given then the default value is used, equal to the machine double epsilon.

Parameters:: tolerance (float, optional) – Max tolerated rounding to zero. If not given the machine double epsilon is used.

Notes

If tolerance is given a negative value, the default value for tolerance will be used (machine double epsilon).

transpose_create(self: cpl.core.Matrix) → cpl.core.Matrix¶

Returns the transpose of the matrix in a new matrix.

Returns:: New transposed matrix.
Return type:: cpl.core.Matrix

static zeros(rows: int, columns: int) → cpl.core.Matrix¶

Create an matrix of columns x rows dimensions, all 0’s

Parameters:

rows (int) – number of rows in the new matrix
columns (int) – number of columns in the new matrix

Returns:

New columns x rows matrix initialised with all 0’s

Return type:

class cpl.core.MatrixRow¶

Returned from a Matrix’s __getitem__ method or iterator. Used to access specific rows of the matrix.

Not instantiatable on its own.

index(self: cpl.core.MatrixRow, arg0: float) → int¶

class cpl.core.Msg¶

This module provides functions to display and log messages. The following operations are supported:

Enable messages output to terminal or to log file.
Optionally adding informative tags to messages.
Setting width for message line wrapping.
Control the message indentation level.
Filtering messages according to their severity level.

This module is configured via the set_config method and controls how messages are output.

class SeverityLevel¶

Members:

DEBUG

INFO

WARNING

ERROR

OFF

property name¶

static debug(component: str, message: str) → None¶

Display a debug message.

Parameters:

component (str) – Name of the function generating the message.
message (str) – Message to output

Notes

The show_component option in the config must be set to True for the component to be visible.

static error(component: str, message: str) → None¶

Display an error message.

Parameters:

component (str) – Name of the function generating the message.
message (str) – Message to output

Notes

The show_component option in the config must be set to True for the component to be visible.

static get_config() → dict¶: Gets current CPL Messaging configuration

static info(component: str, message: str) → None¶

Display an information message.

Parameters:

component (str) – Name of the function generating the message.
message (str) – Message to output

Notes

The show_component option in the config must be set to True for the component to be visible.

static set_config(**kwargs) → None¶

Set CPL Messaging configuration via kwargs as seen in the parameters below

Parameters:

level (cpl.core.Msg.SeverityLevel, optional) – Verbosity level, message below said verbosity level are not printed
domain (str, optional) – The domain name, also known as a task identifier, typically a pipeline recipe name.
width (int, optional) – The maximum width of the displayed text.
indent (int, optional) – The indentation level. Messages are indented by a number of characters equal to the level. Specifying a negative indentation level would set the indentation level to zero.
show_threadid (bool, optional) – True to attach the threadid tag with the messages
show_domain (bool, optional) – True to attach the domain name tag with the messages
show_time (bool, optional) – True to attach the time tag with the messages
show_component (bool, optional) – True to attach the component tag with the messages

static start_file(verbosity: cpl.core.Msg.SeverityLevel, name: str = '.logfile') → None¶

Begin log to file.

Typically called at the start of a script.

If this has already been called previously, the previous file log will stop and restart with the new logger.

Parameters:

Verbosity (cpl.core.Msg.SeverityLevel) – Verbosity level
name (str) – Filename to begin logging to

Raises:

cpl.core.IllegalInputError – If name is longer than 72 characters

static stop_file() → None¶: Close the current log file if running. Will not throw an error if logging is not currently active. This routine may be called in case the logging should be terminated before the end of a program.

static warning(component: str, message: str) → None¶

Display a warning message.

Parameters:

component (str) – Name of the function generating the message.
message (str) – Message to output

Notes

The show_component option in the config must be set to True for the component to be visible.

class cpl.core.Polynomial¶

This module provides functions to handle uni- and multivariate polynomials.

Comparing the two polynomials

P1(x) = p0 + p1.x + p4.x^2

and

P2(x,y) = p0 + p1.x + p2.y + p3.x.y + p4.x^2 + p5.y^2

P1(x) may evaluate to more accurate results than P2(x,0), especially around the roots. The base constructor creates a new polynomial with degree 0 and evaluates as 0.

Parameters:: dim (int) – The positive polynomial dimensions (number of variables)

Notes

Note that a polynomial like P3(z) = p0 + p1.z + p2.z^2 + p3.z^3, z=x^4 is preferable to p4(x) = p0 + p1.x^4 + p2.x^8 + p3.x^12. Polynomials are evaluated using Horner’s method. For multivariate polynomials the evaluation is performed one dimension at a time, starting with the lowest dimension and proceeding upwards through the higher dimensions.

add(self: cpl.core.Polynomial, other: cpl.core.Polynomial) → None¶

Add a polynomial with the same dimension as self

Parameters:: other (cpl.core.Polynomial) – polynomial to add
Raises:: cpl.core.IncompatibleInputError – if self and other do not have identical dimensions

compare(self: cpl.core.Polynomial, other: cpl.core.Polynomial, tol: float) → int¶

Compare the coefficients of two polynomials

The two polynomials are considered equal if they have identical dimensions and the absolute difference between their coefficients does not exceed the given tolerance.

This means that the following two polynomials per definition are considered different:

P1(x1) = 3*x1 different from P2(x1,x2) = 3*x1.

If all input parameters are valid and self and other point to the same polynomial the function returns 0.

If two polynomials have different dimensions, the return value is this (positive) difference.

If two 1D-polynomials differ, the return value is 1 plus the degree of the lowest order differing coefficient.

If for a higher dimension they differ, it is 1 plus the degree of a differing coefficient.

Parameters:

other (cpl.core.Polynomial) – The 2nd polynomial
tol (float) – The absolute (non-negative) tolerance

Returns:

0 when equal, positive when different, negative on error.

Return type:

int

Raises:

cpl.core.IllegalInputError – If tol is negative

copy(self: cpl.core.Polynomial) → cpl.core.Polynomial¶

Return a copy of the Polynomial.

Returns:: A new Polynomial containing a copy of the coefficients of the original.
Return type:: cpl.core.Polynomial

derivative(self: cpl.core.Polynomial, dim: int) → None¶

Compute a first order partial derivative

The dimension of the polynomial is preserved, even if the operation may cause the polynomial to become independent of the dimension dim variable.

self is modified to store the result

Parameters:

dim (int) – The dimension to differentiate (zero for first dimension)

Raises:

cpl.core.IllegalInputError – if dim is negative.
cpl.core.AccessOutOfRangeError – if dim exceeds the dimension of self.

Notes

The call requires n FLOPs, where n is the number of (non-zero) polynomial coefficients whose power in dimension dim is at least 1.

dump(self: cpl.core.Polynomial, filename: str | None = '', mode: str | None = 'w', show: bool | None = True) → str¶

Dump the Polynomial contents to a file, stdout or a string.

This function is intended just for debugging. It just prints the elements of a polynomial, ordered in rows and columns to the file path specified by filename. If a filename is not specified, output goes to stdout (unless show is False).

Parameters:

filename (str, optional) – File to dump polynomial contents to
mode (str, optional) – Mode to open the file with. Defaults to “w” (write, overwriting the contents of the file if it already exists), but can also be set to “a” (append, creating the file if it does not already exist or appending to the end of it if it does).
show (bool, optional) – Send polynomial contents to stdout. Defaults to True.

Returns:

Multiline string containing the dump of the polynomial contents.

Return type:

str

eval(*args, **kwargs)¶

Overloaded function.

eval(self: cpl.core.Polynomial, x: cpl.core.Vector) -> float

Evaluate the polynomial at the given point using Horner’s rule.

A polynomial with no non-zero coefficients evaluates as 0.

The length of x must match the polynomial dimension.

Parameters:

x (cpl.core.Vector) – Points of evaluation

Returns:

The computed value or undefined on error.

Return type:

float

Raises:

cpl.core.IncompatibleInputError – if the length of x differs from the dimension

Notes

With n coefficients the complexity is about 2n FLOPs.
eval(self: cpl.core.Polynomial, x: Iterable) -> float

Evaluate the polynomial at the given point using Horner’s rule.

A polynomial with no non-zero coefficients evaluates as 0.

The length of x must match the polynomial dimension.

Parameters:

x (iterable of float) – Points of evaluation

Returns:

The computed value or undefined on error.

Return type:

float

Raises:

cpl.core.IncompatibleInputError – if the length of x differs from the dimension

Notes

With n coefficients the complexity is about 2n FLOPs.

eval_1d(self: cpl.core.Polynomial, x: float) → Tuple[float, float]¶

Evaluate a univariate (1D) polynomial using Horner’s rule.

A polynomial with no non-zero coefficents evaluates to 0 with a derivative that does likewise.

Parameters:: x (float) – Point of evaluation
Returns:: in the format (result, pd), where pd is the derivative evaluated at x
Return type:: tuple(float, float)
Raises:: cpl.core.InvalidTypeError – if the polynomial is not (1D) univariate

Notes

The result is computed as \(p_0 + x * ( p_1 + x * ( p_2 + ... x * p_n ))\) and requires 2n FLOPs where n+1 is the number of coefficients.

The derivative is computed using a nested Horner rule.

eval_1d_diff(self: cpl.core.Polynomial, a: float, b: float) → Tuple[float, float]¶

Evaluate p(a) - p(b) using Horner’s rule.

Parameters:

a (float) – The evaluation point of the minuend
b (float) – The evaluation point of the subtrahend

Returns:

in the format (result, ppa), where ppa is the result of p(a)

Return type:

tuple(float, float)

Raises:

cpl.core.InvalidTypeError – if the polynomial has the wrong dimension

Notes

The call requires about 4n FLOPs where n is the number of coefficients in self, which is the same as that required for two separate polynomial evaluations. cpl_polynomial_eval_1d_diff() is however more accurate.

The underlying algorithm is the same as that used in eval_1d() when the derivative is also requested.

eval_2d(self: cpl.core.Polynomial, x: float, y: float) → Tuple[float, cpl.core.Vector]¶

Evaluate a bivariate (2D) polynomial using Horner’s rule and compute the derivatives.

A polynomial with no non-zero coefficents evaluates to 0 with a derivative that does likewise.

Parameters:

x (float) – x component of the evaluation point
y (float) – y component of the evaluation point

Returns:

in the format (result, gradient), where gradient is a tuple of 2 floats containing the X and Y components of the gradient vector at the evaluated point

Return type:

tuple(float, tuple(float, float))

Raises:

cpl.core.InvalidTypeError – if the polynomial is not 2D

Notes

The result is computed as \(p_0 + x * ( p_1 + x * ( p_2 + ... x * p_n ))\)

The derivative is computed using a nested Horner rule.

eval_3d(self: cpl.core.Polynomial, x: float, y: float, z: float) → Tuple[float, cpl.core.Vector]¶

Evaluate a trivariate (3D) polynomial using Horner’s rule and compute the derivatives.

A polynomial with no non-zero coefficents evaluates to 0 with a derivative that does likewise.

Parameters:

x (float) – x component of the evaluation point
y (float) – y component of the evaluation point
z (float) – z component of the evaluation point

Returns:

in the format (result, gradient), where gradient is a tuple of 3 floats containing the X, Y and Z components of the gradient vector at the evaluated point

Return type:

tuple(float, tuple(float, float, float))

Raises:

cpl.core.InvalidTypeError – if the polynomial is not 3D

Notes

The result is computed as \(p_0 + x * ( p_1 + x * ( p_2 + ... x * p_n ))\)

If the derivative is requested it is computed using a nested Horner rule.

extract(self: cpl.core.Polynomial, dim: int, other: cpl.core.Polynomial) → cpl.core.Polynomial¶

Collapse one dimension of a multi-variate polynomial by composition

The dimension of the polynomial self must be one greater than that of the other polynomial. Given these two polynomials the dimension dim of self is collapsed by creating a new polynomial from:

self(x0, x1, ..., x{dim-1}, other(x0, x1, ..., x{dim-1}, x{dim+1}, x{dim+2}, ..., x{n-1}), x{dim+1}, x{dim+2}, ..., x{n-1}).

The created polynomial thus has a dimension which is one less than the polynomial self and which is equal to that of the other polynomial. Collapsing one dimension of a 1D-polynomial is equivalent to evaluating it, which can be done with eval_1d().

other polynomial must currently have a degree of zero, i.e. it must be a constant.

Parameters:

dim (int) – The dimension to collapse (zero for first dimension)
other (cpl.core.Polynomial) – The polynomial to replace dimension dim of self

Returns:

The collapsed polynomial or NULL on error

Return type:

cpl.core.Polynomial

Raises:

cpl.core.InvalidTypeError – if the polynomial is uni-variate.
cpl.core.IllegalInputError – if dim is negative.
cpl.core.AccessOutOfRangeError – if dim exceeds the dimension of self.
cpl.core.IncompatibleInputError – if other has the wrong dimension.

Notes

other only allowed to be a constant is to be fixed by CPL

The collapse uses Horner’s rule and requires for n coefficients requires about 2n FLOPs.

fill_polynomial(self: cpl.core.Polynomial, p: int, x0: float, d: float) → cpl.core.Vector¶

Evaluate a 1D-polynomial on equidistant points using Horner’s rule

The evaluation points are x_i = x0 + i * d, i=0, 1, …, n-1, where n is the length of the vector.

Parameters:

out_size (int) – How many points to evaluate (size of returned vector)
x0 (float) – The first point of evaluation
d (float) – The increment between points of evaluation

Returns:

The evaluated points

Return type:

Raises:

cpl.core.InvalidTypeError – If the polynomial self is not 1D

Notes

The call requires about 2nm FLOPs, where m+1 is the number of coefficients in p.

fit(self: cpl.core.Polynomial, samppos: cpl.core.Matrix, fitvals: cpl.core.Vector, dimdeg: bool, maxdeg: List[int], sampsym: List[bool] | None = None, fitsigm: cpl.core.Vector | None = None, mindeg: List[int] | None = None) → None¶

Fit a polynomial to a set of samples in a least squares sense

Any pre-set non-zero coefficients in self are overwritten or reset by the fit.

For 1D-polynomials N = 1 + maxdeg - mindeg coefficients are fitted. A non-zero mindeg ensures that the fitted polynomial has a fix-point at zero.

The number of distinct samples should exceed the number of coefficients to fit. The number of distinct samples may also equal the number of coefficients to fit, but in this case the fit has another meaning (any non-zero residual is due to rounding errors, not a fitting error). It is an error to try to fit more coefficients than there are distinct samples.

In 1D the sampling points as pairs average u_0 (with an odd number of samples one sample must equal u_0).

In 2D the sampling points are symmetric in the 2D-plane. For the first dimension sampling symmetry means that the sampling is line- symmetric around y = u_1, while for the second dimension, sampling symmetry implies line-symmetry around x = u_2. Point symmetry around (x,y) = (u_1, u_2) means that both sampsym[0] and sampsym[1] may be set to true. For Chebyshev nodes sampsym can be set to True.

Parameters:

samppos (cpl.core.Matrix) – Matrix of p sample positions, with d rows and p columns
fitvals (cpl.core.Vector) – Vector of the p values to fit
dimdeg (cpl_boolean) – True iff there is a fitting degree per dimension. If dimdeg is false, an n-degree coefficient is fitted iff mindeg <= n <= maxdeg. If dimdeg is true, nci = 1 + maxdeg[i] - mindeg[i] coefficients are fitted for dimension i
maxdeg (list of ints) – Pointer to 1 or d maximum fitting degree(s), at least mindeg
sampsym (list of bools, optional) – d booleans, true iff the sampling is symmetric. sampsym is ignored if mindeg is nonzero, otherwise the caller may use sampsym to indicate an a priori knowledge that the sampling positions are symmetric
fitsigm (cpl.core.Vector, optional) – Uncertainties of the sampled values, or None for all ones. If relative uncertainties of the sampled values are known, they may be passed via fitsigm. Not passing means that all uncertaintiesequals one.
mindeg (cpl.core.Size, optional) – Pointer to 1 or d minimum fitting degree(s)

Raises:

cpl.core.IllegalInputError – if a mindeg value is negative, or if a maxdeg value is less than the corresponding value
cpl.core.DataNotFoundError – if the number of columns in samppos is less than the number of coefficients to be determined
cpl.core.IncompatibleInputError – if samppos, fitvals or fitsigm have incompatible sizes
cpl.core.SingularMatrixError – if samppos contains too few distinct values
cpl.core.DivisionByZeroError – if an element in fitsigm is zero
cpl.core.UnsupportedModeError – if the polynomial dimension exceeds two

Examples

fit1d = cpl.core.Polynomial(1) samppos1d = my_sampling_points_1d() # 1-row matrix fitvals = my_sampling_values() sampsym = [True] maxdeg1d = 4 # Fit 5 coefficients fit1d.fit(sappos1d,fitsvals, False, [maxdeg1d], sampsym=sampsym)

fit2d = cpl.core.Polynomial(2) samppos2d = my_sampling_points_2d() # 2-row matrix fitvals = my_sampling_values() maxdeg2d = [2, 1] # Fit 6 coefficients fit2d.fit(sappos2d,fitsvals, False, [maxdeg2d])

fit3d = cpl.core.Polynomial(3) samppos3d = my_sampling_points_3d() # 2-row matrix fitvals = my_sampling_values() maxdeg3d = [2, 1, 2] # Fit 6 coefficients fit3d.fit(sappos3d,fitsvals, False, [maxdeg3d])

Notes

Currently only 1D (uni-variate), 2D (bi-variate) and 3D (tri-variate) polynomials are supported. For all but uni-variate polynomials mindeg must be zero.

For a univariate (1D) fit the call requires 6MN + N^3/3 + 7/2N^2 + O(M) FLOPs where M is the number of data points and where N is the number of polynomial coefficients to fit, N = 1 + maxdeg - mindeg.

For a bivariate fit the call requires MN^2 + N^3/3 + O(MN) FLOPs where M is the number of data points and where N is the number of polynomial coefficients to fit.

The fit is done in the following steps: 1) If fitsigm is not None. The factors are applied to the values. 2) If mindeg is zero, the sampling positions are first transformed into Xhat_i = X_i - mean(X_i), i=1, .., dimension. 3) The Vandermonde matrix is formed from Xhat. If fitsigm is not None, the weights are also taken into account. 4) The normal equations of the Vandermonde matrix is solved. 5) If mindeg is zero, the resulting polynomial in Xhat is transformed back to X. Warning: An increase in the polynomial degree will normally reduce the fitting error. However, due to rounding errors and the limited accuracy of the solver of the normal equations, an increase in the polynomial degree may at some point cause the fitting error to _increase_. In some cases this happens with an increase of the polynomial degree from 8 to 9.

fit_residual(self: cpl.core.Polynomial, fitvals: cpl.core.Vector, samppos: cpl.core.Matrix, fitsigm: cpl.core.Vector = None) → Tuple[cpl.core.Vector, float]¶

Compute the residual of a polynomial fit using self as the fitted polynomial

If the relative uncertainties of the sampled values are known, they may be passed via fitsigm. Passing None means that all uncertainties equal one. The uncertainties are taken into account when computing the reduced chi square value.

Parameters:

fitvals (cpl.core.Vector) – Vector of the p fitted values
samppos (cpl.core.Matrix) – Matrix of p sample positions, with d rows and p columns
fitsigm (cpl.core.Vector, optional) – Uncertainties of the sampled values or passed None for a uniform uncertainty

Returns:

tuple in the format (result, rechisq) where: - result is the vector of the fitting residuals, same size as fitvals - redchisq is the reduced chi square of the fit

Return type:

tuple(cpl.core.Vector, double)

Raises:

cpl.core.IncompatibleInputError – if samppos, fitvals, fitsigm have incompatible sizes
cpl.core.DivisionByZeroError – if an element in fitsigm is zero
cpl.core.DataNotFoundError – if the number of columns in samppos is less than than the number of coefficients in the fitted polynomial.

static from_numpy(data: object) → cpl.core.Polynomial¶

Construct a CPL polynomial from a numpy polynomial

Parameters:: data (np.polynomial.polynomial.Polynomial) – Input polynomial

get_coeff(self: cpl.core.Polynomial, pows: List[int]) → float¶

Get a coefficient of the polynomial.

Requesting the value of a coefficient that has not been set is allowed, in this case zero is returned.

Parameters:: pows (list of ints) – The non-negative power(s) of the variable(s)
Raises:: cpl.core.IllegalInputError – if pows contains negative values

Notes

For an N-dimensional polynomial the complexity is O(N)

Examples

coeff = poly1d.get_coeff([3]): Requesting the value of a coefficient that has not been set is allowed, in this case zero is returned.

multiply(self: cpl.core.Polynomial, other: cpl.core.Polynomial) → None¶

Multiply with a polynomial with the same dimension as self

Parameters:: other (cpl.core.Polynomial) – polynomial to multiply with
Raises:: cpl.core.IncompatibleInputError – if self and other do not have identical dimensions

multiply_scalar(self: cpl.core.Polynomial, factor: float) → None¶

Multiply polynomial self with a scalar

Parameters:: factor (float) – factor to multiply with

Notes

If factor is zero, all coefficients are reset, if it is 1 all are copied

set_coeff(self: cpl.core.Polynomial, pows: List[int], value: float) → None¶

Set a coefficient of the polynomial

pows is assumed to have the size of the polynomial dimension.

If the coefficient is already there, it is overwritten, if not, a new coefficient is added to the polynomial. This may cause the degree of the polynomial to be increased, or if the new coefficient is zero, to decrease.

Parameters:

pows (list of ints) – The non-negative power(s) of the variable(s)
value (float) – the coefficient

Raises:

cpl.core.IllegalInputError – if pows contains negative values

Notes

For an N-dimensional polynomial the complexity is O(N)

shift_1d(self: cpl.core.Polynomial, i: int, u: float) → None¶

Modify p, p(x0, x1, …, xi, …) := (x0, x1, …, xi+u, …)

Shifting the polynomial p(x) = x^n with u = 1 will generate the binomial coefficients for n.

Shifting the coordinate system to (x,y) for the 2D-polynomium poly2d:

poly2d.shift_1d(0,x)
poly2d.shift_1d(1,y)

Parameters:

i (int) – The dimension to shift (0 for first)
u (float) – The shift

Raises:

cpl.core.IllegalInputError – if i is negative
cpl.core.AccessOutOfRangeError if i exceeds the dimension of p –

solve_1d(self: cpl.core.Polynomial, x0: float, mul: int) → float¶

A real solution to p(x) = 0 using Newton-Raphsons method

Even if a real solution exists, it may not be found if the first guess is too far from the solution. But a solution is guaranteed to be found if all roots of p are real (except in the case where the derivative at the first guess happens to be zero, see below - for an n-degree polynomial there are up to n-1 such guesses). If the constant term is zero, the solution 0 will be returned regardless of the first guess.

Parameters:

x0 (float) – First guess of the solution
mul (int) – The root multiplicity (or 1 if unknown)

Returns:

The solution

Return type:

float

Raises:

cpl.core.InvalidTypeError – if the polynomial has the wrong dimension
cpl.core.IllegalInputError – if the multiplicity is non-positive
cpl.core.ContinueError – If the algorithm does not converge
cpl.core.DivisionByZeroError – if a division by zero occurs

Notes

No solution is found when the iterative process stops because: 1) It can not proceed because p`(x) = 0 (cpl.core.DivisionByZeroError). 2) Only a finite number of iterations are allowed (cpl.core.ContinueError). Either can happen due to an an actual lack of a real solution or due to an insufficiently good first guess.

The accuracy and robustness deteriorates with increasing multiplicity of the solution. This is also the case with numerical multiplicity, i.e. when multiple solutions are located close together.

mul is assumed to be the multiplicity of the solution. Knowledge of the root multiplicity often improves the robustness and accuracy. If there is no knowledge of the root multiplicity mul should be 1. Setting mul to a too high value should be avoided.

subtract(self: cpl.core.Polynomial, other: cpl.core.Polynomial) → None¶

Subtract a polynomial with the same dimension as self

Parameters:: other (cpl.core.Polynomial) – polynomial to subtract
Raises:: cpl.core.IncompatibleInputError – if self and other do not have identical dimensions

property degree¶: The degree is the highest sum of exponents (with a non-zero coefficient). If there are no non-zero coefficients the degree is zero.

property dimension¶: The dimension of the polynomial.

class cpl.core.Property¶

Properties are basically a variable container which consists of a name, a type identifier and a specific value of that type.

The type identifier always determines the type of the associated value. A property is similar to an ordinary variable and its current value can be set or retrieved through its name. In addition a property may have a descriptive comment associated.

The following types are supported:

cpl.core.Type.BOOL
cpl.core.Type.FLOAT
cpl.core.Type.INT
cpl.core.Type.CHAR
cpl.core.Type.STRING
cpl.core.Type.DOUBLE
cpl.core.Type.LONG
cpl.core.Type.LONG_LONG
cpl.core.Type.FLOAT_COMPLEX
cpl.core.Type.DOUBLE_COMPLEX

Support for arrays in general is currently not available.

dump(self: cpl.core.Property, filename: str | None = '', mode: str | None = 'w', show: bool | None = True) → str¶

Dump a property contents to a file, stdout or a string.

Comment lines start with the hash character.

Parameters:

filename (str, optional) – File to dump property contents to
mode (str, optional) – Mode to open the file with. Defaults to “w” (write, overwriting the contents of the file if it already exists), but can also be set to “a” (append, creating the file if it does not already exist or appending to the end of it if it does).
show (bool, optional) – Send property contents to stdout. Defaults to True.

Returns:

Multiline string containing the dump of the property contents.

Return type:

str

property comment¶: property description

property name¶: name of property

property type¶: CPL type of property. See

class cpl.core.PropertyList¶

The opaque property list data type.

Was designed for supporting the FITS header information. Indeed, it is possible, using a single function, to load a header file into a property list, given the filename and the number of the extension using the load() function.

append(*args, **kwargs)¶

Overloaded function.

append(self: cpl.core.PropertyList, property: cpl.core.Property) -> None

Append a property value to a property list.

This function creates a new property and appends it to the end of a property list. It will not check if the property already exists.

Parameters:

property (cpl.core.Property) – Property to append
append(self: cpl.core.PropertyList, other: cpl.core.PropertyList) -> None

Append a propertylist

This function appends the properties from the property list other to self.

Parameters:

other (cpl.core.PropertyList) – Propertylist to append
append(self: cpl.core.PropertyList, name: str, value: Union[complex, float, bool, str, int, complex, int, int, str, float]) -> None
Append a new property using a name and value

This function appends a new property with name and inital value value. The type will be infered by value’ s type
Parameters:
name (str) – Name for the new property

value (str, char, float, complex, bool, int) – Initial value of the new property

del_regexp(self: cpl.core.PropertyList, regexp: str, invert: bool) → int¶

Erase all properties with name matching a given regular expression.

The function searches for all the properties matching in the list.

The function expects POSIX 1003.2 compliant extended regular expressions.

Parameters:

regexp (str) – Regular expression.
invert (bool) – Flag inverting the sense of matching.

Returns:

The number of erased entries

Return type:

int

dump(self: cpl.core.PropertyList, filename: str | None = '', mode: str | None = 'w', show: bool | None = True) → str¶

Dump a property list contents to a file, stdout or a string.

Each element is preceded by its index number (starting with 1!) and written on a single line.

Comment lines start with the hash character.

Parameters:

filename (str, optional) – File to dump property list contents to
mode (str, optional) – Mode to open the file with. Defaults to “w” (write, overwriting the contents of the file if it already exists), but can also be set to “a” (append, creating the file if it does not already exist or appending to the end of it if it does).
show (bool, optional) – Send property list contents to stdout. Defaults to True.

Returns:

Multiline string containing the dump of the property list contents.

Return type:

str

insert(*args, **kwargs)¶

Overloaded function.

insert(self: cpl.core.PropertyList, index: int, property: cpl.core.Property) -> None

Insert a property at index. PropertyList will increase in size by 1.

insert(self: cpl.core.PropertyList, arg0: str, arg1: cpl.core.Property) -> None

static load(name: str, position: int) → cpl.core.PropertyList¶

Create a filtered property list from a file.

Parameters:

name (str) – Name of the input file.
position (int) – Index of the data set to read.

Returns:

The loaded propertylist from the input file at index position

Return type:

cpl.core.PropertyList

Notes

The function reads the properties of the data set with index position from the file name.

Currently only the FITS file format is supported. The property list is created by reading the FITS keywords from extension position. The numbering of the data sections starts from 0. When creating the property list from a FITS header, any keyword without a value such as undefined keywords, are not transformed into a property. In the case of float or double (complex) keywords, there is no way to identify the type returned by CFITSIO, therefore this function will always load them as double (complex).

static load_regexp(name: str, position: int, regexp: str, invert: bool) → cpl.core.PropertyList¶

Create a filtered property list from a file.

Parameters:

name (str) – Name of the input file.
position (int) – Index of the data set to read.
regexp (str) – Regular expression used to filter properties.
invert (bool) – Flag inverting the sense of matching property names.

Returns:

The loaded propertylist from the input file at index position, with properties matching the regexp filter

Return type:

cpl.core.PropertyList

Notes

The function reads all properties of the data set with index position with matching names from the file name. If the flag invert is False, all properties whose names match the regular expression regexp are read. If invert is set to True, all properties with names not matching regexp are read rather. The function expects POSIX 1003.2 compliant extended regular expressions.

Currently only the FITS file format is supported. The property list is created by reading the FITS keywords from extension position.

The numbering of the data sections starts from 0.

When creating the property list from a FITS header, any keyword without a value such as undefined keywords, are not transformed into a property. In the case of float or double (complex) keywords, there is no way to identify the type returned by CFITSIO, therefore this function will always load them as double (complex).

FITS format specific keyword prefixes (e.g. HIERARCH) must not be part of the given pattern string regexp, but only the actual FITS keyword name may be given.

save(self: cpl.core.PropertyList, name: str, mode: int) → None¶

Save a property list to a FITS file.

Parameters:

name (str) – Name of the input file.
position (int) – Index of the data set to read.
mode (unsigned) – The desired output options (combined with bitwise or of cpl.core.io enums)

Notes

This function saves a property list to a FITS file, using cfitsio. The data unit is empty.

Supported output modes are cpl.core.io.CREATE (create a new file) and cpl.core.io.EXTEND (append to an existing file)

setup_product_header(self: cpl.core.PropertyList, product_frame: cpl.ui.Frame, framelist: cpl.ui.FrameSet, parlist: cpl.ui.ParameterList, recid: str, pipeline_id: str, dictionary_id: str, inherit_frame: object = None) → None¶

Add product keywords to a pipeline product property list.

Parameters:

product_frame (cpl.ui.Frame) – Frame describing the product
framelist (cpl.ui.FrameSet) – List of frames including all input frames
parlist (cpl.ui.ParameterList) – Recipe parameter list
recid (str) – Recipe name
pipeline_id (str) – Pipeline package (unique) identifier
dictionary_id (str) – PRO dictionary identifier
inherit_frame (cpl.ui.Frame, optional) – Frame from which header information is inherited

Return type:

None

Raises:

cpl.core.DataNotFoundError – If the input framelist contains no input frames or a frame in the input framelist does not specify a file. In the former case the string “Empty set-of-frames” is appended to the error message.
cpl.core.IllegalInputError – If the product frame is not tagged or not grouped as cpl.ui.Frame.FrameGroup.PRODUCT. A specified inherit_frame doesn’t belong to the input frame list, or it is not in FITS format.
cpl.core.FileNotFoundError – If a frame in the input framelist specifies a non-existing file.
cpl.core.BadFileFormatError – If a frame in the input framelist specifies an invalid file.

Notes

This function updates and validates that the property list self is DICB compliant. In particular, this function does the following:

Selects a reference frame from which the primary and secondary keyword information is inherited. The primary information is contained in the FITS keywords ORIGIN, TELESCOPE, INSTRUME, OBJECT, RA, DEC, EPOCH, EQUINOX, RADESYS, DATE-OBS, MJD-OBS, UTC, LST, PI-COI, OBSERVER, while the secondary information is contained in all the other keywords. If the inherit_frame is None, both primary and secondary information is inherited from the first frame in the input framelist with group cpl.ui.Frame.FrameGroup.RAW, or if no such frames are present the first frame with group cpl.ui.Frame.FrameGroup.CALIB. If inherit_frame is not None, the secondary information is inherited from inherit_frame instead.
Copy to self, if they are present, the following primary FITS keywords from the first input frame in the framelist: ORIGIN, TELESCOPE, INSTRUME, OBJECT, RA, DEC, EPOCH, EQUINOX, RADESYS, DATE-OBS, MJD-OBS, UTC, LST, PI-COI, OBSERVER. If those keywords are already present in the self property list, they are overwritten only in case they have the same type. If any of these keywords are present with an unexpected type, a warning is issued, but the keywords are copied anyway (provided that the above conditions are fulfilled), and no error is set.
Copy all the HIERARCH ESO * keywords from the primary FITS header of the inherit_frame in framelist, with the exception of the HIERARCH ESO DPR *, and of the HIERARCH ESO PRO * and HIERARCH ESO DRS * keywords if the inherit_frame is a calibration. If those keywords are already present in self, they are overwritten.
If found, remove the HIERARCH ESO DPR * keywords from self.
If found, remove the ARCFILE and ORIGFILE keywords from self.
Add to self the following mandatory keywords from the PRO dictionary: PIPEFILE, ESO PRO DID, ESO PRO REC1 ID, ESO PRO REC1 DRS ID, ESO PRO REC1 PIPE ID, and ESO PRO CATG. If those keywords are already present in self, they are overwritten. The keyword ESO PRO CATG is always set identical to the tag in product_frame.
Only if missing, add to self the following mandatory keywords from the PRO dictionary: ESO PRO TYPE, ESO PRO TECH, and ESO PRO SCIENCE. The keyword ESO PRO TYPE will be set to REDUCED. If the keyword ESO DPR TECH is found in the header of the first frame, ESO PRO TECH is given its value, alternatively if the keyword ESO PRO TECH is found it is copied instead, and if all fails the value UNDEFINED is set. Finally, if the keyword ESO DPR CATG is found in the header of the first frame and is set to SCIENCE, the boolean keyword ESO PRO SCIENCE will be set to true, otherwise it will be copied from an existing ESO PRO SCIENCE keyword, while it will be set to false in all other cases.
Check the existence of the keyword ESO PRO DATANCOM in self. If this keyword is missing, one is added, with the value of the total number of raw input frames.
Add to self the keywords ESO PRO REC1 RAW1 NAME, ESO PRO REC1 RAW1 CATG, ESO PRO REC1 CAL1 NAME, ESO PRO REC1 CAL1 CATG, to describe the content of the input set-of-frames.

See the DICB PRO dictionary for details on the mentioned PRO keywords.

Non-FITS files are handled as files with an empty FITS header.

The pipeline identifier string pipe_id is composed of the pipeline package name and its version number in the form PACKAGE “/” PACKAGE_VERSION.

sort(self: cpl.core.PropertyList, compare: function) → None¶

Sort a property list using a passed function.

Sort is done in place

Parameters:: compare (function(cpl.core.Property, cpl.core.Property) -> int) – The function used to compare two properties. This function compares to determine whether a property is less, equal or greater than another one.
Return type:: None

class cpl.core.Sort¶

Members:

DESCENDING : For use with cpl.core.Vector.sort() for descending order sort

ASCENDING : For use with cpl.core.Vector.sort() for ascending order sort

property name¶

class cpl.core.SortMode¶

Members:

BY_X

BY_Y

property name¶

class cpl.core.Table¶

This module provides functions to create and user PyCPL tables.

A CPL table is made of columns, and a column consists of an array of elements of a given type.

The following types are supported, - cpl.core.Type.INT - cpl.core.Type.LONG_LONG - cpl.core.Type.FLOAT - cpl.core.Type.DOUBLE - cpl.core.Type.DOUBLE_COMPLEX - cpl.core.Type.FLOAT_COMPLEX - cpl.core.Type.STRING.

Moreover, it is possible to define columns of arrays, i.e. columns whose elements are arrays of all the basic types listed above. Within the same column all arrays must have the same type and the same length.

A table column is accessed by specifying its name. The ordering of the columns within a table is undefined: a CPL table is not an n-tuple of columns, but just a set of columns. The N elements of a column are counted from 0 to N-1, with element 0 on top. The set of all the table columns elements with the same index constitutes a table row, and table rows are counted according to the same convention.

It is possible to flag each table row as “selected” or “unselected”, and each column element as “valid” or “invalid”. Selecting table rows is mainly a way to extract just those table parts fulfilling any given condition, while invalidating column elements is a way to exclude such elements from any computation. A CPL table is created with all rows selected, and a column is created with all elements invalidated.

New columns can be allocated either by calling the appropriate function (new_column() for regular columns, new_column_array() for array columns) or setting directly via index (however the given array must be of the number of table rows). See __setitem__ docs for more info.

Array column elements must all be of the same length.

New CPL tables can be built from an existing table-like object, or via the empty static method. See the Parameters section for building from existing data

Parameters:

input (object) –

Data used to build the new CPL table object. This data source must only contain objects of types compatible with CPL tables

input can be the following types: - astropy.table.QTable - pandas.Dataframe - numpy.recarray

Raises:

cpl.core.InvalidTypeError – If one of the columns in input is not a CPL compatible type

class Operator¶

Members:

NOT_EQUAL_TO

EQUAL_TO

GREATER_THAN

NOT_GREATER_THAN

LESS_THAN

NOT_LESS_THAN

property name¶

abs(self: cpl.core.Table, name: str) → None¶

Compute the absolute value of column values.

Each column element is replaced by its absolute value. Invalid elements are not modified by this operation. If the column is complex, its type will be turned to real (cpl.core.Type.FLOAT_COMPLEX will be changed into cpl.core.Type.FLOAT, and cpl.core.Type.DOUBLE_COMPLEX will be changed into cpl.core.Type.DOUBLE).

Parameters:

name (str) – Table column name.

Raises:

cpl.core.DataNotFoundError – If a column with the specified name is not found in self
cpl.core.InvalidTypeError – If the requested column is not numerical, or is an array column

add_columns(self: cpl.core.Table, to_name: str, from_name: str) → None¶

Add the values of two numeric or complex table columns.

The columns are summed element by element, and the result of the sum is stored in the target column. The columns’ types may differ, and in that case the operation would be performed using the standard C upcasting rules, with a final cast of the result to the target column type. Invalid elements are propagated consistently: if either or both members of the sum are invalid, the result will be invalid too. Underflows and overflows are ignored.

Parameters:

to_name (str) – Name of target column.
from_name (str) – Name of source column.

add_scalar(self: cpl.core.Table, name: str, value: float) → None¶

Add a constant value to a numerical or complex column.

The operation is always performed in double precision, with a final cast of the result to the target column type. Invalid elements are are not modified by this operation.

Parameters:

name (str) – Column name.
value (float) – Value to add.

Raises:

cpl.core.DataNotFoundError – If a column with the specified name is not found in self
cpl.core.InvalidTypeError – If the requested column is not numerical, or is an array column

add_scalar_complex(self: cpl.core.Table, name: str, value: complex) → None¶

Add a constant complex value to a numerical or complex column.

The operation is always performed in double precision, with a final cast of the result to the target column type. Invalid elements are are not modified by this operation.

Parameters:

name (str) – Column name.
value (complex) – Value to add.

Raises:

cpl.core.DataNotFoundError – If a column with the specified name is not found in self
cpl.core.InvalidTypeError – If the requested column is not numerical, or is an array column

and_selected(self: cpl.core.Table, name1: str, operator: cpl.core.Table.Operator, name2: str) → int¶

Select from selected table rows, by comparing the values of two columns.

Either both columns must be numerical, or they both must be strings. The comparison between strings is lexicographical. Neither can be a complex or array type.

For all the already selected table rows, the values of the specified column are compared. The table rows not fulfilling the comparison are unselected. Invalid elements from either columns never fulfill any comparison by definition.

For this function, the column is of a numerical type if its type is: * cpl.core.Type.INT * cpl.core.Type.FLOAT * cpl.core.Type.DOUBLE * cpl.core.Type.LONG_LONG

All table rows not fulfilling the comparison are unselected. An invalid element never fulfills any comparison by definition. Allowed relational operators are * cpl.core.Operator.EQUAL_TO * cpl.core.Operator.NOT_EQUAL_TO * cpl.core.Operator.GREATER_THAN * cpl.core.Operator.NOT_GREATER_THAN * cpl.core.Operator.LESS_THAN * cpl.core.Operator.NOT_LESS_THAN

Parameters:

name1 (str) – Name of the first table column
operator (cpl.core.Operator) – Relational Operator. See extended summary for allowed operators.
name2 (str) – Name of second table column.

Returns:

New number of selected rows

Return type:

int

Raises:

cpl.core.DataNotFoundError – If a column with any of the specified names is not found in table.
cpl.core.InvalidTypeError – Invalid types for comparison.

See also

cpl.core.Table.or_selected: To select from unselected rows using column comparison

and_selected_invalid(self: cpl.core.Table, name: str) → int¶

Select from selected table rows all rows with an invalid value in a specified column.

For all the already selected table rows, all the rows containing valid values at the specified column are unselected. See also the function

Parameters:: name (str) – Column name.
Returns:: New number of selected rows
Return type:: int

and_selected_numerical(self: cpl.core.Table, name: str, operator: cpl.core.Table.Operator, value: object) → None¶

Select from already selected table rows, by comparing a column of numercal values to the reference value

For all the already selected table rows, the values of the specified column are compared with the reference value.

The column is of a numerical type if its type is: * cpl.core.Type.INT * cpl.core.Type.FLOAT * cpl.core.Type.DOUBLE * cpl.core.Type.DOUBLE_COMPLEX * cpl.core.Type.FLOAT_COMPLEX * cpl.core.Type.LONG_LONG

All table rows not fulfilling the comparison are unselected. An invalid element never fulfills any comparison by definition. Allowed relational operators are * cpl.core.Operator.EQUAL_TO * cpl.core.Operator.NOT_EQUAL_TO * cpl.core.Operator.GREATER_THAN * cpl.core.Operator.NOT_GREATER_THAN * cpl.core.Operator.LESS_THAN * cpl.core.Operator.NOT_LESS_THAN

Parameters:

name (str) – Column name.
operator (cpl.core.Operator) – Relational Operator. See extended summary for allowed operators.
value (int, float or complex) – Reference value

Returns:

New number of selected rows

Return type:

int

Raises:

cpl.core.DataNotFoundError – if the column of the given name wasn’t found.
cpl.core.TypeMismatchError – Column of the given name is not numerical

See also

cpl.core.Table.or_selected_numerical: To select from unselected rows using numerical operator comparison

and_selected_string(self: cpl.core.Table, name: str, operator: cpl.core.Table.Operator, string: str) → int¶

Select from selected table rows, by comparing a column of string values to the given string.

For all the already selected table rows, the values of the specified column are compared with the reference string.

If operator is equal to cpl.core.Operator.EQUAL_TO or cpl.core.Operator.NOT_EQUAL_TO then the comparison string is treated as a regular expression.

All table rows not fulfilling the comparison are unselected. An invalid element never fulfills any comparison by definition. Allowed relational operators are * cpl.core.Operator.EQUAL_TO * cpl.core.Operator.NOT_EQUAL_TO * cpl.core.Operator.GREATER_THAN * cpl.core.Operator.NOT_GREATER_THAN * cpl.core.Operator.LESS_THAN * cpl.core.Operator.NOT_LESS_THAN

Parameters:

name (str) – Column name.
operator (cpl.core.Operator) – Relational Operator. See extended summary for allowed operators.
string (str) – Reference character string

Returns:

New number of selected rows

Return type:

int

Raises:

cpl.core.DataNotFoundError – if the column of the given name wasn’t found.
cpl.core.TypeMismatchError – Column of the given name is not of type cpl.core.Type.STRING
cpl.core.IllegalInputError – Invalid regular expression

See also

cpl.core.Table.or_selected_string: To select from unselected rows using string comparison

and_selected_window(self: cpl.core.Table, start: int, count: int) → int¶

Select from selected rows only those within a table segment.

All the selected table rows that are outside the specified interval are unselected. If the sum of start and count goes beyond the end of the input table, rows are checked up to the end of the table.

Parameters:

start (int) – First row of table segment.
count (int) – Length of segment

Returns:

New number of selected rows

Return type:

int

Raises:

cpl.core.AccessOutOfRange – self has zero length, or start is outside self’s boundaries
cpl.core.IllegalInputError – count is negative

See also

cpl.core.Table.or_selected_window: To select from unselected rows using a specified segment

arg_column(self: cpl.core.Table, name: str) → None¶

Compute the phase angle value of table column elements.

Each column element is replaced by its phase angle value. The phase angle will be in the range of [-pi,pi]. Invalid elements are not modified by this operation. If the column is complex, its type will be turned to real (cpl.core.Type.FLOAT_COMPLEX will be changed into cpl.core.Type.FLOAT, and cpl.core.Type.DOUBLE_COMPLEX will be changed into cpl.core.Type.DOUBLE).

Parameters:

name (str) – Column name.

Raises:

cpl.core.DataNotFoundError – If a column with the specified name is not found in self
cpl.core.InvalidTypeError – If the requested column is not numerical or complex

cast_column(self: cpl.core.Table, from_name: str, to_name: str, type: cpl.core.Type) → None¶

Cast a numeric or complex column to a new numeric or complex type column.

A new column of the specified type is created, and the content of the given numeric column is cast to the new type. If the input column type is identical to the specified type the column is duplicated as is done by the function duplicate_column(). Note that a column of arrays is always cast to another column of arrays of the specified type, unless it has depth 1. Consistently, a column of numbers can be cast to a column of arrays of depth 1. Here is a complete summary of how any (legal) type specification would be interpreted, depending on the type of the input column:

from_name type = cpl.core.Type.XXX | cpl.core.Type.POINTER specified type = cpl.core.Type.XXX | cpl.core.Type.POINTER to_name type = cpl.core.Type.XXX | cpl.core.Type.POINTER

from_name type = cpl.core.Type.XXX | cpl.core.Type.POINTER (depth > 1) specified type = cpl.core.Type.XXX to_name type = cpl.core.Type.XXX | cpl.core.Type.POINTER

from_name type = cpl.core.Type.XXX | cpl.core.Type.POINTER (depth = 1) specified type = cpl.core.Type.XXX to_name type = cpl.core.Type.XXX

from_name type = cpl.core.Type.XXX specified type = cpl.core.Type.XXX | cpl.core.Type.POINTER to_name type = cpl.core.Type.XXX | cpl.core.Type.POINTER (depth = 1)

from_name type = cpl.core.Type.XXX specified type = cpl.core.Type.POINTER to_name type = cpl.core.Type.XXX | cpl.core.Type.POINTER (depth = 1)

from_name type = cpl.core.Type.XXX specified type = cpl.core.Type.YYY to_name type = cpl.core.Type.YYY

from_name type = cpl.core.Type.XXX | cpl.core.Type.POINTER specified type = cpl.core.Type.YYY | cpl.core.Type.POINTER to_name type = cpl.core.Type.YYY | cpl.core.Type.POINTER

from_name type = cpl.core.Type.XXX | cpl.core.Type.POINTER (depth > 1) specified type = cpl.core.Type.YYY to_name type = cpl.core.Type.YYY | cpl.core.Type.POINTER

from_name type = cpl.core.Type.XXX | cpl.core.Type.POINTER (depth = 1) specified type = cpl.core.Type.YYY to_name type = cpl.core.Type.YYY

from_name type = cpl.core.Type.XXX specified type = cpl.core.Type.YYY | cpl.core.Type.POINTER to_name type = cpl.core.Type.YYY | cpl.core.Type.POINTER (depth = 1)

Parameters:

from_name (str) – Name of table column to cast.
to_name (str) – Name of new table column.
type (cpl.core.Type) – Type of new table column.

column_array(self: cpl.core.Table, name: str) → object¶

Get column data in the form of a numpy.ndarray

The array will be returned with the corresponding type as the column, containing in order all the values contained within column name.

If the column is an array type, then the array returned will be 2d, with each nested array represents a value.

Parameters:

name (str) – column to extract values

Returns:

array of values contained within column name in self.

Return type:

numpy.ndarray

Raises:

cpl.core.DataNotFoundError – If column name does not exist in self
cpl.core.InvalidTypeError – If the column type cannot be cast to a numpy array

compare_structure(self: cpl.core.Table, other: cpl.core.Table) → bool¶

Compare the structure of two tables.

Two tables have the same structure if they have the same number of columns, with the same names, the same types, and the same units. The order of the columns is not relevant.

Parameters:: other (cpl.core.Table) – Other table to compare with.
Returns:: True if the tables have the same structure, otherwise False.
Return type:: bool

conjugate_column(self: cpl.core.Table, name: str) → None¶

Compute the complex conjugate of column values.

Each column element is replaced by its complex conjugate. The operation is always performed in double precision, with a final cast of the result to the target column type. Invalid elements are not modified by this operation.

Parameters:

name (str) – Column name.

Raises:

cpl.core.DataNotFoundError – If a column with the specified name is not found in self
cpl.core.InvalidTypeError – If the requested column is not numerical, or is an array column

copy_structure(self: cpl.core.Table, toCopy: cpl.core.Table) → None¶

Copy the structure (column names, types and units) from another table

This function assignes to a columnless table the same column structure (names, types, units) of a given model table. All columns are physically created in the new table, and they are initialised to contain just invalid elements.

Parameters:: toCopy (cpl.core.Table) – table from which the structure is to be copied from.
Raises:: cpl.core.IllegalInputError – if self contains columns

count_invalid(self: cpl.core.Table, name: str) → int¶

Count number of invalid values in a table column.

Count number of invalid elements in a table column.

Parameters:: name (str) – Name of table column to examine.
Returns:: Number of invalid elements in a table column.
Return type:: int
Raises:: cpl.core.DataNotFoundError – A column with the given name is not found in self.

divide_columns(self: cpl.core.Table, to_name: str, from_name: str) → None¶

Divide two numeric or complex table columns.

The columns are divided element by element, and the result of the division is stored in the target column. The columns’ types may differ, and in that case the operation would be performed using the standard C upcasting rules, with a final cast of the result to the target column type. Invalid elements are propagated consistently: if either or both members of the division are invalid, the result will be invalid too. Underflows and overflows are ignored, but a division by exactly zero will set an invalid column element.

Parameters:

to_name (str) – Name of target column.
from_name (str) – Name of column dividing the target column.

divide_scalar(self: cpl.core.Table, name: str, value: float) → None¶

Divide a numerical or complex column by a constant.

The operation is always performed in double precision, with a final cast of the result to the target column type. Invalid elements are not modified by this operation.

Parameters:

name (str) – Column name.
value (float) – Divisor value.

Raises:

cpl.core.DataNotFoundError – If a column with the specified name is not found in self
cpl.core.InvalidTypeError – If the requested column is not numerical, or is an array column
cpl.core.DivisionByZeroError – value is equal to 0.0

divide_scalar_complex(self: cpl.core.Table, name: str, value: complex) → None¶

Divide a numerical or complex column by a complex constant.

The operation is always performed in double precision, with a final cast of the result to the target column type. Invalid elements are not modified by this operation.

Parameters:

name (str) – Column name.
value (complex) – Divisor value.

Raises:

cpl.core.DataNotFoundError – If a column with the specified name is not found in self
cpl.core.InvalidTypeError – If the requested column is not numerical, or is an array column
cpl.core.DivisionByZeroError – value is equal to 0.0

dump(self: cpl.core.Table, filename: str | None = '', mode: str | None = 'w', start: int = 0, count: object = None, show: bool | None = True) → str¶

Dump the Table contents to a file, stdout or a string.

This function is mainly intended for debug purposes. All column elements are printed according to the column formats, that may be specified for each table column with the function.

Parameters:

filename (str, optional) – file path to dump table contents to
mode (str, optional) – File mode to save the file, default ‘w’ overwrites contents.
start (int) – First row to print
count (int) – Number of rows to print
show (bool, optional) – Send table contents to stdout. Defaults to True.

Returns:

Multiline string containing the dump of the table contents.

Return type:

str

duplicate_column(self: cpl.core.Table, to_name: str, from_table: cpl.core.Table, from_name: str) → None¶

Copy a column from a table to self.

Copy a column from a table to self. The column is duplicated. A column may be duplicated also within the same table.

Parameters:

to_name (str) – New name of copied column.
from_table (cpl.core.Table) – Source table.
from_name (str) – Name of column to copy.

Raises:

cpl.core.DataNotFoundError – A column with the given from_name is not found in from_table.
cpl.core.IncompatibleInputError – self and from_table do not have the same number of rows
cpl.core.IllegalOutputError – to_name already exists as a column in self

static empty(rows: int) → cpl.core.Table¶

Construct empty table with a set number of rows

Parameters:: rows (int) – number of rows in the new table
Returns:: New empty Table with rows number of rows
Return type:: cpl.core.Table
Raises:: cpl.core.IllegalInputError – rows is negative

erase_column(self: cpl.core.Table, name: str) → None¶

Delete a column from a table.

Delete a column from a table. If the table is left without columns, also the selection flags are lost.

Parameters:: name (str) – Name of table column to delete.
Raises:: cpl.core.DataNotFoundError – A column with the given name not found in table.

erase_invalid(self: cpl.core.Table) → None¶

Remove from a table all columns just containing invalid elements, and then all rows containing at least one invalid element.

Firstly, all columns consisting just of invalid elements are deleted from the table. Next, the remaining table rows containing at least one invalid element are also deleted from the table.

The function is similar to the function erase_invalid_rows(), except for the criteria to remove rows containing invalid elements after all invalid columns have been removed. While erase_invalid_rows() requires all elements to be invalid in order to remove a row from the table, this function requires only one (or more) elements to be invalid.

Notes

If the input table just contains invalid elements, all columns are deleted.

erase_invalid_rows(self: cpl.core.Table) → None¶

Remove from a table columns and rows just containing invalid elements.

Table columns and table rows just containing invalid elements are deleted from the table, i.e. a column or a row is deleted only if all of its elements are invalid. The selection flags are set back to “all selected” even if no rows or columns are removed.

Notes

If the input table just contains invalid elements, all columns are deleted.

erase_selected(self: cpl.core.Table) → None¶

Delete the selected rows of a table.

A portion of the table data is physically removed, and the table selection flags are set back to “all selected”.

erase_window(self: cpl.core.Table, start: int, count: int) → None¶

Delete a table segment.

A portion of the table data is physically removed.

Parameters:

start (int) – First row to delete.
count (int) – Number of rows to delete.

Raises:

cpl.core.AccessOutOfRangeError – The table has length of zero, or start is outside the table range.
cpl.core.IllegalInputError – count is negative

exponential_column(self: cpl.core.Table, name: str, base: float) → None¶

Compute the exponential of column values.

Each column element is replaced by its exponential in the specified base. The operation is always performed in double precision, with a final cast of the result to the target column type. Invalid elements are not modified by this operation.

Parameters:

name (str) – Column name.
base (float) – Exponential base.

Raises:

cpl.core.DataNotFoundError – If a column with the specified name is not found in self
cpl.core.InvalidTypeError – If the requested column is not numerical, or is an array column
cpl.core.IllegalInputError – base is not positive

extract(self: cpl.core.Table, start: int, count: int) → cpl.core.Table¶

Create a table from a section of another table.

A number of consecutive rows are copied from an input table to a newly created table. The new table will have the same structure of the original table (see function compare_structure()). If the sum of start and count goes beyond the end of the input table, rows are copied up to the end. All the rows of the new table are selected, i.e., existing selection flags are not transferred from the old table to the new one.

Parameters:

start (int) – First row to be copied to new table.
count (int) – Number of rows to be copied.

Returns:

The new table.

Return type:

cpl.core.Table

extract_selected(self: cpl.core.Table) → cpl.core.Table¶

Create a new table from the selected rows of another table.

A new table is created, containing a copy of all the selected rows of the input table. In the output table all rows are selected.

Returns:: New cpl.core.Table of selected rows
Return type:: cpl.core.Table

fill_invalid(self: cpl.core.Table, name: str, value: object) → None¶

Write a numerical value to invalid elements.

The value will adapt to the column type

Parameters:

name (str) – Column name.
value (float, int, complex, or array) – Value to write to invalid column elements.

Notes

Assigning a value to an invalid numerical element will not make it valid, but assigning a value to an element consisting of an array of numbers will make the array element valid.

get(self: cpl.core.Table, name: str, row: int) → Tuple[float, int]¶

Read a value from a numerical column.

Rows are counted starting from 0.

Parameters:

name (str) – Name of table column to be accessed.
row (int) – Position of element to be read.

Returns:

Value read. In case of invalid table element 0.0 is returned.

Return type:

float

Raises:

cpl.core.AccessOutOfRangeError – self has zero length or row is outside table self’s boundaries
cpl.core.DataNotFoundError – A column with the given name is not found in self.
cpl.core.InvalidTypeError – The specified column is not numerical, or is a column of arrays.

get_column_depth(self: cpl.core.Table, name: str) → int¶

Get the depth of a table column.

Get the depth of a column. Columns of type array always have positive depth, while columns listing numbers or character strings have depth 0.

Parameters:: name (str) – Column name.
Returns:: Column depth
Return type:: int
Raises:: cpl.core.DataNotFoundError – A column with the given name not found in table.

get_column_dimension(self: cpl.core.Table, name: str, indx: int) → int¶

Get size of one dimension of a table column of arrays.

Get the size of one dimension of a column. If a column is not an array column, or if it has no dimensions, 1 is returned.

Parameters:

name (str) – Column name.
indx (int) – Indicate dimension to query (0 = x, 1 = y, 2 = z, etc.).

Returns:

Size of queried dimension of the column, or zero in case of error.

Return type:

int

Raises:

cpl.core.DataNotFoundError – A column with the given name not found in table.
cpl.core.UnsupportedModeError – A column with the given name is not of type cpl.core.Type.ARRAY
cpl.core.AccessOutOfRangeError – The specified indx array is not compatible with the column dimensions
cpl.core.IncompatibleInputError – The specified dimensions are incompatible with the total number of elements in the column arrays.

get_column_dimensions(self: cpl.core.Table, name: str) → int¶

Get the number of dimensions of a table column of arrays.

Get the number of dimensions of a column. If a column is not an array column, or if it has no dimensions, 1 is returned.

Parameters:: name (str) – Column name.
Returns:: Column number of dimensions, or 0 in case of failure.
Return type:: int
Raises:: cpl.core.DataNotFoundError – A column with the given name not found in table.

get_column_format(self: cpl.core.Table, name: str) → str¶

Get the format of a table column.

Return the format of a column.

Parameters:: name (str) – Column name.
Returns:: Format of column.
Return type:: str
Raises:: cpl.core.DataNotFoundError – A column with the given name not found in table.

get_column_max(self: cpl.core.Table, name: str) → float¶

Get maximum value in a numerical column.

Invalid column values are excluded from the computation. The table selection flags have no influence on the result.

Parameters:

name (str) – Column name.

Returns:

Maximum value. See documentation of get_column_mean().

Return type:

float

Raises:

cpl.core.DataNotFoundError – If a column with the specified name is not found in self, or it just contains invalid elements, or table length is zero
cpl.core.InvalidTypeError – If the requested column is not numerical

get_column_maxpos(self: cpl.core.Table, name: str) → int¶

Get position of maximum in a numerical column.

Invalid column values are excluded from the search. The return value is the position of the maximum value where rows are counted starting from 0.

If more than one column element correspond to the max value, the position with the lowest row number is returned.

Parameters:

name (str) – Column name.

Returns:

Returned row position of maximum value in column name

Return type:

int

Raises:

cpl.core.DataNotFoundError – If a column with the specified name is not found in self, or it just contains invalid elements, or table length is zero
cpl.core.InvalidTypeError – If the requested column is not numerical

get_column_mean(self: cpl.core.Table, name: str) → float¶

Compute the mean value of a numerical column.

Invalid column values are excluded from the computation. The table selection flags have no influence on the result.

Parameters:

name (str) – Column name.

Returns:

Mean value

Return type:

float

Raises:

cpl.core.DataNotFoundError – If a column with the specified name is not found in self, or it just contains invalid elements, or table length is zero
cpl.core.InvalidTypeError – If the requested column is not numerical

get_column_mean_complex(self: cpl.core.Table, name: str) → complex¶

Compute the mean value of a numerical or complex column.

Invalid column values are excluded from the computation. The table selection flags have no influence on the result.

Parameters:

name (str) – Column name.

Returns:

Mean value. In case of error 0.0 is returned.

Return type:

complex

Raises:

cpl.core.DataNotFoundError – If a column with the specified name is not found in self, or it just contains invalid elements, or table length is zero
cpl.core.InvalidTypeError – If the requested column is not numerical or complex

get_column_median(self: cpl.core.Table, name: str) → float¶

Compute the median value of a numerical column.

Invalid column values are excluded from the computation. The table selection flags have no influence on the result.

Parameters:

name (str) – Column name.

Returns:

Median value

Return type:

float

Raises:

cpl.core.DataNotFoundError – If a column with the specified name is not found in self, or it just contains invalid elements, or table length is zero
cpl.core.InvalidTypeError – If the requested column is not numerical

get_column_min(self: cpl.core.Table, name: str) → float¶

Get minimum value in a numerical column.

Invalid column values are excluded from the computation. The table selection flags have no influence on the result.

Parameters:

name (str) – Column name.

Returns:

Minimum value. See documentation of get_column_mean().

Return type:

float

Raises:

cpl.core.DataNotFoundError – If a column with the specified name is not found in self, or it just contains invalid elements, or table length is zero
cpl.core.InvalidTypeError – If the requested column is not numerical

get_column_minpos(self: cpl.core.Table, name: str) → int¶

Get position of minimum in a numerical column.

Invalid column values are excluded from the search. The return value is the position of the minimum value where rows are counted starting from 0.

If more than one column element correspond to the minimum value, the position with the lowest row number is returned.

Parameters:

name (str) – Column name.

Returns:

Returned row position of minimum value in column name

Return type:

int

Raises:

cpl.core.DataNotFoundError – If a column with the specified name is not found in self, or it just contains invalid elements, or table length is zero
cpl.core.InvalidTypeError – If the requested column is not numerical

get_column_stdev(self: cpl.core.Table, name: str) → float¶

Find the standard deviation of a table column.

Invalid column values are excluded from the computation of the standard deviation. If just one valid element is found, 0.0 is returned but no error is set. The table selection flags have no influence on the result.

Parameters:

name (str) – Column name.

Returns:

Standard deviation

Return type:

float

Raises:

cpl.core.DataNotFoundError – If a column with the specified name is not found in self, or it just contains invalid elements, or table length is zero
cpl.core.InvalidTypeError – If the requested column is not numerical

get_column_type(self: cpl.core.Table, name: str) → cpl.core.Type¶

Get the type of a table column.

Get the type of a column.

Parameters:: name (str) – Column name.
Returns:: The column type of name
Return type:: cpl.core.Type
Raises:: cpl.core.DataNotFoundError – A column with the given name not found in table.

get_column_unit(self: cpl.core.Table, name: str) → str | None¶

Get the unit of a table column.

Return the unit of a column if present, otherwise None is returned.

Parameters:: name (str) – Column name.
Returns:: Unit of column.
Return type:: str
Raises:: cpl.core.DataNotFoundError – A column with the given name not found in table.

has_invalid(self: cpl.core.Table, name: str) → bool¶

Check if a column contains at least one invalid value.

Check if there are invalid elements in a column. In case of columns of arrays, invalid values within an array are not considered.

Parameters:: name (str) – Name of table column to access.
Returns:: True if the column contains at least one invalid element
Return type:: bool
Raises:: cpl.core.DataNotFoundError – A column with the given name is not found in self.

has_valid(self: cpl.core.Table, name: str) → bool¶

Check if a column contains at least one valid value.

Check if there are valid elements in a column. In case of columns of arrays, invalid values within an array are not considered.

Parameters:: name (str) – Name of table column to access.
Returns:: True if the column contains at least one valid element
Return type:: bool
Raises:: cpl.core.DataNotFoundError – A column with the given name is not found in self.

imag_column(self: cpl.core.Table, name: str) → None¶

Compute the imaginary part value of table column elements.

Each column element is replaced by its imaginary party value only. Invalid elements are not modified by this operation. If the column is complex, its type will be turned to real (cpl.core.Type.FLOAT_COMPLEX will be changed into cpl.core.Type.FLOAT, and cpl.core.Type.DOUBLE_COMPLEX will be changed into cpl.core.Type.DOUBLE). Existing references to the column data should be considered as invalid after calling this method.

Parameters:

name (str) – Column name.

Raises:

cpl.core.DataNotFoundError – If a column with the specified name is not found in self
cpl.core.InvalidTypeError – If the requested column is not numerical or complex

insert(self: cpl.core.Table, insert_table: cpl.core.Table, row: int) → None¶

Insert a table into self

The input tables must have the same structure, as defined by the function

Parameters:

insert_table (cpl.core.Table) – Table to be inserted in the target table.
row (int) – Row where to insert the insert table.

Raises:

cpl.core.AccessOutOfRangeError – row is negative
cpl.core.IncompatibleInputError – self and insert_table do not have the same structure.

insert_window(self: cpl.core.Table, start: int, count: int) → None¶

Insert a segment of rows into table data.

Insert a segment of empty rows, just containing invalid elements. Setting start to a number greater than the column length is legal, and has the effect of appending extra rows at the end of the table: this is equivalent to expanding the table using set_size(). The input column may also have zero length.

The table selection flags are set back to “all selected”.

Parameters:

start (int) – Row where to insert the segment.
count (int) – Length of the segment.

Raises:

cpl.core.AccessOutOfRangeError – start is negative
cpl.core.IllegalInputError – count is negative

is_selected(self: cpl.core.Table, row: int) → bool¶

Determine whether a table row is selected or not.

Parameters:

row (int) – Table row to check.

Returns:

True if row is selected. False if its not.

Return type:

bool

Raises:

cpl.core.DataNotFoundError – If a column with any of the specified names is not found in table.
cpl.core.InvalidTypeError – Invalid types for comparison.

See also

cpl.core.Table.and_selected: To select from already selected rows using column comparison

is_valid(self: cpl.core.Table, name: str, row: int) → bool¶

Check if a column element is valid.

Parameters:

name (str) – Name of table column to access.
row (int) – Column element to examine.

Returns:

True if the column element is valid, False if invalid

Return type:

bool

Raises:

cpl.core.DataNotFoundError – A column with the given name is not found in self.

static load(filename: str, xtnum: int, check_nulls: bool = True) → cpl.core.Table¶

Load a FITS table extension to generate a new cpl.core.Table

The selected FITS file table extension is just read and converted into the cpl.core.Table object.

Parameters:

filename (str) – Name of FITS file with at least one table extension.
xtnum (int) – Number of extension to read, starting from 1.
check_nulls (bool, optional) – If set to False, identified invalid values are not marked.

Returns:

New cpl.core.Table from loaded data.

Return type:

cpl.core.Table

Raises:

cpl.core.FileNotFoundError – A file named as specified in filename is not found.
cpl.core.BadFileFormatError – The input file is not in FITS format.
cpl.core.IllegalInputError – The specified FITS file extension is not a table, or, if it is a table, it has more than 9999 columns.
cpl.core.AccessOutOfRangeError – xtnum is greater than the number of FITS extensions in the FITS file, or is less than 1.
cpl.core.DataNotFoundError – The FITS table has no rows or no columns.
cpl.core.UnspecifiedError – Generic error condition, that should be reported to the CPL Team.

See also

cpl.core.Table.load_window: Load part of the FITS table extension

static load_window(filename: str, xtnum: int, start: int, nrow: int, check_nulls: bool = True, cols: List[str] = []) → cpl.core.Table¶

Load part of a FITS table extension to generate a new cpl.core.Table

The selected FITS file table extension is just read and converted into the cpl.core.Table object.

Parameters:

filename (str) – Name of FITS file with at least one table extension.
xtnum (int) – Number of extension to read, starting from 1.
start (int) – First table row to extract.
nrow (int) – Number of rows to extract.
check_nulls (bool, optional) – If set to False, identified invalid values are not marked.
cols (list of str, optional) – List of the names of the columns to extract. If not given all columns are selected.

Returns:

New cpl.core.Table from loaded data.

Return type:

cpl.core.Table

Raises:

cpl.core.FileNotFoundError – A file named as specified in filename is not found.
cpl.core.BadFileFormatError – The input file is not in FITS format.
cpl.core.IllegalInputError – The specified FITS file extension is not a table, or, if it is a table, it has more than 9999 columns.
cpl.core.AccessOutOfRangeError – xtnum is greater than the number of FITS extensions in the FITS file, or is less than 1. Or start is either less than zero, or greater than the number of rows in the table.
cpl.core.DataNotFoundError – The FITS table has no rows or no columns.
cpl.core.UnspecifiedError – Generic error condition, that should be reported to the CPL Team.

See also

cpl.core.Table.load_window: Load the entire FITS table extension

logarithm_column(self: cpl.core.Table, name: str, base: float) → None¶

Compute the logarithm of column values.

Each column element is replaced by its logarithm in the specified base. The operation is always performed in double precision, with a final cast of the result to the target column type. Invalid elements are not modified by this operation, but zero or negative elements are invalidated by this operation. In case of complex numbers, values very close to the origin may cause an overflow. The imaginary part of the result is chosen in the interval [-pi/ln(base),pi/ln(base)], so it should be kept in mind that doing the logarithm of exponential of a complex number will not always express the phase angle with the same number. For instance, the exponential in base 2 of (5.00, 5.00) is (-30.33, -10.19), and the logarithm in base 2 of the latter will be expressed as (5.00, -4.06).

Parameters:

name (str) – Table column name.
base (float) – Logarithm base.

Raises:

cpl.core.DataNotFoundError – If a column with the specified name is not found in self
cpl.core.InvalidTypeError – If the requested column is not numerical, or is an array column
cpl.core.IllegalInputError – base is not positive

move_column(self: cpl.core.Table, name: str, from_table: cpl.core.Table) → None¶

Move a column from a table to self.

Parameters:

name (str) – Name of column to move.
from_table (cpl.core.Table) – Source table.

Raises:

cpl.core.DataNotFoundError – A column with the given name is not found in from_table.
cpl.core.IncompatibleInputError – self and from_table do not have the same number of rows
cpl.core.IllegalInputError – self and from_table are the same table (object)
cpl.core.IllegalOutputError – name already exists as a column in self

multiply_columns(self: cpl.core.Table, to_name: str, from_name: str) → None¶

Multiply two numeric or complex table columns.

The columns are multiplied element by element, and the result of the multiplication is stored in the target column. See the documentation of the function add_columns() for further details.

Parameters:

to_name (str) – Name of target column.
from_name (str) – Name of column to be multiplied with target column.

multiply_scalar(self: cpl.core.Table, name: str, value: float) → None¶

Multiply a numerical or complex column by a constant.

The operation is always performed in double precision, with a final cast of the result to the target column type. Invalid elements are are not modified by this operation.

Parameters:

name (str) – Column name.
value (float) – Multiplication factor.

Raises:

cpl.core.DataNotFoundError – If a column with the specified name is not found in self
cpl.core.InvalidTypeError – If the requested column is not numerical, or is an array column

multiply_scalar_complex(self: cpl.core.Table, name: str, value: complex) → None¶

Multiply a numerical or complex column by a complex constant.

The operation is always performed in double precision, with a final cast of the result to the target column type. Invalid elements are are not modified by this operation.

Parameters:

name (str) – Column name.
value (complex) – Multiplication factor.

Raises:

cpl.core.DataNotFoundError – If a column with the specified name is not found in self
cpl.core.InvalidTypeError – If the requested column is not numerical, or is an array column

name_column(self: cpl.core.Table, from_name: str, to_name: str) → None¶

Rename a table column.

This function is used to change the name of a column.

Parameters:

from_name (str) – Name of table column to rename.
to_name (str) – New name of column.

Raises:

cpl.core.DataNotFoundError – A column with the given from_name is not found in self.
cpl.core.IllegalOutputError – name already exists as a column in self

new_column(self: cpl.core.Table, name: str, type: cpl.core.Type) → None¶

Create an empty column in a table.

Creates a new column of specified type, excluding array types (for creating a column of arrays use the function new_column_array(), where the column depth must also be specified).

The new column name must be different from any other column name in the table. All the elements of the new column are marked as invalid.

Parameters:

name (str) – Name of the new column.
type (cpl.core.Type) – Type of the new column.

Raises:

cpl.core.InvalidTypeError – type is not supported by cpl.core.Table
cpl.core.IllegalOutputError – column with the same name already exists in the table

new_column_array(self: cpl.core.Table, name: str, type: cpl.core.Type, depth: int) → None¶

Create an empty column of arrays in a table.

This creates a new column of specified array length.

Parameters:

name (str) – Name of the new column.
type (cpl.core.Type) – Type of the new column.
depth (int) – Depth of the new column.

Raises:

cpl.core.InvalidTypeError – type is not supported by cpl.core.Table
cpl.core.IllegalInputError – The specified depth is negative
cpl.core.IllegalOutputError – column with the same name already exists in the table

not_selected(self: cpl.core.Table) → int¶

Select unselected table rows, and unselect selected ones.

Returns:: New number of selected rows
Return type:: int

or_selected(self: cpl.core.Table, name1: str, operator: cpl.core.Table.Operator, name2: str) → int¶

Select from unselected table rows, by comparing the values of two columns.

Either both columns must be numerical, or they both must be strings. The comparison between strings is lexicographical. Neither can be a complex or array type.

For all unselected table rows, the values of the specified column are compared. All the table rows fulfilling the comparison are selected. Invalid elements from either columns never fulfill any comparison by definition.

For this function, the column is of a numerical type if its type is: * cpl.core.Type.INT * cpl.core.Type.FLOAT * cpl.core.Type.DOUBLE * cpl.core.Type.LONG_LONG

Allowed relational operators are * cpl.core.Operator.EQUAL_TO * cpl.core.Operator.NOT_EQUAL_TO * cpl.core.Operator.GREATER_THAN * cpl.core.Operator.NOT_GREATER_THAN * cpl.core.Operator.LESS_THAN * cpl.core.Operator.NOT_LESS_THAN

Parameters:

name1 (str) – Name of the first table column
operator (cpl.core.Operator) – Relational Operator. See extended summary for allowed operators.
name2 (str) – Name of second table column.

Returns:

New number of selected rows

Return type:

int

Raises:

cpl.core.DataNotFoundError – If a column with any of the specified names is not found in table.
cpl.core.InvalidTypeError – Invalid types for comparison.

See also

cpl.core.Table.and_selected: To select from already selected rows using column comparison

or_selected_invalid(self: cpl.core.Table, name: str) → int¶

Select from unselected table rows all rows with an invalid value in a specified column.

For all the unselected table rows, all the rows containing invalid values at the specified column are selected.

Parameters:: name (str) – Column name.
Returns:: New number of selected rows
Return type:: int

or_selected_numerical(self: cpl.core.Table, name: str, operator: cpl.core.Table.Operator, value: object) → None¶

Select from unselected table rows, by comparing a column of numerical values to the reference value

For all the unselected table rows, the values of the specified column are compared with the reference value.

The column is of a numerical type if its type is: * cpl.core.Type.INT * cpl.core.Type.FLOAT * cpl.core.Type.DOUBLE * cpl.core.Type.DOUBLE_COMPLEX * cpl.core.Type.FLOAT_COMPLEX * cpl.core.Type.LONG_LONG

All table rows fulfilling the comparison are selected. An invalid element never fulfills any comparison by definition. Allowed relational operators are * cpl.core.Operator.EQUAL_TO * cpl.core.Operator.NOT_EQUAL_TO * cpl.core.Operator.GREATER_THAN * cpl.core.Operator.NOT_GREATER_THAN * cpl.core.Operator.LESS_THAN * cpl.core.Operator.NOT_LESS_THAN

Parameters:

name (str) – Column name.
operator (cpl.core.Operator) – Relational Operator. See extended summary for allowed operators.
value (int, float or complex) – Reference value

Returns:

New number of selected rows

Return type:

int

Raises:

cpl.core.DataNotFoundError – if the column of the given name wasn’t found.
cpl.core.TypeMismatchError – Column of the given name is not numerical

See also

cpl.core.Table.and_selected_numerical: To select from already selected rows using numerical operator comparison

or_selected_string(self: cpl.core.Table, name: str, operator: cpl.core.Table.Operator, string: str) → int¶

Select from unselected table rows, by comparing a column of string values to the given string.

For all the unselected table rows, the values of the specified column are compared with the reference string. The table rows fulfilling the comparison are selected. An invalid element never fulfills any comparison by definition.

If operator is equal to cpl.core.Operator.EQUAL_TO or cpl.core.Operator.NOT_EQUAL_TO then the comparison string is treated as a regular expression.

Allowed relational operators are * cpl.core.Operator.EQUAL_TO * cpl.core.Operator.NOT_EQUAL_TO * cpl.core.Operator.GREATER_THAN * cpl.core.Operator.NOT_GREATER_THAN * cpl.core.Operator.LESS_THAN * cpl.core.Operator.NOT_LESS_THAN

Parameters:

name (str) – Column name.
operator (cpl.core.Operator) – Relational Operator. See extended summary for allowed operators.
string (str) – Reference character string

Returns:

New number of selected rows

Return type:

int

Raises:

cpl.core.DataNotFoundError – if the column of the given name wasn’t found.
cpl.core.TypeMismatchError – Column of the given name is not of type cpl.core.Type.STRING
cpl.core.IllegalInputError – Invalid regular expression

See also

cpl.core.Table.and_selected_string: To select from already selected rows using string comparison

or_selected_window(self: cpl.core.Table, start: int, count: int) → int¶

Select from unselected rows only those within a table segment.

All the unselected table rows that are within the specified interval are selected. If the sum of start and count goes beyond the end of the input table, rows are checked up to the end of the table.

Parameters:

start (int) – First row of table segment.
count (int) – Length of segment

Returns:

New number of selected rows

Return type:

int

Raises:

cpl.core.AccessOutOfRange – self has zero length, or start is outside self’s boundaries
cpl.core.IllegalInputError – count is negative

See also

cpl.core.Table.and_selected_window: To select from already selected rows using a specified segment

power_column(self: cpl.core.Table, name: str, exponent: float) → None¶

Compute the power of numerical column values.

Each column element is replaced by its power to the specified exponent. For float and float complex the operation is performed in single precision, otherwise it is performed in double precision and then rounded if the column is of an integer type. Results that would or do cause domain errors or overflow are marked as invalid.

Parameters:

name (str) – Name of column of numerical type
exponent (float) – Constant exponent.

Raises:

cpl.core.DataNotFoundError – If a column with the specified name is not found in self
cpl.core.InvalidTypeError – If the requested column is not numerical

real_column(self: cpl.core.Table, name: str) → None¶

Compute the real part value of table column elements.

Each column element is replaced by its real party value only. Invalid elements are not modified by this operation. If the column is complex, its type will be turned to real (cpl.core.Type.FLOAT_COMPLEX will be changed into cpl.core.Type.FLOAT, and cpl.core.Type.DOUBLE_COMPLEX will be changed into cpl.core.Type.DOUBLE).

Parameters:

name (str) – Column name.

Raises:

cpl.core.DataNotFoundError – If a column with the specified name is not found in self
cpl.core.InvalidTypeError – If the requested column is not numerical or complex

save(self: cpl.core.Table, pheader: cpl.core.PropertyList | None, header: cpl.core.PropertyList, filename: str, mode: int) → None¶

Save a CPL table to a FITS file.

This function can be used to convert a CPL table into a binary FITS table extension. If the mode is set to cpl.core.IO.CREATE, a new FITS file will be created containing an empty primary array, with just one FITS table extension. An existing (and writable) FITS file with the same name would be overwritten. If the mode flag is set to cpl.core.IO.EXTEND, a new table extension would be appended to an existing FITS file. If mode is set to cpl.core.IO.APPEND it is possible to add rows to the last FITS table extension of the output FITS file.

Note that the modes cpl.core.IO.EXTEND and cpl.core.IO.APPEND require that the target file must be writable (and do not take for granted that a file is writable just because it was created by the same application, as this depends on the system umask).

When using the mode cpl.core.IO.APPEND additional requirements must be fulfilled, which are that the column properties like type, format, units, etc. must match as the properties of the FITS table extension to which the rows should be added exactly. In particular this means that both tables use the same null value representation for integral type columns!

Two property lists may be passed to this function, both optionally. The first property list, pheader, is just used if the mode is set to cpl.core.IO.CREATE, and it is assumed to contain entries for the FITS file primary header. In pheader any property name related to the FITS convention, as SIMPLE, BITPIX, NAXIS, EXTEND, BLOCKED, and END, are ignored: such entries would be written anyway to the primary header and set to some standard values.

If a no pheader is passed, the primary array would be created with just such entries, that are mandatory in any regular FITS file. The second property list, header, is assumed to contain entries for the FITS table extension header. In this property list any property name related to the FITS convention, as XTENSION, BITPIX, NAXIS, PCOUNT, GCOUNT, and END, and to the table structure, as TFIELDS, TTYPEi, TUNITi, TDISPi, TNULLi, TFORMi, would be ignored: such entries are always computed internally, to guarantee their consistency with the actual table structure. A DATE keyword containing the date of table creation in ISO8601 format is also added automatically.

Using the mode cpl.core.IO.APPEND requires that the column properties of the table to be appended are compared to the column properties of the target FITS extension for each call, which introduces a certain overhead. This means that appending a single table row at a time may not be efficient and is not recommended. Rather than writing one row at a time one should write table chunks containing a suitable number or rows.

Parameters:

pheader (cpl.core.Propertylist) – Primary header entries.
header (cpl.core.Propertylist) – Table header entries.
filename (str) – Name of output FITS file.
mode (unsigned) – Output mode.

Notes

Invalid strings in columns of type cpl.core.Type.STRING are written to FITS as blanks.

select_all(self: cpl.core.Table) → None¶

Select all table rows.

The table selection flags are reset, meaning that they are all marked as selected. This is the initial state of any table.

select_row(self: cpl.core.Table, row: int) → None¶

Flag a table row as selected.

Flag a table row as selected. Any previous selection is kept.

Parameters:: row (int) – Row to select.
Raises:: cpl.core.AccessOutOfRangeError – self has a length of zero, or row is outside the table boundaries.

set_column_depth(self: cpl.core.Table, name: str, depth: int) → None¶

Modify depth of a column of arrays

This function is applicable just to columns of arrays. The contents of the arrays in the specified column will be unchanged up to the lesser of the new and old depths. If the depth is increased, the extra array elements would be flagged as invalid. Existing references to the array data should be considered invalid after calling this method.

Parameters:

name (str) – Column name.
depth (int) – New column depth.

set_column_dimensions(self: cpl.core.Table, name: str, dimensions: List[int]) → None¶

Set the dimensions of a table column of arrays.

Set the number of dimensions of a column. If the dimensions array has size less than 2, nothing is done and no error is returned.

Parameters:

name (str) – Column name.
dimensions (list of int) – the sizes of the column dimensions

Raises:

cpl.core.DataNotFoundError – A column with the given name not found in table.
cpl.core.IllegalInputError – A column with the given name is not of type cpl.core.Type.ARRAY, or dimensions contains invalid elements
cpl.core.IncompatibleInputError – The specified dimensions are incompatible with the total number of elements in the column arrrays.

set_column_format(self: cpl.core.Table, name: str, format: str) → None¶

Give a new format to a table column.

The input format string is duplicated before being used as the column format. If no format is set, “%s” will be used if the column is of type cpl.core.Type.STRING, “%1.5e” if the column is of type cpl.core.Type.FLOAT or cpl.core.Type.DOUBLE, and “%7d” if it is of type cpl.core.Type.INT. The format associated to a column has no effect on any operation performed on columns, and it is used just while printing a table using the function dump().

This information is lost after saving the table in FITS format using save().

Parameters:

name (str) – Column name.
format (str) – New format.

Raises:

cpl.core.DataNotFoundError – A column with the given name not found in table.

set_column_invalid(self: cpl.core.Table, name: str, start: int, count: int) → None¶

Invalidate a column segment.

All the column elements in the specified interval are invalidated. In the case of either a string or an rray column, the corresponding strings or arrays are set free. If the sum of start and count exceeds the number of rows in the table, the column is invalidated up to its end.

Parameters:

name (str) – Name of table column to access.
start (int) – Position where to begin invalidation.
count (int) – Number of column elements to invalidate.

Raises:

cpl.core.DataNotFoundError – A column with the given name is not found in self.
cpl.core.AccessOutOfRangeError – self has zero length, or start is outside the table boundaries.
cpl.core.IllegalInputError – count is negative

set_column_unit(self: cpl.core.Table, name: str, unit: str) → None¶

Give a new unit to a table column.

The input unit string is duplicated before being used as the column unit.

The unit associated to a column has no effect on any operation performed on columns, and it must be considered just an optional description of the content of a column. It is however saved to a FITS file when using save().

Parameters:

name (str) – Column name.
unit (str) – New unit.

Raises:

cpl.core.DataNotFoundError – A column with the given name not found in table.

set_invalid(self: cpl.core.Table, name: str, row: int) → None¶

Flag a column element as invalid.

The column element given by the column name name and the row number row is flagged as invalid. This also means that the data which was stored in this table cell becomes inaccessible. To reset an invalid column cell it must be updated with a new value.

Parameters:

name (str) – Name of table column to access.
row (int) – Table row to set to invalid.

Raises:

cpl.core.AccessOutOfRangeError – self has zero length or row is outside table self’s boundaries
cpl.core.DataNotFoundError – A column with the given name is not found in self.

set_size(self: cpl.core.Table, new_length: int) → None¶

Resize a table to a new number of rows.

The contents of the columns will be unchanged up to the lesser of the new and old sizes. If the table is expanded, the extra table rows would just contain invalid elements. The table selection flags are set back to “all selected”. Existing eferences to the column data should be considered invalid after calling this method.

Parameters:: new_length (int) – New number of rows in table.

shift_column(self: cpl.core.Table, name: str, shift: int) → None¶

Shift the position of numeric or complex column values.

The position of all column values is shifted by the specified amount. If shift is positive, all values will be moved toward the bottom of the column, otherwise toward its top. In either case as many column elements as the amount of the shift will be left undefined, either at the top or at the bottom of the column according to the direction of the shift. These column elements will be marked as invalid. This function is applicable just to numeric and complex columns, and not to strings and or array types. The selection flags are always set back to “all selected” after this operation.

Parameters:

name (str) – Name of table column to shift.
shift (int) – Shift column values by so many rows.

sort(self: cpl.core.Table, reflist: cpl.core.PropertyList) → None¶

Sort table rows according to columns values.

The table rows are sorted according to the values of the specified reference columns. The reference column names are listed in the input

Parameters:: reflist (cpl.core.Propertylist) – Names of reference columns with corresponding sorting mode.

subtract_columns(self: cpl.core.Table, to_name: str, from_name: str) → None¶

Subtract two numeric or complex table columns.

The columns are subtracted element by element, and the result of the subtraction is stored in the target column. See the documentation of the function add_columns() for further details.

Parameters:

to_name (str) – Name of target column.
from_name (str) – Name of column to be subtracted from target column.

subtract_scalar(self: cpl.core.Table, name: str, value: float) → None¶

Subtract a constant value from a numerical or complex column.

See the description of the function add_scalar().

Parameters:

name (str) – Column name.
value (float) – Value to subtract.

subtract_scalar_complex(self: cpl.core.Table, name: str, value: complex) → None¶

Subtract a constant complex value from a numerical or complex column.

The operation is always performed in double precision, with a final cast of the result to the target column type. Invalid elements are are not modified by this operation.

Parameters:

name (str) – Column name.
value (complex) – Value to subtract.

Raises:

cpl.core.DataNotFoundError – If a column with the specified name is not found in self
cpl.core.InvalidTypeError – If the requested column is not numerical, or is an array column

to_records(self: cpl.core.Table) → object¶

Convert the cpl.core.Table to a numpy recarray

Returns:: numpy recarray containing entries and values from the cpl.core.Table
Return type:: numpy.recarray

unselect_all(self: cpl.core.Table) → None¶

Unselect all table rows.

The table selection flags are all unset, meaning that no table rows are selected.

unselect_row(self: cpl.core.Table, row: int) → None¶

Flag a table row as unselected.

Flag a table row as unselected. Any previous selection is kept.

Parameters:: row (int) – Row to unselect.
Raises:: cpl.core.AccessOutOfRangeError – self has a length of zero, or row is outside the table boundaries.

where_selected(self: cpl.core.Table) → numpy.ndarray¶

Get array of indexes to selected table rows

Get array of indexes to selected table rows. If no rows are selected, an array of size zero is returned.

Returns:: Indexes to selected table rows
Return type:: list of int

property column_names¶: list of all column names

property selected¶

number of selected rows in given table.

Type:: int

property shape¶: Shape of the table in the format (rows, columns)

class cpl.core.Type¶

Members:

UNSPECIFIED

CHAR

UCHAR

BOOL

SHORT

USHORT

INT

UINT

LONG

ULONG

LONG_LONG

SIZE

FLOAT

DOUBLE

FLOAT_COMPLEX

DOUBLE_COMPLEX

STRING

ARRAY

property name¶

class cpl.core.Vector¶

Class for ordered sequences of numbers.

A cpl.core.Vector contains an ordered list of double precision floating point numbers. It has methods for sorting, statistics, and other simple operations. Two Vectors may be combined into a cpl.core.Bivector to represent sequences of x and y values.

A Vector can also be created using the zeros class method.

Parameters:: data (iterable of floats) – An iterable object which yields floating point values.

See also

cpl.core.Bivector: Class for pairs of ordered sequences of numbers.
cpl.core.Vector.zeros: Create a Vector of given length, initialised with 0’s.

Examples

>>> vector_list = cpl.core.Vector([1, 2, 3])
... vector_tuple = cpl.core.Vector((4, 5, 6))
... vector_copy = cpl.core.Vector(vector_list)
... vector_zeros = cpl.core.Vector.zeros(5)

class LowPass¶

Filter type for cpl.core.Vector.filter_lowpass_create

Members:

LINEAR

GAUSSIAN

property name¶

add(self: cpl.core.Vector, other: cpl.core.Vector) → None¶

Add a cpl.core.Vector to self

The other vector must have the same size as the calling vector

Parameters:: other (cpl.core.Vector) – Vector to add

add_scalar(self: cpl.core.Vector, value: float) → None¶

Elementwise addition of a scalar to a vector

Add a number to each element of the vector.

Parameters:: value (float) – Number to add

binary_search(self: cpl.core.Vector, value: float) → int¶

In a sorted (ascending) vector find the element closest to the given value

Bisection is used to find the element.

If two (neighboring) elements with different values both minimize fabs(sorted[index] - key) the index of the larger element is returned.

If the vector contains identical elements that minimize fabs(sorted[index] - key) then it is undefined which element has its index returned.

Use cpl.core.Vector.sort(cpl.core.Sort.ASCENDING) before calling this function to ensure the vector is sorted correctly

Parameters:: value (float) – Value to find
Returns:: The index that minimizes fabs(sorted[index] - value)
Return type:: int
Raises:: cpl.core.IllegalInputError – If the vector is not correctly sorted in ascending order.

copy(self: cpl.core.Vector) → cpl.core.Vector¶

Copy the contents of the Vector into a new Vector objects.

Vectors can also be copied by passing a Vector to the Vector constructor.

Returns:: New Vector containing a copy of the contents of the original.
Return type:: cpl.core.Vector

See also

cpl.core.Vector: Class for ordered sequences of numbers.

static correlate(v1: cpl.core.Vector, v2: cpl.core.Vector, max_shift: int) → Tuple[cpl.core.Vector, int]¶

Return cross-correlation of two vectors.

The length of v2 may not exceed that of v1. If the difference in length between v1 and v2 is less than max_shift then this difference must be even (if the difference is odd resampling of v2 may be useful).

The cross-correlation is in fact the dot product of two unit vectors and therefore ranges from -1 to 1.

The cross-correlation is computed with shifts ranging from -max_shift to +max_shift.

On success, element i (starting with 0) of the returned cpl.core.Vector contains the cross-correlation at offset i - max_shift.

If v1 is longer than v2, the first element in v1 used for the resulting cross-correlation is max(0, shift + (len(v1) - len(v2)) / 2).

Parameters:

v1 (cpl.core.Vector) – 1st vector to correlate
v2 (cpl.core.Vector) – 2nd vector to correlate
max_shift (int) – Maximum size of shift to be used when calculating cross correlation.

Returns:

cpl.core.Vector – New Vector of size 2 * max_shift + 1 containing the cross correlation of v1 and v2 for shifts ranging from -max_shift to +max_shift.
int – Index of output Vector at which the maximum cross correlation value occurs.

Raises:

cpl.core.IllegalInputError – if v1 and v2 have incompatible sizes.

Notes

The cross-correlation is, in absence of rounding errors, commutative only for equal-sized vectors, i.e. changing the order of v1 and v2 will move element j in the returned Vector to 2 * max_shift - j and thus change the index of maximum cross correlation from i to 2 * max_shift - i.

If, in absence of rounding errors, more than one shift would give the maximum cross-correlation, rounding errors may cause any one of those shifts to be returned. If rounding errors have no effect the index corresponding to the shift with the smallest absolute value is returned (with preference given to the smaller of two indices that correspond to the same absolute shift).

Cross-correlation with max_shift == 0 requires about 8n FLOPs, where n is the number of elements of v2.

Each increase of max_shift by 1 requires about 4n FLOPs more, when all elements of v2 can be cross-correlated, otherwise the extra cost is about 4m, where m is the number of elements in v2 that can be cross-correlated, n - max_shift <= m < n.

Example of 1D-wavelength calibration (error handling omitted for brevity):

# Dispersion is of type cpl.core.Polynomial
# The return type of mymodel() and myobservation() is cpl.core.Vector
model = mymodel(dispersion)
observed = myobservation()
vxc, max_index = cpl.core.Vector.correlate(model, observed, max_shift)
dispersion.shift_1d(0, max_index - max_shift)

cycle(self: cpl.core.Vector, shift: float) → None¶

Perform a cyclic shift to the right of the elements of the vector

A shift of +1 will move the last element to the first, a shift of -1 will move the first element to the last, a zero-shift will perform a copy (or do nothing in case of an in-place operation).

A non-integer shift will perform the shift in the Fourier domain. Large discontinuities in the vector to shift will thus lead to FFT artifacts around each discontinuity.

Parameters:: shift (float) – The number of positions to cyclic right-shift
Raises:: cpl.core.UnsupportedModeError – if the shift is non-integer and FFTW is unavailable

divide(self: cpl.core.Vector, other: cpl.core.Vector) → None¶

Divide the calling vector by another vector, element-wise

If an element in vector other is zero, a cpl.core.DivisionByZeroError is thrown.

Parameters:

other (cpl.core.Vector) – Vector to divide by

Raises:

cpl.core.IncompatibleInputError – if the calling vector and other have different sizes
cpl.core.DivisionByZeroError – if other contains an element equal to zero.

divide_scalar(self: cpl.core.Vector, divisor: float) → None¶

Elementwise division of a vector with a scalar

Divide each element of the vector with a number.

Parameters:: divisor (float) – Non-zero number to divide with

dump(self: cpl.core.Vector, filename: str | None = '', mode: str | None = 'w', show: bool | None = True) → str¶

Dump a vector contents to a file, stdout or a string.

Each element is preceded by its index number (starting with 1!) and written on a single line.

Comment lines start with the hash character.

Parameters:

filename (str, optional) – File to dump vector contents to
mode (str, optional) – Mode to open the file with. Defaults to “w” (write, overwriting the contents of the file if it already exists), but can also be set to “a” (append, creating the file if it does not already exist or appending to the end of it if it does).
show (bool, optional) – Send vector contents to stdout. Defaults to True.

Returns:

Multiline string containing the dump of the vector contents.

Return type:

str

Notes

In principle a vector can be saved using dump() re-read using read(). This will however introduce significant precision loss due to the limited accuracy of the ASCII representation.

exponential(self: cpl.core.Vector, base: float) → None¶

Compute the exponential of all vector elements.

If the base is zero all vector elements must be positive and if the base is negative all vector elements must be integer.

Parameters:

base (float) – Exponential base.

Raises:

cpl.core.IllegalInputError – base and v are not as requested
cpl.core.DivisionByZeroError – if one of the values is negative or 0

extract(self: cpl.core.Vector, istart: int, istop: int, istep: int = 1) → cpl.core.Vector¶

Extract a sub-vector from a vector

Parameters:

istart (int) – Start index (from 0 to number of elements - 1), must be less than istop
istop (int) – Stop index (from 0 to number of elements - 1), must be greater than istart
istep (int, optional) – Extract every step element (Currently does not support any value other than the default)

Returns:

New sub-vector with the values of the requested range

Return type:

Raises:

cpl.core.AccessOutOfRangeError – if istart is less than 0 or istop is greater than the size of the vector
cpl.core.IllegalInputError – if istep is not 1, or istart is not less than istop

Notes

istep only supporting a value of 1 is to be fixed, as is allowing istop to be greater than istart.

fill(self: cpl.core.Vector, arg0: float) → None¶

Fill the Vector with a given value

Parameters:: val (float) – Value used to fill the cpl_vector

filter_lowpass_create(self: cpl.core.Vector, filter_type: cpl.core.Vector.LowPass, hw: int) → cpl.core.Vector¶

Apply a low-pass filter to a vector

This type of low-pass filtering consists in a convolution with a given kernel. The chosen filter type determines the kind of kernel to apply for convolution.

Supported kernels are cpl.core.Vector.LowPass.LINEAR and cpl.core.Vector.LowPass.GAUSSIAN.

In the case of cpl.core.Vector.LowPass.GAUSSIAN, the gaussian sigma used is 1/sqrt(2). As this function is not meant to be general and cover all possible cases, this sigma is hardcoded and cannot be changed.

The returned signal has exactly as many samples as the input signal.

Parameters:

filter_type (cpl.core.Vector.LowPass) – Type of filter to use
hw (int) – Filter half-width

Returns:

The resulting signal

Return type:

Raises:

cpl.core.IllegalInputError – if filter_type is not supported or if hw is bigger than half the vector size

filter_median_create(self: cpl.core.Vector, hw: int) → cpl.core.Vector¶

Apply a 1D median filter of given half-width to a Vector

This function applies a median smoothing to the caller Vector and returns a new Vector containing a median-smoothed version of the input.

The returned Vector has exactly as many samples as the input one. The outermost hw values are copies of the input, each of the others is set to the median of its surrounding 1 + 2 * hw values.

For historical reasons twice the half-width is allowed to equal the Vector length, although in this case the returned Vector is simply a duplicate of the input one.

If different processing of the outer values is needed or if a more general kernel is needed, then cpl.core.Image.filter_mask() can be called instead with cpl.core.Filter.MEDIAN and the 1D-image input wrapped around self.

Parameters:: hw (int) – Filter half-width
Returns:: The filtered vector.
Return type:: cpl.core.Vector
Raises:: cpl.core.IllegalInputError – if hw is negative or bigger than half the vector

static fit_gaussian(x: object, y: object, y_sigma: object, fit_pars: int, x0: float | None = None, sigma: float | None = None, area: float | None = None, offset: float | None = None) → object¶

Apply a 1d gaussian fit.

This function fits to the input vectors a 1d gaussian function of the form

\[f(x) = \mathrm{area} / \sqrt{2 \pi \sigma^2} * \exp(-(x - x0)^2 / (2 \sigma^2)) + \mathrm{offset}\]

where area > 0, by minimizing chi^2 using a Levenberg-Marquardt algorithm.

The values to fit are read from the input vector x.

The diagonal elements (the variances) are guaranteed to be positive.

Occasionally, the Levenberg-Marquardt algorithm fails to converge to a set of sensible parameters. In this case (and only in this case), a cpl.core.ContinueError is set. To allow the caller to recover from this particular error.

Parameters:

x (cpl.core.Vector) – Positions to fit
y (cpl.core.Vector) – The N values to fit.
y_sigma (cpl.core.Vector) – Uncertainty (one sigma, gaussian errors assumed) associated with y
fit_pars (cpl.core.FitMode) – Specifies which parameters participate in the fit (any other parameters will be held constant). Possible values are cpl.core.FitMode.CENTROID, cpl.core.FitMode.STDEV, cpl.core.FitMode.AREA, cpl.core.FitMode.OFFSET and cpl.core.FitMode.ALL, and any bitwise combination of these (using bitwise OR).
x0 (double, optional) – Preset center of best fit gaussian if cpl.core.FitMode.CENTROID is not used in fit_pars. Value is unused otherwise.
sigma (doublee, optional) – Width of best fit gaussian if cpl.core.FitMode.STDEV is not used in fit_pars. Value is unused otherwise.
area (doublee, optional) – Area of gaussian if cpl.core.FitMode.AREA is not used in fit_pars. Value is unused otherwise.
offset (doublee, optional) – Fitted background level if cpl.core.FitMode.OFFSET is not used in fit_pars. Value is unused otherwise.

Returns:

A FitGaussianResult NamedTuple with the following elements:

x0float: Center of best fit gaussian.
sigmafloat: Width of best fit gaussian. A positive number on success.
areafloat: Area of gaussian. A positive number on succes.
offsetfloat: Fitted background level.
msefloat: the mean squared error of the best fit
red_chisqfloat: the reduced chi-squared of the best fit. None if y_sigma is not passed
covariancecpl.core.Matrix: The formal covariance matrix of the best fit, On success the diagonal terms of the covariance matrix are guaranteed to be positive. However, terms that involve a constant parameter (as defined by the input array evaluate_derivatives) are always set to zero. None if y_sigma is not passed

Return type:

NamedTuple(float, float, float, float, float, float, cpl.core.Matrix)

Raises:

cpl.core.InvalidTypeError – if the specified fit_pars is not a bitwise combination of the allowed values (e.g. 0 or 1).
cpl.core.IncompatibleInputError – if the sizes of any input vectors are different, or if the computation of reduced chi square or covariance is requested, but sigma_y is not provided.
cpl.core.IllegalInputError – if any input noise values, sigma or area is non-positive, or if chi square computation is requested and there are less than 5 data points to fit, or if an initial value is required for x0, sigma, area or offset when a fit_pars mode is not present.
cpl.core.IllegalOutputError – if memory allocation failed.
cpl.core.ContinueError – if the fitting algorithm failed.
cpl.core.SingularMatrixError – if the covariance matrix could not be calculated.

static kernel_profile(type: cpl.core.Kernel, radius: float, size: int) → cpl.core.Vector¶

Return a Vector containing a kernel profile.

A number of predefined kernel profiles are available: - cpl.core.Kernel.DEFAULT: default kernel, currently cpl.core.Kernel.TANH - cpl.core.Kernel.TANH: Hyperbolic tangent - cpl.core.Kernel.SINC: Sinus cardinal - cpl.core.Kernel.SINC2: Square sinus cardinal - cpl.core.Kernel.LANCZOS: Lanczos2 kernel - cpl.core.Kernel.HAMMING: Hamming kernel - cpl.core.Kernel.HANN: Hann kernel - cpl.core.Kernel.NEAREST: Nearest neighbor kernel (1 when dist < 0.5, else 0)

Parameters:

type (cpl.core.Kernel) – Type of kernel profile.
radius (float) – Radius of the profile in pixels
size (int) – Size of the kernel profile in pixels.

Returns:

Vector of length size containing the calculated kernel values.

Return type:

Raises:

cpl.core.IllegalInputError – if radius is non-positive, or in case of the cpl.core.Kernel.TANH profile if size exceeds 32768

static load(filename: str, xtnum: int) → cpl.core.Vector¶

Load a list of values from a FITS file

This function loads a vector from a FITS file (NAXIS = 1).

xtnum specifies from which extension the vector should be loaded. This could be 0 for the main data section or any number between 1 and N, where N is the number of extensions present in the file.

Parameters:

filename (str) – Name of the input file
xtnum (int) – Extension number in the file (0 for primary HDU)

Returns:

The loaded vector from the file, at extension xtnum

Return type:

Raises:

cpl.core.IllegalInputError – if the extension is not valid
cpl.core.FileIOError – if the file cannot be read
cpl.core.UnsupportedModeError – if the file is too large to be read

logarithm(self: cpl.core.Vector, base: float) → None¶

Compute the element-wise logarithm.

The base and all the vector elements must be positive and the base must be different from 1.

Parameters:

base (float) – Logarithm base.

Raises:

cpl.core.IllegalInputError – if base is negative or zero or if one of the vector values is negative or zero
cpl.core.DivisionByZeroError – if a division by zero occurs

max(self: cpl.core.Vector) → float¶

Get the maximum of the vector

Returns:: The maximum value of the vector
Return type:: float

maxpos(self: cpl.core.Vector) → int¶

Get the index of the maximum element of the vector

Returns:: The index (0 for first) of the maximum value
Return type:: int

mean(self: cpl.core.Vector) → float¶

Get the mean of the elements of the vector

Returns:: The mean of the elements value of the vector
Return type:: float

median(self: cpl.core.Vector) → float¶

Get the median of the elements of the vector

Returns:: The median of the elements value of the vector
Return type:: float

min(self: cpl.core.Vector) → float¶

Get the minimum of the vector

Returns:: The minimum value of the vector
Return type:: float

minpos(self: cpl.core.Vector) → int¶

Get the index of the minimum element of the vector

Returns:: The index (0 for first) of the minimum value
Return type:: int

multiply(self: cpl.core.Vector, other: cpl.core.Vector) → None¶

Multiply another vector with the calling vector, component-wise

Parameters:: other (cpl.core.Vector) – Vector to multiply with

multiply_scalar(self: cpl.core.Vector, factor: float) → None¶

Elementwise multiplication of a vector with a scalar

Multiply each element of the vector with a number.

Parameters:: factor (float) – Number to multiply with

power(self: cpl.core.Vector, exponent: float) → None¶

Compute the power of all vector elements.

If the exponent is negative all vector elements must be non-zero and if the exponent is non-integer all vector elements must be non-negative.

Parameters:

exponent (float) – Constant exponent.

Raises:

cpl.core.IllegalInputError – if v and exponent are not as requested
cpl.core.DivisionByZeroError – if one of the values is 0

Notes

Following the behaviour of C99 pow() function, this function sets 0^0 = 1.

product(self: cpl.core.Vector, other: cpl.core.Vector) → float¶

Compute the vector dot product of the caller vector and other

Parameters:: other (cpl.core.Vector) – Another vector of the same size
Returns:: The (non-negative) product
Return type:: float
Raises:: cpl.core.IncompatibleInputError – if other has a different size from the calling vector

static read(filename: str) → cpl.core.Vector¶

Read a list of values from an ASCII file and create a Vector

Parse an input ASCII file values and create a Vector from it Lines beginning with a hash are ignored, blank lines also. In valid lines the value is preceeded by an integer, which is ignored.

In addition to normal files, FIFO (see man mknod) are also supported.

Parameters:

filename (cpl.core.std::string) – Name of the input ASCII file

Returns:

A new Vector with the parsed ASCII file values

Return type: