ExoIris 0.21.0__tar.gz → 0.23.0__tar.gz

{exoiris-0.21.0 → exoiris-0.23.0}/CHANGELOG.md

@@ -5,6 +5,31 @@ All notable changes to ExoIris will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.23.0] - 2025-12-16
+
+### Changed
+- Switched baseline modeling to a least-squares approach.
+
+### Fixed
+- Corrected prior loading for parameter sets.
+- Validated `samples` before posterior spectrum calculation to prevent runtime errors.
+
+## [0.22.0] - 2025-12-13
+
+### Added
+- Added support for free-k knot configuration in spline models.
+- Added SVD solver options in the `loglikelihood.LogLikelihood` class.
+- Added `bspline-quadratic` interpolation option.
+
+### Improved
+- Improved transmission spectrum and log-likelihood methods for robustness and performance.
+- Cleaned up and refactored the `LogLikelihood` class.
+- Updated limb darkening parameter plotting.
+
+### Fixed
+- Added a safety check for uninitialized `white_gp_models` in white
+  light curve processing.
+
 ## [0.21.0] - 2025-11-24
 
 ### Added

{exoiris-0.21.0 → exoiris-0.23.0}/ExoIris.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ExoIris
-Version: 0.21.0
+Version: 0.23.0
 Summary: Easy and robust exoplanet transmission spectroscopy.
 Author-email: Hannu Parviainen <hannu@iac.es>
 License: GPLv3
@@ -29,6 +29,7 @@ Requires-Dist: xarray
 Requires-Dist: seaborn
 Requires-Dist: astropy
 Requires-Dist: uncertainties
+Requires-Dist: scikit-learn
 Dynamic: license-file
 
 # ExoIris: Fast and Flexible Transmission Spectroscopy in Python

{exoiris-0.21.0 → exoiris-0.23.0}/ExoIris.egg-info/requires.txt

@@ -11,3 +11,4 @@ xarray
 seaborn
 astropy
 uncertainties
+scikit-learn

{exoiris-0.21.0 → exoiris-0.23.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ExoIris
-Version: 0.21.0
+Version: 0.23.0
 Summary: Easy and robust exoplanet transmission spectroscopy.
 Author-email: Hannu Parviainen <hannu@iac.es>
 License: GPLv3
@@ -29,6 +29,7 @@ Requires-Dist: xarray
 Requires-Dist: seaborn
 Requires-Dist: astropy
 Requires-Dist: uncertainties
+Requires-Dist: scikit-learn
 Dynamic: license-file
 
 # ExoIris: Fast and Flexible Transmission Spectroscopy in Python

{exoiris-0.21.0 → exoiris-0.23.0}/exoiris/exoiris.py

@@ -32,7 +32,7 @@ from emcee import EnsembleSampler
 from matplotlib.pyplot import subplots, setp, figure, Figure, Axes
 from numpy import (any, where, sqrt, clip, percentile, median, squeeze, floor, ndarray, isfinite,
                    array, inf, arange, argsort, concatenate, full, nan, r_, nanpercentile, log10,
-                   ceil, unique, zeros)
+                   ceil, unique, zeros, cov)
 from numpy.typing import ArrayLike
 from numpy.random import normal
 from pytransit import UniformPrior, NormalPrior
@@ -133,11 +133,20 @@ def load_model(fname: Path | str, name: str | None = None):
             for i in range(hdr['NSPOTS']):
                 a.add_spot(hdr[f'SP{i+1:02d}_EG'])
 
+        # Read the free k knot indices if they exist.
+        # ==========================================
+        if 'N_FREE_K' in hdr and hdr['N_FREE_K'] > 0:
+            n_free_k = hdr['N_FREE_K']
+            a._tsa.set_free_k_knots([int(hdr[f'KK_IX_{i:03d}']) for i in range(n_free_k)])
+
         # Read the priors.
         # ================
         priors = pickle.loads(codecs.decode(json.loads(hdul['PRIORS'].header['PRIORS']).encode(), "base64"))
