cugraph.heterogeneous_neighbor_sample

cugraph.heterogeneous_neighbor_sample(G: Graph, start_list: Sequence, starting_vertex_label_offsets: Sequence, fanout_vals: List[int], *, vertex_type_offsets: Sequence = None, num_edge_types: int = 1, with_replacement: bool = True, with_biases: bool = False, random_state: int = None, return_offsets: bool = False, prior_sources_behavior: str = None, deduplicate_sources: bool = False, return_hops: bool = True, renumber: bool = False, retain_seeds: bool = False, compress_per_hop: bool = False, compression: str = 'COO') → Tuple[Series, Series, None | int | Series]

Performs uniform/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 either uniformly . Heterogeneous neighborhood sampling translates to more than 1 edge type.

Parameters:

GcuGraph.Graph

The graph can be either directed or undirected.

start_listlist or cudf.Series

a list of starting vertices for sampling

starting_vertex_label_offsets: list or cudf.Series

Offsets of each label within the start_list. Expanding ‘starting_vertex_label_offsets’ must lead to an array of len(start_list)

fanout_valslist

List of branching out (fan-out) degrees per starting vertex for each hop level. The fanout value at each hop for each edge type is given by the relationship fanout_vals[x*num_edge_types + edge_type_id] where x is the hop_id.

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).

vertex_type_offsets: list or cudf.Series (Optional)

Offsets for each vertex type in the graph.

num_edge_types: int

Number of edge types where a value of 1 translates to homogeneous neighbor sample whereas a value greater than 1 translates to heterogeneous neighbor sample.

with_replacement: bool, optional (default=True)

Flag to specify if the random sampling is done with replacement

with_biases: bool, optional (default=False)

Flag to specify whether the edges should be sampled uniformly or with biases. Only edge weights can be used as biases for now

random_state: int, optional

Random seed to use when making sampling calls.

return_offsets: bool, optional (default=False)

Whether to return the sampling results with batch ids included as one dataframe, or to instead return two dataframes, one with sampling results and one with batch ids and their start offsets.

prior_sources_behavior: str, optional (default=None)

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 (default=False)

Whether to first deduplicate the list of possible sources from the previous destinations before performing next hop.

return_hops: bool, optional (default=True)

Whether to return the sampling results with hop ids corresponding to the hop where the edge appeared. Defaults to True.

renumber: bool, optional (default=False)

Whether to renumber on a per-batch basis. If True, will return the renumber map and renumber map offsets as an additional dataframe.

retain_seeds: bool, optional (default=False)

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

compress_per_hop: bool, optional (default=False)

Whether to compress globally (default), or to produce a separate compressed edgelist per hop.

compression: str, optional (default=COO)

Sets the compression type for the output minibatches. Valid options are COO (default), CSR, CSC, DCSR, and DCSC.

Returns:

resultcudf.DataFrame or Tuple[cudf.DataFrame, cudf.DataFrame]

GPU data frame containing multiple cudf.Series

If return_offsets=False:

df[‘majors’]: cudf.Series

Contains the source vertices from the sampling result

df[‘minors’]: cudf.Series

Contains the destination vertices from the sampling result

df[‘weight’]: cudf.Series # if provided

Contains the edge weights from the sampling result

df[‘edge_id’]: cudf.Series # if provided

Contains the edge ids from the sampling result

df[‘edge_type’]: cudf.Series # if provided

Contains the edge types from the sampling result

df[‘batch_id’]: cudf.Series

Contains the batch ids from the sampling result

df[‘hop_id’]: cudf.Series

Contains the hop ids from the sampling result

If renumber=True:

(adds the following dataframe) renumber_df[‘renumber_map’]: cudf.Series

Contains the renumber maps for each batch

renumber_df[‘batch_id’]: cudf.Series

Contains the batch ids for the renumber maps

If return_offsets=True:

df[‘majors’]: cudf.Series

Contains the source vertices from the sampling result

df[‘minors’]: cudf.Series

Contains the destination vertices from the sampling result

df[‘weight’]: cudf.Series # if provided

Contains the edge weights from the sampling result

df[‘edge_id’]: cudf.Series # if provided

Contains the edge ids from the sampling result

df[‘edge_type’]: cudf.Series # if provided

Contains the edge types from the sampling result

df[‘batch_id’]: cudf.Series

Contains the batch ids from the sampling result

df[‘hop_id’]: cudf.Series

Contains the hop ids from the sampling result

offsets_df[‘batch_id’]: cudf.Series

Contains the batch ids from the sampling result

offsets_df[‘offsets’]: cudf.Series

Contains the offsets of each batch in the sampling result

If renumber=True:

(adds the following dataframe) renumber_df[‘renumber_map’]: cudf.Series

Contains the renumber maps for each batch

renumber_df[‘batch_id’]: cudf.Series

Contains the batch ids for the renumber maps