Utility functions

Here we have a few functions that are used by internally by PyCASSO but may be useful anyway.

Function list

Created on Oct 25, 2012

@author: andre

pycasso.util.arrayAsRowMatrix(a, ndim)

Reshape a to a “row matrix” of bigger rank, ndim.

Parameters :

a : array

Array to reshape.

ndim : integer

Number of dimensions to reshape.

Returns :

a_reshaped : array

The same array as a, reshaped to ndim dimensions.

pycasso.util.gen_rebin(a, e, bin_e, mean=True)

Rebinning function. Given the value array a, with generic positions e such that e.shape == a.shape, return the sum or the mean values of a inside the bins defined by bin_e.

Parameters :

a : array like

The array values to be rebinned.

e : array like

Generic positions of the values in a.

bin_e : array like

Bins of e to be used in the rebinning.

mean : boolean

Divide the sum by the number of points inside the bin. Defaults to True.

Returns :

a_e : array

An array of length len(bin_e)-1, containing the sum or mean values of a inside each bin.

Examples

TODO: Add examples for gen_rebin.

pycasso.util.getGenHalfRadius(X, r, r_max=None)

Evaluate radius where the cumulative value of X reaches half of its value.

Parameters :

X : array like

The property whose half radius will be evaluated.

r : array like

Radius associated to each value of X. Must be the same shape as X.

r_max : int

Integrate up to r_max. Defaults to np.max(r).

Returns :

HXR : float

The “half X radius.”

Examples

Find the radius containing half of the volume of a gaussian.

>>> import numpy as np
>>> xx, yy = np.indices((100, 100))
>>> x0, y0, A, a = 50.0, 50.0, 1.0, 20.0
>>> z = A * np.exp(-((xx-x0)**2 + (yy-y0)**2)/a**2)
>>> r = np.sqrt((xx - 50)**2 + (yy-50)**2)
>>> getGenHalfRadius(z, r)
16.786338066912215

pycasso.util.getAverageFilledImage(X, to_fill, r__yx, X__r, bin_r)

TODO: getAverageFilledImage documentation.

pycasso.util.getApertureMask(pa, ba, x0, y0, N_x, N_y, apertures)

TODO: Documentation for apertures.

pycasso.util.convexHullMask(mask)

Compute the convex hull of a boolean image mask.

Parameters :

mask : array

2-D image where the True pixels mark the data.

Returns :

convex_mask : array

2-D image of same shape and type as mask, where the convex hull of mask is marked as True values.

pycasso.util.getEllipseParams(image, x0=0.0, y0=0.0, mask=None)

Estimate ellipticity and orientation of the galaxy using the “Stokes parameters”, as described in: http://adsabs.harvard.edu/abs/2002AJ....123..485S The image used is qSignal.

Parameters :

image : array

Image to use when calculating the ellipse parameters.

x0 : float

X coordinate of the origin. Defaults to 0.0.

y0 : float

Y coordinate of the origin. Defaults to 0.0.

mask : array, optional

Mask containing the pixels to take into account.

Returns :

pa : float

Position angle in radians, counter-clockwise relative to the positive X axis.

ba : float

Ellipticity, defined as the ratio between the semiminor axis and the semimajor axis (\(b/a\)).

pycasso.util.getDistance(x, y, x0=0.0, y0=0.0, pa=0.0, ba=1.0)

Return an image (numpy.ndarray) of the distance from the center (x0, y0) in pixels, assuming a projected disk.

Parameters :

x : array

X coordinates to get the pixel distances.

y : array

y coordinates to get the pixel distances.

x0 : float, optional

X coordinate of the origin. Defaults to 0.0.

y0 : float, optional

Y coordinate of the origin. Defaults to 0.0.

pa : float, optional

Position angle in radians, counter-clockwise relative to the positive X axis.

ba : float, optional

Ellipticity, defined as the ratio between the semiminor axis and the semimajor axis (\(b/a\)).

Returns :

pixelDistance : array

Pixel distances.

See also

getImageDistance

pycasso.util.getImageDistance(shape, x0=0.0, y0=0.0, pa=0.0, ba=1.0)

Return an image (numpy.ndarray) of the distance from the center (x0, y0) in pixels, assuming a projected disk.