-        a._tsa.ps = ParameterSet([pickle.loads(p) for p in priors])
-        a._tsa.ps.freeze()
+        for praw in priors:
+            p = pickle.loads(praw)
+            if p.name in a._tsa.ps.names:
+                a._tsa.set_prior(p.name, p.prior)
+
         if 'DE' in hdul:
             a._tsa._de_population = Table(hdul['DE'].data).to_pandas().values
             a._tsa._de_imin = hdul['DE'].header['IMIN']
@@ -154,7 +163,7 @@ class ExoIris:
 
     def __init__(self, name: str, ldmodel, data: TSDataGroup | TSData, nk: int = 50, nldc: int = 10, nthreads: int = 1,
                  tmpars: dict | None = None, noise_model: Literal["white", "fixed_gp", "free_gp"] = 'white',
-                 interpolation: Literal['bspline', 'pchip', 'makima', 'nearest', 'linear'] = 'makima'):
+                 interpolation: Literal['nearest', 'linear', 'pchip', 'makima', 'bspline', 'bspline-quadratic'] = 'makima'):
         """
         Parameters
         ----------
@@ -211,6 +220,7 @@ class ExoIris:
         self._white_fluxes: None | list[ndarray] = None
         self._white_errors: None | list[ndarray] = None
         self._white_models: None | list[ndarray] = None
+        self.white_gp_models: None | list[ndarray] = None
 
     def lnposterior(self, pvp: ndarray) -> ndarray:
         """Calculate the log posterior probability for a single parameter vector or an array of parameter vectors.
@@ -274,9 +284,6 @@ class ExoIris:
         if parameter == 'radius ratios':
             for l in self._tsa.k_knots:
                 self.set_prior(f'k_{l:08.5f}', prior, *nargs)
-        elif parameter == 'baselines':
-            for par in self.ps[self._tsa._sl_baseline]:
-                self.set_prior(par.name, prior, *nargs)
         elif parameter == 'wn multipliers':
             for par in self.ps[self._tsa._sl_wnm]:
                 self.set_prior(par.name, prior, *nargs)
@@ -653,6 +660,9 @@ class ExoIris:
         the data and the number of columns specified (ncol). If the provided axes array (axs)
         does not accommodate all the subplots, the behavior is undefined.
         """
+        if self.white_gp_models is None:
+            raise ValueError("White light curve GP predictions are not available. Run 'optimize_gp_hyperparameters' first.")
+
         ndata = self.data.size
 
         if axs is None:
@@ -871,13 +881,13 @@ class ExoIris:
 
         if result == 'fit':
             pv = self._tsa._de_population[self._tsa._de_imin]
-            ks = self._tsa._eval_k(pv[self._tsa._sl_rratios])
+            ks = self._tsa._eval_k(pv)
             ar = 1e2 * concatenate([squeeze(k) for k in ks]) ** 2
             ax.plot(wavelength[ix], ar[ix], c='k')
             ax.plot(self._tsa.k_knots, 1e2 * pv[self._tsa._sl_rratios] ** 2, 'k.')
         else:
             df = pd.DataFrame(self._tsa._mc_chains.reshape([-1, self._tsa.ndim]), columns=self._tsa.ps.names)
-            ks = self._tsa._eval_k(df.iloc[:, self._tsa._sl_rratios])
+            ks = self._tsa._eval_k(df.values)
             ar = 1e2 * concatenate(ks, axis=1) ** 2
             ax.fill_between(wavelength[ix], *percentile(ar[:, ix], [16, 84], axis=0), alpha=0.25)
             ax.plot(wavelength[ix], median(ar, 0)[ix], c='k')
@@ -893,7 +903,11 @@ class ExoIris:
             ax.set_xticks(xticks, labels=xticks)
         return ax.get_figure()
 
-    def plot_limb_darkening_parameters(self, result: Optional[str] = None, axs: Optional[tuple[Axes, Axes]] = None) -> None | Figure:
+    def plot_limb_darkening_parameters(
+        self,
+        result: None | Literal["fit", "mcmc"] = None,
+        axs: None | tuple[Axes, Axes] = None,
+    ) -> None | Figure:
         """Plot the limb darkening parameters.
 
         Parameters
