PCA¶

class turbustat.statistics.PCA(cube, n_eigs=None, distance=None)[source] [edit on github]¶

Bases: turbustat.statistics.base_statistic.BaseStatisticMixIn

Implementation of Principal Component Analysis (Heyer & Brunt, 2002)

Parameters:	cube : numpy.ndarray or astropy.io.fits.PrimaryHDU or SpectralCube Data cube. n_eigs : int Deprecated. Input using compute_pca or run. distance : Quantity, optional Distance to object in physical units. The output spatial widths will be converted to the units given here.

Examples

>>> from turbustat.statistics import PCA
>>> from spectral_cube import SpectralCube
>>> import astropy.units as u
>>> cube = SpectralCube.read("adv.fits") 
>>> pca = PCA(cube, distance=250 * u.pc) 
>>> pca.run(verbose=True) 

Attributes Summary

eigvals	All eigenvalues.
eigvecs	All eigenvectors.
gamma	Slope of the size-linewidth relation with correction from Chris Brunt’s thesis.
gamma_error_range	One-sigma error bounds on gamma.
index	Power-law index.
index_error_range	One-sigma error bounds on the index.
intercept	Intercept from the fits, converted out of the log value.
intercept_error_range	One-sigma error bounds on the intercept.
n_eigs
spatial_width	Spatial widths for the first n_eigs components.
spatial_width_error	The 1-sigma error bounds on the spatial widths for the first n_eigs components.
spectral_width	Spectral widths for the first n_eigs components.
spectral_width_error	The error bounds on the spectral widths for the first n_eigs components.
total_variance	Total variance of all eigenvalues.
var_proportion	Proportion of variance described by the first n_eigs eigenvalues.

Methods Summary

autocorr_images([n_eigs])	Create the autocorrelation of the eigenimages.
autocorr_spec([n_eigs])	Create the autocorrelation spectra of the eigenvectors.
compute_pca([mean_sub, n_eigs, min_eigval, ...])	Create the covariance matrix and its eigenvalues.
eigimages([n_eigs])	Create eigenimages up to the n_eigs.
find_spatial_widths([method, ...])	Derive the spatial widths using the autocorrelation of the eigenimages.
find_spectral_widths([method, physical_units])	Derive the spectral widths using the autocorrelation of the eigenvectors.
fit_plaw([fit_method, verbose])	Fit the size-linewidth relation.
model(x)	Model with the fit parameters from fit_plaw
noise_ACF([n_eigs])	Create the noise autocorrelation function based off of the eigenvalues beyond PCA.n_eigs.
run([verbose, save_name, mean_sub, ...])	Run the decomposition and fitting in one step.
sonic_length([T_k, mu, use_gamma])	Estimate of the sonic length based on a given temperature.

Attributes Documentation

eigvals¶

All eigenvalues.

eigvecs¶

All eigenvectors.

gamma¶

Slope of the size-linewidth relation with correction from Chris Brunt’s thesis.

gamma_error_range¶

One-sigma error bounds on gamma.

index¶

Power-law index.

index_error_range¶

One-sigma error bounds on the index.

intercept¶

Intercept from the fits, converted out of the log value.

intercept_error_range¶

One-sigma error bounds on the intercept.

n_eigs¶

spatial_width¶

Spatial widths for the first n_eigs components.

spatial_width_error¶

The 1-sigma error bounds on the spatial widths for the first n_eigs components.

spectral_width¶

Spectral widths for the first n_eigs components.

spectral_width_error¶

The error bounds on the spectral widths for the first n_eigs components.

total_variance¶

Total variance of all eigenvalues.

var_proportion¶

Proportion of variance described by the first n_eigs eigenvalues.

Methods Documentation

autocorr_images(n_eigs=None)[source] [edit on github]¶

Create the autocorrelation of the eigenimages.

Parameters:	n_eigs : None or int The number of autocorrelation images to create. When n_eigs is negative, the last -n_eig autocorrelation images are created. If None is given, the number in n_eigs will be returned.
Returns:	acors : np.ndarray 3D array, where the first dimension if the number of eigenvalues.

autocorr_spec(n_eigs=None)[source] [edit on github]¶

Create the autocorrelation spectra of the eigenvectors.

Parameters:	n_eigs : None or int The number of autocorrelation vectors to create. When n_eigs is negative, the last -n_eig autocorrelation vectors are created. If None is given, the number in n_eigs will be returned.
Returns:	acors : np.ndarray 2D array, where the first dimension if the number of eigenvalues.

compute_pca(mean_sub=False, n_eigs='auto', min_eigval=None, eigen_cut_method='value')[source] [edit on github]¶

Create the covariance matrix and its eigenvalues.

If mean_sub is disabled, the first eigenvalue is dominated by the mean of the data, not the variance.

Parameters:

