gwin.models.base module

Base class for models.

class gwin.models.base.BaseModel(variable_params, static_params=None, prior=None, sampling_transforms=None)

Bases: object

Base class for all models.

Given some model \(h\) with parameters \(\Theta\), Bayes Theorem states that the probability of observing parameter values \(\vartheta\) is:

\[p(\vartheta|h) = \frac{p(h|\vartheta) p(\vartheta)}{p(h)}.\]

Here:

• \(p(\vartheta|h)\) is the posterior probability;
• \(p(h|\vartheta)\) is the likelihood;
• \(p(\vartheta)\) is the prior;
• \(p(h)\) is the evidence.

This class defines properties and methods for evaluating the log likelihood, log prior, and log posteror. A set of parameter values is set using the update method. Calling the class’s log(likelihood|prior|posterior) properties will then evaluate the model at those parameter values.

Classes that inherit from this class must implement a _loglikelihood function that can be called by loglikelihood.

Parameters:

• variable_params ((tuple of) string(s)) – A tuple of parameter names that will be varied.
• static_params (dict, optional) – A dictionary of parameter names -> values to keep fixed.
• prior (callable, optional) – A callable class or function that computes the log of the prior. If None provided, will use _noprior, which returns 0 for all parameter values.
• sampling_params (list, optional) – Replace one or more of the variable_params with the given parameters for sampling.
• replace_parameters (list, optional) – The variable_params to replace with sampling parameters. Must be the same length as sampling_params.
• sampling_transforms (list, optional) – List of transforms to use to go between the variable_params and the sampling parameters. Required if sampling_params is not None.
• Properties –
• ---------- –
• logjacobian – Returns the log of the jacobian needed to go from the parameter space of the variable_params to the sampling params.
• logprior – Returns the log of the prior.
• loglikelihood – A function that returns the log of the likelihood function.
• logposterior – A function that returns the log of the posterior.
• loglr – A function that returns the log of the likelihood ratio.
• logplr – A function that returns the log of the prior-weighted likelihood ratio.

current_params

current_stats

Return the default_stats as a dict.

This does no computation. It only returns what has already been calculated. If a stat hasn’t been calculated, it will be returned as numpy.nan.

Returns:Dictionary of stat names -> current stat values. Return type:dict

default_stats

The stats that get_current_stats returns by default.

static extra_args_from_config(cp, section, skip_args=None, dtypes=None)

Gets any additional keyword in the given config file.

Parameters:

• cp (WorkflowConfigParser) – Config file parser to read.
• section (str) – The name of the section to read.
• skip_args (list of str, optional) – Names of arguments to skip.
• dtypes (dict, optional) – A dictionary of arguments -> data types. If an argument is found in the dict, it will be cast to the given datatype. Otherwise, the argument’s value will just be read from the config file (and thus be a string).

Returns:

Dictionary of keyword arguments read from the config file.

Return type:

dict

classmethod from_config(cp, **kwargs)

Initializes an instance of this class from the given config file.

Parameters:

• cp (WorkflowConfigParser) – Config file parser to read.
• **kwargs – All additional keyword arguments are passed to the class. Any provided keyword will over ride what is in the config file.

get_current_stats(names=None)

Return one or more of the current stats as a tuple.

This function does no computation. It only returns what has already been calculated. If a stat hasn’t been calculated, it will be returned as numpy.nan.

Parameters:names (list of str, optional) – Specify the names of the stats to retrieve. If None (the default), will return default_stats. Returns:The current values of the requested stats, as a tuple. The order of the stats is the same as the names. Return type:tuple

logjacobian

The log jacobian of the sampling transforms at the current postion.

If no sampling transforms were provided, will just return 0.

Parameters:**params – The keyword arguments should specify values for all of the variable args and all of the sampling args. Returns:The value of the jacobian. Return type:float

loglikelihood

The log likelihood at the current parameters.

This will initially try to return the current_stats.loglikelihood. If that raises an AttributeError, will call _loglikelihood` to calculate it and store it to current_stats.

logposterior

Returns the log of the posterior of the current parameter values.

The logprior is calculated first. If the logprior returns -inf (possibly indicating a non-physical point), then the loglikelihood is not called.

logprior

Returns the log prior at the current parameters.

name = None

static prior_from_config(cp, variable_params, prior_section, constraint_section)

Gets arguments and keyword arguments from a config file.

Parameters:

• cp (WorkflowConfigParser) – Config file parser to read.
• variable_params (list) – List of of model parameter names.
• prior_section (str) – Section to read prior(s) from.
• constraint_section (str) – Section to read constraint(s) from.

Returns:

The prior.

Return type:

pycbc.distributions.JointDistribution

prior_rvs(size=1, prior=None)

Returns random variates drawn from the prior.

If the sampling_params are different from the variable_params, the variates are transformed to the sampling_params parameter space before being returned.

Parameters:

• size (int, optional) – Number of random values to return for each parameter. Default is 1.
• prior (JointDistribution, optional) – Use the given prior to draw values rather than the saved prior.

Returns:

A field array of the random values.

Return type:

FieldArray

sampling_params

Returns the sampling parameters.

If sampling_transforms is None, this is the same as the variable_params.

static_params

Returns the model’s static arguments.

update(**params)

Updates the current parameter positions and resets stats.

If any sampling transforms are specified, they are applied to the params before being stored.

variable_params

Returns the model parameters.

class gwin.models.base.ModelStats

Bases: object

Class to hold model’s current stat values.

getstats(names, default=nan)

Get the requested stats as a tuple.

If a requested stat is not an attribute (implying it hasn’t been stored), then the default value is returned for that stat.

Parameters:

• names (list of str) – The names of the stats to get.
• default (float, optional) – What to return if a requested stat is not an attribute of self. Default is numpy.nan.

Returns:

A tuple of the requested stats.

Return type:

tuple

getstatsdict(names, default=nan)

Get the requested stats as a dictionary.

If a requested stat is not an attribute (implying it hasn’t been stored), then the default value is returned for that stat.

Parameters:

• names (list of str) – The names of the stats to get.
• default (float, optional) – What to return if a requested stat is not an attribute of self. Default is numpy.nan.

Returns:

A dictionary of the requested stats.

Return type:

dict

statnames

Returns the names of the stats that have been stored.

class gwin.models.base.SamplingTransforms(variable_params, sampling_params, replace_parameters, sampling_transforms)

Bases: object

Provides methods for transforming between sampling parameter space and model parameter space.

apply(samples, inverse=False)

Applies the sampling transforms to the given samples.

Parameters:

• samples (dict or FieldArray) – The samples to apply the transforms to.
• inverse (bool, optional) – Whether to apply the inverse transforms (i.e., go from the sampling args to the variable_params). Default is False.

Returns:

The transformed samples, along with the original samples.

Return type:

dict or FieldArray

classmethod from_config(cp, variable_params)

Gets sampling transforms specified in a config file.

Sampling parameters and the parameters they replace are read from the sampling_params section, if it exists. Sampling transforms are read from the sampling_transforms section(s), using transforms.read_transforms_from_config.

An AssertionError is raised if no sampling_params section exists in the config file.

Parameters:

• cp (WorkflowConfigParser) – Config file parser to read.
• variable_params (list) – List of parameter names of the original variable params.

Returns:

A sampling transforms class.

Return type:

SamplingTransforms

logjacobian(**params)

Returns the log of the jacobian needed to transform pdfs in the variable_params parameter space to the sampling_params parameter space.

Let \(\mathbf{x}\) be the set of variable parameters, \(\mathbf{y} = f(\mathbf{x})\) the set of sampling parameters, and \(p_x(\mathbf{x})\) a probability density function defined over \(\mathbf{x}\). The corresponding pdf in \(\mathbf{y}\) is then:

\[p_y(\mathbf{y}) = p_x(\mathbf{x})\left|\mathrm{det}\,\mathbf{J}_{ij}\right|,\]

where \(\mathbf{J}_{ij}\) is the Jacobian of the inverse transform \(\mathbf{x} = g(\mathbf{y})\). This has elements:

\[\mathbf{J}_{ij} = \frac{\partial g_i}{\partial{y_j}}\]

This function returns \(\log \left|\mathrm{det}\,\mathbf{J}_{ij}\right|\).

Parameters:**params – The keyword arguments should specify values for all of the variable args and all of the sampling args. Returns:The value of the jacobian. Return type:float

gwin.models.base.read_sampling_params_from_config(cp, section_group=None, section='sampling_params')

Reads sampling parameters from the given config file.

Parameters are read from the [({section_group}_){section}] section. The options should list the variable args to transform; the parameters they point to should list the parameters they are to be transformed to for sampling. If a multiple parameters are transformed together, they should be comma separated. Example:

[sampling_params]
mass1, mass2 = mchirp, logitq
spin1_a = logitspin1_a

Note that only the final sampling parameters should be listed, even if multiple intermediate transforms are needed. (In the above example, a transform is needed to go from mass1, mass2 to mchirp, q, then another one needed to go from q to logitq.) These transforms should be specified in separate sections; see transforms.read_transforms_from_config for details.

Parameters:

• cp (WorkflowConfigParser) – An open config parser to read from.
• section_group (str, optional) – Append {section_group}_ to the section name. Default is None.
• section (str, optional) – The name of the section. Default is ‘sampling_params’.

Returns:

• sampling_params (list) – The list of sampling parameters to use instead.
• replaced_params (list) – The list of variable args to replace in the sampler.