profile_likelihood — Profile Likelihood documentation

# 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.

        - start_class (see `compute()`)

        - fit_class (see `compute()`)

    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.