means.inference package

Submodules

Distances

This part of the package implements functions to compute distance between two set of trajectories. Distance functions are typically required for parameter inference (see means.inference.inference).

means.inference.distances.gamma(simulated_trajectories, observed_trajectories_lookup)

Returns the negative log-likelihood of the observed trajectories assuming a gamma distribution on the simulated trajectories values

Parameters:

• simulated_trajectories (list[means.simulation.Trajectory]) – Simulated trajectories
• observed_trajectories_lookup (dict) – A dictionary of (trajectory.description: trajectory) of observed trajectories

Returns:

means.inference.distances.get_distance_function(distance)

Returns the distance function from the string name provided

Parameters:distance – The string name of the distributions Returns:

means.inference.distances.lognormal(simulated_trajectories, observed_trajectories_lookup)

Returns the negative log-likelihood of the observed trajectories assuming a log-normal distribution

on the simulated trajectories values

Parameters:

• simulated_trajectories (list[means.simulation.Trajectory]) – Simulated trajectories
• observed_trajectories_lookup (dict) – A dictionary of (trajectory.description: trajectory) of observed trajectories

Returns:

means.inference.distances.normal(simulated_trajectories, observed_trajectories_lookup)

Returns the negative log-likelihood of the observed trajectories assuming a normal distribution

on the simulated trajectories values

Parameters:

• simulated_trajectories (list[means.simulation.Trajectory]) – Simulated trajectories
• observed_trajectories_lookup (dict) – A dictionary of (trajectory.description: trajectory) of observed trajectories

Returns:

means.inference.distances.sum_of_squares(simulated_trajectories, observed_trajectories_lookup)

Returns the sum-of-squares distance between the simulated_trajectories and observed_trajectories

Parameters:

• simulated_trajectories (list[means.simulation.Trajectory]) – Simulated trajectories
• observed_trajectories_lookup (dict) – A dictionary of (trajectory.description: trajectory) of observed trajectories

Returns:

the distance between simulated and observed trajectories

Return type:

float

means.inference.hypercube.hypercube(number_of_samples, variables)

This implements Latin Hypercube Sampling.

See https://mathieu.fenniak.net/latin-hypercube-sampling/ for intuitive explanation of what it is

Parameters:

• number_of_samples – number of segments/samples
• variables – initial parameters and conditions (list of ranges, i.e. (70, 110), (0.1, 0.5) ..)

Returns:

class means.inference.inference.Inference(problem, starting_parameters, starting_conditions, variable_parameters, observed_trajectories, distance_function_type='sum_of_squares', **simulation_kwargs)

Bases: means.io.serialise.SerialisableObject, means.util.memoisation.MemoisableObject

Parameters:

• problem (ODEProblem) – ODEProblem to infer data for
• starting_parameters (iterable) – A list of starting values for each of the model’s parameters
• starting_conditions (iterable) – A list of starting values for each of the initial conditions. All unspecified initial conditions will be set to zero
• variable_parameters – A dictionary of variable parameters, in the format {parameter_symbol: (min_value, max_value)} where the range (min_value, max_value) is the range of the allowed parameter values. If the range is None, parameters are assumed to be unbounded.
• observed_trajectories – A list of Trajectory objects containing observed data values.
• distance_function_type –

  Method of calculating the data fit. Currently supported values are ‘sum_of_squares’

  minimisation of the sum of squares distance between trajectories

  ‘gamma’

  maximum likelihood optimisation assuming gamma distribution

  ‘normal’

  maximum likelihood optimisation assuming normal distribution

  ‘lognormal’

  maximum likelihood optimisation assuming lognormal distribution

• simulation_kwargs – Keyword arguments to pass to the means.simulation.Simulation instance

constraints

distance_function_type

infer(return_intermediate_solutions=False, return_distance_landscape=False, solver_exceptions_limit=100)

Parameters:

• return_intermediate_solutions – Return the intermediate parameter solutions that optimisation
• return_distance_landscape – Return the distance landscape that was explored

observed_timepoints

observed_trajectories

observed_trajectories_lookup

Similar to observed_trajectories, but returns a dictionary of {description:trajectory}

problem

Return type:ODEProblem

simulation

simulation_kwargs

starting_conditions

starting_conditions_with_variability

starting_parameters

starting_parameters_with_variability

classmethod to_yaml(dumper, data)

variable_parameters

yaml_tag = '!inference'

class means.inference.inference.InferenceWithRestarts(problem, number_of_samples, starting_parameter_ranges, starting_conditions_ranges, variable_parameters, observed_trajectories, distance_function_type='sum_of_squares')

Bases: means.util.memoisation.MemoisableObject

Parameter Inference Method that utilises multiple seed points for the optimisation.

Parameters:

