Skip to content

kima API

Most analyses will use the RVData class to load RV data from a set of files or arrays

Example:

from kima import RVData

data = RVData('filename.txt', skip=1)
kima.RVData API

Load and store RV data

M0_epoch: float property

reference epoch for the mean anomaly

N: int property

Total number of observations

actind: list[list[float]] property

Activity indicators

instrument: str property

instrument name

multi: bool property

Data comes from multiple instruments

obsi: list[int] property

The instrument identifier

sig: list[float] property

The observed RV uncertainties

skip: int property

Lines skipped when reading data

t: list[float] property

The times of observations

units: str property

Units of the RVs and uncertainties

y: list[float] property

The observed radial velocities

get_RV_span() -> float method descriptor

get_RV_span(self) -> float

get_timespan() -> float method descriptor

get_timespan(self) -> float

load() -> None method descriptor

load(self, filename: str, units: str, skip: int, max_rows: int, delimiter: str, indicators: list[str]) -> None

Load RV data from a tab/space separated file with columns

time  vrad  error  quant  error
...   ...   ...    ...    ...
Args: filename (str): the name of the file untis (str): units of the RVs and errors, either "kms" or "ms" skip (int): number of lines to skip in the beginning of the file (default = 2) indicators (list[str]): nodoc

topslope() -> float method descriptor

topslope(self) -> float

and then define one of the several models currently implemented

Example:

from kima import RVmodel

model = RVmodel(fix=False, npmax=2, data=data)
kima.RVmodel API
RVmodel()

init(self, fix: bool, npmax: int, data: kima.Data.RVData) -> None

Implements a sum-of-Keplerians model where the number of Keplerians can be free.

Args: fix (bool): whether the number of Keplerians should be fixed npmax (int): maximum number of Keplerians data (RVData): the RV data

Cprior: kima.distributions.Distribution property

Prior for the systemic velocity

Jprior: kima.distributions.Distribution property

Prior for the extra white noise (jitter)

KO_Kprior: list[kima.distributions.Distribution] property

Prior for KO semi-amplitude

KO_Pprior: list[kima.distributions.Distribution] property

Prior for KO orbital period

KO_eprior: list[kima.distributions.Distribution] property

Prior for KO eccentricity

KO_phiprior: list[kima.distributions.Distribution] property

Prior for KO mean anomaly(ies)

KO_wprior: list[kima.distributions.Distribution] property

Prior for KO argument of periastron

TR_Kprior: list[kima.distributions.Distribution] property

Prior for TR semi-amplitude

TR_Pprior: list[kima.distributions.Distribution] property

Prior for TR orbital period

TR_Tcprior: list[kima.distributions.Distribution] property

Prior for TR mean anomaly(ies)

TR_eprior: list[kima.distributions.Distribution] property

Prior for TR eccentricity

TR_wprior: list[kima.distributions.Distribution] property

Prior for TR argument of periastron

beta_prior: kima.distributions.Distribution property

(Common) prior for the activity indicator coefficients

conditional: kima.RVmodel.RVConditionalPrior property

(self) -> kima.RVmodel.RVConditionalPrior

cubic_prior: kima.distributions.Distribution property

Prior for the cubic coefficient of the trend

data: kima.Data.RVData property

the data

degree: int property

degree of the polynomial trend

enforce_stability: bool property

whether to enforce AMD-stability

fix: bool property

whether the number of Keplerians is fixed

indicator_correlations: bool property

include in the model linear correlations with indicators

individual_offset_prior: list[kima.distributions.Distribution] property

Common prior for the between-instrument offsets

known_object: bool property

whether the model includes (better) known extra Keplerian curve(s)

n_known_object: int property

how many known objects

n_transiting_planet: int property

how many transiting planets

npmax: int property

maximum number of Keplerians

nu_prior: kima.distributions.Distribution property

Prior for the degrees of freedom of the Student-t likelihood

offsets_prior: kima.distributions.Distribution property

Common prior for the between-instrument offsets

quadr_prior: kima.distributions.Distribution property

Prior for the quadratic coefficient of the trend

slope_prior: kima.distributions.Distribution property

Prior for the slope

star_mass: float property

stellar mass [Msun]

