UltraCube

class mufasa.UltraCube.UltraCube(cubefile=None, cube=None, fittype=None, snr_min=None, rmsfile=None, cnv_factor=2, n_cores=True)

Bases: object

A framework for multi-component spectral cube analysis and model fitting.

The UltraCube class manages spectral cubes, supports multi-component model fitting, and provides tools for statistical evaluation, visualization, and residual analysis. It is designed to handle large-scale spectral datasets efficiently.

Parameters:

• cubefile (str, optional) – Path to the FITS cube file. If not provided, a SpectralCube instance must be supplied via the cube parameter.

• cube (SpectralCube, optional) – A SpectralCube instance representing the input spectral data. This parameter is used only if cubefile is not provided.

• fittype (str, optional) – Type of spectral model to fit. Must be compatible with the MetaModel framework.

• snr_min (float, optional) – Minimum signal-to-noise ratio for considering a voxel during fitting.

• rmsfile (str, optional) – Path to the file containing RMS values for the cube.

• cnv_factor (int, optional, default=2) – Factor by which to spatially convolve the cube for pre-processing.

• n_cores (int or bool, optional, default=True) – Number of CPU cores to use for parallel processing. If True, uses all available cores minus one.

Notes

• The UltraCube class is designed to handle cubes with varying spatial and spectral resolutions. It uses the pyspeckit library for fitting and the MetaModel framework for defining custom spectral models.

• Convolution, masking, and statistical evaluation tools are provided for pre- and post-processing of data.

• If a file path is provided via cubefile, the cube is loaded using SpectralCube.read.

• The convolution factor (cnv_factor) is applied to the spatial axes to reduce resolution before processing.

• The number of CPU cores (n_cores) defaults to all but one available core for parallel computations, but can be explicitly set.

convolve_cube(savename=None, factor=None, edgetrim_width=5)

Convolve the SpectralCube to a lower spatial resolution by a specified factor.

Parameters:

• savename (str, optional) – Path to save the convolved cube. If None, the convolved cube is not saved.

• factor (int, optional) – Factor by which to spatially convolve the cube. If None, the default self.cnv_factor is used.

• edgetrim_width (int, optional) – Number of pixels to trim at the edges after convolution. Default is 5.

Return type:

None

Notes

• Convolution reduces the spatial resolution by the specified factor.

• The resulting convolved cube is stored in self.cube_cnv.

• This method uses the convolve_sky_byfactor function to perform spatial convolution.

Raises:

ValueError – If the cube cannot be convolved due to incompatible dimensions or data types.

fit_cube(ncomp, simpfit=False, **kwargs)

Fit the spectral cube with the specified number of components.

Parameters:

• ncomp (int or list of int) – Number of components for the model. If a list is provided, fits are performed for each component.

• simpfit (bool, optional) – Whether to use a simplified fitting method (cubefit_simp) instead of the general fitting method (cubefit_gen).

• **kwargs (dict, optional) – Additional keyword arguments passed to pyspeckit.Cube.fiteach. Includes options like multicore and snr_min.

Return type:

None

Notes

• The multicore parameter in kwargs controls parallel processing. By default, the number of cores set in self.n_cores is used.

• Fit results are stored in self.pcubes for each component.

Raises:

TypeError – If ncomp is not an integer or a list of integers.

get_AICc(ncomp, update=False, planemask=None, expand=20, **kwargs)

get_AICc_likelihood(ncomp1, ncomp2, **kwargs)

get_Tpeak(ncomp)

get_all_lnk_maps(ncomp_max=2, rest_model_mask=True, multicore=True)

get_best_2c_parcube(multicore=True, lnk21_thres=5, lnk20_thres=5, lnk10_thres=5, return_lnks=True)

get_best_residual(cubetype=None)

get_chisq(ncomp, mask=None)

get_cnv_cube(filename=None)

Load the convolved cube if the file exists, or create one if it does not.

Parameters:

filename (str, optional) – Path to the convolved cube file. If None, a new convolved cube is created using the default cnv_factor.

Return type:

None

get_plotter(update=False, spec_unit='km/s', **kwargs)

Initialize or update the Plotter instance for visualizing fitted spectra.

Parameters:

• update (bool, optional) – If True, update the existing plotter instance (default is False).

• spec_unit (str, optional) – The spectral unit to use for plotting the spectral axis (default is ‘km/s’).

• **kwargs (dict, optional) – Additional keyword arguments passed to the Plotter class for initialization.

Return type:

None

get_reduced_chisq(ncomp)

get_residual(ncomp, multicore=None)

Calculate the residual cube by subtracting the fitted model from the data.

Parameters:

• ncomp (int) – Number of components used in the fitted model.

• multicore (int or bool, optional) – Number of cores to use for computation. Defaults to self.n_cores.

Returns:

Residual array representing the difference between the data and the model fit.

Return type:

np.ndarray or dask.array.Array

Notes

• Residual cubes are stored in self.residual_cubes for reuse.

• Residuals are computed for pixels with valid model fits.

Raises:

