ExoIris 0.20.0__tar.gz → 0.21.0__tar.gz

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

@@ -5,6 +5,15 @@ 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.21.0] - 2025-11-24
+
+### Added
+- Added a `loglikelihood.LogLikelihood` class for reduced-rank Gaussian log-likelihood calculation.
+- Added `ExoIris.create_loglikelihood_function` method to generate log-likelihood instances for atmospheric retrieval.
+- Added `ExoIris.radius_ratio_spectrum` and `ExoIris.area_ratio_spectrum` methods to compute posterior transmission 
+  spectrum distributions for given wavelengths.
+- Added `exoiris.util.create_mock_model` utility function for generating mock transmission spectra.
+
 ## [0.20.0] - 2025-11-19
 
 ### Added
@@ -12,8 +21,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   center time, amplitude in a given reference wavelength, full width at half maximum (FWHM), spot temperature in Kelvin,
   and spot shape. The spot amplitude along the wavelength is modeled using the theoretical BT-Settl spectra, the stellar
   effective temperature, the spot temperature, and the reference wavelength in which the spot amplitude is measured.
-- Added the ability to model the contamination from unocculted spots and faculae (the transit light source effect, 
-  or TLSE).
+- Added the ability to model the contamination from unocculted spots and faculae (**the transit light source effect**,
+  or TLSE). This is modeled also using BT-Settl spectra following the formalism described by Rackham et al. (2018).
 - Included two new radius ratio interpolation options: "nearest" and "linear".
 
 ## [0.19.2] - 2025-09-12

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ExoIris
-Version: 0.20.0
+Version: 0.21.0
 Summary: Easy and robust exoplanet transmission spectroscopy.
 Author-email: Hannu Parviainen <hannu@iac.es>
 License: GPLv3

{exoiris-0.20.0 → exoiris-0.21.0}/ExoIris.egg-info/SOURCES.txt

@@ -45,6 +45,7 @@ exoiris/binning.py
 exoiris/ephemeris.py
 exoiris/exoiris.py
 exoiris/ldtkld.py
+exoiris/loglikelihood.py
 exoiris/spotmodel.py
 exoiris/tsdata.py
 exoiris/tslpf.py

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ExoIris
-Version: 0.20.0
+Version: 0.21.0
 Summary: Easy and robust exoplanet transmission spectroscopy.
 Author-email: Hannu Parviainen <hannu@iac.es>
 License: GPLv3

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

@@ -32,7 +32,8 @@ 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)
+                   ceil, unique, zeros)
+from numpy.typing import ArrayLike
 from numpy.random import normal
 from pytransit import UniformPrior, NormalPrior
 from pytransit.param import ParameterSet
@@ -44,6 +45,7 @@ from .ldtkld import LDTkLD
 from .tsdata import TSData, TSDataGroup
 from .tslpf import TSLPF
 from .wlpf import WhiteLPF
+from .loglikelihood import LogLikelihood
 
 
 def load_model(fname: Path | str, name: str | None = None):
@@ -1128,6 +1130,22 @@ 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 save(self, overwrite: bool = False) -> None:
         """Save the ExoIris analysis to a FITS file.
 
@@ -1228,6 +1246,27 @@ class ExoIris:
 
         hdul.writeto(f"{self.name}.fits", overwrite=True)
 
+    def create_loglikelihood_function(self, wavelengths: ArrayLike, kind: Literal['radius_ratio', 'depth'] = 'depth') -> LogLikelihood:
+        """Create a reduced-rank Gaussian log-likelihood function for retrieval.
+
+        Parameters
+        ----------
+        wavelengths
+            The wavelength grid used in the theoretical transmission spectra.
+
+        kind
+            The transmission spectrum type. Can be either 'radius_ratio' or 'depth'.
+
+        Returns
+        -------
+        LogLikelihood
+            An instance of LogLikelihood for analyzing the consistency of the model
+            with the provided wavelengths and chosen log-likelihood kind.
+        """
+        if self.mcmc_chains is None:
+            raise ValueError("Cannot create log-likelihood function before running the MCMC sampler.")
+        return LogLikelihood(self, wavelengths, kind)
+
     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.21.0/exoiris/loglikelihood.py

@@ -0,0 +1,144 @@
+#  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, sqrt, sum
+from numpy.linalg import eigh
+from numpy.typing import ArrayLike
+
+
+class LogLikelihood:
+    def __init__(self, exoiris, wavelength: ArrayLike, kind: Literal['radius_ratio', 'depth'] = 'depth', eps: float = 1e-10):
+        """Reduced-rank Gaussian log-likelihood.
+
+        This class constructs a statistically correct reduced-rank Gaussian
+        log-likelihood function for comparing a theoretical transmission spectrum to the
+        posterior distribution inferred by ExoIris. Because the posterior
+        samples of the transmission spectrum are generated from a spline with
+        far fewer independent parameters than the number of wavelength bins, the
+        empirical covariance matrix is rank-deficient or strongly ill-conditioned.
+        Direct inversion of the full covariance is therefore numerically unstable
+        and produces incorrect likelihoods.
+
+        Parameters
+        ----------
+        exoiris
+            The ExoIris model object from which posterior samples of the knot
+            values and spline interpolation functions are obtained.
+
+        wavelength
+            Wavelength grid on which the radius ratio posterior samples and the
+            theoretical spectra will be evaluated.
+
+        kind
+            The type of the spectrum. Can be either ``radius_ratio`` for a radius ratio
+            spectrum, or ``depth`` for a transit depth spectrum.
+
+        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``.
+
+        Attributes
+        ----------
+        k_posteriors : ndarray of shape (n_samples, n_wavelengths)
+            Radius-ratio posterior samples evaluated on the wavelength grid.
+
+        k_mean : ndarray of shape (n_wavelengths,)
+            Posterior mean radius-ratio spectrum.
+
+        k_cov : ndarray of shape (n_wavelengths, n_wavelengths)
+            Empirical covariance matrix of the posterior samples.
+
+        lambda_r : ndarray of shape (k,)
+            Significant eigenvalues of the covariance matrix (``k`` = reduced
+            dimensionality).
+
+        u_r : ndarray of shape (n_wavelengths, k)
+            Eigenvectors corresponding to the significant eigenvalues.
+
+        sqrt_inv_lambda_r : ndarray of shape (k,)
+            Factors used to whiten the reduced-rank representation.
+
+        y_data : ndarray of shape (k,)
+            Whitened reduced-rank representation of the posterior mean spectrum.
+
+        Notes
+        -----
+         The class implements the reduced-rank likelihood method:
+
+        1. Posterior samples of the spline knot values are evaluated on the
+           user-specified wavelength grid to produce a matrix of radius-ratio
+           samples, ``k_posteriors``.
+
+        2. The empirical mean spectrum and covariance matrix are computed over
+           these samples.
+
+        3. An eigendecomposition of the covariance matrix is performed. All
+           eigenvalues below ``eps * max(eigenvalue)`` are discarded, ensuring that
+           only statistically meaningful directions (i.e., those supported by the
+           spline parameterization and the data) are retained.
+
+        4. The retained eigenvectors form an orthonormal basis for the true
+           low-dimensional subspace in which the posterior distribution lives.
+           Projection onto this basis, followed by whitening with
+           ``lambda_r**(-1/2)``, yields a representation where the posterior is a
+           standard multivariate normal with identity covariance.
+
+        5. The log-likelihood of a theoretical spectrum ``x`` is evaluated in this
+           reduced space as:
+
+               log L = -0.5 * sum_i (y_data[i] - y_model[i])^2
+
+           where ``y_data`` is the whitened reduced-space representation of the
+           posterior mean spectrum, and ``y_model`` is the whitened projection of
+           the model spectrum.
+
+        - This reduced-rank formulation is mathematically equivalent to computing
+          the Gaussian likelihood in knot space, and avoids the numerical
+          instabilities associated with inverting a nearly singular covariance
+          matrix in the oversampled wavelength space.
+
+        - If ``x`` is provided as a scalar, it is broadcast to a constant spectrum
+          over the wavelength grid. Otherwise, it must be an array of the same
+          wavelength length.
+        """
+        self.model = m = exoiris
+        self.wavelength = wavelength
+        self.eps = eps
+
+        if kind == 'radius_ratio':
+            self.spectrum = m.radius_ratio_spectrum(wavelength)
+        elif kind == 'depth':
+            self.spectrum = m.area_ratio_spectrum(wavelength)
+        else:
+            raise ValueError('Unknown spectrum type: {}'.format(kind))
+
+        self.spmean = self.spectrum.mean(0)
+        self.spcov = cov(self.spectrum, rowvar=False)
+
+        evals, u = eigh(self.spcov)
+        tol = eps * evals.max()
+        keep = evals > tol
+        self.lambda_r, self.u_r = evals[keep], u[:, keep]
+        self.sqrt_inv_lambda_r = 1.0 / sqrt(self.lambda_r)
+        self.y_data = (self.u_r.T @ self.spmean) * self.sqrt_inv_lambda_r
+
+    def __call__(self, x):
+        if isinstance(x, float):
+            x = full(self.wavelength.size, x)
+        y_model = (self.u_r.T @ x) * self.sqrt_inv_lambda_r
+        return -0.5*sum((self.y_data - y_model)**2)

{exoiris-0.20.0 → exoiris-0.21.0}/exoiris/tslpf.py

@@ -35,7 +35,6 @@ from scipy.interpolate import (
     splev,
     Akima1DInterpolator,
     interp1d,
-    FloaterHormannInterpolator,
 )
 
 from .tsmodel import TransmissionSpectroscopyModel as TSModel
@@ -102,6 +101,13 @@ def add_knots(x_new, x_old):
     return sort(concatenate([x_new, x_old]))
 
 
+interpolator_choices = ("bspline", "pchip", "makima", "nearest", "linear")
+
+
+interpolators = {'bspline': ip_bspline, 'pchip': ip_pchip, 'makima': ip_makima,
+            'nearest': ip_nearest, 'linear': ip_linear}
+
+
 def clean_knots(knots, min_distance, lmin=0, lmax=inf):
     """Clean the knot table by replacing groups of adjacent knots with a single knot at the group mean.
 
@@ -154,8 +160,10 @@ class TSLPF(LogPosteriorFunction):
         self._baseline_models: list[ndarray] | None = None
         self.interpolation: str = interpolation
 
-        self._ip = {'bspline': ip_bspline, 'pchip': ip_pchip, 'makima': ip_makima,
-                    'nearest': ip_nearest, 'linear': ip_linear}[interpolation]
+        if interpolation not in interpolator_choices:
+            raise ValueError(f'interpolation must be one of {interpolator_choices}')
+        self._ip = interpolators[interpolation]
+        self._ip_ld = interpolators['bspline']
 
         self._gp: Optional[list[GP]] = None
         self._gp_time: Optional[list[ndarray]] = None
@@ -608,8 +616,8 @@ class TSLPF(LogPosteriorFunction):
             ldp = [zeros((pvp.shape[0], npb, 2)) for npb in self.npb]
             for ids in range(self.data.size):
                 for ipv in range(pvp.shape[0]):
-                    ldp[ids][ipv, :, 0] = ip_bspline(self.wavelengths[ids], self.ld_knots, ldk[ipv, :, 0])
-                    ldp[ids][ipv, :, 1] = ip_bspline(self.wavelengths[ids], self.ld_knots, ldk[ipv, :, 1])
+                    ldp[ids][ipv, :, 0] = self._ip_ld(self.wavelengths[ids], self.ld_knots, ldk[ipv, :, 0])
+                    ldp[ids][ipv, :, 1] = self._ip_ld(self.wavelengths[ids], self.ld_knots, ldk[ipv, :, 1])
             return ldp
 
     def transit_model(self, pv, copy=True):

{exoiris-0.20.0 → exoiris-0.21.0}/exoiris/util.py

@@ -15,8 +15,10 @@
 #  along with this program.  If not, see <https://www.gnu.org/licenses/>.
 
 from numba import njit
-from numpy import zeros, sum, sqrt, linspace, vstack, concatenate, floor, dot, ndarray, nan
-
+from numpy import (zeros, sum, sqrt, linspace, vstack, concatenate, floor, dot, ndarray, nan, asarray, tile)
+from numpy._typing import ArrayLike
+from pytransit import TSModel
+from pytransit.orbits import i_from_ba
 
 @njit
 def bin2d(v, e, el, er, bins, estimate_errors: bool = False) -> tuple[ndarray, ndarray]:
@@ -116,4 +118,45 @@ def create_binning(ranges, bwidths):
         n = int(floor((r[1] - r[0]) / w))
         e = linspace(*r, num=n)
         bins.append(vstack([e[:-1], e[1:]]).T)
-    return concatenate(bins)
+    return concatenate(bins)
+
+
+def create_mock_model(ks: ArrayLike, times: ArrayLike = None, ldc: ArrayLike = None, t0: float = 0.0, p: float =2.0, a: float =8.0, b: float =0.0) -> ndarray:
+    """Create a mock transmission spectrum observation using given parameters.
+
+    Parameters
+    ----------
+    ks
+        Array of radius ratios, one radius ratio per wavelength.
+    times
+        Array of time values to set the data points. If None, defaults to a
+        linspace of 500 points in the range [-0.1, 0.1].
+    ldc
+        Array representing the limb darkening coefficients. If None, defaults to
+        a tile of [0.4, 0.4] for each wavelength element.
+    t0
+        Transit center.
+    p
+        Orbital period.
+    a
+        Semi-major axis.
+    b
+        Impact parameter.
+
+    Returns
+    -------
+    ndarray
+        Mock spectrophotometric light curves.
+
+    """
+    ks = asarray(ks)
+    if times is None:
+        times = linspace(-0.1, 0.1, 500)
+    if ldc is None:
+        ldc = tile([0.4, 0.4], (1, ks.size, 1))
+    inc = i_from_ba(b, a)
+
+    m1 = TSModel('power-2', ng=100, nzin=50, nzlimb=50)
+    m1.set_data(times)
+    f1 = m1.evaluate(ks, ldc, t0, p, a, inc)[0]
+    return f1