@@ -922,56 +936,68 @@ class ExoIris:
         This method plots the limb darkening parameters for two-parameter limb darkening models. It supports only
         quadratic, quadratic-tri, power-2, and power-2-pm models.
         """
-        if not self._tsa.ldmodel in ('quadratic', 'quadratic-tri', 'power-2', 'power-2-pm'):
+        if not self._tsa.ldmodel in (
+            "quadratic",
+            "quadratic-tri",
+            "power-2",
+            "power-2-pm",
+        ):
             return None
 
         if axs is None:
-            fig, axs = subplots(1, 2, sharey='all', figsize=(13,4))
+            fig, axs = subplots(1, 2, sharey="all", figsize=(13, 4))
         else:
             fig = axs[0].get_figure()
 
         if result is None:
-            result = 'mcmc' if self._tsa.sampler is not None else 'fit'
-        if result not in ('fit', 'mcmc'):
+            result = "mcmc" if self._tsa.sampler is not None else "fit"
+        if result not in ("fit", "mcmc"):
             raise ValueError("Result must be either 'fit', 'mcmc', or None")
-        if result == 'mcmc' and self._tsa.sampler is None:
-            raise ValueError("Cannot plot posterior solution before running the MCMC sampler.")
+        if result == "mcmc" and not (
+            self._tsa.sampler is not None or self.mcmc_chains is not None
+        ):
+            raise ValueError(
+                "Cannot plot posterior solution before running the MCMC sampler."
+            )
 
         wavelength = concatenate(self.data.wavelengths)
         ix = argsort(wavelength)
 
-        if result == 'fit':
+        if result == "fit":
             pv = self._tsa._de_population[self._tsa._de_imin]
             ldc = squeeze(concatenate(self._tsa._eval_ldc(pv), axis=1))
-            axs[0].plot(self._tsa.ld_knots, pv[self._tsa._sl_ld][0::2], 'ok')
-            axs[0].plot(wavelength[ix], ldc[:,0][ix])
-            axs[1].plot(self._tsa.ld_knots, pv[self._tsa._sl_ld][1::2], 'ok')
-            axs[1].plot(wavelength[ix], ldc[:,1][ix])
+            axs[0].plot(self._tsa.ld_knots, pv[self._tsa._sl_ld][0::2], "ok")
+            axs[0].plot(wavelength[ix], ldc[:, 0][ix])
+            axs[1].plot(self._tsa.ld_knots, pv[self._tsa._sl_ld][1::2], "ok")
+            axs[1].plot(wavelength[ix], ldc[:, 1][ix])
         else:
-            pvp = self._tsa._mc_chains.reshape([-1, self._tsa.ndim])
-            ldc = pvp[:,self._tsa._sl_ld]
+            if self._tsa.sampler is not None:
+                pvp = self._tsa._mc_chains.reshape([-1, self._tsa.ndim])
+            else:
+                pvp = self.mcmc_chains.reshape([-1, self._tsa.ndim])
+            ldc = pvp[:, self._tsa._sl_ld]
 
-            ld1m = median(ldc[:,::2], 0)
-            ld1e = ldc[:,::2].std(0)
-            ld2m = median(ldc[:,1::2], 0)
-            ld2e = ldc[:,1::2].std(0)
+            ld1m = median(ldc[:, ::2], 0)
+            ld1e = ldc[:, ::2].std(0)
+            ld2m = median(ldc[:, 1::2], 0)
+            ld2e = ldc[:, 1::2].std(0)
 
             ldc = concatenate(self._tsa._eval_ldc(pvp), axis=1)
-            ld1p = percentile(ldc[:,:,0], [50, 16, 84], axis=0)
-            ld2p = percentile(ldc[:,:,1], [50, 16, 84], axis=0)
+            ld1p = percentile(ldc[:, :, 0], [50, 16, 84], axis=0)
+            ld2p = percentile(ldc[:, :, 1], [50, 16, 84], axis=0)
 
             axs[0].fill_between(wavelength[ix], ld1p[1, ix], ld1p[2, ix], alpha=0.5)
-            axs[0].plot(wavelength[ix], ld1p[0][ix], 'k')
+            axs[0].plot(wavelength[ix], ld1p[0][ix], "k")
             axs[1].fill_between(wavelength[ix], ld2p[1, ix], ld2p[2, ix], alpha=0.5)
-            axs[1].plot(wavelength[ix], ld2p[0][ix], 'k')
+            axs[1].plot(wavelength[ix], ld2p[0][ix], "k")
 
-            axs[0].errorbar(self._tsa.ld_knots, ld1m, ld1e, fmt='ok')
-            axs[1].errorbar(self._tsa.ld_knots, ld2m, ld2e, fmt='ok')
+            axs[0].errorbar(self._tsa.ld_knots, ld1m, ld1e, fmt="ok")
+            axs[1].errorbar(self._tsa.ld_knots, ld2m, ld2e, fmt="ok")
 
         ldp = full((self.nldp, 2, 2), nan)
         for i in range(self.nldp):
             for j in range(2):
-                p = self.ps[self._tsa._sl_ld][i*2+j].prior
+                p = self.ps[self._tsa._sl_ld][i * 2 + j].prior
                 if isinstance(p, UniformPrior):
                     ldp[i, j, 0] = p.a
                     ldp[i, j, 1] = p.b
@@ -981,11 +1007,15 @@ class ExoIris:
 
         for i in range(2):
             for j in range(2):
-                axs[i].plot(self._tsa.ld_knots, ldp[:, i, j], ':', c='C0')
-
-        setp(axs, xlim=(wavelength.min(), wavelength.max()), xlabel=r'Wavelength [$\mu$m]')
-        setp(axs[0], ylabel='Limb darkening coefficient 1')
-        setp(axs[1], ylabel='Limb darkening coefficient 2')
+                axs[i].plot(self._tsa.ld_knots, ldp[:, i, j], ":", c="C0")
+
+        setp(
+            axs,
+            xlim=(wavelength.min(), wavelength.max()),
+            xlabel=r"Wavelength [$\mu$m]",
+        )
+        setp(axs[0], ylabel="Limb darkening coefficient 1")
+        setp(axs[1], ylabel="Limb darkening coefficient 2")
         return fig
 
     def plot_residuals(self, result: Optional[str] = None, ax: None | Axes | Sequence[Axes] = None,
@@ -1109,8 +1139,8 @@ class ExoIris:
         return fig
 
     @property
-    def transmission_spectrum(self) -> Table:
-        """Get the posterior transmission spectrum as a Pandas DataFrame.
+    def transmission_spectrum_table(self) -> Table:
+        """Get the posterior transmission spectrum as an Astropy Table.
 
         Raises
         ------
@@ -1122,7 +1152,7 @@ class ExoIris:
 
         pvp = self.posterior_samples
         wls = concatenate(self.data.wavelengths)
-        ks = concatenate(self._tsa._eval_k(pvp.values[:, self._tsa._sl_rratios]), axis=1)
+        ks = concatenate(self._tsa._eval_k(pvp.values), axis=1)
         ar = ks**2
         ix = argsort(wls)
         return Table(data=[wls[ix]*u.micrometer,
@@ -1130,21 +1160,103 @@ class ExoIris:
                            median(ar, 0)[ix], ar.std(0)[ix]],
                      names = ['wavelength', 'radius_ratio', 'radius_ratio_e', 'area_ratio', 'area_ratio_e'])
 
-    def radius_ratio_spectrum(self, wavelengths: ArrayLike, knot_samples: ArrayLike | None = None) -> ndarray:
-        if knot_samples is None:
-            knot_samples = self.posterior_samples.iloc[:, self._tsa._sl_rratios].values
-        k_posteriors = zeros((knot_samples.shape[0], wavelengths.size))
-        for i, ks in enumerate(knot_samples):
-            k_posteriors[i, :] = self._tsa._ip(wavelengths, self._tsa.k_knots, ks)
-        return k_posteriors
-
-    def area_ratio_spectrum(self, wavelengths: ArrayLike, knot_samples: ArrayLike | None = None) -> ndarray:
-        if knot_samples is None:
-            knot_samples = self.posterior_samples.iloc[:, self._tsa._sl_rratios].values
-        d_posteriors = zeros((knot_samples.shape[0], wavelengths.size))
-        for i, ks in enumerate(knot_samples):
-            d_posteriors[i, :] = self._tsa._ip(wavelengths, self._tsa.k_knots, ks) ** 2
-        return d_posteriors
+    def transmission_spectrum_samples(self, wavelengths: ndarray | None = None,
+                                      kind: Literal['radius_ratio', 'depth'] = 'depth',
+                                      samples: ndarray | None = None) -> tuple[ndarray, ndarray]:
+        """Calculate posterior transmission spectrum samples.
+
+        This method computes the posterior samples of the transmission spectrum,
+        either as radius ratios or as transit depths, depending on the specified
+        kind. It interpolates the data for given wavelengths or uses the
+        instrumental wavelength grid if none is provided. Requires that MCMC
+        sampling has been performed prior to calling this method.
+
+        Parameters
+        ----------
+        wavelengths
+            The array of wavelengths at which the spectrum should be sampled.
+            If None, the default wavelength grid defined by the instrumental data
+            will be used.
+        kind
+            Specifies the desired representation of the transmission spectrum.
+            'radius_ratio' returns the spectrum in radius ratio units, while
+            'depth' returns the spectrum in transit depth units. Default is 'depth'.
+        samples
+            Array of posterior samples to use for calculation. If None,
+            the method will use previously stored posterior samples.
+
+        Returns
+        -------
+        ndarray
+            Array containing the transmission spectrum samples for the specified
+            wavelengths. The representation (radius ratio or depth) depends on the
+            specified `kind`.
+        """
+        if self.mcmc_chains is None and samples is None:
+            raise ValueError("Cannot calculate posterior transmission spectrum before running the MCMC sampler.")
+
+        if kind not in ('radius_ratio', 'depth'):
+            raise ValueError("Invalid value for `kind`. Must be either 'radius_ratio' or 'depth'.")
+
+        if samples is None:
+            samples = self.posterior_samples.values
+
+        if wavelengths is None:
+            wavelengths = concatenate(self.data.wavelengths)
+            wavelengths.sort()
+
+        k_posteriors = zeros((samples.shape[0], wavelengths.size))
+        k_knots = self._tsa.k_knots.copy()
+        for i, pv in enumerate(samples):
+            if self._tsa.free_k_knot_ids is not None:
+                k_knots[self._tsa.free_k_knot_ids] = pv[self._tsa._sl_kloc]
+            k_posteriors[i, :] = self._tsa._ip(wavelengths, k_knots, pv[self._tsa._sl_rratios])
+
+        if kind == 'radius_ratio':
+            return wavelengths, k_posteriors
+        else:
+            return wavelengths, k_posteriors**2
+
+    def transmission_spectrum(self, wavelengths: ndarray | None = None, kind: Literal['radius_ratio', 'depth'] = 'depth', samples: ndarray | None = None, return_cov: bool = True) -> tuple[ndarray, ndarray]:
+        """Compute the transmission spectrum.
+
+        This method calculates the mean transmission spectrum values and the covariance matrix
+        (or standard deviations) for the given parameter set. The mean represents the average
+        transmission spectrum, and the covariance provides information on the uncertainties and
+        correlations between wavelengths or samples.
+
+        Parameters
+        ----------
+        wavelengths
+            Array of wavelength values at which to calculate the transmission spectrum.
+            If None, the default grid will be used.
+        kind
+            Specifies the method to represent the spectrum. 'radius_ratio' computes the
+            spectrum in terms of the planet-to-star radius ratio, while 'depth' computes
+            the spectrum in terms of transit depth.
+        samples
+            Array of samples used to compute the spectrum uncertainties. If None, previously
+            stored samples will be utilized.
+
+        return_cov : bool, optional
+            Indicates whether to return the covariance matrix of the computed transmission
+            spectrum. If True, the covariance matrix is returned along with the mean spectrum.
+            If False, the standard deviation of the spectrum is returned.
+
+        Returns
+        -------
+        tuple[ndarray, ndarray]
+            A tuple containing two arrays:
+            - The mean transmission spectrum.
+            - The covariance matrix of the spectrum (if `return_cov` is True), or the
+              standard deviation (if `return_cov` is False).
+        """
+        sp_samples = self.transmission_spectrum_samples(wavelengths, kind, samples)[1]
+        mean = sp_samples.mean(0)
+        if return_cov:
+            return mean, cov(sp_samples, rowvar=False)
+        else:
+            return mean, sp_samples.std(0)
 
     def save(self, overwrite: bool = False) -> None:
         """Save the ExoIris analysis to a FITS file.