mean_sub : bool, optional When enabled, subtracts the means of the channels before calculating the covariance. By default, this is disabled to match the Heyer & Brunt method. n_eigs : {int, ‘auto’}, optional Number of eigenvalues to compute. The default setting is ‘auto’, which requires min_eigval to be set. Otherwise, the number of eigenvalues used can be set using an int. Setting to -1 will use all of the eigenvalues. min_eigval : float, optional The cut-off value to determine the number of important eigenvalues. When eigen_cut_method is proportional, min_eigval is the total proportion of variance described up to the Nth eigenvalue. When eigen_cut_method is value, min_eigval is the minimum variance described by that eigenvalue. eigen_cut_method : {‘proportion’, ‘value’}, optional Set whether min_eigval is the proportion of variance determined up to the Nth eigenvalue (proportion) or the minimum value of variance (value).

eigimages(n_eigs=None)[source] [edit on github]¶

Create eigenimages up to the n_eigs.

Parameters:	n_eigs : None or int The number of eigenimages to create. When n_eigs is negative, the last -n_eig eigenimages are created. If None is given, the number in n_eigs will be returned.
Returns:	eigimgs : ndarray 3D array, where the first dimension if the number of eigenvalues.

find_spatial_widths(method='contour', brunt_beamcorrect=True, beam_fwhm=None, physical_scales=True, distance=None)[source] [edit on github]¶

Derive the spatial widths using the autocorrelation of the eigenimages.

Parameters:

methods : {‘contour’, ‘fit’, ‘interpolate’, ‘xinterpolate’}, optional Spatial fitting method to use. The default method is ‘contour’ (fits an ellipse to the 1/e contour about the peak; this is the method used by the Heyer & Brunt works). See WidthEstimate2D for a description of all methods. brunt_beamcorrect : bool, optional Apply the beam correction described in Chris Brunt’s thesis. A beam will be searched for in the given header (looking for “BMAJ”). If this fails, the value must be given in beam_fwhm with angular units. beam_fwhm : None of Quantity, optional When beam correction is enabled, the FWHM beam size can be given here. physical_scales : bool, optional Attempts to convert spatial pixel scales into physical sizes. A warning is raised if no distance is provided. distance : Quantity, optional Distance to object in physical units. The output spatial widths will be converted to the units given here.

find_spectral_widths(method='walk-down', physical_units=True)[source] [edit on github]¶

Derive the spectral widths using the autocorrelation of the eigenvectors.

Parameters:	method : {“walk-down”, “fit”, “interpolate”}, optional Spectral fitting method to use. The default method is ‘walk-down’ (starting at the peak, continue until reaching 1/e of the peak; this is the method used by the Heyer & Brunt works). See WidthEstimate1D for a description of all methods. physical_units : bool, optional Enable conversion into spectral units, as defined within the header.

fit_plaw(fit_method='odr', verbose=False, **kwargs)[source] [edit on github]¶

Fit the size-linewidth relation. This is done through Orthogonal Distance Regression (via scipy), or through MCMC (requires installing emcee).

Parameters:	fit_method : {‘odr’, ‘bayes’}, optional Set the type of fitting to perform. Options are ‘odr’ (orthogonal distance regression) or ‘bayes’ (MCMC). Note that ‘bayes’ requires the emcee package to be installed. verbose : bool, optional Prints out additional information about the fitting and plots the solution. **kwargs Passed to bayes_linear when fit_method is bayes.

model(x)[source] [edit on github]¶

Model with the fit parameters from fit_plaw

noise_ACF(n_eigs=-10)[source] [edit on github]¶

Create the noise autocorrelation function based off of the eigenvalues beyond PCA.n_eigs.

run(verbose=False, save_name=None, mean_sub=False, decomp_only=False, n_eigs='auto', min_eigval=None, eigen_cut_method='value', spatial_method='contour', spectral_method='walk-down', fit_method='odr', beam_fwhm=None, brunt_beamcorrect=True)[source] [edit on github]¶

Run the decomposition and fitting in one step.

Parameters:

verbose : bool, optional Enables plotting of the results. save_name : str,optional Save the figure when a file name is given. mean_sub : bool, optional See compute_pca decomp_only : bool, optional Only run the PCA decomposition, not the entire procedure to derive the size-linewidth relation. This should be enabled when using PCA_Distance. n_eigs : {“auto”, int}, optional See compute_pca min_eigval : float, optional See compute_pca eigen_cut_method : {‘proportion’, ‘value’}, optional See compute_pca spatial_method : str, optional See fit_spatial_widths. spectral_method : str, optional See fit_spectral_widths. fit_method : str, optional See fit_plaw. beam_fwhm : None of Quantity, optional See fit_spatial_widths. brunt_beamcorrect : bool, optional See fit_spatial_widths.

sonic_length(T_k=<Quantity 10.0 K>, mu=1.36, use_gamma=True)[source] [edit on github]¶

Estimate of the sonic length based on a given temperature. Uses the intercept from the fit.

Based on sonic.pro used in the Heyer & Brunt PCA implementation.

Because error from the MCMC fit need not be symmetric, the MCMC samples are needed to provide the correct CIs for the sonic length.

Parameters:	T_k : Quantity, optional Temperature given in units convertible to Kelvin. mu : float, optional Factor to multiply by m_H to account for He and metals. use_gamma : bool, optional Toggle whether to use gamma or index.
Returns:	lambd : Quantity Value of the sonic length. If distance was provided, this will be in the units given in the distance. Otherwise, the result will be in pixel units. lambd_error_range : Quantity The 1-sigma bounds on the sonic length. The units will match lambd.