{ "__type": "IngestedDoc", "__tag": 4010, "_content": { "Notes": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "Array API support (experimental):" } ] }, { "__type": "Text", "__tag": 4046, "value": " This function returns arrays with data-dependent shape. In JAX, at the moment of writing this makes it impossible to execute it inside " }, { "__type": "InlineRole", "__tag": 4003, "value": "@jax.jit", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": "." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Strong", "__tag": 4048, "children": [ { "__type": "Text", "__tag": 4046, "value": "Array API Standard Support" } ] } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineRole", "__tag": 4003, "value": "leaders", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " has experimental support for Python Array API Standard compatible backends in addition to NumPy. Please consider testing these features by setting an environment variable " }, { "__type": "InlineCode", "__tag": 4051, "value": "SCIPY_ARRAY_API=1" }, { "__type": "Text", "__tag": 4046, "value": " and providing CuPy, PyTorch, JAX, or Dask arrays as array arguments. The following combinations of backend and device (or other capability) are supported." } ] }, { "__type": "Code", "__tag": 4050, "value": "==================== ==================== ====================\nLibrary CPU GPU\n==================== ==================== ====================\nNumPy ✅ n/a \nCuPy n/a ⛔ \nPyTorch ✅ ⛔ \nJAX ⚠️ no JIT ⛔ \nDask ⚠️ merges chunks n/a \n==================== ==================== ====================", "execution_status": null }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "See " }, { "__type": "InlineRole", "__tag": 4003, "value": "dev-arrayapi", "domain": null, "role": "ref", "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " for more information." } ] } ] } ], "title": [], "level": 0, "target": null }, "Warns": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null }, "Raises": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null }, "Yields": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null }, "Methods": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null }, "Returns": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Parameters", "__tag": 4026, "children": [ { "__type": "DocParam", "__tag": 4016, "name": "L", "annotation": "ndarray", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The leader linkage node id's stored as a k-element 1-D array, where " }, { "__type": "InlineCode", "__tag": 4051, "value": "k" }, { "__type": "Text", "__tag": 4046, "value": " is the number of flat clusters found in " }, { "__type": "InlineCode", "__tag": 4051, "value": "T" }, { "__type": "Text", "__tag": 4046, "value": "." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "L[j]=i" }, { "__type": "Text", "__tag": 4046, "value": " is the linkage cluster node id that is the leader of flat cluster with id M[j]. If " }, { "__type": "InlineCode", "__tag": 4051, "value": "i < n" }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "InlineCode", "__tag": 4051, "value": "i" }, { "__type": "Text", "__tag": 4046, "value": " corresponds to an original observation, otherwise it corresponds to a non-singleton cluster." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "M", "annotation": "ndarray", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The leader linkage node id's stored as a k-element 1-D array, where " }, { "__type": "InlineCode", "__tag": 4051, "value": "k" }, { "__type": "Text", "__tag": 4046, "value": " is the number of flat clusters found in " }, { "__type": "InlineCode", "__tag": 4051, "value": "T" }, { "__type": "Text", "__tag": 4046, "value": ". This allows the set of flat cluster ids to be any arbitrary set of " }, { "__type": "InlineCode", "__tag": 4051, "value": "k" }, { "__type": "Text", "__tag": 4046, "value": " integers." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "For example: if " }, { "__type": "InlineCode", "__tag": 4051, "value": "L[3]=2" }, { "__type": "Text", "__tag": 4046, "value": " and " }, { "__type": "InlineCode", "__tag": 4051, "value": "M[3]=8" }, { "__type": "Text", "__tag": 4046, "value": ", the flat cluster with id 8's leader is linkage node 2." } ] } ] } ] } ], "title": [], "level": 0, "target": null }, "Summary": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Return the root nodes in a hierarchical clustering." } ] } ], "title": [], "level": 0, "target": null }, "Receives": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null }, "Warnings": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null }, "Attributes": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null }, "Parameters": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Parameters", "__tag": 4026, "children": [ { "__type": "DocParam", "__tag": 4016, "name": "Z", "annotation": "ndarray", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The hierarchical clustering encoded as a matrix. See " }, { "__type": "InlineRole", "__tag": 4003, "value": "linkage", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " for more information." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "T", "annotation": "ndarray", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The flat cluster assignment vector." } ] } ] } ] } ], "title": [], "level": 0, "target": null }, "Extended Summary": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Returns the root nodes in a hierarchical clustering corresponding to a cut defined by a flat cluster assignment vector " }, { "__type": "InlineCode", "__tag": 4051, "value": "T" }, { "__type": "Text", "__tag": 4046, "value": ". See the " }, { "__type": "InlineCode", "__tag": 4051, "value": "fcluster" }, { "__type": "Text", "__tag": 4046, "value": " function for more information on the format of " }, { "__type": "InlineCode", "__tag": 4051, "value": "T" }, { "__type": "Text", "__tag": 4046, "value": "." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "For each flat cluster " }, { "__type": "InlineMath", "__tag": 4057, "value": "j" }, { "__type": "Text", "__tag": 4046, "value": " of the " }, { "__type": "InlineMath", "__tag": 4057, "value": "k" }, { "__type": "Text", "__tag": 4046, "value": " flat clusters represented in the n-sized flat cluster assignment vector " }, { "__type": "InlineCode", "__tag": 4051, "value": "T" }, { "__type": "Text", "__tag": 4046, "value": ", this function finds the lowest cluster node " }, { "__type": "InlineMath", "__tag": 4057, "value": "i" }, { "__type": "Text", "__tag": 4046, "value": " in the linkage tree Z, such that:" } ] }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "BulletList", "__tag": 4053, "ordered": false, "start": 1, "children": [ { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "leaf descendants belong only to flat cluster j (i.e., " }, { "__type": "InlineCode", "__tag": 4051, "value": "T[p]==j" }, { "__type": "Text", "__tag": 4046, "value": " for all " }, { "__type": "InlineMath", "__tag": 4057, "value": "p" }, { "__type": "Text", "__tag": 4046, "value": " in " }, { "__type": "InlineMath", "__tag": 4057, "value": "S(i)" }, { "__type": "Text", "__tag": 4046, "value": ", where " }, { "__type": "InlineMath", "__tag": 4057, "value": "S(i)" }, { "__type": "Text", "__tag": 4046, "value": " is the set of leaf ids of descendant leaf nodes with cluster node " }, { "__type": "InlineMath", "__tag": 4057, "value": "i" }, { "__type": "Text", "__tag": 4046, "value": ")" } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "there does not exist a leaf that is not a descendant with " }, { "__type": "InlineMath", "__tag": 4057, "value": "i" }, { "__type": "Text", "__tag": 4046, "value": " that also belongs to cluster " }, { "__type": "InlineMath", "__tag": 4057, "value": "j" }, { "__type": "Text", "__tag": 4046, "value": " (i.e., " }, { "__type": "InlineCode", "__tag": 4051, "value": "T[q]!=j" }, { "__type": "Text", "__tag": 4046, "value": " for all " }, { "__type": "InlineMath", "__tag": 4057, "value": "q" }, { "__type": "Text", "__tag": 4046, "value": " not in " }, { "__type": "InlineMath", "__tag": 4057, "value": "S(i)" }, { "__type": "Text", "__tag": 4046, "value": "). If this condition is violated, " }, { "__type": "InlineCode", "__tag": 4051, "value": "T" }, { "__type": "Text", "__tag": 4046, "value": " is not a valid cluster assignment vector, and an exception will be thrown." } ] } ] } ] } ] } ], "title": [], "level": 0, "target": null }, "Other Parameters": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null } }, "_ordered_sections": [ "Summary", "Extended Summary", "Parameters", "Attributes", "Methods", "Returns", "Yields", "Receives", "Other Parameters", "Raises", "Warns", "Warnings", "Notes" ], "item_file": "/scipy/cluster/hierarchy.py", "item_line": 4202, "item_type": "function", "aliases": [ "scipy.cluster.hierarchy.leaders" ], "example_section_data": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Code", "__tag": 4050, "value": "from scipy.cluster.hierarchy import ward, fcluster, leaders\nfrom scipy.spatial.distance import pdist\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nGiven a linkage matrix ``Z`` - obtained after apply a clustering method\nto a dataset ``X`` - and a flat cluster assignment array ``T``:\n\n" }, { "__type": "Code", "__tag": 4050, "value": "X = [[0, 0], [0, 1], [1, 0],\n [0, 4], [0, 3], [1, 4],\n [4, 0], [3, 0], [4, 1],\n [4, 4], [3, 4], [4, 3]]\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\n" }, { "__type": "Code", "__tag": 4050, "value": "Z = ward(pdist(X))\n", "execution_status": "success" }, { "__type": "Code", "__tag": 4050, "value": "Z\n", "execution_status": "failure" }, { "__type": "Text", "__tag": 4046, "value": "\n" }, { "__type": "Code", "__tag": 4050, "value": "T = fcluster(Z, 3, criterion='distance')\nT\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\n`scipy.cluster.hierarchy.leaders` returns the indices of the nodes\nin the dendrogram that are the leaders of each flat cluster:\n\n" }, { "__type": "Code", "__tag": 4050, "value": "L, M = leaders(Z, T)\nL\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\n(remember that indices 0-11 point to the 12 data points in ``X``,\nwhereas indices 12-22 point to the 11 rows of ``Z``)\n\n`scipy.cluster.hierarchy.leaders` also returns the indices of\nthe flat clusters in ``T``:\n\n" }, { "__type": "Code", "__tag": 4050, "value": "M\n", "execution_status": "success" } ], "title": [], "level": 0, "target": null }, "see_also": [ { "__type": "SeeAlsoItem", "__tag": 4028, "name": { "__type": "CrossRef", "__tag": 4002, "value": "fcluster", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.cluster.hierarchy:fcluster" }, "kind": "module" }, "descriptions": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "for the creation of flat cluster assignments." } ] } ], "type": "func" } ], "signature": { "__type": "SignatureNode", "__tag": 4029, "kind": "function", "parameters": [ { "__type": "SigParam", "__tag": 4030, "name": "Z", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": { "__type": "Empty", "__tag": 4031 } }, { "__type": "SigParam", "__tag": 4030, "name": "T", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": { "__type": "Empty", "__tag": 4031 } } ], "return_annotation": { "__type": "Empty", "__tag": 4031 }, "target_name": "leaders" }, "references": null, "qa": "scipy.cluster.hierarchy:leaders", "arbitrary": [], "local_refs": [ "L", "M", "T", "Z" ] }