ValueError – If no model fit is available for the specified number of components.

get_rms(ncomp)

get_rss(ncomp, mask=None, planemask=None, update=True, expand=20)

has_fit(ncomp)

Return a mask indicating which pixels have been fitted with a model.

Parameters:

ncomp (int) – The number of components for the model being checked. This value is used to identify the modelled parameter cube (parcube) associated with the number of components.

Returns:

A 2D boolean array with the same spatial dimensions as the data, where True indicates pixels that have been fitted (i.e., contain non-zero, finite values in the parameter cube for the specified model component) and False indicates pixels that were not fitted.

Return type:

np.ndarray

include_model_mask(mask)

load_cube(fitsfile)

Load a spectral cube from a FITS file and convert its units to K and km/s.

The function ensures the cube has intensity units in Kelvin and a spectral axis in velocity units (km/s). If the cube lacks a rest frequency, it assigns one based on the spectral model.

Parameters:

fitsfile (str) – Path to the FITS cube file.

Return type:

None

load_model_fit(filename, ncomp, calc_model=True, multicore=None)

load_pcube(pcube_ref=None)

Load a cube into a pyspeckit.SpectralCube object from a .fits file.

Parameters:

pcube_ref (pyspeckit.SpectralCube) – A pyspeckit.SpectralCube object that works with the same data cube. If provided, the new pcube’s cube attribute will be pointed towards this reference cube to avoid reduandance and save memory

Returns:

pcube – The pyspeckit.SpectralCube object needed work with the fitting

Return type:

pyspeckit.SpectralCube

make_header2D()

Create a 2D header by removing the specified axis.

Parameters:

• header (astropy.io.fits.Header) – FITS header to modify.

• axis (int) – Axis to remove from the header.

Returns:

Modified 2D header.

Return type:

astropy.io.fits.Header

plot_fit(x, y, ncomp, ax=None, **kwargs)

Plot a model fit for a spectrum at (x, y).

Parameters:

• x (int) – X-coordinate of the pixel.

• y (int) – Y-coordinate of the pixel.

• ncomp (int) – The component number to plot.

• ax (matplotlib.axes.Axes, optional) – Axes object to plot on. If None, a new figure and axes are created.

• **kwargs (dict) – Additional keyword arguments passed to plot_fit.

plot_fits_grid(x, y, ncomp, size=3, xsize=None, ysize=None, xlim=None, ylim=None, figsize=None, origin='lower', mod_all=True, savename=None, **kwargs)

Plot a grid of model fits centered at (x, y).

Parameters:

• x (int) – X-coordinate of the central pixel.

• y (int) – Y-coordinate of the central pixel.

• ncomp (int) – The component number to plot.

• size (int, optional) – Size of the grid (must be odd). Default is 3.

• xsize (int, optional) – Number of columns in the grid. Default is size.

• ysize (int, optional) – Number of rows in the grid. Default is size.

• xlim (tuple, optional) – X-axis limits for the plot, in their native units.

• ylim (tuple, optional) – Y-axis limits for the plot, in their native units.

• figsize (tuple, optional) – Size of the figure.

• origin ({'lower', 'upper'}, optional) – Origin of the grid. Default is ‘lower’.

• mod_all (bool, optional) – Whether to plot all model components. Default is True.

• savename (str, optional) – If provided, save the figure to the given filename.

• **kwargs (dict) – Additional keyword arguments passed to plot_fits_grid.

plot_spec(x, y, ax=None, xlab=None, ylab=None, **kwargs)

Plot a single spectrum at (x, y).

Parameters:

• x (int) – X-coordinate of the pixel.

• y (int) – Y-coordinate of the pixel.

• ax (matplotlib.axes.Axes, optional) – Axes object to plot on. If None, a new figure and axes are created.

• xlab (str, optional) – X-axis label. Default is the LSR velocity label.

• ylab (str, optional) – Y-axis label. Default is the main beam temperature label.

• **kwargs (dict) – Additional keyword arguments passed to plot_spec.

Returns:

• fig (matplotlib.figure.Figure) – The figure object.

• ax (matplotlib.axes.Axes) – The axes object.

plot_spec_grid(x, y, size=3, xsize=None, ysize=None, xlim=None, ylim=None, figsize=None, **kwargs)

Plot a grid of spectra centered at (x, y).

Parameters:

• x (int) – X-coordinate of the central pixel.

• y (int) – Y-coordinate of the central pixel.

• size (int, optional) – Size of the grid (must be odd). Default is 3.

• xsize (int, optional) – Number of columns in the grid. Default is size.

• ysize (int, optional) – Number of rows in the grid. Default is size.

• xlim (tuple, optional) – X-axis limits for the plot, in their native units.

• ylim (tuple, optional) – Y-axis limits for the plot, in their native units.

• figsize (tuple, optional) – Size of the figure.

• **kwargs (dict) – Additional keyword arguments passed to plot_spec_grid.

reset_model_mask(ncomps, multicore=True)

save_fit(savename, ncomp, header_note=None)