Region#

class mufasa.master_fitter.Region(cubePath, paraNameRoot, paraDir=None, cnv_factor=2, fittype=None, initialize_logging=True, multicore=True, **kwargs)[source]#

Bases: object

A class to represent the observed spectral cube to perform the model fits.

Examples

Create a Region object and print its attributes:

>>> region = Region("/path/to/cube.fits", "example_name", fittype="nh3_multi_v")
>>> print(region.cubePath)
get_convolved_cube(update=True, cnv_cubePath=None, edgetrim_width=5, paraNameRoot=None, paraDir=None, multicore=True)[source]#

Generate a convolved version of the spectral cube and update the Region object.

Parameters:

  • update (bool, optional) – If True, updates the convolved cube even if it already exists. Defaults to True.

  • cnv_cubePath (str, optional) – File path to save the convolved cube. If None, a default path is generated. Defaults to None.

  • edgetrim_width (int, optional) – Width of the edge to trim from the cube during convolution. Defaults to 5.

  • paraNameRoot (str, optional) – Root name for output parameter files. If None, uses the Region’s paraNameRoot. Defaults to None.

  • paraDir (str, optional) – Directory to store output files. Defaults to the Region’s paraDir.

  • multicore (bool or int, optional) – Number of CPU cores to use for parallel processing. Defaults to True, which uses all available CPUs minus 1.

Return type:

None

get_convolved_fits(ncomp, **kwargs)[source]#

Perform fitting on the convolved spectral cube and save the results.

Parameters:

  • ncomp (int) – Number of components to fit in the spectral model.

  • **kwargs (dict, optional) –

    Additional keyword arguments passed to UCubePlus.fit_cube, including:
    updatebool, optional

    If True, updates the fit results even if they already exist. Defaults to True.

    multicorebool or int, optional

    Number of CPU cores to use for parallel processing. Defaults to True.

Return type:

None

get_fits(ncomp, **kwargs)[source]#

Perform fitting on the original spectral cube and save the results.

Parameters:

  • ncomp (int) – Number of components to fit in the spectral model.

  • **kwargs (dict, optional) –

    Additional keyword arguments passed to UCubePlus.fit_cube, including:
    updatebool, optional

    If True, updates the fit results even if they already exist. Defaults to True.

    guessesndarray, optional

    Initial guesses for the model parameters.

Return type:

None

load_fits(ncomp)[source]#

Load previously saved fitting results for a given number of components.

Note: this function is basically the same as get_fits(), but with update set to False to ensure the fits aren’t refitted

Parameters:

ncomp (int) – Number of components in the spectral model whose fits should be loaded.

Return type:

None

log_progress(process_name, mark_start=False, save=True, timespec='seconds', n_attempted=None, n_success=None, finished=False, cores=None)[source]#

Log the progress of a process, including start/completion times, and attempt/success counts.

Parameters:

  • process_name (str) – Name of the process being logged.

  • mark_start (bool, optional) – If True, marks the start of the process. Defaults to False.

  • save (bool, optional) – If True, saves the log to a CSV file. Defaults to True.

  • timespec (str, optional) – Specifies the level of detail for the timestamp. Defaults to ‘seconds’.

  • n_attempted (int, optional) – Number of attempted fits. Defaults to None.

  • n_success (int, optional) – Number of successful fits. Defaults to None.

  • finished (bool, optional) – If True, marks the process as completed and calculates total runtime. Defaults to False.

  • cores (int, optional) – Number of cores used for the process. Defaults to None.

Return type:

None

Notes

  • When mark_start is True, the start time is logged, and progress is marked as “in progress”.

  • When finished is True, calculates runtime from the start time and marks the process as complete.

  • Progress is saved to the CSV file specified by self.progress_log_name.

master_2comp_fit(snr_min=0.0, **kwargs)[source]#

Perform a comprehensive two-component fitting process on the spectral cube.

This method fits the data in multiple stages, including: 1. Initial fit with convolved cube. 2. Refining bad or marginal fits. 3. Recovering wide separation components. 4. Expanding fits to surrounding pixels.

Parameters:

  • snr_min (float, optional) – Minimum signal-to-noise ratio required for fitting. Default is 0.0.

  • **kwargs (dict, optional) –

    Additional keyword arguments controlling the fitting process:

    • recover_wide : bool, optional If True, attempts to recover wide separation components. Defaults to True.

    • planemask : ndarray, optional 2D mask specifying which pixels to fit. Defaults to None.

    • updateCnvFits : bool, optional If True, updates convolved fits even if they already exist. Defaults to True.

    • refit_bad_pix : bool, optional If True, refits pixels with poor quality fits. Defaults to True.

Returns:

Updated Region object with refined fitting results.

Return type:

Region

Notes

  • This method uses multiple passes to refine the fitting results.

  • The expanded fits use local guesses from neighboring pixels.

Examples

>>> region = Region("/path/to/cube.fits", "example_name", fittype="nh3_multi_v")
>>> region.master_2comp_fit(snr_min=5.0, recover_wide=False)
plot_ppv_scatter(ncomp=2, label_key='peakT', savename=None, vel_scale=0.8, vrange=None, verr_thres=5, **kwargs)[source]#

Generate a 3D scatter plot of the position-position-velocity (PPV) data from the best-fit model.

Parameters:

  • ncomp (int, optional) – Number of components in the model to be plotted. Defaults to 2.

  • label_key (str, optional) – Column in the DataFrame used to color points, e.g., ‘peakT’ for peak intensity. Defaults to ‘peakT’.

  • savename (str, optional) – Path to save the 3D plot as an HTML file. If None, the plot is not saved. Defaults to None.

  • vel_scale (float, optional) – Scale factor for the velocity axis relative to spatial axes. Defaults to 0.8.

  • vrange (tuple of float, optional) – Velocity range (in km/s) for clipping the data. Defaults to None.

  • verr_thres (float, optional) – Velocity error threshold (in km/s) to filter the data. Points with errors above this threshold are excluded. Defaults to 5.

  • **kwargs (dict, optional) – Additional options passed to plot_ppv for plot customization.

Returns:

Generated 3D scatter plot.

Return type:

plotly.graph_objs.Figure

Notes

  • Initializes a ScatterPPV instance using the fitted parameters and calls plot_ppv.

  • Allows customization of plot appearance through additional arguments.

read_best_fits(ncomp=2, header=True)[source]#

Read the best-fit parameters for up to ncomp components from the saved FITS file.

Parameters:

  • ncomp (int, optional) – Maximum number of components in the model to read. Defaults to 2.

  • header (bool, optional) – If True, includes the FITS header in the returned data. Defaults to True.

Returns:

  • data (numpy.ndarray) – Data array containing the fitted parameters.

  • hdr (astropy.io.fits.Header, optional) – FITS file header, included if header is True.

Notes

  • Constructs the file path based on the specified number of components (ncomp) and reads the corresponding FITS file.

  • The data represents the fitted model parameters for the specified component count.

standard_2comp_fit(planemask=None)[source]#

Perform a two-component fit on the spectral cube using default moment-based guesses.

Parameters:

planemask (ndarray, optional) – 2D mask specifying which spatial pixels to fit. Defaults to None.

Return type:

None