stellar_jitter_prior: kima.distributions.Distribution property

Prior for the stellar jitter (common to all instruments)

studentt: bool property

use a Student-t distribution for the likelihood (instead of Gaussian)

transiting_planet: bool property

whether the model includes transiting planet(s)

trend: bool property

whether the model includes a polynomial trend

set_known_object() method descriptor

set_known_object(self, arg: int, /) -> None

set_transiting_planet() method descriptor

set_transiting_planet(self, arg: int, /) -> None

kima.GPmodel API
GPmodel

None

Cprior: kima.distributions.Distribution property

Prior for the systemic velocity

Jprior: kima.distributions.Distribution property

Prior for the extra white noise (jitter)

KO_Kprior: list[kima.distributions.Distribution] property

Prior for KO semi-amplitude

KO_Pprior: list[kima.distributions.Distribution] property

Prior for KO orbital period

KO_eprior: list[kima.distributions.Distribution] property

Prior for KO eccentricity

KO_phiprior: list[kima.distributions.Distribution] property

Prior for KO mean anomaly(ies)

KO_wprior: list[kima.distributions.Distribution] property

Prior for KO argument of periastron

beta_prior: kima.distributions.Distribution property

(Common) prior for the activity indicator coefficients

conditional: kima.RVmodel.RVConditionalPrior property

(self) -> kima.RVmodel.RVConditionalPrior

cubic_prior: kima.distributions.Distribution property

Prior for the cubic coefficient of the trend

degree: int property

degree of the polynomial trend

enforce_stability: bool property

whether to enforce AMD-stability

eta1_prior: kima.distributions.Distribution property

Prior for η1, the GP 'amplitude'

eta2_prior: kima.distributions.Distribution property

Prior for η2, the GP correlation timescale

eta3_prior: kima.distributions.Distribution property

Prior for η3, the GP period

eta4_prior: kima.distributions.Distribution property

Prior for η4, the recurrence timescale or (inverse) harmonic complexity

indicator_correlations: bool property

include in the model linear correlations with indicators

individual_offset_prior: list[kima.distributions.Distribution] property

Common prior for the between-instrument offsets

known_object: bool property

whether the model includes (better) known extra Keplerian curve(s)

n_known_object: int property

how many known objects

n_transiting_planet: int property

how many transiting planets

offsets_prior: kima.distributions.Distribution property

Common prior for the between-instrument offsets

quadr_prior: kima.distributions.Distribution property

Prior for the quadratic coefficient of the trend

slope_prior: kima.distributions.Distribution property

Prior for the slope

star_mass: float property

stellar mass [Msun]

transiting_planet: bool property

whether the model includes transiting planet(s)

trend: bool property

whether the model includes a polynomial trend

set_known_object() method descriptor

set_known_object(self, arg: int, /) -> None

set_transiting_planet() method descriptor

set_transiting_planet(self, arg: int, /) -> None

kima.RVFWHMmodel API
RVFWHMmodel

None

Cprior: kima.distributions.Distribution property

Prior for the systemic velocity

Jprior: kima.distributions.Distribution property

Prior for the extra white noise (jitter)

KO_Kprior: list[kima.distributions.Distribution] property

Prior for KO semi-amplitude

KO_Pprior: list[kima.distributions.Distribution] property

Prior for KO orbital period

KO_eprior: list[kima.distributions.Distribution] property

Prior for KO eccentricity

KO_phiprior: list[kima.distributions.Distribution] property

Prior for KO mean anomaly(ies)

KO_wprior: list[kima.distributions.Distribution] property

Prior for KO argument of periastron

conditional: kima.RVmodel.RVConditionalPrior property

(self) -> kima.RVmodel.RVConditionalPrior

cubic_prior: kima.distributions.Distribution property

Prior for the cubic coefficient of the trend

degree: int property

degree of the polynomial trend

enforce_stability: bool property

whether to enforce AMD-stability

eta1_fwhm_prior: kima.distributions.Distribution property

Prior for the GP 'amplitude' on the FWHM

eta1_prior: kima.distributions.Distribution property

Prior for the GP 'amplitude' on the RVs

eta2_fwhm_prior: kima.distributions.Distribution property

Prior for η2, the GP correlation timescale, on the FWHM

eta2_prior: kima.distributions.Distribution property

Prior for η2, the GP correlation timescale, on the RVs

eta3_fwhm_prior: kima.distributions.Distribution property

Prior for η3, the GP period, on the FWHM

eta3_prior: kima.distributions.Distribution property

Prior for η3, the GP period, on the RVs

eta4_fwhm_prior: kima.distributions.Distribution property

Prior for η4, the recurrence timescale or (inverse) harmonic complexity, on the FWHM

eta4_prior: kima.distributions.Distribution property

Prior for η4, the recurrence timescale or (inverse) harmonic complexity, on the RVs

known_object: bool property

whether the model includes (better) known extra Keplerian curve(s)

n_known_object: int property

how many known objects

quadr_prior: kima.distributions.Distribution property

Prior for the quadratic coefficient of the trend

share_eta2: bool property

whether the η2 parameter is shared between RVs and FWHM

share_eta3: bool property

whether the η3 parameter is shared between RVs and FWHM

share_eta4: bool property

whether the η4 parameter is shared between RVs and FWHM

slope_prior: kima.distributions.Distribution property

Prior for the slope

star_mass: float property

stellar mass [Msun]

trend: bool property

whether the model includes a polynomial trend

set_known_object() method descriptor

set_known_object(self, arg: int, /) -> None

kima.BINARIESmodel API
BINARIESmodel
Cprior property

Prior for the systemic velocity

Jprior property

Prior for the extra white noise (jitter)

KO_Kprior property

(self) -> list[DNest4::ContinuousDistribution]

KO_Pprior property

(self) -> list[DNest4::ContinuousDistribution]

KO_eprior property

(self) -> list[DNest4::ContinuousDistribution]

KO_phiprior property

(self) -> list[DNest4::ContinuousDistribution]

KO_qprior property

(self) -> list[DNest4::ContinuousDistribution]

KO_wdotprior property

(self) -> list[DNest4::ContinuousDistribution]

KO_wprior property

(self) -> list[DNest4::ContinuousDistribution]

binary_mass property

secondary mass [Msun]

binary_radius property

secondary radius [Rsun]

conditional property

(self) -> kima.RVmodel.RVConditionalPrior

cubic_prior property

Prior for the cubic coefficient of the trend

degree property

degree of the polynomial trend

double_lined property

whether the data is for a double lined binary, and has two sets of RVs for each epoch

enforce_stability property

whether to enforce AMD-stability

known_object property

whether to include (better) known extra Keplerian curve(s), should be true for BINARIESmodel

n_known_object property

how many known objects, should be >=1 for BINARIESmodel

nu_prior property

Prior for the degrees of freedom of the Student-t likelihood

offsets_prior property

Common prior for the between-instrument offsets

quadr_prior property

Prior for the quadratic coefficient of the trend

relativistic_correction property

whether to perform the GR correction

slope_prior property

Prior for the slope

star_mass property

primary mass [Msun]

star_radius property

primary radius [Rsun]

studentt property

use a Student-t distribution for the likelihood (instead of Gaussian)

tidal_correction property

whether to perform the tidal correction

trend property

whether the model includes a polynomial trend

To run the sampler and estimate the posterior for the model parameters just call kima.run

Example:

import kima

kima.run(model, steps=1000, num_threads=4)
kima.run API

Run the DNest4 sampler with the given model

Parameters:

Name Type Description Default
m (RVmodel, GPmodel, ...)

The model

required
steps int

How many steps to run. Default is 100.

required
num_threads int

How many threads to use for parallel processing. Default is 1.

required
num_particles int

Number of MCMC particles. Default is 1.

required
new_level_interval int

Number of steps required to create a new level. Default is 2000.

required
save_interval int

Number of steps between saves. Default is 100.

required
thread_steps int

Number of independent steps on each thread. Default is 10.

required
max_num_levels int

Maximum number of levels, or 0 if it should be determined automatically. Default is 0.

required
lambda_ int

DOC. Default is 10.0

required
beta int

DOC. Default is 100.0,

required
compression int

DOC. Default is exp(1.0)

required
seed int

Random number seed value, or 0 to use current time. Default is 0.

required
print_thin int

Thinning steps for terminal output. Default is 50.

required

The distributions sub-package contains the implementation of several probability distributions that can be used as priors for a model parameter. All distributions have standard parameterizations, as you would find e.g. in Wikipedia. Some distributions have a corresponding Truncated version which truncates the support of the distribution to an interval $ [{\rm lower}, {\rm upper} ]$.

Example:

from kima import distributions

parameter_prior = distributions.Gaussian(10, 1)
kima.distributions API

Cauchy

Bases: kima.distributions.Distribution

Cauchy distribution

loc: float property

(self) -> float

scale: float property

(self) -> float

cdf() method descriptor

cdf(self, x: float) -> float

Cumulative distribution function evaluated at x

logpdf() method descriptor

logpdf(self, x: float) -> float

Log of the probability density function evaluated at x

ppf() method descriptor

ppf(self, q: float) -> float

Percent point function (inverse of cdf) evaluated at q

Exponential

Bases: kima.distributions.Distribution

Exponential distribution

cdf() method descriptor

cdf(self, x: float) -> float

Cumulative distribution function evaluated at x

logpdf() method descriptor

logpdf(self, x: float) -> float

Log of the probability density function evaluated at x

ppf() method descriptor

ppf(self, q: float) -> float

Percent point function (inverse of cdf) evaluated at q

Fixed

Bases: kima.distributions.Distribution

'Fixed' distribution

val: float property

(self) -> float

cdf() method descriptor

cdf(self, x: float) -> float

Cumulative distribution function evaluated at x

logpdf() method descriptor

logpdf(self, x: float) -> float

Log of the probability density function evaluated at x

ppf() method descriptor

ppf(self, q: float) -> float

Percent point function (inverse of cdf) evaluated at q

Gaussian

Bases: kima.distributions.Distribution

Gaussian distribution

loc: float property

(self) -> float

scale: float property

(self) -> float

cdf() method descriptor

cdf(self, x: float) -> float

Cumulative distribution function evaluated at x

logpdf() method descriptor

logpdf(self, x: float) -> float

Log of the probability density function evaluated at x

ppf() method descriptor

ppf(self, q: float) -> float

Percent point function (inverse of cdf) evaluated at q

Kumaraswamy

Bases: kima.distributions.Distribution

Kumaraswamy distribution (similar to a Beta distribution)

a: float property

(self) -> float

b: float property

(self) -> float

cdf() method descriptor

cdf(self, x: float) -> float

Cumulative distribution function evaluated at x

logpdf() method descriptor

logpdf(self, x: float) -> float

Log of the probability density function evaluated at x

ppf() method descriptor

ppf(self, q: float) -> float

Percent point function (inverse of cdf) evaluated at q

Laplace

Bases: kima.distributions.Distribution

Laplace distribution

loc: float property

(self) -> float

scale: float property

(self) -> float

cdf() method descriptor

cdf(self, x: float) -> float

Cumulative distribution function evaluated at x

logpdf() method descriptor

logpdf(self, x: float) -> float

Log of the probability density function evaluated at x

ppf() method descriptor

ppf(self, q: float) -> float

Percent point function (inverse of cdf) evaluated at q

LogUniform

Bases: kima.distributions.Distribution

LogUniform distribution (sometimes called reciprocal or Jeffrey's distribution)

lower: float property

(self) -> float

upper: float property

(self) -> float

cdf() method descriptor

cdf(self, x: float) -> float

Cumulative distribution function evaluated at x

logpdf() method descriptor

logpdf(self, x: float) -> float

Log of the probability density function evaluated at x

ppf() method descriptor

ppf(self, q: float) -> float

Percent point function (inverse of cdf) evaluated at q

ModifiedLogUniform

Bases: kima.distributions.Distribution

ModifiedLogUniform distribution

knee: float property

(self) -> float

upper: float property

(self) -> float

cdf() method descriptor

cdf(self, x: float) -> float

Cumulative distribution function evaluated at x

logpdf() method descriptor

logpdf(self, x: float) -> float

Log of the probability density function evaluated at x

ppf() method descriptor

ppf(self, q: float) -> float

Percent point function (inverse of cdf) evaluated at q

RNG

None

rand() method descriptor

rand(self) -> float

rand_int() method descriptor

rand_int(self, arg: int, /) -> int

Rayleigh

Bases: kima.distributions.Distribution

Rayleigh distribution

scale: float property

(self) -> float

cdf() method descriptor

cdf(self, x: float) -> float

Cumulative distribution function evaluated at x

logpdf() method descriptor

logpdf(self, x: float) -> float

Log of the probability density function evaluated at x

ppf() method descriptor

ppf(self, q: float) -> float

Percent point function (inverse of cdf) evaluated at q

Triangular

Bases: kima.distributions.Distribution

Triangular distribution

center: float property

(self) -> float

lower: float property

(self) -> float

upper: float property

(self) -> float

cdf() method descriptor

cdf(self, x: float) -> float

Cumulative distribution function evaluated at x

logpdf() method descriptor

logpdf(self, x: float) -> float

Log of the probability density function evaluated at x

ppf() method descriptor

ppf(self, q: float) -> float

Percent point function (inverse of cdf) evaluated at q

TruncatedCauchy

Bases: kima.distributions.Distribution

docs

loc: float property

(self) -> float

lower: float property

(self) -> float

scale: float property

(self) -> float

upper: float property

(self) -> float

cdf() method descriptor

cdf(self, x: float) -> float

Cumulative distribution function evaluated at x

logpdf() method descriptor

logpdf(self, x: float) -> float

Log of the probability density function evaluated at x

ppf() method descriptor

ppf(self, q: float) -> float

Percent point function (inverse of cdf) evaluated at q

TruncatedExponential

Bases: kima.distributions.Distribution

Exponential distribution truncated to [lower, upper]

lower: float property

(self) -> float

scale: float property

(self) -> float

upper: float property

(self) -> float

cdf() method descriptor

cdf(self, x: float) -> float

Cumulative distribution function evaluated at x

logpdf() method descriptor

logpdf(self, x: float) -> float

Log of the probability density function evaluated at x

ppf() method descriptor

ppf(self, q: float) -> float

Percent point function (inverse of cdf) evaluated at q

TruncatedRayleigh

Bases: kima.distributions.Distribution

Rayleigh distribution truncated to [lower, upper]

lower: float property

(self) -> float

scale: float property

(self) -> float

upper: float property

(self) -> float

cdf() method descriptor

cdf(self, x: float) -> float

Cumulative distribution function evaluated at x

logpdf() method descriptor

logpdf(self, x: float) -> float

Log of the probability density function evaluated at x

ppf() method descriptor

ppf(self, q: float) -> float

Percent point function (inverse of cdf) evaluated at q

Uniform

Bases: kima.distributions.Distribution

Uniform distribuion in [lower, upper]

lower: float property

(self) -> float

upper: float property

(self) -> float

cdf() method descriptor

cdf(self, x: float) -> float

Cumulative distribution function evaluated at x

logpdf() method descriptor

logpdf(self, x: float) -> float

Log of the probability density function evaluated at x

ppf() method descriptor

ppf(self, q: float) -> float

Percent point function (inverse of cdf) evaluated at q

UniformAngle

Bases: kima.distributions.Distribution

Uniform distribuion in [0, 2*PI]

cdf() method descriptor

cdf(self, x: float) -> float

Cumulative distribution function evaluated at x

logpdf() method descriptor

logpdf(self, x: float) -> float

Log of the probability density function evaluated at x

ppf() method descriptor

ppf(self, q: float) -> float

Percent point function (inverse of cdf) evaluated at q

Finally, even though it sits at the core of what kima does, is the keplerian function:

kima.keplerian API

keplerian(t: list[float], P: float, K: float, ecc: float, w: float, M0: float, M0_epoch: float) -> list[float]

Calculate the Keplerian curve at times t

Parameters:

Name Type Description Default
t array

Times at which to calculate the Keplerian function

required
P float

Orbital period [days]

required
K float

Semi-amplitude

required
ecc float

Orbital eccentricity

required
w float

Argument of periastron [rad]

required
M0 float

Mean anomaly at the epoch [rad]

required
M0_epoch float

Reference epoch for the mean anomaly (M=0 at this time) [days]

required

Returns:

Name Type Description
v array

Keplerian function evaluated at input times t