utilities: The submodule for utility functions#

This module contains some utility functions for working with MHNs.

mhn.utilities.compute_next_event_probs(ndarray theta, ndarray current_state, double observation_rate=0) → np.ndarray#

Computes probabilities for each event to be the next one to occur, given the current state.

Parameters:

  • theta (np.ndarray[np.double_t, ndim=2]) – Theta matrix representing a cMHN.

  • current_state (np.ndarray[np.int32_t, ndim=1]) – Array representing the current state. Each entry corresponds to an event being present (1) or not (0).

  • observation_rate (float, optional) – Rate of the observation event. Defaults to 0, meaning no observation occurs before another event.

Returns:

Array containing the probabilities for each event to occur next.

Return type:

np.ndarray

Raises:

ValueError – If the size of theta does not match the size of current_state.

mhn.utilities.gillespie(ndarray theta, ndarray initial_state, int sample_num, bool return_event_times) → tuple[list[list[int]], np.ndarray | list[list[int]], list[list[float]], np.ndarray]#

Simulates event accumulation using the Gillespie algorithm.

Parameters:

  • theta (np.ndarray[np.double_t, ndim=2]) – Theta matrix representing a cMHN or an oMHN.

  • initial_state (np.ndarray[np.int32_t, ndim=1]) – Array representing the starting state. Each entry corresponds to an event being present (1) or not (0).

  • sample_num (int) – Number of samples to simulate.

  • return_event_times (bint) – If True, returns the times at which all events occurred.

Returns:

A tuple containing:

  • A list of lists where each inner list contains active events in chronological order.

  • if return_event_times is True, a list of lists of timepoints at which the events occurred for every sample (occurrence times of events already present in initial_state are declared as None),

  • A numpy array of observation times.

Return type:

tuple[list[list[int]], np.ndarray | list[list[int]], list[list[float]], np.ndarray]

Raises:

ValueError – If the size of theta is neither (n, n) nor (n+1, n).

mhn.utilities.gillespie_timed(ndarray theta, ndarray initial_state, int sample_num, float obs_time, bool return_times) → tuple[list[list[int]] | list[list[int]], list[list[float]]]#

Simulates event accumulation using the Gillespie algorithm, but stops only after a specified observation time.

Parameters:

  • theta (np.ndarray[np.double_t, ndim=2]) – Theta matrix representing a cMHN or an oMHN.

  • initial_state (np.ndarray[np.int32_t, ndim=1]) – Array representing the starting state. Each entry corresponds to an event being present (1) or not (0).

  • sample_num (int) – Number of samples to simulate.

  • obs_time (float) – The observation time after which the simulation stops. If np.inf, the simulation runs until all events have occurred.

  • return_times (bint) – If True, returns the times at which events occurred.

Returns:

A tuple containing:

  • A list of lists where each inner list contains active events in chronological order.

  • if return_times is True, a list of times at which events occurred (occurrence times of events already present in initial_state are declared as None).

Return type:

tuple[list[list[int]] | list[list[int]], list[list[float]]]

Raises:

ValueError – If the size of theta is neither (n, n) nor (n+1, n).

mhn.utilities.sample_artificial_data(ndarray theta, int sample_num) → np.ndarray#

Samples artificial cross-sectional data from a cMHN. Use np.random.seed() to make results reproducible.

Parameters:

  • theta (np.ndarray[np.double_t, ndim=2]) – Theta matrix representing a cMHN.

  • sample_num (int) – Number of samples in the generated data.

Returns:

2D array where each row corresponds to a sample and each column to a gene.

Return type:

np.ndarray

mhn.utilities.set_seed(seed: int)#

Set the random seed for reproducibility. Internally, this sets the seed for the numpy random generator.

Parameters:

seed (int) – The seed value to use for random number generators.