@@ -1163,6 +1275,13 @@ class ExoIris:
         pri.header['interp'] = self._tsa.interpolation
         pri.header['noise'] = self._tsa.noise_model
 
+        if self._tsa.free_k_knot_ids is None:
+            pri.header['n_free_k'] = 0
+        else:
+            pri.header['n_free_k'] = len(self._tsa.free_k_knot_ids)
+            for i, ix in enumerate(self._tsa.free_k_knot_ids):
+                pri.header[f'kk_ix_{i:03d}'] = ix
+
         # Priors
         # ======
         pr = pf.ImageHDU(name='priors')
@@ -1246,7 +1365,9 @@ class ExoIris:
 
         hdul.writeto(f"{self.name}.fits", overwrite=True)
 
-    def create_loglikelihood_function(self, wavelengths: ArrayLike, kind: Literal['radius_ratio', 'depth'] = 'depth') -> LogLikelihood:
+    def create_loglikelihood_function(self, wavelengths: ndarray, kind: Literal['radius_ratio', 'depth'] = 'depth',
+                                      method: Literal['svd', 'randomized_svd', 'eigh'] = 'svd',
+                                      n_max_samples: int = 10000) -> LogLikelihood:
         """Create a reduced-rank Gaussian log-likelihood function for retrieval.
 
         Parameters
@@ -1265,7 +1386,11 @@ class ExoIris:
         """
         if self.mcmc_chains is None:
             raise ValueError("Cannot create log-likelihood function before running the MCMC sampler.")
