{ "__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": " If the input is a lazy Array (e.g. Dask or JAX), the return value may be a 0-dimensional bool Array. When warning=True or throw=True, calling this function materializes the array." } ] }, { "__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": "is_valid_linkage", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.cluster.hierarchy:is_valid_linkage" }, "kind": "module" }, { "__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 ⚠️ see notes ⚠️ see notes \nDask ⚠️ see notes 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": "b", "annotation": "bool", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "True if the inconsistency matrix is valid; False otherwise." } ] } ] } ] } ], "title": [], "level": 0, "target": null }, "Summary": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Check the validity of a 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": "array_like", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Linkage matrix." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "warning", "annotation": "bool, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "When True, issues a Python warning if the linkage matrix passed is invalid." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "throw", "annotation": "bool, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "When True, throws a Python exception if the linkage matrix passed is invalid." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "name", "annotation": "str, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "This string refers to the variable name of the invalid linkage matrix." } ] } ] } ] } ], "title": [], "level": 0, "target": null }, "Extended Summary": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "A linkage matrix is valid if it is a 2-D array (type double) with " }, { "__type": "InlineMath", "__tag": 4057, "value": "n" }, { "__type": "Text", "__tag": 4046, "value": " rows and 4 columns. The first two columns must contain indices between 0 and " }, { "__type": "InlineMath", "__tag": 4057, "value": "2n-1" }, { "__type": "Text", "__tag": 4046, "value": ". For a given row " }, { "__type": "InlineCode", "__tag": 4051, "value": "i" }, { "__type": "Text", "__tag": 4046, "value": ", the following two expressions have to hold:" } ] }, { "__type": "Math", "__tag": 4058, "value": "0 \\leq \\mathtt{Z[i,0]} \\leq i+n-1\n0 \\leq Z[i,1] \\leq i+n-1" }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "I.e., a cluster cannot join another cluster unless the cluster being joined has been generated." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The fourth column of " }, { "__type": "ParamRef", "__tag": 4071, "name": "Z" }, { "__type": "Text", "__tag": 4046, "value": " represents the number of original observations in a cluster, so a valid " }, { "__type": "InlineCode", "__tag": 4051, "value": "Z[i, 3]" }, { "__type": "Text", "__tag": 4046, "value": " value may not exceed the number of original observations." } ] } ], "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": 2220, "item_type": "function", "aliases": [ "scipy.cluster.hierarchy.is_valid_linkage" ], "example_section_data": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Code", "__tag": 4050, "value": "from scipy.cluster.hierarchy import ward, is_valid_linkage\nfrom scipy.spatial.distance import pdist\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nAll linkage matrices generated by the clustering methods in this module\nwill be valid (i.e., they will have the appropriate dimensions and the two\nrequired expressions will hold for all the rows).\n\nWe can check this using `scipy.cluster.hierarchy.is_valid_linkage`:\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": "Code", "__tag": 4050, "value": "is_valid_linkage(Z)\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nHowever, if we create a linkage matrix in a wrong way - or if we modify\na valid one in a way that any of the required expressions don't hold\nanymore, then the check will fail:\n\n" }, { "__type": "Code", "__tag": 4050, "value": "Z[3][1] = 20 # the cluster number 20 is not defined at this point\nis_valid_linkage(Z)\n", "execution_status": "success" } ], "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 a description of what a linkage matrix is." } ] } ], "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": "warning", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "False" }, { "__type": "SigParam", "__tag": 4030, "name": "throw", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "False" }, { "__type": "SigParam", "__tag": 4030, "name": "name", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "None" } ], "return_annotation": { "__type": "Empty", "__tag": 4031 }, "target_name": "is_valid_linkage" }, "references": null, "qa": "scipy.cluster.hierarchy:is_valid_linkage", "arbitrary": [], "local_refs": [ "Z", "b", "name", "throw", "warning" ] }