• problem (ODEProblem) – Problem to infer parameters for
• number_of_samples – Number of the starting points to randomly pick
• starting_parameter_ranges – Valid initialisation ranges for the parameters
• starting_conditions_ranges – Valid initialisation ranges for the initial conditions. If some initial conditions are not set, they will default to 0.
• variable_parameters – A dictionary of variable parameters, in the format {parameter_symbol: (min_value, max_value)} where the range (min_value, max_value) is the range of the allowed parameter values. If the range is None, parameters are assumed to be unbounded.
• observed_trajectories – A list of Trajectory objects containing observed data values.
• distance_function_type –

  Method of calculating the data fit. Currently supported values are - ‘sum_of_squares’ - min sum of squares optimisation - ‘gamma’ - maximum likelihood optimisation assuming gamma distribution - ‘normal’- maximum likelihood optimisation assuming normal distribution - ‘lognormal’ - maximum likelihood optimisation assuming lognormal distribution - any callable function, that takes two arguments: simulated trajectories (list)

  and observed trajectories lookup (dictionary of description: trajectory pairs) see means.inference.distances.sum_of_squares() for examples of such functions

distance_function_type

infer(number_of_processes=1, *args, **kwargs)

Parameters:

• number_of_processes – If set to more than 1, the inference routines will be paralellised using multiprocessing module
• args – arguments to pass to Inference.infer()
• kwargs – keyword arguments to pass to Inference.infer()

Returns:

number_of_samples

observed_trajectories

problem

Return type:ODEProblem

starting_conditions_ranges

starting_parameter_ranges

variable_parameters

Parameter Inference Parallelisation

This part of the package provides helper functions to make parameter inference run in parallel.

means.inference.parallelisation.multiprocessing_apply_infer(object_id)

Used in the InferenceWithRestarts class. Needs to be in global scope for multiprocessing module to pick it up

means.inference.parallelisation.multiprocessing_pool_initialiser(objects, infer_args, infer_kwargs)

means.inference.parallelisation.raw_results_in_parallel(inference_objects, number_of_processes, *args, **kwargs)

means.inference.plotting.plot_2d_trajectory(x, y, x_label='', y_label='', legend=False, ax=None, start_and_end_locations_only=False, start_marker='bo', end_marker='rx', start_label='Start', end_label='End', *args, **kwargs)

means.inference.plotting.plot_contour(x, y, z, x_label, y_label, ax=None, fmt='%.3f', *args, **kwargs)

Inference Results

This part of the package provides classes to store and manage the results of inference.

class means.inference.results.ConvergenceStatusBase(convergence_achieved)

Bases: means.io.serialise.SerialisableObject

convergence_achieved

class means.inference.results.InferenceResult(inference, optimal_parameters, optimal_initial_conditions, distance_at_minimum, convergence_status, solutions, distance_landscape)

Bases: means.io.serialise.SerialisableObject, means.util.memoisation.MemoisableObject

Parameters:

• inference –
• optimal_parameters –
• optimal_initial_conditions –
• distance_at_minimum –
• convergence_status (ConvergenceStatusBase) –
• solutions –
• distance_landscape – distance landscape - all the distances

convergence_status

distance_at_minimum

distance_landscape

The distance to the observed values at each point of the parameter space that was checked. This is different from the solutions list as it returns all the values checked, not only the ones that were chosen as intermediate steps by the solver :return: a list of (parameters, conditions, distance) tuples or None if the inference did not track it :rtype: list[tuple]|None

distance_landscape_as_3d_data(x_axis, y_axis)

Returns the distance landscape as three-dimensional data for the specified projection.

Parameters:

• x_axis – variable to be plotted on the x axis of projection
• y_axis – variable to be plotted on the y axis of projection

Returns:

a 3-tuple (x, y, z) where x and y are the lists of coordinates and z the list of distances at respective coordinates

inference

intermediate_trajectories

observed_trajectories

optimal_initial_conditions

optimal_parameters

optimal_trajectories

parameter_index(parameter_name)

plot(plot_intermediate_solutions=True, plot_observed_data=True, plot_starting_trajectory=True, plot_optimal_trajectory=True, filter_plots_function=None, legend=True, kwargs_observed_data=None, kwargs_starting_trajectories=None, kwargs_optimal_trajectories=None, kwargs_intermediate_trajectories=None)

Plot the inference result.

Parameters:

• plot_intermediate_solutions – plot the trajectories resulting from the intermediate solutions as well
• filter_plots_function – A function that takes a trajectory object and returns True if it should be plotted and false if not. None plots all available trajectories
• legend – Whether to draw the legend or not
• kwargs_observed_data – Kwargs to be passed to the trajectory.plot function for the observed data
• kwargs_starting_trajectories – kwargs to be passed to the trajectory.plot function for the starting trajectories
• kwargs_optimal_trajectories – kwargs to be passed to the trajectory.plot function for the optimal trajectories
• kwargs_intermediate_trajectories – kwargs to be passed to the trajectory.plot function for the intermediate trajectories

plot_distance_landscape_projection(x_axis, y_axis, ax=None, *args, **kwargs)

Plots the projection of distance landscape (if it was returned), onto the parameters specified

Parameters:

• x_axis – symbol to plot on x axis
• y_axis – symbol to plot on y axis
• ax – axis object to plot onto
• args – arguments to pass to matplotlib.pyplot.contourf()
• kwargs – keyword arguments to pass to matplotlib.pyplot.contourf()

Returns:

plot_trajectory_projection(x_axis, y_axis, legend=False, ax=None, start_and_end_locations_only=False, start_marker='bo', end_marker='rx', *args, **kwargs)

Plots the projection of the trajectory through the parameter space the minimisation algorithm took.

Since parameter space is often high-dimensional and paper can realistically represent only two, one needs to specify the x_axis, and y_axis arguments with the variable names to project the high-dimensional grid, on, i.e. x_axis='c_1', y_axis='c_4'

Parameters:

• x_axis (str|:class:~sympy.Symbol) – variable name (parameter or left hand side of equation) to project x axis onto
• y_axis (str|:class:~sympy.Symbol) – variable name to project y axis onto
• legend (bool) – Whether to display legend or not
• ax – Axis to plot onto (defaults to matplotlib.pyplot.gca() if not set)
• start_and_end_locations_only – If set to true, will not plot the trajectory, but only start and end parameter
• start_marker – The marker to use for start of trajectory, defaults to blue circle
• end_marker – The marker to use for end of trajectory, defaults to red x
• args – Arguments to pass to matplotlib.pyplot.plot() function
• kwargs – Keyword arguments to pass to matplotlib.pyplot.plot() function

problem

Return type:ODEProblem

solutions

Solutions at each each iteration of optimisation. :return: a list of (parameters, conditions) pairs :rtype: list[tuple]|None

solutions_as_2d_trajectories(x_axis, y_axis)

Returns the InferenceResult.solutions as a plottable 2d trajectory.

Parameters:

• x_axis – the variable to be on the x axis of projection
• y_axis – the variable to be on the y axis of preojection

Returns:

a tuple x, y specifying lists of x and y coordinates of projection

starting_initial_conditions

starting_parameters

starting_trajectories

classmethod to_yaml(dumper, data)

yaml_tag = '!inference-result'

class means.inference.results.InferenceResultsCollection(inference_results)

Bases: means.io.serialise.SerialisableObject

best

classmethod from_yaml(loader, node)

number_of_results

plot()

plot_distance_landscape_projection(x_axis, y_axis, ax=None, *args, **kwargs)

Plots the distance landscape jointly-generated from all the results

Parameters:

• x_axis – symbol to plot on x axis
• y_axis – symbol to plot on y axis
• ax – axis object to plot onto
• args – arguments to pass to matplotlib.pyplot.contourf()
• kwargs – keyword arguments to pass to matplotlib.pyplot.contourf()

Returns:

plot_trajectory_projection(x_axis, y_axis, *args, **kwargs)

Plots trajectory projection on the specified x and y axes See InferenceResult.plot_trajectory_projection() for information on the arguments and keyword arguments

Parameters:

• x_axis – variable to be plotted on the x axis of the projection
• y_axis – variable to be plotted on the y axis of the projection
• args – arguments to be passed to InferenceResult.plot_trajectory_projection()
• kwargs – keyword arguments to be passed to InferenceResult.plot_trajectory_projection()

results

Returns:The results of performed inferences Return type:list[InferenceResult]

classmethod to_yaml(dumper, data)

yaml_tag = '!serialisable-results-collection'

class means.inference.results.NormalConvergenceStatus(warn_flag, iterations_taken, function_calls_made)

Bases: means.inference.results.ConvergenceStatusBase

function_calls_made

iterations_taken

classmethod to_yaml(dumper, data)

warn_flag

yaml_tag = '!convergence-status'

class means.inference.results.SolverErrorConvergenceStatus

Bases: means.inference.results.ConvergenceStatusBase

classmethod to_yaml(dumper, data)

yaml_tag = '!multiple-solver-errors'

Module contents

Parameter Inference

This part of the package provides utilities for parameter inference. Parameter inference will try to find the set of parameters which produces trajectories with minimal distance to the observed trajectories. Different distance functions are implemented (such as functions minimising the sum of squares error or functions based on parametric likelihood), but it is also possible to use custom distance functions.

The package provides support for both inference from a single starting point (Inference) or inference from random starting points (InferenceWithRestarts).

Some basic inference result plotting functionality is also provided by the package, see the documentation for InferenceResult for more information on this.