Skip to content

Commit

Permalink
tidy up algorithm docstrings
Browse files Browse the repository at this point in the history
  • Loading branch information
@ljeub-pometry
ljeub-pometry committed Jan 23, 2025
1 parent fe13da7 commit 9998f5c
Show file tree
Hide file tree
Showing 3 changed files with 100 additions and 56 deletions.
88 changes: 57 additions & 31 deletions python/python/raphtory/algorithms/__init__.pyi
View file
Original file line number Diff line number Diff line change
Expand Up @@ -229,8 +229,8 @@ def pagerank(
graph: GraphView,
iter_count: int = 20,
max_diff: Optional[float] = None,
use_l2_norm=True,
damping_factor=0.85,
use_l2_norm: bool = True,
damping_factor: float = 0.85,
) -> NodeStateF64:
"""
Pagerank -- pagerank centrality value of the nodes in a graph
Expand All @@ -241,10 +241,12 @@ def pagerank(
Arguments:
graph (GraphView): Raphtory graph
iter_count (int): Maximum number of iterations to run. Note that this will terminate early if convergence is reached.
iter_count (int): Maximum number of iterations to run. Note that this will terminate early if convergence is reached. Defaults to 20.
max_diff (Optional[float]): Optional parameter providing an alternative stopping condition.
The algorithm will terminate if the sum of the absolute difference in pagerank values between iterations
is less than the max diff value given.
use_l2_norm (bool): Flag for choosing the norm to use for convergence checks, True for l2 norm, False for l1 norm. Defaults to True.
damping_factor (float): The damping factor for the PageRank calculation. Defaults to 0.85.
Returns:
NodeStateF64: Mapping of nodes to their pagerank value.
Expand Down Expand Up @@ -339,7 +341,7 @@ def local_clustering_coefficient(graph: GraphView, v: NodeInput) -> float:
"""

def weakly_connected_components(
graph: GraphView, iter_count: int = 9223372036854775807
graph: GraphView, iter_count: Optional[int] = None
) -> NodeStateUsize:
"""
Weakly connected components -- partitions the graph into node sets which are mutually reachable by an undirected path
Expand All @@ -349,7 +351,7 @@ def weakly_connected_components(
Arguments:
graph (GraphView): Raphtory graph
iter_count (int): Maximum number of iterations to run. Note that this will terminate early if the labels converge prior to the number of iterations being reached.
iter_count (int, optional): Maximum number of iterations to run. Note that this will terminate early if the labels converge prior to the number of iterations being reached.
Returns:
NodeStateUsize: Mapping of nodes to their component ids.
Expand Down Expand Up @@ -379,15 +381,15 @@ def in_components(graph: GraphView) -> NodeStateNodes:
NodeStateNodes: Mapping of nodes to the nodes in their 'in-component'
"""

def in_component(node: Node):
def in_component(node: Node) -> NodeStateUsize:
"""
In component -- Finding the "in-component" of a node in a directed graph involves identifying all nodes that can be reached following only incoming edges.
Arguments:
node (Node): The node whose in-component we wish to calculate
Returns:
An array containing the Nodes within the given nodes in-component
NodeStateUsize: Mapping of nodes in the in-component to the distance from the starting node.
"""

def out_components(graph: GraphView) -> NodeStateNodes:
Expand Down Expand Up @@ -436,8 +438,8 @@ def fast_rp(
"""

def global_temporal_three_node_motif(
graph: GraphView, delta: int, threads=None
) -> list:
graph: GraphView, delta: int, threads: Optional[int] = None
) -> list[int]:
"""
Computes the number of three edge, up-to-three node delta-temporal motifs in the graph, using the algorithm of Paranjape et al, Motifs in Temporal Networks (2017).
We point the reader to this reference for more information on the algorithm and background, but provide a short summary below.
Expand Down Expand Up @@ -476,24 +478,26 @@ def global_temporal_three_node_motif(
Arguments:
graph (GraphView): A directed raphtory graph
delta (int): Maximum time difference between the first and last edge of the motif. NB if time for edges was given as a UNIX epoch, this should be given in seconds, otherwise milliseconds should be used (if edge times were given as string)
threads (int, optional): The number of threads to use when running the algorithm.
Returns:
list: A 40 dimensional array with the counts of each motif, given in the same order as described above. Note that the two-node motif counts are symmetrical so it may be more useful just to consider the first four elements.
list[int]: A 40 dimensional array with the counts of each motif, given in the same order as described above. Note that the two-node motif counts are symmetrical so it may be more useful just to consider the first four elements.
Notes:
This is achieved by calling the local motif counting algorithm, summing the resulting arrays and dealing with overcounted motifs: the triangles (by dividing each motif count by three) and two-node motifs (dividing by two).
"""

def global_temporal_three_node_motif_multi(
graph: GraphView, deltas: list[int], threads=None
graph: GraphView, deltas: list[int], threads: Optional[int] = None
) -> list[list[int]]:
"""
Computes the global counts of three-edge up-to-three node temporal motifs for a range of timescales. See `global_temporal_three_node_motif` for an interpretation of each row returned.
Arguments:
graph (GraphView): A directed raphtory graph
deltas(list[int]): A list of delta values to use.
deltas (list[int]): A list of delta values to use.
threads (int, optional): The number of threads to use.
Returns:
list[list[int]]: A list of 40d arrays, each array is the motif count for a particular value of delta, returned in the order that the deltas were given as input.
Expand Down Expand Up @@ -531,7 +535,7 @@ def hits(
Arguments:
graph (GraphView): Graph to run the algorithm on
iter_count (int): How many iterations to run the algorithm
iter_count (int): How many iterations to run the algorithm. Defaults to 20.
threads (int, optional): Number of threads to use
Returns:
Expand Down Expand Up @@ -623,7 +627,7 @@ def louvain(
Arguments:
graph (GraphView): the graph view
resolution (float): the resolution parameter for modularity
resolution (float): the resolution parameter for modularity. Defaults to 1.0.
weight_prop (str | None): the edge property to use for weights (has to be float)
tol (None | float): the floating point tolerance for deciding if improvements are significant (default: 1e-8)
Expand All @@ -644,11 +648,11 @@ def fruchterman_reingold(
Arguments:
graph (GraphView): the graph view
iterations (int | None): the number of iterations to run (default: 100)
scale (float | None): the scale to apply (default: 1.0)
node_start_size (float | None): the start node size to assign random positions (default: 1.0)
cooloff_factor (float | None): the cool off factor for the algorithm (default: 0.95)
dt (float | None): the time increment between iterations (default: 0.1)
iterations (int | None): the number of iterations to run. Defaults to 100.
scale (float | None): the scale to apply. Defaults to 1.0.
node_start_size (float | None): the start node size to assign random positions. Defaults to 1.0.
cooloff_factor (float | None): the cool off factor for the algorithm. Defaults to 0.95.
dt (float | None): the time increment between iterations. Defaults to 0.1.
Returns:
NodeLayout: A mapping from nodes to their [x, y] positions
Expand All @@ -666,11 +670,11 @@ def cohesive_fruchterman_reingold(
Cohesive version of `fruchterman_reingold` that adds virtual edges between isolated nodes
Arguments:
graph (GraphView): A reference to the graph
iter_count (int): The number of iterations to run
scale (float): Global scaling factor to control the overall spread of the graph
node_start_size (float): Initial size or movement range for nodes
cooloff_factor (float): Factor to reduce node movement in later iterations, helping stabilize the layout
dt (float): Time step or movement factor in each iteration
iter_count (int): The number of iterations to run. Defaults to 100.
scale (float): Global scaling factor to control the overall spread of the graph. Defaults to 1.0.
node_start_size (float): Initial size or movement range for nodes. Defaults to 1.0.
cooloff_factor (float): Factor to reduce node movement in later iterations, helping stabilize the layout. Defaults to 0.95.
dt (float): Time step or movement factor in each iteration. Defaults to 0.1.
Returns:
NodeLayout: A mapping from nodes to their [x, y] positions
Expand Down Expand Up @@ -705,13 +709,15 @@ def max_weight_matching(
graph (GraphView): The graph to compute the maximum weight matching for
weight_prop (str, optional): The property on the edge to use for the weight. If not
provided,
max_cardinality (bool): If set to true compute the maximum-cardinality matching
with maximum weight among all maximum-cardinality matchings. Defaults to True.
verify_optimum_flag (bool): If true prior to returning an additional routine
max_cardinality (bool): If set to True, consider only maximum-cardinality matchings. Defaults to True.
If True, finds the maximum-cardinality matching with maximum weight among all maximum-cardinality matchings,
otherwise, finds the maximum weight matching irrespective of cardinality.
verify_optimum_flag (bool): Whether the optimum should be verified. Defaults to False.
If true prior to returning, an additional routine
to verify the optimal solution was found will be run after computing
the maximum weight matching. If it's true and the found matching is not
an optimal solution this function will panic. This option should
normally be only set true during testing. Defaults to False.
normally be only set true during testing.
Returns:
Matching: The matching
Expand Down Expand Up @@ -794,10 +800,30 @@ class Infected(object):
"""Return repr(self)."""

@property
def active(self): ...
def active(self) -> int:
"""
The timestamp at which the infected node started spreading the infection
Returns:
int:
"""

@property
def infected(self): ...
def infected(self) -> int:
"""
The timestamp at which the node was infected
Returns:
int:
"""

@property
def recovered(self): ...
def recovered(self) -> int:
"""
The timestamp at which the infected node stopped spreading the infection
Returns:
int:
"""

def connected_components(graph): ...
14 changes: 13 additions & 1 deletion raphtory/src/python/algorithm/epidemics.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -25,23 +25,35 @@ impl Repr for Infected {
}
}

#[pyclass(name = "Infected", frozen)]
#[pyclass(name = "Infected", frozen, module = "raphtory.algorithms")]
pub struct PyInfected {
inner: Infected,
}

#[pymethods]
impl PyInfected {
/// The timestamp at which the node was infected
///
/// Returns:
/// int:
#[getter]
fn infected(&self) -> i64 {
self.inner.infected
}

/// The timestamp at which the infected node started spreading the infection
///
/// Returns:
/// int:
#[getter]
fn active(&self) -> i64 {
self.inner.active
}

/// The timestamp at which the infected node stopped spreading the infection
///
/// Returns:
/// int:
#[getter]
fn recovered(&self) -> i64 {
self.inner.recovered
Expand Down
Loading

0 comments on commit 9998f5c

Please sign in to comment.