Bispectrum¶

class turbustat.statistics.Bispectrum(img)[source]¶

Bases: BaseStatisticMixIn

Computes the bispectrum (three-point correlation function) of the given image (Burkhart et al., 2010). The bispectrum and the bicoherence are returned. The bicoherence is a normalized version (real and to unity) of the bispectrum.

Parameters:

imgnumpy.ndarray or astropy.io.fits.PrimaryHDU or astropy.io.fits.ImageHDU or spectral_cube.Projection or spectral_cube.Slice: 2D image.

Examples

>>> from turbustat.statistics import Bispectrum
>>> from astropy.io import fits
>>> moment0 = fits.open("Design4_21_0_0_flatrho_0021_13co.moment0.fits") 
>>> bispec = Bispectrum(moment0) 
>>> bispec.run(verbose=True, nsamples=1000) 

Attributes Summary

`bicoherence`	Bicoherence array.
`bispectrum`	Bispectrum array.
`bispectrum_logamp`	log amplitudes of the bispectrum.
`data`
`distance`
`header`
`need_header_flag`
`no_data_flag`
`tracker`	Array showing the number of samples in each k_1 k_2 bin.

Methods Summary

`azimuthal_slice`(radii, delta_radii[, ...])	Create an azimuthal slice of the bispectrum or bicoherence surfaces.
`compute_bispectrum`([show_progress, ...])	Do the computation.
`input_data_header`(data, header[, need_copy])	Check if the header is given separately from the data type.
`load_beam`([beam])	Try loading the beam from the header or a given object.
`load_results`(pickle_file)	Load in a saved pickle file.
`plot_surface`([save_name, show_bicoh, cmap, ...])	Plot the bispectrum amplitude and (optionally) the bicoherence.
`radial_slice`(thetas, delta_thetas[, ...])	Create a radial slice of the bispectrum (or bicoherence) plane.
`run`([show_progress, use_pyfftw, threads, ...])	Compute the bispectrum.
`save_results`(output_name[, keep_data])	Save the results of the SCF to avoid re-computing.

Attributes Documentation

bicoherence¶: Bicoherence array.

bispectrum¶: Bispectrum array.

bispectrum_logamp¶: log amplitudes of the bispectrum.

data¶

distance¶

header¶

need_header_flag = True¶

no_data_flag = False¶

tracker¶: Array showing the number of samples in each k_1 k_2 bin.

Methods Documentation

azimuthal_slice(radii, delta_radii, bin_width=<Quantity 5. deg>, value='bispectrum', return_masks=False)[source]¶

Create an azimuthal slice of the bispectrum or bicoherence surfaces.

Parameters:

radiifloat or np.ndarray: Radii in the bispectrum plane to extract slices at. Multiple slices are returned if radii is an array.
delta_radiifloat or np.ndarray: The width around the radii in the bispectrum plane. If multiple radii are given, delta_radii must match the length of radii.
bin_widthQuantity, optional: The angular size of the bins used to create the slice.
valuestr, optional: Which surface to create a profile from. Can be “bispectrum” (default), “bispectrum_logamp”, or “bicoherence”.
return_masksbool, optional: Return the radial masks used to create the slices.

Returns:

azimuthal_slicesdict: Dictionary with the azimuthal slices. Each radius given in radii is a key in the dictionary. Each slice is a numpy array containing the bin centers, the averaged values, and the standard deviations in the azimuthal bins.

compute_bispectrum(show_progress=True, use_pyfftw=False, threads=1, nsamples=100, seed=1000, mean_subtract=False, **pyfftw_kwargs)[source]¶

Do the computation.

Parameters:

show_progressoptional, bool: Show progress bar while sampling the bispectrum.
use_pyfftwbool, optional: Enable to use pyfftw, if it is installed.
threadsint, optional: Number of threads to use in FFT when using pyfftw.
nsamplesint, optional: Sets the number of samples to take at each vector magnitude.
seedint, optional: Sets the seed for the distribution draws.
mean_subtractbool, optional: Subtract the mean from the data before computing. This removes the “zero frequency” (i.e., constant) portion of the power, resulting in a loss of phase coherence along the k_1=k_2 line.
pyfft_kwargsPassed to: rfft_to_fft. See here for a list of accepted kwargs.

input_data_header(data, header, need_copy=False)¶: Check if the header is given separately from the data type.

load_beam(beam=None)¶

Try loading the beam from the header or a given object.

Parameters:

beamBeam, optional: The beam.

static load_results(pickle_file)¶

Load in a saved pickle file.

Parameters:

pickle_filestr: Name of filename to load in.

Returns:

selfSave statistic class: Statistic instance with saved results.

Examples

Load saved results. >>> stat = Statistic.load_results(“stat_saved.pkl”) # doctest: +SKIP

plot_surface(save_name=None, show_bicoh=True, cmap='viridis', contour_color='k')[source]¶

Plot the bispectrum amplitude and (optionally) the bicoherence.

Parameters:

save_namestr, optional: Save name for the figure. Enables saving the plot.
show_bicohbool, optional: Plot the bicoherence surface. Enabled by default.
cmap{str, matplotlib color map}, optional: Colormap to use in the plots. Default is viridis.
contour_color{str, RGB tuple}, optional: Color of the amplitude contours.

radial_slice(thetas, delta_thetas, bin_width=1.0, value='bispectrum', return_masks=False)[source]¶

Create a radial slice of the bispectrum (or bicoherence) plane.

Parameters:

thetasQuantity: Azimuthal angles in the bispectrum plane to extract slices at. Multiple slices are returned if thetas is an array.
delta_thetasQuantity: The width around the angle in the bispectrum plane. If multiple angles are given, delta_thetas must match the length of thetas.
bin_widthfloat, optional: The radial size of the bins used to create the slice.
valuestr, optional: Which surface to create a profile from. Can be “bispectrum” (default), “bispectrum_logamp”, or “bicoherence”.
return_masksbool, optional: Return the radial masks used to create the slices.

Returns:

radial_slicesdict: Dictionary with the radial slices. Each angle given in thetas is a key in the dictionary. Each slice is a numpy array containing the bin centers, the averaged values, and the standard deviations in the radial bins.

run(show_progress=True, use_pyfftw=False, threads=1, nsamples=100, seed=1000, mean_subtract=False, verbose=False, save_name=None, **pyfftw_kwargs)[source]¶

Compute the bispectrum. Necessary to maintain package standards.

Parameters:

show_progressoptional, bool: Show progress bar while sampling the bispectrum.
use_pyfftwbool, optional: Enable to use pyfftw, if it is installed.
threadsint, optional: Number of threads to use in FFT when using pyfftw.
nsamplesint, optional: See compute_bispectrum.
seedint, optional: See compute_bispectrum.
mean_subtractbool, optional: See compute_bispectrum.
verbosebool, optional: Enables plotting.
save_namestr,optional: Save the figure when a file name is given.
pyfftw_kwargsPassed to: rfft_to_fft. See here for a list of accepted kwargs.

save_results(output_name, keep_data=False)¶

Save the results of the SCF to avoid re-computing. The pickled file will not include the data cube by default.

Parameters:

output_namestr: Name of the outputted pickle file.
keep_databool, optional: Save the data cube in the pickle file when enabled.