[GraphBolt] Update docstring of `itemset.py`. (#7303)

Co-authored-by: Ubuntu <ubuntu@ip-172-31-0-133.us-west-2.compute.internal>

python/dgl/graphbolt/itemset.py

@@ -33,9 +33,8 @@ class ItemSet:
     names: Union[str, Tuple[str]], optional
         The names of the items. If it is a tuple, each name corresponds to an
         item in the tuple. The naming is arbitrary, but in general practice,
-        the names should be chosen from ['seed_nodes', 'node_pairs', 'labels',
-        'seeds', 'negative_srcs', 'negative_dsts'] to align with the attributes
-        of class `dgl.graphbolt.MiniBatch`.
+        the names should be chosen from ['labels', 'seeds', 'indexes'] to align
+        with the attributes of class `dgl.graphbolt.MiniBatch`.
 
     Examples
     --------
@@ -45,19 +44,19 @@ class ItemSet:
     1. Integer: number of nodes.
 
     >>> num = 10
-    >>> item_set = gb.ItemSet(num, names="seed_nodes")
+    >>> item_set = gb.ItemSet(num, names="seeds")
     >>> list(item_set)
     [tensor(0), tensor(1), tensor(2), tensor(3), tensor(4), tensor(5),
      tensor(6), tensor(7), tensor(8), tensor(9)]
     >>> item_set[:]
     tensor([0, 1, 2, 3, 4, 5, 6, 7, 8, 9])
     >>> item_set.names
-    ('seed_nodes',)
+    ('seeds',)
 
     2. Torch scalar: number of nodes. Customizable dtype compared to Integer.
 
     >>> num = torch.tensor(10, dtype=torch.int32)
-    >>> item_set = gb.ItemSet(num, names="seed_nodes")
+    >>> item_set = gb.ItemSet(num, names="seeds")
     >>> list(item_set)
     [tensor(0, dtype=torch.int32), tensor(1, dtype=torch.int32),
      tensor(2, dtype=torch.int32), tensor(3, dtype=torch.int32),
@@ -67,51 +66,50 @@ class ItemSet:
     >>> item_set[:]
     tensor([0, 1, 2, 3, 4, 5, 6, 7, 8, 9], dtype=torch.int32)
     >>> item_set.names
-    ('seed_nodes',)
+    ('seeds',)
 
     3. Single iterable: seed nodes.
 
     >>> node_ids = torch.arange(0, 5)
-    >>> item_set = gb.ItemSet(node_ids, names="seed_nodes")
+    >>> item_set = gb.ItemSet(node_ids, names="seeds")
     >>> list(item_set)
     [tensor(0), tensor(1), tensor(2), tensor(3), tensor(4)]
     >>> item_set[:]
     tensor([0, 1, 2, 3, 4])
     >>> item_set.names
-    ('seed_nodes',)
+    ('seeds',)
 
     4. Tuple of iterables with same shape: seed nodes and labels.
 
     >>> node_ids = torch.arange(0, 5)
     >>> labels = torch.arange(5, 10)
     >>> item_set = gb.ItemSet(
-    ...     (node_ids, labels), names=("seed_nodes", "labels"))
+    ...     (node_ids, labels), names=("seeds", "labels"))
     >>> list(item_set)
     [(tensor(0), tensor(5)), (tensor(1), tensor(6)), (tensor(2), tensor(7)),
      (tensor(3), tensor(8)), (tensor(4), tensor(9))]
     >>> item_set[:]
     (tensor([0, 1, 2, 3, 4]), tensor([5, 6, 7, 8, 9]))
     >>> item_set.names
-    ('seed_nodes', 'labels')
+    ('seeds', 'labels')
 
-    5. Tuple of iterables with different shape: node pairs and negative dsts.
+    5. Tuple of iterables with different shape: seeds and labels.
 
-    >>> node_pairs = torch.arange(0, 10).reshape(-1, 2)
-    >>> neg_dsts = torch.arange(10, 25).reshape(-1, 3)
+    >>> seeds = torch.arange(0, 10).reshape(-1, 2)
+    >>> labels = torch.tensor([1, 1, 0, 0, 0])
     >>> item_set = gb.ItemSet(
-    ...     (node_pairs, neg_dsts), names=("node_pairs", "negative_dsts"))
+    ...     (seeds, labels), names=("seeds", "lables"))
     >>> list(item_set)
-    [(tensor([0, 1]), tensor([10, 11, 12])),
-     (tensor([2, 3]), tensor([13, 14, 15])),
-     (tensor([4, 5]), tensor([16, 17, 18])),
-     (tensor([6, 7]), tensor([19, 20, 21])),
-     (tensor([8, 9]), tensor([22, 23, 24]))]
+    [(tensor([0, 1]), tensor([1])),
+     (tensor([2, 3]), tensor([1])),
+     (tensor([4, 5]), tensor([0])),
+     (tensor([6, 7]), tensor([0])),
+     (tensor([8, 9]), tensor([0]))]
     >>> item_set[:]
-    (tensor([[0, 1], [2, 3], [4, 5], [6, 7],[8, 9]]),
-     tensor([[10, 11, 12], [13, 14, 15], [16, 17, 18], [19, 20, 21],
-        [22, 23, 24]]))
+    (tensor([[0, 1], [2, 3], [4, 5], [6, 7], [8, 9]]),
+     tensor([1, 1, 0, 0, 0]))
     >>> item_set.names
-    ('node_pairs', 'negative_dsts')
+    ('seeds', 'labels')
     """
 
     def __init__(
@@ -256,8 +254,8 @@ class ItemSetDict:
     >>> node_ids_user = torch.arange(0, 5)
     >>> node_ids_item = torch.arange(5, 10)
     >>> item_set = gb.ItemSetDict({
-    ...     "user": gb.ItemSet(node_ids_user, names="seed_nodes"),
-    ...     "item": gb.ItemSet(node_ids_item, names="seed_nodes")})
+    ...     "user": gb.ItemSet(node_ids_user, names="seeds"),
+    ...     "item": gb.ItemSet(node_ids_item, names="seeds")})
     >>> list(item_set)
     [{"user": tensor(0)}, {"user": tensor(1)}, {"user": tensor(2)},
      {"user": tensor(3)}, {"user": tensor(4)}, {"item": tensor(5)},
@@ -266,7 +264,7 @@ class ItemSetDict:
     >>> item_set[:]
     {"user": tensor([0, 1, 2, 3, 4]), "item": tensor([5, 6, 7, 8, 9])}
     >>> item_set.names
-    ('seed_nodes',)
+    ('seeds',)
 
     2. Tuple of iterables with same shape: seed nodes and labels.
 
@@ -277,10 +275,10 @@ class ItemSetDict:
     >>> item_set = gb.ItemSetDict({
     ...     "user": gb.ItemSet(
     ...         (node_ids_user, labels_user),
-    ...         names=("seed_nodes", "labels")),
+    ...         names=("seeds", "labels")),
     ...     "item": gb.ItemSet(
     ...         (node_ids_item, labels_item),
-    ...         names=("seed_nodes", "labels"))})
+    ...         names=("seeds", "labels"))})
     >>> list(item_set)
     [{"user": (tensor(0), tensor(0))}, {"user": (tensor(1), tensor(1))},
      {"item": (tensor(2), tensor(2))}, {"item": (tensor(3), tensor(3))},
@@ -289,36 +287,34 @@ class ItemSetDict:
     {"user": (tensor([0, 1]), tensor([0, 1])),
      "item": (tensor([2, 3, 4]), tensor([2, 3, 4]))}
     >>> item_set.names
-    ('seed_nodes', 'labels')
+    ('seeds', 'labels')
 
-    3. Tuple of iterables with different shape: node pairs and negative dsts.
+    3. Tuple of iterables with different shape: seeds and labels.
 
-    >>> node_pairs_like = torch.arange(0, 4).reshape(-1, 2)
-    >>> neg_dsts_like = torch.arange(4, 10).reshape(-1, 3)
-    >>> node_pairs_follow = torch.arange(0, 6).reshape(-1, 2)
-    >>> neg_dsts_follow = torch.arange(6, 15).reshape(-1, 3)
+    >>> seeds_like = torch.arange(0, 4).reshape(-1, 2)
+    >>> labels_like = torch.tensor([1, 0])
+    >>> seeds_follow = torch.arange(0, 6).reshape(-1, 2)
+    >>> labels_follow = torch.tensor([1, 1, 0])
     >>> item_set = gb.ItemSetDict({
     ...     "user:like:item": gb.ItemSet(
-    ...         (node_pairs_like, neg_dsts_like),
-    ...         names=("node_pairs", "negative_dsts")),
+    ...         (seeds_like, labels_like),
+    ...         names=("seeds", "labels")),
     ...     "user:follow:user": gb.ItemSet(
-    ...         (node_pairs_follow, neg_dsts_follow),
-    ...         names=("node_pairs", "negative_dsts"))})
+    ...         (seeds_follow, labels_follow),
+    ...         names=("seeds", "labels"))})
     >>> list(item_set)
-    [{"user:like:item": (tensor([0, 1]), tensor([4, 5, 6]))},
-     {"user:like:item": (tensor([2, 3]), tensor([7, 8, 9]))},
-     {"user:follow:user": (tensor([0, 1]), tensor([ 6,  7,  8,  9, 10, 11]))},
-     {"user:follow:user": (tensor([2, 3]), tensor([12, 13, 14, 15, 16, 17]))},
-     {"user:follow:user": (tensor([4, 5]), tensor([18, 19, 20, 21, 22, 23]))}]
+    [{'user:like:item': (tensor([0, 1]), tensor(1))},
+     {'user:like:item': (tensor([2, 3]), tensor(0))},
+     {'user:follow:user': (tensor([0, 1]), tensor(1))},
+     {'user:follow:user': (tensor([2, 3]), tensor(1))},
+     {'user:follow:user': (tensor([4, 5]), tensor(0))}]
     >>> item_set[:]
-    {"user:like:item": (tensor([[0, 1], [2, 3]]),
-                        tensor([[4, 5, 6], [7, 8, 9]])),
-     "user:follow:user": (tensor([[0, 1], [2, 3], [4, 5]]),
-                          tensor([[ 6,  7,  8,  9, 10, 11],
-                                  [12, 13, 14, 15, 16, 17],
-                                  [18, 19, 20, 21, 22, 23]]))}
+    {'user:like:item': (tensor([[0, 1], [2, 3]]),
+                        tensor([1, 0])),
+     'user:follow:user': (tensor([[0, 1], [2, 3], [4, 5]]),
+                          tensor([1, 1, 0]))}
     >>> item_set.names
-    ('node_pairs', 'negative_dsts')
+    ('seeds', 'labels')
     """
 
     def __init__(self, itemsets: Dict[str, ItemSet]) -> None: