API Reference (spotgp)

Observations#

class spotgp.observations.TimeSeriesData(x, y, yerr, normalize=False, zero_mean=False)[source]#

Bases: object

Container for observed time series data.

Parameters:

x (array_like, shape (N,)) – Observation times.
y (array_like, shape (N,)) – Observed values (e.g. flux).
yerr (array_like, shape (N,) or float) – Measurement uncertainties. A scalar is broadcast to all points.
normalize (bool) – If True (default), normalize the flux so that the median is 1 and scale yerr accordingly.

property N: int#: Number of data points.

property baseline: float#: Total time baseline.

property median_dt: float#: Median time step.

normalize()[source]#

Normalize the flux so that the median equals 1.

Divides y and yerr by the median of y. This is idempotent: calling it on already-normalized data (median ~ 1) has negligible effect.

detrend(window)[source]#

Subtract a rolling-median trend from the flux.

A median is computed in a sliding window of width window (in the same units as x, typically days). The trend is subtracted and the global median is added back so the baseline stays near the original level.

Parameters:: window (float) – Window width for the rolling median [same units as x].

sigma_clip(lower=3.0, upper=3.0)[source]#

Remove outliers beyond a sigma threshold.

Masks out points where y falls below mean(y) - |lower| * std(y) or above mean(y) + |upper| * std(y).

Parameters:

lower (float) – Number of standard deviations below the mean (default 3).
upper (float) – Number of standard deviations above the mean (default 3).

downsample(dt)[source]#

Downsample the time series into non-overlapping bins of width dt.

Within each bin the flux is the inverse-variance weighted mean and the uncertainty is propagated as:

yerr_bin = 1 / sqrt(sum(1 / yerr_i^2))

Bins containing zero points are dropped.

Parameters:: dt (float) – Bin width in the same units as x.

compute_psd(normalization='psd', freq_min=None, freq_max=None, n_freq=None, samples_per_peak=5)[source]#

Compute the Lomb-Scargle power spectral density.

Parameters:

normalization (str) – LombScargle normalization mode (default “psd”).
freq_min (float, optional) – Frequency bounds.
freq_max (float, optional) – Frequency bounds.
n_freq (int, optional) – Number of frequency grid points.
samples_per_peak (float, optional) – Frequency grid density (default 5).

Returns:

freq (ndarray) – Frequencies [cycles per unit time].
power (ndarray) – PSD at each frequency.

compute_acf(n_bins=None, max_lag=None)[source]#

Compute the empirical autocorrelation function from irregularly sampled data using binned lag pairs.

For each pair of observations (i, j), the lag |x_i - x_j| and product (y_i - mean)(y_j - mean) are accumulated into bins. The ACF is the mean product in each bin, normalized by the variance.

Parameters:

n_bins (int, optional) – Number of lag bins (default: N // 2).
max_lag (float, optional) – Maximum lag to compute (default: half the baseline).

Returns:

lag_centers (ndarray, shape (n_bins,)) – Center of each lag bin.
acf (ndarray, shape (n_bins,)) – Normalized autocorrelation in each bin.

classmethod from_lightkurve(lc, normalize=False, zero_mean=False)[source]#

Create a TimeSeriesData from a lightkurve LightCurve object.

Extracts time, flux, and flux_err arrays, removes NaN entries, and converts Astropy quantities to plain floats if needed.

Parameters:

lc (lightkurve.LightCurve) – A LightCurve object (e.g. from lk.search_lightcurve(...).download()).
normalize (bool) – If True (default), normalize flux to median of 1.
zero_mean (bool) – If True, subtract the mean from the flux.

Return type:

TimeSeriesData

plot(ax=None, color='k', alpha=0.6, marker='.', ms=2, xlabel='Time', ylabel='Flux', **kwargs)[source]#

Plot the time series.

Parameters:

ax (matplotlib Axes, optional) – Axes to plot on. If None, creates a new figure.
color (plot style options.)
alpha (plot style options.)
marker (plot style options.)
ms (plot style options.)
xlabel (str) – Axis labels.
ylabel (str) – Axis labels.
**kwargs – Extra keyword arguments passed to ax.errorbar.

Returns:

Return type:

matplotlib Axes

plot_psd(ax=None, color='k', lw=1.0, loglog=True, xlabel='Frequency', ylabel='Power', **psd_kwargs)[source]#

Plot the Lomb-Scargle PSD.

Calls compute_psd() if it hasn’t been run yet (or if psd_kwargs are provided to override previous settings).

Parameters:

ax (matplotlib Axes, optional)
color (plot style options.)
lw (plot style options.)
loglog (bool) – If True (default), use log-log axes.
xlabel (str) – Axis labels.
ylabel (str) – Axis labels.
**psd_kwargs – Passed to compute_psd().

Returns:

Return type:

matplotlib Axes

plot_acf(ax=None, color='k', lw=1.5, xlabel='Time lag', ylabel='ACF', **acf_kwargs)[source]#

Plot the empirical autocorrelation function.

Calls compute_acf() if it hasn’t been run yet (or if acf_kwargs are provided to override previous settings).

Parameters:

ax (matplotlib Axes, optional)
color (plot style options.)
lw (plot style options.)
xlabel (str) – Axis labels.
ylabel (str) – Axis labels.
**acf_kwargs – Passed to compute_acf().

Returns:

Return type:

matplotlib Axes

Distributions#

class spotgp.distributions.ParameterDistribution[source]#

Bases: object

Base class for a distribution over a scalar kernel parameter.

Subclasses must implement support and __call__.

property support: tuple#: (min, max) range of the parameter.

property mean: float#

numerical via quadrature.

Type:: Mean of the distribution. Default

expectation(func, n_quad=32)[source]#

Compute E[func(x)] under this distribution via Gauss-Legendre quadrature over self.support.

Parameters:

func (callable) – Function to take the expectation of.
n_quad (int) – Number of quadrature points (default 32).

Return type:

float

sample(n, rng=None)[source]#: Draw n samples via inverse-CDF on the quadrature grid. For quick prototyping; not intended for MCMC.

sympy_pdf()[source]#

Return the sympy expression for the PDF.

Subclasses should override to provide their analytic form. The base implementation returns None (numerical only).

Return type:: sympy.Expr or None

get_sympy(display=True, status=None, var_name='x')[source]#

Display the sympy expression for the distribution PDF.

Parameters:

display (bool) – If True (default), render/print the expression.
status (str or None, optional) – If provided, appended to the class name header in brackets.
var_name (str) – Name of the variable (default “x”).

Returns:

{"pdf": expr_or_None}

Return type:

class spotgp.distributions.DeltaDistribution(value)[source]#

Degenerate distribution at a fixed value (Dirac delta).

Wraps a plain float so that all code paths can treat parameters uniformly as distributions. expectation(func) returns func(value) with no quadrature overhead.

property support#: (min, max) range of the parameter.

property mean#

numerical via quadrature.

Type:: Mean of the distribution. Default

expectation(func, n_quad=32)[source]#

Compute E[func(x)] under this distribution via Gauss-Legendre quadrature over self.support.

Parameters:

func (callable) – Function to take the expectation of.
n_quad (int) – Number of quadrature points (default 32).

Return type:

float

sympy_pdf()[source]#

Return the sympy expression for the PDF.

Subclasses should override to provide their analytic form. The base implementation returns None (numerical only).

Return type:: sympy.Expr or None

class spotgp.distributions.UniformDistribution(lo, hi)[source]#

Uniform distribution over [lo, hi].

Parameters:

lo (float) – Lower and upper bounds.
hi (float) – Lower and upper bounds.

property support#: (min, max) range of the parameter.

property mean#

numerical via quadrature.

Type:: Mean of the distribution. Default

sympy_pdf()[source]#

Return the sympy expression for the PDF.

Subclasses should override to provide their analytic form. The base implementation returns None (numerical only).

Return type:: sympy.Expr or None

class spotgp.distributions.GaussianDistribution(mu, sigma, clip_sigma=4.0)[source]#

Truncated Gaussian distribution.

Parameters:

mu (float) – Mean.
sigma (float) – Standard deviation.
clip_sigma (float) – Number of sigma for truncation (default 4).

property support#: (min, max) range of the parameter.

property mean#

numerical via quadrature.

Type:: Mean of the distribution. Default

sympy_pdf()[source]#

Return the sympy expression for the PDF.

Subclasses should override to provide their analytic form. The base implementation returns None (numerical only).

Return type:: sympy.Expr or None

class spotgp.distributions.LogNormalDistribution(mu, sigma, clip_sigma=4.0)[source]#

Log-normal distribution (positive-valued parameters).

If X ~ LogNormal(mu, sigma), then log(X) ~ Normal(mu, sigma).

Parameters:

mu (float) – Mean of log(X).
sigma (float) – Std of log(X).
clip_sigma (float) – Truncation in log-space (default 4).

property support#: (min, max) range of the parameter.

property mean#

numerical via quadrature.

Type:: Mean of the distribution. Default

sympy_pdf()[source]#

Return the sympy expression for the PDF.

Subclasses should override to provide their analytic form. The base implementation returns None (numerical only).

Return type:: sympy.Expr or None

spotgp.distributions.as_distribution(value)[source]#

Wrap a value as a ParameterDistribution if it isn’t one already.

Parameters:: value (float or ParameterDistribution) – If float, returns a DeltaDistribution. If already a ParameterDistribution, returns it unchanged.
Return type:: ParameterDistribution

spotgp.distributions.is_distributed(value)[source]#: Return True if value is a non-degenerate distribution.

Parameters#

class spotgp.params.EnvelopeSpec(name: str, signature_keys: FrozenSet[str], resolve: Callable[[dict], dict], description: str = '')[source]#

Bases: object

Specification for a spot envelope shape.

name#

Unique identifier (e.g. “trapezoid_symmetric”).

Type:: str

signature_keys#

Keys that identify this envelope in a raw hparam dict. Detection checks signature_keys <= raw.keys(); the most specific match (largest signature) wins.

Type:: frozenset[str]

resolve#

(raw: dict) -> dict Returns additional key-value pairs to merge into the resolved hparam. Must always include "tau_spot" (a scalar timescale) for backward compatibility with modules that require a single timescale value.

Type:: callable

description#

Human-readable summary shown in error messages.

Type:: str

name: str#

signature_keys: FrozenSet[str]#

resolve: Callable[[dict], dict]#

description: str = ''#

class spotgp.params.AmplitudeSpec(name: str, signature_keys: FrozenSet[str], formula: Callable[[dict], float], description: str = '')[source]#

Bases: object

Specification for a kernel amplitude parameterization.

name#

Unique identifier.

Type:: str

signature_keys#

Keys that identify this amplitude mode in a raw hparam dict.

Type:: frozenset[str]

formula#

(raw: dict) -> float Computes sigma_k from the raw dict.

Type:: callable

description#

Human-readable summary shown in error messages.

Type:: str

name: str#

signature_keys: FrozenSet[str]#

formula: Callable[[dict], float]#

description: str = ''#

spotgp.params.register_envelope(spec: EnvelopeSpec, priority: str = 'low') → None[source]#

Parameters:

spec (EnvelopeSpec)
priority ({"low", "high"}) – “high” prepends (checked first within its specificity tier); “low” appends (default). Specificity (len of signature_keys) always takes precedence over priority.

spotgp.params.register_amplitude(spec: AmplitudeSpec, priority: str = 'low') → None[source]#

Parameters:

spec (AmplitudeSpec)
priority ({"low", "high"}) – Same semantics as register_envelope.

spotgp.params.resolve_hparam(raw: dict) → dict[source]#

Validate and normalise a raw hyperparameter dict.

Steps#

Checks that base required keys (peq, kappa, inc, lspot) are present.
Auto-detects the envelope type from registered EnvelopeSpecs and merges any derived keys (e.g. scalar tau from tau_em/tau_dec).
Auto-detects the amplitude mode from registered AmplitudeSpecs and injects the computed sigma_k.

The most-specific matching spec (largest signature_keys) wins for both envelope and amplitude detection.

returns:: A new dict containing all original keys plus any keys injected by the envelope and amplitude resolvers. The returned dict always contains "tau_spot" and "sigma_k".
rtype:: dict
raises TypeError:: If raw is not a dict.
raises ValueError:: If required keys are missing, or if no registered spec matches.

Envelope Functions#

class spotgp.envelope.EnvelopeFunction[source]#

Bases: ABC

Abstract base class for spot size envelope functions.

To define a custom envelope, subclass this and implement:

Required:

tau_spot (property) : characteristic timescale [days]. Used to set the extent of numerical integration grids.

Gamma(t) : normalized envelope, peak = 1.

Optional (numerical defaults are provided):

lspot (property) : plateau duration [days]. Default: 0.

param_dict (property): {name: value} dict of envelope parameters. Needed for GPSolver to know which parameters to fit. Default: {} (kernel evaluation still works; fitting will not expose envelope parameters).

R_Gamma(lag) : autocorrelation ∫ Γ(t)Γ(t+lag)dt. Default: computed via FFT from Gamma.

Gamma_hat(omega) : |FT[Gamma]|(ω). Default: computed via FFT from Gamma.

Gamma_hat_sq(omega) : |FT[Gamma]|²(ω). Default: Gamma_hat(omega) ** 2.

kernel_support() : upper lag bound where R_Gamma is negligible. Default: lspot + 6 * tau_spot.

The numerical defaults are computed lazily: the FFT grids are built once on the first call and cached on the instance, so there is no cost for subclasses that override these methods.

Example

>>> class GaussianEnvelope(EnvelopeFunction):
...     def __init__(self, sigma):
...         self._sigma = float(sigma)
...     @property
...     def tau_spot(self):
...         return self._sigma
...     @property
...     def param_dict(self):
...         return {"tau_spot": self._sigma}
...     def Gamma(self, t):
...         import jax.numpy as jnp
...         return jnp.exp(-0.5 * (t / self._sigma) ** 2)

abstract property tau_spot: float#: Characteristic (scalar) timescale [days].

abstractmethod Gamma(t)[source]#

Normalized spot-size envelope evaluated at relative times t.

t = 0 is the center/peak of the envelope. Must return values in [0, 1] with a peak of 1. Should be JAX-compatible (jnp operations) so that it can be evaluated inside JIT-compiled code.

property lspot: float#: Spot plateau duration [days]. Default 0 (no plateau).

property param_dict: dict#

Envelope parameters as {name: value}.

Override this to expose envelope parameters to GPSolver and SpotEvolutionModel. The default returns an empty dict, which means the envelope shape is fixed (not inferred during GP fitting).

kernel_support() → float[source]#

Upper bound on the lag support of R_Gamma [days].

Used by GPSolver to compute the banded-Cholesky bandwidth. Default: lspot + 6 * tau_spot. Override for tighter bounds.

Gamma_integral() → float[source]#

Integral of the squared-size envelope: \(\int \Gamma(t)\,dt\).

Used by AnalyticMean to compute the expected flux deficit. Default: numerical quadrature from Gamma(t). Override with a closed-form expression for better accuracy.

R_Gamma(lag)[source]#

Autocorrelation R_Gamma(lag) = ∫ Gamma(t) · Gamma(t + lag) dt.

Default: interpolated from an FFT-based precomputed grid. Override with an analytic expression for better performance.

Gamma_hat(omega)[source]#

Fourier transform magnitude |FT[Gamma]|(omega).

Default: interpolated from an FFT-based precomputed grid. Override with a closed-form expression for better performance.

Gamma_hat_sq(omega)[source]#

|FT[Gamma](omega)|² = Gamma_hat(omega)².

Default: interpolated from an FFT-based precomputed grid.

sympy_Gamma()[source]#

Sympy expression for Gamma(t).

Override in subclasses that have a closed-form envelope. Returns None if no analytic expression is available.

sympy_Gamma_hat()[source]#

Sympy expression for Gamma_hat(omega) = FT[Gamma](omega).

Override in subclasses with a closed-form Fourier transform. Returns None if no analytic form is available.

sympy_R_Gamma()[source]#

Sympy expression for R_Gamma(tau) = integral Gamma(t) Gamma(t+tau) dt.

Override in subclasses with a closed-form autocorrelation. Returns None if no analytic form is available.

get_sympy(display=True, status=None, compute_symbolic=False)[source]#

Retrieve and display sympy expressions for Gamma, Gamma_hat, and R_Gamma.

Prints or renders the LaTeX equation for each function that has a closed-form analytic expression, or ‘[numerical]’ for functions that rely on FFT-based approximations.

Requires sympy (pip install sympy).

Parameters:

display (bool, optional) – If True (default), render equations as formatted LaTeX in a Jupyter notebook (via IPython.display) or print them as LaTeX strings in a plain terminal.
status (str or None, optional) – If provided, appended to the class name header in brackets, e.g. "user defined" renders as TrapezoidSymmetricEnvelope [user defined].
compute_symbolic (bool, optional) – If True, attempt to derive Gamma_hat and R_Gamma symbolically from sympy_Gamma() when no explicit override exists. Can be slow for complex envelopes. Defaults to False.

Returns:

``{“Gamma”: expr_or_None, “Gamma_hat”: expr_or_None,: ”R_Gamma”: expr_or_None}``

Return type:

check_functions(n_pts=300, ax=None, show=False)[source]#

Compare analytic overrides of Gamma_hat and R_Gamma to the FFT-based numerical implementations.

Checks whether the subclass has provided analytic overrides for Gamma_hat(omega) and/or R_Gamma(lag). For each override found, evaluates both the analytic and numerical versions on a fine grid, plots the comparison, and computes the RMSE and max absolute error (both normalized by the numerical peak).

Parameters:

n_pts (int, optional) – Number of evaluation points on each grid. Default 300.
ax (matplotlib Axes or array of Axes, optional) – Axes to plot on. If None, a new figure is created sized to the number of overridden functions.
show (bool, optional) – If True, call plt.show() after plotting. Default False.

Returns:

errors – Keys are the names of overridden functions ("Gamma_hat" and/or "R_Gamma"). Each value is a dict with:

"rmse" : root-mean-square error (normalized by peak)
"max_err" : maximum absolute error (normalized by peak)

Return type:

class spotgp.envelope.TrapezoidSymmetricEnvelope(lspot, tau_spot)[source]#

Symmetric trapezoidal envelope.

Shape: linear rise over tau_spot, plateau of lspot, linear decay over tau_spot.

Parameters:

lspot (float or ParameterDistribution) – Plateau duration [days].
tau_spot (float or ParameterDistribution) – Rise/decay timescale [days].
ParameterDistribution (When either parameter is a)
R_Gamma
the (returns the marginalized autocorrelation integrated over)
return (distribution(s). The lspot and tau_spot properties)
compatibility. (the distribution means for backward)

property tau_spot: float#: Characteristic (scalar) timescale [days].

property lspot: float#: Spot plateau duration [days]. Default 0 (no plateau).

property lspot_distribution#: The full ParameterDistribution for lspot.

property tau_spot_distribution#: The full ParameterDistribution for tau_spot.

property param_dict: dict#

Envelope parameters as {name: value}.

Override this to expose envelope parameters to GPSolver and SpotEvolutionModel. The default returns an empty dict, which means the envelope shape is fixed (not inferred during GP fitting).

Gamma(t)[source]#

Normalized spot-size envelope evaluated at relative times t.

t = 0 is the center/peak of the envelope. Must return values in [0, 1] with a peak of 1. Should be JAX-compatible (jnp operations) so that it can be evaluated inside JIT-compiled code.

Gamma_hat(omega)[source]#

Fourier transform magnitude |FT[Gamma]|(omega).

Default: interpolated from an FFT-based precomputed grid. Override with a closed-form expression for better performance.

Gamma_hat_sq(omega)[source]#

|FT[Gamma](omega)|² = Gamma_hat(omega)².

Default: interpolated from an FFT-based precomputed grid.

R_Gamma(lag)[source]#

Autocorrelation R_Gamma(lag) = ∫ Gamma(t) · Gamma(t + lag) dt.

Default: interpolated from an FFT-based precomputed grid. Override with an analytic expression for better performance.

kernel_support() → float[source]#

Upper bound on the lag support of R_Gamma [days].

Used by GPSolver to compute the banded-Cholesky bandwidth. Default: lspot + 6 * tau_spot. Override for tighter bounds.

Gamma_integral() → float[source]#

Integral of the squared-size envelope: \(\int \Gamma(t)\,dt\).

Used by AnalyticMean to compute the expected flux deficit. Default: numerical quadrature from Gamma(t). Override with a closed-form expression for better accuracy.

sympy_Gamma()[source]#

Sympy expression for Gamma(t).

Override in subclasses that have a closed-form envelope. Returns None if no analytic expression is available.

sympy_Gamma_hat()[source]#

Sympy expression for Gamma_hat(omega) = FT[Gamma](omega).

Override in subclasses with a closed-form Fourier transform. Returns None if no analytic form is available.

class spotgp.envelope.TrapezoidAsymmetricEnvelope(lspot: float, tau_em: float, tau_dec: float)[source]#

Asymmetric trapezoidal envelope with distinct emergence and decay rates.

Shape: linear rise over tau_em, plateau of lspot, linear decay over tau_dec.

Parameters:

lspot (float) – Plateau duration [days].
tau_em (float) – Emergence timescale [days].
tau_dec (float) – Decay timescale [days].

property tau_spot: float#: Characteristic (scalar) timescale [days].

property tau_em: float#

property tau_dec: float#

property lspot: float#: Spot plateau duration [days]. Default 0 (no plateau).

property param_dict: dict#

Envelope parameters as {name: value}.

Override this to expose envelope parameters to GPSolver and SpotEvolutionModel. The default returns an empty dict, which means the envelope shape is fixed (not inferred during GP fitting).

Gamma(t)[source]#

Normalized spot-size envelope evaluated at relative times t.

t = 0 is the center/peak of the envelope. Must return values in [0, 1] with a peak of 1. Should be JAX-compatible (jnp operations) so that it can be evaluated inside JIT-compiled code.

R_Gamma(lag)[source]#

Autocorrelation R_Gamma(lag) = ∫ Gamma(t) · Gamma(t + lag) dt.

Default: interpolated from an FFT-based precomputed grid. Override with an analytic expression for better performance.

kernel_support() → float[source]#

Upper bound on the lag support of R_Gamma [days].

Used by GPSolver to compute the banded-Cholesky bandwidth. Default: lspot + 6 * tau_spot. Override for tighter bounds.

Gamma_integral() → float[source]#

Integral of the squared-size envelope: \(\int \Gamma(t)\,dt\).

Used by AnalyticMean to compute the expected flux deficit. Default: numerical quadrature from Gamma(t). Override with a closed-form expression for better accuracy.

sympy_Gamma()[source]#

Sympy expression for Gamma(t).

Override in subclasses that have a closed-form envelope. Returns None if no analytic expression is available.

class spotgp.envelope.SkewedGaussianEnvelope(sigma_sn: float, n_sn: float, lspot: float = 0.0)[source]#

Skew-normal (Baranyi et al. 2021) envelope.

Implements Eq. (1) of Baranyi et al. (2021) A&A 653, A59:: Gamma(t) ∝ exp(-t²/(2σ²)) · (1 + erf(n·t / (σ·√2)))

Parameters:

sigma_sn (float) – Scale parameter [days].
n_sn (float) – Skewness (dimensionless). n_sn < 0: rapid rise / slow decay; n_sn > 0: slow rise / rapid decay; n_sn = 0: Gaussian.
lspot (float, optional) – Unused (required by base schema); set to 0 (default).

property tau_spot: float#: Characteristic (scalar) timescale [days].

property sigma_sn: float#

property n_sn: float#

property lspot: float#: Spot plateau duration [days]. Default 0 (no plateau).

property param_dict: dict#

Envelope parameters as {name: value}.

Override this to expose envelope parameters to GPSolver and SpotEvolutionModel. The default returns an empty dict, which means the envelope shape is fixed (not inferred during GP fitting).

Gamma(t)[source]#: JAX-traceable Gamma(t) via interpolation from precomputed grid.

Gamma_hat(omega)[source]#

Fourier transform magnitude |FT[Gamma]|(omega).

Default: interpolated from an FFT-based precomputed grid. Override with a closed-form expression for better performance.

Gamma_hat_sq(omega)[source]#

|FT[Gamma](omega)|² = Gamma_hat(omega)².

Default: interpolated from an FFT-based precomputed grid.

R_Gamma(lag)[source]#

Autocorrelation R_Gamma(lag) = ∫ Gamma(t) · Gamma(t + lag) dt.

Default: interpolated from an FFT-based precomputed grid. Override with an analytic expression for better performance.

kernel_support() → float[source]#

Upper bound on the lag support of R_Gamma [days].

Used by GPSolver to compute the banded-Cholesky bandwidth. Default: lspot + 6 * tau_spot. Override for tighter bounds.

class spotgp.envelope.ExponentialEnvelope(tau_spot: float)[source]#

Bilateral exponential (double-sided) envelope.

Gamma(t) = exp(-|t| / tau_spot)

This gives a spot that is at peak at t = 0 and decays symmetrically with characteristic timescale tau_spot. There is no plateau (lspot = 0).

Analytical results:: Gamma_hat(omega) = 2*tau_spot / (1 + (omega*tau_spot)²) [Lorentzian] R_Gamma(lag) = (tau_spot + |lag|) * exp(-|lag| / tau_spot)

Parameters:: tau_spot (float) – Decay timescale [days].

property tau_spot: float#: Characteristic (scalar) timescale [days].

property lspot: float#: Spot plateau duration [days]. Default 0 (no plateau).

property param_dict: dict#

Envelope parameters as {name: value}.

Override this to expose envelope parameters to GPSolver and SpotEvolutionModel. The default returns an empty dict, which means the envelope shape is fixed (not inferred during GP fitting).

Gamma(t)[source]#

Normalized spot-size envelope evaluated at relative times t.

t = 0 is the center/peak of the envelope. Must return values in [0, 1] with a peak of 1. Should be JAX-compatible (jnp operations) so that it can be evaluated inside JIT-compiled code.

Gamma_hat(omega)[source]#: |FT[Gamma]| = 2*tau_spot / (1 + (omega*tau_spot)²) (Lorentzian).

Gamma_hat_sq(omega)[source]#

|FT[Gamma](omega)|² = Gamma_hat(omega)².

Default: interpolated from an FFT-based precomputed grid.

R_Gamma(lag)[source]#: R_Gamma(lag) = (tau_spot + |lag|) * exp(-|lag| / tau_spot).

kernel_support() → float[source]#

Upper bound on the lag support of R_Gamma [days].

Used by GPSolver to compute the banded-Cholesky bandwidth. Default: lspot + 6 * tau_spot. Override for tighter bounds.

Gamma_integral() → float[source]#

Integral of the squared-size envelope: \(\int \Gamma(t)\,dt\).

Used by AnalyticMean to compute the expected flux deficit. Default: numerical quadrature from Gamma(t). Override with a closed-form expression for better accuracy.

sympy_Gamma()[source]#

Sympy expression for Gamma(t).

Override in subclasses that have a closed-form envelope. Returns None if no analytic expression is available.

sympy_Gamma_hat()[source]#

Sympy expression for Gamma_hat(omega) = FT[Gamma](omega).

Override in subclasses with a closed-form Fourier transform. Returns None if no analytic form is available.

sympy_R_Gamma()[source]#

Sympy expression for R_Gamma(tau) = integral Gamma(t) Gamma(t+tau) dt.

Override in subclasses with a closed-form autocorrelation. Returns None if no analytic form is available.

class spotgp.envelope.ExponentialAsymmetricEnvelope(tau_em: float, tau_dec: float)[source]#

Asymmetric exponential envelope with separate rise and decay timescales.

Gamma(t) = exp( t / tau_em) for t < 0 (emergence / rise) Gamma(t) = exp(-t / tau_dec) for t >= 0 (decay)

The spot emerges with timescale tau_em and decays with timescale tau_dec. There is no plateau (lspot = 0).

Analytical Fourier transform:

Gamma_hat(omega) = tau_em / (1 + (omega * tau_em)^2)

tau_dec / (1 + (omega * tau_dec)^2)

Parameters:

tau_em (float) – Emergence (rise) timescale [days].
tau_dec (float) – Decay timescale [days].

property tau_spot: float#

max of the two timescales.

Type:: Effective timescale

property lspot: float#: Spot plateau duration [days]. Default 0 (no plateau).

property param_dict: dict#

Envelope parameters as {name: value}.

Override this to expose envelope parameters to GPSolver and SpotEvolutionModel. The default returns an empty dict, which means the envelope shape is fixed (not inferred during GP fitting).

Gamma(t)[source]#

Normalized spot-size envelope evaluated at relative times t.

t = 0 is the center/peak of the envelope. Must return values in [0, 1] with a peak of 1. Should be JAX-compatible (jnp operations) so that it can be evaluated inside JIT-compiled code.

Gamma_hat(omega)[source]#: Sum of two Lorentzians (one per timescale).

kernel_support() → float[source]#

Upper bound on the lag support of R_Gamma [days].

Used by GPSolver to compute the banded-Cholesky bandwidth. Default: lspot + 6 * tau_spot. Override for tighter bounds.

Gamma_integral() → float[source]#

Integral of the squared-size envelope: \(\int \Gamma(t)\,dt\).

Used by AnalyticMean to compute the expected flux deficit. Default: numerical quadrature from Gamma(t). Override with a closed-form expression for better accuracy.

spotgp.envelope.compute_R_Gamma_numerical(envelope_func, tau_ref, n_grid=4096, extent=12.0)[source]#

Compute R_Gamma(lag) = ∫ Gamma(t) · Gamma(t + lag) dt via FFT.

Parameters:

envelope_func (callable) – f(t: np.ndarray) -> np.ndarray, the normalized envelope Gamma(t).
tau_ref (float) – Reference timescale [days] setting grid extent and resolution.
n_grid (int) – Number of time-grid points (default 4096).
extent (float) – Grid half-width in units of tau_ref (default 12.0).

Returns:

lag_grid (jnp.ndarray, shape (n_grid,))
R_Gamma_vals (jnp.ndarray, shape (n_grid,))

Latitude Distribution#

class spotgp.latitude.LatitudeDistributionFunction[source]#

Bases: object

Base class for starspot latitude distributions.

Defines the probability density p(phi) over stellar latitude phi and the latitude range over which spots are placed.

The default implementation is a uniform distribution over [-pi/2, pi/2]. To define a custom distribution, subclass this class and override __call__ and optionally lat_range.

Examples

Equatorial band (spots confined to |phi| < 30 deg):

>>> class EquatorialBand(LatitudeDistributionFunction):
...     @property
...     def lat_range(self):
...         return (-np.pi / 6, np.pi / 6)
...     def __call__(self, phi):
...         return 1.0

Gaussian centred on the equator:

>>> class GaussianLatitude(LatitudeDistributionFunction):
...     def __init__(self, sigma=np.pi / 6):
...         self.sigma = sigma
...     def __call__(self, phi):
...         return np.exp(-0.5 * (phi / self.sigma) ** 2)

property param_dict: dict#

none.

Type:: Free latitude parameters as {name: value}. Default

property param_keys: tuple#: Ordered parameter names for the theta vector.

property lat_range: tuple#: (min, max) latitude in radians.

sympy_pdf()[source]#

Return the sympy expression for the latitude PDF p(phi).

Subclasses should override this to provide their analytic form. The base implementation returns 1 (uniform distribution).

Returns:: Sympy expression for p(phi), or None if no analytic form exists.
Return type:: sympy.Expr or None

get_sympy(display=True, status=None)[source]#

Display the sympy expression for the latitude PDF p(phi).

Requires sympy (pip install sympy).

Parameters:

display (bool, optional) – If True (default), render equations as formatted LaTeX in a Jupyter notebook (via IPython.display) or print them as LaTeX strings in a plain terminal.
status (str or None, optional) – If provided, appended to the class name header in brackets, e.g. "default" renders as LatitudeDistributionFunction [default].

Returns:

{"pdf": expr_or_None}

Return type:

class spotgp.latitude.UniformDoubleHemisphereBand(min_lat_deg: float = 0.0, max_lat_deg: float = 90.0)[source]#

Bases: LatitudeDistributionFunction

Uniform distribution confined to min_lat < |phi| < max_lat.

property param_dict: dict#

none.

Type:: Free latitude parameters as {name: value}. Default

property lat_range: tuple#: (min, max) latitude in radians.

sympy_pdf()[source]#

Return the sympy expression for the latitude PDF p(phi).

Subclasses should override this to provide their analytic form. The base implementation returns 1 (uniform distribution).

Returns:: Sympy expression for p(phi), or None if no analytic form exists.
Return type:: sympy.Expr or None

Visibility Functions#

class spotgp.visibility.VisibilityFunction(peq: float, kappa: float, inc: float)[source]#

Bases: object

Stellar visibility function parameterized by rotation and inclination.

The visibility function V(phi, lon) describes the flux contribution from a spot at latitude phi as the star rotates. It is expanded in a Fourier series over rotation harmonics, with coefficients c_n(inc, phi).

Parameters:

peq (float) – Equatorial rotation period [days].
kappa (float) – Differential rotation shear (dimensionless).
inc (float) – Stellar inclination [radians].

property param_dict: dict#

value}.

