AG_fft_tools Package

AG_fft_tools Package

FFT Tools

Wrappers around numpy, scipy, and pyfftw tools to perform 2D convolution in general, smoothing with a set of ‘standard’ kernels, and computing power spectra and PSDs.

convolve Module

AG_fft_tools.convolve.convolve(img, kernel, crop=True, return_fft=False, fftshift=True, fft_pad=True, psf_pad=False, ignore_nan=False, quiet=False, ignore_zeros=True, min_wt=1e-08, force_ignore_zeros_off=False, normalize_kernel=<function sum at 0x102671050>, debug=False, nthreads=1)

Convolve an image with a kernel. Returns something the size of an image. Assumes image & kernel are centered

NOTE Order matters; the kernel should be second.

Options: fft_pad - Default on. Zero-pad image to the nearest 2^n psf_pad - Default off. Zero-pad image to be at least the sum of the image

sizes (in order to avoid edge-wrapping when smoothing)

crop - Default on. Return an image of the size of the largest input image.

If the images are asymmetric in opposite directions, will return the largest image in both directions.

return_fft - Return the FFT instead of the convolution. Useful for making

PSDs.

fftshift - If return_fft on, will shift & crop image to appropriate

dimensions

ignore_nan - attempts to re-weight assuming NAN values are meant to be

ignored, not treated as zero.

ignore_zeros - Ignore the zero-pad-created zeros. Desirable if you have

periodic boundaries on a non-2^n grid

force_ignore_zeros_off - You can choose to turn off the ignore-zeros when padding,

but this is only recommended for purely debug purposes

min_wt - If ignoring nans/zeros, force all grid points with a weight less

than this value to NAN (the weight of a grid point with no ignored neighbors is 1.0)

normalize_kernel - if specified, function to divide kernel by to normalize it

nthreads - if fftw3 is installed, can specify the number of threads to

allow FFTs to use. Probably only helpful for large arrays

AG_fft_tools.convolve.fftw2(array, nthreads=1)

AG_fft_tools.convolve.ifftw2(array, nthreads=1)

AG_fft_tools.convolve.smooth(image, kernelwidth=3, kerneltype='gaussian', trapslope=None, silent=True, psf_pad=True, interp_nan=False, nwidths='max', min_nwidths=6, return_kernel=False, normalize_kernel=<function sum at 0x102671050>, **kwargs)

Returns a smoothed image using a gaussian, boxcar, or tophat kernel

Options: kernelwidth - width of kernel in pixels (see definitions below) kerneltype - gaussian, boxcar, or tophat.

For a gaussian, uses a gaussian with sigma = kernelwidth (in pixels)

out to [nwidths]-sigma

A boxcar is a kernelwidth x kernelwidth square A tophat is a flat circle with radius = kernelwidth

Default options:

psf_pad = True - will pad the input image to be the image size + PSF.

Slows things down but removes edge-wrapping effects (see convolve) This option should be set to false if the edges of your image are symmetric.

interp_nan = False - Will replace NaN points in an image with the

smoothed average of its neighbors (you can still simply ignore NaN values by setting ignore_nan=True but leaving interp_nan=False)

silent = True - turn it off to get verbose statements about kernel

types

return_kernel = False - If set to true, will return the kernel as the

second return value

nwidths = ‘max’ - number of kernel widths wide to make the kernel. Set to

‘max’ to match the image shape, otherwise use any integer

min_nwidths = 6 - minimum number of gaussian widths to make the kernel

(the kernel will be larger than the image if the image size is < min_widths*kernelsize)

normalize_kernel - Should the kernel preserve the map sum (i.e. kernel.sum() = 1)

or the kernel peak (i.e. kernel.max() = 1) ? Must be a function that can operate on a numpy array

Note that the kernel is forced to be even sized on each axis to assure no offset when smoothing.

correlate2d Module

AG_fft_tools.correlate2d.correlate2d(im1, im2, **kwargs)

Cross-correlation of two images of arbitrary size. Returns an image cropped to the largest of each dimension of the input images

Options: return_fft - if true, return fft(im1)*fft(im2[::-1,::-1]), which is the power

spectral density

fftshift - if true, return the shifted psd so that the DC component is in

the center of the image

pad - Default on. Zero-pad image to the nearest 2^n crop - Default on. Return an image of the size of the largest input image.

If the images are asymmetric in opposite directions, will return the largest image in both directions.

WARNING: Normalization may be arbitrary if you use the PSD

psds Module

Power Spectra

AG_fft_tools.psds.PSD2(image, image2=None, oned=False, fft_pad=False, real=False, imag=False, binsize=1.0, radbins=1, azbins=1, radial=False, hanning=False, wavnum_scale=False, twopi_scale=False, **kwargs)

Two-dimensional Power Spectral Density. NAN values are treated as zero.

image2 - can specify a second image if you want to see the cross-power-spectrum instead of the

power spectrum.

oned - return radial profile of 2D PSD (i.e. mean power as a function of spatial frequency)

freq,zz = PSD2(image); plot(freq,zz) is a power spectrum

fft_pad - Add zeros to the edge of the image before FFTing for a speed

boost? (the edge padding will be removed afterwards)

real - Only compute the real part of the PSD (Default is absolute value) imag - Only compute the complex part of the PSD (Default is absolute value) hanning - Multiply the image to be PSD’d by a 2D Hanning window before performing the FTs.

Reduces edge effects. This idea courtesy Paul Ricchiazzia (May 1993), author of the IDL astrolib psd.pro

wavnum_scale - multiply the FFT^2 by the wavenumber when computing the PSD? twopi_scale - multiply the FFT^2 by 2pi? azbins - Number of azimuthal (angular) bins to include. Default is 1, or

all 360 degrees. If azbins>1, the data will be split into [azbins] equally sized pie pieces. Azbins can also be a numpy array. See AG_image_tools.azimuthalAverageBins for details

radial - An option to return the azimuthal power spectrum (i.e., the spectral power as a function

of angle). Not commonly used.

radbins - number of radial bins (you can compute the azimuthal power spectrum in different annuli)

AG_fft_tools.psds.hanning2d(M, N)

A 2D hanning window, as per IDL’s hanning function. See numpy.hanning for the 1d description

AG_fft_tools.psds.power_spectrum(*args, **kwargs)

Thin wrapper of PSD2. Returns the 1D power spectrum in stead of the 2D Power Spectral Density

AG_fft_tools.psds.pspec(psd2, return_index=True, wavenumber=False, return_stddev=False, azbins=1, binsize=1.0, view=False, **kwargs)

Create a Power Spectrum (radial profile of a PSD) from a Power Spectral Density image

return_index - if true, the first return item will be the indexes wavenumber - if one dimensional and return_index set, will return a normalized wavenumber instead view - Plot the PSD (in logspace)?