Histogram Fitting#

Use massphoto.distfit.fit() for raw samples or precomputed histograms. It returns massphoto.distfit.FitResult. Select the fitting engine with method="hybrid" (default) or method="full".

Convenience wrapper to call either hybrid or full fitting method.

If initial_peaks is not provided, automatically detects peaks and sets bounds.

Accepts various input formats:

data=samples: unbinned data with auto-binning
data=samples, bins=N: unbinned data with N bins
data=samples, bins=edges: unbinned data with custom edges
data=samples, binwidth=w: unbinned data with bin width w
data=(counts, edges): pre-computed histogram

Parameters:

data (unbinned samples OR tuple (counts, bin_edges))
bins (number of bins or bin edges array)
initial_peaks (list of peak positions (mu values) or None for auto-detection)
initial_sigma (single sigma for all peaks, or list of sigmas (None for auto-estimation))
initial_amps (single amplitude for all peaks, or list of amplitudes (None for auto-estimation))
binwidth (bin width for automatic binning)
method ('hybrid' or 'full')
min_prominence (minimum peak prominence for auto-detection (None for auto-estimation))
max_peaks (maximum number of peaks to detect (None for unlimited))
include_background (whether to fit constant background)
**kwargs (passed to the selected fitting engine. The hybrid method accepts) – bounds_mu, bounds_sigma, and verbose; the full method accepts weights, bounds, jacobian, and verbose.

Return type:

FitResult

Notes

If initial_peaks is not provided, peaks will be automatically detected using find_peak_guesses. Use min_prominence and max_peaks to control detection sensitivity.
If initial_sigma is not provided, it will be estimated from the data using estimate_bandwidth_from_fwhm based on the highest peak’s FWHM. You can also provide a single sigma for all peaks or individual sigmas.
In most cases, the ‘hybrid’ method is recommended for better stability with overlapping peaks, while ‘full’ fits amplitudes as free parameters and allows to constrain them with bounds if needed.

Examples

>>> # Automatic peak detection with custom binning
>>> result = fit(masses, binwidth=2.5, include_background=True)

>>> # Manual peak specification with automatic sigma/amplitude
>>> result = fit(masses, initial_peaks=[100, 200, 300], bins=50)

>>> # Manual peak specification with shared sigma
>>> result = fit(masses, initial_peaks=[100, 200], initial_sigma=10.0)

>>> # Full manual specification
>>> result = fit(masses, initial_peaks=[100, 200],
...                        initial_sigma=[8.0, 12.0], initial_amps=[500, 300])

Typical output#

FitResult(
    peaks=DataFrame with columns:
        ['A', 'mu', 'sigma', 'A_err', 'mu_err', 'sigma_err'],
    background=...,            # Fitted background value
    background_err=...,        # Uncertainty of background
    counts=array([...]),       # Histogram bin counts
    bin_edges=array([...]),    # Histogram bin edges
    model_counts=array([...]), # Model-predicted counts per bin
    residuals=array([...]),    # Difference: counts - model_counts
    cov=array([...]),          # Covariance matrix (if available)
    metrics={...},             # Goodness-of-fit metrics
    warnings=[...],            # List of warnings (if any)
    # Convenience attributes for plotting
    bin_centers=array([...]),  # Bin centers for plotting
    bin_widths=...,            # Bin width for plotting
    model_x=array([...]),      # High-resolution x values for model plotting
    model_y=array([...]),      # Model values at high-resolution x for plotting
)

class massphoto.distfit.FitResult(peaks, background, background_err, counts, bin_edges, model_counts, residuals, cov, metrics, warnings, bin_centers=None, bin_widths=None, model_x=None, model_y=None)[source]#

Bases: object

Complete fitting result.

This dataclass stores all fit outputs (peaks, background, model, residuals, covariance, and summary metrics) as attributes.

Parameters:

peaks (DataFrame)
background (float)
background_err (float | None)
counts (ndarray)
bin_edges (ndarray)
model_counts (ndarray)
residuals (ndarray)
cov (ndarray | None)
metrics (dict[str, float])
warnings (list[str])
bin_centers (ndarray | None)
bin_widths (float | None)
model_x (ndarray | None)
model_y (ndarray | None)

peaks: DataFrame#: Per-peak fit parameters with columns A, mu, sigma, and *_err.

background: float#: Constant background level (0.0 if not fitted).

background_err: float | None#: Uncertainty of background if estimated.

counts: ndarray#: Observed histogram bin counts used for fitting.

bin_edges: ndarray#: Histogram bin edges corresponding to counts.

model_counts: ndarray#: Model-predicted counts per bin.

residuals: ndarray#: counts - model_counts for each bin.

cov: ndarray | None#: Covariance matrix for parameters when available.

metrics: dict[str, float]#: Goodness-of-fit metrics (rss, chi2, red_chi2, aic, bic).

warnings: list[str]#: Warnings emitted during fitting/covariance estimation.

bin_centers: ndarray | None = None#: Bin centers corresponding to counts/model_counts.

bin_widths: float | None = None#: Bin widths corresponding to counts/model_counts.

model_x: ndarray | None = None#: Fitted model evaluated at high-resolution x values when available.

model_y: ndarray | None = None#: Fitted model y values at high-resolution x when available.