Parameters :

shape : (float, float)

Shape of the image to get the pixel distances.

x0 : float, optional

X coordinate of the origin. Defaults to 0.0.

y0 : float, optional

Y coordinate of the origin. Defaults to 0.0.

pa : float, optional

Position angle in radians, counter-clockwise relative to the positive X axis. Defaults to 0.0.

ba : float, optional

Ellipticity, defined as the ratio between the semiminor axis and the semimajor axis (\(b/a\)). Defaults to 1.0.

Returns :

pixelDistance : 2-D array

Image containing the distances.

See also

getDistance, getEllipseParams

pycasso.util.getAngle(x, y, x0=0.0, y0=0.0, pa=0.0, ba=1.0)

Return an image (numpy.ndarray of same shape as :attr`qSignal`) of the angle in radians of each pixel, relative from the axis of the position angle pa. The projection is fixed assuming the galaxy is a disk, throught the ellipticity parameter ba.

The angle is obtained “de-rotating” the pixel positions, stretching the y-coordinates to account for the perspective, and then calculating the arc tangent of the resulting y/x.

Parameters :

x : array

X coordinates to calculate the angle.

y : array

Y coordinates to calculate the angle.

x0 : float, optional

X coordinate of the origin. Defaults to 0.0.

y0 : float, optional

Y coordinate of the origin. Defaults to 0.0.

pa : float, optional

Position angle in radians, counter-clockwise relative to the positive X axis. Defaults to 0.

ba : float, optional

Ellipticity, defined as the ratio between the semiminor axis and the semimajor axis (\(b/a\)). This controls the corretion of the projection of the galaxy. Set to 1.0 (default) to disable the correction.

Returns :

pixelAngle : 2-D array

Image containing the angles in radians.

See also

getPixelDistance

pycasso.util.getImageAngle(shape, x0=0.0, y0=0.0, pa=0.0, ba=1.0)

Return an image (numpy.ndarray of same shape as :attr`qSignal`) of the angle in radians of each pixel, relative from the axis of the position angle pa. The projection is fixed assuming the galaxy is a disk, throught the ellipticity parameter ba.

The angle is obtained “de-rotating” the pixel positions, stretching the y-coordinates to account for the perspective, and then calculating the arc tangent of the resulting y/x.

Parameters :

shape : (float, float)

Shape of the image to get the angles.

x0 : float, optional

X coordinate of the origin. Defaults to 0.0.

y0 : float, optional

Y coordinate of the origin. Defaults to 0.0.

pa : float, optional

Position angle in radians, counter-clockwise relative to the positive X axis. Defaults to 0.

ba : float, optional

Ellipticity, defined as the ratio between the semiminor axis and the semimajor axis (\(b/a\)). This controls the corretion of the projection of the galaxy. Set to 1.0 (default) to disable the correction.

Returns :

pixelAngle : 2-D array

Image containing the angles in radians.

See also

getPixelDistance

pycasso.util.radialProfile(prop, r__yx, bin_r, rad_scale=1.0, mask=None, mode='mean', return_npts=False)

Calculate the radial profile of an N-D image.

Parameters :

prop : array

Image of property to calculate the radial profile.

r__yx : array

Distance of each pixel to the galaxy center, in pixels.

bin_r : array

Semimajor axis bin boundaries in units of rad_scale.

rad_scale : float, optional

Scale of the bins, in pixels. Defaults to 1.0.

mask : array, optional

Mask containing the pixels to use in the radial profile. Must have the shape (N_y, N_x). Defaults to qMask.

mode : string, optional

One of:

• 'mean': Compute the mean inside the radial bins (default).
• 'median': Compute the median inside the radial bins.
• 'sum': Compute the sum inside the radial bins.
• 'var': Compute the variance inside the radial bins.

return_npts : bool, optional

If set to True, also return the number of points inside each bin. Defaults to False.

Returns :

radProf : [masked] array

Array containing the radial profile as the last dimension. Note that radProf.shape[-1] == (len(bin_r) - 1) If prop is a masked aray, this and npts will be a masked array as well.

npts : [masked] array, optional

The number of points inside each bin, only if return_npts is set to True.

See also

getPixelDistance