Type:: Visibility parameters as {name

property param_keys: tuple#: Ordered parameter names.

omega0(phi)[source]#: Latitude-dependent rotation angular frequency [rad/day].

cn_squared(phi, n_harmonics: int = 3)[source]#

Squared Fourier coefficients |c_n|² at stellar latitude phi.

Returns:: cn_sq
Return type:: jnp.ndarray, shape (n_harmonics + 1,)

get_sympy(display=True, status=None)[source]#

Display the sympy expressions for the visibility function.

Renders or prints LaTeX for:

omega_0(phi): latitude-dependent rotation angular frequency.
a_0, a_1, theta_v: intermediate visibility geometry variables.
c_0, c_1: special-case Fourier coefficients.
c_n: general Fourier coefficient (n >= 2).

Intermediate symbols are introduced so each equation stays compact and human-readable.

Requires sympy (pip install sympy).

Parameters:

display (bool, optional) – If True (default), render equations as formatted LaTeX in a Jupyter notebook (via IPython.display) or print them as LaTeX strings in a plain terminal.
status (str or None, optional) – If provided, appended to the class name header in brackets, e.g. "user defined" renders as VisibilityFunction [user defined].

Returns:

``{“omega0”: expr, “a0”: expr, “a1”: expr,: ”theta_v”: expr, “c0”: expr, “c1”: expr, “cn”: expr}``

Return type: