Functions 

transmission_models.utils.sample_in_between(model, Dt)[source]

Sample a random infection time between two events using a beta distribution parameterized by the model’s infection parameters.

Parameters:

model (object) – The model object containing infection parameters (expects attributes k_inf).
Dt (float) – The scale parameter (duration between events).

Returns:

A random sample from the beta distribution.

Return type:

transmission_models.utils.random_combination(iterable, r=1)[source]

Randomly select a combination of r elements from the given iterable.

Parameters:

iterable (iterable) – The input iterable to select elements from.
r (int, optional) – The number of elements to select. Default is 1.

Returns:

A tuple containing r randomly selected elements from the iterable.

Return type:

tuple

Notes

This function is equivalent to a random selection from itertools.combinations(iterable, r).

transmission_models.utils.search_firsts_sampled_siblings(host, T)[source]

Search the firsts sampled siblings of a host in the transmission tree.

Parameters:

host (Host) – The host to search the siblings from.
T (nx.DiGraph) – The transmission tree where the host belongs to.

Returns:

The list of the firsts sampled siblings of the host.

Return type:

transmission_models.utils.search_first_sampled_parent(host, T, root)[source]

Search the first sampled parent of a host in the transmission tree.

Parameters:

host (Host) – The host to search the parent from. If the host is the root of the tree, it returns None.
T (nx.DiGraph) – The transmission tree where the host belongs to.
root (Host) – The root of the transmission tree.

Returns:

The first sampled parent of the host, or None if host is the root.

Return type:

Host or None

transmission_models.utils.Delta_log_gamma(Dt_ini, Dt_end, k, theta)[source]

Compute the log likelihood of the gamma distribution for the time between two events.

Parameters:

Dt_ini (float) – Initial time.
Dt_end (float) – End time.
k (float) – Shape parameter of the gamma distribution.
theta (float) – Scale parameter of the gamma distribution.

Returns:

Difference of the log likelihood of the gamma distribution.

Return type:

transmission_models.utils.hierarchy_pos(G, root=None, width=1.0, vert_gap=0.2, vert_loc=0, xcenter=0.5)[source]

Compute hierarchical layout positions for a tree graph.

Parameters:

G (networkx.Graph) – The graph (must be a tree).
root (node, optional) – The root node of the current branch. If None, the root will be found automatically.
width (float, optional) – Horizontal space allocated for this branch. Default is 1.0.
vert_gap (float, optional) – Gap between levels of hierarchy. Default is 0.2.
vert_loc (float, optional) – Vertical location of root. Default is 0.
xcenter (float, optional) – Horizontal location of root. Default is 0.5.

Returns:

A dictionary of positions keyed by node.

Return type:

Notes

This function is adapted from Joel’s answer at https://stackoverflow.com/a/29597209/2966723. Licensed under Creative Commons Attribution-Share Alike.

transmission_models.utils.hierarchy_pos_times(G, root=None, width=1.0, vert_gap=0.2, vert_loc=0, xcenter=0.5)[source]

Compute hierarchical layout positions for a tree graph, using time as vertical position.

Parameters:

G (networkx.Graph) – The graph (must be a tree).
root (node, optional) – The root node of the current branch. If None, the root will be found automatically.
width (float, optional) – Horizontal space allocated for this branch. Default is 1.0.
vert_gap (float, optional) – Gap between levels of hierarchy. Default is 0.2.
vert_loc (float, optional) – Vertical location of root. Default is 0.
xcenter (float, optional) – Horizontal location of root. Default is 0.5.

Returns:

A dictionary of positions keyed by node.

Return type:

Notes

This function is adapted from Joel’s answer at https://stackoverflow.com/a/29597209/2966723. Licensed under Creative Commons Attribution-Share Alike.

transmission_models.utils.plot_transmision_network(T, nodes_labels=False, pos=None, highlighted_nodes=None, ax=None, to_frame=False, title=None, filename=None, show=True)[source]

Visualize a transmission network using matplotlib and networkx.

Parameters:

T (networkx.DiGraph) – The transmission network to plot.
nodes_labels (bool, optional) – Whether to display node labels. Default is False.
pos (dict, optional) – Node positions for layout. If None, uses graphviz_layout. Default is None.
highlighted_nodes (list, optional) – List of nodes to highlight. Default is None.
ax (matplotlib.axes.Axes, optional) – The axes to plot on. If None, uses current axes. Default is None.
to_frame (bool, optional) – If True, saves the plot to a temporary image and returns it as an array. Default is False.
title (str, optional) – Title for the plot. Default is None.
filename (str, optional) – If provided, saves the plot to this file. Default is None.
show (bool, optional) – Whether to display the plot. Default is True.

Returns:

image – The image array if to_frame is True, otherwise None.

Return type:

ndarray or None

transmission_models.utils.tree_to_dict(model, h)[source]

Convert a host and its descendants to a nested dictionary suitable for JSON export.

Parameters:

model (object) – The transmission model containing the tree structure.
h (host) – The host node to convert.

Returns:

A nested dictionary representing the host and its descendants.

Return type:

transmission_models.utils.cast_types(value, types_map)[source]

Recursively cast types in a nested data structure.

This function recursively traverses a nested data structure (dict, list) and casts any values that match the types in types_map to their target types. Useful for fixing JSON serialization issues with numpy types.

Parameters:

value (any) – The value to cast. Can be a dict, list, or any other type.
types_map (list of tuples) – List of (from_type, to_type) tuples specifying type conversions.

Returns:

The value with types cast according to types_map.

Return type:

any

Examples

>>> import numpy as np
>>> import json
>>> data = [np.int64(123)]
>>> data = cast_types(data, [(np.int64, int), (np.float64, float)])
>>> data_json = json.dumps(data)
>>> data_json == "[123]"
True

Notes

This function is useful for fixing “TypeError: Object of type int64 is not JSON serializable” errors when working with numpy arrays and JSON.

transmission_models.utils.tree_to_json(model, filename)[source]

Save a transmission model and its tree to a JSON file.

Parameters:

model (object) – The transmission model to export.
filename (str) – The path to the output JSON file.

transmission_models.utils.get_host_from_dict(dict_tree)[source]

Create a host object from a dictionary representation (as used in JSON trees).

Parameters:: dict_tree (dict) – The dictionary representing a host (from JSON).
Returns:: The reconstructed host object.
Return type:: host

transmission_models.utils.read_tree_dict(dict_tree, h1=None, edge_list=[])[source]

Recursively read a tree dictionary and extract edges as (parent, child) tuples.

Parameters:

dict_tree (dict) – The dictionary representing the tree (from JSON).
h1 (host, optional) – The parent host node. If None, will be created from dict_tree.
edge_list (list, optional) – The list to append edges to. Default is an empty list.

Returns:

A list of (parent, child) edge tuples.

Return type:

transmission_models.utils.json_to_tree(filename, sampling_params=None, offspring_params=None, infection_params=None)[source]

Load a transmission model from a JSON file and reconstruct the model object.

Parameters:

filename (str) – Path to the JSON file.
sampling_params (dict, optional) – Sampling parameters to override those in the file. Default is None.
offspring_params (dict, optional) – Offspring parameters to override those in the file. Default is None.
infection_params (dict, optional) – Infection parameters to override those in the file. Default is None.

Returns:

The reconstructed transmission model.

Return type:

didelot_unsampled

transmission_models.utils.build_infection_based_network(model, host_list)[source]

Generate a transmission tree network given a list of sampled hosts.

This function creates a transmission tree from the dataset. It uses the model’s sampling and infection parameters to construct a plausible initial transmission network.

For each host, we get a number of infected hosts and then we toss a coin to each host to see if they are connected given the infection time.

At the end, we add a virtual root host to connect all disconnected components.

Parameters:

model (didelot_unsampled) – The transmission model with sampling and infection parameters.
host_list (list) – List of host objects representing the sampled data.

Returns:

model

Return type:

The updated model with the generated transmission tree

Notes

This function implements the algorithm described in the notebook for generating initial transmission networks. It creates a directed graph representing the transmission tree and adds a virtual root host to connect all disconnected components.

transmission_models.utils.random() → x in the interval [0, 1).

transmission_models.utils.topology_movements.tree_slicing_to_offspring(model, selected_host=None, forced=False, verbose=False)[source]

Slices a node reconnecting it with its grandparent. It passes from a chain model to a offspring model for the selected_host, its parent and grandparent.

Parameters:

model: transmission_models.models.didelot_unsampled.didelotUnsampled
model with the transmission network to apply the transformation

selected_host: host object. Default None
host to be sliced. If None, it is randomly selected

forced: bool. Default False
If True, the movement is forced because the other is not possible

verbose: bool. Default False
If True, it prints information about the movement

Returns:

T_new: nx.DiGraph
New transmission network with the moves applied

gg: float
Ratio of proposals

selected_host: host object
Host sliced

parent: host object
Parent of the selected_host

grandparent: host object
Grandparent of the selected_host

to_chain: bool
If True, the proposal was to reconnect selected_host to be connected with one of its brother. Else, it was reconnected to its grandparent

transmission_models.utils.topology_movements.tree_slicing_to_chain(model, selected_host=None, selected_sibling=None, forced=False, verbose=False)[source]

Slices a node reconnecting it with one of its sibling. It passes from a offspring model to a chain model for the selected_host, its parent and the choosen sibling.

Parameters:

modeltransmission_models.models.didelot_unsampled.didelot_unsampled
model with the transmission network to apply the transformation

selected_host: host object. Default None
host to be sliced. If None, it is randomly selected

selected_sibling: host object. Default None
sibling to connect the selected_host. If None, it is randomly selected

forced: bool. Default False
If True, the movement is forced because the other is not possible

verbose: bool. Default False
If True, it prints information about the movement

Returns:

T_new: nx.DiGraph: New transmission network with the moves applied
gg: float: Ratio of proposals
selected_host: host object: Host sliced
parent: host object: Parent of the selected_host
selected_sibling: host object: Sibling now connected to the selected_host
to_chain: bool: If True, the proposal was to reconnect selected_host to be connected with one of its brother. Else, it was reconnected to its grandparent

transmission_models.utils.topology_movements.tree_slicing_step(model, P_to_offspring=0.5, verbose=False)[source]

Performs a tree slicing step in the transmission tree. Can be either to parent or sibling with equal probability.

Parameters:

model (transmission_models.models.didelot_unsampled.didelotUnsampled) – Transmission model
verbose (bool. Default False) – If True, it prints information about the proposal

Prior Functions

transmission_models.classes.partial_sampled_utils.check_attribute_sampling(host, attribute)[source]

Check if a host has a sampled attribute.

Parameters:

host (object) – The host to check.
attribute (str) – The attribute to check for sampling.

Returns:

True if the attribute is sampled, False otherwise.

Return type:

bool

transmission_models.classes.partial_sampled_utils.search_partial_sampled_siblings(host, T)[source]

Search for partially sampled siblings of a host in the transmission tree.

Parameters:

host (object) – The host to search siblings for.
T (object) – The transmission tree.

Returns:

List of partially sampled siblings.

Return type:

transmission_models.classes.partial_sampled_utils.search_partial_sampled_parent(host, T, root)[source]

Search for the partially sampled parent of a host in the transmission tree.

Parameters:

host (object) – The host to search the parent for.
T (object) – The transmission tree.
root (object) – The root of the transmission tree.

Returns:

The partially sampled parent, or None if not found.

Return type:

object or None

Utils Module

Utilities Module.

This module contains utility functions for tree manipulation, visualization, and data conversion in transmission network analysis.

Main Functions

tree_to_newick : Convert transmission tree to Newick format search_firsts_sampled_siblings : Find first sampled siblings in tree search_first_sampled_parent : Find first sampled parent in tree plot_transmision_network : Visualize transmission network tree_to_json : Convert tree to JSON format json_to_tree : Convert JSON to tree format tree_slicing_step : Tree topology manipulation functions

Visualization

hierarchy_pos : Generate hierarchical layout positions hierarchy_pos_times : Generate time-based hierarchical layout plot_transmision_network : Plot transmission network with various options

Data Conversion

tree_to_newick : Convert to Newick format for phylogenetic software tree_to_json : Convert to JSON for data storage json_to_tree : Convert from JSON back to tree structure

transmission_models.utils.tree_to_newick(g, lengths=True, root=None)[source]

Convert a transmission tree to Newick format for phylogenetic software.

Parameters:

g (networkx.DiGraph) – The transmission tree as a directed graph.
lengths (bool, optional) – Whether to include branch lengths in the Newick string. Default is True.
root (node, optional) – The root node of the tree. If None, the root will be inferred.

Returns:

The Newick string representation of the tree.

Return type:

str

transmission_models.utils.pdf_in_between(model, Dt, t)[source]

Compute the probability density function (PDF) value for the infection time between two events using a beta distribution parameterized by the model’s infection parameters.

Parameters:

model (object) – The model object containing infection parameters (expects attributes k_inf).
Dt (float) – The scale parameter (duration between events).
t (float) – The time at which to evaluate the PDF.

Returns:

The PDF value at time t.

Return type:

transmission_models.utils.sample_in_between(model, Dt)[source]

Sample a random infection time between two events using a beta distribution parameterized by the model’s infection parameters.

Parameters:

model (object) – The model object containing infection parameters (expects attributes k_inf).
Dt (float) – The scale parameter (duration between events).

Returns:

A random sample from the beta distribution.

Return type:

transmission_models.utils.random_combination(iterable, r=1)[source]

Randomly select a combination of r elements from the given iterable.

Parameters:

iterable (iterable) – The input iterable to select elements from.
r (int, optional) – The number of elements to select. Default is 1.

Returns:

A tuple containing r randomly selected elements from the iterable.

Return type:

tuple

Notes

This function is equivalent to a random selection from itertools.combinations(iterable, r).

transmission_models.utils.search_firsts_sampled_siblings(host, T)[source]

Search the firsts sampled siblings of a host in the transmission tree.

Parameters:

host (Host) – The host to search the siblings from.
T (nx.DiGraph) – The transmission tree where the host belongs to.

Returns:

The list of the firsts sampled siblings of the host.

Return type:

transmission_models.utils.search_first_sampled_parent(host, T, root)[source]

Search the first sampled parent of a host in the transmission tree.

Parameters:

host (Host) – The host to search the parent from. If the host is the root of the tree, it returns None.
T (nx.DiGraph) – The transmission tree where the host belongs to.
root (Host) – The root of the transmission tree.

Returns:

The first sampled parent of the host, or None if host is the root.

Return type:

Host or None

transmission_models.utils.Delta_log_gamma(Dt_ini, Dt_end, k, theta)[source]

Compute the log likelihood of the gamma distribution for the time between two events.

Parameters:

Dt_ini (float) – Initial time.
Dt_end (float) – End time.
k (float) – Shape parameter of the gamma distribution.
theta (float) – Scale parameter of the gamma distribution.

Returns:

Difference of the log likelihood of the gamma distribution.

Return type:

transmission_models.utils.hierarchy_pos(G, root=None, width=1.0, vert_gap=0.2, vert_loc=0, xcenter=0.5)[source]

Compute hierarchical layout positions for a tree graph.

Parameters:

G (networkx.Graph) – The graph (must be a tree).
root (node, optional) – The root node of the current branch. If None, the root will be found automatically.
width (float, optional) – Horizontal space allocated for this branch. Default is 1.0.
vert_gap (float, optional) – Gap between levels of hierarchy. Default is 0.2.
vert_loc (float, optional) – Vertical location of root. Default is 0.
xcenter (float, optional) – Horizontal location of root. Default is 0.5.

Returns:

A dictionary of positions keyed by node.

Return type:

Notes

This function is adapted from Joel’s answer at https://stackoverflow.com/a/29597209/2966723. Licensed under Creative Commons Attribution-Share Alike.

transmission_models.utils.hierarchy_pos_times(G, root=None, width=1.0, vert_gap=0.2, vert_loc=0, xcenter=0.5)[source]

Compute hierarchical layout positions for a tree graph, using time as vertical position.

Parameters:

G (networkx.Graph) – The graph (must be a tree).
root (node, optional) – The root node of the current branch. If None, the root will be found automatically.
width (float, optional) – Horizontal space allocated for this branch. Default is 1.0.
vert_gap (float, optional) – Gap between levels of hierarchy. Default is 0.2.
vert_loc (float, optional) – Vertical location of root. Default is 0.
xcenter (float, optional) – Horizontal location of root. Default is 0.5.

Returns:

A dictionary of positions keyed by node.

Return type:

Notes

This function is adapted from Joel’s answer at https://stackoverflow.com/a/29597209/2966723. Licensed under Creative Commons Attribution-Share Alike.

transmission_models.utils.plot_transmision_network(T, nodes_labels=False, pos=None, highlighted_nodes=None, ax=None, to_frame=False, title=None, filename=None, show=True)[source]

Visualize a transmission network using matplotlib and networkx.

Parameters:

T (networkx.DiGraph) – The transmission network to plot.
nodes_labels (bool, optional) – Whether to display node labels. Default is False.
pos (dict, optional) – Node positions for layout. If None, uses graphviz_layout. Default is None.
highlighted_nodes (list, optional) – List of nodes to highlight. Default is None.
ax (matplotlib.axes.Axes, optional) – The axes to plot on. If None, uses current axes. Default is None.
to_frame (bool, optional) – If True, saves the plot to a temporary image and returns it as an array. Default is False.
title (str, optional) – Title for the plot. Default is None.
filename (str, optional) – If provided, saves the plot to this file. Default is None.
show (bool, optional) – Whether to display the plot. Default is True.

Returns:

image – The image array if to_frame is True, otherwise None.

Return type:

ndarray or None

transmission_models.utils.tree_to_dict(model, h)[source]

Convert a host and its descendants to a nested dictionary suitable for JSON export.

Parameters:

model (object) – The transmission model containing the tree structure.
h (host) – The host node to convert.

Returns:

A nested dictionary representing the host and its descendants.

Return type:

transmission_models.utils.cast_types(value, types_map)[source]

Recursively cast types in a nested data structure.

This function recursively traverses a nested data structure (dict, list) and casts any values that match the types in types_map to their target types. Useful for fixing JSON serialization issues with numpy types.

Parameters:

value (any) – The value to cast. Can be a dict, list, or any other type.
types_map (list of tuples) – List of (from_type, to_type) tuples specifying type conversions.

Returns:

The value with types cast according to types_map.

Return type:

any

Examples

>>> import numpy as np
>>> import json
>>> data = [np.int64(123)]
>>> data = cast_types(data, [(np.int64, int), (np.float64, float)])
>>> data_json = json.dumps(data)
>>> data_json == "[123]"
True

Notes

This function is useful for fixing “TypeError: Object of type int64 is not JSON serializable” errors when working with numpy arrays and JSON.

transmission_models.utils.tree_to_json(model, filename)[source]

Save a transmission model and its tree to a JSON file.

Parameters:

model (object) – The transmission model to export.
filename (str) – The path to the output JSON file.

transmission_models.utils.get_host_from_dict(dict_tree)[source]

Create a host object from a dictionary representation (as used in JSON trees).

Parameters:: dict_tree (dict) – The dictionary representing a host (from JSON).
Returns:: The reconstructed host object.
Return type:: host

transmission_models.utils.read_tree_dict(dict_tree, h1=None, edge_list=[])[source]

Recursively read a tree dictionary and extract edges as (parent, child) tuples.

Parameters:

dict_tree (dict) – The dictionary representing the tree (from JSON).
h1 (host, optional) – The parent host node. If None, will be created from dict_tree.
edge_list (list, optional) – The list to append edges to. Default is an empty list.

Returns:

A list of (parent, child) edge tuples.

Return type: