pylibcugraph.homogeneous_biased_neighbor_sample#

pylibcugraph.homogeneous_biased_neighbor_sample( ResourceHandle resource_handle, _GPUGraph input_graph, start_vertex_list, 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=False, return_hops=False, renumber=False, retain_seeds=False, compression='COO', compress_per_hop=False, random_state=None, )[source]#

Performs biased 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. 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.

edge_biases: not supported.

start_vertex_list: device array type

Device array containing the list of starting vertices for sampling.

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: tuple of 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 when supported. Defaults to False.

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)

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)
>>> 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,
...     store_transposed=True, renumber=False, do_expensive_check=False)
>>> sampling_results = pylibcugraph.homogeneous_biased_neighbor_sample(
...         resource_handle, G, start_vertices, None, h_fan_out, False, True)
>>> sampling_results
{'sources': array([2, 2, 5, 5], dtype=int32),
 'destinations': array([1, 3, 3, 4], dtype=int32),
 'indices': array([3.1, 4.1, 7.2, 3.2], dtype=float32)}

>>> start_vertices = cupy.asarray([2, 5, 1]).astype(numpy.int32)
>>> starting_vertex_label_offsets = cupy.asarray([0, 2, 3])
>>> sampling_results = pylibcugraph.homogeneous_biased_neighbor_sample(
...         resource_handle, G, start_vertices, starting_vertex_label_offsets,
...         h_fan_out, False, True)
>>> sampling_results
{'majors': array([2, 2, 5, 5, 1, 1], dtype=int32),
 'minors': array([1, 3, 3, 4, 3, 4], dtype=int32),
 'weight': array([3.1, 4.1, 7.2, 3.2, 2.1, 1.1], dtype=float32)}