4. Documentation¶

4.1. hybrid_hawkes_exp module¶

class mpoints.hybrid_hawkes_exp.HybridHawkesExp(number_of_event_types, number_of_states, events_labels, states_labels)[source]¶

Bases: object

This class implements state-dependent Hawkes processes with exponential kernels, a subclass of hybrid marked point processes. The main features it provides include simulation and statistical inference (estimation).

Parameters:	number_of_event_types (int) – number of different event types. number_of_states (int) – number of possible states. events_labels (list of strings) – names of the different event types. states_labels (list of strings) – names of the possible states.

static array_to_parameters(array, number_of_event_types_1, number_of_states, number_of_event_types_2=0)[source]¶

Retrieves the parameters \((\nu, \alpha, \beta)\) from a 1D array. It is NOT assumed that the length of the 1st and 3rd dimensions of the arrays \((\alpha_{e'xe})\) and \((\beta_{e'xe})\) are equal. For instance, in log_likelihood_of_events_partial(), only of subgroup of the parameters \((\nu, \alpha, \beta)\) are required.

Parameters:	array (1D numpy array) – an array containing the parameters \((\nu, \alpha, \beta)\). number_of_event_types_1 (int) – length of the first dimension of \((\alpha_{e'xe})\) and \((\beta_{e'xe})\). number_of_states (int) – number of possible states in the state-dependent Hawkes process, length of the second dimension. number_of_event_types_2 (int) – length of the third dimension of \((\alpha_{e'xe})\) and \((\beta_{e'xe})\). It is also the length of \(\nu\). If set to zero, we assume that array contains ALL the parameters and not only a subgroup, meaning that 1st and 3rd dimensions of the arrays \((\alpha_{e'xe})\) and \((\beta_{e'xe})\) are equal.
Return type:	1D numpy array, 3D numpy array, 3D numpy array
Returns:	the parameters \((\nu, \alpha, \beta)\).

compute_events_residuals(times, events, states, time_start, initial_partial_sums=0)[source]¶

Computes the events residuals \(r^e_n\) defined by

\[r^e_n := \int_{t^e_{n-1}}^{t^e_n} \lambda_e (t)dt,\]

where \(t^e_n\) is the time when the n th event of type e occurred. The methods wraps a C implementation that was obtained via Cython.

Parameters:	times (1D numpy array of float) – the times at which events occur. events (1D numpy array of int) – the sequence of event types, events[n] is the event type of the n th event. states (1D numpy array of int) – the sequence of states, states[n] is the new state of the system following the n th event. time_start (float) – the time at which we consider that the process started, prior times are treated as an initial condition. initial_partial_sums (3D numpy array) – the initial condition can also be given implicitly via the partial sums \(S_{e',x,e}(-\infty, \mbox{time_start}]\).
Return type:	list of 1D numpy arrays
Returns:	the e th element of the list is the sequence \((r^e_n)\) corresponding to the event type e.

compute_partial_sums(times, events, states, time_end, initial_partial_sums=None, time_initial_condition=None)[source]¶

Computes the partial sums

\[S_{e'xe}(-\infty,T] := \alpha_{e'xe} \sum_{n : t^{e'x}_n \leq T} \exp(-\beta_{e'xe}(T-t^{e'x}_n)),\]

where e and e’ are event types, x is a possible state, \(t^{e'x}_n\) is the time when the n th event of type e’ after which the state is x occurred. The collection of partial sums \((S_{e'xe})\) at time \(T\) encodes the history of the state-dependent Hawkes process up to time \(T\). It can for example be used to simulate the process from time \(T\). In simulate(), one can pass the partial sums as an initial condition instead of the entire history.

Parameters:	times (1D numpy array of float) – the times at which events occur. events (1D numpy array of int) – the sequence of event types, events[n] is the event type of the n th event. states (1D numpy array of int) – the sequence of states, states[n] is the new state of the system following the n th event. time_end (float) – \(T\), the time up to which the partial sums are computed. initial_partial_sums (3D numpy array of float) – an initial condition (events that occur before times) can be given implicitly as partial sums. time_initial_condition (float) – the time up to which the partial sums given as an initial condition were computed.
Return type:	3D numpy array of float
Returns:	the partial sums, array[e’, x, e] corresponds to \(S_{e'x'e}\).

compute_total_residuals(times, events, states, time_start, initial_partial_sums=0, initial_state=0)[source]¶

Computes the total residuals \(r^{ex}_n\) defined by

\[r^{ex}_n := \int_{t^{ex}_{n-1}}^{t^{ex}_n}\phi_{e}(X(t),x) \lambda_e (t)dt,\]

where \(t^{ex}_n\) is the time when the n th event of type e after which the state is x occurred. The methods wraps a C implementation that was obtained via Cython.

Parameters:	times (1D numpy array of float) – the times at which events occur. events (1D numpy array of int) – the sequence of event types, events[n] is the event type of the n th event. states (1D numpy array of int) – the sequence of states, states[n] is the new state of the system following the n th event. time_start (float) – the time at which we consider that the process started, prior times are treated as an initial condition. initial_partial_sums (3D numpy array) – the initial condition can also be given implicitly via the partial sums \(S_{e',x,e}(-\infty, \mbox{time_start}]\). initial_state (int) – if there are no event times before time_start, this is used as the initial state.
Return type:	list of 1D numpy arrays
Returns:	the sequence \((r^{ex}_n)\) is the x + e * number_of_states th element in the list.

static decay_coefficients_to_string(decay_coefficients)[source]¶

Transforms the decay coefficients \(\beta\) to a string that can be printed in the console or a text file.

Parameters:	decay_coefficients (3D numpy array) – the decay coefficients \(\beta\).
Return type:	string
Returns:	sequence of matrices \((\beta_{\cdot x \cdot})\), one per possible state x.

estimate_hawkes_parameters(times, events, states, time_start, time_end, maximum_number_of_iterations=2000, method='TNC', parameters_lower_bound=1e-06, parameters_upper_bound=None, given_guesses=[], number_of_random_guesses=1, min_decay_coefficient=0.5, max_decay_coefficient=100, parallel_estimation=True)[source]¶

Estimates the parameters of the intensities (arrival rates) of events, i.e., \((\nu, \alpha, \beta)\). Estimation if performed via maximum likelihood. This method uses the scipy.minimize library.

Parameters:	times (1D numpy array of float) – the times at which events occur. events (1D numpy array of int) – the sequence of event types, events[n] is the event type of the n th event. states (1D numpy array of int) – the sequence of states, states[n] is the new state of the system following the n th event. time_start (float) – the time at which we consider that the process started, prior times are treated as an initial condition. time_end (float) – the time at which we stopped to record the process. maximum_number_of_iterations (int) – will be passed to the maxiter argument in scipy.minimize. Depending on method, it is the maximum number of iterations or function evaluations. method (string) – the optimisation method used in scipy.minimize. parameters_lower_bound (float) – lower bound on all the parameters. parameters_upper_bound (float) – upper bound on all the parameters. given_guesses (list of 1D numpy array) – every member x is an initial guess on the parameters. For every x, we attempt to maximise the likelihood starting from x. One can go from x to \((\nu, \alpha, \beta)\) and vice versa using `array_to_parameters()` and `parameters_to_array()`. We retain the solution that gives the highest likelihood. number_of_random_guesses (int) – the method can also generate random initial guesses. min_decay_coefficient (numpy array or float) – defines how a random guess is generated. max_decay_coefficient (numpy array of float) – a random guess on \(\beta_{e'xe}\) is generated uniformly in the interval [min_decay_coefficient[e’,x,e], max_decay_coefficient[e’,x.e]] but on a logarithmic scale. parallel_estimation (boolean) – the MLE problem can be decomposed into \(d_e\) independent optimisation problems, where \(d_e\) is the number of event types. When True, each problem is solved independently. In this case, the limit on the number of iterations or function evaluations is applied independently to each sub-problem.
Return type:	scipy.optimize.OptimizerResult, 1D numpy array, string
Returns:	The first object is the optimisation result and contains the maximum likelihood estimate along with additional information on the optimisation routine. The second object contains the initial guess that resulted in the highest likelihood after running the optimisation procedure. The third object indicates the nature of this initial guess (‘random’ or ‘given’).

estimate_transition_probabilities(events, states)[source]¶

Estimates the transition probabilities \(\phi\) of the state process from the data. This method returns the maximum likelihood estimate. One can prove that it coincides with the empirical transition probabilities.

Parameters:	events (1D array of int) – the sequence of event types, events[n] is the event type of the n th event. states (1D array of int) – the sequence of states, states[n] is the new state of the system following the n th event.
Return type:	3D array
Returns:	the estimated transition probabilities \(\phi\).

generate_base_rates_labels()[source]¶

Produces labels for the base rates \(\nu\). This uses the events labels of the model.

Return type:	list of string
Returns:	list[e] returns a label for \(\nu_e\).

generate_decay_coefficients_labels()[source]¶

Produces labels for the decay coefficients \(\beta\). This uses the events and states labels of the model.

Return type:	list of list of list of string
Returns:	list[e’][x][e] returns a label for \(\beta_{e'xe}\).

generate_impact_coefficients_labels()[source]¶

Produces labels for the impact coefficients \(\alpha\). This uses the events and states labels of the model.

Return type:	list of list of list of string
Returns:	list[e’][x][e] returns a label for \(\alpha_{e'xe}\).

generate_product_labels()[source]¶

Produces labels for all the couples of events types and possible states. This uses the events and states labels of the model.

Return type:	list of strings
Returns:	the label for the couple (e, x) is given by by list[n] where \(n = x + e \times \mbox{number_of_event_types}\).

gradient(parameters, times, events, states, time_start, time_end)[source]¶

Computes the gradient of the log-likelihood \(l\) with respect to the parameters \((\nu, \alpha, \beta)\). The method wraps a C implementation that was obtained via Cython.

Parameters:	parameters (1D numpy array) – the parameters \((\nu, \alpha, \beta)\) put into a single array. Go from parameters to \((\nu, \alpha, \beta)\) and vice versa using `array_to_parameters()` and `parameters_to_array()`. times (1D numpy array of float) – the times at which events occur. events (1D numpy array of int) – the sequence of event types, events[n] is the event type of the n th event. states (1D numpy array of int) – the sequence of states, states[n] is the new state of the system following the n th event. time_start (float) – \(t_0\), the time at which we consider that the process started, prior times are treated as an initial condition. time_end (float) – \(T\), the time at which we stopped to record the process.
Return type:	float
Returns:	the gradient of the log-likelihood \(l\).

gradient_partial(event_type, parameters, times, events, states, time_start, time_end)[source]¶

Computes the gradient of the partial log-likelihood \(l_e\) with respect to the parameters \((\nu, \alpha, \beta)\) that govern \(\lambda_e\), the intensity of events of type e. The method wraps a C implementation that was obtained via Cython.

Parameters:	event_type (int) – e, the event type for which we want to compute the gradient of the partial log-likelihood \(l_e\). parameters (1D numpy array) – only the parameters \((\nu, \alpha, \beta)\) that govern \(\lambda_e\) put into a single array. Go from parameters to \((\nu, \alpha, \beta)\) and vice versa using `array_to_parameters()` and `parameters_to_array()`. times (1D numpy array of float) – the times at which events occur. events (1D numpy array of int) – the sequence of event types, events[n] is the event type of the n th event. states (1D numpy array of int) – the sequence of states, states[n] is the new state of the system following the n th event. time_start (float) – \(t_0\), the time at which we consider that the process started, prior times are treated as an initial condition. time_end (float) – \(T\), the time at which we stopped to record the process.
Return type:	float
Returns:	the gradient of the partial log-likelihood \(l_e\).

static impact_coefficients_to_string(impact_coefficients)[source]¶

Transforms the impact coefficients \(\alpha\) to a string that can be printed in the console or a text file.

Parameters:	impact_coefficients (3D numpy array) – the impact coefficients \(\alpha\).
Return type:	string
Returns:	sequence of matrices \((\alpha_{\cdot x \cdot})\), one per possible state x.

intensities_of_events(partial_sums)[source]¶

Computes the intensities, given the partial sums \(S_{e'xe}\).

Parameters:	partial_sums (3D numpy array of float) – the partial sums \(S_{e',x',e}\) at the considered time.
Return type:	1D numpy array of float
Returns:	the intensities, array[e] is the value of \(\lambda_e\) at the considered time.

intensities_of_events_at_times(compute_times, times, events, states)[source]¶

Computes the intensities at the compute_times given a realisation of the state-dependent Hawkes process.

Parameters:	compute_times (1D numpy array of float) – the times at which the intensities will be computed. times (1D numpy array of float) – the times at which events occur. events (1D numpy array of int) – the sequence of event types, events[n] is the event type of the n th event. states (1D numpy array of int) – the sequence of states, states[n] is the new state of the system following the n th event.
Return type:	1D numpy array of float, 2D numpy array of float
Returns:	the first array contains both the compute_times and the event times of the given realisation, in increasing order. Note that the event times are put there twice: the intensities are computed just before and right after the event times. The second array gives the intensities at the times of the first array. array2[e,n] is the intensity of events of type e at time array1[n].

intensity_of_event(event_type, partial_sums)[source]¶

Computes the intensity of events of type event_type, given the partial sums \(S_{e'xe}\).

Parameters:	event_type (int) – the event type for which the intensity is computed. partial_sums (3D numpy array of float) – the partial sums \(S_{e',x',e}\) at the considered time.
Return type:	float
Returns:	the value of \(\lambda_e\) at the considered time.

static kernel_at_time(time, alpha, beta)[source]¶

Evaluates the kernel of the model at the given time with the given parameters.

Parameters:	time (float) – the positive time \(t\). alpha (float) – a non-negative \(\alpha\). beta (float) – a positive \(\beta\).
Return type:	float
Returns:	\(\alpha\exp(-\beta t)\).

log_likelihood_of_events(parameters, times, events, states, time_start, time_end)[source]¶

Computes the log-likelihood of the observed times and event types under the assumption that they are the realisation of a state-dependent Hawkes process with the given parameters. The log-likelihood is given by

\[l := \sum_{n : t_0 < t_n \leq T} \lambda_{e_n}(t_n) - \sum_e \int_{t_0}^T \lambda_e(t)dt,\]

where \((t_n)\) and \((e_n)\) are the sequences of event times and event types, respectively. The method wraps a C implementation that was obtained via Cython.

Parameters:	parameters (1D numpy array) – the parameters \((\nu, \alpha, \beta)\) put into a single array. Go from parameters to \((\nu, \alpha, \beta)\) and vice versa using `array_to_parameters()` and `parameters_to_array()`. times (1D numpy array of float) – the times at which events occur. events (1D numpy array of int) – the sequence of event types, events[n] is the event type of the n th event. states (1D numpy array of int) – the sequence of states, states[n] is the new state of the system following the n th event. time_start (float) – \(t_0\), the time at which we consider that the process started, prior times are treated as an initial condition. time_end (float) – \(T\), the time at which we stopped to record the process.
Return type:	float
Returns:	the log-likelihood \(l\).

log_likelihood_of_events_partial(event_type, parameters, times, events, states, time_start, time_end)[source]¶

Computes the log-likelihood of the arrival times of events of the given type under the assumption that they are the realisation of a state-dependent Hawkes process with the given parameters. These parameters include only those that govern \(\lambda_e\), the intensity of events of type e. For example, among the base rates \(\nu\), only \(\nu_e\) should be contained in parameters. This partial log-likelihood is given by

\[l_e := \sum_{n : t_0 < t^e_n \leq T} \lambda_{e}(t^e_n) - \int_{t_0}^T \lambda_e(t)dt,\]

where \((t^e_n)\) are the arrival times of events of the given type e. The method wraps a C implementation that was obtained via Cython.

Parameters:	event_type (int) – e, the event type for which we want to compute the partial log-likelihood \(l_e\). parameters (1D numpy array) – only the parameters \((\nu, \alpha, \beta)\) that govern \(\lambda_e\) put into a single array. Go from parameters to \((\nu, \alpha, \beta)\) and vice versa using `array_to_parameters()` and `parameters_to_array()`. times (1D numpy array of float) – the times at which events occur. events (1D numpy array of int) – the sequence of event types, events[n] is the event type of the n th event. states (1D numpy array of int) – the sequence of states, states[n] is the new state of the system following the n th event. time_start (float) – \(t_0\), the time at which we consider that the process started, prior times are treated as an initial condition. time_end (float) – \(T\), the time at which we stopped to record the process.
Return type:	float
Returns:	the partial log-likelihood \(l_e\).

static parameters_to_array(base_rates, impact_coefficients, decay_coefficients)[source]¶

Puts the model parameters \((\nu, \alpha, \beta)\) into a one dimensional array.

Parameters:	base_rates (1D numpy array) – the collection \((\nu_{e})\). impact_coefficients (3D numpy array) – the collection \((\alpha_{e'xe})\). decay_coefficients (3D numpy array) – the collection \((\beta_{e'xe})\).
Return type:	1D numpy array
Returns:	the parameters put into a single 1D array.

static proportion_of_events_and_states(events, states, number_of_event_types, number_of_states)[source]¶

Computes the empirical distribution of the events and states.

Parameters:	events (1D numpy array of int) – the sequence of event types, events[n] is the event type of the n th event. states (1D numpy array of int) – the sequence of states, states[n] is the new state of the system following the n th event. number_of_event_types (int) – number of different event types. number_of_states (int) – number of possible states.
Return type:	2D numpy array of float
Returns:	array[e,x] is the percentage of events of type e after which the state is x.

set_hawkes_parameters(base_rates, impact_coefficients, decay_coefficients)[source]¶

Fixes the parameters \((\nu, \alpha, \beta)\) that define the intensities (arrival rates) of events. The are used in simulate(), compute_events_residuals() and compute_total_residuals().

Parameters:	base_rates (1D numpy array) – one base rate \(\nu_e\) per event type \(e\). impact_coefficients (3D numpy array) – the alphas \(\alpha_{e'xe}\). decay_coefficients (3D numpy array) – the betas \(\beta_{e'xe}\).
Returns:

set_transition_probabilities(transition_probabilities)[source]¶

Fixes the transition probabilities \(\phi\) of the state-dependent Hawkes process. The are used to simulate() and compute_total_residuals().

Parameters:	transition_probabilities (3D numpy array) – shape should be \((d_x, d_e,d_x)\) where \(d_e\) and \(d_x\) are the number of event types and states, respectively. The entry \(i, j, k\) is the probability of going from state \(i\) to state \(k\) when an event of type \(j\) occurs.
Returns:

simulate(time_start, time_end, initial_condition_times=[], initial_condition_events=[], initial_condition_states=[], initial_partial_sums=0, initial_state=0, max_number_of_events=1000000)[source]¶

Simulates a sample path of the state-dependent Hawkes process. The methods wraps a C implementation that was obtained via Cython.

Parameters:	time_start (float) – time at which the simulation starts. time_end (float) – time at which the simulation ends. initial_condition_times (array) – times of events before and including time_start. initial_condition_events (array of int) – types of the events that occurred at initial_condition_times. initial_condition_states (array of int) – values of the state process just after the initial_condition_times. initial_partial_sums (3D numpy array) – the initial condition can also be given implicitly via the partial sums \(S_{e',x,e}(-\infty, \mbox{time_start}]\). initial_state (int) – if there are no event times before time_start, this is used as the initial state. max_number_of_events (int) – the simulation stops when this number of events is reached (including the initial condition).
Return type:	array, array of int, array of int
Returns:	the times at which the events occur, their types and the values of the state process right after each event. Note that these include the initial condition as well.

static transition_matrix_to_string(transition_probabilities)[source]¶

Transforms the transition probabilities \(\phi\) to a string that can be printed in the console or a text file.

Parameters:	transition_probabilities (3D numpy array) – the transition probabilities \(\phi\).
Return type:	string
Returns:	sequence of transition probability matrices \((\phi_e)\), one per event type e.

4.2. plot_tools module¶

mpoints.plot_tools.correlogram(residuals, path='', fig_name='correlogram.pdf', title=None, labels=None, model_labels=None, palette=None, n_lags=50, figsize=(8, 6), size_labels=16, size_ticks=14, size_legend=16, bottom=None, top=None, left=None, right=None, savefig=False)[source]¶

Correlogram of residuals.

Parameters:	residuals (list) – list of lists (one list of residuals per event type) or list of lists of lists when multiple models are compared (one list of lists per model). path (string) – where the figure is saved. fig_name (string) – name of the file. title (string) – suptitle. labels (list of strings) – labels of the event types. model_labels (list of strings) – names of the different considered models. palette (list of colours) – color palette, one color per model. n_lags (int) – number of lags to plot. figsize ((int, int)) – tuple (width, height). size_labels (int) – fontsize of labels. size_ticks (int) – fontsize of tick labels. legend_size (int) – fontsize of the legend. bottom (float) – between 0 and 1, adjusts the bottom margin, see matplotlib subplots_adjust. top (float) – between 0 and 1, adjusts the top margin, see matplotlib subplots_adjust. left (float) – between 0 and 1, adjusts the left margin, see matplotlib subplots_adjust. right (float) – between 0 and 1, adjusts the right margin, see matplotlib subplots_adjust. savefig (boolean) – set to True to save the figure.
Return type:	Figure, array of Axes
Returns:	the figure and array of figures (see matplotlib).

mpoints.plot_tools.discrete_distribution(probabilities, path='', fig_name='distribution_events_states.pdf', v_labels=None, h_labels=None, title=None, color_map=None, figsize=(12, 6), size_labels=16, size_values=14, bottom=None, top=None, left=None, right=None, savefig=False, usetex=False)[source]¶

Annotated heatmap of a given discrete distribution with 2 dimensions.

Parameters:	probabilities (2D array) – the 2D discrete distribution. path (string) – where the figure is saved. fig_name (string) – name of the file. v_labels (list of strings) – labels for the first dimension (vertical). h_labels (list of strings) – labels for the second dimension (horizontal). title (string) – suptitle. color_map – color map for the heatmap, see seaborn documentation. figsize ((int, int)) – tuple (width, height). size_labels (int) – fontsize of labels. size_values (int) – fontsize of the annotations on top of the heatmap. bottom (float) – between 0 and 1, adjusts the bottom margin, see matplotlib subplots_adjust. top (float) – between 0 and 1, adjusts the top margin, see matplotlib subplots_adjust. left (float) – between 0 and 1, adjusts the left margin, see matplotlib subplots_adjust. right (float) – between 0 and 1, adjusts the right margin, see matplotlib subplots_adjust. savefig (boolean) – set to True to save the figure. usetex (boolean) – set to True if matplolib figure is rendered with TeX.
Return type:	Figure
Returns:	the figure (see matplotlib).

mpoints.plot_tools.kernels_exp(impact_coefficients, decay_coefficients, events_labels=None, states_labels=None, path='', fig_name='kernels.pdf', title=None, palette=None, figsize=(9, 7), size_labels=16, size_values=14, size_legend=16, bottom=None, top=None, left=None, right=None, savefig=False, fig_array=None, fig=None, tmin=None, tmax=None, npoints=500, ymax=None, alpha=1, legend_pos=0, log_timescale=True, ls='-')[source]¶

Plots the kernels of a state-dependent Hawkes process. Here the kernels are assumed to be exponential, that is, \(k_{e'e}(t,x)=\alpha_{e'xe}\exp(-\beta_{e'xe}t)\). We plot the functions

\[t\mapsto ||k_{e'e}(\cdot,x)||_{1,t} := \int _{0}^{t} k_{e'e}(s,x)ds.\]

The quantity \(||k_{e'e}(\cdot,x)||_{1,t}\) can be interpreted as the average number of events of type \(e\) that are directly precipitated by an event of type \(e'\) within \(t\) units of time, under state \(x\). There is a subplot for each couple of event types \((e',e)\). In each subplot, there is a curve for each possible state \(x\).

Parameters:	impact_coefficients (3D array) – the alphas \(\alpha_{e'xe}\). decay_coefficients (3D array) – the betas \(\beta_{e'xe}\). events_labels (list of strings) – labels of the event types. states_labels (list of strings) – labels of the states. path (string) – where the figure is saved. fig_name (string) – name of the file. title (string) – suptitle. palette (list of colours) – color palette, one color per state \(x\). figsize ((int, int)) – tuple (width, height). size_labels (int) – fontsize of labels. size_values (int) – fontsize of tick labels. size_legend (int) – fontsize of the legend. bottom (float) – between 0 and 1, adjusts the bottom margin, see matplotlib subplots_adjust. top (float) – between 0 and 1, adjusts the top margin, see matplotlib subplots_adjust. left (float) – between 0 and 1, adjusts the left margin, see matplotlib subplots_adjust. right (float) – between 0 and 1, adjusts the right margin, see matplotlib subplots_adjust. savefig (boolean) – set to True to save the figure. fig_array (array of Axes) – fig_array, where to plot the kernels (see matplotlib). fig (Figure) – figure, where to plot the figure (see matplotlib). tmin (float) – we plot over the time interval [tmin, tmax]. tmax (float) – we plot over the time interval [tmin, tmax]. npoints (int) – number of points used to plot. ymax (float) – upper limit of the y axis. alpha (float) – between 0 and 1, transparency of the curves. legend_pos (int) – position of the legend in the array of figures. log_timescale (boolean) – set to False to plot with a linear timescale.g ls (string) – the linestyle (see matplotlib).
Return type:	Figure, array of Axes
Returns:	the figure and array of figures (see matplotlib).

mpoints.plot_tools.qq_plot(residuals, shape=None, path='', fig_name='qq_plot.pdf', log=False, q_min=0.01, q_max=0.99, number_of_quantiles=100, title=None, labels=None, model_labels=None, palette=None, figsize=(12, 6), size_labels=16, size_ticks=14, legend_size=16, bottom=0.12, top=0.93, left=0.08, right=0.92, savefig=False, leg_pos=0)[source]¶

Qq-plot of residuals.

Parameters:	residuals (list) – list of lists (one list of residuals per event type) or list of lists of lists when multiple models are compared (one list of lists per model). shape ((int, int)) – 2D-tuple (number of rows, number of columns), shape of the array of figures. path (string) – where the figure is saved. fig_name (string) – name of the file. log (boolean) – set to True for qq-plots with log-scale. q_min (float) – smallest quantile to plot (e.g., 0.01 for 1%). q_max (float) – largest quantile to plot. number_of_quantiles (int) – number of points used to plot. title (string) – suptitle. labels (list of strings) – labels of the event types. model_labels (list of strings) – names of the different considered models. palette (list of colours) – color palette, one color per model. figsize ((int, int)) – tuple (width, height). size_labels (int) – fontsize of labels. size_ticks (int) – fontsize of tick labels. legend_size (int) – fontsize of the legend. bottom (float) – between 0 and 1, adjusts the bottom margin, see matplotlib subplots_adjust. top (float) – between 0 and 1, adjusts the top margin, see matplotlib subplots_adjust. left (float) – between 0 and 1, adjusts the left margin, see matplotlib subplots_adjust. right (float) – between 0 and 1, adjusts the right margin, see matplotlib subplots_adjust. savefig (boolean) – set to True to save the figure. leg_pos (int) – position of the legend in the array of figures.
Return type:	Figure, array of Axes
Returns:	the figure and array of figures (see matplotlib).

mpoints.plot_tools.sample_path(times, events, states, model, time_start, time_end, color_palette=None, labelsize=16, ticksize=14, legendsize=16, num=1000, s=12, savefig=False, path='', fig_name='sample_path.pdf')[source]¶

Plots a sample path along with the intensities.

Parameters:	times (array of floats) – times when the events occur. events (array of int) – type of the event at each event time. states (array of int) – state process after each event time. model (`HybridHawkesExp`) – the model that is used to compute the intensities. time_start (float) – time at which the plot starts. time_end (float) – time at which the plot ends. color_palette (list of colours) – one colour per event type. labelsize (int) – fontsize of labels. ticksize (int) – fontsize of tick labels. legendsize (int) – fontsize of the legend. num (int) – number of points used to plot. s (int) – size of the dots in the scatter plot of the events. savefig (boolean) – set to True to save the figure. path (string) – where the figure is saved. fig_name (string) – name of the file.
Return type:	Figure, array of Axes
Returns:	the figure and array of figures (see matplotlib).

mpoints.plot_tools.transition_probabilities(probabilities, shape=None, path='', fig_name='transition_probabilities.pdf', events_labels=None, states_labels=None, title=None, color_map=None, figsize=(12, 6), size_labels=16, size_values=14, bottom=0.1, top=0.95, left=0.08, right=0.92, wspace=0.2, hspace=0.2, savefig=False, usetex=False)[source]¶

Annotated heatmap of the transition probabilities of a state-dependent Hawkes process.

Parameters:	probabilities (3D array) – the transition probabilities. shape ((int, int)) – 2D-tuple (number of rows, number of columns), shape of the array of figures. path (string) – where the figure is saved. fig_name (string) – name of the file. events_labels (list of strings) – labels of the event types. states_labels (list of strings) – labels of the states. title (string) – suptitle. color_map – color map for the heatmap, see seaborn documentation. figsize ((int, int)) – tuple (width, height). size_labels (int) – fontsize of labels. size_values (int) – fontsize of the annotations on top of the heatmap. bottom (float) – between 0 and 1, adjusts the bottom margin, see matplotlib subplots_adjust. top (float) – between 0 and 1, adjusts the top margin, see matplotlib subplots_adjust. left (float) – between 0 and 1, adjusts the left margin, see matplotlib subplots_adjust. right (float) – between 0 and 1, adjusts the right margin, see matplotlib subplots_adjust. wspace (float) – horizontal spacing between the subplots, see matplotlib subplots_adjust. hspace (float) – vertical spacing between the subplots, see matplotlib subplots_adjust. savefig (boolean) – set to True to save the figure. usetex (boolean) – set to True if matplolib figure is rendered with TeX.
Return type:	Figure, array of Axes
Returns:	the figure and array of figures (see matplotlib).