-        return LogLikelihood(self, wavelengths, kind)
+        return LogLikelihood(wavelengths,
+                             self.transmission_spectrum_samples(wavelengths, kind)[1],
+                             method=method,
+                             n_max_samples=n_max_samples,
+                             nk=self.nk)
 
     def create_initial_population(self, n: int, source: str, add_noise: bool = True) -> ndarray:
         """Create an initial parameter vector population for the DE optimisation.

exoiris-0.23.0/exoiris/loglikelihood.py

@@ -0,0 +1,139 @@
+#  ExoIris: fast, flexible, and easy exoplanet transmission spectroscopy in Python.
+#  Copyright (C) 2025 Hannu Parviainen
+#
+#  This program is free software: you can redistribute it and/or modify
+#  it under the terms of the GNU General Public License as published by
+#  the Free Software Foundation, either version 3 of the License, or
+#  (at your option) any later version.
+#
+#  This program is distributed in the hope that it will be useful,
+#  but WITHOUT ANY WARRANTY; without even the implied warranty of
+#  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+#  GNU General Public License for more details.
+#
+#  You should have received a copy of the GNU General Public License
+#  along with this program.  If not, see <https://www.gnu.org/licenses/>.
+from typing import Literal
+
+from numpy import full, cov, sum, ndarray, log, pi, asarray
+from numpy.linalg import eigh, svd
+from sklearn.utils.extmath import randomized_svd
+
+
+class LogLikelihood:
+    def __init__(self, wavelength: ndarray, spectra: None | ndarray = None, spmean: None | ndarray = None,
+                 spcov: None | ndarray = None, eps: float = 1e-10, method: Literal['svd', 'randomized_svd', 'eigh'] = 'svd',
+                 n_max_samples: int = 10000, nk: int | None = None):
+        """Reduced-rank Normal log-likelihood.
+
+        This class constructs a statistically robust log-likelihood function for
+        comparing a theoretical transmission spectrum to the posterior distribution
+        inferred by ExoIris.
+
+        Because the posterior samples are generated from a spline with $K$ knots
+        but evaluated on $M$ wavelengths ($M \gg K$), the empirical covariance
+        matrix is singular or strongly ill-conditioned. This class solves the
+        rank-deficiency problem by projecting the model into the principal
+        subspace of the posterior (Karhunen-Loève compression).
+
+        Parameters
+        ----------
+        wavelength
+            The wavelength grid with a shape (M,) on which the posterior samples and theoretical
+            spectra are evaluated.
+        spectra
+            The posterior spectrum samples with shape (N_samples, M_wavelengths).
+            If provided, ``spmean`` and ``spcov`` are computed automatically.
+            Mutually exclusive with ``spmean`` and ``spcov``.
+        spmean
+            The pre-computed mean spectrum with shape (M,). Must be provided
+            along with ``spcov`` if ``spectra`` is None.
+        spcov
+            The pre-computed covariance matrix with shape (M, M). Must be provided
+            along with ``spmean`` if ``spectra`` is None.
+        eps
+            Relative tolerance factor used to determine which eigenvalues of
+            the covariance matrix are considered significant. Eigenvalues smaller
+            than ``eps * max_eigenvalue`` are discarded. Default is ``1e-10``.
+
+        Notes
+        -----
+        This implementation follows the "Signal-to-Noise Eigenmode" formalism
+        described by Tegmark et al. (1997) for analyzing rank-deficient
+        cosmological datasets.
+
+        The log-likelihood is evaluated as:
+
+        .. math:: \ln \mathcal{L} = -\frac{1}{2} \left[ \sum_{i=1}^{K} \frac{p_i^2}{\lambda_i} + \sum_{i=1}^{K} \ln(\lambda_i) + K \ln(2\pi) \right]
+
+        where $\lambda_i$ are the significant eigenvalues of the covariance
+        matrix, and $p_i$ are the projections of the model residuals onto the
+        corresponding eigenvectors (principal components).
+
+        References
+        ----------
+        Tegmark, M., Taylor, A. N., & Heavens, A. F. (1997). Karhunen-Loève
+        eigenvalue problems in cosmology: how should we tackle large data sets?
+        *The Astrophysical Journal*, 480(1), 22.
+        """
+        self.wavelength = wavelength
+        self.eps = eps
+
+        if spectra is not None and (spmean is not None or spcov is not None):
+            raise ValueError("Cannot specify both `spectra` and `spmean` and `spcov`.")
+
+        if spectra is None and (spmean is None or spcov is None):
+            raise ValueError("Must specify either `spectra` or both `spmean` and `spcov`.")
+
+        if spectra is not None:
+            spectra = spectra[:n_max_samples, :]
+            self.spmean = spectra.mean(axis=0)
+
+        if method == 'svd':
+            _, sigma, evecs = svd(spectra - spectra.mean(0), full_matrices=False)
+            evals = (sigma**2) / (spectra.shape[0] - 1)
+            evecs = evecs.T
+        elif method == 'randomized_svd':
+            if nk is None:
+                raise ValueError("Must specify `nk` when using `method='randomized_svd'`.")
+            _, sigma, evecs = randomized_svd(spectra - spectra.mean(0),  n_components=nk, n_iter=5, random_state=0)
+            evals = (sigma ** 2) / (spectra.shape[0] - 1)
+            evecs = evecs.T
+        elif method == 'eigh' or (spmean is not None and spcov is not None):
+            if spectra is not None:
+                self.spcov = cov(spectra, rowvar=False)
+            else:
+                self.spmean = spmean
+                self.spcov = spcov
+            evals, evecs = eigh(self.spcov)
+
+        keep = evals > eps * evals.max()
+        self.eigenvalues, self.eigenvectors = evals[keep], evecs[:, keep]
+        self.log_det = sum(log(self.eigenvalues))
+        self.log_twopi = self.eigenvalues.size * log(2*pi)
+
+    def __call__(self, model: ndarray | float) -> ndarray:
+        """Evaluate the log-likelihood of a model spectrum.
+
+        Parameters
+        ----------
+        model : float or ndarray
+            The theoretical model spectrum. If a float is provided, it is
+            broadcast to a flat spectrum. If an array, it must match the
+            wavelength grid size used during initialization.
+
+        Returns
+        -------
+        float
+            The natural log-likelihood $\ln \mathcal{L}$.
+        """
+        if isinstance(model, float):
+            model = full(self.wavelength.size, model)
+        else:
+            model = asarray(model)
+
+        # Project the residuals onto the eigenvectors (Basis Rotation)
+        # and Compute the Mahalanobis Distance (Chi-Squared in Subspace).
+        p = (self.spmean - model) @ self.eigenvectors
+        chisq = sum(p**2 / self.eigenvalues)
+        return -0.5 * (chisq + self.log_det + self.log_twopi)