spotter.kernels
===============

.. py:module:: spotter.kernels

.. autoapi-nested-parse::

   Gaussian process kernels and covariance utilities for stellar surfaces and fluxes.

   This module defines kernels for spatial correlations on the sphere, active latitude
   modulation, and flux time series, including marginalization over inclination.



Classes
-------

.. autoapisummary::

   spotter.kernels.GreatCircleDistance
   spotter.kernels.ActiveLatitude
   spotter.kernels.FluxKernel


Functions
---------

.. autoapisummary::

   spotter.kernels.norm_cov_series
   spotter.kernels.probability_inc


Module Contents
---------------

.. py:class:: GreatCircleDistance

   Bases: :py:obj:`tinygp.kernels.stationary.Distance`


   Compute the great-circle distance between two 3-vectors.


   .. py:method:: distance(X1, X2)

      Compute the great-circle distance between two unit vectors.

      :param X1: First unit vector.
      :type X1: array_like, shape (3,)
      :param X2: Second unit vector.
      :type X2: array_like, shape (3,)

      :returns: **d** -- Great-circle distance in radians.
      :rtype: float



.. py:class:: ActiveLatitude

   Bases: :py:obj:`tinygp.kernels.Kernel`


   Kernel describing the correlation between pixel values on a sphere,
   modulated by latitude.

   :param kernel: Base kernel.
   :type kernel: kernels.Kernel
   :param latitude: Latitude of activity band (radians).
   :type latitude: float
   :param sigma: Width of activity band.
   :type sigma: float
   :param symetric: If True, kernel is symmetric about the equator.
   :type symetric: bool, optional


   .. py:attribute:: kernel
      :type:  tinygp.kernels.Kernel


   .. py:attribute:: latitude
      :type:  jax.Array


   .. py:attribute:: sigma
      :type:  jax.Array


   .. py:attribute:: symetric
      :type:  bool
      :value: True



   .. py:method:: amplitude(X)

      Compute the amplitude modulation for a given pixel.

      :param X: Cartesian coordinates of pixel.
      :type X: array_like, shape (3,)

      :returns: **amp** -- Amplitude modulation factor.
      :rtype: float



   .. py:method:: evaluate(X1, X2)

      Evaluate the kernel between two pixels.

      :param X1: First pixel coordinates.
      :type X1: array_like, shape (3,)
      :param X2: Second pixel coordinates.
      :type X2: array_like, shape (3,)

      :returns: **value** -- Kernel value.
      :rtype: float



.. py:function:: norm_cov_series(mu, cov, N=10)

   Series approximation to the normalized covariance.

   This is stolen from starry_process

   :param mu: Mean value.
   :type mu: float
   :param cov: Covariance matrix.
   :type cov: ndarray
   :param N: Number of terms in the series.
   :type N: int, optional

   :returns: **norm_cov** -- Normalized covariance matrix.
   :rtype: ndarray


.. py:function:: probability_inc(inc)

   Probability density for inclination angle. Given spotter's convention,
   this is simply sin(inc)

   :param inc: Inclination angle(s) in radians.
   :type inc: float or ndarray

   :returns: **prob** -- Probability density.
   :rtype: float or ndarray


.. py:class:: FluxKernel

   Bases: :py:obj:`tinygp.kernels.Kernel`


   Kernel for the flux time series of a star, marginalizing over inclination.

   :param surface_kernel: Kernel on the stellar surface.
   :type surface_kernel: kernels.Kernel
   :param star: Star object.
   :type star: Star
   :param u: Limb darkening coefficients.
   :type u: array_like, optional
   :param inc: Inclination in radians.
   :type inc: float, optional
   :param order: Number of quadrature points for inclination marginalization.
   :type order: int, optional
   :param normalize: Whether to normalize the covariance.
   :type normalize: bool, optional


   .. py:attribute:: surface_kernel
      :type:  tinygp.kernels.Kernel


   .. py:attribute:: star
      :type:  spotter.Star


   .. py:attribute:: u
      :type:  jax.Array
      :value: None



   .. py:attribute:: inc
      :type:  jax.Array
      :value: None



   .. py:attribute:: order
      :type:  int
      :value: 30



   .. py:attribute:: normalize
      :type:  bool
      :value: True



   .. py:method:: __post_init__()

      Initialize the kernel by precomputing the surface covariance.



   .. py:method:: X(time, i)

      Compute the design matrix for given time and inclination.

      :param time: Time in days.
      :type time: float
      :param i: Inclination in radians.
      :type i: float

      :returns: **X** -- Design matrix.
      :rtype: ndarray



   .. py:method:: eval(X2, X1, inc)

      Evaluate the kernel for given times and inclination.

      :param X2: Second time.
      :type X2: float
      :param X1: First time.
      :type X1: float
      :param inc: Inclination in radians.
      :type inc: float

      :returns: **value** -- Kernel value.
      :rtype: float



   .. py:method:: evaluate(X1, X2)

      Evaluate the kernel, marginalizing over inclination if needed.

      :param X1: First time.
      :type X1: float
      :param X2: Second time.
      :type X2: float

      :returns: **value** -- Kernel value.
      :rtype: float



   .. py:method:: __call__(X1, X2=None)

      Call the kernel, optionally normalizing the covariance.

      :param X1: First time.
      :type X1: float
      :param X2: Second time.
      :type X2: float, optional

      :returns: **value** -- Kernel value or covariance matrix.
      :rtype: float