pylibcugraph.homogeneous_biased_temporal_neighbor_sample

pylibcugraph.homogeneous_biased_temporal_neighbor_sample(

ResourceHandle resource_handle,

_GPUGraph input_graph,

temporal_property_name,

start_vertex_list,

starting_vertex_start_times,

starting_vertex_label_offsets,

h_fan_out,

*,

bool_t with_replacement,

bool_t do_expensive_check,

prior_sources_behavior=None,

deduplicate_sources=False,

disjoint_sampling=True,

return_hops=False,

renumber=False,

retain_seeds=False,

compression='COO',

compress_per_hop=False,

random_state=None,

temporal_sampling_comparison='strictly_increasing',

)

Performs biased temporal neighborhood sampling, which samples nodes from a graph based on the current node’s neighbors, with a corresponding fan_out value at each hop. The edges are sampled with biases.

Temporal sampling considers the time associated with the edges. For example, if we start at vertex v1 and sample an edge that takes us to vertex v2 at time t1, when we sample in the next hop from vertex v2, we want to consider only edges that occur after time t1.

Homogeneous neighborhood sampling translates to 1 edge type.

Parameters:

resource_handle: ResourceHandle

Handle to the underlying device and host resources needed for referencing data and running algorithms.

input_graphSGGraph or MGGraph

The input graph, for either Single or Multi-GPU operations.

temporal_property_namechar

Name associated with the edge property in the graph that should be used as the time. Currently unused.

edge_biases: not supported.

start_vertex_list: device array type

Device array containing the list of starting vertices for sampling.

starting_vertex_start_times: device array type (Optional)

Optional per-seed lower bound of the time window. Edge times must be >= this value when provided. Must have length equal to len(start_vertex_list) and a dtype compatible with the graph’s temporal property.

For increasing walks this is also the hop-0 frontier time (sampling begins here and walks forward). For decreasing walks the frontier originates at the (currently unbound) upper end of the window instead, and this array remains only a floor on eligible edge times, yielding a window [start, +inf) whose frontier begins at +inf.

starting_vertex_label_offsets: device array type (Optional)

Offsets of each label within the start vertex list. Expanding ‘starting_vertex_label_offsets’ must lead to an array of len(start_vertex_list)

h_fan_out: numpy array type

Device array containing the branching out (fan-out) degrees per starting vertex for each hop level

The sampling method can use different fan_out values for each edge type which is not the case for homogeneous neighborhood sampling (both biased and uniform).

with_replacement: bool

If true, sampling procedure is done with replacement (the same vertex can be selected multiple times in the same step).

do_expensive_check: bool

If True, performs more extensive tests on the inputs to ensure validitity, at the expense of increased run time.

prior_sources_behavior: str (Optional)

Options are “carryover”, and “exclude”. Default will leave the source list as-is. Carryover will carry over sources from previous hops to the current hop. Exclude will exclude sources from previous hops from reappearing as sources in future hops.

deduplicate_sources: bool (Optional)

If True, will deduplicate the source list before sampling. Defaults to False.

renumber: bool (Optional)

If True, will renumber the sources and destinations on a per-batch basis and return the renumber map and batch offsets in additional to the standard returns.

retain_seeds: bool (Optional)

If True, will retain the original seeds (original source vertices) in the output even if they do not have outgoing neighbors. Defaults to False.

compression: str (Optional)

Options: COO (default), CSR, CSC, DCSR, DCSR Sets the compression format for the returned samples.

compress_per_hop: bool (Optional)

If False (default), will create a compressed edgelist for the entire batch. If True, will create a separate compressed edgelist per hop within a batch.

disjoint_sampling: bool (Optional)

If True, enables disjoint sampling between seeds per hop. Defaults to True. Temporal sampling requires disjoint sampling, so passing False raises an error.

random_state: int (Optional)

Random state to use when generating samples. Optional argument, defaults to a hash of process id, time, and hostname. (See pylibcugraph.random.CuGraphRandomState)

temporal_sampling_comparison: str (Optional)

Options: ‘strictly_increasing’ (default), ‘strictly_decreasing’, ‘monotonically_increasing’, ‘monotonically_decreasing’, ‘last’ Sets the comparison operator for temporal sampling.

Returns:

A tuple of device arrays, where the first and second items in the tuple

are device arrays containing the starting and ending vertices of each

walk respectively, the third item in the tuple is a device array

containing the start labels, and the fourth item in the tuple is a device

array containing the indices for reconstructing paths.

If renumber was set to True, then the fifth item in the tuple is a device

array containing the renumber map, and the sixth item in the tuple is a

device array containing the renumber map offsets (which delineate where

the renumber map for each batch starts).

Examples

>>> import pylibcugraph, cupy, numpy
>>> srcs = cupy.asarray([0, 1, 1, 2, 2, 2, 3, 4, 1, 3, 4, 0, 1, 3, 5, 5], dtype=numpy.int32)
>>> dsts = cupy.asarray([1, 3, 4, 0, 1, 3, 5, 5, 0, 1, 1, 2, 2, 2, 3, 4], dtype=numpy.int32)
>>> weights = cupy.asarray([0.1, 2.1, 1.1, 5.1, 3.1, 4.1, 7.2, 3.2, 0.1, 2.1, 1.1, 5.1, 3.1,
...                         4.1, 7.2, 3.2], dtype=numpy.float32)
>>> edge_start_times = cupy.asarray([0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15],
...                                  dtype=numpy.int32)
>>> edge_end_times= cupy.asarray([1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16],
...                                  dtype=numpy.int32)
>>> start_vertices = cupy.asarray([2, 5]).astype(numpy.int32)
>>> h_fan_out = numpy.array([2]).astype(numpy.int32)
>>> resource_handle = pylibcugraph.ResourceHandle()
>>> graph_props = pylibcugraph.GraphProperties(
...     is_symmetric=False, is_multigraph=False)
>>> G = pylibcugraph.SGGraph(
...     resource_handle, graph_props, srcs, dsts, weight_array=weights,
...     edge_start_time_array=edge_start_times, edge_end_time_array=edge_end_times,
...     store_transposed=True, renumber=False, do_expensive_check=False)
>>> sampling_results = pylibcugraph.homogeneous_biased_temporal_neighbor_sample(
...         resource_handle, G, None, start_vertices, None, None, h_fan_out, False, True)
>>> sampling_results
{'majors': array([2, 2, 5, 5], dtype=int32),
 'minors': array([0, 1, 3, 4], dtype=int32),
 'weight': array([5.1, 3.1, 7.2, 3.2], dtype=float32),
 'edge_start_time': array([11, 9, 6, 7], dtype=int32),
 'edge_end_time': array([12, 10, 7, 8], dtype=int32)}

>>> start_vertices = cupy.asarray([2, 5, 1]).astype(numpy.int32)
>>> starting_vertex_label_offsets = cupy.asarray([0, 2, 3])
>>> sampling_results = pylibcugraph.homogeneous_biased_temporal_neighbor_sample(
...         resource_handle, G, None, start_vertices, None, starting_vertex_label_offsets,
...         h_fan_out, False, True)
>>> sampling_results
{'majors': array([2, 2, 5, 5, 1, 1], dtype=int32),
 'minors': array([0, 3, 3, 4, 2, 3], dtype=int32),
 'weight': array([5.1, 4.1, 7.2, 3.2, 3.1, 2.1], dtype=float32),
 'edge_start_time': array([11, 10, 6, 7, 8, 3], dtype=int32),
 'edge_end_time': array([12, 11, 7, 8, 9, 4], dtype=int32),
 'batch_id': array([0, 0, 0, 0, 1, 1], dtype=int32),
 'label_hop_offsets': array([0, 4, 6])}