kinextract.FitState

class kinextract.FitState(x: ndarray, g: ndarray, gerr: ndarray, t: ndarray, outside_tpl: ndarray, c1: float, resd: float, xlam: float, xl: ndarray, sigl0: float, npix: int, nl: int, iskip: int, nt: int, icoff: int, nlosvd: int, scale: float, coffi: float = 0.0, coff2i: float = 0.0, prenormalized: bool = False, norm_extra: dict = <factory>, fortran_template_mixture: bool = True, fit_global_amp: bool = False, vgrid0: ndarray | None = None, facnew0: ndarray | None = None, losvd_j0: ndarray | None = None, losvd_j1: ndarray | None = None, losvd_w: ndarray | None = None, ip_map: ndarray | None = None, ip_mask: ndarray | None = None, t_err: ndarray | None = None, f_template: float = 0.0, emission_pre_mask: ndarray | None = None, continuum_mult: ndarray | None = None, fit_continuum: bool = False, continuum_poly_mode: str = 'none', continuum_poly_x: ndarray | None = None, continuum_poly_bound: float = 0.1, v_center: float = 0.0, ntot: int = 0, xlam_wing_shrink: float = 0.0, xlam_wing_shrink_sfac: float = 1.8)[source]

Mutable container holding the full numerical state of one spectral fit.

A single FitState instance is built once per spatial bin (spaxel or aperture) being fit and is threaded through every stage of the pipeline: the chi-squared objective function, the roughness-penalty regularization, the continuum co-fit (see kinextract.joint), and the final output writers. It bundles the observed spectrum, the stellar/SSP template matrix, the non-parametric LOSVD velocity grid, and precomputed index maps that make the template-LOSVD convolution fast to evaluate repeatedly inside the optimizer.

The LOSVD itself is represented non-parametrically: as a histogram of nl amplitudes on the velocity grid xl (km/s), recovered by chi-squared minimization with a roughness penalty controlled by xlam, rather than fit as a Gauss-Hermite parametric form.

Parameters and Attributes are documented together below since this is a plain dataclass (all constructor parameters become attributes).

x

Galaxy wavelength grid, in Angstroms (rest frame after any redshift correction), for the pixels included in the fit.

Type:: ndarray, shape (npix,)

g

Observed galaxy flux at each pixel of x.

Type:: ndarray, shape (npix,)

gerr

Per-pixel flux uncertainty. Pixels to be excluded from the fit (bad regions, emission lines, template-coverage gaps) are marked by setting the corresponding entry to the sentinel BIG (see kinextract._utils) rather than removed, so array shapes stay aligned across the pipeline.

Type:: ndarray, shape (npix,)

t

Stellar/SSP template matrix on the galaxy grid, one column per template, each normalized to a flux level of order 1 (see kinextract.templates.build_template_matrix_fortran()).

Type:: ndarray, shape (npix, nt)

outside_tpl

True where a given template in t does not cover a given pixel’s wavelength – per-template, not per-pixel, so a pixel covered by some but not all templates only excludes the templates that actually lack coverage there rather than the whole pixel. Replaces the fragile t == 1.0 sentinel used in the original Fortran-derived logic, which could misidentify genuine in-range pixels whose value happened to equal 1.0 exactly.

Type:: ndarray of bool, shape (npix, nt)

xlam

Roughness-penalty regularization strength applied to the recovered LOSVD. Larger values force a smoother (lower curvature) LOSVD at the cost of chi-squared fit quality.

Type:: float

xl

LOSVD velocity-bin centers, in km/s. Defines the non-parametric histogram grid on which the LOSVD amplitudes b are recovered.

Type:: ndarray, shape (nl,)

sigl0

Fiducial/reference velocity dispersion (km/s) used to scale the roughness penalty and to set the default extent of xl when an explicit velocity range is not supplied.

Type:: float

npix

Number of wavelength pixels in the fit region (length of x, g, gerr, and the first axis of t).

Type:: int

nl

Number of LOSVD velocity bins (length of xl); the LOSVD is represented as an nl-bin histogram, not a parametric form.

Type:: int

nt

Number of stellar/SSP templates (columns of t).

Type:: int

iskip

Number of pixels to skip at each end of the spectrum when computing chi-squared/writing outputs (edge pixels affected by convolution boundary effects).

Type:: int

icoff

Continuum-offset handling mode used by the objective function: which of coffi/coff2i are held fixed vs. fit as free parameters (see kinextract.numerics for the exact mapping).

Type:: int

nlosvd

Number of points on the fine internal velocity grid (vgrid0) used to evaluate the LOSVD during convolution; typically much finer than nl for numerical accuracy, and computed from the pixel scale and a reference wavelength so the convolution kernel is well resolved.

Type:: int

scale

Wavelength step of the galaxy grid x, in Angstroms per pixel.

Type:: float

c1

Fortran-convention pixel-index offset (1 - x[0] / scale) used together with facnew0 to compute integer pixel shifts for the LOSVD convolution via nint_fortran, preserving exact correspondence with the legacy Fortran pixel-indexing scheme.

Type:: float

resd

Cube of the wavelength pixel scale (scale ** 3); enters the roughness-penalty normalization inherited from the original Fortran formulation.

Type:: float

coffi, coff2i

Initial/fixed continuum-offset and continuum-slope parameters, interpreted according to icoff.

Type:: float

prenormalized

True if the input spectrum was already continuum-normalized on disk (a .norm file), in which case the continuum co-fit is skipped.

Type:: bool

fortran_template_mixture

True to reproduce the original Fortran convention for how template weights are combined into the model spectrum.

Type:: bool

fit_global_amp

True to fit a single overall flux-normalization amplitude shared across all templates, in addition to per-template weights.

Type:: bool

vgrid0

Fine internal velocity grid used for LOSVD evaluation during convolution (see nlosvd).

Type:: ndarray or None, shape (nlosvd,)

facnew0

Per-point conversion factor from velocity (on vgrid0) to fractional pixel shift, used to build ip_map.

Type:: ndarray or None, shape (nlosvd,)

losvd_j0, losvd_j1

Lower/upper bin indices into xl bracketing each point of vgrid0, precomputed by precompute_losvd_interp for fast linear interpolation of the LOSVD histogram onto the fine grid.

Type:: ndarray or None, shape (nlosvd,)

losvd_w

Linear interpolation weight (0-1) for losvd_j1 at each point of vgrid0 (weight for losvd_j0 is 1 - losvd_w).

Type:: ndarray or None, shape (nlosvd,)

ip_map

Precomputed pixel-shift index map for the template-LOSVD convolution: ip_map[i, j] is the (zero-based, Fortran-NINT rounded) pixel index that velocity point j maps flux from onto output pixel i. Built once per fit by precompute_ip_map since it depends only on the (fixed) wavelength grid and velocity grid, not on the trial LOSVD amplitudes.

Type:: ndarray or None, shape (npix, nlosvd)

ip_mask

Boolean mask marking which entries of ip_map fall inside the valid pixel range [0, npix); out-of-range contributions are excluded from the convolution sum.

Type:: ndarray or None, shape (npix, nlosvd)

t_err

Per-pixel template flux uncertainty matrix, normalized like t.

Type:: ndarray or None, shape (npix, nt)

f_template

Pooled median fractional template flux error across all templates and pixels, used as a floor/inflation term for effective flux errors in the fit.

Type:: float

continuum_mult

Multiplicative continuum model (from the joint P-spline continuum co-fit, see kinextract.joint) applied to the template-only model spectrum to reproduce the observed continuum shape. Left at all-ones when fit_continuum is False (pre-normalized mode).

Type:: ndarray or None, shape (npix,)

fit_continuum

True to co-fit a continuum baseline (via kinextract.joint) alongside the LOSVD and template weights, rather than relying on a pre-normalized input spectrum.

Type:: bool

v_center

Velocity (km/s) to recenter the LOSVD wing-taper smoothness penalty on (see kinextract.numerics._compute_smoothness()). Always 0.0 for the default MAP pipeline, matching the original Fortran convention (the fixed grid’s zero point, not a data-driven estimate, which is more robust when the estimate itself is imprecise). Only the optional Bayesian path (kinextract.bayesian.fit_state_bayesian()) sets this to a nonzero, data-driven value.

Type:: float

ntot

Running count of objective-function evaluations for the current optimization, used for progress logging.

Type:: int

__init__(x: ndarray, g: ndarray, gerr: ndarray, t: ndarray, outside_tpl: ndarray, c1: float, resd: float, xlam: float, xl: ndarray, sigl0: float, npix: int, nl: int, iskip: int, nt: int, icoff: int, nlosvd: int, scale: float, coffi: float = 0.0, coff2i: float = 0.0, prenormalized: bool = False, norm_extra: dict = <factory>, fortran_template_mixture: bool = True, fit_global_amp: bool = False, vgrid0: ndarray | None = None, facnew0: ndarray | None = None, losvd_j0: ndarray | None = None, losvd_j1: ndarray | None = None, losvd_w: ndarray | None = None, ip_map: ndarray | None = None, ip_mask: ndarray | None = None, t_err: ndarray | None = None, f_template: float = 0.0, emission_pre_mask: ndarray | None = None, continuum_mult: ndarray | None = None, fit_continuum: bool = False, continuum_poly_mode: str = 'none', continuum_poly_x: ndarray | None = None, continuum_poly_bound: float = 0.1, v_center: float = 0.0, ntot: int = 0, xlam_wing_shrink: float = 0.0, xlam_wing_shrink_sfac: float = 1.8) → None

Methods

__init__(x, g, gerr, t, outside_tpl, c1, ...)

Attributes

`coff2i`
`coffi`
`continuum_mult`
`continuum_poly_bound`
`continuum_poly_mode`
`continuum_poly_x`
`emission_pre_mask`
`f_template`
`facnew0`
`fit_continuum`
`fit_global_amp`
`fortran_template_mixture`
`ip_map`
`ip_mask`
`losvd_j0`
`losvd_j1`
`losvd_w`
`ntot`
`prenormalized`
`t_err`
`v_center`
`vgrid0`
`xlam_wing_shrink`
`xlam_wing_shrink_sfac`
`x`
`g`
`gerr`
`t`
`outside_tpl`
`c1`
`resd`
`xlam`
`xl`
`sigl0`
`npix`
`nl`
`iskip`
`nt`
`icoff`
`nlosvd`
`scale`
`norm_extra`