profile_likelihood

profile_likelihood.profile_likelihood

Tools to compute and present the profile likelihood of a model.

class profile_likelihood.profile_likelihood(model, nparams: int, npred: int, param_names=None)

Bases: profile_likelihood.compute.Compute, profile_likelihood.plot.Plots

Compute and present profile likelihood.

Parameters
model: callable

Function that is used in the optimization. This can be the residuals (which is required if we use Levenberg-Marquardt algorithm) or just the cost function (which is needed for other algorithm, such as conjugate-gradient).

nparams: int

Number of parameters the model accepts.

npred: int

Number of predictions the model returns.

param_names: list of strings (optional)

List of name of the parameters of the model. This list is used as the dictionary keys and the labels on the profile likelihood plots. default: ['parameter0', 'parameter1', ....]

Attributes
model

Function which is used in the optimization.

nparams

Number of parameters.

npred

Number of predictions.

param_names

List of the names of the parameters in the model.

results

Results of the profile likelihood computation.

property best_results

The best results from self.results. This will be the same as self.results if only 1 initial guess is used. If the computation is done using multiple initial guesses, then this will get the best result (lowest cost) for each fixed parameter value.

compute(center, idx='all', points=None, bounds=[- 10, 10], dt=0.1, verbose=False, dumpfile=None, processes=1, ignore_error=False, **kwargs)

Run profile likelihood computation.

Parameters
center: {1D ndarray, 2D ndarray}

Points in parameter space where the computation uses as the center to create points in the profile likelihood computation, i.e. the computation will start with fixed parameter specified by the center, then move the fixed parameter to the left of the center, then to the right.

idx: {int, 1D ndarray,”all”}, optional

Index of the parameter to compute the profile likelihood. default: 'all', that is compute profile likelihood for all parameters.

points: {1D ndarray, 2D ndarray}, optional

Each element of this point will be used as the value of the fixed parameter. If a 1D ndarray is given, the profle likelihood computation for every idx will use the same list. Otherwise, the computation for every idx uses list from every row. If None, then linearly spaced points will be created using bounds, dt, and the best-fit parameter values. default: None

bounds: {1D ndarray, 2D ndarray}, optional

If 1D ndarray is given, then every parameter will have the same bounds. If 2D ndarray is given, every row gives the bounds of each parameter. default: [0, 10]

dt: {float, 1D ndarray}, optional

Spacing between points. If a scalar number is given, profile likelihood computation for each parameter uses the same spacing. If a 1D ndarray is given, each element of the array is used as spacing in the computation with its respective order. default: 0.1

verbose: bool, optional

An option to print out some information during computation to track the progress. Information printed:

name: "parameter's name",
fix: "fixed parameter's value"
error: "error code from the optimization routine"
cost: "cost value at the optimized parameters"

default: False

dumpfile: str, optional

If dumpfile is not None, the result of optimization on each point will be dumped into this file. This works like a backend to retrieve the computation results as it runs. The format of information dumped:

idx:{idx}; error:{error_code}; parameters:{parameters};
cost:{cost}
  • idx - Refering to index of parameter in of which the profile likelihood computation is performed

  • error_code - Error code returned by the optimization algorithm.

  • parameters - Optimized parameters from the optimization process, with the fixed parameter value placed in its correct position.

  • cost - Cost value evaluated at the optimized parameters.

default: None

processes: int, optional

Number of processes used in the computation. Each process computes profile likelihood for different parameter. This parameter will be useful if the model has many parameters. default: 1

ignore_error: bool, optional

A flag to ignore the error that happens during computation. If this is set to be True, then when some error happens the computation will still running, but the error message will be stored in the result dictionary for the parameter(s) of which the error occurs. Otherwise, the computation will terminate whenever an error occurs. default: False

**kwargs

Specify custom classes. See below for the classes available.

start_class: object, kwargs

Class object to handle the initial guesses of the optimization. As the default, there will be 1 initial guess, which is the previous optimized parameters. Requirements for user-define start_class:

  • Attributes: self.nguess - Number of different initial guess’.

  • Methods:

    • self.set_points_0() - Reset initial starting points to starting point. The profile likelihood computation will start from center then moves to the left, and then it will go back to the center and move to the right this time. This method is called when the computation move back to the center.

    • self.get_points() - Get initial guesses to use in the optimization.

    • self.update() - Update the next starting points.

default: None, which uses single_starting_point

fit_class: object, kwargs

Class object that contains the optimization routine. Requirements for user-define fit_class:

  • Attributes: self.nreturned - number of things returned by the by the fitting class. This is translated as the number of columns of the array to store the results temporarily. This will be used to create the matrix to store the results temporarily.

  • Methods:

    • self.optimize(residuals, initial_guess, idx, fixed_param) - This method contains the optimization routine to use.

    • self.callback(opt_output, fixed_param, idx) - Method to process raw results from fit_class.optimize (opt_output parameter) to match the format used by profile_likelihood class. This method returns a 1D array, with element 0 be error_code, elements 1 to n be opt_params, and element n+1 be cost. The array can have more element to return, if user wishes to return more information.

default: None, which uses fit_leastsq

Returns
results: python:dict

Dictionary of the results of the calculation. The format of the dictionary is

results = {"parameter0": {"error_code": error_code,
                          "parameters": opt_params,
                          "others": other_information,
                          "cost": cost_values},
           "parameter1": {...},
           ...}
