Modeling Protocol

This module provides some infrastructure that makes it easy to implement abstract “models” to be used within the celerite framework. Many of the methods are probably more generally applicable but the implementation constraints can be simplified since we’re just concerned about supporting the needs of celerite.

The basic premise is that a Model is an object that has an ordered set of named parameters. These parameters are assumed to be continuous but they can have bounds. There is also the concept of an “active set” of parameters that are being varied in a fit procedure. The other parameters are “frozen” to a particular value. Frozen parameters can be “thawed” to be returned to the active set.

There isn’t a formal requirement for the “value” interface that a Model subclass should implement but in some cases, a model will be expected to implement a get_value method that returns the “value” of the model (this can mean many different things but we’ll motivate this with an example below) for the current setting of the parameters.

Since these models will be used in the context of Bayesian parameter estimation each model also implements a Model.log_prior() method that computes the log of the prior probability of the current setting of the model parameters.

The full interface is described in detail below and the tutorials demonstrate the basic usage of the protocol.

class celerite.modeling.Model(*args, **kwargs)

An abstract class implementing the skeleton of the modeling protocol

Initial parameter values can either be provided as arguments in the same order as parameter_names or by name as keyword arguments.

A minimal subclass of this would have the form:

class CustomModel(Model):
    parameter_names = ("parameter_1", "parameter_2")

    def get_value(self, x):
        return self.parameter_1 + self.parameter_2 + x

model = CustomModel(parameter_1=1.0, parameter_2=2.0)
# or...
model = CustomModel(1.0, 2.0)
Parameters:bounds (Optional[list or dict]) – Bounds can be given for each parameter setting their minimum and maximum allowed values. This parameter can either be a list (with length full_size) or a dict with named parameters. Any parameters that are omitted from the dict will be assumed to have no bounds. These bounds can be retrieved later using the celerite.Model.get_parameter_bounds() method and, by default, they are used in the celerite.Model.log_prior() method.
compute_gradient(*args, **kwargs)

Compute the “gradient” of the model for the current parameters

This method should be overloaded by subclasses to implement the actual functionality of the model. The output of this function should be an array where the first dimension is full_size.

freeze_all_parameters()

Freeze all parameters of the model

freeze_parameter(name)

Freeze a parameter by name

Parameters:name – The name of the parameter
full_size

The total number of parameters (including frozen parameters)

get_parameter(name)

Get a parameter value by name

Parameters:name – The name of the parameter
get_parameter_bounds(include_frozen=False)

Get a list of the parameter bounds

Parameters:include_frozen (Optional[bool]) – Should the frozen parameters be included in the returned value? (default: False)
get_parameter_dict(include_frozen=False)

Get an ordered dictionary of the parameters

Parameters:include_frozen (Optional[bool]) – Should the frozen parameters be included in the returned value? (default: False)
get_parameter_names(include_frozen=False)

Get a list of the parameter names

Parameters:include_frozen (Optional[bool]) – Should the frozen parameters be included in the returned value? (default: False)
get_parameter_vector(include_frozen=False)

Get an array of the parameter values in the correct order

Parameters:include_frozen (Optional[bool]) – Should the frozen parameters be included in the returned value? (default: False)
get_value(*args, **kwargs)

Compute the “value” of the model for the current parameters

This method should be overloaded by subclasses to implement the actual functionality of the model.

log_prior()

Compute the log prior probability of the current parameters

parameter_vector

An array of all parameters (including frozen parameters)

set_parameter(name, value)

Set a parameter value by name

Parameters:
  • name – The name of the parameter
  • value (float) – The new value for the parameter
set_parameter_vector(vector, include_frozen=False)

Set the parameter values to the given vector

Parameters:
  • vector (array[vector_size] or array[full_size]) – The target parameter vector. This must be in the same order as parameter_names and it should only include frozen parameters if include_frozen is True.
  • include_frozen (Optional[bool]) – Should the frozen parameters be included in the returned value? (default: False)
thaw_all_parameters()

Thaw all parameters of the model

thaw_parameter(name)

Thaw a parameter by name

Parameters:name – The name of the parameter
vector_size

The number of active (or unfrozen) parameters

class celerite.modeling.ModelSet(models)

An abstract wrapper for combining named Model objects

The parameter names of a composite model are prepended by the submodel name. For example:

model = ModelSet([
    ("model1", Model(par1=1.0, par2=2.0)),
    ("model2", Model(par3=3.0, par4=4.0)),
])
print(model.get_parameter_names())

will print

["model1:par1", "model1:par2", "model2:par3", "model2:par4"]
Parameters:models – This should be a list of the form: [("model1", Model(...)), ("model2", Model(...)), ...].
class celerite.modeling.ConstantModel(*args, **kwargs)

A simple concrete model with a single parameter value

Parameters:value (float) – The value of the model.