{ "__type": "IngestedDoc", "__tag": 4010, "_content": { "Notes": { "__type": "Section", "__tag": 4015, "children": [ { "__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": "CrossRef", "__tag": 4002, "value": "fcluster", "reference": { "__type": "RefInfo", "__tag": 4000, "module": null, "version": null, "kind": "local", "path": "fcluster" }, "kind": "local" }, { "__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 ⚠️ computes graph 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": "fcluster", "annotation": "ndarray", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "An array of length " }, { "__type": "InlineCode", "__tag": 4051, "value": "n" }, { "__type": "Text", "__tag": 4046, "value": ". " }, { "__type": "InlineCode", "__tag": 4051, "value": "T[i]" }, { "__type": "Text", "__tag": 4046, "value": " is the flat cluster number to which original observation " }, { "__type": "InlineCode", "__tag": 4051, "value": "i" }, { "__type": "Text", "__tag": 4046, "value": " belongs." } ] } ] } ] } ], "title": [], "level": 0, "target": null }, "Summary": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Form flat clusters from the hierarchical clustering defined by the given linkage matrix." } ] } ], "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 with the matrix returned by the " }, { "__type": "InlineRole", "__tag": 4003, "value": "linkage", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " function." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "t", "annotation": "scalar", "desc": [ { "__type": "DefList", "__tag": 4033, "children": [ { "__type": "DefListItem", "__tag": 4037, "dt": { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "For criteria 'inconsistent', 'distance' or 'monocrit'," } ] }, "dd": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "this is the threshold to apply when forming flat clusters." } ] } ] }, { "__type": "DefListItem", "__tag": 4037, "dt": { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "For 'maxclust' or 'maxclust_monocrit' criteria," } ] }, "dd": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "this would be max number of clusters requested." } ] } ] } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "criterion", "annotation": "str, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The criterion to use in forming flat clusters. This can be any of the following values:" } ] }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "DefList", "__tag": 4033, "children": [ { "__type": "DefListItem", "__tag": 4037, "dt": { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "inconsistent" }, { "__type": "Text", "__tag": 4046, "value": " :" } ] }, "dd": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If a cluster node and all its descendants have an inconsistent value less than or equal to " }, { "__type": "ParamRef", "__tag": 4071, "name": "t" }, { "__type": "Text", "__tag": 4046, "value": ", then all its leaf descendants belong to the same flat cluster. When no non-singleton cluster meets this criterion, every node is assigned to its own cluster. (Default)" } ] } ] }, { "__type": "DefListItem", "__tag": 4037, "dt": { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "distance" }, { "__type": "Text", "__tag": 4046, "value": " :" } ] }, "dd": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Forms flat clusters so that the original observations in each flat cluster have no greater a cophenetic distance than " }, { "__type": "ParamRef", "__tag": 4071, "name": "t" }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] }, { "__type": "DefListItem", "__tag": 4037, "dt": { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "maxclust" }, { "__type": "Text", "__tag": 4046, "value": " :" } ] }, "dd": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Finds a minimum threshold " }, { "__type": "InlineCode", "__tag": 4051, "value": "r" }, { "__type": "Text", "__tag": 4046, "value": " so that the cophenetic distance between any two original observations in the same flat cluster is no more than " }, { "__type": "InlineCode", "__tag": 4051, "value": "r" }, { "__type": "Text", "__tag": 4046, "value": " and no more than " }, { "__type": "ParamRef", "__tag": 4071, "name": "t" }, { "__type": "Text", "__tag": 4046, "value": " flat clusters are formed." } ] } ] }, { "__type": "DefListItem", "__tag": 4037, "dt": { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "monocrit" }, { "__type": "Text", "__tag": 4046, "value": " :" } ] }, "dd": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Forms a flat cluster from a cluster node c with index i when " }, { "__type": "InlineCode", "__tag": 4051, "value": "monocrit[j] <= t" }, { "__type": "Text", "__tag": 4046, "value": "." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "For example, to threshold on the maximum mean distance as computed in the inconsistency matrix R with a threshold of 0.8 do " } ] }, { "__type": "Code", "__tag": 4050, "value": "MR = maxRstat(Z, R, 3)\nfcluster(Z, t=0.8, criterion='monocrit', monocrit=MR)", "execution_status": null } ] }, { "__type": "DefListItem", "__tag": 4037, "dt": { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "maxclust_monocrit" }, { "__type": "Text", "__tag": 4046, "value": " :" } ] }, "dd": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Forms a flat cluster from a non-singleton cluster node " }, { "__type": "InlineCode", "__tag": 4051, "value": "c" }, { "__type": "Text", "__tag": 4046, "value": " when " }, { "__type": "InlineCode", "__tag": 4051, "value": "monocrit[i] <= r" }, { "__type": "Text", "__tag": 4046, "value": " for all cluster indices " }, { "__type": "InlineCode", "__tag": 4051, "value": "i" }, { "__type": "Text", "__tag": 4046, "value": " below and including " }, { "__type": "InlineCode", "__tag": 4051, "value": "c" }, { "__type": "Text", "__tag": 4046, "value": ". " }, { "__type": "InlineCode", "__tag": 4051, "value": "r" }, { "__type": "Text", "__tag": 4046, "value": " is minimized such that no more than " }, { "__type": "InlineCode", "__tag": 4051, "value": "t" }, { "__type": "Text", "__tag": 4046, "value": " flat clusters are formed. monocrit must be monotonic. For example, to minimize the threshold t on maximum inconsistency values so that no more than 3 flat clusters are formed, do " } ] }, { "__type": "Code", "__tag": 4050, "value": "MI = maxinconsts(Z, R)\nfcluster(Z, t=3, criterion='maxclust_monocrit', monocrit=MI)", "execution_status": null } ] } ] } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "depth", "annotation": "int, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The maximum depth to perform the inconsistency calculation. It has no meaning for the other criteria. Default is 2." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "R", "annotation": "ndarray, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The inconsistency matrix to use for the " }, { "__type": "InlineCode", "__tag": 4051, "value": "'inconsistent'" }, { "__type": "Text", "__tag": 4046, "value": " criterion. This matrix is computed if not provided." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "monocrit", "annotation": "ndarray, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "An array of length n-1. " }, { "__type": "InlineRole", "__tag": 4003, "value": "monocrit[i]", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " is the statistics upon which non-singleton i is thresholded. The monocrit vector must be monotonic, i.e., given a node c with index i, for all node indices j corresponding to nodes below c, " }, { "__type": "InlineCode", "__tag": 4051, "value": "monocrit[i] >= monocrit[j]" }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] } ] } ], "title": [], "level": 0, "target": null }, "Extended Summary": { "__type": "Section", "__tag": 4015, "children": [], "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": 2515, "item_type": "function", "aliases": [ "scipy.cluster.hierarchy.fcluster" ], "example_section_data": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Code", "__tag": 4050, "value": "from scipy.cluster.hierarchy import ward, fcluster\nfrom scipy.spatial.distance import pdist\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nAll cluster linkage methods - e.g., `scipy.cluster.hierarchy.ward`\ngenerate a linkage matrix ``Z`` as their output:\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": "Text", "__tag": 4046, "value": "\n" }, { "__type": "Code", "__tag": 4050, "value": "Z\n", "execution_status": "failure" }, { "__type": "Text", "__tag": 4046, "value": "\nThis matrix represents a dendrogram, where the first and second elements\nare the two clusters merged at each step, the third element is the\ndistance between these clusters, and the fourth element is the size of\nthe new cluster - the number of original data points included.\n\n`scipy.cluster.hierarchy.fcluster` can be used to flatten the\ndendrogram, obtaining as a result an assignation of the original data\npoints to single clusters.\n\nThis assignation mostly depends on a distance threshold ``t`` - the maximum\ninter-cluster distance allowed:\n\n" }, { "__type": "Code", "__tag": 4050, "value": "fcluster(Z, t=0.9, criterion='distance')\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\n" }, { "__type": "Code", "__tag": 4050, "value": "fcluster(Z, t=1.1, criterion='distance')\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\n" }, { "__type": "Code", "__tag": 4050, "value": "fcluster(Z, t=3, criterion='distance')\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\n" }, { "__type": "Code", "__tag": 4050, "value": "fcluster(Z, t=9, criterion='distance')\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nIn the first case, the threshold ``t`` is too small to allow any two\nsamples in the data to form a cluster, so 12 different clusters are\nreturned.\n\nIn the second case, the threshold is large enough to allow the first\n4 points to be merged with their nearest neighbors. So, here, only 8\nclusters are returned.\n\nThe third case, with a much higher threshold, allows for up to 8 data\npoints to be connected - so 4 clusters are returned here.\n\nLastly, the threshold of the fourth case is large enough to allow for\nall data points to be merged together - so a single cluster is returned." } ], "title": [], "level": 0, "target": null }, "see_also": [ { "__type": "SeeAlsoItem", "__tag": 4028, "name": { "__type": "CrossRef", "__tag": 4002, "value": "linkage", "reference": { "__type": "RefInfo", "__tag": 4000, "module": "current-module", "version": "current-version", "kind": "to-resolve", "path": "linkage" }, "kind": "module" }, "descriptions": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "for information about hierarchical clustering methods work." } ] } ], "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 } }, { "__type": "SigParam", "__tag": 4030, "name": "criterion", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "inconsistent" }, { "__type": "SigParam", "__tag": 4030, "name": "depth", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "2" }, { "__type": "SigParam", "__tag": 4030, "name": "R", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "None" }, { "__type": "SigParam", "__tag": 4030, "name": "monocrit", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "None" } ], "return_annotation": { "__type": "Empty", "__tag": 4031 }, "target_name": "fcluster" }, "references": null, "qa": "scipy.cluster.hierarchy:fcluster", "arbitrary": [], "local_refs": [ "R", "Z", "criterion", "depth", "fcluster", "monocrit", "t" ] }