property compute_info

Information of the compute method the user sets, which will show the list of fixed parameter values, number of initial guess, and the name and location of the start and fit classes.

property fit_info

Name and location of the class used to perform the optimization.

property fixed_params

List of values of the parameters that are set fixed.

load_results(filename, center, verbose=False, **kwargs)

Load self.results from the previously saved calculation. The arguments here are similar to self.compute. However, arguments bounds, dt, and points are not needed as the internal mechanism will load thosse information from the loaded results.

Parameters
filename: str

Path to the result file.

center: {1D ndarray, 2D ndarray}

Points in parameter space where the computation uses as the center to create points in the profile likelihood computation, i.e. the computation will start with fixed parameter specified by the center, then move the fixed parameter to the left of the center, then to the right.

verbose: bool, optional

Value of the verbose flag, which is an option to print out some information during computation to track the progress. This argument will be use if further calculation is to be done next.

**kwargs

Specifying custom classes to use.

Returns
results: python:dict

See profile_likelihood.compute().

property model_info

Name and location of the model class

property param_names

List of the names of the parameters in the model.

plot_paths(idx='all', bounds=None, xlabels='default', aspect='auto', pkwargs=None)

Plot profile likelihood paths. The paths are projected onto 2D planes in parameter space.

Parameters
idx: {“all”, 1d-array}, optional

Index of the parameters to plot. If “all” is given, then the paths for all parameters will be plotted. If an array of length 2 is given, the parameter correspond to the first element is plotted on the x-axis. It can receive an array with length > 2 as well. default: “all”

bounds: {1d-array, 2d-array}, optional

Upper and lower bounds of the plot for each parameter, stored in an N x 2 array. If a 1D array is given, the array will be copied to make a 2D array. If a 2D array is given, each row should correspond to different parameter, the first column contains the lower bounds and the second column the upper bounds. default: None

xlabels: {“default”, list of str}, optional

List of labels that will be written on the x axis on each plot. This list should have the same length as the number parameters in the model. default: “default”, which uses self.param_names

aspect: {“auto”, “equal”, float}, optional

An option to set the aspect ratio of the plots. It is the same as the aspect argument in matplotlib.axes.Axes.set_aspect. default: “auto”

pkwargs: dict {“x”: {}, “y”: {}}, optional

Optional Line2D properties to customize the profile likelihood paths. pkwargs["x"] contains properties to customize the path which has fixed parameter plotted on the horizontal axis, and similarly pkwargs["y"] is used for the other path. default: {“x”: {“ls”: “–”}, “y”: {}}

Returns
axes: python:list

Axes object of the plots.

plot_paths_and_profiles(idx='all', bounds=None, xlabels='default', cplabel='cost', cplim=None, cpscale='linear', aspect='auto', pkwargs=None, cpkwargs=None)

Plot both the paths and the cost profile. The paths will be plotted on the lower diagonal while the cost profile on the diagonal. It is pretty much combination of plot_paths() and plot_profiles().

For the parameters and what this returns, see plot_paths() and plot_profiles()

plot_profiles(idx='all', bounds=None, xlabels='default', cplabel='cost', cplim=None, cpscale='linear', aspect='auto', cpkwargs=None)

Plot cost profiles of the model, i.e. negative loglikelihoods. If plt.show() doesn’t show the plot, try to use other backend, like TkAgg, Qt5Agg, etc.

Parameters
idx: {“all”, 1d-array}, optional

Index of the parameters to plot. default: “all”, which will plot the cost profiles for all parameters.

bounds: {1d-array, 2d-array}, optional

Upper and lower bounds of the plot for each parameter, stored in an N x 2 array. If a 1D array is given, the array will be copied to make a 2D array. If a 2D array is given, each row should correspond to different parameter, the first column contains the lower bounds and the second column the upper bounds. default: None

xlabels: {“default”, list of str}, optional

List of labels that will be written on the x axis on each plot. This list should have the same length as the number parameters in the model. default: “default”, which uses self.param_names

cplabel: str, optional

String to write as the label of the vertical axis of the cost profile plot. default: “cost”

cplim: {None, 1d-array, 2d-array}, optional

List of upper bounds and lower bounds for each parameter, stored In an N x 2 array. Each row correspond to different parameter, column 1 contains the lower bounds, and column 2 the upper bounds. For now, the array needs to contain the bounds for the complete parameters. default: None

cpscale: {“linear”, “log”}, optional

Scaling to use in the y-axis of cost profile plots. Same yscale function in matplotlib.pyplot. default: “linear”

aspect: {“auto”, “equal”, float}, optional

An option to set the aspect ratio of the plots. It is the same as the aspect argument in matplotlib.axes.Axes.set_aspect. default: “auto”

cpkwargs: dict (optional)

Optional Line2D properties to customize the profile likelihood plots. default: {}

Returns
axes: python:list

Axes object of the plots.

print_error(parameter)

Print error message.

Parameters
parameter: str

Name of parameter requested.

save_best_results(filename)

Save self.best_results dictionary as a JSON file.

Parameters
filename: str

Path and filename destination to save self.best_results

save_results(filename)

Save self.results dictionary as a JSON file.

Parameters
filename: str

Path and filename destination to save self.results

property start_info

Name and location of the class used to choose starting points to the optimization.